mpay_v2_webman/doc/project_progress.md

# MPay V2 Development Progress

更新日期：2026-03-13

本文档用于记录当前项目完成度、明显缺口和建议推进顺序，方便后续继续开发时快速接手。

## 1. 当前总体判断

项目已经完成了“支付中台基础骨架 + 后台配置能力 + Epay 协议首条链路”的主体搭建。

更准确地说：

- 数据模型已经比较完整
- 后台配置能力已经具备可用性
- 支付流程主链路已经跑通到“下单并返回拉起参数”
- 真正需要继续补的是“真实渠道闭环、规则执行、异步补偿、通用协议扩展”

## 2. 已完成

### 2.1 基础框架与环境

- Webman 项目骨架已搭建
- MySQL / Redis / JWT / Cache / Event / Redis Queue 依赖已接入
- 管理后台与 API 路由已拆分

### 2.2 管理后台能力

- 验证码登录
- JWT 鉴权中间件
- 管理员信息查询
- 菜单与系统配置读取
- 商户 CRUD
- 商户应用 CRUD
- 支付方式 CRUD
- 支付插件注册 CRUD
- 支付通道 CRUD
- 订单列表 / 详情 / 后台发起退款

### 2.3 核心支付数据结构

已建表并落地：

- 商户
- 商户应用
- 支付方式
- 插件注册
- 支付通道
- 支付订单
- 回调日志
- 商户通知任务
- 回调幂等收件箱

### 2.4 下单主链路

已打通：

- Epay 参数校验
- Epay MD5 验签
- 商户应用识别
- 幂等订单创建
- 通道路由
- 插件实例化
- 插件下单
- 订单回写支付参数
- 返回兼容 Epay 的响应结构

### 2.5 支付状态基础设施

- 订单状态机服务已存在
- 成功 / 失败 / 全额退款关单状态迁移已定义
- 回调日志记录能力已存在
- 回调幂等收件箱已存在
- 商户通知任务创建逻辑已存在

### 2.6 插件体系

已建立统一插件契约：

- `PaymentInterface`
- `PayPluginInterface`
- `BasePayment`

说明后续继续接入新渠道时，整体扩展方式已经明确。

## 3. 部分完成

### 3.1 Epay 兼容是“主路径”，但还不是“全量兼容”

当前已实现：

- `submit.php`
- `mapi.php`
- `api.php?act=order`
- `api.php?act=refund`

但 `doc/epay.md` 中提到的一些能力，如 `query`、`settle`、`orders` 等，代码中暂未实现。

### 3.2 支付宝插件代码较完整，但未在当前数据库启用

现状：

- `AlipayPayment.php` 已实现
- 当前开发库 `ma_pay_plugin` 中只有 `lakala`

这意味着支付宝更多处于“代码已写好、配置未接入”的状态。

### 3.3 回调后通知商户的基础逻辑存在，但补偿闭环还不完整

已完成：

- 创建通知任务
- 发送通知
- 失败重试时间计算

待确认 / 待补齐：

- 当前没有看到明确的任务投递入口
- 也没有看到定时调度 `NotifyMerchantJob` 的配置闭环
- `NotifyMerchantJob` 虽然存在，但尚未形成明确的可运行消费链路

更保守地说，商户通知补偿链路还没有真正闭环。

## 4. 待完成

### 4.1 通用 OpenAPI

当前状态：

- `PayController` 只有骨架
- `create/query/close/refund` 都返回 `501`
- `OpenApiAuthMiddleware` 已存在，但未挂到路由

建议判断：这是下一阶段最适合补完的能力之一。

### 4.2 拉卡拉真实对接

当前状态：

- `LakalaPayment::pay()` 只返回 mock 二维码
- `query/close/refund/notify` 全部未实现

影响：

- 现在只能用于打通订单创建流程
- 还不能进行真实线上支付联调

### 4.3 通道路由规则执行

数据库已设计的字段很多，但运行期并未全部生效：

- `daily_limit` 未校验
- `daily_cnt` 未校验
- `min_amount` 未校验
- `max_amount` 未校验
- `split_ratio` 当前只存储，未看到清算分账逻辑
- 路由策略目前只是“按排序取第一条可用通道”

这块是项目从“能下单”走向“可运营”的关键缺口。

