mirror of
https://gitee.com/technical-laohu/mpay_v2_webman.git
synced 2026-03-25 12:14:31 +08:00
313 lines
14 KiB
Markdown
313 lines
14 KiB
Markdown
# MPAY V2 项目技术栈与结构文档
|
||
|
||
## 1. 项目概述
|
||
|
||
MPAY V2 是一个基于 Webman 后端框架和 Vue 3 前端框架的支付管理系统，核心聚焦支付业务：商户管理、通道配置、统一支付、易支付兼容、商户通知等。管理后台提供管理员认证、菜单、系统配置、通道与插件管理；对外提供 OpenAPI 与易支付标准接口。
|
||
|
||
## 2. 技术架构
|
||
|
||
### 2.1 后端技术栈
|
||
|
||
| 类别 | 技术/框架 | 版本 | 用途 | 来源 |
|
||
|------|-----------|------|------|------|
|
||
| 基础框架 | Webman | ^2.1 | 高性能HTTP服务框架 | composer.json |
|
||
| PHP版本 | PHP | >=8.1 | 开发语言 | composer.json |
|
||
| 数据库 | webman/database | ^2.1 | 数据库操作 | composer.json |
|
||
| 缓存 | Redis | ^2.1 | 缓存存储 | composer.json |
|
||
| 缓存 | webman/cache | ^2.1 | 缓存管理 | composer.json |
|
||
| 认证 | JWT | ^7.0 | 管理员认证 | composer.json |
|
||
| 验证码 | webman/captcha | ^1.0 | 登录验证码 | composer.json |
|
||
| 事件系统 | webman/event | ^1.0 | 事件管理 | composer.json |
|
||
| 配置管理 | vlucas/phpdotenv | ^5.6 | 环境变量 | composer.json |
|
||
| 定时任务 | workerman/crontab | ^1.0 | 定时任务 | composer.json |
|
||
| 队列 | webman/redis-queue | ^2.1 | 消息队列 | composer.json |
|
||
| 验证 | topthink/think-validate | ^3.0 | 数据验证 | composer.json |
|
||
| 容器 | php-di/php-di | 7.0 | 依赖注入 | composer.json |
|
||
| 日志 | monolog/monolog | ^2.0 | 日志管理 | composer.json |
|
||
| 控制台 | webman/console | ^2.1 | 命令行工具 | composer.json |
|
||
|
||
### 2.2 前端技术栈
|
||
|
||
| 类别 | 技术/框架 | 版本 | 用途 | 来源 |
|
||
|------|-----------|------|------|------|
|
||
| 基础框架 | Vue | ^3.5.15 | 前端框架 | package.json |
|
||
| 语言 | TypeScript | ^5.2.2 | 开发语言 | package.json |
|
||
| 构建工具 | Vite | ^6.3.5 | 构建工具 | package.json |
|
||
| UI框架 | Arco Design | ^2.57.0 | 界面组件库 | package.json |
|
||
| 状态管理 | Pinia | ^2.3.0 | 状态管理 | package.json |
|
||
| 路由 | Vue Router | ^4.3.0 | 前端路由 | package.json |
|
||
| HTTP客户端 | Axios | ^1.6.8 | API调用 | package.json |
|
||
| 表单生成 | @form-create/arco-design | ^3.2.37 | 动态表单 | package.json |
|
||
| 图表 | @visactor/vchart | ^1.11.0 | 数据可视化 | package.json |
|
||
| 国际化 | vue-i18n | 10.0.0-alpha.3 | 多语言支持 | package.json |
|
||
| 工具库 | @vueuse/core | ^12.4.0 | 实用工具 | package.json |
|
||
| 二维码 | qrcode | ^1.5.4 | 二维码生成 | package.json |
|
||
|
||
## 3. 项目结构
|
||
|
||
### 3.1 后端目录结构
|
||
|
||
```
|
||
d:\phpstudy_pro\WWW\mpay\mpay_v2_webman\
|
||
├── app/ # 应用代码
|
||
│ ├── common/ # 通用代码
|
||
│ │ ├── base/ # 基础类
|
||
│ │ │ ├── BaseController.php
|
||
│ │ │ ├── BaseModel.php
|
||
│ │ │ ├── BaseRepository.php
|
||
│ │ │ └── BaseService.php
|
||
│ │ ├── contracts/ # 契约/接口
|
||
│ │ │ ├── PayPluginInterface.php
|
||
│ │ │ └── AbstractPayPlugin.php
|
||
│ │ ├── constants/ # 常量
|
||
│ │ ├── enums/ # 枚举
|
||
│ │ ├── middleware/ # 中间件（Cors, StaticFile）
|
||
│ │ ├── payment/ # 支付插件实现
|
||
│ │ │ └── LakalaPayment.php
|
||
│ │ └── utils/ # 工具类（JwtUtil 等）
|
||
│ ├── events/ # 事件
|
||
│ ├── exceptions/ # 异常（BadRequest, NotFound, Validation 等）
|
||
│ ├── http/
|
||
│ │ ├── admin/ # 管理后台
|
||
│ │ │ ├── controller/
|
||
│ │ │ │ ├── AuthController.php
|
||
│ │ │ │ ├── AdminController.php
|
||
│ │ │ │ ├── MenuController.php
|
||
│ │ │ │ ├── SystemController.php
|
||
│ │ │ │ ├── ChannelController.php
|
||
│ │ │ │ └── PluginController.php
|
||
│ │ │ └── middleware/
|
||
│ │ │ └── AuthMiddleware.php
|
||
│ │ └── api/ # 对外 API
|
||
│ │ ├── controller/
|
||
│ │ │ ├── PayController.php # OpenAPI 支付接口（骨架）
|
||
│ │ │ └── EpayController.php # 易支付接口（submit.php/mapi.php/api.php）
|
||
│ │ └── middleware/
|
||
│ │ ├── EpayAuthMiddleware.php
|
||
│ │ └── OpenApiAuthMiddleware.php
|
||
│ ├── jobs/ # 异步任务
|
||
│ │ └── NotifyMerchantJob.php
|
||
│ ├── models/ # 数据模型
|
||
│ │ ├── Admin.php
|
||
│ │ ├── Merchant.php
|
||
│ │ ├── MerchantApp.php
|
||
│ │ ├── PaymentMethod.php
|
||
│ │ ├── PaymentPlugin.php
|
||
│ │ ├── PaymentChannel.php
|
||
│ │ ├── PaymentOrder.php
|
||
│ │ ├── PaymentCallbackLog.php
|
||
│ │ ├── PaymentNotifyTask.php
|
||
│ │ └── SystemConfig.php
|
||
│ ├── repositories/ # 数据仓储
|
||
│ │ ├── AdminRepository.php
|
||
│ │ ├── MerchantRepository.php
|
||
│ │ ├── MerchantAppRepository.php
|
||
│ │ ├── PaymentMethodRepository.php
|
||
│ │ ├── PaymentPluginRepository.php
|
||
│ │ ├── PaymentChannelRepository.php
|
||
│ │ ├── PaymentOrderRepository.php
|
||
│ │ ├── PaymentNotifyTaskRepository.php
|
||
│ │ ├── PaymentCallbackLogRepository.php
|
||
│ │ └── SystemConfigRepository.php
|
||
│ ├── routes/ # 路由
|
||
│ │ ├── admin.php
|
||
│ │ ├── api.php
|
||
│ │ └── mer.php
|
||
│ ├── services/ # 业务逻辑
|
||
│ │ ├── AuthService.php
|
||
│ │ ├── AdminService.php
|
||
│ │ ├── CaptchaService.php
|
||
│ │ ├── MenuService.php
|
||
│ │ ├── SystemConfigService.php
|
||
│ │ ├── SystemSettingService.php
|
||
│ │ ├── PluginService.php # 插件注册与实例化
|
||
│ │ ├── ChannelRouterService.php # 通道路由（按商户+应用+支付方式选通道）
|
||
│ │ ├── PayOrderService.php # 订单创建、幂等、退款
|
||
│ │ ├── PayService.php # 统一下单、调用插件
|
||
│ │ ├── NotifyService.php # 商户通知、重试
|
||
│ │ └── api/
|
||
│ │ └── EpayService.php # 易支付业务封装
|
||
│ ├── validation/ # 验证器
|
||
│ │ ├── EpayValidator.php
|
||
│ │ └── SystemConfigValidator.php
|
||
│ └── process/ # 进程（Http, Monitor）
|
||
├── config/ # 配置文件
|
||
├── database/ # 数据库脚本
|
||
│ └── mvp_payment_tables.sql # 支付系统核心表（ma_*）
|
||
├── doc/ # 文档
|
||
│ ├── skill.md
|
||
│ ├── epay.md
|
||
│ ├── payment_flow.md
|
||
│ ├── validation.md
|
||
│ └── payment_system_implementation.md
|
||
├── public/
|
||
├── resource/
|
||
│ └── mpay_v2_admin/ # 前端项目
|
||
├── .env
|
||
└── composer.json
|
||
```
|
||
|
||
### 3.2 数据库表结构（`database/mvp_payment_tables.sql`）
|
||
|
||
| 表名 | 说明 |
|
||
|------|------|
|
||
| ma_merchant | 商户表 |
|
||
| ma_merchant_app | 商户应用表（api_type 区分 openapi/epay/custom） |
|
||
| ma_pay_method | 支付方式字典（alipay/wechat/unionpay） |
|
||
| ma_pay_plugin | 支付插件注册表（plugin_code 为主键） |
|
||
| ma_pay_channel | 支付通道表（merchant_id, merchant_app_id, method_id 关联） |
|
||
| ma_pay_order | 支付订单表（status: 0-PENDING, 1-SUCCESS, 2-FAIL, 3-CLOSED） |
|
||
| ma_pay_callback_log | 支付回调日志表 |
|
||
| ma_notify_task | 商户通知任务表（order_id, retry_cnt, next_retry_at） |
|
||
| ma_system_config | 系统配置表 |
|
||
| ma_admin | 管理员表 |
|
||
|
||
### 3.3 前端目录结构
|
||
|
||
```
|
||
resource/mpay_v2_admin/
|
||
├── src/
|
||
│ ├── api/
|
||
│ ├── components/
|
||
│ ├── layout/
|
||
│ ├── router/
|
||
│ ├── store/
|
||
│ ├── views/
|
||
│ │ ├── login/
|
||
│ │ ├── home/
|
||
│ │ ├── finance/
|
||
│ │ ├── channel/
|
||
│ │ ├── analysis/
|
||
│ │ └── system/
|
||
│ ├── App.vue
|
||
│ └── main.ts
|
||
├── package.json
|
||
└── vite.config.ts
|
||
```
|
||
|
||
## 4. 核心功能模块
|
||
|
||
### 4.1 支付业务流程约定
|
||
|
||
1. **订单创建**：`PayOrderService::createOrder`，支持幂等（merchant_id + merchant_app_id + mch_order_no 唯一）
|
||
2. **通道路由**：`ChannelRouterService::chooseChannel(merchantId, merchantAppId, methodId)` 按第一个可用通道
|
||
3. **统一下单**：`PayService::unifiedPay` → 创建订单 → 选通道 → 实例化插件 → 调用 `unifiedOrder`
|
||
4. **商户通知**：`NotifyService::createNotifyTask`，`notify_url` 从订单 `extra['notify_url']` 获取
|
||
5. **通知重试**：`NotifyMerchantJob` 定时拉取待重试任务，指数退避
|
||
|
||
### 4.2 支付插件接口
|
||
|
||
- `app/common/contracts/PayPluginInterface.php`
|
||
- `app/common/contracts/AbstractPayPlugin.php`
|
||
- 示例实现：`app/common/payment/LakalaPayment.php`
|
||
|
||
插件需实现：`getName`、`getSupportedMethods`、`getConfigSchema`、`getSupportedProducts`、`init`、`unifiedOrder`、`refund`、`verifyNotify` 等。
|
||
|
||
### 4.3 后端核心模块
|
||
|
||
| 模块 | 主要功能 | 文件位置 |
|
||
|------|----------|----------|
|
||
| 认证 | 管理员登录、验证码 | AuthController, AuthService |
|
||
| 管理员 | 获取管理员信息 | AdminController, AdminService, Admin 模型 |
|
||
| 菜单 | 获取路由菜单 | MenuController, MenuService |
|
||
| 系统 | 字典、配置管理 | SystemController, SystemConfigService |
|
||
| 通道管理 | 通道列表、详情、保存 | ChannelController, PaymentChannelRepository |
|
||
| 插件管理 | 插件列表、配置 Schema、产品列表 | PluginController, PluginService |
|
||
| 易支付 | submit.php/mapi.php/api.php | EpayController, EpayService |
|
||
|
||
### 4.4 前端核心模块
|
||
|
||
| 模块 | 主要功能 | 位置 |
|
||
|------|----------|------|
|
||
| 布局 | 系统整体布局 | src/layout/ |
|
||
| 认证 | 登录、权限控制 | src/views/login/ |
|
||
| 首页 | 数据概览 | src/views/home/ |
|
||
| 财务管理 | 结算、对账、发票 | src/views/finance/ |
|
||
| 渠道管理 | 通道配置、支付方式 | src/views/channel/ |
|
||
| 数据分析 | 交易分析、商户分析 | src/views/analysis/ |
|
||
| 系统设置 | 系统配置、字典管理 | src/views/system/ |
|
||
|
||
## 5. API 接口设计
|
||
|
||
### 5.1 管理后台（/adminapi）
|
||
|
||
| 路径 | 方法 | 控制器 | 功能 | 权限 |
|
||
|------|------|--------|------|------|
|
||
| /adminapi/captcha | GET | AuthController | 获取验证码 | 无 |
|
||
| /adminapi/login | POST | AuthController | 管理员登录 | 无 |
|
||
| /adminapi/user/getUserInfo | GET | AdminController | 获取管理员信息 | JWT |
|
||
| /adminapi/menu/getRouters | GET | MenuController | 获取路由菜单 | JWT |
|
||
| /adminapi/system/getDict[/{code}] | GET | SystemController | 获取字典 | JWT |
|
||
| /adminapi/system/base-config/tabs | GET | SystemController | 获取配置标签 | JWT |
|
||
| /adminapi/system/base-config/form/{tabKey} | GET | SystemController | 获取表单配置 | JWT |
|
||
| /adminapi/system/base-config/submit/{tabKey} | POST | SystemController | 提交配置 | JWT |
|
||
| /adminapi/channel/list | GET | ChannelController | 通道列表 | JWT |
|
||
| /adminapi/channel/detail | GET | ChannelController | 通道详情 | JWT |
|
||
| /adminapi/channel/save | POST | ChannelController | 保存通道 | JWT |
|
||
| /adminapi/channel/plugins | GET | PluginController | 插件列表 | JWT |
|
||
| /adminapi/channel/plugin/config-schema | GET | PluginController | 插件配置 Schema | JWT |
|
||
| /adminapi/channel/plugin/products | GET | PluginController | 插件产品列表 | JWT |
|
||
|
||
### 5.2 易支付接口（对外 API）
|
||
|
||
| 路径 | 方法 | 控制器 | 功能 | 说明 |
|
||
|------|------|--------|------|------|
|
||
| /submit.php | ANY | EpayController | 页面跳转支付 | 参数：pid, key, out_trade_no, money, name, type, notify_url 等 |
|
||
| /mapi.php | POST | EpayController | API 接口支付 | 返回 trade_no、payurl/qrcode/urlscheme |
|
||
| /api.php | GET | EpayController | 订单查询/退款 | act=order 查询，act=refund 退款 |
|
||
|
||
易支付约定：`pid` 映射为 `app_id`（商户应用标识），`key` 为 `app_secret`。
|
||
|
||
## 6. 命名与约定
|
||
|
||
### 6.1 模型与仓储命名
|
||
|
||
- 业务语义命名：`PaymentMethod`、`PaymentOrder`、`PaymentChannel` 等，不使用 `ma` 前缀
|
||
- 表名仍为 `ma_*`，通过模型 `$table` 映射
|
||
|
||
### 6.2 订单相关字段
|
||
|
||
- 系统订单号：`order_id`
|
||
- 商户订单号：`mch_order_no`
|
||
- 商户ID：`merchant_id`
|
||
- 商户应用ID：`merchant_app_id`
|
||
- 通道ID：`channel_id`
|
||
- 支付方式ID：`method_id`（关联 ma_pay_method.id）
|
||
|
||
### 6.3 商户应用 api_type
|
||
|
||
用于区分不同 API 的验签与通知方式：`openapi`、`epay`、`custom` 等。
|
||
|
||
## 7. 开发流程
|
||
|
||
### 7.1 后端开发
|
||
|
||
1. **环境**：PHP 8.1+，Composer，MySQL，Redis
|
||
2. **依赖**：`composer install`
|
||
3. **数据库**：执行 `database/mvp_payment_tables.sql`
|
||
4. **配置**：复制 `.env.example` 为 `.env`
|
||
5. **启动**：
|
||
- Linux：`php start.php start`
|
||
- Windows：`php windows.php start`
|
||
|
||
### 7.2 前端开发
|
||
|
||
1. **环境**：Node.js 18.12+，PNPM 8.7+
|
||
2. **依赖**：`pnpm install`
|
||
3. **开发**：`pnpm dev`
|
||
4. **构建**：`pnpm build:prod`
|
||
|
||
## 8. 相关文档
|
||
|
||
| 文件 | 说明 |
|
||
|------|------|
|
||
| doc/epay.md | 易支付接口说明 |
|
||
| doc/payment_flow.md | 支付流程说明 |
|
||
| doc/payment_system_implementation.md | 支付系统实现说明 |
|
||
| doc/validation.md | 验证规则说明 |
|
||
| database/mvp_payment_tables.sql | 支付系统表结构 |
|
||
|
||
## 9. 总结
|
||
|
||
MPAY V2 以支付业务为核心，采用 Webman + Vue 3 技术栈，后端分层清晰（Controller → Service → Repository → Model），支持支付插件扩展与易支付兼容。管理后台基于 JWT 认证，提供通道、插件、系统配置等管理能力；对外提供易支付标准接口（submit/mapi/api），便于第三方商户接入。
|