docs: 支付模块开发文档 + git 域名更新

- 新增 backend/design/支付模块架构概览.md - 新增 backend/design/支付模块数据库设计.md (21张表 DDL) - 新增 backend/design/支付模块接口设计.md - git.dev.vifo.cc → git.vifo.cc 全局替换
2026-06-09 01:54:20 +08:00
parent 1324a52049
commit 7b2f3d77ca
10 changed files with 1308 additions and 34 deletions
@@ -0,0 +1,252 @@
+# 支付模块接口设计
+
+> **来源**: `~/rui/支付模块架构设计.md` v1.0
+> **创建日期**: 2026-06-08
+> **模块**: rui-payment
+
+---
+
+## 一、接口分层
+
+| 层级 | 路径前缀 | 认证 | 说明 |
+|------|---------|------|------|
+| 对外接口 | `/payment/open/**` | 需认证 | 商户/业务系统调用 |
+| 对外入口 | `/payment/entry/**` | 免认证 | 收银台、扫码支付 |
+| 第三方回调 | `/payment/notify/**` | 免认证 | 支付/退款异步通知 |
+| 内部接口 | `/payment/inner/**` | @Inner | 微服务间调用 |
+
+---
+
+## 二、对外接口（需认证）
+
+### 2.1 支付交易 `/payment/open/trade`
+
+#### 统一下单 `POST /payment/open/trade/pay`
+
+```java
+// 请求
+{
+    "channel": "alipay",               // PayChannel 枚举
+    "payType": "app",                   // PayType 枚举
+    "merchantOrderNo": "BIZ2026060801", // 业务订单号
+    "subject": "商品标题",
+    "body": "商品描述",
+    "amount": 100.00,                   // BigDecimal，元
+    "currency": "CNY",
+    "notifyUrl": "https://xxx/notify",
+    "returnUrl": "https://xxx/return",
+    "clientIp": "127.0.0.1",
+    "userId": "oXXXXXXXX"               // 微信 JSAPI 需要 openid
+}
+
+// 响应
+{
+    "code": 200,
+    "data": {
+        "success": true,
+        "channelOrderNo": null,
+        "payParams": {                   // 支付宝 APP
+            "orderInfo": "alipay_sdk=..."
+        },
+        // 或 "payUrl": "<form>...</form>",   // 支付宝 H5/PC
+        // 或 "payQrCode": "weixin://...",     // 微信 Native
+        // 或 "payParams": {"prepayId": "..."} // 微信 JSAPI
+    }
+}
+```
+
+#### 统一执行入口 `POST /payment/open/trade/execute`
+
+支持所有渠道和动作的通用入口。
+
+```java
+// 请求
+{
+    "channel": "alipay",
+    "action": "query",
+    "merchantOrderNo": "PAY20260608001"
+}
+
+// 响应 — 查询示例
+{
+    "code": 200,
+    "data": {
+        "success": true,
+        "channelOrderNo": "20260608...",
+        "payParams": {
+            "tradeStatus": "TRADE_SUCCESS",
+            "totalAmount": "100.00"
+        }
+    }
+}
+```
+
+> 详细的 PayRequest/PayResponse 字段说明和每个 Action 的请求/返回示例见 `rui-payment-provider/API.md`。
+
+### 2.2 退款 `/payment/open/refund`
+
+| 接口 | 方法 | 说明 |
+|------|------|------|
+| `/payment/open/refund/apply` | POST | 申请退款 |
+| `/payment/open/refund/{refundNo}` | GET | 查询退款单 |
+
+#### 申请退款 `POST /payment/open/refund/apply`
+
+```java
+// 请求 PayRefundApplyRequest
+{
+    "orderNo": "PAY20260608001",
+    "refundAmount": 50.00,
+    "refundReason": "用户申请退款",
+    "notifyUrl": "https://xxx/refund_notify"
+}
+
+// 响应 PayRefundVO
+{
+    "code": 200,
+    "data": {
+        "refundNo": "REF20260608001",
+        "orderNo": "PAY20260608001",
+        "refundAmount": 50.00,
+        "refundStatus": 0,                // 0:退款中 1:退款成功 2:退款失败
+        "channelRefundNo": null
+    }
+}
+```
+
+### 2.3 分账 `/payment/open/split`
+
+| 接口 | 方法 | 说明 |
+|------|------|------|
+| `/payment/open/split/create` | POST | 创建分账订单 |
+| `/payment/open/split/{splitNo}` | GET | 查询分账订单 |
+| `/payment/open/split/execute/{splitNo}` | POST | 执行分账（手动触发） |
+| `/payment/open/split/return/{splitNo}` | POST | 回退分账 |
+
+#### 创建分账订单 `POST /payment/open/split/create`
+
+```java
+// 请求 SplitOrderCreateRequest
+{
+    "orderNo": "PAY20260608001",
+    "splitReceivers": [
+        {
+            "receiverId": 1,
+            "receiverType": 1,
+            "receiverName": "商户A",
+            "amount": 30.00,
+            "rate": 0.30
+        }
+    ]
+}
+```
+
+### 2.4 商户进件 `/payment/open/merchant`
+
+| 接口 | 方法 | 说明 |
+|------|------|------|
+| `/payment/open/merchant/apply` | POST | 提交商户入驻申请 |
+| `/payment/open/merchant/{merchantNo}` | GET | 查询商户信息 |
+| `/payment/open/merchant/{merchantNo}` | PUT | 更新商户信息 |
+| `/payment/open/merchant/qualification/upload` | POST | 提交资质材料 |
+| `/payment/open/merchant/qualification/{merchantNo}` | GET | 查询资质列表 |
+| `/payment/open/merchant/audit/{merchantNo}` | GET | 查询审核记录 |
+| `/payment/open/merchant/channel/{merchantNo}` | GET | 查询渠道配置 |
+| `/payment/open/merchant/channel/apply` | POST | 申请渠道开通 |
+| `/payment/open/merchant/settle/{merchantNo}` | GET | 查询结算配置 |
+| `/payment/open/merchant/settle/{merchantNo}` | PUT | 更新结算配置 |
+
+---
+
+## 三、对外入口（免认证）
+
+### `/payment/entry`
+
+| 接口 | 方法 | 说明 |
+|------|------|------|
+| `/payment/entry/cashier/{orderNo}` | GET | 收银台页面（H5） |
+| `/payment/entry/scan` | POST | 扫码支付 |
+
+---
+
+## 四、第三方回调（免认证）
+
+### `/payment/notify`
+
+| 接口 | 方法 | 说明 |
+|------|------|------|
+| `/payment/notify/alipay` | POST | 支付宝支付回调 |
+| `/payment/notify/wechat_pay` | POST | 微信支付回调（JSON body） |
+| `/payment/notify/unionpay` | POST | 银联支付回调 |
+| `/payment/notify/alipay/refund` | POST | 支付宝退款回调 |
+| `/payment/notify/wechat_pay/refund` | POST | 微信退款回调（JSON body） |
+
+#### 支付宝回调
+
+```
+POST /payment/notify/alipay
+Content-Type: application/x-www-form-urlencoded
+
+out_trade_no=PAY20260608001&trade_no=20260608...&trade_status=TRADE_SUCCESS&total_amount=100.00&...
+```
+
+- 返回纯文本 `"success"` 表示成功，`"fail"` 表示失败
+
+#### 微信回调
+
+```
+POST /payment/notify/wechat_pay
+Content-Type: application/json
+
+{"id":"xxx","create_time":"...","resource_type":"encrypt-resource","event_type":"TRANSACTION.SUCCESS","resource":{...}}
+```
+
+- 请求头携带 `Wechatpay-Serial`, `Wechatpay-Nonce`, `Wechatpay-Signature`, `Wechatpay-Timestamp`
+- 返回 JSON `{"code":"SUCCESS","message":"成功"}`
+
+---
+
+## 五、内部接口（@Inner）
+
+### `/payment/inner`
+
+| 接口 | 方法 | 说明 |
+|------|------|------|
+| `/payment/inner/order/status/{orderNo}` | GET | 查询支付状态 |
+| `/payment/inner/order/biz/{bizOrderNo}` | GET | 根据业务订单号查询 |
+| `/payment/inner/order/create` | POST | 创建支付订单（内部调用） |
+
+---
+
+## 六、管理后台接口
+
+### 6.1 支付渠道管理 `/payment/admin/channel`
+
+| 接口 | 方法 | 说明 |
+|------|------|------|
+| `/payment/admin/channel/list` | GET | 渠道列表 |
+| `/payment/admin/channel/{id}` | GET | 渠道详情 |
+| `/payment/admin/channel` | POST | 新增渠道 |
+| `/payment/admin/channel/{id}` | PUT | 修改渠道 |
+| `/payment/admin/channel/{id}/enable` | PUT | 启用渠道 |
+| `/payment/admin/channel/{id}/disable` | PUT | 停用渠道 |
+
+### 6.2 代理商管理 `/payment/admin/agent`
+
+| 接口 | 方法 | 说明 |
+|------|------|------|
+| `/payment/admin/agent/list` | GET | 代理商列表 |
+| `/payment/admin/agent/{id}` | GET | 代理商详情 |
+| `/payment/admin/agent` | POST | 新增代理商 |
+| `/payment/admin/agent/{id}` | PUT | 修改代理商 |
+| `/payment/admin/agent/{id}/commission` | GET | 佣金记录 |
+| `/payment/admin/agent/{id}/settlement` | GET | 结算记录 |
+
+### 6.3 结算管理 `/payment/admin/settle`
+
+| 接口 | 方法 | 说明 |
+|------|------|------|
+| `/payment/admin/settle/list` | GET | 结算单列表 |
+| `/payment/admin/settle/{id}` | GET | 结算单详情 |
+| `/payment/admin/settle/generate` | POST | 生成结算单 |
+| `/payment/admin/settle/{id}/confirm` | POST | 确认结算 |