# 支付处理

<cite>
**本文引用的文件**
- [支付集成指南.md](file://docs/支付集成指南.md)
- [payment.controller.ts](file://server/src/modules/payment/payment.controller.ts)
- [payment.service.ts](file://server/src/modules/payment/payment.service.ts)
- [index.vue（支付确认）](file://my-uniapp-vue3/src/pages/payment-confirm/index.vue)
- [index.vue（支付结果）](file://my-uniapp-vue3/src/pages/payment-result/index.vue)
- [schema.prisma](file://server/prisma/schema.prisma)
- [security.ts](file://server/src/middleware/security.ts)
- [auth.ts](file://server/src/middleware/auth.ts)
- [errorHandler.ts](file://server/src/middleware/errorHandler.ts)
- [index.ts（数据库连接）](file://server/src/models/index.ts)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本技术文档面向“支付处理系统”，围绕订阅支付流程进行系统化说明，覆盖订单创建、支付发起、状态跟踪与结果通知；深入解释第三方支付网关（支付宝、微信支付）的SDK接入与回调处理机制；阐述支付安全策略（签名验证、防重放、数据加密）、状态管理（成功/失败/超时）、退款与异常处理，并提供API接口文档与集成指南。

## 项目结构
支付系统由“前端页面 + 后端控制器 + 支付服务 + 数据库模型 + 安全与认证中间件”构成，采用模块化组织，便于扩展与维护。

```mermaid
graph TB
subgraph "前端"
PC["支付确认页<br/>payment-confirm/index.vue"]
PR["支付结果页<br/>payment-result/index.vue"]
end
subgraph "后端"
C["支付控制器<br/>payment.controller.ts"]
S["支付服务<br/>payment.service.ts"]
M["安全中间件<br/>security.ts"]
A["认证中间件<br/>auth.ts"]
E["错误处理中间件<br/>errorHandler.ts"]
D["Prisma模型<br/>schema.prisma"]
DB["数据库连接<br/>models/index.ts"]
end
PC --> C
PR --> C
C --> S
S --> D
D --> DB
C --> M
C --> A
C --> E
```

图示来源
- [payment.controller.ts:1-258](file://server/src/modules/payment/payment.controller.ts#L1-L258)
- [payment.service.ts:1-578](file://server/src/modules/payment/payment.service.ts#L1-L578)
- [schema.prisma:40-61](file://server/prisma/schema.prisma#L40-L61)
- [security.ts:1-154](file://server/src/middleware/security.ts#L1-L154)
- [auth.ts:1-81](file://server/src/middleware/auth.ts#L1-L81)
- [errorHandler.ts:1-67](file://server/src/middleware/errorHandler.ts#L1-L67)
- [index.ts（数据库连接）:1-15](file://server/src/models/index.ts#L1-L15)

章节来源
- [payment.controller.ts:1-258](file://server/src/modules/payment/payment.controller.ts#L1-L258)
- [payment.service.ts:1-578](file://server/src/modules/payment/payment.service.ts#L1-L578)
- [schema.prisma:40-61](file://server/prisma/schema.prisma#L40-L61)

## 核心组件
- 支付控制器：负责路由注册、参数校验、调用支付服务、返回统一格式响应。
- 支付服务：封装订单创建、支付渠道生成、回调处理、订阅激活、Token配额初始化等业务逻辑。
- 前端页面：支付确认页用于选择支付方式并创建订单；支付结果页展示支付状态与引导操作。
- 数据库模型：包含订单、订阅计划、订阅记录、Token余额与使用记录等。
- 安全与认证：XSS/SQL注入防护、JWT认证、统一错误处理。

章节来源
- [payment.controller.ts:1-258](file://server/src/modules/payment/payment.controller.ts#L1-L258)
- [payment.service.ts:1-578](file://server/src/modules/payment/payment.service.ts#L1-L578)
- [index.vue（支付确认）:1-433](file://my-uniapp-vue3/src/pages/payment-confirm/index.vue#L1-L433)
- [index.vue（支付结果）:1-322](file://my-uniapp-vue3/src/pages/payment-result/index.vue#L1-L322)
- [schema.prisma:252-330](file://server/prisma/schema.prisma#L252-L330)
- [security.ts:1-154](file://server/src/middleware/security.ts#L1-L154)
- [auth.ts:1-81](file://server/src/middleware/auth.ts#L1-L81)
- [errorHandler.ts:1-67](file://server/src/middleware/errorHandler.ts#L1-L67)

## 架构总览
支付系统采用“控制器-服务-模型”的分层架构，结合第三方支付网关的异步回调实现可靠的状态同步。

```mermaid
sequenceDiagram
participant U as "用户"
participant F as "前端页面"
participant C as "支付控制器"
participant S as "支付服务"
participant G as "支付网关"
participant DB as "数据库"
U->>F : 选择套餐并点击支付
F->>C : POST /api/payment/create
C->>S : createPaymentOrder(userId, planId, method)
S->>G : 发起支付生成支付链接/二维码
G-->>S : 返回支付凭证
S->>DB : 写入订单记录
S-->>C : 返回订单信息
C-->>F : 返回支付URL/二维码
F->>G : 跳转/扫码支付
G-->>C : 异步回调verifyAlipaySign/微信回调
C->>S : handlePaymentCallback(orderNo, paymentId, status)
S->>DB : 更新订单状态/激活订阅/初始化Token
C-->>G : 返回成功/失败
```

图示来源
- [payment.controller.ts:10-95](file://server/src/modules/payment/payment.controller.ts#L10-L95)
- [payment.service.ts:122-406](file://server/src/modules/payment/payment.service.ts#L122-L406)
- [schema.prisma:40-61](file://server/prisma/schema.prisma#L40-L61)

## 详细组件分析

### 支付控制器（payment.controller.ts）
- 路由职责
  - 创建订单：/api/payment/create（需要认证）
  - 模拟支付：/api/payment/mock（仅开发环境）
  - 支付宝异步通知：/api/payment/alipay/notify
  - 支付宝同步返回：/api/payment/alipay/return
  - 微信支付回调：/api/payment/wechat/notify
  - 微信订单查询：/api/payment/wechat/query/:orderNo
  - 订单列表：/api/payment/orders
  - 订单详情：/api/payment/orders/:orderNo
  - 支付宝扫码：/api/payment/alipay/qrcode
- 关键点
  - 统一参数校验与错误处理
  - 支付宝回调进行签名验证后再处理
  - 微信回调按交易状态分别处理成功/失败

章节来源
- [payment.controller.ts:1-258](file://server/src/modules/payment/payment.controller.ts#L1-L258)

### 支付服务（payment.service.ts）
- 订单生命周期
  - 生成订单号、查询套餐、创建订单记录
  - 根据支付方式生成支付链接或二维码
  - 处理回调：幂等判断、更新订单状态、激活订阅、初始化Token余额
- 支付渠道
  - 支付宝：沙箱/生产环境自动切换，支持H5跳转与当面付二维码
  - 微信：NATIVE支付生成二维码，提供查询接口
- 安全与容错
  - SDK懒加载，避免ESM兼容问题
  - 未配置时返回模拟链接，保证开发可用性
  - 对微信支付返回状态进行严格校验

```mermaid
flowchart TD
Start(["进入 handlePaymentCallback"]) --> FindOrder["查询订单是否存在"]
FindOrder --> Exists{"订单存在？"}
Exists --> |否| ThrowErr["抛出错误：订单不存在"]
Exists --> |是| Paid{"订单已支付？"}
Paid --> |是| ReturnOk["返回：订单已支付"]
Paid --> |否| Status{"回调状态"}
Status --> |失败| UpdateFail["更新订单为失败"]
Status --> |成功| UpdatePaid["更新订单为成功<br/>写入支付流水号/时间"]
UpdatePaid --> Activate["激活订阅/初始化Token"]
Activate --> Done(["结束"])
UpdateFail --> Done
ThrowErr --> Done
```

图示来源
- [payment.service.ts:359-406](file://server/src/modules/payment/payment.service.ts#L359-L406)

章节来源
- [payment.service.ts:1-578](file://server/src/modules/payment/payment.service.ts#L1-L578)

### 前端页面（支付确认与结果）
- 支付确认页
  - 展示订单信息与应付金额
  - 选择支付方式（支付宝/微信）
  - 创建订单并根据支付方式跳转或显示二维码
  - 开发环境提供模拟支付入口
- 支付结果页
  - 展示支付成功/失败/待支付/未知状态
  - 从URL参数解析支付宝同步返回状态

章节来源
- [index.vue（支付确认）:1-433](file://my-uniapp-vue3/src/pages/payment-confirm/index.vue#L1-L433)
- [index.vue（支付结果）:1-322](file://my-uniapp-vue3/src/pages/payment-result/index.vue#L1-L322)

### 数据库模型（Prisma）
- 订单（Order）：包含用户、订单号、金额、状态、支付方式、支付流水号、支付时间等
- 订阅计划（SubscriptionPlan）：套餐级别、价格、Token配额、功能开关等
- 订阅（Subscription）：用户订阅记录、有效期、状态、自动续费
- Token余额（TokenBalance）：月度/年度配额、使用量、重置时间
- Token使用（TokenUsage）：使用类型、数量、内容长度、关联订单

```mermaid
erDiagram
USER ||--o{ ORDER : "拥有"
USER ||--o{ SUBSCRIPTION : "拥有"
USER ||--o{ TOKEN_BALANCE : "唯一拥有"
USER ||--o{ TOKEN_USAGE : "产生"
SUBSCRIPTION_PLAN ||--o{ ORDER : "被购买"
SUBSCRIPTION_PLAN ||--o{ SUBSCRIPTION : "定义"
ORDER ||--o{ TOKEN_USAGE : "产生使用记录"
```

图示来源
- [schema.prisma:40-61](file://server/prisma/schema.prisma#L40-L61)
- [schema.prisma:252-330](file://server/prisma/schema.prisma#L252-L330)

章节来源
- [schema.prisma:40-61](file://server/prisma/schema.prisma#L40-L61)
- [schema.prisma:252-330](file://server/prisma/schema.prisma#L252-L330)

### 安全与认证
- 安全中间件
  - XSS防护：过滤请求体与查询参数，设置安全响应头
  - SQL注入检测：对请求参数进行模式匹配检测
  - 敏感数据脱敏：对响应中的敏感字段进行脱敏
- 认证中间件
  - JWT校验，支持可选认证与开发环境豁免
- 错误处理
  - 统一错误包装与响应格式，开发环境返回堆栈

章节来源
- [security.ts:1-154](file://server/src/middleware/security.ts#L1-L154)
- [auth.ts:1-81](file://server/src/middleware/auth.ts#L1-L81)
- [errorHandler.ts:1-67](file://server/src/middleware/errorHandler.ts#L1-L67)

## 依赖分析
- 控制器依赖服务与中间件，服务依赖Prisma模型与支付SDK，前端依赖控制器API。
- 支付SDK懒加载避免ESM兼容问题；微信支付通过本地证书文件与动态公钥导出适配dotenv限制。
- 数据库连接通过PrismaClient统一管理。

```mermaid
graph LR
PC["payment.controller.ts"] --> PS["payment.service.ts"]
PS --> PRISMA["schema.prisma"]
PS --> SDK["支付SDK(懒加载)"]
PC --> SEC["security.ts"]
PC --> AUTH["auth.ts"]
PC --> ERR["errorHandler.ts"]
PRISMA --> DB["models/index.ts"]
```

图示来源
- [payment.controller.ts:1-258](file://server/src/modules/payment/payment.controller.ts#L1-L258)
- [payment.service.ts:1-578](file://server/src/modules/payment/payment.service.ts#L1-L578)
- [schema.prisma:40-61](file://server/prisma/schema.prisma#L40-L61)
- [security.ts:1-154](file://server/src/middleware/security.ts#L1-L154)
- [auth.ts:1-81](file://server/src/middleware/auth.ts#L1-L81)
- [errorHandler.ts:1-67](file://server/src/middleware/errorHandler.ts#L1-L67)
- [index.ts（数据库连接）:1-15](file://server/src/models/index.ts#L1-L15)

章节来源
- [payment.controller.ts:1-258](file://server/src/modules/payment/payment.controller.ts#L1-L258)
- [payment.service.ts:1-578](file://server/src/modules/payment/payment.service.ts#L1-L578)
- [schema.prisma:40-61](file://server/prisma/schema.prisma#L40-L61)

## 性能考虑
- 支付SDK懒加载：仅在首次使用时加载，减少启动开销。
- 微信支付证书与公钥导出：避免dotenv多行PEM解析问题，提升稳定性。
- 订单状态幂等处理：回调重复触发不会重复更新状态。
- 前端轮询策略：结果页对订单状态进行定时轮询，避免长连接占用。

## 故障排查指南
- 支付宝回调签名失败
  - 检查APP ID、私钥、公钥配置是否正确
  - 确认回调URL与沙箱/生产环境匹配
- 微信支付不可用
  - 检查商户号、APIv3密钥、证书序列号与私钥文件
  - 查看返回状态码与错误信息，优先解决证书/密钥问题
- 订单状态异常
  - 核对回调参数与订单号一致性
  - 检查handlePaymentCallback是否重复执行
- 前端无法跳转/二维码不显示
  - 确认创建订单返回的paymentUrl/qrcode字段
  - 开发环境模拟支付仅限非H5端弹窗确认

章节来源
- [payment.controller.ts:58-95](file://server/src/modules/payment/payment.controller.ts#L58-L95)
- [payment.service.ts:246-295](file://server/src/modules/payment/payment.service.ts#L246-L295)
- [index.vue（支付确认）:113-200](file://my-uniapp-vue3/src/pages/payment-confirm/index.vue#L113-L200)

## 结论
该支付系统以清晰的分层架构与完善的第三方网关对接实现了稳定可靠的订阅支付能力。通过严格的签名验证、幂等处理与安全中间件，保障了支付流程的安全与稳定。建议后续完善退款流程与自动续费机制，持续优化用户体验与系统健壮性。

## 附录

### API 接口文档
- 创建支付订单
  - 方法：POST
  - 路径：/api/payment/create
  - 请求体：{ planId: number, paymentMethod: 'alipay' | 'wechat' | 'mock', returnUrl?: string }
  - 响应：{ code: number, message: string, data: 订单信息 }
- 模拟支付（开发环境）
  - 方法：POST
  - 路径：/api/payment/mock
  - 请求体：{ orderNo: string }
  - 响应：{ code: number, message: string, data: { success: boolean, message: string } }
- 支付宝异步通知
  - 方法：POST
  - 路径：/api/payment/alipay/notify
  - 请求体：回调参数（含签名）
  - 响应：'success' 或 'fail'
- 支付宝同步返回
  - 方法：GET
  - 路径：/api/payment/alipay/return
  - 查询参数：回调参数（含签名）
  - 响应：重定向至支付结果页
- 微信支付回调
  - 方法：POST
  - 路径：/api/payment/wechat/notify
  - 请求体：回调XML
  - 响应：{ code: 'SUCCESS'|'FAIL', message: string }
- 查询微信订单
  - 方法：GET
  - 路径：/api/payment/wechat/query/:orderNo
  - 响应：{ code: number, message: string, data: 查询结果 }
- 订单列表
  - 方法：GET
  - 路径：/api/payment/orders?page=1&pageSize=20
  - 响应：{ code: number, message: string, data: { list, total, page, pageSize, totalPages } }
- 订单详情
  - 方法：GET
  - 路径：/api/payment/orders/:orderNo
  - 响应：{ code: number, message: string, data: 订单详情 }
- 支付宝扫码
  - 方法：POST
  - 路径：/api/payment/alipay/qrcode
  - 请求体：{ planId: number }
  - 响应：{ code: number, message: string, data: { orderNo, amount, planName, qrcode } }

章节来源
- [payment.controller.ts:10-203](file://server/src/modules/payment/payment.controller.ts#L10-L203)

### 第三方支付集成指南（摘要）
- 支付宝
  - 配置APP ID、私钥、公钥与回调URL
  - 使用沙箱/生产自动切换
  - H5跳转与当面付二维码两种模式
- 微信支付
  - 配置商户号、APIv3密钥、证书序列号与私钥文件
  - NATIVE支付生成二维码
  - 提供订单查询接口

章节来源
- [支付集成指南.md:28-210](file://docs/支付集成指南.md#L28-L210)