收款闭环 · 独角数卡 + 自托管 USDT(TRC20) + webhook JIT 发码

2026-07-09 · 阅读版 · 执行真相源 docs/superpowers/plans/2026-07-09-payment-clean-usdt-loop.md（带 checkbox）· #34（tier-1）

目标：把「下单 → USDT 付款 → 自动发激活码 → 客户端/用户中心兑换 → 订阅生效」端到端打通，全程自托管、售出才发码、无跑分、无第三方支付主体。
关键前提（已摸底）：激活码后端大半已就绪——POST /v1/redeem（兑换，幂等+限频）、批次生成/导出、发卡店回调 /webhook/store/codes（HMAC+时间戳+nonce）都在。本方案新增核心只有一个后端端点（JIT 发码 /internal/codes/mint）+ 一个独立收款服务 pangolin-pay（TronGrid watcher + epay 支付口）。

三大组件 / 数据流

买家 ──下单──▶ 独角数卡(门面, 独立 VPS)
                   │ 建单 + epay 跳转
                   ▼
           pangolin-pay(自建收款服务, 同 VPS)
             ├ 派生每单唯一 TRC20 收款地址 (watch-only, 只持 xpub)
             ├ TronGrid watcher 轮询到账 + 确认
             └ 到账 ──epay notify──▶ 独角数卡「已支付」
                       │
                       ▼ 独角数卡 API-提货
           pangolin-pay /issue ──HMAC──▶ pangolin 控制面 POST /internal/codes/mint
                                             └ 生成合法码 + 存 unused + 返回明文
                       │
                       ▼ 独角数卡把码交付买家
买家 ──输码──▶ 客户端/用户中心 POST /v1/redeem ──▶ 订阅生效

安全红线（贯穿全程）：① 热服务 pangolin-pay 只持 xpub 派生收款地址、绝不持私钥（能收不能转，脱库也转不走钱）；② 私钥/助记词冷备 + Bitwarden，不入 git、不上热机；③ 收款终点=自托管钱包，变现经交易所出金 US LLC，记账走 accounting；④ 全程不碰跑分/中国支付。部署在独立海外小 VPS，不放 pangolin1（内存紧 + 风险隔离），只经 HTTPS+HMAC 与控制面 api.yanmeiai.com 通信。

已就绪 vs 本轮新增

能力	状态
`POST /v1/redeem` 兑换（幂等+限频+账户锁）	已实现
批次生成/导出（Crockford Base32 75-bit 带校验位，只存 hash）	已实现
发卡店回调 `/webhook/store/codes`（HMAC+时间戳+nonce）	已实现（留给未来第三方发卡店）
`POST /internal/codes/mint` JIT 发码	本轮新增
`pangolin-pay`：TronGrid watcher + epay 支付口	本轮新增
自托管 TRC20 HD 钱包 + 归集/变现 runbook	本轮新增

Phase 0.5 — 钱包选型（用哪个钱包）

先厘清：这套架构的「钱包」是两件事，别当成装一个 app。

主种子（钱在哪）：一套 BIP39 助记词，冷存。资产本体。
watcher 收款：热服务用库从 account xpub（公钥）派生每单地址——watch-only，不是钱包 app，拿不到私钥。
归集签名：动钱时在冷端用私钥离线签 sweep 交易。

所以「用哪个钱包」= 选 ① 主种子怎么冷存 + ② watcher 用哪个派生库。

① 主种子 / 冷存候选

方案	冷存安全	xpub 导出	归集签名	结论
离线生成助记词 + 库派生推荐	高（纸/钢板离线，永不联网）	从种子导 account xpub	离线机用库签	最贴合 watch-only 架构、最灵活
Ledger 硬件钱包（可叠加）	最高（私钥不出设备）	可导 account 公钥（需工具）	插 Ledger 签	想再加一层硬件冷存就用它兜底
TronLink / imToken / Trust（手机热钱包）	低（热钱包）	不便批量派生	app 内签	不推荐当收款主钱包

② watcher 派生库候选（给热服务 watch-only 派生，非钱包）

语言	库
Go（与 server 同栈，推荐）	`tyler-smith/go-bip39` + `btcd/btcutil/hdkeychain`（BIP32）→ 公钥转 TRON base58 地址；或成熟 TRON Go SDK
Python	`tronpy` + `bip_utils`（一步派生 TRON 地址）

推荐：主种子用离线生成 BIP39 助记词（想再稳叠一层 Ledger 冷存）；watcher 用 Go 库从 account xpub watch-only 派生（与 server 同栈、好集成、热机无私钥）。收款钱包 = 你自己的 HD 种子，不是某个 app。

0.5.1 定主种子方案：离线助记词（推荐）/ 是否叠加 Ledger 冷存；记录选型。
0.5.2 定 watcher 派生库（Go bip39+hdkeychain→TRON / Python tronpy+bip_utils），跑通派生并与钱包 app 交叉核对同一地址（防派生不一致收不到钱）。
0.5.3 定归集冷签工具（离线机脚本 / Ledger），确认能对 sweep 交易离线签名。

Phase 1 — 自托管钱包（TRC20 HD，watch-only 收款）

一套助记词派生无限个收款地址；热服务只拿 xpub 派生地址收款、拿不到私钥；私钥冷备用于归集。

1.1 离线生成 BIP39 助记词（24 词），TRON 派生路径 m/44'/195'/0'/0/i（195=TRON）。工具：离线机 tronpy/tronweb 或硬件钱包（Ledger 导出 xpub），生成不联网。
1.2 密钥分级：助记词/私钥→冷备+Bitwarden（永不上热机）；account xpub→给 pangolin-pay watch-only 派生；HMAC secret→Bitwarden。
1.3 定冷钱包归集地址 + 记 USDT-TRC20 合约地址（主网 TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t，核对无误再写死）。
1.4 备少量 TRX 作归集 gas（TRON 转账吃 energy/bandwidth）。
1.5 验证：xpub 离线派生前 5 地址；往 index 0 打 1 USDT 测试，确认 watch-only 查得到。

