docs: 支付框架设计(收款流程重构:渠道抽象层 / 爱发电主通道 / 当面付辅助通道 / 状态机 / 对账超时 / 异常兜底 + 原型说明)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
+365
@@ -0,0 +1,365 @@
|
||||
# 收款流程重构:从「半自动」到全自助
|
||||
|
||||
> 金钻工坊 · 自助模板渲染 · 设计文档
|
||||
> 版本 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 验签;产品定位为线下收银)。
|
||||
Reference in New Issue
Block a user