docs(pay): 地址池收款模型 plan(折中方案,#34/34A)

从每单唯一 HD 地址改为地址池复用(池=峰值并行度、复用摊薄激活/归集)。规则:最小编号
idle 绑单/无 idle 派生/15min 超时释放/同用户单订单。核心安全点:地址复用迟到付款错配
→ 匹配按 tx+金额+时间戳(晚于建单)、每单唯一金额、孤儿付款记录。双产物 md+html,登记 index。
待用户确认后执行(tier-1)。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
wangjia
2026-07-09 14:44:22 +08:00
parent fd285708c7
commit 5055afdbd7
3 changed files with 211 additions and 0 deletions
+30
View File
@@ -44,6 +44,11 @@
</div>
<h2>设计方案 / Specs</h2>
<a class="doc" href="payment-reseller-fulfillment-design.html">
<div class="t">支付落地方案 · 发卡/Reseller 收款 + 激活码自动发货 <span class="tag html">HTML</span></div>
<div class="d">把「收钱」与品牌 VPN 主体解耦:收款外包给发卡平台/Reseller(他们承担支付宝/微信跑分、冻卡、跑路风险),你只交付「激活码」;客户端/用户中心只认码,codes 模块核销即生效。含完整流程图(钱流/码流/结算)、两种对接模型(A 预充卡密库存 / B API 实时签发 POST /v1/codes/issue)、三阶段落地节奏、对账与风险边界(主体永不碰跑分/中国支付)。灰产“付完秒发货”体验的合规化替身。</div>
<div class="path">docs/payment-reseller-fulfillment-design.html</div>
</a>
<a class="doc" href="cicd-design.html">
<div class="t">CI/CD 全流程(tag 触发编译/发版/部署)<span class="tag html">HTML</span></div>
<div class="d">#30。参考 jiu 的 scripts/ci + .gitea/workflowstag 触发(site-v*/server-v*/client-v*)→ 编译 → 测试 → Gitea release → 部署。runner 混合(nas=官网+服务端容器化 / mac=Android+macOS / windows=Windows)。服务端部署固化 F3/F4「备份→migrate→换二进制→重启→健康检查+回滚」;官网部署 pangolin.yanmeiai.com;客户端 apk/dmg/exe 挂 release 喂官网下载链接。密钥作用域:Apple/token 账户级、部署 key/Android keystore 仓库级。范围 A~F(排除 iOS/#26/#25)。</div>
@@ -86,6 +91,26 @@
</a>
<h2>实现计划 / Plans</h2>
<a class="doc" href="pay-address-pool-plan.html">
<div class="t">pangolin-pay 地址池收款模型(折中方案,#34/34A)<span class="tag html">HTML</span></div>
<div class="d">阅读版;执行真相源 <code>docs/superpowers/plans/2026-07-09-pay-address-pool.md</code>(含 checkbox)。从"每单唯一 HD 地址"改为<b>地址池复用</b>:池大小=峰值并行度(初始 10,不够动态派生),地址复用摊薄激活/归集,归集成本 O(订单数)→O(池大小)。规则:最小编号 idle 绑单、无 idle 派生新址、15min 超时释放、同用户单订单。核心安全点:地址复用的<b>迟到付款错配</b>——匹配按"到账 tx+金额+时间戳(晚于建单)"、每单唯一金额、孤儿付款记录。5 Phase:数据模型→建单→watcher 匹配/释放/孤儿→归集(能量租赁)→并发/复用真链验证。</div>
<div class="path">docs/pay-address-pool-plan.html · 真相源 docs/superpowers/plans/2026-07-09-pay-address-pool.md</div>
</a>
<a class="doc" href="crypto-tx-engine-plan.html">
<div class="t">pangolin-pay 加密货币交易引擎(#34 第一块,可独立验证)<span class="tag html">HTML</span></div>
<div class="d">阅读版;执行真相源 <code>docs/superpowers/plans/2026-07-09-crypto-tx-engine.md</code>(含 checkbox)。#34 里"加密货币交易"核心的独立可执行件:钱包(两套助记词 A 运营/B 金库,离线生成、热服务只持 xpub)→ Go 服务 pangolin-pay HD 派生收款地址(对齐 Ian Coleman)→ TronGrid watcher 侦测 TRC20 到账(每单唯一地址+金额、确认、幂等)→ 归集 sweep(离线签名、TRON gas 两步/能量租赁)→ 真实 1 USDT 端到端验证。不含独角数卡/发码,跑通后再接门面。</div>
<div class="path">docs/crypto-tx-engine-plan.html · 真相源 docs/superpowers/plans/2026-07-09-crypto-tx-engine.md</div>
</a>
<a class="doc" href="payment-clean-usdt-plan.html">
<div class="t">收款闭环 · 独角数卡 + 自托管 USDT(TRC20) + webhook JIT#34<span class="tag html">HTML</span></div>
<div class="d">阅读版;执行真相源 <code>docs/superpowers/plans/2026-07-09-payment-clean-usdt-loop.md</code>(含 checkbox)。最干净长期方案:门面独角数卡(独立海外 VPS)+ 自托管 TRC20 HD 钱包(热服务只持 xpub、watch-only,绝不持私钥)+ 自建 TronGrid watcher(每单唯一地址侦测到账)+ webhook JIT 发码(新增控制面 <code>POST /internal/codes/mint</code>,HMAC,售出才产合法码)。复用已就绪 codesredeem/批次/webhook)。6 Phase:钱包 → watcher → mint 端点 → 独角数卡 epay+API提货对接 → 部署/归集/变现/对账 → 端到端验证。全程无跑分、收款终点自托管、变现出金 US LLC。</div>
<div class="path">docs/payment-clean-usdt-plan.html · 真相源 docs/superpowers/plans/2026-07-09-payment-clean-usdt-loop.md</div>
</a>
<a class="doc" href="payment-a-selfhosted-store-plan.html">
<div class="t">方案A · 自建发卡网(独角数卡)落地细化 <span class="tag html">HTML</span></div>
<div class="d">门面自建(独角数卡,独立 VPS 隔离部署)+ USDT 收款 + 激活码自动发货。<b>关键:后端已就绪</b>——发卡店回调 <code>POST /webhook/store/codes</code>HMAC+时间戳+nonce 防重放)、兑换 <code>POST /v1/redeem</code>(JWT)、批次生成/导出/作废均在 server/internal/codes。含拓扑图、两种发货模型(A 预充卡密零胶水 / B webhook JIT 更安全,待补 /internal/codes/mint 单源产码)、SKU 映射、USDT 两条接入路子、落地步骤与风险边界。</div>
<div class="path">docs/payment-a-selfhosted-store-plan.html</div>
</a>
<a class="doc" href="frontend-ds-refactor-plan.html">
<div class="t">前端设计系统治理重构(ds-flow 全端)<span class="tag html">HTML</span></div>
<div class="d">阅读版;执行真相源 <code>docs/superpowers/plans/2026-07-07-frontend-ds-refactor.md</code>(含 checkbox)。用 ds-flow 把 Flutter 五端 + 官网 + 用户中心收口到「设计单源·代码镜像·静态闸拦漂移·golden/fidelity 双级像素验收兜底」。<b>非从零 bootstrap(已约 65% 达标)</b>:补原型三件套(atoms.css/icons.js/index.html 登记页)+ Web 共享原子层去重(各自实现+同源闸)+ 硬编码色/fidelity 闸 + 启用 pre-commit。6 阶段:CLAUDE.md → 原型单源 → Web token 同源 → Web 原子对齐 → Flutter golden 补齐 → 闸挂满。主题保持 light/dark。</div>
@@ -128,6 +153,11 @@
</a>
<h2>知识库 / 调研</h2>
<a class="doc" href="payment-channels-overview.html">
<div class="t">支付渠道选型总览 <span class="tag html">HTML</span></div>
<div class="d">各支付渠道候选与甄别标准(研究起点,非背书)。核心心智:「发卡平台」= 门面 × 通道两层分离,灰/干净分水岭在通道不在门面。候选 A 自建发卡网(独角数卡/acg-faka/KamiFaka)· B 加密网关(NOWPayments/Cryptomus/CoinGate)· C 自建 USDT 监听(TronGrid)· D 官方鹅(TG Stars/IAP)· E 支付宝微信第三方(跑分层,不列名单)。含决策矩阵 + 尽调清单 + 推荐起步组合(独角数卡+USDT)。</div>
<div class="path">docs/payment-channels-overview.html</div>
</a>
<a class="doc" href="frontend-overview.html">
<div class="t">前端全景(ds-flow 设计系统治理)<span class="tag html">HTML</span></div>
<div class="d">Flutter 五端 + 官网 + 用户中心的设计系统治理全景:一次 UI 改动标准路径、目录地图、三层真相源模型、令牌 codegen、四道静态闸「违规谁拦」、像素验收(golden 双主题 + fidelity 待建)、响应式五端、规则速查。原型单源 design/prototype/tokens/atoms/icons/index.html)、check-ds/check-l1-sync/check_ds_code/codegen-drift 四闸进 CI、golden 全量 34 绿含 CJK。</div>
+110
View File
@@ -0,0 +1,110 @@
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>pangolin-pay 地址池收款模型 实现计划</title>
<style>
:root{
--bg:#0f1117; --panel:#171a22; --panel2:#1d2129; --fg:#e6e8ee; --fg2:#a8afbd;
--accent:#e0884f; --accent2:#5fb0c9; --ok:#5ec27a; --bad:#e06a6a; --warn:#e0b84f;
--border:#272c36; --mono:"SF Mono",ui-monospace,Menlo,Consolas,monospace;
--sans:-apple-system,"PingFang SC","Helvetica Neue",Arial,sans-serif;
}
*{box-sizing:border-box}
body{margin:0;background:var(--bg);color:var(--fg);font-family:var(--sans);line-height:1.7;font-size:15px}
.wrap{max-width:960px;margin:0 auto;padding:48px 24px 96px}
h1{font-size:28px;line-height:1.3;margin:0 0 8px}
.sub{color:var(--fg2);font-size:15px;margin:0 0 32px}
h2{font-size:20px;margin:40px 0 12px;padding-bottom:8px;border-bottom:1px solid var(--border);color:var(--accent)}
p{margin:10px 0}
code{font-family:var(--mono);font-size:.85em;background:var(--panel2);padding:1px 6px;border-radius:5px;color:#f0d9c4}
pre{background:#0a0c11;border:1px solid var(--border);border-radius:10px;padding:14px 16px;overflow-x:auto;font-family:var(--mono);font-size:12.5px;line-height:1.5;color:#cdd3df}
.tag{display:inline-block;font-size:12px;font-weight:600;padding:2px 9px;border-radius:999px}
.tag.info{background:rgba(95,176,201,.16);color:var(--accent2)}
ul.ck{list-style:none;padding-left:4px}
ul.ck li{position:relative;padding-left:26px;margin:7px 0}
ul.ck li::before{content:"☐";position:absolute;left:0;color:var(--fg2)}
ul{padding-left:22px} li{margin:6px 0}
.lead{background:linear-gradient(180deg,rgba(224,136,79,.10),transparent);border:1px solid var(--border);border-radius:12px;padding:18px 20px;margin:0 0 8px}
.small{color:var(--fg2);font-size:13px}
a{color:var(--accent2)} .back{display:inline-block;margin-bottom:24px;font-size:13px}
b{color:#fff}
.warnbox{background:rgba(224,106,106,.08);border:1px solid rgba(224,106,106,.35);border-radius:12px;padding:14px 18px;margin:14px 0}
.warnbox b{color:var(--bad)}
table{width:100%;border-collapse:collapse;margin:16px 0;font-size:13.5px}
th,td{text-align:left;padding:9px 12px;border-bottom:1px solid var(--border);vertical-align:top}
th{color:var(--fg2);font-weight:600;font-size:13px}
</style>
</head>
<body>
<div class="wrap">
<a class="back" href="index.html">← 文档索引</a>
<h1>pangolin-pay 地址池收款模型</h1>
<p class="sub">2026-07-09 · <span class="tag info">阅读版</span> · 执行真相源 <code>docs/superpowers/plans/2026-07-09-pay-address-pool.md</code> · #34/34A 收款模型修订(折中方案)</p>
<div class="lead">
从"每单唯一 HD 地址"改为<b>地址池复用</b>:池大小 = <b>峰值并行度</b>(初始 10,不够动态派生),地址复用摊薄激活/归集成本;仍多地址,<b>避免并发订单金额撞、对账精确</b>。归集成本从 O(订单数) 降到 <b>O(池大小)</b>,激活一次/地址即长期复用。是"单地址(省钱撞单)"与"每单唯一(精确但贵)"的折中。
</div>
<div class="warnbox">
<b>核心风险 · 地址复用的迟到付款错配:</b>地址回收后绑给新订单,若前一个用户超时后才付款,钱打到已绑新订单的地址上 → 可能误配。<b>解法(必须):</b>① 匹配按"到账 tx + 金额 + 时间戳(晚于建单)",<b>不按余额、不只按地址</b>;② <b>每单唯一金额</b>(基准+唯一尾数);③ 匹配不到活跃订单的到账 → 记 <code>orphan_payments</code> 人工对账;④(可选)超时后地址冷却再重绑。
</div>
<h2>设计(规则 + 安全点)</h2>
<ul>
<li><b>地址池</b>:HD 派生地址(<code>m/44'/195'/0'/0/i</code>),状态 <code>idle|busy</code>,初始 10。</li>
<li><b>建单</b>:绑<b>最小编号 idle</b> 地址→busy;无 idle → 派生新地址入池。<b>原子</b>(事务/行锁,防并发抢同址)。</li>
<li><b>每单唯一金额</b> ⭐:基准 + 唯一尾数,当前活跃订单间不撞;复用地址上旧单迟到付款不误配新单。</li>
<li><b>15min 超时</b> → expired → 地址回 idle(可选冷却)→ 提示重建订单。</li>
<li><b>付款完成</b> → paid → 地址回 idle(注意:地址里仍有 USDT 待归集,idle 只表示可重绑)。</li>
<li><b>匹配</b>:找"到该地址 + 金额命中 + 区块时间晚于建单"的转入 tx。</li>
<li><b>同用户单订单</b>:同时只能一个活跃订单。</li>
<li><b>归集</b>:定期扫池内有余额地址→冷钱包(能量租赁 ~$0.1–1/笔);池 ~10,笔数有界;与 busy 解耦。</li>
</ul>
<h2>Phase A — 数据模型</h2>
<ul class="ck">
<li><b>A.1</b> <code>addresses(id, addr_index唯一, address, state, activated, created_at)</code>,按需派生入池。</li>
<li><b>A.2</b> <code>pay_orders</code><code>user_ref / address_id / expect_amount(唯一金额) / matched_tx_id</code></li>
<li><b>A.3</b> <code>orphan_payments(tx_id唯一, address, value, block_ts, handled)</code></li>
<li><b>A.4</b> 复用 addr_cursor 派生新址;迁移 + 索引(status/address/user_ref)。</li>
</ul>
<h2>Phase B — 建单</h2>
<ul class="ck">
<li><b>B.1</b> CreateOrder(user, sku):校验同用户无活跃单 → 原子选最小 idle 置 busy(无则派生)→ 分配唯一金额 → 写 pending(TTL 15min)。</li>
<li><b>B.2</b> 唯一金额分配(基准+唯一尾数,当前活跃单间不撞)。</li>
<li><b>B.3</b> GetOrder + releaseAddress 公共方法(paid/expired 复用)。</li>
</ul>
<h2>Phase C — watcher(匹配/释放/孤儿)</h2>
<ul class="ck">
<li><b>C.1</b> 匹配:pending 单查其地址转入,value 命中唯一金额 且 <code>block_ts&gt;created</code> → paid + 记 tx + 释放地址。</li>
<li><b>C.2</b> 超时:pending 过期 → expired + 释放地址(可选冷却)。</li>
<li><b>C.3</b> 孤儿:匹配不到活跃订单的到账 → 记 orphan_payments(去重)。</li>
<li><b>C.4</b> 幂等(tx_id 去重)+ 崩溃恢复;TronGrid 取 block_timestamp 供时间过滤。</li>
</ul>
<h2>Phase D — 归集</h2>
<ul class="ck">
<li><b>D.1</b> 扫池内有余额地址 → 冷钱包(能量租赁,先手动 runbook);与订单状态解耦。</li>
</ul>
<h2>Phase E — 测试 + 真链</h2>
<ul class="ck">
<li><b>E.1</b> 单测:并发不抢同址、复用后迟到付款不误配、唯一金额、超时释放、孤儿、幂等、崩溃恢复、同用户单订单。</li>
<li><b>E.2</b> 真链:两并发订单各绑地址付款;一单超时释放后新单复用同址,旧地址补"旧金额"付款应成孤儿不误配;归集。</li>
</ul>
<h2>不在本轮 / 取舍</h2>
<ul>
<li>GasFree(#35,免 TRX 但每笔固定 1 USDT,更适合少地址批量,另议)。</li>
<li>能量租赁自动化(先手动);池增长上限(先宽松);发货侧(独角数卡 + /internal/codes/mint)另排。</li>
</ul>
<p class="small" style="margin-top:32px">相关:<a href="crypto-tx-engine-plan.html">加密货币交易引擎(已实现钱包/tron/sweep)</a> · <a href="payment-clean-usdt-plan.html">#34 收款闭环全景</a></p>
</div>
</body>
</html>
@@ -0,0 +1,71 @@
# pangolin-pay 地址池收款模型(折中方案,取代"每单唯一 HD 地址")
> #34/34A 收款模型修订。**Context**:每单唯一 HD 地址 → 每地址激活(~1 TRX)+ 归集(每笔一次转账)成本随
> **订单总数线性增长**(#34 暴露的严峻成本)。改为**地址池复用**:池大小 = **峰值并行度**(初始 10,不够动态派生),
> 地址**复用**摊薄激活/归集;仍是多地址,**避免并发订单金额撞、对账精确**。这是"单地址(省钱但撞单)"与
> "每单唯一(精确但贵)"的折中。
>
> 归集成本从"O(订单数)"降到"O(池大小)";激活成本一次性(每个池地址激活一次即长期复用)。
>
> **本 plan = 用户定的规则 + 补齐的安全点**(核心:地址复用的**迟到付款错配**)。已实现的 Phase B(钱包派生)、
> tron(TronGrid 读到账/建/广播/签名)、cmd/sweep 复用;主要改 store / pay(建单)/ watcher(匹配)。
## 设计(规则 + 安全点)
- **地址池**:HD 派生地址(路径 `m/44'/195'/0'/0/i`,与现有一致),各有状态 `idle | busy`。初始池 10。
- **建单**:绑**最小编号的 idle** 地址 → 置 `busy`;**无 idle → 派生下一个新地址**(编号递增)入池并绑之。
- **每单唯一金额** ⭐必需:基准价 + 唯一尾数(如按订单序号映射的微分),保证**当前活跃订单之间金额不撞**,
且复用地址上"旧订单迟到付款"不会误配"新订单"。
- **15 分钟超时**:超时 → `expired` → 地址回 `idle`(可选**冷却期**再重绑,降低迟到错配)→ 提示用户**重建订单**、用新订单地址付款。
- **付款完成**:watcher 确认到账 → 订单 `paid` → 地址回 `idle`。**注意**:此时地址里**仍有 USDT**(待归集);
`idle` 只表示"可重绑",不代表钱清了。
- **匹配规则(核心)**:watcher 找**到该地址、金额 == 该单唯一金额(或 ≥,带容差)、且到账区块时间晚于订单创建**
的 TRC20 转入 **tx** → 匹配。**绝不按余额、不只按地址**(地址会累积余额、会复用)。
- **同用户单订单**:同一用户同时只能有**一个**活跃(pending)订单。
- **孤儿付款**:到账 tx 匹配不到任何活跃订单(迟到 / 欠额 / 误差)→ 记 `orphan_payments`,人工对账/补发。
- **归集**:定期扫池内**有余额**的地址 → 冷钱包(**能量租赁** ~$0.11/笔);池 ~10 地址,**归集笔数有界**;
归集与 `busy` 无关(随时可扫,不影响待付订单——到账是未来的独立 tx)。
- **池增长上限**(可选):无空闲就新建,设上限防滥用无限增长(超限则排队/拒单)。
## Phase A — 数据模型改造
- [ ] `addresses` 表:`id / addr_index(唯一) / address / state('idle'|'busy') / activated(bool) / created_at`;初始不预建,按需派生入池。
- [ ] `pay_orders` 改:加 `user_ref`(同用户单订单约束用)、`address_id`(绑定的池地址)、`expect_amount`(唯一金额,micro-USDT)、`matched_tx_id`;保留 status/created_at/expires_at。
- [ ] `orphan_payments` 表:`tx_id(唯一) / address / value / block_ts / created_at / handled(bool)`
- [ ] 复用现有 `addr_cursor`(HD 派生游标)派生新池地址。迁移脚本 + 索引(status、address、user_ref)。
## Phase B — 建单(pay 服务)
- [ ] `CreateOrder(userRef, sku)`:① 校验**同用户无活跃订单**(有则返回现有/拒);② **原子**选最小编号 `idle` 地址(事务 + 行锁)置 `busy`;③ 无 idle → `NextAddrIndex` 派生新地址(`AddressFromAccountXpub`)入池并绑;④ 分配**唯一金额**;⑤ 写 `pending` 单(TTL 15min)。
- [ ] **唯一金额分配**:基准金额 + 唯一尾数,保证与**当前所有活跃订单**不撞(可用订单序号 → 尾数微分,micro-USDT 级);记录基准+尾数便于展示。
- [ ] `GetOrder`;释放地址的公共方法 `releaseAddress(addrID)`(paid/expired 复用)。
## Phase C — watcher 改造(匹配 + 释放 + 孤儿)
- [ ] **匹配**:对每个 `pending` 单,查其绑定地址的 TRC20 转入;筛 `value` 命中唯一金额(==,或 ≥ 带小容差)**且 `block_ts > order.created_at`** → `paid` + 记 `matched_tx_id`;**释放地址 → idle**。
- [ ] **超时**:`pending` 过期 → `expired` + 释放地址 → idle(可选冷却期后才允许重绑)。
- [ ] **孤儿**:遍历池地址的到账 tx,凡匹配不到任何活跃订单的转入 → 写 `orphan_payments`(去重 by tx_id)。
- [ ] **幂等**(tx_id 全局去重,含 orphan)、崩溃恢复(从 DB pending + 池状态重建)。TronGrid 需能取到账时间戳(`block_timestamp`)用于时间过滤。
## Phase D — 归集(复用 cmd/sweep)
- [ ] 扫池内**有余额**地址 → 冷钱包;接**能量租赁**(先手动 runbook,后续自动化);归集与订单状态解耦。
- [ ] 归集不清空 `busy` 语义;只搬余额。runbook 写清"哪些地址、多久扫一次、能量怎么租"。
## Phase E — 测试 + 真链验证
- [ ] 单测:并发建单**不抢同址**(原子性)、地址**复用后旧订单迟到付款不误配新订单**(唯一金额+时间戳)、唯一金额不撞、超时释放、孤儿记录、幂等、崩溃恢复、同用户单订单约束。
- [ ] 真链:两并发订单各绑不同地址各自付款到 paid;一单超时释放后新单**复用同址**,再对旧地址补一笔"旧金额"付款 → 应成**孤儿**、不误配新单;归集池地址到冷钱包。
## Verification / 判据
- `go test ./...`(store/pay/watcher 新逻辑全绿,重点覆盖复用错配)。
- 真链:并发 + 复用 + 迟到付款三场景表现正确;归集笔数 = 有余额的池地址数(有界)。
- 成本:激活一次/地址、归集 O(池大小);对小额高频订单不再被激活费线性拖累。
## 不在本轮 / 取舍
- GasFree(#35,免 TRX 但每笔固定 1 USDT,更适合少地址批量,另议)。
- 能量租赁自动化(先手动)。
- 池增长上限/排队(先不设,或设一个宽上限)。
- 发货侧(独角数卡 + /internal/codes/mint)另排。