mirror of
https://gitee.com/technical-laohu/mpay_v2_webman.git
synced 2026-04-21 17:44:27 +08:00
codex基础代码更新
This commit is contained in:
技术老胡
320
doc/project_progress.md
Normal file
320
doc/project_progress.md
Normal file
@@ -0,0 +1,320 @@
|
||||
# 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. 当前一句话结论
|
||||
|
||||
这是一个“骨架已经成型、第一条协议已打通、非常适合继续往生产级推进”的支付中台项目；下一阶段的重点不是重写，而是把已有设计真正补成闭环。
|
||||
Reference in New Issue
Block a user