Files
junhong_cmp_fiber/openspec/changes/finalize-unified-stop-resume-rule/design.md
邹进 42e881576d
All checks were successful
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Successful in 9m33s
feat: 卡网关按运营商账户限流并记录停复机调用
- 新增网关限流:按本系统运营商账户(卡 carrier_id)→ 限流组 → 操作限制每秒请求数,每次 HTTP 尝试计量,默认限流、仅后台人工点击/通道阈值/自动续费/手动刷新豁免;支持只统计与拦截两种模式,默认只统计
- Asynq 遇限流不计失败、固定短延迟重试;轮询任务与停复机业务重试遇限流短延迟重排
- 停机、复机不再使用网关内部重试,只发一次请求
- 网关返回结构化错误;新增上游错误分类规则表与测试接口
- 新增按月分区的停复机记录表:系统自动停复机只写记录,不再写统一审计与集成日志;普通轮询查询不再写集成日志
- 新增限流组、错误分类、停复机记录、按账户调用统计与枚举后台接口
- 迁移 000243~000246;同步 OpenSpec 提案(含后续 6 个 change)与技术方案、工程约束
2026-10-24 15:06:41 +09:00

41 lines
3.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
## Context
依据 `docs/engineering/轮询按运营商账户限流技术方案.md` 第三部分第 12 节、第五部分第 3 节前置条件与"上线前演练"。
现状:
- `internal/service/iot_card/stop_resume_unified.go`:`unifiedStopResumeEnabled()` 读 `cfg.StopResume.UnifiedRuleEnabled`;`autoResumableStopReason`、`autoControlSuspended`、`unifiedRealnameOK` 在开关开启时生效,关闭时走 `isRealnameOK` 旧分支与 `isPollingStopReason`。
- 迁移 242:`tb_carrier.realname_control_enabled` 默认 0;生产库仍为迁移 240(未上线)。
- `internal/task/polling_realname_handler.go:70`:行业卡跳过实名查询。
- `internal/domain/cardobservation/network.go:88` `ShouldStopPollingForRisk` 要求 `isStandalone`;生产 8,420 张风险停机或已销户卡均为独立卡且已关闭轮询。
- 停复机调用返回终态时只按失败处理,不关闭轮询。
## Goals / Non-Goals
**Goals:** 停复机只有一套口径;实名轮询与实名管控口径一致;风险停机与已销户无论如何发现都关闭轮询;开启前可预演影响。
**Non-Goals:** 不改停复机触发路径与执行方式(第 6 个 Change);不改暂停轮询的套餐失效停机与自动恢复轮询(第 6、7 个 Change);不改激活状态计算口径。
## Decisions
1. **先演练开启、再删除开关**:保留开关会长期双口径,但演练必须早于开启;故第一次发布只加演练与补齐、不改口径,开启并稳定后第二次发布删除开关。
2. **复机含 `carrier_stopped`**:用户已定"只看本系统规则"。上游终态卡由关闭轮询兜底,不进入自动复机;未识别的终态由错误分类在复机失败时识别并关闭轮询。
3. **关闭轮询只作用于卡自身**:设备下其他卡仍可能正常使用;`autoControlSuspended` 按卡判断,该卡不再参与自动停复机,设备维度判断对其余卡照常。
4. **终态关闭轮询由规则标记驱动**:在错误分类表加 `auto_disable_polling`,而不是在代码里写死关键字,符合"数值与分组由配置决定"。关闭时同事务回写 `gateway_extend`,并写不轮询清单(第 7 个 Change 上线后;之前只改 `enable_polling` 并写审计)。
5. **演练用读侧 Query**:复用统一判断函数,输入卡与资产当前数据和可选的假设实名管控配置,输出目标状态;按批读取、只读,不经聚合根写状态。明细导出复用统一导出任务。
## Risks / Trade-offs
- [开启实名管控后行业卡被停] → 已知口径变化;演练可按假设配置预演,运营按结果决定是否开启。
- [演练全量扫描较慢] → 按账户分批、只读;导出走异步任务。
- [删除开关后无法快速回到旧口径] → 前置要求新规则已在生产稳定运行;必要时代码回退。
## Migration Plan
演练必须在新规则开启之前可用,因此分两次发布:
1. 第一次发布:迁移(错误分类表加列)、演练接口、风险停机与已销户关闭轮询补齐;总开关仍关闭,停复机行为不变。演练始终按新规则判断,不受总开关影响。
2. 运营:设置需要实名的账户;生产执行演练并导出核对;需保持停机的卡关闭轮询。维护者开启总开关并重启全部进程,首日监控。
3. 第二次发布(新规则稳定后):删除总开关、旧口径与部署环境变量,实名轮询改按账户实名管控跳过。
4. 回退:第一次发布后可直接关闭总开关回到旧口径;第二次发布后需代码回退。