jiu 授权续费对接 pay v2 改造计划

jiu 两侧的 pay v1 对接已经完整上线，本任务不是从零接入，而是契约升级（v1 → v2）：

后端 backend/internal/service/pay.go 已有 PayService 四职责：签名下单 CreatePurchase / webhook 入账 HandleCallback→settle（FOR UPDATE + out_trade_no 幂等 + 金额核对）/ 续期 entitle（max(现到期,now)+时长）/ 60s 查单兜底 reconcileOnce；表 license_purchases、配置 PAY_BASE_URL/PAY_SECRET/PAY_RETURN_URL、路由 POST /api/v1/pay/callback 全部就位
客户端 purchase_card.dart 已有三态状态机（选套餐 → launchUrl 拉起收银台 → 3s 轮询 + 30s 心跳兜底），iOS hideExternalPurchaseUi 合规开关、promo 限购、到期横幅入口都在
官网 web/checkout.njk:167 直读下单响应的 d.pay_url 跳收银台——兼容约束的来源

零改动沿用HMAC 签名算法（util.PaySign：base64(HMAC-SHA256(secret, "jiu\n ts\n nonce\n rawBody"))、±5min 窗）、out_trade_no 幂等键、entitle 续期语义、路由挂载、PAY_* 配置链、iOS 合规开关、轮询/心跳。

v2 契约 delta（已读 design/pay-v2 代码核实）

项	v1（现实现）	v2（本计划目标）
下单	`POST /api/v1/orders` {product_id, biz_system, biz_ref, return_url, client_type}	`POST /api/v2/orders` {sku, method, biz_system, biz_ref, return_url}；sku 直接用 biz_code（productID 查询+10min 缓存整段删除）；无 client_type
下单响应	{pay_url, out_trade_no, amount("2999.00"), subject}	{order_no, session:{render_type, payload, expires_at?}}；alipay 落 `redirect` + payload.url；不回传金额
查单	`GET /api/v1/orders/:otn`，四态	`GET /api/v2/orders/:no`（无鉴权，见风险节），{order_no, status, subject, amount_minor, currency, paid_at?}，八态 created\|pending\|paid\|canceled\|expired\|refunding\|partially_refunded\|refunded；不回传 biz_ref
webhook	扁平 payload，amount 元串，有 trade_no	+`event_type`（当前仅 payment.succeeded）+ X-Pay-Event 头（不参与签名）；amount_minor int64 + currency；无 trade_no；重投固定 60s 无退避无死信；成功判定 = 200 且 body 含 "SUCCESS"（大小写不敏感，现回包 {"code":"SUCCESS"} 天然满足）
签名	完全一致四段 \n 拼接 HMAC-SHA256 → base64 标准编码，`util.PaySign/PaySignVerify` 零改动；pay 侧无 nonce 去重，jiu 侧自建（D3）
金额	string 元	amount_minor int64（CNY=分）+ currency 大写码，全链路禁 float
retry / cancel	无	retry：409 currency_mismatch=需换方式新建单（jiu 单渠道不接，D6）；cancel：恒 200 {"data":{"canceled":bool}}，仅 pending 翻转成功（jiu 接，防单堆积）

pay 侧欠账（jiu 无法解决，列联调前置依赖，不阻塞开发）：

wap 缺口手机拉起支付宝 App 断线的唯一根因：v2 下单无 client_type、gateway 不设 Metadata["is_mobile"] → alipay 恒走 page.pay。redirect 机制本身没有问题；pay 补契约后 jiu 跟进一行
qr render_type 仅文档口径无代码实现——体验增强项而非缺失：alipay PC 收银台页面本身含二维码，桌面扫码今天即可用，qr 内嵌只是省一次浏览器跳转
seedPlans 仅 alipay_sandbox 开关下执行，生产套餐种子需部署时确认
pay 侧需配置 BIZ_JIU_SECRET / BIZ_JIU_CALLBACK_URL
查单/retry/cancel 无鉴权本身是 pay 既定惯例（不可猜 ID + payload 无敏感字段，与 refunds 查询同型，P4 终审已归档为模式一致），非设计缺陷；jiu 侧也无未鉴权暴露（客户端/官网只轮询 jiu 自己的 JWT+shop_id 接口）。真正的加固点仅两处：order_no 熵偏薄（≈32 位）、改状态端点（cancel/retry）可被持单号者骚扰——建议 pay 仓增熵 + 对改状态端点限流

