Files
junhong_cmp_fiber/openspec/changes/add-tiered-polling-and-pre-activation-settlement/tasks.md
邹进 2ddaffe373
All checks were successful
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Successful in 9m57s
docs: 轮询配置接口文档与实际行为对齐
- 匹配预览 GET 只收 query iccid,POST 只收请求体,去掉 POST 文档中多余的 query 参数
- 预览草稿 overrides 改为独立结构,字段全部可选,最多 20 条
- clear_fields 用具名类型生成数组元素枚举;ordered_ids 说明须为正整数且不重复
2026-10-24 17:41:52 +09:00

5.2 KiB
Raw Blame History

0. 前置确认

  • 0.1 前置以测试环境为准,不以生产状态为前置(用户 2026-10-24 决定):rebuild-card-traffic-metering-and-stop-resume 代码已在 Iteration/8-11,测试库已执行 000241/000242;第 1 个 Change 已部署测试环境。

1. 迁移与模型

  • 1.1 新增成对迁移:tb_polling_config 增加 package_state、asset_status、pre_reset_window、pre_reset_carddata_interval(均可空);down 删列。
  • 1.2 model.PollingConfig 增加字段;修正间隔字段注释为"正数按间隔、0 不检查、空继承"。

2. 配置合并与分层匹配

  • 2.1 config_manager.go:配置加载按 priority, id 排序;MergedTaskIntervals 采用第一个非空取值,0 表示不检查。
  • 2.2 新增套餐状态与资产状态匹配;package_usage_store 增加按资产查询套餐状态(单个与批量),设备卡按设备计算。
  • 2.3 initializer.go(批量)、lifecycle_service.go、执行收尾重入队处传入套餐状态与资产状态。
  • 2.4 已销售无套餐、在库卡未匹配任何配置时告警且不入队。

3. 重置日前加密

  • 3.1 统一"计算下次到期"函数:窗口内间隔、越过重置时刻改为"重置时刻 − 收尾提前量"、窗口前截断到窗口起点、越过后恢复正常;初始化、收尾、生命周期共用。
  • 3.2 收尾提前量:暂用常量 PollingPreResetTailMinutes(5 分钟),未做成系统参数。

4. 配置接口

  • 4.1 /polling-configs DTO 增加 4 个字段,间隔校验改为"0 或不小于最小间隔",说明文字按三态;保存校验无套餐已销售与在库层卡状态必须为正数;优先级重复且条件可能重叠时返回提示。
  • 4.2 PUT /polling-configs/priorities:事务内整体重排,写统一审计,发配置变更通知。
  • 4.3 GET /polling-configs/match-preview?iccid=;POST /polling-configs/match-preview 请求体带 overrides(未保存修改):返回维度取值、命中配置、每类最终间隔与来源;只读。
  • 4.4 POST /polling-configs/recalculate-due(可选运营商账户)与 GET /polling-configs/recalculate-due/:task_id:异步分批,只提前不推后,不调网关。
  • 4.5 GET /polling-stats/tiers、GET /polling-stats/pre-reset。
  • 4.6 同步路由、cmd/api/docs.go、cmd/gendocs/main.go 并重新生成接口文档。

5. 流量按观测时间归属

  • 5.1 观测携带 observed_at;traffic_flow.go 判断可扣套餐时只认 activated_at ≤ observed_at 的生效主套餐,否则只记已结算。(只对已切换日快照计量的卡生效:老算法在观测时不判断套餐、由扣减消费者按当前生效套餐扣减,按 8-11 约定不改消费者)

6. 激活前结算与统一激活锁

  • 6.1 实名激活与订单购买即生效补上 RedisPackageActivationLockKey;各入口锁 TTL 调整为大于结算总超时 + 事务耗时;抢锁失败沿用现有冲突处理。(实名激活与订单入口最多等 5 秒,抢不到照常继续并告警,不丢激活;锁 TTL 统一 60 秒)
  • 6.2 锁内、激活事务前:判断资产当前无生效主套餐且卡已切换日快照计量时执行结算(独立卡一次、设备逐张),使用限流等待模式;单步超时与总超时为系统参数。(单步 4 秒、总 8 秒暂用常量,未做成系统参数;查询走现有限流守卫)
  • 6.3 结算观测带"激活前结算"标记,入账后不触发停复机评估。
  • 6.4 结算失败、超时或被跳过的卡写告警(卡、资产、错误);不阻塞激活。(告警写错误日志,metric=package.pre_activation_settlement.failed)

7. 编译与规范校验

  • 7.1 gofmt -w;go build ./cmd/api ./cmd/worker 通过。
  • 7.2 openspec validate add-tiered-polling-and-pre-activation-settlement 与 openspec doctor --json 通过。(validate 通过;当前 openspec 无 doctor 命令)

8. 测试环境验证(自动化测试为 N/A,按 ENG-TEST-001)

  • 8.1 现有配置在升级后各卡最终间隔不变(用匹配预览抽查)。(2026-10-24:唯一启用配置 29,28 张卡均命中,间隔与来源正确)
  • 8.2 间隔 0 停止继承、空值继承、相同优先级按 ID 稳定。(草稿预演通过)
  • 8.3 无套餐已销售、在库层卡状态为空或 0 时保存被拒;未匹配告警出现。(保存被拒已验证;未匹配告警按统计接口 unmatched_* 观察,当前为 0)
  • 8.4 整体排序后匹配结果按新顺序;重算到期时间只提前不推后。(重排与失败回滚通过;发现失败/限流延后的卡被重算拉到立即执行,已改为过期时候选取"现在 + 新间隔")
  • 8.5 重置日前窗口:最后一次查询落在"重置时刻 − 收尾提前量",越过后恢复正常间隔。
  • 8.6 二次销售卡购买即生效:先结算再激活,新套餐不承担上一用户本月用量;结算不产生停机。
  • 8.7 构造结算慢返回且另一入口先激活:激活前用量只记已结算。
  • 8.8 实名激活与订单购买并发:串行执行,无重复结算;结算超时照常激活并告警。