feat: 卡网关按运营商账户限流并记录停复机调用
All checks were successful
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Successful in 9m33s

- 新增网关限流:按本系统运营商账户(卡 carrier_id)→ 限流组 → 操作限制每秒请求数,每次 HTTP 尝试计量,默认限流、仅后台人工点击/通道阈值/自动续费/手动刷新豁免;支持只统计与拦截两种模式,默认只统计
- Asynq 遇限流不计失败、固定短延迟重试;轮询任务与停复机业务重试遇限流短延迟重排
- 停机、复机不再使用网关内部重试,只发一次请求
- 网关返回结构化错误;新增上游错误分类规则表与测试接口
- 新增按月分区的停复机记录表:系统自动停复机只写记录,不再写统一审计与集成日志;普通轮询查询不再写集成日志
- 新增限流组、错误分类、停复机记录、按账户调用统计与枚举后台接口
- 迁移 000243~000246;同步 OpenSpec 提案(含后续 6 个 change)与技术方案、工程约束
This commit is contained in:
邹进
2026-10-24 15:06:41 +09:00
parent 9e45097aa2
commit 42e881576d
106 changed files with 7173 additions and 48 deletions

View File

@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-10-24

View File

@@ -0,0 +1,27 @@
## Context
依据 `docs/engineering/轮询按运营商账户限流技术方案.md` 第一部分第 6 节、第四部分"保护期整套机制"。
现状:后台设备停复机设置 `protect:device:{id}:stop|start`(1 小时,互斥,`internal/service/device/service.go:1506,1663`);保护期内拒绝相反人工操作;`polling:protect` 轮询(`internal/task/polling_protect_handler.go`)方向不一致时 `ForceStopCard` / `ForceStartCard`;自动停复机 `EvaluateAndAct` 不看保护期,造成反复翻转。`ProtectCheckSkipsForRealname`(`stop_resume_unified.go`)仅保护期轮询使用。资产 DTO 有 `device_protect_status`(`asset_dto.go:38,144`、`client_asset_dto.go:75`)。
## Goals / Non-Goals
**Goals:** 删除保护期的设置、检查、轮询与展示逻辑;不破坏现有客户端;数据库只加不删。
**Non-Goals:** 不改停复机业务规则(第 4、6 个 Change);不删 `protect_period` 常量与历史数据;不删数据库列。
## Decisions
1. **字段保留、固定返回 `none`**:直接删字段会让读取该字段的老版本小程序出错;固定值兼容成本最低。备选"字段 omitempty 后不返回":老客户端读不到同样可能出错,放弃。
2. **数据库列只改注释**:遵循"数据库只加不删";`protect_check_interval`、`last_protect_check_at` 列注释标记已废弃,代码中去掉读写。
3. **存量 Redis 保护期 key 不清理**:TTL 只有 1 小时,上线后自然过期;代码不再读取,即使残留也无影响。
4. **Asynq 中已排队的 `polling:protect` 任务**:保留一个空处理函数直接返回成功一个发布周期,避免"未注册任务类型"错误堆积,下一次发布再移除;或上线前确认队列为空。选择保留空处理函数,更稳妥。
## Risks / Trade-offs
- [运营依赖保护期防止误操作] → 已定"规则优先、人工停机无豁免",需要保持停机的关闭轮询(第 7 个 Change 提供批量操作)。
- [前端仍展示保护期] → 固定 `none` 时前端显示"无",不报错;前端随后去掉展示。
## Migration Plan
1. 迁移只改列注释。2. 测试环境验证后由维护者发布生产。3. 回退:代码回退即可恢复保护期逻辑,数据库无需回退。

View File

