feat(pay): 同源收款测试页 GET /_test(Phase E 手动闭环验证)

pay-server 自带 /_test 测试页:创建订单→显示收款地址+精确金额(可复制)
+过期倒计时→轮询状态到 paid。同源、无 CORS/CSP 摩擦,不碰营销站安全头;
纯调 POST /order + GET /order/{id},无私钥无密钥。生产收银台后续走独角数卡门面。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs/superpowers/plans/2026-07-09-crypto-tx-engine.md

@@ -0,0 +1,79 @@
+# pangolin-pay 加密货币交易引擎(钱包 + watcher + 收款侦测 + 归集)
+
+> #34 的**第一块、可独立执行、能用真实小额 USDT 端到端验证**的基础件。**只做加密货币的"交易"核心**——
+> 生成/派生地址、侦测链上到账、归集(sweep)——**不含**独角数卡对接、不含 `/internal/codes/mint` 发码
+> (那是"发货侧",本引擎跑通后再接)。
+>
+> **成果物**:一个独立 Go 服务 `pangolin-pay`(部署在独立海外 VPS),对外提供"建单→给收款地址→侦测到账→
+> 标记已付"的 HTTP 接口 + 一套离线归集工具。跑通后,任何门面(独角数卡 / 自建下单页)都能挂上来。
+>
+> **安全铁律(贯穿)**:热服务只持 **xpub**(watch-only 派生地址)+ TronGrid key + 金库收款地址,**绝不持私钥**;
+> 私钥/助记词冷存,归集在离线端签名。参考知识:brain `notes/dev/crypto-hd-wallet-basics.html`。
+>
+> **关键常量(开工核对无误再写死)**:USDT-TRC20 合约 `TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t`(6 位小数);
+> TRON 派生 `m/44'/195'/0'/0/i`;TronGrid `https://api.trongrid.io`。
+
+---
+
+## Phase A — 钱包与密钥(全程离线)
+
+- [ ] A.1 **离线**生成**两套**助记词(断网 Mac 跑 Ian Coleman standalone / `bip_utils`,选 Coin=TRX、24 词、English):
+  - **钱包 A · 运营收款**;**钱包 B · 冷备金库**(另一套,独立冷存)
+- [ ] A.2 导出**钱包 A 的 account xpub**(`m/44'/195'/0'` 的 Account Extended **Public** Key);取**钱包 B 的地址0**(`T...`)当**归集目标**
+- [ ] A.3 冷存:助记词 A/B **分开**手抄/钢板 + Bitwarden;**只把** xpub_A + sweep 地址_B 放进 `pangolin-pay` 配置(Bitwarden 管密钥)
+- [ ] A.4 **交叉核对**:B 阶段的 Go 派生实现算出的地址 0..4,必须与 Ian Coleman 显示的**逐个一致**(防派生实现不一致 → 收款地址对不上 → 收不到钱)
+
+---
+
+## Phase B — 服务骨架 + HD 派生
+
+- [ ] B.1 建 Go 服务 `pangolin-pay`(独立 cmd 或独立仓)。配置:`xpub_A` / `sweep_addr_B` / `TRONGRID_API_KEY` / 确认数 / 订单超时。自带 SQLite
+- [ ] B.2 **HD 派生模块**:`tyler-smith/go-bip39` + `btcsuite/.../hdkeychain` 从 **xpub_A** watch-only 派生 `.../0/i` 公钥 →
+      TRON 地址(公钥 → Keccak-256 取后 20 字节 → 前缀 `0x41` → Base58Check → `T...`)。**单测:派生地址对齐 Ian Coleman(A.4)**
+- [ ] B.3 数据模型:
+  - `pay_orders(order_no PK, sku, expect_amount, addr_index, address, status, tx_id, confirmations, created_at, expires_at)`
+  - `addr_cursor(next_index)` — HD 派生游标,单调递增,地址**不复用**
+
+---
+
+## Phase C — 收款(建单 + 侦测到账)
+
+- [ ] C.1 `POST /order`:入参 `sku`/基准金额 → cursor++ 派生**新收款地址** → 写单(`expect_amount` 做**唯一尾数**去重、`expires=+15min`)→ 返回 `{order_no, address, expect_amount, expires_at}`
+- [ ] C.2 `GET /order/{order_no}`:返回 `status`(pending/paid/expired)+ 到账信息
+- [ ] C.3 **TronGrid watcher**(轮询):对每个 pending 单地址查 TRC20 转入
+  - `GET /v1/accounts/{addr}/transactions/trc20?only_confirmed=true&contract_address=<USDT>&limit=...`(头带 `TRON-PRO-API-KEY`)
+  - 匹配:`to==address` 且 `token==USDT` 且 `value≥expect_amount`(USDT 6 位小数,注意单位换算)且已确认 → `status=paid`、记 `tx_id`
+- [ ] C.4 **幂等**(同 `tx_id` 只认一次)+ **超时** pending→expired(地址不复用)+ **崩溃恢复**(从 DB 未决单继续轮询)
+- [ ] C.5 TronGrid 限流退避 + 重试;测试用 mock TronGrid 覆盖:金额匹配 / 确认门槛 / 超时 / 幂等 / 恢复
+
+---
+
+## Phase D — 归集(sweep,离线签名)
+
+- [ ] D.1 **归集清单**:watcher(xpub)列出有余额地址 `[(index, address, balance)]`
+- [ ] D.2 **gas**:从一个 `gas 钱包`给每个待归集地址打少量 **TRX**(TRC20 转账吃 energy;收款地址无 TRX);量大改**能量租赁**降本
+- [ ] D.3 **离线签名**(离线机,导入**钱包 A 助记词**):派生 `address_i` 私钥 → 构造 TRC20 `transfer(sweep_addr_B, balance)` → **离线签名**
+- [ ] D.4 **广播**:把签好的交易经 TronGrid `POST /wallet/broadcasttransaction` 上链(**只有签名后的交易出门,私钥不出门**)
+- [ ] D.5 半自动脚本(离线端)+ **归集 runbook**;触发=阈值(攒够 X)或定时;热派生地址不长期囤大额
+
+---
+
+## Phase E — 端到端验证(真实小额 USDT)
+
+- [ ] E.1 真单:`POST /order` → 往返回的地址转 **1 USDT(TRC20)** → watcher 侦测 + 确认 → `GET /order` 变 `paid`
+- [ ] E.2 归集:对该地址执行 D 流程 → USDT 到达**钱包 B 冷地址**
+- [ ] E.3 安全核对:`pangolin-pay` 进程/配置**无任何私钥/助记词**(只有 xpub);密钥不入 git(红线扫描);地址不复用
+
+---
+
+## Verification（判据）
+
+- `go test ./...`:HD 派生对齐 Ian Coleman、watcher 匹配/确认/超时/幂等/恢复全绿。
+- 真机:一笔真 1 USDT 从建单→侦测→确认→归集到冷地址全通。
+- 安全:热服务无私钥、密钥不入 git、每单唯一地址不复用——逐项核对。
+
+## 不在本轮
+
+- 独角数卡门面对接 + epay 支付口(下一块:接门面)。
+- `/internal/codes/mint` JIT 发码 + 兑换闭环(发货侧,#34 后续)。
+- HD 自动 sweep(先人工离线归集)、多币种(先只 USDT-TRC20)、watcher 高可用。

docs/superpowers/plans/2026-07-09-payment-clean-usdt-loop.md

@@ -0,0 +1,185 @@
+# 收款闭环 · 独角数卡 + 自托管 USDT(TRC20)+ webhook JIT 发码（最干净长期方案）
+
+> #34。目标：把「下单 → USDT 付款 → 自动发激活码 → 客户端/用户中心兑换 → 订阅生效」端到端打通，
+> 全程自托管、售出才发码、无跑分、无第三方支付主体。
+>
+> **关键前提（已摸底）**：激活码后端大半已就绪——`POST /v1/redeem`（JWT 兑换，含幂等+限频+账户锁）、
+> 批次生成/导出（`server/cmd/codegen` + `server/internal/codes`，码为 Crockford Base32 75-bit 带校验位、只存
+> hash）、发卡店回调 `POST /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 agent；④ 全程不碰跑分/中国支付。
+>
+> **主体归属**：`pangolin-pay` + 独角数卡部署在**独立海外小 VPS**（不放 pangolin1：内存紧 + 风险隔离），
+> 只经 HTTPS + HMAC 与 pangolin 控制面（`api.yanmeiai.com`）通信。
+>
+> 参考文档：`docs/payment-a-selfhosted-store-plan.html` / `payment-channels-overview.html` /
+> `payment-reseller-fulfillment-design.html`。
+
+---
+
+## Phase 0 — 计划落库 + todo
+
+- [ ] 0.1 本 `.md` 定稿 + 生成 HTML 阅读版 `docs/payment-clean-usdt-plan.html`，登记进 `docs/index.html`「实现计划」
+- [ ] 0.2 `/todo` 把 #34 propose 为「待确认」（tier-1，`--ref` 指向本 `.md`），等用户 approve 再进 Phase 1
+
+---
+
+## Phase 0.5 — 钱包选型（用哪个钱包）
+
+**先厘清：这套架构的「钱包」是两件事，别当成装一个 app。**
+- **主种子（钱在哪）**：一套 BIP39 助记词，冷存。这是资产本体。
+- **watcher 收款（派生地址）**：热服务用**库**从 account **xpub（公钥）**派生每单地址——**watch-only，不是钱包 app**，也拿不到私钥。
+- **归集签名**：需要动钱时，在冷端用私钥离线签 sweep 交易。
+
+所以「用哪个钱包」= 选①主种子怎么冷存 + ②watcher 用哪个派生库。
+
+**① 主种子 / 冷存 候选**
+
+| 方案 | 冷存安全 | xpub 导出(给 watcher) | 归集签名 | 结论 |
+|---|---|---|---|---|
+| **离线生成助记词 + 库派生**（推荐） | 高（纸/钢板离线保存，永不联网） | 直接从种子导 account xpub | 离线机用库签 | **最贴合 watch-only 架构、最灵活** |
+| **Ledger 硬件钱包**（可叠加） | 最高（私钥永不出设备） | 可导 account 公钥（需配套工具） | 插 Ledger 签 | 想再加一层硬件冷存就用它兜底 |
+| TronLink / imToken / Trust（手机热钱包） | 低（热钱包） | 不便批量 per-order 派生 | app 内签 | **不推荐**当收款主钱包（热 + 难集成） |
+
+**② watcher 派生库 候选**（给热服务 watch-only 派生 TRON 地址，非钱包）
+
+| 语言 | 库 |
+|---|---|
+| Go（与 server 同栈，推荐） | `tyler-smith/go-bip39`（助记词）+ `btcsuite/btcd/btcutil/hdkeychain`（BIP32 派生）→ 公钥转 TRON base58 地址（`0x41` 前缀 + Keccak）；或成熟 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 coin type）。
+      工具：离线机器用 `tronpy` / `tronweb` 或硬件钱包（Ledger，导出 account xpub）。**生成过程不联网。**
+- [ ] 1.2 密钥分级存放：
+  - **助记词/私钥** → 冷备（纸/钢板离线）+ Bitwarden 记录，**永不上热机、不入 git**
+  - **account xpub（公钥）** → 给 `pangolin-pay` 用来 watch-only 派生收款地址（无私钥）
+  - **HMAC secret**（Phase 3/4 用）→ Bitwarden
+- [ ] 1.3 定**冷钱包归集地址**（cold sweep 目标）+ 记录 USDT-TRC20 合约地址（主网 `TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t`，**核对无误再写死**）
+- [ ] 1.4 备少量 **TRX** 作归集 gas（TRON 转账吃 energy/bandwidth，账户无 energy 时烧 TRX）；记 energy 租赁备选
+- [ ] 1.5 验证：用 xpub 离线派生前 5 个地址；往 index 0 打 1 USDT 小额测试，确认 watch-only 能查到该地址收款
+
+---
+
+## Phase 2 — pangolin-pay：TronGrid watcher（自建收款侦测）
+
+目标：一个独立 Go 服务，派生每单唯一地址、轮询 TronGrid 侦测到账、确认后置单已付。
+
+- [ ] 2.1 建服务骨架 `pangolin-pay`（Go，复用 server 的 DB 方言层思路；独立仓/独立 cmd 均可）。自带轻量 DB（SQLite 即可）
+- [ ] 2.2 数据模型：
+  - `pay_orders(order_no PK, sku, plan, duration_days, addr_index, address, expect_amount, status, tx_id, confirmations, created_at, expires_at)`
+  - `addr_cursor(next_index)` — HD 派生游标，单调递增
+- [ ] 2.3 **每单唯一地址**：建单时从 xpub 派生 `m/.../0/next_index` 分配给该单（最准，免金额撞车）。次选：单地址+唯一金额（备选降级）
+- [ ] 2.4 TronGrid 轮询：对每个 pending 单地址查 TRC20 转入
+  - endpoint：`GET https://api.trongrid.io/v1/accounts/{addr}/transactions/trc20?only_confirmed=true&contract_address=<USDT>`
+  - 比对：`to==address`、`token==USDT`、`value≥expect_amount`（含小额容差处理）
+- [ ] 2.5 **确认数**：只认 `only_confirmed`（已固化）交易，或等 ≥N 区块（TRON 约 1 分钟）。到账+确认 → `status=paid`、记 `tx_id`
+- [ ] 2.6 到账后触发发货（Phase 4 的 epay notify）；**幂等**：同 `tx_id` 只认一次，一个 order 只发一次货
+- [ ] 2.7 订单超时（默认 15min）未付 → `status=expired`、释放地址（地址不复用，避免旧付款串单）
+- [ ] 2.8 TronGrid API key + 限流退避 + 失败重试；watcher 崩溃可恢复（从 DB 未决单继续轮询）
+- [ ] 2.9 测试：mock TronGrid → 单测 金额匹配 / 确认门槛 / 超时 / 幂等（同 tx 重放）/ 崩溃恢复
+
+---
+
+## Phase 3 — pangolin 控制面：JIT 发码端点 `POST /internal/codes/mint`
+
+目标：付款确认时**即时生成一个合法激活码**（这才是 webhook JIT 的落点：售出才产码、才有效）。
+现有 `/webhook/store/codes` 要求调用方自带合法码；自建场景由 pangolin 产码更干净（保证格式+校验位单源）。
+
+- [ ] 3.1 新增 `POST /internal/codes/mint`（挂 `/internal` 组，**无 JWT**，HMAC 同 webhook：
+      `X-Pangolin-Signature: sha256=<hmac>` + `X-Pangolin-Timestamp`(±5min) + `X-Pangolin-Nonce`(Redis 去重)）
+- [ ] 3.2 body `{plan: free|pro|team, duration_days, order_ref}` → 复用 `codes.GenerateCode()` 产码 +
+      `Store.CreateCode(hash, planID, duration, batchID)` 存 unused（channel=ChannelStore）→ 返回 `{code, expires_at}`
+- [ ] 3.3 **幂等**：以 `order_ref` 为幂等键（存 `order_ref→code_hash` 映射）；同单重放返回**同一个码**，绝不重复发
+- [ ] 3.4 secret 走 Bitwarden → `server.env`（`CODES_MINT_HMAC_SECRET`）；路由挂载（`main.go`），仅 HMAC 保护、不经公网 JWT
+- [ ] 3.5 复用现有 webhook 的验签/时间戳/nonce 逻辑（抽公共中间件，避免重复实现）
+- [ ] 3.6 测试：验签通过/失败、时间戳越界、nonce 重放、`order_ref` 幂等、产码格式（Canonicalize 可还原+校验位对）
+
+---
+
+## Phase 4 — 独角数卡对接（门面 + 自动发货）
+
+目标：独角数卡做门面/订单/交付，`pangolin-pay` 做 USDT 支付口 + 发货时取码。
+
+- [ ] 4.1 （研究·先做）摸清所用独角数卡版本的**支付接口（epay 兼容规范）**与**API-提货/自动发货商品**机制
+      （版本相关，需实测；产出对接点清单再实现）
+- [ ] 4.2 `pangolin-pay` 实现 **epay 兼容支付接口**：独角数卡建单 → 跳我方支付页（展示该单 USDT 地址 + 应付金额 +
+      倒计时 + 网络必须 TRC20 强提示）
+- [ ] 4.3 到账（Phase 2.5）→ 按 epay 规范 **notify 独角数卡**（带签名）→ 独角数卡标「已支付」
+- [ ] 4.4 商品设为 **API-提货**：独角数卡发货时调 `pangolin-pay /issue` → 内部以 HMAC 调 pangolin
+      `/internal/codes/mint` 取合法码 → 返回独角数卡 → 交付买家（页面/邮件/站内）
+- [ ] 4.5 **SKU 映射表**（配置化，不散在代码）：独角数卡商品 → `plan + duration_days`
+      （Pro 月=pro/30、Pro 年=pro/365、Team 月/年=team/30|365；对齐 `design/CLAUDE.md §7` 与官网 Pricing）
+- [ ] 4.6 幂等贯通：独角数卡 order_no 作为 `order_ref` 一路透传到 mint，保证一单一码
+
+---
+
+## Phase 5 — 部署 · 运维 · 安全
+
+- [ ] 5.1 独立海外小 VPS（2C/2G 起）部署：独角数卡（Docker：PHP+MySQL+Redis）+ `pangolin-pay` + 域名 + HTTPS
+      （**不放 pangolin1**）
+- [ ] 5.2 密钥落位核对：`pangolin-pay` 只有 **xpub + TronGrid key + epay 签名密钥 + mint HMAC secret**；
+      **无私钥/助记词**（冷备）。全部 Bitwarden，不入 git
+- [ ] 5.3 **归集 runbook**：定期把各收款地址 USDT sweep 到冷钱包（**离线签名**，热机不碰私钥）；备 TRX gas
+- [ ] 5.4 **变现 runbook**：冷钱包 → 交易所（能出金到 US LLC 的，自行核实）→ 卖 USDT→USD → US LLC 银行；
+      入账交 `code/accounting` agent（本项目不做费用台账）
+- [ ] 5.5 监控告警（接现有 Telegram 告警）：watcher 存活、TronGrid 配额、到账延迟、mint 失败、订单异常堆积
+- [ ] 5.6 **对账**：独角数卡订单 ↔ `pay_orders` ↔ codes（mint 条数/redeem 条数）三方日结，差异告警
+
+---
+
+## Phase 6 — 端到端验证
+
+- [ ] 6.1 真单闭环：下单 → USDT 付款（TRC20）→ watcher 确认 → mint 码 → 独角数卡交付 →
+      客户端/用户中心 `POST /v1/redeem` → 订阅/时长生效、全端同步
+- [ ] 6.2 异常路径：超时未付 / 金额不足 / 重复付款 / 确认期网络抖动 / mint 重放 → 各自表现符合预期
+- [ ] 6.3 安全核对：热服务 `otool`/进程无私钥；密钥不在 git（红线扫描）；redeem 幂等+限频生效；
+      每单唯一地址不复用
+
+---
+
+## Verification（端到端判据）
+
+- 后端：`cd server && go test ./internal/codes/...`（新增 mint 端点验签/幂等/格式测试全绿）。
+- pangolin-pay：`go test ./...`（watcher 匹配/确认/超时/幂等/恢复）。
+- 真机：一笔真 USDT 小额单，从下单到订阅生效全通；异常路径逐条演练。
+- 安全：热服务无私钥、密钥不入 git、每单唯一地址、redeem 幂等限频——逐项核对。
+
+## 不在本轮
+
+- 支付宝/微信第三方通道（E 层，灰产，另议且当可替换插件）。
+- HD 自动 sweep 归集（先人工离线归集，量大再自动化）。
+- 多币种（先只 USDT-TRC20）、watcher 高可用/多实例、加密网关备选路子（B 方案）。
+- Telegram Stars / Apple IAP 独立收款口（海外补充，另排）。