1. 维护代码健壮

2. 更新项目结构文档
2026-05-10 19:04:27 +08:00 · 2026-04-27 16:20:41 +08:00
parent 9a16a88640
commit 0e5de50337
198 changed files with 21038 additions and 702 deletions
--- a/doc/frontend/README.md
+++ b/doc/frontend/README.md
@@ -0,0 +1,32 @@
+# 前端总说明
+
+当前有三套独立前端，均可单独安装、启动、构建和发布。
+
+| 项目 | 技术栈 | 页面入口 | API 前缀 | 主要职责 |
+| --- | --- | --- | --- | --- |
+| `admin` | Vue 3 + Vite + Arco Design | `/admin` | `/adminapi` | 平台运营与配置 |
+| `mer` | Vue 3 + Vite + Arco Design | `/mer` | `/merapi` | 商户自助后台 |
+| `cashier` | Vue 3 + Vite + Tailwind CSS | `/cashier`、`/payment` | `/api/cashier` | 用户侧收银台 |
+
+## 共性
+
+- 每个前端都有自己的 `package.json` 和环境文件。
+- `admin`、`mer` 的 axios 实例会在 `VITE_APP_BASE_URL` 后拼接 `/adminapi` 或 `/merapi`。
+- `cashier` 的 axios 实例使用 `VITE_API_BASE_URL` 作为基址，并在请求路径中拼接 `VITE_API_PREFIX`，默认是 `/api`。
+- 本地开发默认代理或直连 `http://127.0.0.1:8787`。
+
+## 命令
+
+| 项目 | 开发 | 构建 | 预览 |
+| --- | --- | --- | --- |
+| `admin` | `pnpm dev` | `pnpm build:dev` / `pnpm build:prod` / `pnpm build:test` | `pnpm preview` |
+| `mer` | `pnpm dev` | `pnpm build:dev` / `pnpm build:prod` / `pnpm build:test` | `pnpm preview` |
+| `cashier` | `pnpm dev` | `pnpm build` | `pnpm preview` |
+
+## 阅读入口
+
+- [管理后台前端](./admin.md)
+- [商户后台前端](./mer.md)
+- [收银台前端](./cashier.md)
+- [接口总说明](../api/README.md)
+- [部署总说明](../deployment/README.md)
--- a/doc/frontend/admin.md
+++ b/doc/frontend/admin.md
@@ -0,0 +1,54 @@
+# 管理后台前端
+
+`admin` 是平台管理后台，服务于运营、配置、财务和运维人员。
+
+## 基本信息
+
+- 目录：`admin/`
+- 技术栈：Vue 3、Vite、TypeScript、Arco Design、Pinia、axios
+- 页面入口：`/admin`
+- API 前缀：`VITE_APP_BASE_URL + /adminapi`
+- 开发默认后端：`http://127.0.0.1:8787`
+- 开发公共路径：`/admin`
+- 生产公共路径：`/`
+
+## 主要模块
+
+- 商户、商户分组、商户 API 凭证、商户策略
+- 支付方式、支付插件、插件配置、支付通道、轮询组与绑定
+- 路由解析预览
+- 支付订单、退款订单、清算订单
+- 商户账户、资金流水
+- 通道日统计、通道通知日志、支付回调日志、商户通知任务
+- 文件资产、系统菜单、字典、系统配置页面、管理员用户
+
+## 关键目录
+
+```text
+src/api/modules/       接口封装
+src/router/            静态路由和动态路由处理
+src/views/             页面
+src/store/             Pinia 状态
+src/components/        业务与通用组件
+```
+
+## 文件上传
+
+管理后台的文件资产接口是 `/adminapi/file-asset`。系统配置和插件配置中的上传字段仍使用 `type: "upload"`；需要走项目定制的图片/文件选择器时，在 `props.fileUpload` 中声明：
+
+- `selectorType`：`image` 或 `file`
+- `scene`：图片、证书、文本或其他场景
+- `isLocal`：是否强制本地存储
+- `isPublic`：是否公开访问
+- `getKey`：上传成功后回填的响应字段，常用 `url`、`object_key`、`preview_url`、`id`
+
+完整文件资产行为见 [文件资产](../backend/files.md)。
+
+## 常用命令
+
+```bash
+pnpm install
+pnpm dev
+pnpm build:prod
+pnpm preview
+```
--- a/doc/frontend/cashier.md
+++ b/doc/frontend/cashier.md
@@ -0,0 +1,47 @@
+# 收银台前端
+
+`cashier` 是用户侧支付前端，负责收银台上下文展示、确认支付、跳转和支付结果页。
+
+## 基本信息
+
+- 目录：`cashier/`
+- 技术栈：Vue 3、Vite、TypeScript、Tailwind CSS、axios、qrcode
+- 页面入口：`/cashier`、`/payment`
+- JSON API：默认 `/api/cashier/*`
+- 开放支付 API：后端同时提供 `/api/pay/*`
+- 本地代理：`/api` 默认代理到 `http://127.0.0.1:8787`
+
+## 页面路由
+
+| 路由 | 页面 |
+| --- | --- |
+| `/cashier` | 首页 |
+| `/cashier/:bizNo` | 收银台入口页 |
+| `/payment/:payNo` | 支付页 |
+| `/payment/:payNo/redirect` | 支付中转页 |
+| `/payment/:payNo/result` | 结果页 |
+| `/payment/:payNo/success` | 成功结果页 |
+| `/payment/:payNo/return` | 支付返回页 |
+| `/payment/:payNo/error` | 支付错误页 |
+| `/payment/:payNo/back` | 返回中转页 |
+
+页面路由前缀在 `src/config/index.ts` 中固定为 `CASHIER_PATH_PREFIX=/cashier`、`PAYMENT_PATH_PREFIX=/payment`。当前 `.env` 中的 `VITE_ROUTE_PREFIX` 只是遗留示例变量，代码没有读取它。
+
+## 接口调用
+
+`src/api/cashier.ts` 当前封装三类接口：
+
+- `GET /api/cashier/context?biz_no=...`
+- `POST /api/cashier/confirm`
+- `GET /api/cashier/pay-order?pay_no=...`
+
+`VITE_API_PREFIX` 会影响请求路径前缀，默认是 `api`；`VITE_API_BASE_URL` 用于直连后端，不填时本地通过 Vite 代理访问 `/api`。
+
+## 常用命令
+
+```bash
+pnpm install
+pnpm dev
+pnpm build
+pnpm preview
+```
--- a/doc/frontend/menu.md
+++ b/doc/frontend/menu.md
@@ -0,0 +1,146 @@
+# 菜单说明
+
+> 真实菜单以 [`../../mpay/config/menu.php`](../../mpay/config/menu.php) 为准；稳定口径见 [`../standards.md`](../standards.md)。
+
+这份文档只说明当前页面和菜单职责，不重复项目事实。
+
+## 1. 管理后台当前菜单
+
+```text
+管理后台
+├─ 首页
+├─ 商户管理
+│  ├─ 商户列表
+│  └─ 商户分组
+├─ 通道中心
+│  ├─ 支付方式
+│  ├─ 支付插件
+│  ├─ 插件配置
+│  ├─ 通道列表
+│  └─ 通道日统计
+├─ 路由中心
+│  ├─ 轮询组
+│  ├─ 路由编排
+│  └─ 路由预览
+├─ 交易中心
+│  ├─ 支付订单
+│  ├─ 退款订单
+│  ├─ 清算订单
+│  ├─ 通道通知日志
+│  └─ 支付回调日志
+├─ 资金中心
+│  ├─ 资金账户
+│  └─ 资金流水
+├─ 系统管理
+│  ├─ 管理员用户
+│  └─ 系统配置
+└─ 文件中心
+   └─ 文件管理
+```
+
+## 2. 商户后台当前菜单
+
+```text
+商户后台
+├─ 首页
+├─ 通道中心
+│  ├─ 我的通道
+│  ├─ 路由预览
+│  └─ 商户 API 凭证
+├─ 交易中心
+│  ├─ 支付订单
+│  ├─ 退款订单
+│  └─ 清算记录
+├─ 资金中心
+│  ├─ 可提现余额
+│  └─ 余额流水
+└─ 基础设置
+   ├─ 商户资料
+   └─ 登录认证
+```
+
+## 3. 页面职责
+
+### 3.1 商户管理
+
+| 页面 | 当前职责 |
+|---|---|
+| 商户列表 | 商户主体资料维护 + 通过操作台抽屉查看接入、商户 API 凭证、资金等摘要 |
+| 商户分组 | 商户分组主数据维护，是路由绑定的输入条件 |
+
+说明：
+
+- 不再单独暴露“商户用户”页面
+- 商户更多能力通过商户列表内的操作台处理
+
+### 3.2 通道中心
+
+| 页面 | 当前职责 |
+|---|---|
+| 支付方式 | 支付方式字典维护 |
+| 支付插件 | 扫描插件类并同步插件定义 |
+| 插件配置 | 维护插件初始化配置 |
+| 通道列表 | 维护平台通道和商户自有通道 |
+| 通道日统计 | 查看通道健康度、成功率、耗时等 |
+
+### 3.3 路由中心
+
+| 页面 | 当前职责 |
+|---|---|
+| 轮询组 | 维护轮询组本身，并在组内编排候选通道 |
+| 路由编排 | 维护“商户分组 + 支付方式 -> 轮询组”的绑定关系 |
+| 路由预览 | 按真实链路预览某次支付会命中哪个通道 |
+
+当前路由模式：
+
+- 顺序依次轮询
+- 权重随机轮询
+- 默认启用通道
+
+### 3.4 交易中心
+
+| 页面 | 当前职责 |
+|---|---|
+| 支付订单 | 平台支付单查询、详情、回调和状态跟踪 |
+| 退款订单 | 退款单查询、退款推进和退款结果跟踪 |
+| 清算订单 | 平台代收清算批次、明细和结算结果查看 |
+| 通道通知日志 | 查看通道侧通知记录和失败原因 |
+| 支付回调日志 | 查看支付回调记录和幂等处理结果 |
+
+### 3.5 资金中心
+
+| 页面 | 当前职责 |
+|---|---|
+| 资金账户 | 商户账户余额、冻结余额、可用余额查看 |
+| 资金流水 | 商户账户入账、出账、冻结、解冻流水查看 |
+
+### 3.6 系统管理
+
+| 页面 | 当前职责 |
+|---|---|
+| 管理员用户 | 平台管理员账号维护 |
+| 系统配置 | 平台级配置维护与同步 |
+
+### 3.7 文件中心
+
+| 页面 | 当前职责 |
+|---|---|
+| 文件管理 | 统一管理图片、证书、文本和其他附件，支持本地存储和对象存储切换 |
+
+### 3.8 商户后台
+
+| 页面 | 当前职责 |
+|---|---|
+| 我的通道 | 只读查看当前商户可见通道 |
+| 路由预览 | 输入支付方式和金额，查看当前商户会命中的通道 |
+| 商户 API 凭证 | 查看当前商户的商户 API 凭证相关信息 |
+| 商户资料 | 维护联系人与结算信息 |
+| 登录认证 | 修改登录密码，查看登录相关信息 |
+
+## 4. 口径差异
+
+- 轮询组已从“通道中心”移动到“路由中心”
+- 商户管理不再拆“商户用户”
+- 商户更多能力仍收在列表页内的操作台
+- 商户后台登录已改为“商户号 + 密码”
+- 商户 API 凭证与商户后台登录彻底分离
--- a/doc/frontend/mer.md
+++ b/doc/frontend/mer.md
@@ -0,0 +1,46 @@
+# 商户后台前端
+
+`mer` 是商户自助后台，服务于商户查看自身资料、凭证、订单、退款和资金信息。
+
+## 基本信息
+
+- 目录：`mer/`
+- 技术栈：Vue 3、Vite、TypeScript、Arco Design、Pinia、axios
+- 页面入口：`/mer`
+- API 前缀：`VITE_APP_BASE_URL + /merapi`
+- 开发默认后端：`http://127.0.0.1:8787`
+- 开发公共路径：`/mer`
+- 生产公共路径：`/`
+
+## 主要模块
+
+- 商户登录、退出、当前用户资料
+- 商户资料维护、修改登录密码
+- 我的通道维护、商户插件配置、路由预览
+- 商户 API 凭证查看与重置
+- 支付订单、退款订单、退款重试
+- 清算记录、可提现余额、资金流水
+- 菜单树和字典项
+
+## 自助通道配置
+
+商户端通道中心包含“我的通道”和“插件配置”。“插件配置”只展示当前商户自己的配置；“我的通道”新增或编辑时只能绑定当前商户的插件配置，并且插件来源受管理后台“商户端自助使用”开关控制。
+
+## 关键目录
+
+```text
+src/api/modules/       接口封装
+src/router/            路由
+src/views/             页面
+src/store/             状态
+src/components/        组件
+```
+
+## 常用命令
+
+```bash
+pnpm install
+pnpm dev
+pnpm build:prod
+pnpm preview
+```