@@ -0,0 +1,32 @@
## Why
后台对设备停机或复机时会设置 1 小时保护期,保护期内阻止相反的人工操作,`protect` 轮询发现方向不一致时强制停复机。但自动停复机不检查保护期,保护期内会出现"自动停机 → 保护期强制复机 → 再自动停机"的反复翻转,且与"只要符合规则就自动停复机"的原则冲突。本 Change 是《轮询按运营商账户限流技术方案》第五部分第 3 节第 3 步:整体下线保护期,为后续调度与停复机改造减负。
## What Changes
- **BREAKING** 后台设备停机、复机不再设置保护期,也不再因保护期拒绝相反操作;单卡手动停复机去掉保护期检查。
- **BREAKING** 下线 `polling:protect` 轮询任务类型:不再注册、调度、统计与监控;轮询并发配置与任务类型名称不再包含保护期检查。
- 轮询配置的 `protect_check_interval` 不再读写,接口不再接受与返回该字段;数据库列保留,列注释标记已废弃。
- 卡字段 `last_protect_check_at` 不再读写;数据库列保留,列注释标记已废弃。
- 资产接口(后台与 C 端)的 `device_protect_status` **字段保留**,固定返回"无保护期"并在接口文档标记废弃,待前端与老版本小程序不再读取后另行删除。
- 停机原因常量 `protect_period` 保留(历史数据与对外开放接口映射仍需要),不再产生新值;删除 `RedisDeviceProtectKey`、`DeviceProtectPeriodDuration`。
- 存量保护期 Redis key 上线后自然过期(TTL 1 小时),不做迁移。
## Capabilities
### New Capabilities
(无)
### Modified Capabilities
- `polling-operations`:"轮询并发配置覆盖实际任务"去掉 `protect`;"轮询任务类型名称可读"去掉"保护期检查"。
- `asset-device`:新增"设备停复机不设保护期"要求,并约定 `device_protect_status` 字段的兼容返回。
## Impact
- 依赖:无前置 Change。第 4 个 Change 改写通道阈值规范时一并去掉"保护期强制复机"表述。
- 数据库:新增成对迁移,只更新 `tb_polling_config.protect_check_interval`、`tb_iot_card.last_protect_check_at` 的列注释(标记废弃);不删列、不改数据。
- 代码:删除 `internal/task/polling_protect_handler.go` 与 `pkg/queue/handler.go` 中的注册;`internal/service/device/service.go`(不设、不查保护期);`internal/service/iot_card/stop_resume_service.go`(手动停复机去掉保护期检查);`stop_resume_unified.go` 删除 `ProtectCheckSkipsForRealname`;`internal/polling/config_manager.go`、`initializer.go`、调度器去掉 `protect` 类型;`internal/model/dto/polling_config_dto.go`、`asset_dto.go`、`client_asset_dto.go`、`internal/service/asset/service.go`;`pkg/constants`。
- 接口:`/polling-configs` 不再含 `protect_check_interval`;`/polling-concurrency` 不再含 `protect`;资产详情 `device_protect_status` 固定为无保护期并标记废弃。重新生成接口文档。
- 前端:轮询配置页去掉保护期间隔;资产详情(后台与 C 端)不再展示保护期状态。

View File

@@ -0,0 +1,21 @@
## ADDED Requirements
### Requirement: 设备停复机不设保护期
系统 SHALL 在后台对设备停机或复机后不设置保护期,MUST NOT 因此前的设备停机或复机拒绝相反的人工操作;单卡手动停复机 MUST NOT 检查保护期。系统 MUST NOT 调度保护期一致性检查,也 MUST NOT 产生停机原因 `protect_period` 的新记录;历史记录中的 `protect_period` 保留并照常展示,对外开放接口的停机原因映射保持不变。
#### Scenario: 设备停机后立即复机
- **WHEN** 运营对设备停机后 10 分钟内点击复机
- **THEN** 系统按复机规则执行,不因保护期拒绝
#### Scenario: 停机后自动规则复机
- **WHEN** 设备被人工停机后满足自动复机条件
- **THEN** 系统按规则自动复机,不存在保护期内的强制停机或强制复机
### Requirement: 保护期状态字段兼容返回
系统 SHALL 在后台资产详情与 C 端资产详情中继续返回 `device_protect_status` 字段,其值 MUST 固定为无保护期(`none`),接口文档 MUST 标记该字段已废弃。字段删除另行变更,前提是后台前端与 C 端(含老版本小程序)均不再读取。
#### Scenario: 老版本客户端读取
- **WHEN** 老版本小程序读取设备资产详情
- **THEN** 响应中仍有 `device_protect_status`,值为 `none`

