@kunlv/atdc 1.0.0

package/central/ticket_center_server/.handoffs/TASK-238389_QYinVipLimit.md

@@ -0,0 +1,128 @@
+# TASK-238389_QYinVipLimit 交接文档
+
+> 生成时间：2026-07-17 12:00
+> 生成方式：/atd:handoff
+> 源交接：`ticket_center_server.TASK-fxiQyin/docs/handoffs/TASK-238389_QYinVipLimit.md`
+> 当前工作区：`/Users/lvkun/Documents/Codes/ticket_center_server.TASK-238389_QYinVipLimit`（分支 `TASK-238389_QYinVipLimit`）
+> 会话来源：Q音绿钻发货失败静默成功排查 → 存量补发 → 错误语义修正 → `rights_grant_check` 并发/限流分析 → **切至此分支做限流改造**
+
+---
+
+## 做了什么
+
+**动机**：Q音绿钻发货失败（如未映射码 `10101`）曾被当成功吞掉导致不重试/失货；线上 `rights_grant_check` 多 job 并发打满对方限流 300；需在本分支做 Q音 VIP 发放限流改造。
+
+**结果**：前序 worktree（`TASK-fxiQyin`）已厘清失败语义与补单路径、补发 CLI/名单、64 路并发打到 300 的机制，并落地 Retry vs 永久失败语义；**本分支尚未开始限流代码/openspec**，当前即为限流改造起点。
+
+---
+
+## 关键决策
+
+| # | 决策 | 选了 | 排除了 | 原因 |
+|---|------|------|--------|------|
+| 1 | 发货失败是否一律 `return error` | 仅 `DeliveryStatusRetry(=3)` 返回 error | 所有非 Shipped 都 return error | `DeliveryQQVipStatusFail(=4)`「不允许发货」重试无意义，会打爆补单/限流 |
+| 2 | 存量 800+ 单补发顺序 | 先补发再改 bug | 先上线错误语义再补发 | 业务要求先止血到账；补发以权益表验收，不信 `SendSvip` 返回值 |
+| 3 | 补发方式 | CLI `resend_qmusic_svip` 读 CSV + 查 `user_ticket_rights` | 仅把 `sync_status` 打回 0 跑 `rights_check` | 旧逻辑失败也 `nil`，rights_check 会误推 sync 成功 |
+| 4 | 限流改造落点 | 本分支 worktree `TASK-238389_QYinVipLimit` | 在 `TASK-fxiQyin` 上继续改 | 独立需求/分支，避免串工作区 |
+
+### 状态语义（务必保持，限流改造勿破坏）
+
+| Status | 常量 | 含义 | `handleQMusicGreenDiamond` |
+|--------|------|------|----------------------------|
+| 2 | `DeliveryStatusShipped` | 真成功 | 落库 + 短信 |
+| 3 | `DeliveryStatusRetry` | 未映射/可重试（含原 10101 类） | `return error` 触发重试 |
+| 4 | `DeliveryQQVipStatusFail` | 不允许发货（白名单码） | `return nil`，不重试、不落成功态 |
+
+`parseDeliveryResponse`：成功→2；`isQMusicDeliveryNotAllowed`→4；其余未知码→3。
+
+本分支已确认存在：`add_right_impl.go` 中 Retry→`fmt.Errorf(...)`；`qmusicResultStatus` 将 status=4 映射为 `ResultStatusFailed`。
+
+---
+
+## 受影响模块
+
+```
+# 前序已改（来自 TASK-fxiQyin，本分支应已包含语义修复）
+service/biz/rights/
+  └── add_right_impl.go          — Retry 用响应字段构造 error（勿 wrap nil err）；永久失败 return nil
+service/biz/rights/member/
+  └── qmusic_provider.go         — status=4 → ResultStatusFailed
+service/rpc/
+  └── qmusic_direct_vip_impl.go  — 未知码→DeliveryStatusRetry；callTencentMusicAPI 为限流落点候选
+
+cli/cmd/rights/
+  ├── resend_qmusic_svip.go      — CSV 补发；以 QY right_type=4 + status=1 验收
+  ├── rights_grant_check.go      — 延迟发放扫表；8 库×每库8表；无客户端限流（问题源）
+  └── rights_check.go            — sync_status=0 补全链路；SendSvip nil 会推进 sync=1
+cli/
+  └── register.go                — 注册 resend_qmusic_svip
+
+# 本分支待改（限流）
+service/redis/
+  ├── redis_rate.go              — 已有 RateLimiter.AllowPerSecond（可复用）
+  └── redis_limit.go             — 计数限流备选
+service/rpc/
+  └── qmusic_direct_vip_impl.go / local.go(SendSvip) — 限流挂载点待定
+
+docs/bugfix/
+  └── ticket-QQ音乐绿钻发货静默失败-ISSUE-0027.md
+```
+
+### 相关路径 / 资产
+
+| 项 | 路径 |
+|----|------|
+| **限流改造 worktree（当前）** | `/Users/lvkun/Documents/Codes/ticket_center_server.TASK-238389_QYinVipLimit` |
+| 前序语义修复 worktree | `/Users/lvkun/Documents/Codes/ticket_center_server.TASK-fxiQyin` |
+| 补发名单 | `/Users/lvkun/Documents/kugou/userid_orderno.csv`（872 行，已校验可解析） |
+| openspec change | **尚无** `openspec/changes/*238389*` / `*QYinVip*` — 需新建 |
+
+---
+
+## 测试状态
+
+| 覆盖范围 | 状态 | 说明 |
+|---------|------|------|
+| 单元测试 | ⚠️ | Retry wrap-nil / 永久失败不重试等语义变更未见专门单测补齐 |
+| CSV 解析 | ✅ | 872 行 PARSE_OK，无重复/坏行 |
+| 存量补发 | ⚠️ | CLI 已就绪；是否全量跑完、失败清单需接手确认 |
+| 限流改造 | ❌ | 本分支目标功能，**尚未开始**（无 openspec、无代码 diff） |
+
+---
+
+## 未解决问题
+
+- **Q音侧限流 300（本分支主目标）**：`rights_grant_check` 8 job×每库 8 协程 = **64 路并发**，无本地限流；对方 RTT~200ms 时理论 QPS≈320，已实锤可触发限流。应加共享令牌桶/间隔或降并发，目标峰值 **<300**（建议 200～250）。
+- **永久失败 return nil 与 RightsCheck**：`status=4` 不重试合理，但 `rights_check` 若走 SendSvip 得 nil 仍可能把订单 `sync_status` 推成成功——会员永久失败时其它权益仍前进；是否要落「失败态权益记录」便于对账未定。
+- **aiconsult #366882**：审查建议「非成功一律 return error」与业务决策冲突；已按「仅 Retry 抛错」落地，相关 MR 需说明。
+- **补发 CLI 内对 SendSvip error 仅 Warn**：验收靠权益表；限流改造后建议失败也写入 fail-out 并可选尊重 error。
+- **存量补发是否跑完**：需查 `resend_ok/fail/skip` CSV，失败单用 fail 名单重跑。
+
+---
+
+## 下一步
+
+1. **本目录已是正确 worktree**（`TASK-238389_QYinVipLimit`）— 勿再切回 `TASK-fxiQyin` 写限流。
+2. **按 openspec 流程起规格**：`/opsx:propose`（或项目 flow）写清限流方案；候选挂载点：`callTencentMusicAPI` / `SendSvip` / `processPendingRight`；优先复用 `service/redis/redis_rate.go` 的 `RateLimiter`（跨 job 全局生效）。
+3. **并发调参备选（改代码前可先运维止血）**：减 job 或降 `-w`（例如每库 `-w=2` → 总并发≈16）；代码侧共享限流器更稳。
+4. **确认存量补发**：查 `resend_ok/fail/skip`；失败单重跑。
+5. **可选**：为 `handleQMusicGreenDiamond` Retry/永久失败分支补单测，防止再次把 4 当成可重试。
+
+### `rights_grant_check` 并发速查（线上）
+
+```
+命令：bin/cli rights_grant_check -t=1000 -i={0..7} -w=10
+配置：ticket_user sharding_db=8, sharding_table=64 → 每库 8 表
+实际：每 job 8 协程（不是 10）；8 job 合计 64 协程；表内串行
+峰值 QPS ≈ 64 / 单次耗时
+```
+
+---
+
+## 相关资源
+
+- Bugfix：`docs/bugfix/ticket-QQ音乐绿钻发货静默失败-ISSUE-0027.md`
+- 审查事件：aiconsult #168343 / Bug 366873（wrap nil err）、366882（非成功 return nil）
+- 样本订单：`12607131000330004220001010395` / userid `2534695307`
+- 已有限流设施：`service/redis/redis_rate.go`（`RateLimiter.AllowPerSecond`）、`service/redis/redis_limit.go`
+- 源交接（前序会话）：`/Users/lvkun/Documents/Codes/ticket_center_server.TASK-fxiQyin/docs/handoffs/TASK-238389_QYinVipLimit.md`

