Files
go-sms-V2/docs/acceptance/s4-d1d2-callback.md
T
Tory bb60d60529
ci / test (push) Canceled after 0s
ci / web-test (push) Canceled after 0s
ci / build (push) Canceled after 0s
ci / deploy-dev (push) Canceled after 0s
S4-D1/D2: C1 回调推送引擎+C2 上行自动拉黑——验收项「死信可查/拒收即拉黑」✅: ①C1=callback_task 队列表(迁移 v21,状态机 pending→sent/dead+attempt/next_retry_at/last_code)+PushWorker(2s 扫/批 100/并发 8/2^n 秒指数退避封顶 10min/10 次耗尽死信/UPDATE CAS 防竞态)+双挂点(report 终态首锁[Consumer+PairService,与 CMPP Deliver 同点同语义]+uplink 消费尾)+URL 门控 account_config.report_url/uplink_url(60s TTL 缓存,未配置零任务)+GET /ops/callback(列表+状态计数面板)/POST /ops/callback/:id/resend(casbin ops callback:read/write v21 所种)+前端回调管理页(ops-callback 路由系统管理组+api/callback.ts+状态面板/筛选/载荷展开/死信重派;matrix+guard 33 菜单显式更)+metrics callback_push_total{type,result}/blacklist_total+openapi v1.4.0;②C2=AutoBlacklister 等值词表(trim+lower 防误伤,默认 R/TD/退订/拒收;SystemConfig uplink.blacklist.keywords 可配 60s 刷新)→policy_blacklist(source=2/账号级/uk 幂等)+Redis Set 即时生效,拉黑不影响上行推送(需求原文);③真机全链六步实证(dev 中间件):回执 DELIVRD→detail 终态→HTTP 回调 JSON 送达(200/sent)+上行 R→拉黑(source=2+Redis=1)+推送送达+坏 URL→attempt10→dead→resend ISC:000→修复重投 sent+status_counts 面板;一次性探针 cmd/cbprobe 用后即删+冒烟数据全清;④单测 +13(callback 6[入队门控/载荷/状态机全链/并发批]+uplink 5[词表/配置覆盖/幂等缓存/消费链]+report 2[首锁一次/nil]);⑤门禁=build/vet/-race 40 包/lint 0/eslint0/vue-tsc0/vitest 148/build 全绿;迁移测试 v15..v21 两遍幂等+dev 实跑 v21;gofmt 存量 8 文件顺手清零(S2 遗留);⑥口径诚实标注:载荷无签名挂账/拦截终态 HTTP 未挂(CMPP 侧已有)/PushWorker 单实例 at-least-once;验收单 s4-d1d2-callback.md+CHANGELOG+memory-bank 回填
2026-11-16 11:19:55 +08:00

5.0 KiB

S4 验收单 D1/D2:C1 回调推送引擎 + C2 上行自动拉黑(2026-11-16)

泳道:S4 C1/C2+冷热(3 计划日)第 1-2 日;验收项「死信可查 / 拒收即拉黑」✅(冷查<1s 属 D3 未验)。

一、交付范围

C1 HTTP 回调推送引擎(需求 2.5 / 实施计划 5.8)

组件 文件 说明
队列表 entity/callback.go + 迁移 v21_callback_domain callback_task(状态机 0 待推送/1 已送达/2 死信;attempt/next_retry_at/last_code/last_err;idx_cb_status_retry 扫描索引);casbin 种 ops callback:read/write
入队服务 service/callback/callback.go EnqueueReport(终态首锁后)/EnqueueUplink(上行消费后);URL 门控=account_config.report_url/uplink_url(60s TTL 内存缓存,未配置零任务);Resend(死信 CAS 重派)
推送引擎 service/callback/worker.go PushWorker 2s 扫描/批 100/并发 8/单请求 5s 超时;2xx→sent;失败 2^attempt 秒指数退避(封顶 10min);10 次耗尽→dead;UPDATE CAS 防并发竞态
挂点 report/consumer.go + report/pair.go 与 CMPP Deliver 同点(finalizeDetail 首锁后,事务提交后动作,与 bill.Confirm 同构);手动配对终态同推
挂点 uplink/consumer.go 匹配回填→拉黑→推送(拉黑不影响推送,需求原文)
管理端点 api/http/v1/callback_handler.go GET /ops/callback(列表+状态计数面板)/ POST /ops/callback/:id/resend;openapi v1.4.0
管理页 web/src/views/ops/callback/index.vue + api/callback.ts 状态面板(待推送/已送达/死信存量)+筛选+载荷展开+死信重派;路由 ops-callback(admin/ops,系统管理组)
观测 metrics go_sms_callback_push_total{type,result=sent/retry/dead} + go_sms_callback_blacklist_total
装配 cmd/consumer(引擎+双挂点)/ cmd/gateway(PairService+管理面) —