View File

@@ -0,0 +1,25 @@
## MODIFIED Requirements
### Requirement: 轮询并发配置覆盖实际任务
系统 SHALL 为 `realname`、`carddata`、`package` 与 `card_status` 四类实际轮询任务各维护一项可查询、可更新的并发配置;`stop_start` 与已下线的 `protect` 不得作为轮询并发配置返回或接受维护。`card_status` 初始最大并发数 MUST 为 300。
#### Scenario: 查询完整配置集合
- **WHEN** 授权操作者查询轮询并发配置列表
- **THEN** 返回上述四类任务且不含 `stop_start` 与 `protect`
#### Scenario: 维护高于一千的既有并发配置
- **WHEN** 授权操作者为已配置轮询任务提交大于 1000 的正整数最大并发数
- **THEN** 系统保存该值并使后续轮询限流读取该值
#### Scenario: 提交保护期并发配置
- **WHEN** 授权操作者提交 `protect` 的并发配置
- **THEN** 系统拒绝该请求
### Requirement: 轮询任务类型名称可读
系统 SHALL 在轮询并发状态中返回与任务类型一致的中文名称:实名检查、流量检查、套餐检查或卡状态检查。
#### Scenario: 查询卡状态并发配置
- **WHEN** 授权操作者查询 `card_status` 的并发状态
- **THEN** 返回的 `task_type_name` 为“卡状态检查”

View File

@@ -0,0 +1,32 @@
## 1. 迁移
- [ ] 1.1 新增成对迁移:更新 `tb_polling_config.protect_check_interval`、`tb_iot_card.last_protect_check_at` 列注释为"已废弃";down 恢复原注释。
## 2. 设备与单卡停复机
- [ ] 2.1 `internal/service/device/service.go`:设备停机、复机不再设置保护期,不再因保护期拒绝相反操作。
- [ ] 2.2 `internal/service/iot_card/stop_resume_service.go`:手动停复机单卡(第 969、1036 行附近)去掉保护期检查。
- [ ] 2.3 删除 `RedisDeviceProtectKey`、`DeviceProtectPeriodDuration`;保留 `StopReasonProtectPeriod` 并在注释说明不再产生新值。
## 3. 下线保护期轮询
- [ ] 3.1 删除 `internal/task/polling_protect_handler.go`;`pkg/queue/handler.go` 对 `polling:protect` 改为空处理函数直接成功(下一次发布再移除)。
- [ ] 3.2 调度器、初始化器、生命周期、监控与统计去掉 `protect` 类型;删除 `ProtectCheckSkipsForRealname`。
- [ ] 3.3 轮询并发配置与任务类型名称去掉 `protect`,提交 `protect` 时拒绝。
- [ ] 3.4 `PollingConfig` 模型与 DTO 去掉 `ProtectCheckInterval`;`config_manager.go` 匹配去掉保护期;`IotCard` 模型去掉 `LastProtectCheckAt` 的读写。
## 4. 资产接口兼容
- [ ] 4.1 后台与 C 端资产详情的 `device_protect_status` 固定返回 `none`,DTO 说明标记已废弃;`internal/service/asset/service.go` 不再读取保护期 key。
- [ ] 4.2 重新生成接口文档。
## 5. 编译与规范校验
- [ ] 5.1 `gofmt -w`;`go build ./cmd/api ./cmd/worker` 通过;全仓检索无残留的保护期 key 读写。
- [ ] 5.2 `openspec validate remove-device-protect-period` 与 `openspec doctor --json` 通过。
## 6. 测试环境验证(自动化测试为 N/A,按 ENG-TEST-001)
- [ ] 6.1 设备停机后立即复机成功,不被保护期拒绝;单卡手动停复机同样。
- [ ] 6.2 不再产生 `polling:protect` 任务与 `protect_period` 停机原因;历史 `protect_period` 记录正常展示。
- [ ] 6.3 资产详情 `device_protect_status` 恒为 `none`;轮询配置接口不含保护期间隔;并发配置不含 `protect`。