mirror of
https://gitee.com/technical-laohu/mpay_v2_webman.git
synced 2026-05-09 02:14:53 +08:00
74 lines
3.4 KiB
Markdown
74 lines
3.4 KiB
Markdown
# 稳定口径
|
||
|
||
本文只记录当前项目需要长期保持一致的事实和约束。更细的字段、表结构和接口参数以代码、路由文件和 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` 同步默认值。
|