已定设计决策

D1 金额链路（价格权威在 pay 不变）：v2 下单不回金额 → 下单成功后立即查单回填 amount_minor/currency/subject（best-effort，失败不阻断）；settle 时本地 amount_minor==0（残单）先补查再核对，仍拿不到则拒绝入账 fail-closed 等 pay 重投。核对 = int64 相等 + currency 相等
D2 事件分发：以 payload.event_type 为准（X-Pay-Event 头不参与签名仅日志）。payment.succeeded → settle；其余事件（refund.* 等）记 ALERT 日志后 ack SUCCESS——pay v2 重投无退避无死信，回 FAIL 会 60s 永久重投；退款接入按任务书排除、另起任务
D3 nonce 防重放：jiu 侧内存去重（map + 10min 滚动清理），命中回 401。pay 每次重投重新生成 nonce/签名不受影响；真正幂等仍靠 settle 短路；单实例部署，重启丢失由幂等兜底
D4 表结构：license_purchases 新增 amount_minor bigint + currency varchar(8)；旧 amount 列保留只读，启动 Go 回填存量（复用 toCents，参照 backfillPinyin），观察一版后另行 DROP（同定价消歧惯例）
D5 兼容铁律：后端下单/查单响应同时输出新字段与弃用字段（pay_url=redirect 时的 payload.url、amount=格式化元串）——官网 checkout 与已发行客户端不升级也不能坏；官网本期零改动
D6 retry 不接 / cancel 接：单渠道 alipay 无换方式需求，409 currency_mismatch 按约定=新建订单（「重新选择」已覆盖）；cancel 轻量接入，「重新选择」时透传 pay，防 pending 堆积挤占 reconcile 每轮 50 条限额
D7 客户端 render_type 分发：redirect → launchUrl（现行为）；qr → 卡内嵌 QrImageView（新增 qr_flutter，纯 Dart 全平台，按文档口径 qr_content 实现、联调校准）；未知 → toast 提示升级
D8 状态映射：reconcile 遇 canceled/expired → 标 failed（不扩本地枚举）；created/pending 继续等；refund 系 no-op 记日志
D9 配置零新增：PAY_* 三件套已在 viper/production.env/render-env.sh/Bitwarden 链上
D10 UI 治理（按 2026-07-10 铁律：原型=代码 100% 一致，前端改动先改原型）：授权管理已完成 design-first（原型 license.html / m-license.html 三 tab 已评审提交 13b7274），实现逐像素落地、原型与代码同提交；qr 内嵌态动 PurchaseCard 前仍需先补原型
D11 授权管理提升（2026-07-10 评审通过并入）：授权管理提升独立一级屏（桌面侧边栏「系统」组 + /license；移动 /me/license），三 tab：授权信息 / 在线购买续费（iOS 合规态整 tab 隐藏）/ 订单管理。「继续支付」=打开下单时存储的 pay_url（不接 retry，维持 D6）；「授权续期至」=settle 回写 renewed_to；模型加 pay_url/renewed_to 两列

任务分解（8 任务，每任务 TDD + 独立提交）

