Files
jinzuanwork/docs/支付框架设计.md
T

366 lines
22 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 收款流程重构:从「半自动」到全自助
> 金钻工坊 · 自助模板渲染 · 设计文档
> 版本 v1 · 2026-10-07 · 状态:设计稿(正式站代码未改动) · 范围:网页下单的付款与履约
> 在线版(页面,内容相同):https://claude.ai/artifact/ErKjgvjU9fBipacGpuURuQ
## 目录
- [00 概要与决策](#00-概要与决策)
- [01 总体架构](#01-总体架构)
- [02 ① 支付渠道抽象层](#02--支付渠道抽象层)
- [03 ② 爱发电主通道:全自动流程](#03--爱发电主通道全自动流程)
- [04 ③ 当面付辅助通道](#04--当面付辅助通道)
- [05 ④ 订单状态机](#05--订单状态机)
- [06 ⑤ 对账与超时关单](#06--对账与超时关单)
- [07 ⑥ 异常与人工兜底](#07--异常与人工兜底)
- [08 付款区交互](#08-付款区交互)
- [09 迁移与删除项](#09-迁移与删除项)
- [10 分阶段实施](#10-分阶段实施)
- [11 待金钻确认](#11-待金钻确认)
- [附 原型(测试环境)](#附-原型测试环境)
---
## 00 概要与决策
**目标**:买家下单、付款、开始渲染,全程不需要金钻动手。人工只处理系统判断不了的异常,比如金额不对、重复付款、迟到很久的付款。
| 通道 | 说明 |
|---|---|
| **主通道 · 爱发电专链** | 合规、已开通。买家跳到爱发电付款;系统靠回调 + 主动对账自动确认到账。手续费约 6%。 |
| **辅助通道 · 支付宝当面付** | 页面内直接显示二维码,扫码即付,到账秒级确认。手续费 0.6%。线上使用属于场景错配,有风控风险(见第 04 节)。 |
> **决策记录**:支付宝当面付官方定位是线下面对面收银,用在网站上可能被风控限额或关闭支付权限。金钻已知悉此风险,决定作为辅助通道使用,风险自担。设计上的应对:爱发电始终可用;当面付出现异常自动熔断、隐藏,不影响下单。
### 五条设计原则
- **到账只有一个入口。** 不管哪个渠道、回调还是对账,确认到账都调用同一个 `settle_payment()`,由它负责核对金额、去重、激活订单。
- **先验真,再履约。** 回调内容一律不直接信:爱发电要验签并用接口精确反查;当面付要验 RSA2 签名并核对金额和应用号。
- **天然幂等。** 同一笔渠道流水号只能入账一次;重复回调、回调和对账同时到达,都不会激活两次。
- **回调会丢,所以要主动对账。** 后台定时查渠道,把漏掉的到账补上。
- **订单内容和付款分开。** 订单记录买家要什么,支付单记录钱的往来。一张订单可以有多次付款尝试,比如换了渠道或二维码过期重来。
---
## 01 总体架构
```mermaid
flowchart LR
B[买家·订单页] -->|1 提交订单| O[订单服务]
O -->|2 选渠道 建支付单| G[渠道抽象层]
G --> A[爱发电渠道]
G --> Z[当面付渠道]
A -->|专链 / 专链二维码| B
Z -->|收款二维码| B
A -.回调.-> N[回调入口]
Z -.异步通知.-> N
R[定时对账] -->|主动查单| A
R -->|主动查单| Z
B -->|轮询 / 付好了没反应| P[查单接口]
P --> Z
P --> A
N --> S{{settle_payment 统一到账}}
R --> S
P --> S
S -->|金额够·首次| ACT[激活订单 进渲染队列]
S -->|金额不足·重复·迟到太久| TODO[后台待办 人工]
```
下单内容(皮肤、模板、分辨率)、渲染机、确认收货、卡密下单这条路都**不变**。卡密本身就是已付款凭证,它的订单直接进入 `waiting`,不经过本设计的付款环节。
---
## 02 ① 支付渠道抽象层
每个渠道是一个独立模块,实现同一组接口。下单流程、状态机、对账任务只认这组接口,不关心具体是哪个渠道。以后加微信、个体户的官方网站支付、或者聚合支付,只需要新写一个模块。
| 接口 | 作用 | 爱发电实现 | 当面付实现 |
|---|---|---|---|
| `create(order, pay)` | 生成付款方式 | 拼专链:`order/create?user_id&custom_price&custom_order_id=pay_id&remark`,返回跳转链接 + 同一链接的二维码 | 调 `alipay.trade.precreate`,带 `out_trade_no=pay_id`、金额、`time_expire`、`notify_url`,返回 `qr_code` |
| `verify_notify(req)` | 把回调变成「可信的到账事实」或拒绝 | 验 `data.sign`(官方公钥)→ 用 `out_trade_no` 调 `query-order` 精确反查 → 以反查结果为准 | 验 RSA2 签名(支付宝公钥)→ 核对 `app_id`、`out_trade_no` 存在、`trade_status` |
| `query(pay)` | 主动查一笔支付单 | 扫最近的订单页,按 `custom_order_id` 找 | `alipay.trade.query` |
| `close(pay)` | 关闭过期支付单 | 无法远程关闭,只在本地标记过期(迟到付款靠对账收回) | `alipay.trade.close`(未扫码的单可能返回「交易不存在」,视为已关) |
| `refund(pay, amt)` | 退款(只在后台人工触发) | 不支持接口退款,提示去爱发电后台操作 | `alipay.trade.refund` |
| `health()` | 渠道是否可用 | 配置齐全即可用 | 配置齐全且未熔断 |
### 统一到账入口 settle_payment()
```text
settle_payment(channel, pay_id, trade_no, amount_paid, source)
1. 在一个数据库事务里锁住这条支付单
2. trade_no 已入账过 → 直接返回「已处理」(幂等)
3. 支付单状态是 paid → 记为「重复付款」,进待办,返回
4. amount_paid < amount_due → 支付单记 mismatch,进待办「金额不足」,返回
5. 支付单记 paid(写 trade_no、实付、时间、来源)
6. 看订单状态:
unpaid → 激活:订单转 waiting,进渲染队列
closed 且在宽限期内 → 恢复并激活(内容还在)
closed 超过宽限期 → 进待办「迟到付款」,人工补单或退款
已经是 waiting 之后 → 进待办「重复付款」(另一渠道已付过)
7. 其他同一订单的未付支付单 → 关闭(当面付调 close)
```
`source` 只用于留痕:`notify` / `reconcile` / `poll` / `buyer_check` / `admin`。
### 新增数据
| 表 | 字段 | 说明 |
|---|---|---|
| `payments` 支付单 | `pay_id`(主键,如 `YS7ZBZW6P1`)、`oid`、`channel`、`amount_due`、`state`、`created_at`、`expire_at`、`trade_no`(唯一)、`amount_paid`、`paid_at`、`last_query_at`、`note` | 一张订单可以有多条;`trade_no` 加唯一约束,是幂等的最后防线 |
| `pay_events` 流水 | 时间、渠道、类型(notify/query/close/refund)、关联 pay_id、结果、原文摘要(截断 4KB) | 只追加不修改,用于对账和申诉 |
| `pay_todo` 待办 | 类型、pay_id / 渠道流水号、金额、说明、处理人、处理结果 | 开单后台的「支付待办」列表 |
密钥(爱发电 token 与公钥、支付宝应用私钥与支付宝公钥)只放服务器配置文件,权限 600,不进仓库、不进前端。
---
## 03 ② 爱发电主通道:全自动流程
```mermaid
sequenceDiagram
participant B as 买家
participant S as 我方服务器
participant F as 爱发电
B->>S: 选「爱发电」付款
S->>S: 建支付单 pay_id,应付金额锁定
S-->>B: 专链(手机直接跳;电脑显示专链二维码)
B->>F: 打开专链付款(custom_order_id = pay_id)
F-->>S: Webhook 推送(可能延迟或丢失)
S->>S: 验签 data.sign
S->>F: query-order 按 out_trade_no 精确反查
F-->>S: 订单详情(status、金额、custom_order_id)
S->>S: settle_payment → 激活订单
S-->>F: 回应 ec=200
loop 页面可见时每 3 秒
B->>S: 查订单状态
end
S-->>B: 已到账 · 排队中
```
1. **生成专链。** 链接带 `custom_price`(本单应付)、`custom_order_id`(支付单号 pay_id)、`remark`(订单号,给买家和金钻看)。需要一个「自选金额」方案承载 `custom_price`。
2. **展示。** 手机端直接跳转;电脑端显示专链二维码(本地生成,不用第三方二维码服务),手机扫码打开爱发电付款。买家回到订单页时页面开始轮询。
3. **回调先落流水、马上回 200。** 收到推送后先写 `pay_events`,然后返回 `{"ec":200,"em":""}`。后续处理失败不影响这次应答,由对账补救。
4. **验签。** 用爱发电官方公钥验 `data.sign`(2025 年 7 月起提供;待签字符串为 `out_trade_no + user_id + plan_id + total_amount`,SHA256,Base64)。验签失败直接丢弃,记流水。暂时拿不到公钥时,跳过这一步,以下一步为准。
5. **精确反查。** 调用 `query-order` 并带 `out_trade_no`(接口支持按订单号查,不再翻页找)。之后**只用反查结果**里的状态、金额、`custom_order_id`。
6. **认单。** `status == 2` 且 `custom_order_id` 对应得上本地支付单,调用 `settle_payment()`。
没有 `custom_order_id`(买家直接在爱发电店铺下单,或用了旧链接),按现有逻辑当作购买卡密:按实付金额发码,通过爱发电自动回复给买家。**不再**用留言或金额唯一匹配去猜是哪张网页单。
7. **金额闸门。** 买家可以在爱发电页面手动改金额,所以实付必须 ≥ 应付,否则支付单记为 mismatch,进待办。
---
## 04 ③ 当面付辅助通道
```mermaid
sequenceDiagram
participant B as 买家
participant S as 我方服务器
participant A as 支付宝
B->>S: 选「支付宝扫码」
S->>S: 熔断检查 · 金额上限检查 · 建支付单
S->>A: alipay.trade.precreate(out_trade_no=pay_id,time_expire=+15分钟)
A-->>S: qr_code
S-->>B: 页面显示二维码 + 15 分钟倒计时
B->>A: 支付宝扫码付款
par 异步通知
A-->>S: notify(RSA2 签名)
S->>S: 验签 → settle_payment → 回 "success"
and 页面轮询
loop 每 3 秒
B->>S: 查支付单
S->>A: trade.query(每单最多 5 秒查一次)
end
end
S-->>B: 已到账 · 排队中
```
1. **预下单。** 先检查熔断状态和金额上限(个人基础版单笔 ≤1000 元,建议再保守一点设 500 元,超过的只给爱发电)。调 `alipay.trade.precreate`,商品名统一写成中性文案,如「金钻工坊 渲染服务」,加订单号。
2. **出码。** `qr_code` 在前端本地画成二维码,配 15 分钟倒计时;过期后显示「重新生成」,生成新支付单并关闭旧的。手机端加一个「打开支付宝付款」按钮,跳到支付宝扫这个码(不保证所有浏览器都能拉起,按钮仅作方便)。
3. **异步通知。** 验 RSA2 签名 → 核对 `app_id`、`out_trade_no` 是本地支付单、`total_amount` 等于应付 → `trade_status` 为 `TRADE_SUCCESS` 或 `TRADE_FINISHED` 时调 `settle_payment()` → 回纯文本 `success`。验签失败回其他内容,支付宝会重试。
4. **轮询查单。** 页面可见时每 3 秒问一次服务器;服务器对同一笔支付单最多每 5 秒调一次 `trade.query`,查到成功同样走 `settle_payment()`。页面切到后台就停轮询,回来立刻查一次。
5. **过期关单。** 到期后先最后查一次,确认没付再 `trade.close`,本地记 closed。
### 线上使用的风控注意事项
- **场景错配。** 当面付是线下收银产品,签约时也按线下门店审核。线上使用可能被判场景不符,表现为:交易被拦、限额下调、要求补充材料,严重的关闭当面付权限,甚至影响支付宝账户。
- **额度。** 无营业执照的基础版单笔 ≤1000 元、单日 ≤5 万元。
- **资金。** 被风控时可能冻结一段时间的收款,要有心理准备,不能把它当唯一收款方式。
### 降低风险的做法
- **爱发电永远在。** 付款区默认推荐爱发电,当面付作为「也可以用支付宝扫码」的备选。
- **自动熔断。** 预下单或查单连续失败 3 次,或返回风控、权限类错误码(如 `ACQ.ACCESS_FORBIDDEN`、`ACQ.SELLER_BEEN_BLOCKED` 一类),自动关闭当面付 6 小时,页面隐藏这个选项并通知金钻;之后由后台手动恢复。
- **控制节奏。** 同一买家(同一 IP 或同一订单)10 分钟内最多生成 3 个二维码;全站同时未付款的当面付二维码不超过 20 个,超过就只给爱发电。
- **控制金额。** 设单笔上限(建议 500 元),大单只走爱发电。
- **交易信息真实一致。** 商品名、金额、订单号都是真实的,不伪装成线下消费;不使用营销类字眼。
- **留证。** 每笔交易保留订单号、皮肤、成品和小票,被要求补材料或申诉时拿得出交易真实性证明。
- **定期提现。** 当面付的钱实时进入支付宝余额,定期转出,降低冻结时的损失。
---
## 05 ④ 订单状态机
```mermaid
stateDiagram-v2
[*] --> unpaid: 网页下单提交
[*] --> waiting: 卡密下单提交
unpaid --> waiting: 到账(settle_payment)
unpaid --> closed: 超过 24 小时未付
unpaid --> void: 后台注销
closed --> waiting: 宽限期内迟到付款
waiting --> working: 渲染机领单
working --> done: 全部出图
working --> failed: 渲染失败
working --> waiting: 渲染机掉线回收
failed --> waiting: 免费重渲 / 后台重试
done --> waiting: 免费重渲(确认收货前)
done --> [*]: 开放下载满 72 小时,卡密核销
```
| 状态 | 含义 | 买家看到 | 变化 |
|---|---|---|---|
| `unpaid` | 已提交,等付款 | 付款区:渠道选择 / 二维码 / 倒计时 | 不变 |
| `closed` | 超时未付,自动关闭;内容保留到清理期 | 「订单已关闭,重新下单」;宽限期内付款仍会自动恢复 | **新增** |
| `void` | 后台人工注销 | 「订单已注销」 | 不变 |
| `waiting` | 已付款(或卡密),排队 | 排队位置 | 不变 |
| `working` / `done` / `failed` | 渲染流水线 | 同现在 | 不变 |
| `paid` | 旧:买家申报「已付」等人工确认 | — | **删除**,改为订单上的标记 `buyer_claim_at`,只用于触发立即对账和提醒金钻 |
确认收货(`accepted`)、直发(`direct`)、免费重渲已用(`redo_used`)仍然是订单上的标记,不是状态。
### 支付单状态
```mermaid
stateDiagram-v2
[*] --> created: 建单
created --> paid: 到账且金额够
created --> mismatch: 到账但金额不足
created --> closed: 过期 / 订单已在别的渠道付过
closed --> paid: 迟到付款(对账发现)
paid --> refunded: 后台退款
mismatch --> paid: 人工确认补齐
mismatch --> refunded: 人工退款
```
---
## 06 ⑤ 对账与超时关单
服务器内一个后台调度线程(或 systemd 定时器调用 `admin.py`),每分钟运行一轮。每个任务各自加锁,同一时间只跑一个实例。
| 任务 | 频率 | 做什么 |
|---|---|---|
| 爱发电对账 | 有未结爱发电支付单时每 60 秒 | 从第一页往后拉 `query-order`,直到早于最老的未结支付单;按 `custom_order_id` 匹配,命中就 `settle_payment(source=reconcile)` |
| 当面付补查 | 每 60 秒 | 对创建超过 1 分钟、30 秒内没查过的未结支付单调 `trade.query` |
| 支付单过期 | 每 60 秒 | 到期的支付单最后查一次 → 没付就 `close`,记 closed |
| 订单超时关闭 | 每 5 分钟 | `unpaid` 超过 24 小时且没有活跃支付单 → 订单转 `closed` |
| 迟到付款扫描 | 每 10 分钟 | 对最近 72 小时内关闭的支付单再做一次对账,抓迟到付款 |
| 日对账 | 每天 04:00 | 前一天两个渠道的成交笔数和金额 vs 本地 paid 支付单,有差异进待办 |
### 时间参数(可配置)
| 参数 | 建议值 | 说明 |
|---|---|---|
| 当面付二维码有效期 | 15 分钟 | 写进 `time_expire`,到期关单 |
| 爱发电支付单有效期 | 2 小时 | 本地标记;过期后付款仍能被对账收回 |
| 订单待付款保留 | 24 小时 | 之后转 `closed` |
| 迟到付款宽限 | 关闭后 72 小时 | 宽限内到账自动恢复并激活;超过进待办 |
| 页面轮询 | 3 秒,页面可见时 | 当面付二维码页最长 15 分钟;爱发电回到页面后最长 10 分钟 |
---
## 07 ⑥ 异常与人工兜底
所有需要人工的情况都进开单后台的「支付待办」,带上订单号、渠道流水号、应付和实付金额,以及推荐操作。
| 场景 | 系统自动做 | 人工做 |
|---|---|---|
| 回调丢失或延迟 | 【自动】对账补上 | 无 |
| 伪造回调 | 【自动】验签失败或反查不到,丢弃并记流水 | 无 |
| 买家点「付好了没反应」 | 【自动】立即对账一次;仍未找到,提示稍等并显示「呼叫金钻」 | 收到呼叫后在待办里核对 |
| 金额不足(买家改了金额) | 【自动】不激活,支付单记 mismatch,页面提示差额 | 【人工】补差价后确认,或退款 |
| 重复付款(两个渠道都付了 / 付了两次) | 【自动】只激活一次,第二笔进待办 | 【人工】退款:当面付后台一键退;爱发电去爱发电后台退 |
| 订单关闭后付款(宽限内) | 【自动】恢复订单并激活 | 无 |
| 订单关闭后付款(超过宽限) | 进待办 | 【人工】内容还在就手动激活,否则退款或联系买家 |
| 爱发电成交没有 custom_order_id | 【自动】按购买卡密处理:按实付发码 | 实付不足一张时人工处理 |
| 当面付被风控 / 接口连续失败 | 【自动】熔断 6 小时,页面隐藏,只剩爱发电 | 【人工】查看支付宝通知,处理后在后台恢复 |
| 日对账有差异 | 进待办,列出差异明细 | 【人工】逐笔核对 |
### 开单后台新增
- 「支付待办」列表:确认补齐、退款(当面付)、手动激活、忽略并备注。
- 「按渠道流水号认领」:输入爱发电订单号或支付宝交易号,指定到某张订单(取代现在买家自己填爱发电订单号的旧入口)。
- 渠道开关:当面付熔断状态、手动关闭 / 恢复。
- 保留现有「手动激活」,作为最后手段。
---
## 08 付款区交互
1. 提交订单后,付款区显示应付金额,以及两个选项:「爱发电付款(推荐)」和「支付宝扫码」。当面付熔断或金额超限时,只显示爱发电。
2. 选爱发电:手机直接跳转;电脑显示专链二维码,并附「在本机打开」的链接。
3. 选支付宝:显示二维码和倒计时;过期后显示「重新生成」。
4. 付款期间页面自动轮询,到账后直接切到「已到账 · 排队中」,不需要买家点任何按钮。
5. 「我已经付好了」改成「付好了没反应?」:点了立即对账,找不到再给「呼叫金钻」。
6. 订单页始终能看到订单号和取件链接;不再附送未激活的卡密。
---
## 09 迁移与删除项
### 迁移
- 上线时现存的 `unpaid` 订单:为每单补建一条爱发电支付单,`pay_id` 就用订单号本身(旧专链里的 `custom_order_id` 本来就是订单号),老链接付款照样能对上。
- 现存的 `paid` 订单(买家申报过):全部列进待办,人工逐笔核对后激活或关闭。
- 已有的爱发电账本(`payplatform-orders`)保留只读,作为历史对账依据。
### 删除
- 回调里的「留言含兑换码」「留言含订单号」「金额唯一匹配」三层猜测。
- 网页单提交时生成的未激活卡密(凭证统一为订单号 + 取件码)。
- 没有页面在用的旧接口 `/api/activate`、`/api/activate-payplatform`。
- 订单状态 `paid`。
---
## 10 分阶段实施
| 阶段 | 内容 | 上线标准 |
|---|---|---|
| 一 · 骨架 + 爱发电全自动 | 支付单与流水表、渠道接口、`settle_payment()`、爱发电验签和精确反查、对账任务、超时关单、`closed` 状态、页面轮询、迁移脚本 | 测试覆盖:重复回调、回调丢失、伪造回调、金额不足、重复付款、迟到付款、并发到账;在测试环境用真实小额爱发电订单跑通一次 |
| 二 · 当面付 | 当面付渠道、二维码页、异步通知、轮询查单、关单、熔断、节奏和金额限制 | 先用支付宝沙箱跑通全部用例,再用正式应用付 0.01 元验证一次后开放 |
| 三 · 后台与清理 | 支付待办、按流水号认领、退款按钮、渠道开关、日对账报告;删除旧逻辑和旧接口 | 后台各操作都有确认步骤和操作记录 |
每个阶段沿用现在的上线方式:先备份,队列为空时重启;前端单独上线,可随时回滚。
---
## 11 待金钻确认
1. 爱发电开发者后台的签名公钥(验签用),并确认有一个「自选金额」方案可承载 `custom_price`。
2. 支付宝开放平台当面付应用:AppID、应用私钥(服务器生成后由他上传公钥)、支付宝公钥、异步通知地址。
3. 时间参数是否按建议值:二维码 15 分钟、订单保留 24 小时、迟到宽限 72 小时。
4. 当面付单笔上限:建议 500 元。
5. 付款区默认推荐哪个渠道:建议爱发电。
6. 现存的「已申报付款」订单由谁、何时核对。
---
## 附 原型(测试环境)
为验证上面的流程,按本设计做了一个可运行原型。**它只是测试环境,和正式站完全隔离:**
- 部署在甲骨文预览机(161.33.11.66),不在正式服务器上;正式站的下单、付款代码和数据都没有改动。
- 爱发电、支付宝的账号与密钥全部是占位符,所有付款请求都发往原型内置的模拟网关,不连真实渠道、不会产生真实交易。
- 原型有自己独立的 SQLite 数据库,不读写正式站的订单和卡密。
- 后续开发也只在预览机上进行,不碰生产。
| 项 | 位置 |
|---|---|
| 付款页 | http://161.33.11.66/pay-proto/ |
| 后台 | http://161.33.11.66/pay-proto/admin(口令在预览机 `/var/lib/jz-pay-proto/admin_token`) |
| 代码 | 仓库 `backend/pay-proto/`(说明见其中 `README.md`) |
| 测试 | `python3 backend/pay-proto/tests/test_proto.py`,24 个场景 |
依据:爱发电开发者文档(Webhook 无保证送达、需幂等并配合 query-order;2025-07 起 `data.sign` 可用官方公钥验签;下单链接支持 `custom_order_id` / `custom_price` / `remark`);支付宝开放平台当面付文档(precreate / query / close / 异步通知 RSA2 验签;产品定位为线下收银)。