Files
junhong_cmp_fiber/openspec/changes/rebuild-card-traffic-metering-and-stop-resume/tasks.md
邹进 96771a204f
Some checks failed
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Has been cancelled
feat: 卡流量改为日快照计量并统一停复机规则
卡流量计量(按名单灰度,默认 off):
- 新增卡日快照与切换水位表(000241),按通道上游流量重置日换算自然月、重置日防旧值
- 已切换的卡按月对账产生增量,无生效中套餐只结算不发事件;第一次切换写水位
- 已切换卡读数有效即判定通道阈值,卡表本月用量用快照覆盖,日流量读快照
- 配置 JUNHONG_TRAFFIC_CALC_MODE/CARDS、JUNHONG_TRAFFIC_FLOW_SNAPSHOT_ENABLED

停复机规则(总开关 JUNHONG_STOP_RESUME_UNIFIED_RULE_ENABLED,默认关闭):
- 复机不看停机原因,持通道阈值锁仍拒绝;暂停轮询的卡不自动停复机
- 通道新增实名管控 realname_control_enabled(000242,默认 0),开启后不区分行业卡与实名策略
- 实名管控从 0 改 1 需确认,修改并入通道更新审计

OpenSpec Change: rebuild-card-traffic-metering-and-stop-resume
2026-10-20 17:49:26 +09:00