### 4.4 Epay 协议映射细节

当前内部支付方式代码使用：

- `alipay`
- `wechat`

但传统 Epay 常见值通常还有：

- `wxpay`
- `qqpay`

当前代码里没有看到统一别名映射层，说明“协议兼容”仍偏接口形态兼容，而不是完整字段语义兼容。

### 4.5 插件注册与初始化数据同步

代码、SQL、数据库现状存在轻微偏差：

- `database/dev_seed.sql` 里准备了 `alipay` 和 `lakala`
- 当前开发库只看到 `lakala`

建议后续把“代码存在但数据库未启用”的状态统一起来，减少联调歧义。

### 4.6 通道安全与敏感配置

当前通道配置直接存在 `config_json` 中，后续建议补充：

- 敏感字段加密存储
- 后台展示脱敏
- 配置变更审计日志

### 4.7 测试体系

当前仓库里没有看到成体系的：

- 单元测试
- 协议测试
- 插件对接测试
- 回调幂等测试
- 退款回归测试

这会让后续迭代的回归成本越来越高。

## 5. 风险与注意点

### 5.1 当前“多通道”能力更偏配置层，而不是调度层

虽然表结构和后台已经支持多通道，但运行时路由还比较简单，不能完全体现：

- 限额控制
- 金额区间控制
- 通道健康度切换
- 优先级与容灾

### 5.2 退款能力目前偏基础版

当前退款服务已存在，但从实现上看：

- 更适合单次退款 / 全额退款
- 全额退款后直接把订单关闭
- 没有独立退款单模型
- 没有完整的部分退款累计能力

### 5.3 回调成功后的订单与通知一致性要继续加强

当前已经有：

- 幂等收件箱
- 状态机
- 通知任务表

这是很好的基础。

但真正生产级还建议再补：

- 事务边界说明
- 异常重放工具
- 回调人工补单工具
- 通知签名

## 6. 建议优先级

### P0：优先补完，直接影响可用性

1. 实现真实渠道插件，至少先补完一个可联调通道
2. 补完 OpenAPI 主链路
3. 在路由阶段执行金额限制 / 限额 / 笔数规则
4. 打通商户通知任务的实际调度与重试闭环

### P1：补齐可运营能力

1. 增加支付方式别名映射，提升 Epay 兼容度
2. 把 `AlipayPayment` 正式接入插件注册与通道配置
3. 增加后台对通道能力、产品、环境的可视化说明
4. 增加日志检索与问题排查手段

### P2：走向平台化

1. 增加更多协议兼容层
2. 增加清算 / 分账 / 对账
3. 增加风控规则
4. 增加监控、告警、报表

## 7. 建议后续开发方向

### 方向一：先做“一个真实可用通道”

建议优先把某一个通道做成完整闭环：

- 下单
- 回调
- 查单
- 关单
- 退款

这样项目就能从“框架完成”升级为“真实可上线联调”。

### 方向二：补通用 OpenAPI

原因：

- 你已经明确后续可能兼容更多接口
- 当前通用控制器和鉴权中间件已经有雏形
- 补完之后，项目会从“单协议适配器”升级为“统一支付网关”

### 方向三：把通道路由做成真正的策略引擎

建议把下面这些字段从“仅存储”升级为“真实执行”：

- 金额范围
- 单日限额
- 单日限笔
- 通道优先级
- 通道健康状态
- 权重或降级策略

### 方向四：补测试与排障工具

优先建议增加：

- 下单幂等测试
- 回调幂等测试
- 退款状态测试
- 协议字段兼容测试
- 一键重发通知工具

## 8. 推荐继续开发顺序

如果下一次直接继续往下做，我建议按这个顺序推进：

1. 选定一个真实渠道作为首个闭环目标
2. 补完该插件的 `notify/query/refund/close`
3. 接入并验证商户通知补偿链路
4. 在 `ChannelRouterService` 前后补齐通道规则校验
5. 正式实现 `PayController`
6. 抽象协议适配层，准备支持更多接口
7. 增加测试与后台排障能力

## 9. 当前一句话结论

这是一个“骨架已经成型、第一条协议已打通、非常适合继续往生产级推进”的支付中台项目；下一阶段的重点不是重写，而是把已有设计真正补成闭环。