mpay_v2_webman/doc/standards.md

稳定口径

本文只记录当前项目需要长期保持一致的事实和约束。更细的字段、表结构和接口参数以代码、路由文件和 DDL 为准。

项目边界

• mpay 是 Webman 后端，提供管理后台、商户后台、收银台、ePay 兼容和开放 API。
• admin、mer、cashier 是三套独立 Vue 前端，分别构建和发布。
• 根目录不是业务仓库，只作为多项目工作区。
• 新文档统一维护在 docs/；mpay/doc/ 只作为旧资料归档。

返回格式

• 成功态统一使用 HTTP 200。
• 业务状态由响应体 code 判断，前端拦截器按 code 处理成功、失败和登录过期。
• 控制器负责参数接收和响应包装；服务层和仓库层遇到业务错误直接抛项目异常。
• 金额统一使用“分”作为存储和接口计算单位。
• 模型时间序列化统一输出 Y-m-d H:i:s。

鉴权与签名

• 管理后台走 /adminapi，登录后通过 Authorization 头传管理员 token。
• 商户后台走 /merapi，登录主体是 ma_merchant，登录字段是 merchant_no + password。
• 商户开放 API 凭证在 ma_merchant_api_credential，只用于接口签名，不参与商户后台登录。
• ePay V1/V2 兼容接口的签名规则独立维护，不能反向污染后台登录逻辑。

支付路由

支付选路固定围绕以下数据关系展开：

商户 -> 商户分组 -> 路由绑定 -> 轮询组 -> 轮询组通道编排 -> 支付通道 -> 支付插件配置

路由模式当前为：

• 0：顺序轮询
• 1：权重随机
• 2：默认启用通道

pay_types、transfer_types 存支付方式代码数组；支付插件类由运行时根据插件配置解析。

资金与清算

• 商户资金账户表是 ma_merchant_account。
• 资金流水表是 ma_merchant_account_ledger。
• 平台代收成功后不直接进入商户可提现余额，清算成功后才入账。
• 支付回调、通道通知日志、商户通知任务、通道日统计和清算记录都属于核心链路。

服务层命名

• *Service：对控制器或外部调用方暴露的门面。
• *QueryService：查询、列表、详情和展示拼装。
• *CommandService：新增、修改、删除、状态变更。
• *LifecycleService：支付、退款、清算等状态推进。
• *CallbackService：第三方回调和通知处理。
• *SyncService：配置同步、插件扫描、目录同步。
• *SupportService：有业务语义的共享辅助能力；不要只转发基础工具方法。

文件资产

• 文件资产模型名是 FileRecord，数据表是 ma_file_asset。
• 管理后台文件接口前缀是 /adminapi/file-asset。
• 支持本地存储、远程 URL 导入、阿里云 OSS、腾讯云 COS。
• 上传字段仍使用 type: "upload"；需要走项目定制选择器时，在 props.fileUpload 中声明场景、可见性、存储偏好和回填字段。
• object_key 是站点相对路径或对象键；url 只保存公开可访问地址；私有文件可通过预览/下载接口临时读取。

运行与配置

• 后端 HTTP 进程默认监听 0.0.0.0:8787。
• payment-runtime 进程负责商户通知重试、支付超时扫描和支付中订单主动查单。
• 站点 URL、支付运行时开关、存储配置等长期配置优先进入系统配置，不在业务代码中临时拼接。
• 新增系统配置后执行 php webman system:config-sync 同步默认值。