Files
junhong_cmp_fiber/openspec/changes/finalize-unified-stop-resume-rule/proposal.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

36 lines
4.3 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.
## Why
`Iteration/8-11` 已实现停复机新规则,但靠总开关与旧口径并存:代码里同时保留两套实名判断与复机条件,实名轮询仍按行业卡跳过,与"按运营商账户实名管控"的新口径不一致。后续停复机指令队列(第 6 个 Change)需要唯一口径。另一方面,生产 2026-10-24 实查:停机、开启轮询且有生效套餐的卡中,`not_realname` 15,059 张、`carrier_stopped` 998 张、停因为空 83 张、`manual` 22 张;所有账户实名管控默认 0,新规则开启即可能批量复机,必须先演练。本 Change 是《轮询按运营商账户限流技术方案》第五部分第 3 节第 4 步。
## What Changes
- **BREAKING** 新规则转正:删除总开关 `stop_resume.unified_rule_enabled`(`JUNHONG_STOP_RESUME_UNIFIED_RULE_ENABLED`)及其配置、部署变量与全部分支;删除旧口径(行业卡放行、卡或设备 `realname_policy` 放行、只对轮询停因自动复机、`ListByDeviceIDAndPollingStopReasons`)。
- 复机不看停机原因,包括运营商侧主动停机 `carrier_stopped`:是否复机只由本系统规则决定。
- **BREAKING** 实名轮询改为:卡所属运营商账户未开实名管控时跳过查实名;不再按行业卡跳过。
- 风险停机、已销户必须关闭轮询:保留现有查状态自动关闭;补齐绑定设备的卡(只关该卡自身,不级联设备)与停复机调用直接返回终态两种情况;错误分类规则增加"自动关闭轮询"标记,只允许终态类别勾选。
- 新增停复机规则演练接口:对全部停机与开机卡按规则只判断不执行,按运营商账户 × 停机原因 × 判断结果输出汇总与明细,可传入假设的实名管控配置预演,明细可导出。
- 通道阈值新周期解锁后的复机条件随转正去掉总开关表述;同时去掉已下线的"保护期强制复机"表述。
- 上线前演练作为发布前置步骤写入任务。
## Capabilities
### New Capabilities
(无)
### Modified Capabilities
- `card-stop-resume`:删除总开关要求;停机、复机、实名管控要求去掉"总开关开启时"前提;复机明确包含 `carrier_stopped`;新增实名轮询按账户实名管控跳过、风险停机与已销户关闭轮询补齐、规则演练。(该能力由 `rebuild-card-traffic-metering-and-stop-resume` 引入,本 Change 要求其先归档。)
- `polling-operations`:删除"停复机遵循实际生效实名策略"(旧口径)。
- `carrier-channel-traffic-threshold`:"通道阈值停机与周期恢复"去掉总开关与保护期表述,复机条件固定为 `card-stop-resume` 的复机条件。
- `gateway-call-observability`:错误分类规则增加"自动关闭轮询"标记(该能力由第 1 个 Change 引入)。
## Impact
- 依赖:`rebuild-card-traffic-metering-and-stop-resume` 已归档并上线生产(总开关可仍关闭);第 1 个 Change(错误分类)与第 3 个 Change(去掉保护期)已上线。
- **分两次发布**:第一次发布演练接口与关闭轮询补齐,总开关仍关闭、停复机行为不变;运营为需要实名的账户设置 `realname_control_enabled = 1`,用演练核对"将被复机 / 将被停机"的卡并导出确认,需保持停机的卡先关闭轮询,然后维护者开启总开关;新规则稳定运行后第二次发布删除总开关与旧口径、实名轮询改口径。
- 数据库:新增成对迁移,`tb_gateway_error_classification` 增加 `auto_disable_polling` 列并为"已销户""风险停机"类规则置位。
- 代码:`internal/service/iot_card/stop_resume_unified.go` 并入主逻辑;`stop_resume_service.go` 删除旧分支;`internal/task/polling_realname_handler.go:70`;`internal/domain/cardobservation/network.go` `ShouldStopPollingForRisk` 去掉独立卡限制;停复机失败处理接入"自动关闭轮询";`pkg/config/config.go`、`loader.go`、`defaults/config.yaml`、`.gitea/workflows/deploy.yaml`、`docker-compose.prod.yml` 删除总开关;新增演练 Query 与接口。
- 接口:新增 `GET /stop-resume-rule/dry-run` 与导出场景 `stop_resume_rule_dry_run`;错误分类接口增加 `auto_disable_polling` 字段。
- 行为:开启实名管控的账户下,行业卡未实名也会被停机;未开实名管控的账户不再查实名。