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

57 lines
5.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.
## 0. 前置确认
- [x] 0.1 前置以测试环境为准,不以生产状态为前置(用户 2026-10-24 决定):`rebuild-card-traffic-metering-and-stop-resume` 代码已在 `Iteration/8-11`,测试库已执行 000241/000242;第 1 个 Change 已部署测试环境。
## 1. 迁移与模型
- [x] 1.1 新增成对迁移:`tb_polling_config` 增加 `package_state`、`asset_status`、`pre_reset_window`、`pre_reset_carddata_interval`(均可空);down 删列。
- [x] 1.2 `model.PollingConfig` 增加字段;修正间隔字段注释为"正数按间隔、0 不检查、空继承"。
## 2. 配置合并与分层匹配
- [x] 2.1 `config_manager.go`:配置加载按 `priority, id` 排序;`MergedTaskIntervals` 采用第一个非空取值,`0` 表示不检查。
- [x] 2.2 新增套餐状态与资产状态匹配;`package_usage_store` 增加按资产查询套餐状态(单个与批量),设备卡按设备计算。
- [x] 2.3 `initializer.go`(批量)、`lifecycle_service.go`、执行收尾重入队处传入套餐状态与资产状态。
- [x] 2.4 已销售无套餐、在库卡未匹配任何配置时告警且不入队。
## 3. 重置日前加密
- [x] 3.1 统一"计算下次到期"函数:窗口内间隔、越过重置时刻改为"重置时刻 − 收尾提前量"、窗口前截断到窗口起点、越过后恢复正常;初始化、收尾、生命周期共用。
- [x] 3.2 收尾提前量:暂用常量 `PollingPreResetTailMinutes`(5 分钟),未做成系统参数。
## 4. 配置接口
- [x] 4.1 `/polling-configs` DTO 增加 4 个字段,间隔校验改为"0 或不小于最小间隔",说明文字按三态;保存校验无套餐已销售与在库层卡状态必须为正数;优先级重复且条件可能重叠时返回提示。
- [x] 4.2 `PUT /polling-configs/priorities`:事务内整体重排,写统一审计,发配置变更通知。
- [x] 4.3 `GET /polling-configs/match-preview?iccid=`;`POST /polling-configs/match-preview` 请求体带 `overrides`(未保存修改):返回维度取值、命中配置、每类最终间隔与来源;只读。
- [x] 4.4 `POST /polling-configs/recalculate-due`(可选运营商账户)与 `GET /polling-configs/recalculate-due/:task_id`:异步分批,只提前不推后,不调网关。
- [x] 4.5 `GET /polling-stats/tiers`、`GET /polling-stats/pre-reset`。
- [x] 4.6 同步路由、`cmd/api/docs.go`、`cmd/gendocs/main.go` 并重新生成接口文档。
## 5. 流量按观测时间归属
- [x] 5.1 观测携带 `observed_at`;`traffic_flow.go` 判断可扣套餐时只认 `activated_at ≤ observed_at` 的生效主套餐,否则只记已结算。(只对已切换日快照计量的卡生效:老算法在观测时不判断套餐、由扣减消费者按当前生效套餐扣减,按 8-11 约定不改消费者)
## 6. 激活前结算与统一激活锁
- [x] 6.1 实名激活与订单购买即生效补上 `RedisPackageActivationLockKey`;各入口锁 TTL 调整为大于结算总超时 + 事务耗时;抢锁失败沿用现有冲突处理。(实名激活与订单入口最多等 5 秒,抢不到照常继续并告警,不丢激活;锁 TTL 统一 60 秒)
- [x] 6.2 锁内、激活事务前:判断资产当前无生效主套餐且卡已切换日快照计量时执行结算(独立卡一次、设备逐张),使用限流等待模式;单步超时与总超时为系统参数。(单步 4 秒、总 8 秒暂用常量,未做成系统参数;查询走现有限流守卫)
- [x] 6.3 结算观测带"激活前结算"标记,入账后不触发停复机评估。
- [x] 6.4 结算失败、超时或被跳过的卡写告警(卡、资产、错误);不阻塞激活。(告警写错误日志,metric=package.pre_activation_settlement.failed)
## 7. 编译与规范校验
- [x] 7.1 `gofmt -w`;`go build ./cmd/api ./cmd/worker` 通过。
- [x] 7.2 `openspec validate add-tiered-polling-and-pre-activation-settlement` 与 `openspec doctor --json` 通过。(validate 通过;当前 openspec 无 doctor 命令)
## 8. 测试环境验证(自动化测试为 N/A,按 ENG-TEST-001)
- [x] 8.1 现有配置在升级后各卡最终间隔不变(用匹配预览抽查)。(2026-10-24:唯一启用配置 29,28 张卡均命中,间隔与来源正确)
- [x] 8.2 间隔 `0` 停止继承、空值继承、相同优先级按 ID 稳定。(草稿预演通过)
- [x] 8.3 无套餐已销售、在库层卡状态为空或 0 时保存被拒;未匹配告警出现。(保存被拒已验证;未匹配告警按统计接口 unmatched_* 观察,当前为 0)
- [x] 8.4 整体排序后匹配结果按新顺序;重算到期时间只提前不推后。(重排与失败回滚通过;发现失败/限流延后的卡被重算拉到立即执行,已改为过期时候选取"现在 + 新间隔")
- [ ] 8.5 重置日前窗口:最后一次查询落在"重置时刻 − 收尾提前量",越过后恢复正常间隔。
- [ ] 8.6 二次销售卡购买即生效:先结算再激活,新套餐不承担上一用户本月用量;结算不产生停机。
- [ ] 8.7 构造结算慢返回且另一入口先激活:激活前用量只记已结算。
- [ ] 8.8 实名激活与订单购买并发:串行执行,无重复结算;结算超时照常激活并告警。