xinyin025/mpay_v2_webman

Fork 0

mirror of https://gitee.com/technical-laohu/mpay_v2_webman.git synced 2026-03-24 11:54:26 +08:00

Files

技术老胡 9de902231f 更新数据库结构

2026-03-10 13:47:28 +08:00

14 KiB

Raw Permalink Blame History

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 支付业务流程约定

订单创建：PayOrderService::createOrder，支持幂等（merchant_id + merchant_app_id + mch_order_no 唯一）
通道路由：ChannelRouterService::chooseChannel(merchantId, merchantAppId, methodId) 按第一个可用通道
统一下单：PayService::unifiedPay → 创建订单 → 选通道 → 实例化插件 → 调用 unifiedOrder
商户通知：NotifyService::createNotifyTask，notify_url 从订单 extra['notify_url'] 获取
通知重试：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 后端开发

环境：PHP 8.1+，Composer，MySQL，Redis
依赖：composer install
数据库：执行 database/mvp_payment_tables.sql
配置：复制 .env.example 为 .env
启动：
- Linux：php start.php start
- Windows：php windows.php start

7.2 前端开发

环境：Node.js 18.12+，PNPM 8.7+
依赖：pnpm install
开发：pnpm dev
构建：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），便于第三方商户接入。

14 KiB Raw Permalink Blame History Unescape Escape