22 KiB
收款流程重构:从「半自动」到全自助
金钻工坊 · 自助模板渲染 · 设计文档 版本 v1 · 2026-10-07 · 状态:设计稿(正式站代码未改动) · 范围:网页下单的付款与履约 在线版(页面,内容相同):https://claude.ai/artifact/ErKjgvjU9fBipacGpuURuQ
目录
- 00 概要与决策
- 01 总体架构
- 02 ① 支付渠道抽象层
- 03 ② 爱发电主通道:全自动流程
- 04 ③ 当面付辅助通道
- 05 ④ 订单状态机
- 06 ⑤ 对账与超时关单
- 07 ⑥ 异常与人工兜底
- 08 付款区交互
- 09 迁移与删除项
- 10 分阶段实施
- 11 待金钻确认
- 附 原型(测试环境)
00 概要与决策
目标:买家下单、付款、开始渲染,全程不需要金钻动手。人工只处理系统判断不了的异常,比如金额不对、重复付款、迟到很久的付款。
| 通道 | 说明 |
|---|---|
| 主通道 · 爱发电专链 | 合规、已开通。买家跳到爱发电付款;系统靠回调 + 主动对账自动确认到账。手续费约 6%。 |
| 辅助通道 · 支付宝当面付 | 页面内直接显示二维码,扫码即付,到账秒级确认。手续费 0.6%。线上使用属于场景错配,有风控风险(见第 04 节)。 |
决策记录:支付宝当面付官方定位是线下面对面收银,用在网站上可能被风控限额或关闭支付权限。金钻已知悉此风险,决定作为辅助通道使用,风险自担。设计上的应对:爱发电始终可用;当面付出现异常自动熔断、隐藏,不影响下单。
五条设计原则
- 到账只有一个入口。 不管哪个渠道、回调还是对账,确认到账都调用同一个
settle_payment(),由它负责核对金额、去重、激活订单。 - 先验真,再履约。 回调内容一律不直接信:爱发电要验签并用接口精确反查;当面付要验 RSA2 签名并核对金额和应用号。
- 天然幂等。 同一笔渠道流水号只能入账一次;重复回调、回调和对账同时到达,都不会激活两次。
- 回调会丢,所以要主动对账。 后台定时查渠道,把漏掉的到账补上。
- 订单内容和付款分开。 订单记录买家要什么,支付单记录钱的往来。一张订单可以有多次付款尝试,比如换了渠道或二维码过期重来。
01 总体架构
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()
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 ② 爱发电主通道:全自动流程
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: 已到账 · 排队中
- 生成专链。 链接带
custom_price(本单应付)、custom_order_id(支付单号 pay_id)、remark(订单号,给买家和金钻看)。需要一个「自选金额」方案承载custom_price。 - 展示。 手机端直接跳转;电脑端显示专链二维码(本地生成,不用第三方二维码服务),手机扫码打开爱发电付款。买家回到订单页时页面开始轮询。
- 回调先落流水、马上回 200。 收到推送后先写
pay_events,然后返回{"ec":200,"em":""}。后续处理失败不影响这次应答,由对账补救。 - 验签。 用爱发电官方公钥验
data.sign(2025 年 7 月起提供;待签字符串为out_trade_no + user_id + plan_id + total_amount,SHA256,Base64)。验签失败直接丢弃,记流水。暂时拿不到公钥时,跳过这一步,以下一步为准。 - 精确反查。 调用
query-order并带out_trade_no(接口支持按订单号查,不再翻页找)。之后只用反查结果里的状态、金额、custom_order_id。 - 认单。
status == 2且custom_order_id对应得上本地支付单,调用settle_payment()。 没有custom_order_id(买家直接在爱发电店铺下单,或用了旧链接),按现有逻辑当作购买卡密:按实付金额发码,通过爱发电自动回复给买家。不再用留言或金额唯一匹配去猜是哪张网页单。 - 金额闸门。 买家可以在爱发电页面手动改金额,所以实付必须 ≥ 应付,否则支付单记为 mismatch,进待办。
04 ③ 当面付辅助通道
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: 已到账 · 排队中
- 预下单。 先检查熔断状态和金额上限(个人基础版单笔 ≤1000 元,建议再保守一点设 500 元,超过的只给爱发电)。调
alipay.trade.precreate,商品名统一写成中性文案,如「金钻工坊 渲染服务」,加订单号。 - 出码。
qr_code在前端本地画成二维码,配 15 分钟倒计时;过期后显示「重新生成」,生成新支付单并关闭旧的。手机端加一个「打开支付宝付款」按钮,跳到支付宝扫这个码(不保证所有浏览器都能拉起,按钮仅作方便)。 - 异步通知。 验 RSA2 签名 → 核对
app_id、out_trade_no是本地支付单、total_amount等于应付 →trade_status为TRADE_SUCCESS或TRADE_FINISHED时调settle_payment()→ 回纯文本success。验签失败回其他内容,支付宝会重试。 - 轮询查单。 页面可见时每 3 秒问一次服务器;服务器对同一笔支付单最多每 5 秒调一次
trade.query,查到成功同样走settle_payment()。页面切到后台就停轮询,回来立刻查一次。 - 过期关单。 到期后先最后查一次,确认没付再
trade.close,本地记 closed。
线上使用的风控注意事项
- 场景错配。 当面付是线下收银产品,签约时也按线下门店审核。线上使用可能被判场景不符,表现为:交易被拦、限额下调、要求补充材料,严重的关闭当面付权限,甚至影响支付宝账户。
- 额度。 无营业执照的基础版单笔 ≤1000 元、单日 ≤5 万元。
- 资金。 被风控时可能冻结一段时间的收款,要有心理准备,不能把它当唯一收款方式。
降低风险的做法
- 爱发电永远在。 付款区默认推荐爱发电,当面付作为「也可以用支付宝扫码」的备选。
- 自动熔断。 预下单或查单连续失败 3 次,或返回风控、权限类错误码(如
ACQ.ACCESS_FORBIDDEN、ACQ.SELLER_BEEN_BLOCKED一类),自动关闭当面付 6 小时,页面隐藏这个选项并通知金钻;之后由后台手动恢复。 - 控制节奏。 同一买家(同一 IP 或同一订单)10 分钟内最多生成 3 个二维码;全站同时未付款的当面付二维码不超过 20 个,超过就只给爱发电。
- 控制金额。 设单笔上限(建议 500 元),大单只走爱发电。
- 交易信息真实一致。 商品名、金额、订单号都是真实的,不伪装成线下消费;不使用营销类字眼。
- 留证。 每笔交易保留订单号、皮肤、成品和小票,被要求补材料或申诉时拿得出交易真实性证明。
- 定期提现。 当面付的钱实时进入支付宝余额,定期转出,降低冻结时的损失。
05 ④ 订单状态机
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)仍然是订单上的标记,不是状态。
支付单状态
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 付款区交互
- 提交订单后,付款区显示应付金额,以及两个选项:「爱发电付款(推荐)」和「支付宝扫码」。当面付熔断或金额超限时,只显示爱发电。
- 选爱发电:手机直接跳转;电脑显示专链二维码,并附「在本机打开」的链接。
- 选支付宝:显示二维码和倒计时;过期后显示「重新生成」。
- 付款期间页面自动轮询,到账后直接切到「已到账 · 排队中」,不需要买家点任何按钮。
- 「我已经付好了」改成「付好了没反应?」:点了立即对账,找不到再给「呼叫金钻」。
- 订单页始终能看到订单号和取件链接;不再附送未激活的卡密。
09 迁移与删除项
迁移
- 上线时现存的
unpaid订单:为每单补建一条爱发电支付单,pay_id就用订单号本身(旧专链里的custom_order_id本来就是订单号),老链接付款照样能对上。 - 现存的
paid订单(买家申报过):全部列进待办,人工逐笔核对后激活或关闭。 - 已有的爱发电账本(
payplatform-orders)保留只读,作为历史对账依据。
删除
- 回调里的「留言含兑换码」「留言含订单号」「金额唯一匹配」三层猜测。
- 网页单提交时生成的未激活卡密(凭证统一为订单号 + 取件码)。
- 没有页面在用的旧接口
/api/activate、/api/activate-payplatform。 - 订单状态
paid。
10 分阶段实施
| 阶段 | 内容 | 上线标准 |
|---|---|---|
| 一 · 骨架 + 爱发电全自动 | 支付单与流水表、渠道接口、settle_payment()、爱发电验签和精确反查、对账任务、超时关单、closed 状态、页面轮询、迁移脚本 |
测试覆盖:重复回调、回调丢失、伪造回调、金额不足、重复付款、迟到付款、并发到账;在测试环境用真实小额爱发电订单跑通一次 |
| 二 · 当面付 | 当面付渠道、二维码页、异步通知、轮询查单、关单、熔断、节奏和金额限制 | 先用支付宝沙箱跑通全部用例,再用正式应用付 0.01 元验证一次后开放 |
| 三 · 后台与清理 | 支付待办、按流水号认领、退款按钮、渠道开关、日对账报告;删除旧逻辑和旧接口 | 后台各操作都有确认步骤和操作记录 |
每个阶段沿用现在的上线方式:先备份,队列为空时重启;前端单独上线,可随时回滚。
11 待金钻确认
- 爱发电开发者后台的签名公钥(验签用),并确认有一个「自选金额」方案可承载
custom_price。 - 支付宝开放平台当面付应用:AppID、应用私钥(服务器生成后由他上传公钥)、支付宝公钥、异步通知地址。
- 时间参数是否按建议值:二维码 15 分钟、订单保留 24 小时、迟到宽限 72 小时。
- 当面付单笔上限:建议 500 元。
- 付款区默认推荐哪个渠道:建议爱发电。
- 现存的「已申报付款」订单由谁、何时核对。
附 原型(测试环境)
为验证上面的流程,按本设计做了一个可运行原型。它只是测试环境,和正式站完全隔离:
- 部署在甲骨文预览机(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 验签;产品定位为线下收银)。