1表结构 + 存量回填 — model 加 AmountMinor/Currency；BackfillPurchaseAmountMinor（"2999.00"→299900+CNY，幂等只处理 amount_minor=0 行）挂 main.go；schema.sql / testutil SQLite 建表同步。测试：回填正确、已有值不覆盖
2下单+查单切 /api/v2 — 请求体 {sku, method:"alipay", biz_system, biz_ref, return_url}；解析 order_no+session；下单后查单回填；删 productID/prodCache；PurchaseResult 改 {out_trade_no, render_type, payload, amount_minor, currency, subject, ~~pay_url~~, ~~amount~~}（弃用字段照 D5 输出）；queryOrder 八态。测试：mock v2 双端点断言请求形状/签名可验/兼容字段
3webhook v2 — payNotification 改 event_type/amount_minor/currency（删 amount/trade_no）；事件分发（D2）+ nonce 防重放（D3）；settle 签名改 int64 + 残单补查（D1）；handler Callback 零改动。测试：入账/幂等重投/nonce 重放 401/refund ack/金额差 1 分拒绝/残单兜底
4reconcile 八态映射 — paid→settle；canceled/expired→failed；refund 系 no-op。测试 ×4 状态
5取消透传 — POST /api/v1/license/purchase/:otn/cancel（admin，license 组=LicenseGuard 豁免区）→ pay cancel → canceled==true 才标 failed（false=已付竞态，保持 pending 等入账）。测试：成功/竞态/跨店 404
6客户端模型层 — PurchaseOrder{renderType, payload, amountMinor, currency} + redirectUrl/qrContent getter；yuanFromMinor（299900→"2,999.00"）落 core/utils/money.dart；repository +cancelPurchase。测试：fromJson/格式化
7PurchaseCard 分发 — _submit 按 renderType：redirect 外跳 / qr 内嵌 QrImageView(180) / 未知 toast；金额展示 yuanFromMinor；「重新选择」fire-and-forget cancel；pubspec +qr_flutter ^4.1.0。验收：flutter analyze+test、settings golden 无 diff、check_ds_code.mjs 过闸
9订单列表接口 — GET /api/v1/license/purchases：分页/状态筛选/summary（累计·笔数·待支付），仅管理员，跨店隔离；pending 单回 pay_url 供继续支付；LEFT JOIN users 取下单人
10授权管理独立屏三 tab（双端） — 按已评审原型逐像素实现：路由 /license+侧边栏项+settings 摘除授权子导航；订单 tab 桌面 DsTable+抽屉 / 移动 MCard 流+sheet；继续支付/取消订单/重新购买切购买 tab；settings golden 更新 + 新屏 golden ×3 + fidelity 注册
8文档同步（收尾） — docs/pay支付对接开发指南.html v2 化（标注 v1 断代）；db-schema.html 四新列；CONTRACT 台账回填；用户手册补「授权管理/订单管理」节（两侧同步）

执行顺序：后端链 1→2→3→4→5→9 与前端链 6→7→10 交错推进，Task 8 收尾。

联调 checklist（pay v2 部署后，不阻塞开发）

pay v2 合 main 部署；生产 accounts 配 alipay、seedPlans 套餐落库（seed 现仅 sandbox 开关下执行，需确认）
密钥对齐：pay 侧 BIZ_JIU_SECRET = jiu 侧 PAY_SECRET（Bitwarden 单源）；BIZ_JIU_CALLBACK_URL=https://jiu.51yanmei.com/api/v1/pay/callback；jiu 侧 PAY_BASE_URL 指 v2
¥0.01/¥1 真单走通（jiu payPlans 白名单无 test_liandiao：用 promo ¥1，或临时加 test_liandiao 映射联调后移除）：下单→收银台→实付→webhook 续期→轮询 success→写权限即时恢复（InvalidateLicensePhase）
阻断 webhook 验证 reconcile 5 分钟查单兜底；接收器临时回 FAIL 观察 60s 重投与幂等
官网 checkout（pay_url 兼容字段）+ 旧版客户端购买路径回归
pay 侧欠账跟进：端型透传补契约 → jiu 加回 client_type 一行 → 真机验证手机拉起支付宝；查单/cancel 无鉴权加固（限流+增熵）；refund 事件消费另起任务
取消路径：客户端「重新选择」→ pay 订单翻 canceled

红线与 DoD

金额禁 float；幂等（60s 无限重投安全）；Status/Cancel 带 shop_id（JWT 取）；零写真实库（SQLite in-memory + httptest）；不部署不发版不打 tag
go build/vet/test ./... + flutter analyze/test + check_ds_code.mjs + check-l1-sync.mjs 全绿后停在本地提交态，todo 标 done 等验收