Pangolin × pay v2 接入 — 终验交付说明

Task 8（终验）· 全量矩阵 + OpenAPI 登记 + 交付说明 · 2026-07-10/11 · 配套计划：2026-07-10-pangolin-pay-v2-integration.md（执行真相源，Task 1–8 checkbox）

1. 测试矩阵结果

2. OpenAPI 登记

在 server/api/openapi.yaml（codegen 唯一实际消费源；design/server/openapi.yaml 是 CI 仅做结构校验的旧文档，二者早已不同步，见「遗留项」②）新增 Pay tag 与以下端点：

新增 schema：PayCatalogItem / PaySession（render_type 多态： crypto_address / redirect / qr）/ PayOrderSessionResult / PayOrderStatus / PayWebhookEvent；新增 PayConflict / PayUpstream 错误响应组件。未运行 go generate ./... 重新生成 server/api/gen/*.gen.go——main.go 的 /v1/pay/* 路由是直接手写 chi 挂载（cmd/server/main.go:408-413），不经过 gen.ServerInterface，OpenAPI 文档是纯规格登记，不影响运行时；internal/httpapi/unimplemented.go 的编译期断言 var _ gen.ServerInterface = ... 因未重新生成而不受影响，go build 已验证无恙。

3. 迁移彩排（Step 2，文件库带数据升级）

新增 server/internal/store/pay_migration_rehearsal_test.go（纳入常规 go test ./...，非一次性脚本），两个测试：

4. 已知取舍（Self-Review，逐条见 task-8-brief.md）

5. 遗留项

1. MySQL 集成测试：本次已在本机 docker 验证通过（含 000021 MODIFY ENUM），run_mysql_test.sh 的 multiStatements=true 脚本 bug 已顺带修复入 commit。若 CI runner 本身无 docker，仍会跳过该 job（非本计划新增依赖）。
2. OpenAPI 两份文件的同步策略：server/api/openapi.yaml（codegen 实际消费源）与 design/server/openapi.yaml（CI 仅结构校验，标题都不同、缺 /notices 等多个既有端点）早已不同步——这是 Task 8 之前就存在的既有漂移，本次未强行同步（会引入与既有漂移无关的大改动），只在 server/api/openapi.yaml 登记新端点。建议后续单独排期决定：要么把 design/server/openapi.yaml 废弃改指向 server/api/openapi.yaml，要么定期同步脚本化。
3. 支付宝 return_url：App 场景暂空，web 用户中心接入时再传。
4. 本计划 HTML 阅读版：docs/superpowers/plans/2026-07-10-pangolin-pay-v2-integration.md 尚无同内容 HTML 阅读版登记进 docs/index.html——按仓规矩属于「定稿后补」，本次交付说明已登记，计划本身的阅读版建议下一刀单独补齐。
5. 手动冒烟（Step 4）未做：brief 标注可选，已用 httptest 覆盖等价路径，详见第 1 节表格备注。
6. 新发现：go.mod 的 github.com/wangjia/codes 本地文件系统 replace 会阻断异机 go build——

   replace github.com/wangjia/codes => /Users/wangjia/code/codes

   这行是 codes-lib 重构分支遗留（早于本次 pay-v2 接入，go.mod 里已有注释自述为 「Validation-branch local replace... Coordination item for merge」），与本次 pay-v2 改动无关， 但因为 internal/pay 通过 internal/codes.Service 间接依赖它，实测会影响到本任务。 本次用 docker run --rm -v "$PWD/server:/app:ro" -w /app golang:1.25 go build ./...（不挂载 /Users/wangjia/code/codes，模拟 CI 环境）复现：replacement directory /Users/wangjia/code/codes does not exist——说明 .gitea/workflows/ci.yml 的「Go — build + test」job（同样用干净 golang:1.25 容器）在本分支上当前会构建失败，且如果直接在 pangolin1 上用 deploy/single-node/deploy.sh「就地构建」（脚本里 command -v go 分支）也会同样失败。 不是本计划引入的新问题，但是合并/部署前必须解决的前置阻断项——按 go.mod 注释里已给的方向： 把 wangjia/codes 换成真实发布版本（git config --global url."ssh://git@..." .insteadOf + CI/dev 机 GOPRIVATE=github.com/wangjia/codes），不用本地路径 replace。此项超出 Task 8 授权范围 （涉及私有仓库发布/CI 凭据），未在本次改动，仅如实记录。

6. 联调 Checklist（端到端，等 pay 部署后执行；不阻塞本次交付）

单测已用 httptest 假 pay 全覆盖签名/幂等语义；本节是真环境验收，来自 task-8-brief.md 原文，逐条打勾。

1. pay 侧就绪：/api/v2 可达；pangolin 的 biz 配置与种子 SQL 已按下节部署附录落库（products×3 + product_prices(USDT)×3 + biz_system=pangolin）
2. 价格一致性：pay 下单三档，断言返回/扣款金额与 pangolin catalog.go 展示价一致（CNY 2999/6888/19999 分；USDT 按附录种子）
3. pangolin server 配置：PAY_BASE_URL/PAY_BIZ_SYSTEM=pangolin/PAY_BIZ_SECRET 已入 /etc/pangolin* env；重启后日志无「PAY_BASE_URL 未配置」
4. 签名互通：POST /v1/pay/orders {"sku":"pro_month","method":"crypto"} → 200 返回 crypto_address session；403/401 核对 secret 与时钟（±300s）
5. webhook 连通：pay 侧 CallbackURL 指向 http://<pangolin-server>:8080/v1/webhook/pay；SupportedEvents=[payment.succeeded]；重发工具投递一条 → pangolin 无验签错误、pay 侧收到 200+SUCCESS
6. USDT 真付一单（小额档）：转账精确金额 → webhook → App 轮询页自动切「已开通」；subscriptions 出现 source='pay' 行，pay_purchases 行 paid + sub_id/amount/currency 回填；audit_log 有 pay_grant
7. 重投验证：pay 侧手动重发同一事件 → pangolin 回 SUCCESS，订阅到期不变
8. 支付宝 redirect 一单：method=alipay + metadata.is_mobile 按端型 → 返回 redirect url 可拉起
9. 换渠道：crypto 下单后 retry alipay → 收 409 CURRENCY_MISMATCH；App 自动取消旧单新建 alipay 单
10. 叠加：同账号再购一档 → expires_at 在原值上顺延（非从 now 重算）
11. 限流不误伤：连续下单/取消超 30 次/分触发 pay 429 → App 提示「操作过于频繁」而非崩溃
12. 时钟检查：pangolin1 与 pay 所在机 timedatectl NTP 同步（±300s 窗口前提）

7. 部署附录

联调/上线前的 pay 侧与 pangolin 侧配置；本计划不执行部署。

A. pay 侧种子 SQL

-- ① 收款商户（alipay 渠道；crypto 走 pay 的 crypto provider 配置，不在此表）
INSERT INTO merchants (code, name, channel, production, enabled, created_at, updated_at)
VALUES ('pangolin', 'Pangolin', 'alipay', 1, 1, NOW(), NOW());
-- 记下自增 id，下面记作 <MID>

-- ② 三档产品（biz_code 即 v2 sku，与 pangolin catalog.go 严格一致）
INSERT INTO products (merchant_id, name, description, price, active, sort, biz_code, created_at, updated_at) VALUES
  (<MID>, 'Pangolin 专业版·月付', '31 天', '29.99',  1, 1, 'pro_month',   NOW(), NOW()),
  (<MID>, 'Pangolin 专业版·季付', '92 天', '68.88',  1, 2, 'pro_quarter', NOW(), NOW()),
  (<MID>, 'Pangolin 专业版·年付', '366 天','199.99', 1, 3, 'pro_year',    NOW(), NOW());

-- ③ USDT 结算价（crypto 渠道必需；微单位，1 USDT = 1_000_000）
INSERT INTO product_prices (product_id, currency, amount_minor, created_at, updated_at) VALUES
  ((SELECT id FROM products WHERE biz_code='pro_month'),   'USDT',  4200000, NOW(), NOW()),
  ((SELECT id FROM products WHERE biz_code='pro_quarter'), 'USDT',  9700000, NOW(), NOW()),
  ((SELECT id FROM products WHERE biz_code='pro_year'),    'USDT', 27990000, NOW(), NOW());

执行前用 SELECT * FROM products WHERE biz_code LIKE 'pro_%' 确认无残留旧行（幂等按 biz_code 判）。NOW() 在 pay 库合法（pangolin「禁 NOW()」纪律只约束本仓 server SQL）。

B. pay 侧 biz 配置

biz_systems:
  - name: pangolin
    secret: <与 pangolin PAY_BIZ_SECRET 相同，Bitwarden 生成 32+ 字节随机串>
    callback_url: http://<pangolin-server>:8080/v1/webhook/pay
    supported_events: [payment.succeeded]   # 白名单只开这一个

C. pangolin 侧 env（/etc/pangolin-server.env 或等价，不入 git）

PAY_BASE_URL=http://<pay-server 地址>          # 如 https://pay.51yanmei.com
PAY_BIZ_SYSTEM=pangolin                        # 默认值即 pangolin，可省
PAY_BIZ_SECRET=<同 B 节 secret，Bitwarden 取>

D. 部署顺序

1. pangolin cmd/migrate up（000021，subscriptions 重建 + pay_purchases 建表——不可逆，一旦产生 source='pay' 行后无法一键 down，见第 3 节安全特性）
2. 重启 pangolin-server
3. pay 侧种子 + biz 配置
4. 联调 checklist（第 6 节）

前置阻断：在 D①/D② 之前，若走「就地构建」（deploy/single-node/deploy.sh 机上有 go 时会自动 go build），须先解决第 5 节遗留项⑥的 wangjia/codes replace 路径问题，否则构建会在 pangolin1 上直接失败（本地开发机因为恰好存在 /Users/wangjia/code/codes 才能编译，不代表其它机器可用）。

E. codes 依赖 pin

server/go.mod 当前锁定 github.com/wangjia/codes @ c772d525679441d0579df6e309deba2d60254ab5（commit 见 go.mod 注释），经由本地文件系统 replace 而非可复现的模块下载——部署/CI 前必须换成可在异机复现的方式（git insteadOf + GOPRIVATE，或发布真实版本 tag），否则 pangolin1 / CI runner 上 go build 会直接因「replacement directory 不存在」失败。详情与复现方法见第 5 节遗留项最后一条。