# PaymentCenter 支付中心

一个基于 Go + Gin 的统一支付网关系统，为商户提供下单、退款、查询、收银台等支付能力，底层对接微信支付、支付宝等第三方支付平台。

> 代码位置：后端接口位于 `app/`，收银台页面模板位于 `front/templates/`。

---

## 1. 技术栈

| 组件 | 选型 |
|------|------|
| 语言 | Go |
| Web 框架 | [Gin](https://github.com/gin-gonic/gin) |
| ORM | [xorm](https://xorm.io/) |
| 第三方支付 | [go-pay](https://github.com/go-pay/gopay) |
| JSON | [bytedance/sonic](https://github.com/bytedance/sonic) |
| 参数校验 | go-playground/validator.v9 |
| 缓存/分布式锁 | Redis（snow-core/redis） |
| 数据库 | MySQL |
| 加密算法 | RSA / SM2 / SM4 / AES / DES3 |

---

## 2. 目录结构

```
PaymentCenter/
├── app/
│   ├── constants/             # 常量定义（错误码、公共枚举、pojo）
│   │   ├── common/common.go   # 订单状态、支付渠道、路由前缀
│   │   └── errorcode/         # 错误码与中文消息
│   ├── http/
│   │   ├── routes/route.go    # 路由注册入口
│   │   ├── requestmapping/    # 路由→请求结构体映射
│   │   ├── middlewares/       # 中间件（CORS、鉴权、加解密、参数校验）
│   │   ├── controllers/
│   │   │   ├── base.go        # 公共：Success/Error/GenRequest/ApiRes
│   │   │   ├── front/         # C 端：支付 API、收银台、回调
│   │   │   └── backend/       # 管理后台
│   │   └── entities/          # 请求/响应结构体
│   ├── services/
│   │   ├── api_request_valid.go  # App 校验 & IP 白名单
│   │   ├── order.go              # 订单 CRUD & 状态检查
│   │   ├── pay_page.go           # 收银台渠道列表、订单状态检查
│   │   ├── apicrypt/             # RSA/SM2/SM4 加解密实现
│   │   └── thirdpay/             # 第三方支付业务封装
│   │       ├── pay.go            # 下单/退款/关闭主流程
│   │       ├── pay_page.go       # 收银台业务：V2 预下单、查询
│   │       ├── pay_query.go      # 三方查询
│   │       ├── do/               # 渠道策略层（PayCheck、Pay、PayWay 映射）
│   │       └── thirdpay_notify/  # 回调异步通知处理
│   ├── third/paymentService/     # go-pay 封装（微信/支付宝底层调用）
│   ├── models/                   # xorm 实体（orders、app、merchant、pay_channel…）
│   ├── data/                     # Repository 层（OrderRepo、PayChannelRepo 等）
│   ├── utils/                    # snowflake、JWT、HTTP client、useragent、DES
│   │   └── encrypt/              # AES、RSA、SM2、SM4
│   ├── caches/                   # 缓存
│   └── mq/                       # 消息队列
└── front/
    └── templates/
        ├── payPage.html          # 收银台主页面
        ├── payTemplateDefault.html # 渠道跳转模板
        ├── success.html          # 支付成功（JSAPI 场景）
        └── fail.html             # 支付失败
```

---

## 3. 架构分层与调用链

```
Gin 路由
   │
   ▼
Middleware（CORS → ValidateRequest / ValidatePayRequest → 加解密）
   │
   ▼
Controller（front/ 或 backend/）
   │
   ▼
services/（业务编排 + services/thirdpay/）
   │
   ▼
services/thirdpay/do/（PayCheck → Pay → PayWay 策略）
   │
   ▼
third/paymentService/（go-pay 底层调用）→ 微信 / 支付宝
   │
   ▼
data/（Repository）→ models/（xorm ORM）→ MySQL
```

- **控制器层**：只做 HTTP 层的事（绑定请求、调用 service、封装返回）
- **服务层**：核心业务（状态机、幂等、分布式锁、渠道路由）
- **Repository（data/）**：只做数据库 CRUD，不包含业务逻辑

---

## 4. C 端接口清单

> 接口前缀：`/pay/front/api/v1` 或 `/pay/front/api/v2`

| 方法 | 路由 | 中间件 | 功能 |
|------|------|--------|------|
| POST | `/notify/wx/:payChannelId` | - | 微信支付回调 |
| POST | `/notify/ali/:payChannelId` | - | 支付宝支付回调 |
| POST | `/pay/url` (V1) | ValidatePayRequest | 下单，同步返回支付 URL / JsInfo |
| POST | `/pay/url` (V2) | ValidatePayRequest | 预下单，仅创建订单，返回收银台 URL |
| POST | `/pay/refund` | ValidatePayRequest | 退款 |
| POST | `/pay/query` | ValidatePayRequest | 查询订单状态 |
| POST | `/pay/close` | ValidatePayRequest | 关闭订单 |
| GET | `/payPage?no={id}` | - | 收银台 HTML 页面入口 |
| POST | `/payPage/list` | ValidateRequest | 获取可用支付渠道列表 |
| GET | `/payPage/submit` | ValidateRequest | 获取支付跳转链接（渲染 payTemplateDefault.html）|
| POST | `/payPage/query` | - | 收银台页面轮询订单状态 |
| POST | `/ali/getOauth` | ValidateRequest | 支付宝小程序获取 openId |
| POST/GET | `/wx/*` | ValidateRequest | 微信授权 / openId / JSAPI / 小程序支付 |

- 路由定义参见 [app/http/routes/route.go](file:///e:/goproject/goproject/PaymentCenter/app/http/routes/route.go)
- 路由→结构体映射参见 [app/http/requestmapping/front.go](file:///e:/goproject/goproject/PaymentCenter/app/http/requestmapping/front.go)

---

## 5. 两种下单模式

### 5.1 模式一：V1 直接下单（`POST /pay/front/api/v1/pay/url`）

适用于商户自己管理收银台页面：

1. 商户构造请求 `RequestBody{ app_id, timestamp, data, key }`，加密后发起
2. 中间件 `ValidatePayRequest()`：查 App 配置 → 解密 → 反序列化为 `PayReqs`
3. 控制器调用 `thirdpay.ThirdPayInfoCheck()` → `thirdpay.ThirdPayUrl()`
4. 同步返回 `ApiResponse{ Order, Url, JsInfo }`

### 5.2 模式二：V2 预下单 + 收银台（推荐）

适用于商户跳转至我方收银台页面：

1. 商户调用 `POST /pay/front/api/v2/pay/url`
2. `PayUrlV2Service()`：
   - Redis 分布式锁（`payUrl:{out_trade_no}`，3 秒）
   - 检查商户是否有可用支付渠道
   - 按 `out_trade_no + app_id` 查询订单；不存在则新建订单（状态 WAITPAY）
   - 返回收银台 URL：`https://pay-host/pay/front/api/v1/payPage?no={orders.id}`
3. 商户将用户浏览器跳转到收银台
4. **收银台页面**（`payPage.html`）：
   - 读取 URL 参数 `no`（**订单自增 ID，不是 out_trade_no**）
   - `POST /payPage/list?id=xxx` 拉取渠道列表
   - 单渠道直接跳转 `/payPage/submit`，多渠道让用户选择
   - 选择后跳转到第三方支付页面
   - 支付完成后轮询 `/payPage/query`，成功后跳转到商户 `return_url`

---

## 6. 收银台页面流程

```
商户后台
  │ POST /v2/pay/url ─────┐
  │                        ▼
  │                 支付中心创建订单
  │                        │
  │                        ▼
  │           返回 payPage?no={orderId}
  │
  └── 用户浏览器 ───► GET payPage.html
                       │
                       ├── JS 调 POST /payPage/list 获取渠道
                       │
                       ├── GET /payPage/submit 获取跳转链接
                       │       └──► payTemplateDefault.html window.location
                       │
                       ├── POST /payPage/query 轮询订单状态
                       │
                       └── 支付成功 → 跳转 return_url
```

页面文件：

- [payPage.html](file:///e:/goproject/goproject/PaymentCenter/front/templates/payPage.html) — 收银台主页（含加载态、渠道选择、状态确认弹窗）
- [payTemplateDefault.html](file:///e:/goproject/goproject/PaymentCenter/front/templates/payTemplateDefault.html) — 第三方支付跳转
- [success.html](file:///e:/goproject/goproject/PaymentCenter/front/templates/success.html) — 微信 JSAPI 成功
- [fail.html](file:///e:/goproject/goproject/PaymentCenter/front/templates/fail.html) — 支付失败

前端注意：`payPage.html` 中的 `API_BASE_URL` 默认写死为 `http://localhost:7081`，部署时需要替换为生产地址。

---

## 7. 请求加解密体系

### 7.1 两个核心中间件

| 中间件 | 路由 | 说明 |
|--------|------|------|
| `ValidateRequest()` | 收银台列表、授权、小程序等 | 普通参数解析（form/json）+ validator 校验 + 可选日志 |
| `ValidatePayRequest()` | `/pay/url`、`/pay/refund`、`/pay/query`、`/pay/close` | 支付专用：`app_id` 查表 → 按 `key_type` 解密 data → 二次解析校验 |

中间件代码：[app/http/middlewares/base.go](file:///e:/goproject/goproject/PaymentCenter/app/http/middlewares/base.go)

### 7.2 支付请求结构（加密封装）

```
{
  "app_id":    123,        // 应用 ID，查表得 KeyType
  "timestamp": 1700000000, // 时间戳
  "data":      "...",      // 真实业务参数的密文（PayReqs JSON → 加密 → Base64）
  "key":       "..."       // 部分算法所需对称密钥密文
}
```

解密后 `data` 对应的业务结构，在 `requestmapping.FrontRequestMap` 中按路由映射。

### 7.3 加密算法（由 `app.key_type` 决定）

| 类型 | 实现文件 |
|------|---------|
| NO_CRYPT | 明文（不加密） |
| RSA | [services/apicrypt/rsa.go](file:///e:/goproject/goproject/PaymentCenter/app/services/apicrypt/rsa.go) |
| SM2 | [services/apicrypt/sm2.go](file:///e:/goproject/goproject/PaymentCenter/app/services/apicrypt/sm2.go) |
| SM4 | [services/apicrypt/sm4.go](file:///e:/goproject/goproject/PaymentCenter/app/services/apicrypt/sm4.go) |

注册处：[services/apicrypt/types.go](file:///e:/goproject/goproject/PaymentCenter/app/services/apicrypt/types.go) 中的 `ApiCryptMap`

### 7.4 响应加密

- 非生产环境：`controllers.Success/Error` 直接返回 `{ code, message, data }` JSON
- 生产环境（`config.GetConf().Env == "production"`）：整体 JSON 用 DES3 + Base64 加密后以纯文本返回
- 对应方法：`controllers.EncriptJson()`

---

## 8. 订单模型 & 状态机

### 8.1 Orders 表

字段定义：[app/models/ordersmodel/orders.go](file:///e:/goproject/goproject/PaymentCenter/app/models/ordersmodel/orders.go)

| 字段 | 类型 | 说明 |
|------|------|------|
| id | int64 | 主键，snowflake 生成 |
| merchant_id | int64 | 商户 |
| pay_channel_id | int64 | 支付渠道实例 |
| app_id | int64 | 应用 |
| out_trade_no | string(50) | 外部/商户订单号 |
| order_type | tinyint | 1=支付, 2=退款 |
| refund_order_id | int64 | 退款关联的原订单 |
| amount | int | 订单金额，单位：**分** |
| actual_amount | int | 实际金额，单位：**分** |
| payer_total | int | 付款方金额，单位：**分** |
| ext_json | string(1024) | 扩展 JSON |
| desc | string(100) | 商品描述 |
| status | tinyint | 订单状态（见下） |
| create_time / update_time | datetime | 自动维护 |

### 8.2 订单状态（`constants/common/common.go`）

| 常量 | 值 | 说明 |
|------|----|------|
| ORDER_STATUS_WAITPAY | 1 | 待支付（刚创建） |
| ORDER_STATUS_PAYING | 2 | 支付中（已调第三方下单） |
| ORDER_STATUS_PAYED | 3 | 支付成功 |
| ORDER_STATUS_FAILED | 4 | 支付失败 |
| ORDER_STATUS_CLOSE | 5 | 已关闭 |

### 8.3 状态流转

```
WAITPAY(1) ──► PAYING(2) ──┬──► PAYED(3)
  │                         │
  └─────► CLOSE(5)          └──► FAILED(4)
```

状态检查方法：`services.OrderStatusCheck(order)`，位置 [app/services/pay_page.go](file:///e:/goproject/goproject/PaymentCenter/app/services/pay_page.go#L89-L103)

---

## 9. 支付渠道体系

### 9.1 渠道类型枚举

定义在 `constants/common/common.go`：

| 常量 | 值 | 含义 |
|------|----|------|
| PAY_CHANNEL_WECHAT_JSAPI | 1 | 微信公众号 JSAPI |
| PAY_CHANNEL_WECHAT_H5 | 2 | 微信 H5 |
| PAY_CHANNEL_WECHAT_APP | 3 | 微信 APP |
| PAY_CHANNEL_WECHAT_NATIVE | 4 | 微信 Native 扫码 |
| PAY_CHANNEL_WECHAT_MINI | 5 | 微信小程序 |
| PAY_CHANNEL_ALIPAY_WEB | 6 | 支付宝网页/移动应用 |
| PAY_CHANNEL_ALIPAY_MINI | 7 | 支付宝小程序 |
| PAY_CHANNEL_ALIPAY_JSAPI | 8 | 支付宝 JSAPI |
| PAY_CHANNEL_ALIPAY_PC | 9 | 支付宝 PC 网站 |

### 9.2 策略映射（渠道 → 实现方法）

- 下单：`services/thirdpay/do/pay_way.go` 的 `PayWayList[channelType]`
- 退款：`services/thirdpay/do/refund_way.go` 的 `RefundWayList[channelType]`
- 底层统一入口：`third/paymentService/payment_service.go` 的 `PaymentService(ctx, req)`
  - 根据 `req.ChannelType` 路由到 `AliPayService()` 或 `WechatPayService()`

### 9.3 客户端环境 → 可用渠道

- 微信浏览器内 → JSAPI（需要 openId，收银台会自动先走授权）
- PC 浏览器 → 微信 Native、支付宝 PC
- 手机浏览器（非微信内）→ 微信 H5、支付宝 Web

实现：`services.PayPageChannelList()` + `services.ClientEnvCheck(ua)`

---

## 10. 新增功能的操作清单

### 10.1 新增一个 C 端 API

1. 在 `app/http/entities/front/` 定义 Request/Response 结构体
2. 在 `app/http/requestmapping/front.go` 的两个 map 中添加路由 → 结构体映射
3. 在 `app/http/routes/route.go` 注册路由，挂上合适的中间件
4. 在 `app/http/controllers/front/` 对应文件新增 handler（用 `controllers.GetRequest(c).(*front.XXX)` 取参数）
5. 在 `app/services/` 或 `app/services/thirdpay/` 实现业务逻辑

### 10.2 新增一个支付渠道

1. 在 `constants/common/common.go` 增加 `PAY_CHANNEL_XXX` 常量和 `PayChannelName`/`PayChannelList` 条目
2. 在 `services/thirdpay/do/pay_way.go` 的 `PayWayList` 注册实现方法
3. 在 `third/paymentService/wechat_service.go` 或 `ali_service.go` 增加对应分支
4. 若需区分客户端环境，更新 `OpenInPayChannelMap`

### 10.3 新增一个页面模板

1. 在 `front/templates/` 下新增 `.html`
2. 路由里通过 `c.HTML(http.StatusOK, "文件名.html", gin.H{...})` 渲染
3. `router.LoadHTMLGlob("./front/templates/*")` 已在 routes 中注册

### 10.4 新增一个错误码

1. 在 `constants/errorcode/error_code.go` 定义 const，并在 `ErrCodeMap` 注册中文消息
2. 使用：`controllers.Error(c, errorcode.XXX)` 或 `controllers.ApiRes(c, nil, code)`

### 10.5 新增数据模型 / Repository

1. 在 `app/models/xxxmodel/` 定义结构体（xorm tag + TableName + GetInstance 单例）
2. 在 `app/data/` 新增 `XxxRepo` 封装 xorm 操作（推荐配合 `builder.Cond` 拼装条件）
3. 在 `app/services/` 新增 `XxxFindOne` / `XxxList` 等服务方法

---

## 11. 编码规范与注意事项

- **金额单位**：全链路使用 **分**（int）；前端展示时 `/100` 转元；不得出现 float64 金额
- **订单 ID vs out_trade_no**：
  - `orders.id` = 雪花自增 ID（支付中心内部、收银台查询使用）
  - `out_trade_no` = 商户外部订单号（商户下单、查询使用）
  - **不要混用**
- **幂等性**：V2 下单通过 Redis 分布式锁（key=`payUrl:{out_trade_no}`，3 秒）+ 数据库 `(out_trade_no, app_id)` 唯一约束保证
- **中间件选型**：
  - 加密支付接口 → `ValidatePayRequest()`
  - 收银台、授权、小程序等 → `ValidateRequest()`
  - 回调接口 → 直接在 controller 解析（走第三方验签）
- **统一返回**：`controllers.Success/Error/ApiRes/HandCodeRes`，不要手写 JSON
- **错误码来源**：`constants/errorcode/error_code.go`，不要硬编码数字
- **日志**：`utils.Log(ctx, tag, ...)`；支付链路关键节点必须有日志
- **单元测试**：工具类、加解密、snowflake 等均有 `_test.go`，新工具函数建议配套

---

## 12. 关键文件速查

| 功能 | 文件 |
|------|------|
| 路由注册 | [app/http/routes/route.go](file:///e:/goproject/goproject/PaymentCenter/app/http/routes/route.go) |
| 路由→结构体映射 | [app/http/requestmapping/front.go](file:///e:/goproject/goproject/PaymentCenter/app/http/requestmapping/front.go) |
| 中间件 | [app/http/middlewares/base.go](file:///e:/goproject/goproject/PaymentCenter/app/http/middlewares/base.go) |
| 公共返回/参数解析 | [app/http/controllers/base.go](file:///e:/goproject/goproject/PaymentCenter/app/http/controllers/base.go) |
| 支付接口 controller | [app/http/controllers/front/api.go](file:///e:/goproject/goproject/PaymentCenter/app/http/controllers/front/api.go) |
| 收银台 controller | [app/http/controllers/front/pay_page.go](file:///e:/goproject/goproject/PaymentCenter/app/http/controllers/front/pay_page.go) |
| 回调/微信/支付宝 controller | [app/http/controllers/front/payment_controller.go](file:///e:/goproject/goproject/PaymentCenter/app/http/controllers/front/payment_controller.go) |
| 请求结构体 | [app/http/entities/front/pay.go](file:///e:/goproject/goproject/PaymentCenter/app/http/entities/front/pay.go) |
| 订单服务 | [app/services/order.go](file:///e:/goproject/goproject/PaymentCenter/app/services/order.go) |
| 收银台服务（渠道列表/状态检查） | [app/services/pay_page.go](file:///e:/goproject/goproject/PaymentCenter/app/services/pay_page.go) |
| App 校验 | [app/services/api_request_valid.go](file:///e:/goproject/goproject/PaymentCenter/app/services/api_request_valid.go) |
| 第三方支付主流程 | [app/services/thirdpay/pay.go](file:///e:/goproject/goproject/PaymentCenter/app/services/thirdpay/pay.go) |
| 收银台/V2 下单 | [app/services/thirdpay/pay_page.go](file:///e:/goproject/goproject/PaymentCenter/app/services/thirdpay/pay_page.go) |
| 加解密类型注册 | [app/services/apicrypt/types.go](file:///e:/goproject/goproject/PaymentCenter/app/services/apicrypt/types.go) |
| 错误码 | [app/constants/errorcode/error_code.go](file:///e:/goproject/goproject/PaymentCenter/app/constants/errorcode/error_code.go) |
| 公共常量 | [app/constants/common/common.go](file:///e:/goproject/goproject/PaymentCenter/app/constants/common/common.go) |
| Orders 模型 | [app/models/ordersmodel/orders.go](file:///e:/goproject/goproject/PaymentCenter/app/models/ordersmodel/orders.go) |
| Order Repository | [app/data/orders.go](file:///e:/goproject/goproject/PaymentCenter/app/data/orders.go) |
| 底层 go-pay 调用入口 | app/third/paymentService/payment_service.go |
| 收银台页面 | [front/templates/payPage.html](file:///e:/goproject/goproject/PaymentCenter/front/templates/payPage.html) |
| 跳转模板 | [front/templates/payTemplateDefault.html](file:///e:/goproject/goproject/PaymentCenter/front/templates/payTemplateDefault.html) |
| 雪花 ID 生成 | [app/utils/snowflake/snow_flake.go](file:///e:/goproject/goproject/PaymentCenter/app/utils/snowflake/snow_flake.go) |