1. 维护代码健壮

2. 更新项目结构文档

doc/deployment/README.md

@@ -0,0 +1,26 @@
+# 部署总说明
+
+四个项目独立启动、构建和发布。后端负责 API 与页面兜底路由，前端负责生成静态产物。
+
+## 命令速览
+
+| 项目 | 开发/启动 | 构建 |
+| --- | --- | --- |
+| `mpay` | `php webman start` 或 `php windows.php` | 无前端构建 |
+| `admin` | `pnpm dev` | `pnpm build:prod` |
+| `mer` | `pnpm dev` | `pnpm build:prod` |
+| `cashier` | `pnpm dev` | `pnpm build` |
+
+## 默认端口与路径
+
+- 后端默认监听 `http://127.0.0.1:8787`。
+- 管理后台页面入口是 `/admin`，接口是 `/adminapi`。
+- 商户后台页面入口是 `/mer`，接口是 `/merapi`。
+- 收银台页面入口是 `/cashier`、`/payment`，接口是 `/api/cashier` 和 `/api/pay`。
+
+## 部署建议
+
+- 后端生产环境使用守护进程或进程管理工具托管。
+- `admin`、`mer`、`cashier` 的 `dist/` 可独立托管，也可发布到 `mpay/public` 下对应目录。
+- 如果前后端同域部署，确保 `/adminapi`、`/merapi`、`/api`、ePay V1 兼容入口都能转发到 `mpay`。
+- 环境变量说明见 [env.md](./env.md)。

doc/deployment/admin.md

@@ -0,0 +1,18 @@
+# 管理后台部署
+
+命令默认在 `admin/` 目录执行。
+
+```bash
+pnpm install
+pnpm build:prod
+```
+
+产物在 `dist/`。
+
+## 路径
+
+- 开发公共路径：`/admin`
+- 生产默认公共路径：`/`
+- 生产接口基址：`VITE_APP_BASE_URL=/`，运行时请求 `/adminapi`
+
+部署到子路径时，同步调整 `VITE_PUBLIC_PATH` 和网关重写规则。

doc/deployment/backend.md

@@ -0,0 +1,31 @@
+# 后端部署
+
+命令默认在 `mpay/` 目录执行。
+
+## 前置条件
+
+- PHP 8.1+
+- Composer
+- MySQL
+- Redis
+
+## 启动
+
+```bash
+composer install
+Copy-Item .env.example .env
+php webman start
+```
+
+Windows 开发环境需要同时启动自定义进程时：
+
+```bash
+php windows.php
+```
+
+## 生产要点
+
+- 配置数据库、Redis、JWT 密钥和支付运行时心跳。
+- 使用进程管理工具托管 `webman` 和 `payment-runtime`。
+- 执行 `php webman system:config-sync` 同步系统配置默认值。
+- 如使用 OSS/COS，先在系统配置中补齐存储参数。

doc/deployment/cashier.md

@@ -0,0 +1,19 @@
+# 收银台部署
+
+命令默认在 `cashier/` 目录执行。
+
+```bash
+pnpm install
+pnpm build
+```
+
+产物在 `dist/`。
+
+## 路径
+
+- 页面入口：`/cashier`、`/payment`
+- 收银台 JSON API：`/api/cashier`
+- ePay V2 / 开放支付 API：`/api/pay`、`/api/merchant`、`/api/transfer`
+- ePay V1 兼容入口：`/submit.php`、`/mapi.php`、`/api.php`
+
+如果前端不走同域代理，配置 `VITE_API_BASE_URL` 指向后端；否则保持为空，通过相对路径访问 `/api`。

doc/deployment/env.md

@@ -0,0 +1,65 @@
+# 环境变量
+
+本文只列当前代码读取或模板中声明的关键变量，不记录敏感值。
+
+## 后端 `mpay`
+
+环境文件：
+
+- `.env`
+- `.env.example`
+
+关键变量：
+
+| 变量 | 用途 |
+| --- | --- |
+| `DB_HOST`、`DB_PORT`、`DB_DATABASE`、`DB_USERNAME`、`DB_PASSWORD` | MySQL 连接 |
+| `REDIS_HOST`、`REDIS_PORT`、`REDIS_PASSWORD`、`REDIS_DATABASE` | Redis 连接 |
+| `CACHE_DRIVER` | 缓存驱动 |
+| `AUTH_JWT_ISSUER`、`AUTH_JWT_LEEWAY` | JWT 通用参数 |
+| `AUTH_ADMIN_JWT_SECRET`、`AUTH_ADMIN_JWT_TTL`、`AUTH_ADMIN_JWT_REDIS_PREFIX` | 管理后台登录 token |
+| `AUTH_MERCHANT_JWT_SECRET`、`AUTH_MERCHANT_JWT_TTL`、`AUTH_MERCHANT_JWT_REDIS_PREFIX` | 商户后台登录 token |
+| `PAY_RUNTIME_HEARTBEAT_SECONDS` | 支付运行时进程心跳间隔 |
+
+系统配置、站点 URL、支付运行时开关和存储参数主要由 `config/system_config.php` 定义，并可同步到数据库。
+
+## 管理后台 `admin`
+
+环境文件：
+
+- `.env`
+- `.env.development`
+- `.env.production`
+- `.env.test`
+
+关键变量：
+
+| 变量 | 用途 |
+| --- | --- |
+| `VITE_USER_NODE_ENV` | 环境标识 |
+| `VITE_ROUTER_MODE` | 路由模式，开发默认为 `history`，生产默认为 `hash` |
+| `VITE_PUBLIC_PATH` | 构建公共路径，开发默认为 `/admin` |
+| `VITE_APP_BASE_URL` | 后端基址，前端会拼接 `/adminapi` |
+| `VITE_APP_OPEN_MOCK` | 是否使用本地 mock，代码中有读取 |
+
+## 商户后台 `mer`
+
+环境文件和变量与 `admin` 基本一致；前端会在 `VITE_APP_BASE_URL` 后拼接 `/merapi`。
+
+## 收银台 `cashier`
+
+环境文件：
+
+- `.env`
+- `.env.example`
+
+关键变量：
+
+| 变量 | 用途 |
+| --- | --- |
+| `VITE_USE_MOCK` | 是否启用 mock 演示 |
+| `VITE_API_PREFIX` | API 路径前缀，默认 `api` |
+| `VITE_API_PROXY_TARGET` | Vite 开发代理目标，默认 `http://127.0.0.1:8787` |
+| `VITE_API_BASE_URL` | 直连后端 API 基址，留空则走相对路径/开发代理 |
+
+注意：`cashier/.env.example` 中仍有 `VITE_ROUTE_PREFIX`，但当前 `cashier/src/config/index.ts` 未读取它；页面路由前缀实际固定为 `/cashier` 和 `/payment`。

doc/deployment/mer.md

@@ -0,0 +1,18 @@
+# 商户后台部署
+
+命令默认在 `mer/` 目录执行。
+
+```bash
+pnpm install
+pnpm build:prod
+```
+
+产物在 `dist/`。
+
+## 路径
+
+- 开发公共路径：`/mer`
+- 生产默认公共路径：`/`
+- 生产接口基址：`VITE_APP_BASE_URL=/`，运行时请求 `/merapi`
+
+部署到子路径时，同步调整 `VITE_PUBLIC_PATH` 和网关重写规则。