Phase 2 — pangolin-pay：TronGrid watcher（自建收款侦测）

2.1 建 Go 服务 pangolin-pay（自带轻量 SQLite）。
2.2 数据模型：pay_orders(order_no, sku, plan, duration_days, addr_index, address, expect_amount, status, tx_id, confirmations, created_at, expires_at) + addr_cursor(next_index)。
2.3 每单唯一地址：建单时从 xpub 派生 m/.../0/next_index（最准，免金额撞车）。次选单地址+唯一金额。
2.4 TronGrid 轮询：GET /v1/accounts/{addr}/transactions/trc20?only_confirmed=true&contract_address=<USDT>，比对 to/token/金额（含容差）。
2.5 确认：只认已固化交易或等 ≥N 区块（约 1 分钟）→ status=paid + 记 tx_id。
2.6 到账触发发货；幂等：同 tx_id 只认一次、一单只发一次。
2.7 超时（默认 15min）→ expired、释放地址（不复用，避免串单）。
2.8 TronGrid key + 限流退避 + 重试；崩溃可从 DB 未决单恢复。
2.9 测试：mock TronGrid → 金额匹配/确认门槛/超时/幂等/恢复。

Phase 3 — 控制面：JIT 发码端点 `POST /internal/codes/mint`

付款确认时即时生成一个合法码——这才是 webhook JIT 的落点：售出才产码、才有效。自建场景由 pangolin 产码（保证格式+校验位单源），比让外部产码更干净。

POST /internal/codes/mint            # /internal 组, 无 JWT, HMAC 同 webhook
Headers: X-Pangolin-Signature: sha256=<hmac> · X-Pangolin-Timestamp(±5min) · X-Pangolin-Nonce
Body:    { "plan":"pro", "duration_days":365, "order_ref":"<独角数卡订单号>" }
→ 200   { "code":"PGL-XXXX-...", "expires_at":"..." }   # 以 order_ref 幂等, 同单返同码

3.1 新增端点，HMAC+时间戳+nonce（复用 webhook 那套验签，抽公共中间件）。
3.2 复用 codes.GenerateCode() 产码 + Store.CreateCode 存 unused（channel=ChannelStore）→ 返回明文。
3.3 幂等：order_ref 为幂等键（存 order_ref→code_hash），同单重放返回同一码。
3.4 secret → Bitwarden → server.env（CODES_MINT_HMAC_SECRET）；main.go 挂路由。
3.5 保留现有 /webhook/store/codes 供未来第三方发卡店。
3.6 测试：验签/时间戳/nonce/order_ref 幂等/产码格式。

Phase 4 — 独角数卡对接（门面 + 自动发货）

4.1（研究·先做）摸清所用独角数卡版本的 epay 支付接口 + API-提货/自动发货商品机制（版本相关，实测出对接点清单再实现）。
4.2 pangolin-pay 实现 epay 兼容支付接口：独角数卡建单 → 跳我方支付页（USDT 地址+应付金额+倒计时+TRC20 强提示）。
4.3 到账 → 按 epay 规范 notify 独角数卡（签名）→ 标「已支付」。
4.4 商品设 API-提货：发货时调 pangolin-pay /issue → 内部 HMAC 调 /internal/codes/mint 取码 → 交付买家。
4.5 SKU 映射表（配置化）：独角数卡商品 → plan+duration_days（Pro 月/年、Team 月/年；对齐官网 Pricing）。
4.6 幂等贯通：独角数卡 order_no 作为 order_ref 一路透传到 mint，一单一码。

Phase 5 — 部署 · 运维 · 安全

5.1 独立海外小 VPS（2C/2G）部署：独角数卡（Docker）+ pangolin-pay + 域名 + HTTPS（不放 pangolin1）。
5.2 密钥落位核对：pangolin-pay 只有 xpub + TronGrid key + epay 签名密钥 + mint HMAC secret，无私钥/助记词（冷备）。全 Bitwarden。
5.3 归集 runbook：定期把各收款地址 USDT sweep 到冷钱包（离线签名），备 TRX gas。
5.4 变现 runbook：冷钱包 → 交易所（能出金 US LLC 的）→ 卖 USDT→USD → 银行；记账交 accounting agent。
5.5 监控告警（接现有 Telegram）：watcher 存活、TronGrid 配额、到账延迟、mint 失败、订单堆积。
5.6 对账：独角数卡订单 ↔ pay_orders ↔ codes（mint/redeem）三方日结，差异告警。

Phase 6 — 端到端验证

6.1 真单闭环：下单→USDT付款→watcher确认→mint码→独角数卡交付→/v1/redeem→订阅生效、全端同步。
6.2 异常路径：超时未付/金额不足/重复付/确认期抖动/mint 重放。
6.3 安全核对：热服务无私钥、密钥不入 git、每单唯一地址不复用、redeem 幂等+限频。

验收判据：后端 go test ./internal/codes/... 含 mint 验签/幂等/格式全绿；pangolin-pay go test 含匹配/确认/超时/幂等/恢复；真机一笔真 USDT 小额单全通 + 异常逐条演练；安全逐项核对。

不在本轮

支付宝/微信第三方通道（E 层，灰产，另议且当可替换插件）。
HD 自动 sweep 归集（先人工离线归集）。
多币种、watcher 高可用、加密网关备选路子（B 方案）。
Telegram Stars / Apple IAP 独立收款口（海外补充，另排）。

相关：支付渠道选型总览 · 方案A 自建发卡网细化 · 发卡+发货架构