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

7.2 KiB
Raw Blame History

1. 迁移与模型

  • 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 删除两表。
  • 1.2 新增成对迁移 000242:tb_carrier 增加 realname_control_enabled smallint not null default 0;down 删除该列。
  • 1.3 新增 model.CardFlowDay、model.CardFlowSwitch;model.Carrier 增加 RealnameControlEnabled。

2. 计量领域规则

  • 2.1 新增 internal/domain/cardflow/:按重置日 R 把读数换算为自然月累计(R = 1、R > 1 且日号 ≥ R、R > 1 且日号 < R 三种,小于 0 按 0)。
  • 2.2 重置日防旧值:R = 1 比上月最大快照、R > 1 比本月 1~R−1 号最大快照(大于 0 才判断),超过 0.9 倍按 0;返回是否触发。
  • 2.3 按月对账增量 Δ = 本月最大 − 本月已结算合计,以及每天用量(当天最大 − 本月此前最大,小于 0 按 0)。
  • 2.4 重置日严格读取与兜底:按卡 carrier_id 查 data_reset_day,失败、为空或不在 1~28 时 CUCC 取 27、其余取 1 并记日志;不使用 TrafficObservation.ResetDay。

3. 快照与水位存储

  • 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 号最大值、本月已结算合计;累加当天已结算。
  • 3.2 新增 internal/store/postgres/card_flow_switch_store.go:按卡读取与写入切换水位。

4. 切换配置

  • 4.1 pkg/config 增加 TrafficCalc 配置段与 defaults/config.yaml 默认值(mode: off、名单为空、快照开关开),对应 JUNHONG_TRAFFIC_CALC_MODE、JUNHONG_TRAFFIC_CALC_CARDS、JUNHONG_TRAFFIC_FLOW_SNAPSHOT_ENABLED。
  • 4.2 启动时把名单展开为内存卡集合:device:<id> 展开为当前绑定全部卡;iot_card:<id> 实际使用设备套餐(与 resolveActivePackages 同口径)时启动日志报错并跳过;full 为全部卡。API 与全部 Worker 共用同一实现。

5. 观测事务的已切换分支

  • 5.1 internal/application/cardobservation/traffic.go:读数 > 0 时按第 2 节规则写当天快照;已切换卡在事务 1 内写,未切换卡在事务 1 提交后写(失败只告警,受快照开关控制);判定已切换出错一律走老分支,老分支逻辑不改。
  • 5.2 已切换且有水位的卡:按月对账计算 Δ;只读判断卡或当前绑定设备是否有 status=1 套餐(出错按有套餐);有套餐写 V1 事件并累加已结算,无套餐只累加已结算;不再写老增量的 V1 事件。
  • 5.3 已切换但无水位的卡(第一次切换观测):写快照,按老增量与套餐判断决定是否写 V1,把本月最大与已结算合计的差额计入已结算,同事务写切换水位。
  • 5.4 已切换卡的通道阈值判定:读数 > 0 且本次未被防旧值处理即调用 EvaluateInTx;第一次切换观测仍按老条件;未切换卡条件不变。
  • 5.5 已切换卡在同一条卡表 Updates 里用本月最大快照覆盖 current_month_usage_mb;last_gateway_reading_mb 只读不写。

6. 日流量读侧

  • 6.1 日流量查询对已切换卡改读快照(每天用量按 2.3),未切换卡仍读原来源;全量切换后的 Redis 日流量缓冲与 02:00 落盘下线不在本节,按上线步骤另行处理。

7. 停复机新规则

  • 7.1 pkg/config 增加 JUNHONG_STOP_RESUME_UNIFIED_RULE_ENABLED(默认关闭);关闭时 stop_resume_service.go 全部现有路径保持不变。
  • 7.2 新增目标状态判断:卡或绑定设备暂停轮询 → 不动作;开机时无套餐、流量用完、通道实名管控且未实名即停(停因与设备扩散规则不变);停机时有套餐、流量未用完、已实名或通道未管控即复,不看停因;持通道阈值锁拒绝复机。
  • 7.3 EvaluateAndAct 两个分支、resumeSingleCard、resumeDeviceCards、ResumeCardIfStopped 在总开关开启时改用 7.2 判断;设备复机在总开关开启时复用 iot_card_store.go 现有的 ListByDeviceIDAndNetworkStatus 取设备下全部停机卡。
  • 7.4 isRealnameOK 在总开关开启时改为按卡所属通道 realname_control_enabled 判断(0 满足、1 看 real_name_status),删除行业卡与卡/设备实名策略分支,通道查询失败返回错误;人工复机同步生效。
  • 7.5 internal/task/polling_protect_handler.go:总开关开启时只在通道开启实名管控且卡未实名时跳过保护期检查。
  • 7.6 internal/application/carrierthreshold/ 新周期恢复:总开关开启时复机条件改用 7.2(不再以其他停因或网关扩展状态阻止),条件不满足只解锁。

8. 通道实名管控配置

  • 8.1 service/carrier 与通道 DTO:创建、修改、详情支持 realname_control_enabled,仅超级管理员与平台用户可提交,非平台账号提交被拒;修改并入通道更新审计。
  • 8.2 通道修改从 0 改为 1 时返回或提供该通道未实名开机卡数,供管理端二次确认。
  • 8.3 同步路由文档说明,运行 go run cmd/gendocs/main.go 重新生成接口文档。

9. 构建与测试环境验证

  • 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 通道实名管控字段的权限与审计:非平台账号提交被拒,平台账号修改写入通道更新审计。