1. 维护代码健壮

2. 更新项目结构文档

doc/overview.md

@@ -0,0 +1,62 @@
+# 项目总览
+
+`MPAY_V2` 是一个支付中台工作区，后端基于 Webman，前端拆成管理后台、商户后台和收银台三套独立应用。
+
+## 工作区组成
+
+| 目录 | 类型 | 职责 |
+| --- | --- | --- |
+| `mpay` | PHP / Webman 后端 | 支付、退款、路由、插件、回调、商户、资金、清算、文件与系统配置 |
+| `admin` | Vue 3 管理后台 | 商户、通道、插件、轮询、订单、退款、清算、资金、日志、文件、系统配置 |
+| `mer` | Vue 3 商户后台 | 商户资料、API 凭证、可用通道、路由预览、订单、退款、清算、余额和流水 |
+| `cashier` | Vue 3 收银台 | 收银台上下文、确认支付、支付跳转、支付单状态和结果页 |
+| `docs` | 文档中心 | 当前项目事实、接口、部署和协作说明 |
+
+根目录只是工作区容器；`admin`、`mer`、`cashier`、`mpay` 各自保留独立 Git 仓库。
+
+## 核心链路
+
+```text
+商户系统/ePay 请求
+  -> 后端校验商户与签名
+  -> 创建业务单/支付单
+  -> 商户分组路由解析
+  -> 轮询组选择支付通道
+  -> 支付插件调用第三方
+  -> 收银台展示或跳转
+  -> 回调/查单推进状态
+  -> 通知商户
+  -> 清算后写入商户资金与流水
+```
+
+## 当前入口
+
+| 场景 | 页面入口 | API 入口 | 后端路由文件 |
+| --- | --- | --- | --- |
+| 管理后台 | `/admin` | `/adminapi` | `mpay/app/route/admin.php` |
+| 商户后台 | `/mer` | `/merapi` | `mpay/app/route/mer.php` |
+| 收银台 | `/cashier`、`/payment` | `/api/cashier`、`/api/pay` | `mpay/app/route/api.php` |
+| ePay V1 兼容 | `/submit.php`、`/mapi.php`、`/api.php` | 同左 | `mpay/app/route/api.php` |
+| ePay V2 / 开放 API | 无固定页面 | `/api/pay`、`/api/merchant`、`/api/transfer` | `mpay/app/route/api.php` |
+
+## 后端重点模块
+
+- `app/http`：管理后台、商户后台、开放 API 的控制器、中间件和参数校验。
+- `app/route`：显式路由；默认路由已关闭。
+- `app/service/payment`：支付、退款、清算、路由、插件、通知、追踪和 ePay 协议。
+- `app/service/merchant`：商户主体、登录、分组、策略、商户后台能力和 API 凭证。
+- `app/service/account`：商户资金账户和流水。
+- `app/service/file`：文件资产、上传、预览、下载和存储驱动。
+- `app/common/payment`：支付插件实现，当前包含 Alipay、ePay V1、ePay V2 和模板插件。
+
+## 数据范围
+
+当前 DDL 包含支付配置、商户、订单、退款、转账、资金、清算、日志、通知、文件、系统配置和管理员用户表。完整表结构以 [当前 DDL](./db/payment-middle-ddl.sql) 为准。
+
+## 推荐阅读
+
+1. [架构与请求流](./architecture.md)
+2. [后端总说明](./backend/README.md)
+3. [前端总说明](./frontend/README.md)
+4. [接口总说明](./api/README.md)
+5. [部署总说明](./deployment/README.md)