1. 维护代码健壮

2. 更新项目结构文档

doc/standards.md

@@ -0,0 +1,73 @@
+# 稳定口径
+
+本文只记录当前项目需要长期保持一致的事实和约束。更细的字段、表结构和接口参数以代码、路由文件和 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 兼容接口的签名规则独立维护，不能反向污染后台登录逻辑。
+
+## 支付路由
+
+支付选路固定围绕以下数据关系展开：
+
+```text
+商户 -> 商户分组 -> 路由绑定 -> 轮询组 -> 轮询组通道编排 -> 支付通道 -> 支付插件配置
+```
+
+路由模式当前为：
+
+- `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` 同步默认值。