codex基础代码更新

doc/project_overview.md

@@ -0,0 +1,414 @@
+# MPay V2 Project Overview
+
+更新日期：2026-03-13
+
+## 1. 项目定位
+
+这是一个基于 Webman 的多商户支付中台项目，当前主要目标是：
+
+- 提供后台管理能力，维护商户、应用、支付方式、支付插件、支付通道、订单与系统配置
+- 为商户应用提供统一支付能力
+- 当前已优先兼容 `epay` 协议，后续可继续扩展更多外部支付协议
+- 通过“支付插件 + 通道配置”的方式对接第三方渠道
+
+结合当前代码与数据库，项目已经具备“多商户 -> 多应用 -> 多通道 -> 多插件”的基础骨架。
+
+## 2. 技术栈与运行环境
+
+### 后端技术栈
+
+- PHP `>= 8.1`
+- Webman `^2.1`
+- webman/database
+- webman/redis
+- webman/cache
+- webman/console
+- webman/captcha
+- webman/event
+- webman/redis-queue
+- firebase/php-jwt
+- yansongda/pay `~3.7.0`
+
+### 当前环境配置要点
+
+- HTTP 服务监听：`0.0.0.0:8787`
+- 数据库：MySQL
+- 缓存与队列：Redis
+- 管理后台认证：JWT
+- 当前 `.env` 已配置远程 MySQL / Redis 地址，开发前需要确认本机网络可达
+
+## 3. 当前环境可调用的 MCP 能力
+
+本次会话中，已确认可以直接用于本项目的 MCP / 环境能力如下：
+
+### MySQL MCP
+
+- 可直接执行 SQL
+- 可读取当前开发库表结构与数据
+- 已确认能访问 `mpay_admin` 相关表，例如：
+  - `ma_merchant`
+  - `ma_merchant_app`
+  - `ma_pay_channel`
+  - `ma_pay_order`
+  - `ma_notify_task`
+  - `ma_callback_inbox`
+  - `ma_pay_callback_log`
+
+适合后续继续做：
+
+- 表结构核对
+- 初始化数据检查
+- 回调与订单状态排查
+- 开发联调时快速确认通道配置
+
+### Playwright MCP
+
+- 可进行浏览器打开、点击、表单填写、快照、截图、网络请求分析
+- 适合后续验证：
+  - 管理后台登录流程
+  - 通道配置页面交互
+  - 提交支付后的跳转页/表单页
+  - 回调相关前端可视流程
+
+### MCP 资源浏览
+
+- 可列出 MCP 资源
+- 可读取资源内容
+- 当前未返回资源模板
+
+### 非 MCP 但对开发有用的本地能力
+
+- Shell 命令执行
+- 工作区文件读写
+- 代码补丁编辑
+
+## 4. 业务模型总览
+
+### 4.1 商户模型
+
+- 表：`ma_merchant`
+- 作用：定义商户主体
+- 关键字段：
+  - `merchant_no`
+  - `merchant_name`
+  - `funds_mode`
+  - `status`
+
+### 4.2 商户应用模型
+
+- 表：`ma_merchant_app`
+- 作用：商户可创建多个应用，每个应用具备独立 `app_id` / `app_secret`
+- 关键字段：
+  - `merchant_id`
+  - `api_type`
+  - `app_id`
+  - `app_secret`
+  - `app_name`
+  - `status`
+
+当前代码中，`app_id` 既是应用标识，也是外部协议鉴权入口；`epay` 兼容链路直接用它作为 `pid`。
+
+### 4.3 支付方式模型
+
+- 表：`ma_pay_method`
+- 作用：维护支付方式字典
+- 当前库内数据：
+  - `alipay`
+  - `wechat`
+  - `unionpay`
+
+### 4.4 支付插件模型
+
+- 表：`ma_pay_plugin`
+- 作用：把“支付通道配置”与“PHP 插件实现类”解耦
+- 插件需要同时实现：
+  - `PaymentInterface`
+  - `PayPluginInterface`
+
+当前代码里已有两个插件类：
+
+- `app/common/payment/LakalaPayment.php`
+- `app/common/payment/AlipayPayment.php`
+
+但当前数据库只注册了 `lakala`，还没有把 `alipay` 作为活动插件注册进现网开发库。
+
+### 4.5 支付通道模型
+
+- 表：`ma_pay_channel`
+- 作用：把“商户应用 + 支付方式 + 插件 + 参数配置”绑定起来
+- 关键字段：
+  - `merchant_id`
+  - `merchant_app_id`
+  - `plugin_code`
+  - `method_id`
+  - `config_json`
+  - `split_ratio`
+  - `chan_cost`
+  - `chan_mode`
+  - `daily_limit`
+  - `daily_cnt`
+  - `min_amount`
+  - `max_amount`
+  - `status`
+  - `sort`
+
+这正对应你描述的核心业务特点：一个应用下可配置多个支付通道，每个通道可挂接不同插件与参数。
+
+### 4.6 支付订单模型
+
+- 表：`ma_pay_order`
+- 作用：统一存放系统支付订单
+- 关键特性：
+  - 系统订单号：`order_id`
+  - 商户订单号：`mch_order_no`
+  - 幂等唯一键：`(merchant_id, merchant_app_id, mch_order_no)`
+  - `extra` JSON 用于存放 `notify_url`、`return_url`、`pay_params`、退款信息等
+
+### 4.7 回调与通知模型
+
+- `ma_callback_inbox`：回调幂等收件箱
+- `ma_pay_callback_log`：回调日志
+- `ma_notify_task`：商户异步通知任务
+
+这三张表说明项目已经为“渠道回调幂等 + 日志留痕 + 商户通知补偿”预留了比较完整的基础设施。
+
+## 5. 代码分层与关键入口
+
+### 外部接口入口
+
+- `app/http/api/controller/EpayController.php`
+- `app/http/api/controller/PayController.php`
+
+### 支付主流程服务
+
+- `app/services/api/EpayProtocolService.php`
+- `app/services/api/EpayService.php`
+- `app/services/PayService.php`
+- `app/services/PayOrderService.php`
+- `app/services/ChannelRouterService.php`
+- `app/services/PluginService.php`
+- `app/services/PayNotifyService.php`
+- `app/services/NotifyService.php`
+- `app/services/PaymentStateService.php`
+
+### 支付插件契约
+
+- `app/common/contracts/PaymentInterface.php`
+- `app/common/contracts/PayPluginInterface.php`
+- `app/common/base/BasePayment.php`
+
+### 管理后台接口
+
+- 商户：`MerchantController`
+- 商户应用：`MerchantAppController`
+- 支付方式：`PayMethodController`
+- 插件注册：`PayPluginController`
+- 通道：`ChannelController`
+- 订单：`OrderController`
+- 系统配置：`SystemController`
+- 登录认证：`AuthController`
+
+## 6. 当前已落地的对外接口
+
+### 路由现状
+
+当前 `app/routes/api.php` 实际挂载的对外接口为：
+
+- `GET|POST /submit.php`
+- `POST /mapi.php`
+- `GET /api.php`
+- `ANY /notify/{pluginCode}`
+
+### 兼容协议现状
+
+当前真正已打通的是 `epay` 风格接口：
+
+- `submit.php`：页面跳转支付
+- `mapi.php`：API 下单
+- `api.php?act=order`：查单
+- `api.php?act=refund`：退款
+
+### OpenAPI 现状
+
+`PayController` 中存在以下方法：
+
+- `create`
+- `query`
+- `close`
+- `refund`
+
+但当前都还是 `501 not implemented`，并且对应路由尚未挂载，因此“通用 OpenAPI”目前仍是预留骨架，不是已上线能力。
+
+## 7. 核心支付链路
+
+### 7.1 Epay 下单链路
+
+1. 商户调用 `submit.php` 或 `mapi.php`
+2. `EpayProtocolService` 负责参数提取与校验
+3. `EpayService` 使用 `app_secret` 做 MD5 验签
+4. 构造统一内部订单数据
+5. `PayOrderService` 创建订单，并通过联合唯一键保证幂等
+6. `ChannelRouterService` 根据 `merchant_id + merchant_app_id + method_id` 选取通道
+7. `PluginService` 从注册表解析插件类并实例化
+8. 插件执行 `pay()`
+9. `PayService` 回写：
+   - `channel_id`
+   - `chan_order_no`
+   - `chan_trade_no`
+   - `fee`
+   - `real_amount`
+   - `extra.pay_params`
+10. 转换成 `epay` 所需返回结构给调用方
+
+### 7.2 回调处理链路
+
+1. 第三方渠道回调 `/notify/{pluginCode}`
+2. `PayNotifyService` 调插件 `notify()` 验签与解析
+3. 通过 `ma_callback_inbox` 做幂等去重
+4. 状态机更新订单状态
+5. 写入回调日志
+6. 创建商户通知任务
+
+### 7.3 商户通知链路
+
+1. `NotifyService` 根据订单 `extra.notify_url` 创建通知任务
+2. 通知内容写入 `ma_notify_task`
+3. `sendNotify()` 使用 HTTP POST JSON 回调商户
+4. 若商户返回 HTTP 200 且 body 为 `success`，视为通知成功
+
+## 8. 插件与通道现状
+
+### `LakalaPayment`
+
+状态：示例插件 / mock 插件
+
+现状：
+
+- `pay()` 已实现，但只是返回模拟二维码字符串
+- `query()` 未实现
+- `close()` 未实现
+- `refund()` 未实现
+- `notify()` 未实现
+
+这意味着当前库里虽然已经能“创建订单并拿到拉起参数”，但还不能完成真实的拉卡拉闭环。
+
+### `AlipayPayment`
+
+状态：代码层面相对完整
+
+已实现：
+
+- `pay()`
+- `query()`
+- `close()`
+- `refund()`
+- `notify()`
+
+特点：
+
+- 基于 `yansongda/pay`
+- 支持产品类型：
+  - `alipay_web`
+  - `alipay_h5`
+  - `alipay_scan`
+  - `alipay_app`
+- 可根据环境自动选产品
+
+注意：
+
+- 当前开发库没有注册 `alipay` 插件记录
+- 当前通道也没有指向 `AlipayPayment`
+
+所以它虽然写在代码里，但当前数据库并没有真正启用它。
+
+## 9. 管理后台现状
+
+后台已经覆盖以下核心维护能力：
+
+- 验证码登录 + JWT 鉴权
+- 商户管理
+- 商户应用管理
+- 支付方式管理
+- 支付插件注册管理
+- 支付通道管理
+- 订单列表 / 详情 / 退款
+- 系统基础配置管理
+
+这部分说明“支付中心后台”已经不是空架子，而是可以承接后续运营配置的。
+
+## 10. 当前开发库快照（基于 2026-03-13 实际查询）
+
+### 数据量
+
+- `ma_admin`: 1
+- `ma_merchant`: 1
+- `ma_merchant_app`: 1
+- `ma_pay_method`: 3
+- `ma_pay_plugin`: 1
+- `ma_pay_channel`: 2
+- `ma_pay_order`: 1
+- `ma_notify_task`: 0
+- `ma_callback_inbox`: 0
+- `ma_pay_callback_log`: 0
+
+### 当前商户与应用
+
+- 商户：`M001 / 测试商户`
+- 应用：`1001 / 测试应用-易支付`
+- 应用类型：`epay`
+
+### 当前活动插件
+
+- `lakala -> app\\common\\payment\\LakalaPayment`
+
+### 当前通道
+
+- `lakala_alipay`
+- `lakala_wechat`
+
+### 当前示例订单
+
+- 订单号：`P20260312160833644578`
+- 商户单号：`TEST123`
+- 状态：`PENDING`
+- 通道：`channel_id = 1`
+- `extra.pay_params` 为 mock 二维码
+
+## 11. 当前代码与需求的对应关系
+
+你给出的项目特点，与当前实现的对应情况如下：
+
+### 已匹配的部分
+
+- 多商户：已支持
+- 一个商户多个应用：已支持
+- 一个应用多个支付通道：已支持
+- 通道可绑定支付方式：已支持
+- 通道可绑定支付插件：已支持
+- 通道可存储插件参数：已支持
+- 通道可配置手续费：已支持，当前会参与 `fee` / `real_amount` 计算
+- 商户通过 `APPID` 发起支付：已支持，当前主要在 `epay` 兼容链路中落地
+- 创建订单并调用第三方插件：已支持
+
+### 仅完成“数据建模”，尚未完全落地执行的部分
+
+- 每日限额：字段已存在，但当前下单/路由流程未校验
+- 每日笔数限制：字段已存在，但当前未校验
+- 最小/最大金额限制：字段已存在，但当前未校验
+- 更复杂的路由策略：当前仅按 `sort` 取第一条可用通道
+- 多协议统一 OpenAPI：控制器骨架存在，但未真正接入
+
+## 12. 后续阅读建议
+
+如果下一次继续开发，建议优先从以下文件继续进入：
+
+- 支付入口：`app/http/api/controller/EpayController.php`
+- 协议适配：`app/services/api/EpayProtocolService.php`
+- 业务主流程：`app/services/PayService.php`
+- 订单创建：`app/services/PayOrderService.php`
+- 回调处理：`app/services/PayNotifyService.php`
+- 插件管理：`app/services/PluginService.php`
+- 拉卡拉插件：`app/common/payment/LakalaPayment.php`
+- 支付宝插件：`app/common/payment/AlipayPayment.php`
+- 通道配置：`app/http/admin/controller/ChannelController.php`
+