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. 当前一句话结论

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