This website requires JavaScript.
0
Issues
Pull Requests
Milestones
Explore
0
Create…
New Repository
New Migration
New Organization
public
Signed in as
public
Profile
Starred
Subscriptions
Settings
Help
Sign Out
public
/
jinzuanwork
Unwatch
1
Star
0
Fork
0
Code
Issues
Pull Requests
Actions
Packages
Projects
Releases
Wiki
Activity
Settings
Files
jinzuanwork
/
docs
/
or
Cancel
Edit File
Preview
Preview Changes
Spaces
Tabs
2
4
8
Wrap
No wrap
# 收款流程重构:从「半自动」到全自助 > 金钻工坊 · 自助模板渲染 · 设计文档 > 版本 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 验签;产品定位为线下收银)。
Commit Changes
Add a Signed-off-by trailer by the committer at the end of the commit log message.
Commit directly to the
main
branch.
Create a
new branch
for this commit and start a pull request.
Commit Changes
Cancel