From 7b2f3d77caa937cf2b6e23419ddc858d2fefa183 Mon Sep 17 00:00:00 2001 From: pigeon Date: Tue, 9 Jun 2026 01:54:20 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=94=AF=E4=BB=98=E6=A8=A1=E5=9D=97?= =?UTF-8?q?=E5=BC=80=E5=8F=91=E6=96=87=E6=A1=A3=20+=20git=20=E5=9F=9F?= =?UTF-8?q?=E5=90=8D=E6=9B=B4=E6=96=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增 backend/design/支付模块架构概览.md - 新增 backend/design/支付模块数据库设计.md (21张表 DDL) - 新增 backend/design/支付模块接口设计.md - git.dev.vifo.cc → git.vifo.cc 全局替换 --- README.md | 4 +- ai-skills/gitea-api.md | 24 +- ai-skills/issue-workflow.md | 10 +- backend/design/支付模块接口设计.md | 252 +++++++++ backend/design/支付模块数据库设计.md | 802 +++++++++++++++++++++++++++ backend/design/支付模块架构概览.md | 220 ++++++++ backend/guides/AI开发操作手册.md | 10 +- frontend/design/cashier-design.md | 6 +- gitea-runner-docker-compose.yml | 12 +- standards/API设计规范.md | 2 +- 10 files changed, 1308 insertions(+), 34 deletions(-) create mode 100644 backend/design/支付模块接口设计.md create mode 100644 backend/design/支付模块数据库设计.md create mode 100644 backend/design/支付模块架构概览.md diff --git a/README.md b/README.md index c845524..a28c42d 100644 --- a/README.md +++ b/README.md @@ -38,7 +38,7 @@ rui-docs/ ```bash # 添加 submodule -git submodule add ssh://git@git.dev.vifo.cc:222/rui/rui-docs.git docs +git submodule add ssh://git@git.vifo.cc:222/rui/rui-docs.git docs # 更新到最新 git submodule update --remote @@ -50,7 +50,7 @@ git submodule update --init --recursive ### 独立查看 ```bash -git clone ssh://git@git.dev.vifo.cc:222/rui/rui-docs.git +git clone ssh://git@git.vifo.cc:222/rui/rui-docs.git cd rui-docs ``` diff --git a/ai-skills/gitea-api.md b/ai-skills/gitea-api.md index d9cebab..578ab82 100644 --- a/ai-skills/gitea-api.md +++ b/ai-skills/gitea-api.md @@ -10,11 +10,11 @@ | 仓库 | Git 地址 | API Issue 端点 | |------|---------|---------------| -| rui-framework | `ssh://git@git.dev.vifo.cc:222/rui/rui-framework.git` | `https://git.dev.vifo.cc/api/v1/repos/rui/rui-framework/issues` | -| rui-cashier | `ssh://git@git.dev.vifo.cc:222/rui/rui-cashier.git` | `https://git.dev.vifo.cc/api/v1/repos/rui/rui-cashier/issues` | -| rui-payment | `ssh://git@git.dev.vifo.cc:222/rui/rui-payment.git` | `https://git.dev.vifo.cc/api/v1/repos/rui/rui-payment/issues` | -| rui-frontend | `ssh://git@git.dev.vifo.cc:222/rui/rui-frontend.git` | `https://git.dev.vifo.cc/api/v1/repos/rui/rui-frontend/issues` | -| rui-docs | `ssh://git@git.dev.vifo.cc:222/rui/rui-docs.git` | `https://git.dev.vifo.cc/api/v1/repos/rui/rui-docs/issues` | +| rui-framework | `ssh://git@git.vifo.cc:222/rui/rui-framework.git` | `https://git.vifo.cc/api/v1/repos/rui/rui-framework/issues` | +| rui-cashier | `ssh://git@git.vifo.cc:222/rui/rui-cashier.git` | `https://git.vifo.cc/api/v1/repos/rui/rui-cashier/issues` | +| rui-payment | `ssh://git@git.vifo.cc:222/rui/rui-payment.git` | `https://git.vifo.cc/api/v1/repos/rui/rui-payment/issues` | +| rui-frontend | `ssh://git@git.vifo.cc:222/rui/rui-frontend.git` | `https://git.vifo.cc/api/v1/repos/rui/rui-frontend/issues` | +| rui-docs | `ssh://git@git.vifo.cc:222/rui/rui-docs.git` | `https://git.vifo.cc/api/v1/repos/rui/rui-docs/issues` | ## 工单路由规则 @@ -68,7 +68,7 @@ curl -s -X POST \ -H "Authorization: token ${TOKEN}" \ -H "Content-Type: application/json" \ -d @/tmp/issue.json \ - "https://git.dev.vifo.cc/api/v1/repos/{owner}/{repo}/issues" + "https://git.vifo.cc/api/v1/repos/{owner}/{repo}/issues" ``` **示例**（提交到 rui-framework 仓库）： @@ -79,7 +79,7 @@ curl -s -X POST \ -H "Authorization: token ${TOKEN}" \ -H "Content-Type: application/json" \ -d @/tmp/issue.json \ - "https://git.dev.vifo.cc/api/v1/repos/rui/rui-framework/issues" + "https://git.vifo.cc/api/v1/repos/rui/rui-framework/issues" ``` **返回示例**： @@ -88,7 +88,7 @@ curl -s -X POST \ "id": 7, "number": 2, "title": "[API-REQ] 用户编辑接口密码字段处理优化", - "html_url": "https://git.dev.vifo.cc/rui/rui-framework/issues/2", + "html_url": "https://git.vifo.cc/rui/rui-framework/issues/2", "state": "open" } ``` @@ -98,7 +98,7 @@ curl -s -X POST \ ```bash TOKEN=$(cat ~/.config/gitea/token) curl -s -H "Authorization: token ${TOKEN}" \ - "https://git.dev.vifo.cc/api/v1/repos/{owner}/{repo}/issues/{id}" + "https://git.vifo.cc/api/v1/repos/{owner}/{repo}/issues/{id}" ``` ## 列出仓库所有 Issue @@ -106,7 +106,7 @@ curl -s -H "Authorization: token ${TOKEN}" \ ```bash TOKEN=$(cat ~/.config/gitea/token) curl -s -H "Authorization: token ${TOKEN}" \ - "https://git.dev.vifo.cc/api/v1/repos/{owner}/{repo}/issues?state=open" + "https://git.vifo.cc/api/v1/repos/{owner}/{repo}/issues?state=open" ``` ## 回复 Issue 评论 @@ -117,7 +117,7 @@ curl -s -X POST \ -H "Authorization: token ${TOKEN}" \ -H "Content-Type: application/json" \ -d '{"body": "✅ 已完成\n\n完成内容..."}' \ - "https://git.dev.vifo.cc/api/v1/repos/{owner}/{repo}/issues/{id}/comments" + "https://git.vifo.cc/api/v1/repos/{owner}/{repo}/issues/{id}/comments" ``` ## 关闭 Issue @@ -128,7 +128,7 @@ curl -s -X PATCH \ -H "Authorization: token ${TOKEN}" \ -H "Content-Type: application/json" \ -d '{"state": "closed"}' \ - "https://git.dev.vifo.cc/api/v1/repos/{owner}/{repo}/issues/{id}" + "https://git.vifo.cc/api/v1/repos/{owner}/{repo}/issues/{id}" ``` ## 常用端点 diff --git a/ai-skills/issue-workflow.md b/ai-skills/issue-workflow.md index 172a275..d2bd76c 100644 --- a/ai-skills/issue-workflow.md +++ b/ai-skills/issue-workflow.md @@ -8,14 +8,14 @@ ```bash TOKEN=$(cat ~/.config/gitea/token) curl -s -H "Authorization: token ${TOKEN}" \ - "https://git.dev.vifo.cc/api/v1/repos/{owner}/{repo}/issues/{id}" + "https://git.vifo.cc/api/v1/repos/{owner}/{repo}/issues/{id}" ``` 也可以列出当前仓库所有未关闭的工单： ```bash TOKEN=$(cat ~/.config/gitea/token) curl -s -H "Authorization: token ${TOKEN}" \ - "https://git.dev.vifo.cc/api/v1/repos/{owner}/{repo}/issues?state=open" + "https://git.vifo.cc/api/v1/repos/{owner}/{repo}/issues?state=open" ``` ### 2. 分析需求 @@ -55,7 +55,7 @@ curl -s -X POST \ -H "Authorization: token ${TOKEN}" \ -H "Content-Type: application/json" \ -d '{"body": "✅ 已完成\n\n完成内容..."}' \ - "https://git.dev.vifo.cc/api/v1/repos/{owner}/{repo}/issues/{id}/comments" + "https://git.vifo.cc/api/v1/repos/{owner}/{repo}/issues/{id}/comments" ``` ### 6. 关闭工单 @@ -66,7 +66,7 @@ curl -s -X PATCH \ -H "Authorization: token ${TOKEN}" \ -H "Content-Type: application/json" \ -d '{"state": "closed"}' \ - "https://git.dev.vifo.cc/api/v1/repos/{owner}/{repo}/issues/{id}" + "https://git.vifo.cc/api/v1/repos/{owner}/{repo}/issues/{id}" ``` ## 跨仓库提工单 @@ -91,7 +91,7 @@ curl -s -X POST \ -H "Authorization: token ${TOKEN}" \ -H "Content-Type: application/json" \ -d @/tmp/issue.json \ - "https://git.dev.vifo.cc/api/v1/repos/rui/rui-framework/issues" + "https://git.vifo.cc/api/v1/repos/rui/rui-framework/issues" ``` ## 提交规范 diff --git a/backend/design/支付模块接口设计.md b/backend/design/支付模块接口设计.md new file mode 100644 index 0000000..93b9def --- /dev/null +++ b/backend/design/支付模块接口设计.md @@ -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": "
...
", // 支付宝 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 | 确认结算 | diff --git a/backend/design/支付模块数据库设计.md b/backend/design/支付模块数据库设计.md new file mode 100644 index 0000000..d7fc140 --- /dev/null +++ b/backend/design/支付模块数据库设计.md @@ -0,0 +1,802 @@ +# 支付模块数据库设计 + +> **来源**: `~/rui/支付模块架构设计.md` v1.0 +> **创建日期**: 2026-06-08 +> **模块**: rui-payment +> **表数量**: 21 张 + +--- + +## ER 关系概览 + +``` +pay_order ──→ pay_record ──→ pay_channel_merchant + │ │ + ↓ ↓ +pay_refund pay_channel + +pay_merchant ──→ pay_merchant_qualification ──→ pay_merchant_audit + │ + ↓ +pay_merchant_channel ──→ pay_merchant_settle + +pay_split_order ──→ pay_split_detail ──→ pay_split_receiver + +pay_agent ──→ pay_agent_merchant ──→ pay_agent_commission ──→ pay_agent_settlement + +pay_account ──→ pay_account_record + │ + ↓ +pay_account_freeze + +pay_reconcile ──→ pay_reconcile_diff +``` + +--- + +### 3.1 支付核心表 + +#### 3.1.1 支付订单表 (pay_order) + +```sql +CREATE TABLE pay_order ( + id BIGINT NOT NULL COMMENT '主键ID', + tenant_id BIGINT NOT NULL DEFAULT 0 COMMENT '租户ID', + order_no VARCHAR(64) NOT NULL COMMENT '支付订单号（系统生成）', + biz_order_no VARCHAR(64) NOT NULL COMMENT '业务订单号（外部传入）', + biz_type TINYINT NOT NULL DEFAULT 1 COMMENT '业务类型 1:订单支付 2:充值 3:转账', + subject VARCHAR(256) NOT NULL COMMENT '订单标题', + body VARCHAR(500) DEFAULT NULL COMMENT '订单描述', + total_amount DECIMAL(19,4) NOT NULL COMMENT '订单总金额', + pay_amount DECIMAL(19,4) NOT NULL DEFAULT 0.0000 COMMENT '实际支付金额', + discount_amount DECIMAL(19,4) NOT NULL DEFAULT 0.0000 COMMENT '优惠金额', + fee_amount DECIMAL(19,4) NOT NULL DEFAULT 0.0000 COMMENT '手续费金额', + currency VARCHAR(10) NOT NULL DEFAULT 'CNY' COMMENT '币种', + payer_id BIGINT DEFAULT NULL COMMENT '付款人ID', + payer_type TINYINT NOT NULL DEFAULT 1 COMMENT '付款人类型 1:用户 2:商户', + payer_name VARCHAR(100) DEFAULT NULL COMMENT '付款人名称', + payee_id BIGINT NOT NULL COMMENT '收款人ID（商户ID）', + payee_type TINYINT NOT NULL DEFAULT 1 COMMENT '收款人类型 1:商户 2:平台', + payee_name VARCHAR(100) DEFAULT NULL COMMENT '收款人名称', + channel_id BIGINT DEFAULT NULL COMMENT '支付渠道ID', + channel_code VARCHAR(50) DEFAULT NULL COMMENT '支付渠道编码', + pay_status TINYINT NOT NULL DEFAULT 0 COMMENT '支付状态 0:待支付 1:支付中 2:支付成功 3:支付失败 4:已关闭 5:已退款', + pay_time DATETIME(3) DEFAULT NULL COMMENT '支付成功时间', + expire_time DATETIME(3) NOT NULL COMMENT '订单过期时间', + client_ip VARCHAR(128) DEFAULT NULL COMMENT '客户端IP', + device VARCHAR(100) DEFAULT NULL COMMENT '设备信息', + notify_url VARCHAR(500) DEFAULT NULL COMMENT '异步通知地址', + return_url VARCHAR(500) DEFAULT NULL COMMENT '同步跳转地址', + extra_params JSON DEFAULT NULL COMMENT '扩展参数（渠道特定参数）', + error_code VARCHAR(100) DEFAULT NULL COMMENT '错误码', + error_msg VARCHAR(500) DEFAULT NULL COMMENT '错误信息', + remark VARCHAR(500) DEFAULT NULL COMMENT '备注', + status TINYINT NOT NULL DEFAULT 1 COMMENT '状态 0:禁用 1:启用', + deleted TINYINT NOT NULL DEFAULT 0 COMMENT '逻辑删除 0:正常 1:删除', + created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间', + updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间', + PRIMARY KEY (id), + UNIQUE KEY uk_order_no (tenant_id, order_no), + UNIQUE KEY uk_biz_order_no (tenant_id, biz_order_no, biz_type), + INDEX idx_pay_status (pay_status), + INDEX idx_payee_id (payee_id), + INDEX idx_payer_id (payer_id), + INDEX idx_channel_id (channel_id), + INDEX idx_pay_time (pay_time), + INDEX idx_created_at (created_at), + INDEX idx_tenant_id (tenant_id) +) COMMENT='支付订单表'; +``` + +#### 3.1.2 支付流水表 (pay_record) + +```sql +CREATE TABLE pay_record ( + id BIGINT NOT NULL COMMENT '主键ID', + tenant_id BIGINT NOT NULL DEFAULT 0 COMMENT '租户ID', + record_no VARCHAR(64) NOT NULL COMMENT '流水号', + order_id BIGINT NOT NULL COMMENT '支付订单ID', + order_no VARCHAR(64) NOT NULL COMMENT '支付订单号', + channel_id BIGINT NOT NULL COMMENT '支付渠道ID', + channel_code VARCHAR(50) NOT NULL COMMENT '渠道编码', + channel_merchant_no VARCHAR(100) DEFAULT NULL COMMENT '渠道商户号', + channel_order_no VARCHAR(128) DEFAULT NULL COMMENT '渠道订单号', + pay_amount DECIMAL(19,4) NOT NULL COMMENT '支付金额', + fee_amount DECIMAL(19,4) NOT NULL DEFAULT 0.0000 COMMENT '手续费', + currency VARCHAR(10) NOT NULL DEFAULT 'CNY' COMMENT '币种', + pay_status TINYINT NOT NULL DEFAULT 0 COMMENT '支付状态 0:待支付 1:支付中 2:支付成功 3:支付失败 4:已关闭', + pay_time DATETIME(3) DEFAULT NULL COMMENT '支付成功时间', + payer_info JSON DEFAULT NULL COMMENT '付款人信息（openid、银行卡号等）', + notify_status TINYINT NOT NULL DEFAULT 0 COMMENT '通知状态 0:未通知 1:通知成功 2:通知失败', + notify_times INT NOT NULL DEFAULT 0 COMMENT '通知次数', + notify_last_time DATETIME(3) DEFAULT NULL COMMENT '最后通知时间', + error_code VARCHAR(100) DEFAULT NULL COMMENT '错误码', + error_msg VARCHAR(500) DEFAULT NULL COMMENT '错误信息', + remark VARCHAR(500) DEFAULT NULL COMMENT '备注', + status TINYINT NOT NULL DEFAULT 1 COMMENT '状态', + deleted TINYINT NOT NULL DEFAULT 0 COMMENT '逻辑删除', + created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间', + updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间', + PRIMARY KEY (id), + UNIQUE KEY uk_record_no (tenant_id, record_no), + UNIQUE KEY uk_channel_order (tenant_id, channel_id, channel_order_no), + INDEX idx_order_id (order_id), + INDEX idx_order_no (order_no), + INDEX idx_pay_status (pay_status), + INDEX idx_pay_time (pay_time), + INDEX idx_created_at (created_at), + INDEX idx_tenant_id (tenant_id) +) COMMENT='支付流水表'; +``` + +#### 3.1.3 退款单表 (pay_refund) + +```sql +CREATE TABLE pay_refund ( + id BIGINT NOT NULL COMMENT '主键ID', + tenant_id BIGINT NOT NULL DEFAULT 0 COMMENT '租户ID', + refund_no VARCHAR(64) NOT NULL COMMENT '退款单号', + order_id BIGINT NOT NULL COMMENT '支付订单ID', + order_no VARCHAR(64) NOT NULL COMMENT '支付订单号', + record_id BIGINT NOT NULL COMMENT '支付流水ID', + record_no VARCHAR(64) NOT NULL COMMENT '支付流水号', + channel_id BIGINT NOT NULL COMMENT '支付渠道ID', + channel_refund_no VARCHAR(128) DEFAULT NULL COMMENT '渠道退款单号', + refund_amount DECIMAL(19,4) NOT NULL COMMENT '退款金额', + total_amount DECIMAL(19,4) NOT NULL COMMENT '订单总金额', + refund_status TINYINT NOT NULL DEFAULT 0 COMMENT '退款状态 0:待退款 1:退款中 2:退款成功 3:退款失败', + refund_time DATETIME(3) DEFAULT NULL COMMENT '退款成功时间', + refund_reason VARCHAR(500) DEFAULT NULL COMMENT '退款原因', + operator_id BIGINT DEFAULT NULL COMMENT '操作人ID', + operator_name VARCHAR(100) DEFAULT NULL COMMENT '操作人名称', + notify_status TINYINT NOT NULL DEFAULT 0 COMMENT '通知状态', + error_code VARCHAR(100) DEFAULT NULL COMMENT '错误码', + error_msg VARCHAR(500) DEFAULT NULL COMMENT '错误信息', + remark VARCHAR(500) DEFAULT NULL COMMENT '备注', + status TINYINT NOT NULL DEFAULT 1 COMMENT '状态', + deleted TINYINT NOT NULL DEFAULT 0 COMMENT '逻辑删除', + created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间', + updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间', + PRIMARY KEY (id), + UNIQUE KEY uk_refund_no (tenant_id, refund_no), + INDEX idx_order_id (order_id), + INDEX idx_order_no (order_no), + INDEX idx_refund_status (refund_status), + INDEX idx_created_at (created_at), + INDEX idx_tenant_id (tenant_id) +) COMMENT='退款单表'; +``` + +### 3.2 支付渠道表 + +#### 3.2.1 支付渠道表 (pay_channel) + +```sql +CREATE TABLE pay_channel ( + id BIGINT NOT NULL COMMENT '主键ID', + tenant_id BIGINT NOT NULL DEFAULT 0 COMMENT '租户ID', + channel_code VARCHAR(50) NOT NULL COMMENT '渠道编码 如:alipay_app,wx_jsapi', + channel_name VARCHAR(100) NOT NULL COMMENT '渠道名称', + channel_type TINYINT NOT NULL DEFAULT 1 COMMENT '渠道类型 1:支付宝 2:微信支付 3:银联 4:其他', + payment_type TINYINT NOT NULL DEFAULT 1 COMMENT '支付方式 1:扫码 2:App 3:H5 4:JSAPI 5:小程序 6:刷脸', + config_json JSON NOT NULL COMMENT '渠道配置（JSON格式）', + fee_rate DECIMAL(5,4) NOT NULL DEFAULT 0.0060 COMMENT '手续费率（如0.0060=0.6%）', + fee_type TINYINT NOT NULL DEFAULT 1 COMMENT '手续费类型 1:百分比 2:固定金额', + min_amount DECIMAL(19,4) DEFAULT NULL COMMENT '单笔最小金额', + max_amount DECIMAL(19,4) DEFAULT NULL COMMENT '单笔最大金额', + day_limit_amount DECIMAL(19,4) DEFAULT NULL COMMENT '单日限额', + sort_no INT NOT NULL DEFAULT 0 COMMENT '排序号', + is_default TINYINT NOT NULL DEFAULT 0 COMMENT '是否默认渠道 0:否 1:是', + weight INT NOT NULL DEFAULT 100 COMMENT '权重（用于路由）', + success_rate DECIMAL(5,2) NOT NULL DEFAULT 100.00 COMMENT '成功率（%）', + status TINYINT NOT NULL DEFAULT 1 COMMENT '状态 0:禁用 1:启用', + deleted TINYINT NOT NULL DEFAULT 0 COMMENT '逻辑删除', + created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间', + updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间', + PRIMARY KEY (id), + UNIQUE KEY uk_channel_code (tenant_id, channel_code), + INDEX idx_channel_type (channel_type), + INDEX idx_status (status), + INDEX idx_tenant_id (tenant_id) +) COMMENT='支付渠道表'; +``` + +#### 3.2.2 渠道商户配置表 (pay_channel_merchant) + +```sql +CREATE TABLE pay_channel_merchant ( + id BIGINT NOT NULL COMMENT '主键ID', + tenant_id BIGINT NOT NULL DEFAULT 0 COMMENT '租户ID', + channel_id BIGINT NOT NULL COMMENT '支付渠道ID', + merchant_id BIGINT NOT NULL COMMENT '商户ID', + merchant_no VARCHAR(100) NOT NULL COMMENT '渠道商户号', + app_id VARCHAR(100) DEFAULT NULL COMMENT '应用ID', + private_key TEXT DEFAULT NULL COMMENT '商户私钥', + public_key TEXT DEFAULT NULL COMMENT '商户公钥', + api_key VARCHAR(500) DEFAULT NULL COMMENT 'API密钥', + cert_path VARCHAR(500) DEFAULT NULL COMMENT '证书路径', + cert_password VARCHAR(100) DEFAULT NULL COMMENT '证书密码', + notify_url VARCHAR(500) DEFAULT NULL COMMENT '异步通知地址', + return_url VARCHAR(500) DEFAULT NULL COMMENT '同步跳转地址', + fee_rate DECIMAL(5,4) NOT NULL DEFAULT 0.0060 COMMENT '商户自定义费率', + status TINYINT NOT NULL DEFAULT 1 COMMENT '状态', + deleted TINYINT NOT NULL DEFAULT 0 COMMENT '逻辑删除', + created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间', + updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间', + PRIMARY KEY (id), + UNIQUE KEY uk_channel_merchant (tenant_id, channel_id, merchant_id), + INDEX idx_merchant_id (merchant_id), + INDEX idx_channel_id (channel_id), + INDEX idx_tenant_id (tenant_id) +) COMMENT='渠道商户配置表'; +``` + +### 3.3 商户进件表 + +#### 3.3.1 商户表 (pay_merchant) + +```sql +CREATE TABLE pay_merchant ( + id BIGINT NOT NULL COMMENT '主键ID', + tenant_id BIGINT NOT NULL DEFAULT 0 COMMENT '租户ID', + merchant_no VARCHAR(64) NOT NULL COMMENT '商户编号', + merchant_name VARCHAR(200) NOT NULL COMMENT '商户名称', + merchant_short_name VARCHAR(100) DEFAULT NULL COMMENT '商户简称', + merchant_type TINYINT NOT NULL DEFAULT 1 COMMENT '商户类型 1:企业 2:个体户 3:个人', + agent_id BIGINT DEFAULT NULL COMMENT '所属代理ID', + contact_name VARCHAR(100) NOT NULL COMMENT '联系人姓名', + contact_phone VARCHAR(20) NOT NULL COMMENT '联系人电话', + contact_email VARCHAR(100) DEFAULT NULL COMMENT '联系人邮箱', + province_code VARCHAR(20) DEFAULT NULL COMMENT '省份编码', + city_code VARCHAR(20) DEFAULT NULL COMMENT '城市编码', + district_code VARCHAR(20) DEFAULT NULL COMMENT '区县编码', + address VARCHAR(500) DEFAULT NULL COMMENT '详细地址', + logo_url VARCHAR(500) DEFAULT NULL COMMENT '商户Logo', + website VARCHAR(500) DEFAULT NULL COMMENT '商户网站', + business_scope VARCHAR(500) DEFAULT NULL COMMENT '经营范围', + audit_status TINYINT NOT NULL DEFAULT 0 COMMENT '审核状态 0:待提交 1:待审核 2:审核中 3:审核通过 4:审核驳回', + audit_remark VARCHAR(500) DEFAULT NULL COMMENT '审核备注', + audit_time DATETIME(3) DEFAULT NULL COMMENT '审核时间', + merchant_status TINYINT NOT NULL DEFAULT 0 COMMENT '商户状态 0:未激活 1:正常 2:冻结 3:注销', + activate_time DATETIME(3) DEFAULT NULL COMMENT '激活时间', + total_transaction_amount DECIMAL(19,4) NOT NULL DEFAULT 0.0000 COMMENT '累计交易金额', + total_transaction_count INT NOT NULL DEFAULT 0 COMMENT '累计交易笔数', + remark VARCHAR(500) DEFAULT NULL COMMENT '备注', + status TINYINT NOT NULL DEFAULT 1 COMMENT '状态', + deleted TINYINT NOT NULL DEFAULT 0 COMMENT '逻辑删除', + created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间', + updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间', + PRIMARY KEY (id), + UNIQUE KEY uk_merchant_no (tenant_id, merchant_no), + INDEX idx_agent_id (agent_id), + INDEX idx_audit_status (audit_status), + INDEX idx_merchant_status (merchant_status), + INDEX idx_tenant_id (tenant_id) +) COMMENT='商户表'; +``` + +#### 3.3.2 商户资质表 (pay_merchant_qualification) + +```sql +CREATE TABLE pay_merchant_qualification ( + id BIGINT NOT NULL COMMENT '主键ID', + tenant_id BIGINT NOT NULL DEFAULT 0 COMMENT '租户ID', + merchant_id BIGINT NOT NULL COMMENT '商户ID', + qual_type TINYINT NOT NULL DEFAULT 1 COMMENT '资质类型 1:营业执照 2:法人身份证正面 3:法人身份证反面 4:开户许可证 5:门头照 6:店内照 7:结算银行卡 8:特殊资质', + qual_name VARCHAR(100) NOT NULL COMMENT '资质名称', + qual_no VARCHAR(100) DEFAULT NULL COMMENT '资质编号（如营业执照号）', + qual_image_url VARCHAR(500) NOT NULL COMMENT '资质图片URL', + qual_image_url2 VARCHAR(500) DEFAULT NULL COMMENT '资质图片URL2（反面）', + valid_start_date DATE DEFAULT NULL COMMENT '有效期开始', + valid_end_date DATE DEFAULT NULL COMMENT '有效期结束', + is_permanent TINYINT NOT NULL DEFAULT 0 COMMENT '是否永久有效 0:否 1:是', + verify_status TINYINT NOT NULL DEFAULT 0 COMMENT '核验状态 0:未核验 1:核验通过 2:核验失败', + verify_result VARCHAR(500) DEFAULT NULL COMMENT '核验结果', + remark VARCHAR(500) DEFAULT NULL COMMENT '备注', + status TINYINT NOT NULL DEFAULT 1 COMMENT '状态', + deleted TINYINT NOT NULL DEFAULT 0 COMMENT '逻辑删除', + created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间', + updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间', + PRIMARY KEY (id), + INDEX idx_merchant_id (merchant_id), + INDEX idx_qual_type (qual_type), + INDEX idx_tenant_id (tenant_id) +) COMMENT='商户资质表'; +``` + +#### 3.3.3 商户审核记录表 (pay_merchant_audit) + +```sql +CREATE TABLE pay_merchant_audit ( + id BIGINT NOT NULL COMMENT '主键ID', + tenant_id BIGINT NOT NULL DEFAULT 0 COMMENT '租户ID', + merchant_id BIGINT NOT NULL COMMENT '商户ID', + audit_type TINYINT NOT NULL DEFAULT 1 COMMENT '审核类型 1:入驻审核 2:资质变更 3:费率变更 4:结算变更', + audit_level TINYINT NOT NULL DEFAULT 1 COMMENT '审核层级 1:初审 2:复审', + audit_status TINYINT NOT NULL DEFAULT 0 COMMENT '审核状态 0:待审核 1:审核通过 2:审核驳回', + audit_remark VARCHAR(500) DEFAULT NULL COMMENT '审核意见', + auditor_id BIGINT DEFAULT NULL COMMENT '审核人ID', + auditor_name VARCHAR(100) DEFAULT NULL COMMENT '审核人姓名', + audit_time DATETIME(3) DEFAULT NULL COMMENT '审核时间', + pre_data JSON DEFAULT NULL COMMENT '变更前数据', + post_data JSON DEFAULT NULL COMMENT '变更后数据', + remark VARCHAR(500) DEFAULT NULL COMMENT '备注', + status TINYINT NOT NULL DEFAULT 1 COMMENT '状态', + deleted TINYINT NOT NULL DEFAULT 0 COMMENT '逻辑删除', + created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间', + updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间', + PRIMARY KEY (id), + INDEX idx_merchant_id (merchant_id), + INDEX idx_audit_type (audit_type), + INDEX idx_audit_status (audit_status), + INDEX idx_tenant_id (tenant_id) +) COMMENT='商户审核记录表'; +``` + +#### 3.3.4 商户渠道配置表 (pay_merchant_channel) + +```sql +CREATE TABLE pay_merchant_channel ( + id BIGINT NOT NULL COMMENT '主键ID', + tenant_id BIGINT NOT NULL DEFAULT 0 COMMENT '租户ID', + merchant_id BIGINT NOT NULL COMMENT '商户ID', + channel_id BIGINT NOT NULL COMMENT '支付渠道ID', + channel_code VARCHAR(50) NOT NULL COMMENT '渠道编码', + channel_merchant_no VARCHAR(100) DEFAULT NULL COMMENT '渠道子商户号', + channel_app_id VARCHAR(100) DEFAULT NULL COMMENT '渠道应用ID', + channel_status TINYINT NOT NULL DEFAULT 0 COMMENT '渠道状态 0:未申请 1:申请中 2:已通过 3:已驳回 4:已停用', + apply_time DATETIME(3) DEFAULT NULL COMMENT '申请时间', + audit_time DATETIME(3) DEFAULT NULL COMMENT '渠道审核时间', + audit_remark VARCHAR(500) DEFAULT NULL COMMENT '渠道审核备注', + fee_rate DECIMAL(5,4) NOT NULL DEFAULT 0.0060 COMMENT '商户渠道费率', + day_limit_amount DECIMAL(19,4) DEFAULT NULL COMMENT '单日限额', + single_limit_amount DECIMAL(19,4) DEFAULT NULL COMMENT '单笔限额', + config_json JSON DEFAULT NULL COMMENT '渠道特定配置（JSON）', + remark VARCHAR(500) DEFAULT NULL COMMENT '备注', + status TINYINT NOT NULL DEFAULT 1 COMMENT '状态', + deleted TINYINT NOT NULL DEFAULT 0 COMMENT '逻辑删除', + created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间', + updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间', + PRIMARY KEY (id), + UNIQUE KEY uk_merchant_channel (tenant_id, merchant_id, channel_id), + INDEX idx_merchant_id (merchant_id), + INDEX idx_channel_id (channel_id), + INDEX idx_channel_status (channel_status), + INDEX idx_tenant_id (tenant_id) +) COMMENT='商户渠道配置表'; +``` + +#### 3.3.5 商户结算配置表 (pay_merchant_settle) + +```sql +CREATE TABLE pay_merchant_settle ( + id BIGINT NOT NULL COMMENT '主键ID', + tenant_id BIGINT NOT NULL DEFAULT 0 COMMENT '租户ID', + merchant_id BIGINT NOT NULL COMMENT '商户ID', + settle_type TINYINT NOT NULL DEFAULT 1 COMMENT '结算方式 1:自动结算 2:手动结算', + settle_cycle TINYINT NOT NULL DEFAULT 1 COMMENT '结算周期 1:T+0 2:T+1 3:T+7 4:T+30', + min_settle_amount DECIMAL(19,4) NOT NULL DEFAULT 1.0000 COMMENT '最低结算金额', + settle_account_type TINYINT NOT NULL DEFAULT 1 COMMENT '结算账户类型 1:对公账户 2:对私账户 3:支付宝 4:微信', + settle_account_name VARCHAR(100) NOT NULL COMMENT '结算账户名', + settle_account_no VARCHAR(200) NOT NULL COMMENT '结算账号', + settle_bank_code VARCHAR(50) DEFAULT NULL COMMENT '结算银行编码', + settle_bank_name VARCHAR(100) DEFAULT NULL COMMENT '结算银行名称', + settle_bank_branch VARCHAR(200) DEFAULT NULL COMMENT '开户支行', + settle_bank_province VARCHAR(50) DEFAULT NULL COMMENT '开户省份', + settle_bank_city VARCHAR(50) DEFAULT NULL COMMENT '开户城市', + is_default TINYINT NOT NULL DEFAULT 1 COMMENT '是否默认结算配置', + remark VARCHAR(500) DEFAULT NULL COMMENT '备注', + status TINYINT NOT NULL DEFAULT 1 COMMENT '状态', + deleted TINYINT NOT NULL DEFAULT 0 COMMENT '逻辑删除', + created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间', + updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间', + PRIMARY KEY (id), + UNIQUE KEY uk_merchant_settle (tenant_id, merchant_id), + INDEX idx_merchant_id (merchant_id), + INDEX idx_tenant_id (tenant_id) +) COMMENT='商户结算配置表'; +``` + +### 3.4 分账表 + +#### 3.3.1 分账订单表 (pay_split_order) + +```sql +CREATE TABLE pay_split_order ( + id BIGINT NOT NULL COMMENT '主键ID', + tenant_id BIGINT NOT NULL DEFAULT 0 COMMENT '租户ID', + split_no VARCHAR(64) NOT NULL COMMENT '分账订单号', + order_id BIGINT NOT NULL COMMENT '支付订单ID', + order_no VARCHAR(64) NOT NULL COMMENT '支付订单号', + record_id BIGINT NOT NULL COMMENT '支付流水ID', + total_amount DECIMAL(19,4) NOT NULL COMMENT '分账总金额', + split_status TINYINT NOT NULL DEFAULT 0 COMMENT '分账状态 0:待分账 1:分账中 2:分账成功 3:分账失败 4:已回退', + split_type TINYINT NOT NULL DEFAULT 1 COMMENT '分账类型 1:实时分账 2:延迟分账', + split_mode TINYINT NOT NULL DEFAULT 1 COMMENT '分账模式 1:按比例 2:按固定金额', + split_time DATETIME(3) DEFAULT NULL COMMENT '分账成功时间', + finish_time DATETIME(3) DEFAULT NULL COMMENT '分账完成时间', + return_url VARCHAR(500) DEFAULT NULL COMMENT '异步通知地址', + error_code VARCHAR(100) DEFAULT NULL COMMENT '错误码', + error_msg VARCHAR(500) DEFAULT NULL COMMENT '错误信息', + remark VARCHAR(500) DEFAULT NULL COMMENT '备注', + status TINYINT NOT NULL DEFAULT 1 COMMENT '状态', + deleted TINYINT NOT NULL DEFAULT 0 COMMENT '逻辑删除', + created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间', + updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间', + PRIMARY KEY (id), + UNIQUE KEY uk_split_no (tenant_id, split_no), + INDEX idx_order_id (order_id), + INDEX idx_order_no (order_no), + INDEX idx_split_status (split_status), + INDEX idx_created_at (created_at), + INDEX idx_tenant_id (tenant_id) +) COMMENT='分账订单表'; +``` + +#### 3.3.2 分账明细表 (pay_split_detail) + +```sql +CREATE TABLE pay_split_detail ( + id BIGINT NOT NULL COMMENT '主键ID', + tenant_id BIGINT NOT NULL DEFAULT 0 COMMENT '租户ID', + split_order_id BIGINT NOT NULL COMMENT '分账订单ID', + split_no VARCHAR(64) NOT NULL COMMENT '分账订单号', + receiver_id BIGINT NOT NULL COMMENT '接收方ID', + receiver_type TINYINT NOT NULL DEFAULT 1 COMMENT '接收方类型 1:商户 2:平台 3:代理商 4:个人', + receiver_name VARCHAR(100) DEFAULT NULL COMMENT '接收方名称', + split_amount DECIMAL(19,4) NOT NULL COMMENT '分账金额', + split_rate DECIMAL(5,4) DEFAULT NULL COMMENT '分账比例', + split_status TINYINT NOT NULL DEFAULT 0 COMMENT '分账状态 0:待分账 1:分账中 2:分账成功 3:分账失败', + split_time DATETIME(3) DEFAULT NULL COMMENT '分账成功时间', + channel_detail_no VARCHAR(128) DEFAULT NULL COMMENT '渠道分账明细单号', + error_code VARCHAR(100) DEFAULT NULL COMMENT '错误码', + error_msg VARCHAR(500) DEFAULT NULL COMMENT '错误信息', + remark VARCHAR(500) DEFAULT NULL COMMENT '备注', + status TINYINT NOT NULL DEFAULT 1 COMMENT '状态', + deleted TINYINT NOT NULL DEFAULT 0 COMMENT '逻辑删除', + created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间', + updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间', + PRIMARY KEY (id), + INDEX idx_split_order_id (split_order_id), + INDEX idx_split_no (split_no), + INDEX idx_receiver_id (receiver_id), + INDEX idx_split_status (split_status), + INDEX idx_tenant_id (tenant_id) +) COMMENT='分账明细表'; +``` + +#### 3.3.3 分账接收方表 (pay_split_receiver) + +```sql +CREATE TABLE pay_split_receiver ( + id BIGINT NOT NULL COMMENT '主键ID', + tenant_id BIGINT NOT NULL DEFAULT 0 COMMENT '租户ID', + receiver_type TINYINT NOT NULL DEFAULT 1 COMMENT '接收方类型 1:商户 2:平台 3:代理商 4:个人', + receiver_id BIGINT NOT NULL COMMENT '接收方业务ID', + receiver_name VARCHAR(100) NOT NULL COMMENT '接收方名称', + channel_type TINYINT NOT NULL DEFAULT 1 COMMENT '渠道类型 1:支付宝 2:微信 3:银行卡', + account_type VARCHAR(50) DEFAULT NULL COMMENT '账户类型 如:login_name(支付宝登录号),openid(微信)', + account_no VARCHAR(200) NOT NULL COMMENT '接收账号', + account_name VARCHAR(100) DEFAULT NULL COMMENT '账号真实姓名', + relation_type TINYINT NOT NULL DEFAULT 1 COMMENT '关系类型 1:服务商 2:门店 3:员工 4:个人', + channel_relation_json JSON DEFAULT NULL COMMENT '渠道关系配置（JSON）', + is_default TINYINT NOT NULL DEFAULT 0 COMMENT '是否默认接收方', + remark VARCHAR(500) DEFAULT NULL COMMENT '备注', + status TINYINT NOT NULL DEFAULT 1 COMMENT '状态', + deleted TINYINT NOT NULL DEFAULT 0 COMMENT '逻辑删除', + created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间', + updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间', + PRIMARY KEY (id), + UNIQUE KEY uk_receiver (tenant_id, receiver_type, receiver_id, channel_type), + INDEX idx_receiver_id (receiver_id), + INDEX idx_account_no (account_no), + INDEX idx_status (status), + INDEX idx_tenant_id (tenant_id) +) COMMENT='分账接收方表'; +``` + +### 3.5 代理商表 + +#### 3.4.1 代理商表 (pay_agent) + +```sql +CREATE TABLE pay_agent ( + id BIGINT NOT NULL COMMENT '主键ID', + tenant_id BIGINT NOT NULL DEFAULT 0 COMMENT '租户ID', + agent_no VARCHAR(64) NOT NULL COMMENT '代理商编号', + agent_name VARCHAR(200) NOT NULL COMMENT '代理商名称', + agent_type TINYINT NOT NULL DEFAULT 1 COMMENT '代理商类型 1:个人 2:企业', + parent_id BIGINT DEFAULT 0 COMMENT '上级代理ID 0:顶级代理', + level TINYINT NOT NULL DEFAULT 1 COMMENT '代理层级 1:一级 2:二级 3:三级', + level_path VARCHAR(500) DEFAULT NULL COMMENT '层级路径 如: /1/5/10/', + contact_name VARCHAR(100) DEFAULT NULL COMMENT '联系人', + contact_phone VARCHAR(20) DEFAULT NULL COMMENT '联系电话', + contact_email VARCHAR(100) DEFAULT NULL COMMENT '联系邮箱', + id_card VARCHAR(18) DEFAULT NULL COMMENT '身份证号', + business_license VARCHAR(100) DEFAULT NULL COMMENT '营业执照号', + address VARCHAR(500) DEFAULT NULL COMMENT '地址', + commission_rate DECIMAL(5,4) NOT NULL DEFAULT 0.0000 COMMENT '默认佣金比例', + min_settle_amount DECIMAL(19,4) NOT NULL DEFAULT 100.0000 COMMENT '最低结算金额', + settle_type TINYINT NOT NULL DEFAULT 1 COMMENT '结算类型 1:自动结算 2:手动结算', + settle_cycle TINYINT NOT NULL DEFAULT 1 COMMENT '结算周期 1:T+1 2:T+7 3:T+30', + settle_account_id BIGINT DEFAULT NULL COMMENT '结算账户ID', + merchant_count INT NOT NULL DEFAULT 0 COMMENT '拓展商户数', + total_transaction_amount DECIMAL(19,4) NOT NULL DEFAULT 0.0000 COMMENT '累计交易金额', + total_commission_amount DECIMAL(19,4) NOT NULL DEFAULT 0.0000 COMMENT '累计佣金金额', + status TINYINT NOT NULL DEFAULT 1 COMMENT '状态 0:禁用 1:启用 2:审核中', + deleted TINYINT NOT NULL DEFAULT 0 COMMENT '逻辑删除', + created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间', + updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间', + PRIMARY KEY (id), + UNIQUE KEY uk_agent_no (tenant_id, agent_no), + INDEX idx_parent_id (parent_id), + INDEX idx_level (level), + INDEX idx_status (status), + INDEX idx_tenant_id (tenant_id) +) COMMENT='代理商表'; +``` + +#### 3.4.2 代理商户关系表 (pay_agent_merchant) + +```sql +CREATE TABLE pay_agent_merchant ( + id BIGINT NOT NULL COMMENT '主键ID', + tenant_id BIGINT NOT NULL DEFAULT 0 COMMENT '租户ID', + agent_id BIGINT NOT NULL COMMENT '代理商ID', + merchant_id BIGINT NOT NULL COMMENT '商户ID', + merchant_name VARCHAR(200) DEFAULT NULL COMMENT '商户名称', + commission_rate DECIMAL(5,4) NOT NULL DEFAULT 0.0000 COMMENT '佣金比例（覆盖代理默认比例）', + bind_time DATETIME(3) DEFAULT NULL COMMENT '绑定时间', + unbind_time DATETIME(3) DEFAULT NULL COMMENT '解绑时间', + is_bind TINYINT NOT NULL DEFAULT 1 COMMENT '是否绑定 0:解绑 1:绑定', + status TINYINT NOT NULL DEFAULT 1 COMMENT '状态', + deleted TINYINT NOT NULL DEFAULT 0 COMMENT '逻辑删除', + created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间', + updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间', + PRIMARY KEY (id), + UNIQUE KEY uk_agent_merchant (tenant_id, agent_id, merchant_id), + INDEX idx_agent_id (agent_id), + INDEX idx_merchant_id (merchant_id), + INDEX idx_tenant_id (tenant_id) +) COMMENT='代理商户关系表'; +``` + +#### 3.4.3 代理佣金记录表 (pay_agent_commission) + +```sql +CREATE TABLE pay_agent_commission ( + id BIGINT NOT NULL COMMENT '主键ID', + tenant_id BIGINT NOT NULL DEFAULT 0 COMMENT '租户ID', + commission_no VARCHAR(64) NOT NULL COMMENT '佣金记录号', + agent_id BIGINT NOT NULL COMMENT '代理商ID', + merchant_id BIGINT NOT NULL COMMENT '商户ID', + order_id BIGINT NOT NULL COMMENT '支付订单ID', + order_no VARCHAR(64) NOT NULL COMMENT '支付订单号', + record_id BIGINT NOT NULL COMMENT '支付流水ID', + transaction_amount DECIMAL(19,4) NOT NULL COMMENT '交易金额', + commission_rate DECIMAL(5,4) NOT NULL COMMENT '佣金比例', + commission_amount DECIMAL(19,4) NOT NULL COMMENT '佣金金额', + commission_status TINYINT NOT NULL DEFAULT 0 COMMENT '佣金状态 0:待结算 1:已结算 2:已取消', + settle_time DATETIME(3) DEFAULT NULL COMMENT '结算时间', + settle_batch_no VARCHAR(64) DEFAULT NULL COMMENT '结算批次号', + remark VARCHAR(500) DEFAULT NULL COMMENT '备注', + status TINYINT NOT NULL DEFAULT 1 COMMENT '状态', + deleted TINYINT NOT NULL DEFAULT 0 COMMENT '逻辑删除', + created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间', + updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间', + PRIMARY KEY (id), + UNIQUE KEY uk_commission_no (tenant_id, commission_no), + INDEX idx_agent_id (agent_id), + INDEX idx_merchant_id (merchant_id), + INDEX idx_order_id (order_id), + INDEX idx_commission_status (commission_status), + INDEX idx_settle_batch_no (settle_batch_no), + INDEX idx_created_at (created_at), + INDEX idx_tenant_id (tenant_id) +) COMMENT='代理佣金记录表'; +``` + +#### 3.4.4 代理结算表 (pay_agent_settlement) + +```sql +CREATE TABLE pay_agent_settlement ( + id BIGINT NOT NULL COMMENT '主键ID', + tenant_id BIGINT NOT NULL DEFAULT 0 COMMENT '租户ID', + settlement_no VARCHAR(64) NOT NULL COMMENT '结算单号', + agent_id BIGINT NOT NULL COMMENT '代理商ID', + settlement_type TINYINT NOT NULL DEFAULT 1 COMMENT '结算类型 1:佣金结算 2:退款扣回', + start_time DATETIME(3) NOT NULL COMMENT '结算开始时间', + end_time DATETIME(3) NOT NULL COMMENT '结算结束时间', + total_count INT NOT NULL DEFAULT 0 COMMENT '结算笔数', + total_amount DECIMAL(19,4) NOT NULL DEFAULT 0.0000 COMMENT '结算总金额', + fee_amount DECIMAL(19,4) NOT NULL DEFAULT 0.0000 COMMENT '手续费金额', + actual_amount DECIMAL(19,4) NOT NULL DEFAULT 0.0000 COMMENT '实际结算金额', + settlement_status TINYINT NOT NULL DEFAULT 0 COMMENT '结算状态 0:待结算 1:结算中 2:结算成功 3:结算失败', + settlement_time DATETIME(3) DEFAULT NULL COMMENT '结算成功时间', + settlement_method TINYINT NOT NULL DEFAULT 1 COMMENT '结算方式 1:转账到余额 2:银行转账 3:支付宝 4:微信', + settlement_account VARCHAR(200) DEFAULT NULL COMMENT '结算账户', + settlement_account_name VARCHAR(100) DEFAULT NULL COMMENT '结算账户名', + settlement_batch_no VARCHAR(128) DEFAULT NULL COMMENT '渠道结算批次号', + remark VARCHAR(500) DEFAULT NULL COMMENT '备注', + status TINYINT NOT NULL DEFAULT 1 COMMENT '状态', + deleted TINYINT NOT NULL DEFAULT 0 COMMENT '逻辑删除', + created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间', + updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间', + PRIMARY KEY (id), + UNIQUE KEY uk_settlement_no (tenant_id, settlement_no), + INDEX idx_agent_id (agent_id), + INDEX idx_settlement_status (settlement_status), + INDEX idx_start_time (start_time), + INDEX idx_end_time (end_time), + INDEX idx_tenant_id (tenant_id) +) COMMENT='代理结算表'; +``` + +### 3.6 资金账户表 + +#### 3.5.1 资金账户表 (pay_account) + +```sql +CREATE TABLE pay_account ( + id BIGINT NOT NULL COMMENT '主键ID', + tenant_id BIGINT NOT NULL DEFAULT 0 COMMENT '租户ID', + account_no VARCHAR(64) NOT NULL COMMENT '账户号', + account_type TINYINT NOT NULL DEFAULT 1 COMMENT '账户类型 1:用户 2:商户 3:平台 4:代理', + owner_id BIGINT NOT NULL COMMENT '账户所有者ID', + owner_name VARCHAR(100) DEFAULT NULL COMMENT '账户所有者名称', + balance DECIMAL(19,4) NOT NULL DEFAULT 0.0000 COMMENT '账户余额', + available_balance DECIMAL(19,4) NOT NULL DEFAULT 0.0000 COMMENT '可用余额', + frozen_balance DECIMAL(19,4) NOT NULL DEFAULT 0.0000 COMMENT '冻结余额', + total_income DECIMAL(19,4) NOT NULL DEFAULT 0.0000 COMMENT '累计收入', + total_expenditure DECIMAL(19,4) NOT NULL DEFAULT 0.0000 COMMENT '累计支出', + currency VARCHAR(10) NOT NULL DEFAULT 'CNY' COMMENT '币种', + password_hash VARCHAR(255) DEFAULT NULL COMMENT '支付密码', + status TINYINT NOT NULL DEFAULT 1 COMMENT '状态 0:冻结 1:正常', + deleted TINYINT NOT NULL DEFAULT 0 COMMENT '逻辑删除', + created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间', + updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间', + PRIMARY KEY (id), + UNIQUE KEY uk_account_no (tenant_id, account_no), + UNIQUE KEY uk_owner (tenant_id, account_type, owner_id), + INDEX idx_owner_id (owner_id), + INDEX idx_status (status), + INDEX idx_tenant_id (tenant_id) +) COMMENT='资金账户表'; +``` + +#### 3.5.2 账户流水表 (pay_account_record) + +```sql +CREATE TABLE pay_account_record ( + id BIGINT NOT NULL COMMENT '主键ID', + tenant_id BIGINT NOT NULL DEFAULT 0 COMMENT '租户ID', + record_no VARCHAR(64) NOT NULL COMMENT '流水号', + account_id BIGINT NOT NULL COMMENT '账户ID', + account_no VARCHAR(64) NOT NULL COMMENT '账户号', + record_type TINYINT NOT NULL DEFAULT 1 COMMENT '流水类型 1:收入 2:支出 3:冻结 4:解冻 5:充值 6:提现', + biz_type TINYINT NOT NULL DEFAULT 1 COMMENT '业务类型 1:支付 2:退款 3:分账 4:佣金 5:结算 6:提现 7:充值', + biz_id BIGINT DEFAULT NULL COMMENT '业务ID', + biz_no VARCHAR(64) DEFAULT NULL COMMENT '业务单号', + amount DECIMAL(19,4) NOT NULL COMMENT '变动金额', + before_balance DECIMAL(19,4) NOT NULL COMMENT '变动前余额', + after_balance DECIMAL(19,4) NOT NULL COMMENT '变动后余额', + remark VARCHAR(500) DEFAULT NULL COMMENT '备注', + status TINYINT NOT NULL DEFAULT 1 COMMENT '状态', + deleted TINYINT NOT NULL DEFAULT 0 COMMENT '逻辑删除', + created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间', + updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间', + PRIMARY KEY (id), + UNIQUE KEY uk_record_no (tenant_id, record_no), + INDEX idx_account_id (account_id), + INDEX idx_biz_id (biz_id), + INDEX idx_biz_no (biz_no), + INDEX idx_record_type (record_type), + INDEX idx_created_at (created_at), + INDEX idx_tenant_id (tenant_id) +) COMMENT='账户流水表'; +``` + +#### 3.5.3 资金冻结表 (pay_account_freeze) + +```sql +CREATE TABLE pay_account_freeze ( + id BIGINT NOT NULL COMMENT '主键ID', + tenant_id BIGINT NOT NULL DEFAULT 0 COMMENT '租户ID', + freeze_no VARCHAR(64) NOT NULL COMMENT '冻结单号', + account_id BIGINT NOT NULL COMMENT '账户ID', + freeze_amount DECIMAL(19,4) NOT NULL COMMENT '冻结金额', + freeze_type TINYINT NOT NULL DEFAULT 1 COMMENT '冻结类型 1:退款保障 2:争议处理 3:合规审查', + freeze_status TINYINT NOT NULL DEFAULT 0 COMMENT '冻结状态 0:冻结中 1:已解冻 2:已扣款', + biz_type TINYINT NOT NULL DEFAULT 1 COMMENT '业务类型 1:订单 2:提现', + biz_id BIGINT NOT NULL COMMENT '业务ID', + biz_no VARCHAR(64) NOT NULL COMMENT '业务单号', + expire_time DATETIME(3) DEFAULT NULL COMMENT '过期自动解冻时间', + unfreeze_time DATETIME(3) DEFAULT NULL COMMENT '实际解冻时间', + remark VARCHAR(500) DEFAULT NULL COMMENT '备注', + status TINYINT NOT NULL DEFAULT 1 COMMENT '状态', + deleted TINYINT NOT NULL DEFAULT 0 COMMENT '逻辑删除', + created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间', + updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间', + PRIMARY KEY (id), + UNIQUE KEY uk_freeze_no (tenant_id, freeze_no), + INDEX idx_account_id (account_id), + INDEX idx_biz_id (biz_id), + INDEX idx_freeze_status (freeze_status), + INDEX idx_expire_time (expire_time), + INDEX idx_tenant_id (tenant_id) +) COMMENT='资金冻结表'; +``` + +### 3.7 对账结算表 + +#### 3.6.1 对账单表 (pay_reconcile) + +```sql +CREATE TABLE pay_reconcile ( + id BIGINT NOT NULL COMMENT '主键ID', + tenant_id BIGINT NOT NULL DEFAULT 0 COMMENT '租户ID', + reconcile_no VARCHAR(64) NOT NULL COMMENT '对账单号', + channel_id BIGINT NOT NULL COMMENT '支付渠道ID', + channel_code VARCHAR(50) NOT NULL COMMENT '渠道编码', + reconcile_date DATE NOT NULL COMMENT '对账日期', + reconcile_type TINYINT NOT NULL DEFAULT 1 COMMENT '对账类型 1:支付对账 2:退款对账', + total_count INT NOT NULL DEFAULT 0 COMMENT '总笔数', + total_amount DECIMAL(19,4) NOT NULL DEFAULT 0.0000 COMMENT '总金额', + success_count INT NOT NULL DEFAULT 0 COMMENT '对平笔数', + success_amount DECIMAL(19,4) NOT NULL DEFAULT 0.0000 COMMENT '对平金额', + fail_count INT NOT NULL DEFAULT 0 COMMENT '差异笔数', + fail_amount DECIMAL(19,4) NOT NULL DEFAULT 0.0000 COMMENT '差异金额', + missing_count INT NOT NULL DEFAULT 0 COMMENT '漏单笔数（平台有渠道无）', + extra_count INT NOT NULL DEFAULT 0 COMMENT '多渠道笔数（渠道有平台无）', + amount_diff_count INT NOT NULL DEFAULT 0 COMMENT '金额差异笔数', + status TINYINT NOT NULL DEFAULT 0 COMMENT '状态 0:对账中 1:对账成功 2:对账失败 3:已处理', + file_url VARCHAR(500) DEFAULT NULL COMMENT '对账文件URL', + remark VARCHAR(500) DEFAULT NULL COMMENT '备注', + status_record TINYINT NOT NULL DEFAULT 1 COMMENT '状态', + deleted TINYINT NOT NULL DEFAULT 0 COMMENT '逻辑删除', + created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间', + updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间', + PRIMARY KEY (id), + UNIQUE KEY uk_reconcile (tenant_id, channel_id, reconcile_date, reconcile_type), + INDEX idx_reconcile_date (reconcile_date), + INDEX idx_status (status), + INDEX idx_tenant_id (tenant_id) +) COMMENT='对账单表'; +``` + +#### 3.6.2 对账差异表 (pay_reconcile_diff) + +```sql +CREATE TABLE pay_reconcile_diff ( + id BIGINT NOT NULL COMMENT '主键ID', + tenant_id BIGINT NOT NULL DEFAULT 0 COMMENT '租户ID', + reconcile_id BIGINT NOT NULL COMMENT '对账单ID', + diff_type TINYINT NOT NULL DEFAULT 1 COMMENT '差异类型 1:平台漏单 2:多渠道 3:金额不符 4:状态不符', + order_id BIGINT DEFAULT NULL COMMENT '平台订单ID', + order_no VARCHAR(64) DEFAULT NULL COMMENT '平台订单号', + channel_order_no VARCHAR(128) DEFAULT NULL COMMENT '渠道订单号', + platform_amount DECIMAL(19,4) DEFAULT NULL COMMENT '平台金额', + channel_amount DECIMAL(19,4) DEFAULT NULL COMMENT '渠道金额', + platform_status TINYINT DEFAULT NULL COMMENT '平台状态', + channel_status TINYINT DEFAULT NULL COMMENT '渠道状态', + handle_status TINYINT NOT NULL DEFAULT 0 COMMENT '处理状态 0:待处理 1:已处理', + handle_result TINYINT DEFAULT NULL COMMENT '处理结果 1:补单 2:退款 3:挂账 4:忽略', + handle_remark VARCHAR(500) DEFAULT NULL COMMENT '处理备注', + handler_id BIGINT DEFAULT NULL COMMENT '处理人ID', + handler_name VARCHAR(100) DEFAULT NULL COMMENT '处理人', + handle_time DATETIME(3) DEFAULT NULL COMMENT '处理时间', + remark VARCHAR(500) DEFAULT NULL COMMENT '备注', + status TINYINT NOT NULL DEFAULT 1 COMMENT '状态', + deleted TINYINT NOT NULL DEFAULT 0 COMMENT '逻辑删除', + created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间', + updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间', + PRIMARY KEY (id), + INDEX idx_reconcile_id (reconcile_id), + INDEX idx_order_id (order_id), + INDEX idx_handle_status (handle_status), + INDEX idx_tenant_id (tenant_id) +) COMMENT='对账差异表'; +``` + +--- + diff --git a/backend/design/支付模块架构概览.md b/backend/design/支付模块架构概览.md new file mode 100644 index 0000000..cefbb87 --- /dev/null +++ b/backend/design/支付模块架构概览.md @@ -0,0 +1,220 @@ +# 支付模块架构概览 + +> **来源**: `~/rui/支付模块架构设计.md` v1.0 +> **创建日期**: 2026-06-08 +> **模块**: rui-payment + +--- + +## 一、定位 + +rui-payment 是一个**聚合支付平台**，为上层业务提供统一、安全、高效的支付能力。 + +### 核心能力 + +| 能力 | 说明 | +|------|------| +| 聚合支付 | 支持支付宝、微信支付、银联云闪付等多渠道 | +| 智能路由 | 根据费率、成功率、渠道状态自动选择最优通道 | +| 分账体系 | 平台、商户、代理商多级分账，支持实时/延迟/手动分账 | +| 代理商体系 | 三级代理、佣金计算、代理结算 | +| 资金账户 | 余额、冻结、可用资金管理和流水记录 | +| 商户进件 | 商户入驻、资质上传、审核管理、渠道子商户配置 | +| 对账结算 | 自动对账、差错处理、结算单生成 | + +--- + +## 二、模块结构 + +``` +rui-payment/ +├── rui-payment-common/ # DTO、枚举、常量、工具 +├── rui-payment-core/ # Mapper、Entity、Service（数据库层） +├── rui-payment-provider/ # 第三方支付 SDK 封装（纯网关，不碰 DB） +├── rui-payment-api/ # REST API 服务（可部署） +└── rui-payment-task/ # MQ 监听器 + 定时任务 +``` + +### 依赖关系 + +``` +rui-payment-common + ↑ +rui-payment-core ──→ rui-payment-provider + ↑ ↑ +rui-payment-api ←───────┘ + ↑ +rui-payment-task +``` + +**关键边界**: `rui-payment-provider` 不依赖 `rui-payment-core`，只做三方 SDK 调用。 + +### 各模块职责 + +| 模块 | 核心职责 | 典型类 | +|------|---------|--------| +| common | DTO、VO、枚举、常量 | `PayRequest`, `PayResponse`, `PayStatus` | +| core | 业务逻辑、数据访问 | `PayOrderService`, `PayOrderMapper`, `PayOrder` | +| provider | 第三方 SDK 封装 | `AlipayPayHandler`, `WechatPayJsapiHandler` | +| api | REST API、启动类 | `PaymentTradeController`, `PaymentNotifyController` | +| task | 定时任务、MQ 监听 | `ReconcileJob`, `SettlementJob`, `PayTimeoutListener` | + +--- + +## 三、核心业务概念 + +### 3.1 支付核心 + +``` +PayOrder (支付订单) ──→ PayRecord (支付流水) ──→ PayChannelConfig (渠道配置) + │ + ↓ +PayRefund (退款单) +``` + +- **PayOrder**: 业务侧发起的支付请求，含金额、商品信息、买卖双方 +- **PayRecord**: 单次支付尝试记录，含渠道信息、三方流水号。一个 Order 可对应多次 Record +- **PayRefund**: 对已成功支付的订单退款，支持部分退款和多次退款 + +### 3.2 分账 + +``` +SplitOrder (分账订单) ──→ SplitDetail (分账明细) ──→ SplitReceiver (分账接收方) +``` + +分账模式: +- **实时分账**: 支付成功后立即调用渠道分账接口 +- **延迟分账**: 支付成功后冻结资金，延迟期（默认 T+7）后自动分账 +- **手动分账**: 运营人员在后台手动触发 + +### 3.3 代理商 + +``` +Agent (代理商) ──→ AgentRelation (代理关系) ──→ AgentMerchant (代理商户) + │ + ↓ +AgentCommission (代理佣金) ──→ AgentSettlement (代理结算) +``` + +三级代理体系，每级独立计算佣金。 + +### 3.4 资金账户 + +``` +Account (资金账户) ──→ AccountLog (账户流水) + │ + ↓ +AccountFreeze (资金冻结) +``` + +为每个商户/用户/代理创建独立资金账户，支持冻结、解冻。 + +### 3.5 商户进件 + +``` +Merchant (商户) ──→ MerchantQualification (资质) ──→ MerchantAuditRecord (审核) + │ + ↓ +MerchantChannelConfig (渠道配置) ──→ SubMerchantInfo (子商户) +``` + +--- + +## 四、核心流程 + +### 4.1 支付流程 + +``` +业务系统 → 支付API → 支付Core(保存订单) → 支付Provider(调SDK) → 第三方支付 + ↓ +业务系统 ← 支付API(通知) ← Core(更新状态+分账+佣金) ← Provider(解析回调) ← 异步通知 +``` + +1. 业务系统调用支付 API 创建订单 +2. API 调 Core 保存订单 +3. API 通过 Provider 调三方 SDK，返回支付参数 +4. 用户完成支付，三方异步通知 Provider +5. Provider 验签解析，将结果通过 PayResponse 返回 +6. Core 更新订单状态、记录流水、处理分账和佣金 +7. API 异步通知业务系统 + +### 4.2 分账流程 + +``` +支付成功 → Core(创建分账订单+明细) → Provider(调渠道分账接口) → Core(更新状态+更新账户余额) +``` + +### 4.3 对账流程 + +``` +定时任务 → 下载渠道对账文件 → 与本地订单逐笔比对 → 生成差异记录 → 人工/自动处理差异 +``` + +--- + +## 五、关键设计决策 + +| 决策 | 理由 | +|------|------| +| 订单与流水分离 | 用户可能多次尝试支付（切换渠道、失败重试），每次需要独立追踪 | +| 延迟分账（默认 T+7） | 降低退款风险，符合渠道分账规则，给予平台资金沉淀期 | +| 三级代理体系 | 满足大部分场景，避免层级过多导致佣金比例过低 | +| 独立资金账户 | 清晰的资金追踪，支持冻结/解冻，便于对账审计 | +| Provider 不碰 DB | 纯网关设计，解耦三方 SDK 与业务逻辑，可独立测试和替换 | + +--- + +## 六、安全设计 + +| 领域 | 措施 | +|------|------| +| 支付安全 | 签名验证、敏感信息加密存储、回调 IP 白名单、金额严格校验、幂等控制 | +| 资金安全 | 支付密码 BCrypt 加密、资金操作审计日志、风控拦截、退款保障期资金冻结 | + +--- + +## 七、Nacos 配置 + +```yaml +payment: + order-timeout: 30 # 订单超时（分钟） + split-delay-days: 7 # 分账延迟（天） + commission-settle-cycle: T+1 # 佣金结算周期 + notify-max-times: 5 # 通知重试次数 + notify-intervals: 15,30,60,300,900 # 通知间隔（秒） + + channels: + alipay: + enabled: true + sandbox: false + app-id: ${ALIPAY_APP_ID} + private-key: ${ALIPAY_PRIVATE_KEY} + public-key: ${ALIPAY_PUBLIC_KEY} + wechatpay: + enabled: true + sandbox: false + app-id: ${WXPAY_APP_ID} + mch-id: ${WXPAY_MCH_ID} + api-v3-key: ${WXPAY_API_V3_KEY} + +security: + oauth2: + ignore-urls: + - /payment/entry/** + - /payment/notify/** +``` + +--- + +## 八、待开发功能清单 + +- [ ] 支付核心流程（下单、支付、回调、查询、关闭） +- [ ] 退款功能（申请、查询、回调） +- [ ] 分账功能（创建、执行、回退、查询） +- [ ] 商户进件（入驻、资质、审核、渠道配置） +- [ ] 代理商体系（多级代理、佣金计算、结算） +- [ ] 资金账户（开户、流水、冻结） +- [ ] 对账（下载、比对、差异处理） +- [ ] 结算（商户结算、代理结算） +- [ ] 银联渠道接入 +- [ ] 单元测试（核心逻辑覆盖率 ≥80%） diff --git a/backend/guides/AI开发操作手册.md b/backend/guides/AI开发操作手册.md index 1602d87..1ce2be4 100644 --- a/backend/guides/AI开发操作手册.md +++ b/backend/guides/AI开发操作手册.md @@ -213,7 +213,7 @@ git push origin main ```bash # 查看 Actions 运行状态 -# 访问：https://git.dev.vifo.cc/rui/{仓库名}/actions +# 访问：https://git.vifo.cc/rui/{仓库名}/actions ``` ### 模块间通信示例 @@ -294,22 +294,22 @@ const cashierApi = { git remote -v # 确认是 Gitea 地址 -gitea ssh://git@git.dev.vifo.cc:222/rui/xxx.git +gitea ssh://git@git.vifo.cc:222/rui/xxx.git # 如果失败，检查 SSH 密钥 -ssh -p 222 git@git.dev.vifo.cc +ssh -p 222 git@git.vifo.cc ``` ### CI 构建失败 ```bash # 查看构建日志 -# 访问：https://git.dev.vifo.cc/rui/{仓库}/actions +# 访问：https://git.vifo.cc/rui/{仓库}/actions ``` ### 钉钉没收到通知 ```bash # 检查 Webhook 配置 -# 访问：https://git.dev.vifo.cc/rui/{仓库}/settings/hooks +# 访问：https://git.vifo.cc/rui/{仓库}/settings/hooks ``` --- diff --git a/frontend/design/cashier-design.md b/frontend/design/cashier-design.md index 39d45c6..fdd30fb 100644 --- a/frontend/design/cashier-design.md +++ b/frontend/design/cashier-design.md @@ -30,9 +30,9 @@ | 仓库 | 地址 | 说明 | |------|------|------| -| 前端 | `ssh://git@git.dev.vifo.cc:222/rui/rui-frontend.git` | admin-ui + 移动端 | -| 后端 | `ssh://git@git.dev.vifo.cc:222/rui/rui-cashier.git` | 收银系统独立后端服务 | -| 文档 | `ssh://git@git.dev.vifo.cc:222/rui/rui-docs.git` | 共享文档中心 | +| 前端 | `ssh://git@git.vifo.cc:222/rui/rui-frontend.git` | admin-ui + 移动端 | +| 后端 | `ssh://git@git.vifo.cc:222/rui/rui-cashier.git` | 收银系统独立后端服务 | +| 文档 | `ssh://git@git.vifo.cc:222/rui/rui-docs.git` | 共享文档中心 | > ⚠️ **注意**：收银系统相关 Issue 应提交到 `rui/rui-cashier` 仓库，不是 `rui-framework` diff --git a/gitea-runner-docker-compose.yml b/gitea-runner-docker-compose.yml index 03c04b6..ae70f47 100644 --- a/gitea-runner-docker-compose.yml +++ b/gitea-runner-docker-compose.yml @@ -6,9 +6,9 @@ services: - USER_UID=1000 - USER_GID=1000 - GITEA__database__DB_TYPE=sqlite3 - - GITEA__server__DOMAIN=git.dev.vifo.cc - - GITEA__server__ROOT_URL=https://git.dev.vifo.cc - - GITEA__server__SSH_DOMAIN=git.dev.vifo.cc + - GITEA__server__DOMAIN=git.vifo.cc + - GITEA__server__ROOT_URL=https://git.vifo.cc + - GITEA__server__SSH_DOMAIN=git.vifo.cc - GITEA__actions__ENABLED=true - GITEA__webhook__ALLOWED_HOST_LIST=* # 或者只允许特定网段： @@ -32,7 +32,7 @@ services: container_name: runner-default environment: CONFIG_FILE: /config.yaml - GITEA_INSTANCE_URL: "https://git.dev.vifo.cc" + GITEA_INSTANCE_URL: "https://git.vifo.cc" GITEA_RUNNER_REGISTRATION_TOKEN: "${GITEA_RUNNER_TOKEN}" GITEA_RUNNER_NAME: "runner-default" GITEA_RUNNER_LABELS: "ubuntu-latest:docker://node:20-slim" @@ -54,7 +54,7 @@ services: container_name: runner-node environment: CONFIG_FILE: /config.yaml - GITEA_INSTANCE_URL: "https://git.dev.vifo.cc" + GITEA_INSTANCE_URL: "https://git.vifo.cc" GITEA_RUNNER_REGISTRATION_TOKEN: "${GITEA_RUNNER_TOKEN}" GITEA_RUNNER_NAME: "runner-node" GITEA_RUNNER_LABELS: "node:docker://node:20-slim,ubuntu-latest:docker://node:20-slim" @@ -83,7 +83,7 @@ services: restart: always environment: CONFIG_FILE: /config.yaml - GITEA_INSTANCE_URL: "https://git.dev.vifo.cc" + GITEA_INSTANCE_URL: "https://git.vifo.cc" GITEA_RUNNER_REGISTRATION_TOKEN: "${GITEA_RUNNER_TOKEN}" GITEA_RUNNER_NAME: "runner-java" GITEA_RUNNER_LABELS: "java:docker://maven:3.9-eclipse-temurin-17,ubuntu-latest:docker://maven:3.9-eclipse-temurin-17" diff --git a/standards/API设计规范.md b/standards/API设计规范.md index fd536e7..fa1a816 100644 --- a/standards/API设计规范.md +++ b/standards/API设计规范.md @@ -470,7 +470,7 @@ http://localhost:9601/v3/api-docs # 收银服务 API 文档 ## 十三、文件存储服务（rui-service-storage） > **服务定位**：独立微服务（9400 端口 / 聚合启动器 9399），所有业务模块共用一个上传入口，通过 `bizType` 区分业务场景。 -> **前端组件**：``（[rui-frontend#5](https://git.dev.vifo.cc/rui/rui-frontend/issues/5)）。 +> **前端组件**：``（[rui-frontend#5](https://git.vifo.cc/rui/rui-frontend/issues/5)）。 ### 13.1 上传文件