C2 上行自动拉黑(需求 2.5 / 实施计划 5.7)

组件 说明
uplink/blacklist.go AutoBlacklister:词表等值匹配(trim+lower,默认 R/TD/退订/拒收)——防「我要退订它」类正常回复误伤;SystemConfig uplink.blacklist.keywords 逗号分隔可配,60s 刷新
落库 policy_blacklist INSERT OnConflict DoNothing(source=2 上行拒收,账号级=归属账号,operator=uplink-auto;幂等锚 uk_mobile_account)
即时生效 interceptor.AddBlacklistCache → Redis Set gosms:blacklist:local(拦截链一级缓存,下一单即拦)

二、真机全链冒烟(dev MySQL/Kafka/Redis,2026-11-16 11:15)

  1. 回执终态→HTTP 回调:种子 detail(73021000101,status=1)+seg(cbprobe-m1)→ 投 sms-report DELIVRD → 明细 2(SUCCESS)→ callback_task#2 type=1 → PushWorker 推送 → 接收端收到 /report {"type":"report","detail_id":73021000101,…,"status":2,"stat":"SUCCESS"},status=1/last_code=200 ✅
  2. 上行→拉黑+推送:投 sms-up(content="R",account=90001)→ policy_blacklist(mobile=13877776666,source=2,operator=uplink-auto)✅ + Redis SISMEMBER=1 ✅ + 接收端收到 /uplink {…,"content":"R"} ✅(拉黑不影响推送实证)
  3. 死信→重派:坏 URL 任务 attempt=9 → 一轮失败 attempt=10 → status=2 dead(last_err=connection refused)✅ → POST /ops/callback/3/resend ISC:000 → URL 修复后重投 → status=1/sent/200 ✅
  4. 管理面:GET /ops/callback?status=2 → list 含死信行 + status_counts={dead:1,sent:2} ✅(非侵入 JWT,走查脚本同法)
  5. metrics::8082 go_sms_callback_push_total{result="sent",type="report"}=1 / go_sms_callback_blacklist_total=1 ✅
  6. 冒烟数据全清(callback_task/policy_blacklist/detail/seg 删除;account_config URL 置空);一次性探针 cmd/cbprobe 用后即删。

三、门禁(七件套)

  • 后端:build ✓ / vet ✓ / -race 40 包全绿 / golangci-lint 0 issues / 迁移测试末七窗口 v15..v21 两遍幂等+v21 断言;dev 库实跑 v21(callback_task 表+casbin 两策略核验)。
  • 前端:eslint 0 警 / vue-tsc 0 / vitest 148 全绿(role-menu-matrix +ops-callback;guard 菜单 32→33 显式更)/ build ✓。
  • 单测增量:callback 6 件(入队门控/载荷/状态机全链 500→退避→死信→重派→送达/并发批)+ uplink 5 件(词表/SystemConfig 覆盖/幂等+缓存/消费链挂点)+ report 2 件(首锁入队一次/nil 零开销)。

四、口径与假设(诚实标注)

  1. 载荷无签名:POST JSON 不带签名头(需求未定义);客户侧回调地址建议内网/HTTPS。后续可加 X-Gosms-Signature=md5(api_secret+body)(挂账)。
  2. 拦截终态(受理期 ISC:xxx 拒收)暂不入 HTTP 回调:CMPP 侧经 blockedDeliverAdapter 已推;HTTP 侧待用户反馈需求后再挂(范围控制)。
  3. 多实例部署:PushWorker 单实例语义;多实例重复推送容忍(at-least-once,CAS 保证状态机,客户端幂等兜底)——与 CMPP Deliver 同语义。
  4. 退避参数:2s 扫描/2^n 秒退避(封顶 10min)/10 次(累计 ~17min)为保守起步;S5 压测期重标。
  5. 浏览器页面走查(回调管理页)留待用户本人(:5173,admin/ops 可见「系统管理→回调管理」)。