package/central/ticket_center_server/.test_plans/TASK-227254-SupportMembership-self-test-plan.md

@@ -0,0 +1,566 @@
+# TASK-227254-SupportMembership 自测计划（可执行版）
+
+> 所有命令可直接复制运行。变量 `<HOST>` 替换为测试环境地址（如 `http://ticketcenter-test.kgidc.cn`）。
+
+---
+
+## 第零步：测试前准备
+
+```bash
+# 1. 预置 SKU 数据
+mysql> INSERT INTO membership_product_sku (sku_code, name, icon, platform, member_type, vip_type, list_price, sale_price, status, sort, sale_start_time, sale_end_time, create_time, update_time)
+VALUES ('test-kg-vip-month', '酷狗VIP月卡', 'https://img.example.com/kg.png', 101, 1, 1001, 1800, 1500, 1, 100, '2025-01-01', '2027-12-31', NOW(), NOW());
+INSERT INTO membership_product_sku (sku_code, name, icon, platform, member_type, vip_type, list_price, sale_price, status, sort, sale_start_time, sale_end_time, create_time, update_time)
+VALUES ('test-qm-vip-month', 'Q音绿钻月卡', 'https://img.example.com/qm.png', 102, 1, 2001, 1800, 1500, 1, 100, '2025-01-01', '2027-12-31', NOW(), NOW());
+INSERT INTO membership_product_sku (sku_code, name, icon, platform, member_type, vip_type, list_price, sale_price, status, sort, sale_start_time, sale_end_time, create_time, update_time)
+VALUES ('test-kw-vip-month', '酷我VIP月卡', 'https://img.example.com/kw.png', 103, 1, 3001, 1800, 1500, 1, 100, '2025-01-01', '2027-12-31', NOW(), NOW());
+
+# 2. 记录测试 userid（后续命令会用 ***）
+# 酷狗 userid:  XXXXXXXXX（需替换）
+# Q音  userid:  YYYYYYYYY（需替换）
+# 酷我 userid:  ZZZZZZZZZ（需替换）
+
+# 3. 记下一个全局变量方便后续命令复用
+export HOST=http://127.0.0.1:8080
+```
+
+---
+
+## 链 1：商品查询
+
+### 1.1 正常查询
+```bash
+curl -s "${HOST}/membership/product/list?performance_id=474134&app_type=1" | jq '.list | length'
+# 预期：>0，返回酷狗平台 SKU
+```
+
+### 1.2 Q音平台过滤
+```bash
+curl -s "${HOST}/membership/product/list?performance_id=474134&app_type=2" | jq '.list[] | select(.platform==101)'
+# 预期：空（不返回酷狗 SKU）
+```
+
+### 1.3 无匹配演出
+```bash
+curl -s "${HOST}/membership/product/list?performance_id=99999999&app_type=1" | jq '.list'
+# 预期：[]，popup 字段存在
+```
+
+### 1.4 Redis 缓存验证
+```bash
+# 连续调两次，查看服务日志
+curl -s "${HOST}/membership/product/list?performance_id=474134&app_type=1" > /dev/null
+sleep 1
+curl -s "${HOST}/membership/product/list?performance_id=474134&app_type=1" > /dev/null
+# 查日志：第一次有 "membership GetProductList loaded, platform:xxx count:N"
+# 第二次无 DB 查询日志（命中缓存）
+```
+
+### 1.5 售卖窗口外
+```sql
+UPDATE membership_product_sku SET sale_end_time = '2025-01-02 00:00:00' WHERE sku_code = 'test-kg-vip-month';
+```
+```bash
+curl -s "${HOST}/membership/product/list?performance_id=474134&app_type=1" | jq '.list[] | select(.sku_code=="test-kg-vip-month")'
+# 预期：空
+```
+```sql
+-- 恢复
+UPDATE membership_product_sku SET sale_end_time = '2027-12-31 00:00:00' WHERE sku_code = 'test-kg-vip-month';
+```
+
+---
+
+## 链 2：订单创建
+
+### 2.1 正常下单（记录 orderNo 供后续使用）
+```bash
+# 酷狗用户下单
+curl -s -X POST "${HOST}/membership/order/create" \
+  -H 'Content-Type: application/json' \
+  -d '{"userid":XXXXXXXXX,"app_type":1,"sku_code":"test-kg-vip-month","num":1,"ext":"{}"}' | jq .
+# 预期：{"order_no":"...", "price_total":1500, "expire_time":"2026-..."}
+# ⚠️ 记下 order_no → 暴露 ORD_KG_1="..."
+```
+```bash
+# Q音用户下单
+curl -s -X POST "${HOST}/membership/order/create" \
+  -H 'Content-Type: application/json' \
+  -d '{"userid":YYYYYYYYY,"app_type":2,"sku_code":"test-qm-vip-month","num":1,"ext":"{\"c_field\":\"1_2\"}"}' | jq .
+# ⚠️ 记下 order_no → 暴露 ORD_QM_1="..."
+```
+```bash
+# 酷我用户下单
+curl -s -X POST "${HOST}/membership/order/create" \
+  -H 'Content-Type: application/json' \
+  -d '{"userid":ZZZZZZZZZ,"app_type":3,"sku_code":"test-kw-vip-month","num":1,"ext":""}' | jq .
+# ⚠️ 记下 order_no → 暴露 ORD_KW_1="..."
+```
+
+### 2.2 多数量下单
+```bash
+curl -s -X POST "${HOST}/membership/order/create" \
+  -H 'Content-Type: application/json' \
+  -d '{"userid":XXXXXXXXX,"app_type":1,"sku_code":"test-kg-vip-month","num":3}' | jq .
+# 预期：price_total=4500（=1500*3）
+# ⚠️ 记下 order_no → 暴露 ORD_KG_NUM3="..."
+```
+```sql
+SELECT order_no, num, price_payable FROM membership_order WHERE order_no='${ORD_KG_NUM3}';
+-- 预期：num=3, price_payable=4500
+```
+
+### 2.3 Ext 透传
+```sql
+SELECT ext FROM membership_order WHERE order_no='${ORD_QM_1}';
+-- 预期：{"c_field":"1_2"}
+```
+
+### 2.4 SKU 不存在
+```bash
+curl -s -X POST "${HOST}/membership/order/create" \
+  -H 'Content-Type: application/json' \
+  -d '{"userid":XXXXXXXXX,"app_type":1,"sku_code":"bad-sku-not-exist"}' | jq .
+# 预期：返回 20504（MembershipSkuNotAvailableErr）
+```
+
+### 2.5 平台不匹配
+```bash
+# 用酷狗用户买 Q音 SKU
+curl -s -X POST "${HOST}/membership/order/create" \
+  -H 'Content-Type: application/json' \
+  -d '{"userid":XXXXXXXXX,"app_type":1,"sku_code":"test-qm-vip-month"}' | jq .
+# 预期：返回 20504（MembershipSkuNotAvailableErr，sku platform=102 ≠ app_type=1）
+```
+
+### 2.6 重复下单保护
+```bash
+# 先完成一次下单
+curl -s -X POST "${HOST}/membership/order/create" \
+  -H 'Content-Type: application/json' \
+  -d '{"userid":XXXXXXXXX,"app_type":1,"sku_code":"test-kg-vip-month"}' | jq .
+# 记下 order_no → ORD_KG_DUP="..."
+```
+```sql
+-- 手工制造"已支付"假数据
+UPDATE membership_order SET order_status=2, pay_status=2, version=1, price_paid=1500, paid_at=NOW() WHERE order_no='${ORD_KG_DUP}';
+```
+```bash
+# 再次检查重复
+curl -s "${HOST}/membership/order/repeat_check?userid=XXXXXXXXX&app_type=1" | jq .
+# 预期：need_block=true, product_name 非空
+```
+
+### 2.7 参数校验
+```bash
+# userid=0
+curl -s -X POST "${HOST}/membership/order/create" \
+  -H 'Content-Type: application/json' \
+  -d '{"userid":0,"app_type":1,"sku_code":"test-kg-vip-month"}' | jq .
+```
+```bash
+# 不传 sku_code
+curl -s -X POST "${HOST}/membership/order/create" \
+  -H 'Content-Type: application/json' \
+  -d '{"userid":XXXXXXXXX,"app_type":1}' | jq .
+# 两个预期都返回 ParamErr
+```
+
+---
+
+## 链 3：支付
+
+### 3.1 发起支付
+```bash
+curl -s -X POST "${HOST}/membership/order/pay" \
+  -H 'Content-Type: application/json' \
+  -d '{"userid":XXXXXXXXX,"app_type":1,"order_no":"${ORD_KG_1}","pay_type":1,"openid":"test-openid-xxx"}' | jq .
+# 预期：返回 pay_data 对象
+```
+
+### 3.2 iOS → 小程序支付
+```bash
+# 需要 middleware 注入 client_code 到 context，如果本地无法注入，改为直接调用 inner 接口验证日志：
+# 把订单状态重置为待支付
+mysql> UPDATE membership_order SET order_status=1, pay_status=1, version=version+1 WHERE order_no='${ORD_KG_1}';
+# 修改 model 验证代码后通过日志验证：
+# grep "PayOrder WxMiniprogramPay req" /path/to/log
+```
+
+### 3.5 iOS 无 Openid 报错
+```bash
+# 需要 client_code 含 "ios"。本地不好模拟，可以在 PayOrder 方法里打 log 确认分支。
+# 替代验证：修改代码临时让 isIOS=true，不传 openid，应返回 ParamErr
+```
+
+### 3.6 Q音 BizAppID
+```bash
+curl -s -X POST "${HOST}/membership/order/pay" \
+  -H 'Content-Type: application/json' \
+  -d '{"userid":YYYYYYYYY,"app_type":2,"order_no":"${ORD_QM_1}","pay_type":1,"openid":"test-openid-xxx"}' | jq .
+# 日志关键词：grep "qqmusic_biz_key"
+```
+
+### 3.7 酷狗 BizAppID
+```bash
+curl -s -X POST "${HOST}/membership/order/pay" \
+  -H 'Content-Type: application/json' \
+  -d '{"userid":XXXXXXXXX,"app_type":1,"order_no":"${ORD_KG_1}","pay_type":1,"openid":"test-openid-xxx"}' | jq .
+# 日志关键词：grep "kugou_biz_key"
+```
+
+### 3.8 支付回调
+```bash
+# 先确保订单 order_status=1（待支付）
+mysql> UPDATE membership_order SET order_status=1, pay_status=1, version=version+1 WHERE order_no='${ORD_KG_1}';
+```
+```bash
+curl -s "${HOST}/inner/v1/membership/order/pay_notify?order_no=${ORD_KG_1}&appid=123&sign=abc&out_trade_no=TEST_TRADE_001&trade_status=1" 
+# 预期：返回 "success"
+```
+```sql
+SELECT order_status, pay_status, price_paid FROM membership_order WHERE order_no='${ORD_KG_1}';
+-- 预期：order_status=2(Paid), pay_status=2
+```
+
+### 3.9 重复回调幂等
+```bash
+curl -s "${HOST}/inner/v1/membership/order/pay_notify?order_no=${ORD_KG_1}&appid=123&sign=abc&out_trade_no=TEST_TRADE_001&trade_status=1"
+# 预期：仍返回 "success"，不报错
+```
+
+---
+
+## 链 4：履约发放
+
+### 4.1 手动触发履约
+```bash
+# 酷狗订单（先确认已支付：order_status=2）
+curl -s -X POST "${HOST}/inner/v1/membership/order/fulfill" \
+  -H 'Content-Type: application/json' \
+  -d "{\"order_no\":\"${ORD_KG_1}\"}"
+# 预期：返回成功
+```
+```sql
+SELECT order_status, completed_at FROM membership_order WHERE order_no='${ORD_KG_1}';
+-- 预期：order_status=4(Completed)
+```
+
+### 4.2 酷狗会员发放日志
+```bash
+grep "kugou Grant VipCreateOrder req" /path/to/log | tail -1
+grep "kugou Grant VipCreateOrder resp" /path/to/log | tail -1
+```
+
+### 4.3 Q音会员发放日志
+```bash
+# 先让 Q音订单也变成已支付再调 fulfill
+mysql> UPDATE membership_order SET order_status=2, pay_status=2, version=version+1, price_paid=1500, paid_at=NOW() WHERE order_no='${ORD_QM_1}';
+```
+```bash
+curl -s -X POST "${HOST}/inner/v1/membership/order/fulfill" \
+  -H 'Content-Type: application/json' \
+  -d "{\"order_no\":\"${ORD_QM_1}\"}"
+grep "qmusic Grant" /path/to/log | tail -2
+```
+
+### 4.4 酷我会员发放日志
+```bash
+mysql> UPDATE membership_order SET order_status=2, pay_status=2, version=version+1, price_paid=1500, paid_at=NOW() WHERE order_no='${ORD_KW_1}';
+```
+```bash
+curl -s -X POST "${HOST}/inner/v1/membership/order/fulfill" \
+  -H 'Content-Type: application/json' \
+  -d "{\"order_no\":\"${ORD_KW_1}\"}"
+grep "kuwo Grant" /path/to/log | tail -2
+```
+
+### 4.5 发放幂等
+```bash
+# 再调一次同一个 order_no
+curl -s -X POST "${HOST}/inner/v1/membership/order/fulfill" \
+  -H 'Content-Type: application/json' \
+  -d "{\"order_no\":\"${ORD_KG_1}\"}"
+grep "fulfillment skipped by idempotency" /path/to/log | tail -1
+```
+
+### 4.6 数量×发放周期
+```bash
+# 用多数量订单 ORD_KG_NUM3（num=3, member_type=1 月卡）
+mysql> UPDATE membership_order SET order_status=2, pay_status=2, version=version+1, price_paid=4500, paid_at=NOW() WHERE order_no='${ORD_KG_NUM3}';
+```
+```bash
+curl -s -X POST "${HOST}/inner/v1/membership/order/fulfill" \
+  -H 'Content-Type: application/json' \
+  -d "{\"order_no\":\"${ORD_KG_NUM3}\"}"
+grep "kugou Grant VipCreateOrder req" /path/to/log | tail -1 | grep "month"
+# 预期：month=3（月卡×3 份=3 个月）
+```
+
+### 4.7 发放失败重试
+```bash
+# 构造一条新订单并支付
+curl -s -X POST "${HOST}/membership/order/create" \
+  -H 'Content-Type: application/json' \
+  -d '{"userid":XXXXXXXXX,"app_type":1,"sku_code":"test-kg-vip-month","num":1}' | jq -r '.order_no'
+# 记下 → EXPORT ORD_KG_FAIL1="..."
+mysql> UPDATE membership_order SET order_status=2, pay_status=2, version=version+1, price_paid=1500, paid_at=NOW() WHERE order_no='${ORD_KG_FAIL1}';
+```
+```bash
+# 触发履约（如酷狗 RPC 不可达会失败）
+curl -s -X POST "${HOST}/inner/v1/membership/order/fulfill" \
+  -H 'Content-Type: application/json' \
+  -d "{\"order_no\":\"${ORD_KG_FAIL1}\"}"
+```
+```sql
+SELECT o.order_status, f.fulfillment_status, f.retry_strategy, f.next_retry_at
+FROM membership_order o
+JOIN membership_order_fulfillment f ON o.order_no = f.order_no
+WHERE o.order_no = '${ORD_KG_FAIL1}';
+-- 预期：fulfillment_status=3, retry_strategy=1, next_retry_at > NOW()
+```
+
+### 4.8 履约状态锁
+```bash
+# 同一订单同时发两个 fulfill 请求（用 & 后台）
+curl -s -X POST "${HOST}/inner/v1/membership/order/fulfill" \
+  -H 'Content-Type: application/json' \
+  -d "{\"order_no\":\"${ORD_KG_1}\"}" &
+curl -s -X POST "${HOST}/inner/v1/membership/order/fulfill" \
+  -H 'Content-Type: application/json' \
+  -d "{\"order_no\":\"${ORD_KG_1}\"}" &
+wait
+# 日志中一个 "state locked for grant"，另一个 "already processing and not timeout"
+```
+
+---
+
+## 链 5：履约失败重试 Cron
+
+### 5.1 重试扫描
+```bash
+# 确保 4.7 留下了失败记录，然后手动改 next_retry_at 为过去
+mysql> UPDATE membership_order_fulfillment SET next_retry_at = '2020-01-01 00:00:00', retry_strategy=1 WHERE order_no='${ORD_KG_FAIL1}';
+```
+```bash
+# 启动 cron
+./cli membership_fulfill_retry -l=10 -k=lock_test_fulfill_retry 2>&1 | tail -5
+# 预期：日志 "membership fulfill retry success" 或 "deferred again"
+```
+
+### 5.2 处理中超时
+```sql
+-- 模拟一条卡在 Processing 且超时（>15 分钟前开始）的记录
+UPDATE membership_order_fulfillment
+SET fulfillment_status = 1, processing_started_at = DATE_SUB(NOW(), INTERVAL 20 MINUTE)
+WHERE order_no = '${ORD_KG_FAIL1}';
+```
+```bash
+./cli membership_fulfill_retry -l=10 -k=lock_test_fulfill_retry 2>&1 | tail -3
+# 预期：该记录被重新触发
+```
+
+### 5.3 未到重试时间
+```sql
+UPDATE membership_order_fulfillment SET next_retry_at = DATE_ADD(NOW(), INTERVAL 1 HOUR), fulfillment_status=3 WHERE order_no='${ORD_KG_FAIL1}';
+```
+```bash
+./cli membership_fulfill_retry -l=10 -k=lock_test_fulfill_retry 2>&1 | tail -3
+# 预期：日志 "finished, retryable: 0"
+```
+
+---
+
+## 链 6：业务方通知
+
+### 6.1 履约成功后通知
+```sql
+-- 找一个已完成履约的订单
+SELECT order_no, biz_notify_status FROM membership_order WHERE order_no='${ORD_KG_1}';
+-- 预期：biz_notify_status=1（只要通知接口可达）
+```
+
+### 6.2 通知失败吞错误
+```bash
+# 构造新订单走完 链2→链3→链4 流程，如果回调接口失败（本地环境降级验证）：
+```
+```sql
+-- 手工修改为"已完成但未通知"
+UPDATE membership_order SET biz_notify_status=0, biz_notify_retry_count=0, biz_notify_next_retry_at='1970-01-01 00:00:00' WHERE order_no='${ORD_KG_1}';
+```
+```bash
+# 通过 RetryBizNotify 触发的日志验证：
+grep "biz notify callback failed" /path/to/log | tail -1
+```
+
+### 6.3 通知重试 cron
+```sql
+-- 制造一条待通知订单
+UPDATE membership_order SET biz_notify_status=0, biz_notify_retry_count=0, biz_notify_next_retry_at='2020-01-01 00:00:00' WHERE order_status=4 AND order_no='${ORD_KG_1}';
+```
+```bash
+./cli membership_biz_notify_retry -l=10 2>&1 | tail -5
+# 预期：日志 "biz notify retry finished, count:1"
+```
+
+### 6.4 重试间隔递增
+```sql
+-- 模拟第一次重试失败，把 next_retry_at 改过去
+UPDATE membership_order SET biz_notify_retry_count=0, biz_notify_next_retry_at='2020-01-01 00:00:00', biz_notify_status=0 WHERE order_no='${ORD_KG_1}';
+```
+```bash
+./cli membership_biz_notify_retry -l=10 2>&1 | tail -3
+```
+```sql
+SELECT biz_notify_retry_count, biz_notify_next_retry_at FROM membership_order WHERE order_no='${ORD_KG_1}';
+-- 预期：retry_count=1, next_retry_at ≈ NOW()+30s（Apollo 默认间隔）
+```
+
+### 6.5 超过最大重试次数
+```sql
+-- 手动设满
+UPDATE membership_order SET biz_notify_retry_count=99, biz_notify_next_retry_at='2020-01-01 00:00:00' WHERE order_no='${ORD_KG_1}';
+```
+```bash
+./cli membership_biz_notify_retry -l=10 2>&1 | tail -3
+```
+```sql
+SELECT biz_notify_retry_count FROM membership_order WHERE order_no='${ORD_KG_1}';
+-- 预期：count 不变（≥ 5 = Apollo max，不再重试）
+```
+
+### 6.6 通知请求体映射
+```bash
+grep "biz notify request built" /path/to/log | tail -1
+# 预期日志：user_id=XXXXXXXXX, quantity=1, product_id=test-kg-vip-month
+```
+
+### 6.7 Extend 原样透传
+```bash
+grep "MembershipBizNotifyCallback" /path/to/log | tail -3
+# 检查请求 body 中的 Extend 字段是否和 order.Ext 一致
+```
+
+---
+
+## 链 7：订单管理
+
+### 7.1 查询状态
+```bash
+curl -s "${HOST}/membership/order/query_status?userid=XXXXXXXXX&app_type=1&order_no=${ORD_KG_1}" | jq .
+# 预期：{"status":4}
+```
+
+### 7.2 取消订单（需先有未支付订单）
+```bash
+# 创建一条新订单
+ORD_KG_CANCEL=$(curl -s -X POST "${HOST}/membership/order/create" \
+  -H 'Content-Type: application/json' \
+  -d '{"userid":XXXXXXXXX,"app_type":1,"sku_code":"test-kg-vip-month","num":1}' | jq -r '.order_no')
+echo "ORD_KG_CANCEL=${ORD_KG_CANCEL}"
+```
+```bash
+curl -s -X POST "${HOST}/membership/order/cancel" \
+  -H 'Content-Type: application/json' \
+  -d "{\"userid\":XXXXXXXXX,\"app_type\":1,\"order_no\":\"${ORD_KG_CANCEL}\"}" | jq .
+```
+```sql
+SELECT order_status, pay_status FROM membership_order WHERE order_no='${ORD_KG_CANCEL}';
+-- 预期：order_status=5, pay_status=4
+```
+
+### 7.3 已支付不能取消
+```bash
+curl -s -X POST "${HOST}/membership/order/cancel" \
+  -H 'Content-Type: application/json' \
+  -d "{\"userid\":XXXXXXXXX,\"app_type\":1,\"order_no\":\"${ORD_KG_1}\"}" | jq .
+# 预期：返回 MembershipOrderStatusInvalidErr
+```
+
+### 7.4 订单详情
+```bash
+curl -s "${HOST}/membership/order/detail?userid=XXXXXXXXX&app_type=1&order_no=${ORD_KG_1}" | jq .
+# 预期：product_name、icon、price_total、order_status 都和 DB 一致
+```
+
+### 7.5 订单列表
+```bash
+curl -s "${HOST}/membership/order/list?userid=XXXXXXXXX&app_type=1&page=1&page_size=5" | jq '{has_more,count: (.list|length)}'
+# 预期：有记录，has_more 正确
+```
+
+### 7.6 数量展示
+```bash
+curl -s "${HOST}/membership/order/detail?userid=XXXXXXXXX&app_type=1&order_no=${ORD_KG_NUM3}" | jq '.order | {quantity, price_total}'
+# 预期：quantity=3
+```
+
+---
+
+## 链 8：会员优先购权限
+
+### 8.1 未登录
+```bash
+curl -s "${HOST}/v1/performance/detail?performance_id=474134&app_type=1&userid=0" | jq '.performance_vip_sale_permission'
+# 预期：{"eligible":false,"reason":"not_logged_in"} 或 null（无配置时）
+```
+
+### 8.2 平台不匹配
+```bash
+curl -s "${HOST}/v1/performance/detail?performance_id=474134&app_type=1&userid=XXXXXXXXX" | jq '.performance_vip_sale_permission'
+# 检查 reason 字段（有配置时可能是 eligible 或 platform_mismatch）
+```
+
+### 8.3 非 VIP 用户
+```bash
+# 用一个不是 VIP 的普通用户查
+curl -s "${HOST}/v1/performance/detail?performance_id=474134&app_type=1&userid=999999999" | jq '.performance_vip_sale_permission'
+# 预期：reason 为 not_eligible 或 check_degraded（取决于 RPC 是否可达）
+```
+
+### 8.4 无 VIP 配置演出
+```bash
+curl -s "${HOST}/v1/performance/detail?performance_id=474134&app_type=1&userid=XXXXXXXXX" | jq 'keys | contains(["performance_vip_sale_config"])'
+# 如果演出未配置优先购，预期：false（字段不下发）
+```
+
+---
+
+## 链 9：日志验证
+
+```bash
+# 全部链跑完后，汇总 grep 检查
+echo "=== 下单 ==="
+grep "CreateOrder success" /path/to/log | tail -3
+
+echo "=== 支付 RPC ==="
+grep "PayOrder.*Pay.*req\|PayOrder.*Pay.*resp" /path/to/log | tail -4
+
+echo "=== 履约发放 RPC ==="
+grep "Grant .*req\|Grant .*resp" /path/to/log | tail -6
+
+echo "=== 履约步骤 ==="
+grep "fulfillment prepare start\|fulfillment prepared\|fulfillment finalize success" /path/to/log | tail -5
+
+echo "=== 业务通知 ==="
+grep "biz notify" /path/to/log | tail -5
+
+echo "=== Cron 重试 ==="
+grep "membership.*retry finished" /path/to/log | tail -3
+```
+
+---
+
+## 测试完成检查
+
+```bash
+# 最终编译验证
+go build ./...
+
+# 最终单元测试
+go test ./service/biz/membership/... -count=1
+
+# ⚠️ 清理测试数据（可选）
+mysql> DELETE FROM membership_order WHERE order_no LIKE 'MC%' AND user_id IN (XXXXXXXXX, YYYYYYYYY, ZZZZZZZZZ);
+mysql> DELETE FROM membership_order_fulfillment WHERE order_no LIKE 'MC%';
+```