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

22 KiB
Raw Permalink Blame History

收款流程重构:从「半自动」到全自助

金钻工坊 · 自助模板渲染 · 设计文档 版本 v1 · 2026-10-07 · 状态:设计稿(正式站代码未改动) · 范围:网页下单的付款与履约 在线版(页面,内容相同):https://claude.ai/artifact/ErKjgvjU9fBipacGpuURuQ

目录


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: 已到账 · 排队中
  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 ③ 当面付辅助通道

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 ④ 订单状态机

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 付款区交互

  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 验签;产品定位为线下收银)。