60 lines
7.2 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.
## 1. 迁移与模型
- [x] 1.1 新增成对迁移 `000241`:建 `tb_card_flow_day`(`iot_card_id`、`flow_date`、`month_used_mb`、`vendor_used_mb`、`settled_mb`、`stale_guarded`、`obs_count`、时间戳,唯一键 `(iot_card_id, flow_date)`)与 `tb_card_flow_switch`(`iot_card_id` 唯一、`switched_at`、`month_used_mb`、`vendor_used_mb`、`old_baseline_mb`、`old_month_usage_mb`、`old_reading_accepted`、`old_increment_mb`、`created_at`);down 删除两表。
- [x] 1.2 新增成对迁移 `000242`:`tb_carrier` 增加 `realname_control_enabled smallint not null default 0`;down 删除该列。
- [x] 1.3 新增 `model.CardFlowDay`、`model.CardFlowSwitch`;`model.Carrier` 增加 `RealnameControlEnabled`。
## 2. 计量领域规则
- [x] 2.1 新增 `internal/domain/cardflow/`:按重置日 `R` 把读数换算为自然月累计(`R = 1`、`R > 1` 且日号 ≥ `R`、`R > 1` 且日号 < `R` 三种,小于 0 按 0)。
- [x] 2.2 重置日防旧值:`R = 1` 比上月最大快照、`R > 1` 比本月 1~R−1 号最大快照(大于 0 才判断),超过 0.9 倍按 0;返回是否触发。
- [x] 2.3 按月对账增量 `Δ = 本月最大 − 本月已结算合计`,以及每天用量(当天最大 − 本月此前最大,小于 0 按 0)。
- [x] 2.4 重置日严格读取与兜底:按卡 `carrier_id` 查 `data_reset_day`,失败、为空或不在 1~28 时 `CUCC` 取 27、其余取 1 并记日志;不使用 `TrafficObservation.ResetDay`。
## 3. 快照与水位存储
- [x] 3.1 新增 `internal/store/postgres/card_flow_day_store.go`:`INSERT ... ON CONFLICT (iot_card_id, flow_date) DO UPDATE` 原子写入(本月累计取较大值);查询本月最大值、本月 1~R−1 号最大值、上月最大值与上月 1~R−1 号最大值、本月已结算合计;累加当天已结算。
- [x] 3.2 新增 `internal/store/postgres/card_flow_switch_store.go`:按卡读取与写入切换水位。
## 4. 切换配置
- [x] 4.1 `pkg/config` 增加 `TrafficCalc` 配置段与 `defaults/config.yaml` 默认值(`mode: off`、名单为空、快照开关开),对应 `JUNHONG_TRAFFIC_CALC_MODE`、`JUNHONG_TRAFFIC_CALC_CARDS`、`JUNHONG_TRAFFIC_FLOW_SNAPSHOT_ENABLED`。
- [x] 4.2 启动时把名单展开为内存卡集合:`device:<id>` 展开为当前绑定全部卡;`iot_card:<id>` 实际使用设备套餐(与 `resolveActivePackages` 同口径)时启动日志报错并跳过;`full` 为全部卡。API 与全部 Worker 共用同一实现。
## 5. 观测事务的已切换分支
- [x] 5.1 `internal/application/cardobservation/traffic.go`:读数 `> 0` 时按第 2 节规则写当天快照;已切换卡在事务 1 内写,未切换卡在事务 1 提交后写(失败只告警,受快照开关控制);判定已切换出错一律走老分支,老分支逻辑不改。
- [x] 5.2 已切换且有水位的卡:按月对账计算 `Δ`;只读判断卡或当前绑定设备是否有 status=1 套餐(出错按有套餐);有套餐写 V1 事件并累加已结算,无套餐只累加已结算;不再写老增量的 V1 事件。
- [x] 5.3 已切换但无水位的卡(第一次切换观测):写快照,按老增量与套餐判断决定是否写 V1,把本月最大与已结算合计的差额计入已结算,同事务写切换水位。
- [x] 5.4 已切换卡的通道阈值判定:读数 `> 0` 且本次未被防旧值处理即调用 `EvaluateInTx`;第一次切换观测仍按老条件;未切换卡条件不变。
- [x] 5.5 已切换卡在同一条卡表 `Updates` 里用本月最大快照覆盖 `current_month_usage_mb`;`last_gateway_reading_mb` 只读不写。
## 6. 日流量读侧
- [x] 6.1 日流量查询对已切换卡改读快照(每天用量按 2.3),未切换卡仍读原来源;全量切换后的 Redis 日流量缓冲与 02:00 落盘下线不在本节,按上线步骤另行处理。
## 7. 停复机新规则
- [x] 7.1 `pkg/config` 增加 `JUNHONG_STOP_RESUME_UNIFIED_RULE_ENABLED`(默认关闭);关闭时 `stop_resume_service.go` 全部现有路径保持不变。
- [x] 7.2 新增目标状态判断:卡或绑定设备暂停轮询 → 不动作;开机时无套餐、流量用完、通道实名管控且未实名即停(停因与设备扩散规则不变);停机时有套餐、流量未用完、已实名或通道未管控即复,不看停因;持通道阈值锁拒绝复机。
- [x] 7.3 `EvaluateAndAct` 两个分支、`resumeSingleCard`、`resumeDeviceCards`、`ResumeCardIfStopped` 在总开关开启时改用 7.2 判断;设备复机在总开关开启时复用 `iot_card_store.go` 现有的 `ListByDeviceIDAndNetworkStatus` 取设备下全部停机卡。
- [x] 7.4 `isRealnameOK` 在总开关开启时改为按卡所属通道 `realname_control_enabled` 判断(0 满足、1 看 `real_name_status`),删除行业卡与卡/设备实名策略分支,通道查询失败返回错误;人工复机同步生效。
- [x] 7.5 `internal/task/polling_protect_handler.go`:总开关开启时只在通道开启实名管控且卡未实名时跳过保护期检查。
- [x] 7.6 `internal/application/carrierthreshold/` 新周期恢复:总开关开启时复机条件改用 7.2(不再以其他停因或网关扩展状态阻止),条件不满足只解锁。
## 8. 通道实名管控配置
- [x] 8.1 `service/carrier` 与通道 DTO:创建、修改、详情支持 `realname_control_enabled`,仅超级管理员与平台用户可提交,非平台账号提交被拒;修改并入通道更新审计。
- [x] 8.2 通道修改从 0 改为 1 时返回或提供该通道未实名开机卡数,供管理端二次确认。
- [x] 8.3 同步路由文档说明,运行 `go run cmd/gendocs/main.go` 重新生成接口文档。
## 9. 构建与测试环境验证
- [x] 9.1 对变更 Go 文件执行 `gofmt -w`,运行 `go build ./cmd/api ./cmd/worker`、`openspec validate rebuild-card-traffic-metering-and-stop-resume --strict`。
- [ ] 9.2 按 ENG-TEST-001 在维护者指定的测试环境执行迁移 up/down/up,核对两张新表与 `tb_carrier` 新列默认值。
- [ ] 9.3 计量模式 `off`:非灰度卡观测一次,卡表、V1 事件、扣减、停复机结果与改动前一致,且写入了快照;关闭快照开关后停写。
- [ ] 9.4 灰度 `device:<测试设备>`:构造冻结卡(基线高于读数)、二次销售卡、本月无快照的正常卡、联通 27 号与 1 号重置的卡,逐次核对快照、已结算、水位、V1 事件与套餐已用量;退回删水位后同日再切回不重复扣。
- [ ] 9.5 已切换冻结卡读数达阈值写通道停机锁;重置日防旧值触发时不判定;资产详情、卡列表、设备导出的本月用量等于本月最大快照;日流量读快照。
- [ ] 9.6 停复机总开关关闭时行为与改动前一致;开启后核对:外部停机、人工停机、设备保护期停机的卡满足条件复机;暂停轮询的卡充值后不复机;通道开启实名管控时未实名卡(含行业卡)停机且不复机、实名后复机;通道未管控时未实名卡不停机、人工复机不被拒;持阈值锁拒绝复机;新周期解锁按新条件复机。
- [ ] 9.7 通道实名管控字段的权限与审计:非平台账号提交被拒,平台账号修改写入通道更新审计。