huang
cebcada950
核心改造： - 增量算法：流量计算从覆盖式改为增量累加（gateway - lastReading），支持上游运营商重置检测 - 日流量缓冲：insertDataUsageRecord 改为 Redis INCRBYFLOAT，每日凌晨落盘到 tb_card_daily_usage - 运营商：新增 data_reset_day 字段（联通=27，其余=1） - IoT卡：新增 last_gateway_reading_mb 字段存储上次网关读数 - 查询层：新建 TrafficQueryService 合并 Redis（今日）+ DB（历史）数据源 - 清理：删除 DataUsageRecord model/store，移除 polling_handler 旧引用 迁移：000094-000097（carrier字段、iot_card字段、数据初始化、日流量表）
8.5 KiB
Context
轮询系统每 5-15 分钟调用网关获取所有卡的流量数据，写入 DB。当前问题：
- 每次轮询无条件写详单记录，增量=0 也写，DB 膨胀严重（P2-26）
current_month_usage_mb直接用网关值覆盖，上游自然月重置时我们的值也归零（P2-27）
核心改造对象：internal/task/polling_handler.go 中的 calculateFlowUpdates()、calculateFlowIncrement() 和 insertDataUsageRecord()。
Goals / Non-Goals
Goals:
- 月流量改为增量累加，不受上游自然月重置影响（E-2）
- 流量详单减少 90%+ 的无效写入（E-1）
- 查询层无缝兼容新数据源（E-3）
- 清理旧流量详单代码路径（
tb_data_usage_record相关代码） - 提供数据初始化脚本保证上线安全
Non-Goals:
- 不修改轮询调度逻辑（频率、并发控制不变）
- 不新增自动化测试
- 不修改套餐级重置逻辑（
ResetService不受影响，套餐的data_reset_cycle机制独立运行）
Decisions
1. E-2 先于 E-1 的原因
决策：先改增量算法（E-2），再改存储介质（E-1）。
原因：E-2 修的是"数据正确性"（覆盖 vs 累加），E-1 修的是"写入效率"（DB vs Redis）。正确性比效率更紧迫。且 E-2 的 increment 变量是 E-1 Redis 写入的前提。
2. 合并 calculateFlowUpdates() 和 calculateFlowIncrement()
决策：合并为一个函数，返回 (updates map[string]any, increment float64)。
原因：当前两个函数各自独立计算增量，用途不同：
calculateFlowUpdates()→ 更新卡的current_month_usage_mb、data_usage_mb等字段calculateFlowIncrement()→ 算增量给DeductDataUsage()（将增量记录到套餐已用量）
改造后两者使用同一个增量公式（gatewayFlowMB - card.LastGatewayReadingMB），维护两份重复逻辑有不一致风险。合并后调用方式：
updates, increment := h.calculateFlowUpdates(card, gatewayFlowMB, now)
// updates 用于更新卡字段
// increment 用于套餐已用量记录
3. 运营商重置日检测算法（上游重置）
data_reset_day 是运营商级别字段（tb_carrier.data_reset_day），标识上游运营商每月清零网关计数器的日期。这跟我们系统套餐的 data_reset_cycle（daily/monthly/yearly）是两个完全独立的维度。
// 增量 = 当前读数 - 上次读数
increment := gatewayFlowMB - card.LastGatewayReadingMB
if increment < 0 {
// 当前值比上次小 → 可能是上游运营商重置了
resetDay := getCarrierResetDay(card.CarrierID)
if isResetWindow(time.Now().Day(), resetDay) {
// 在重置日窗口内，视为正常上游重置
increment = gatewayFlowMB // 重置后原始值就是增量
} else {
// 非重置日出现值下降，异常，不计入
logger.Warn("流量异常：非重置日出现值下降")
increment = 0
}
}
isResetWindow 精确定义：
// isResetWindow 判断今天是否在运营商重置日窗口内
// 窗口 = 重置日当天 + 前一天（容错网关数据延迟）
// 例：resetDay=27 → 窗口包含 26、27
// 例：resetDay=1 → 窗口包含上月最后一天、1号
func isResetWindow(now time.Time, resetDay int) bool {
today := now.Day()
if today == resetDay {
return true
}
// 前一天容错：计算 resetDay 的前一天
resetDate := time.Date(now.Year(), now.Month(), resetDay, 0, 0, 0, 0, now.Location())
prevDay := resetDate.AddDate(0, 0, -1).Day()
return today == prevDay
}
4. 跨自然月重置逻辑
current_month_usage_mb 是卡级字段，记录这张卡本自然月的系统累计用量。跨自然月时需要重置。
改造后的跨月处理：
if isCrossMonth {
updates["last_month_total_mb"] = card.CurrentMonthUsageMB
updates["current_month_start_date"] = currentMonthStart
updates["current_month_usage_mb"] = 0 // 新月从 0 开始累计（不再 = gatewayFlowMB）
// increment 仍然正常计算（由 LastGatewayReadingMB 决定）
}
注意：这里的"自然月重置"是我们系统级别对 current_month_usage_mb 的重置。跟套餐级别的 data_reset_cycle 完全独立——套餐的已用量重置由 ResetService（reset_service.go）负责，重置的是 PackageUsage.DataUsageMB，不涉及卡级字段。
5. Redis 缓冲策略
- Key 格式：
traffic:daily:{card_id}:{YYYY-MM-DD} - 操作：
INCRBYFLOAT（原子增量） - TTL：48 小时（给落盘任务足够消费时间）
- 落盘频率：每天凌晨 2 点（Asynq Scheduler），SCAN 昨日 key → UPSERT → DELETE
为什么不用 Sorted Set？ 每张卡每天只有一个值，简单 KV + INCRBYFLOAT 最高效。
6. 落盘 UPSERT 语义：覆盖（幂等安全）
INSERT INTO tb_card_daily_usage (iot_card_id, date, usage_mb)
VALUES ($1, $2, $3)
ON CONFLICT (iot_card_id, date)
DO UPDATE SET usage_mb = EXCLUDED.usage_mb, updated_at = NOW();
选择覆盖而非累加：Redis INCRBYFLOAT 保证值是正确的累积值，落盘只是"从 Redis 搬到 DB"。重试时覆盖写结果不变，天然幂等。如果用累加，任务重试会导致数据翻倍。
7. 落盘分批策略
10 万张活跃卡 ≈ 10 万个 Redis key。分批处理避免单次操作过大：
- SCAN 阶段：
SCAN cursor pattern COUNT 500，分批收集所有昨日 key - UPSERT 阶段：每批 200 条，批量 UPSERT 到 DB
- DELETE 阶段：每批 200 条，Pipeline 批量删除已落盘 key
预估耗时：10 万 key ≈ 30-60 秒。Asynq 任务超时设为 5 分钟。
8. 数据初始化脚本
上线前必须运行：
-- 将所有卡的 last_gateway_reading_mb 初始化为当前月用量
-- 避免上线后第一次轮询把整个已用量当作增量
UPDATE tb_iot_card
SET last_gateway_reading_mb = current_month_usage_mb
WHERE last_gateway_reading_mb = 0 AND current_month_usage_mb > 0;
此脚本放在迁移文件中但标注为"上线前人工确认执行"。
新卡首次轮询：last_gateway_reading_mb 默认 0，首次轮询增量 = 全量（网关返回值）。对于新入库的卡（从没用过）这是正确的。批量导入已有使用量的卡时，导入脚本应同步设置 last_gateway_reading_mb = current_month_usage_mb。
9. 查询层兼容策略
TrafficQueryService.GetDailyUsage() 合并两段数据：
- 今天 → 从 Redis 读（可能还没落盘）
- 历史 → 从
tb_card_daily_usage读 - 排序合并后返回
10. 旧流量详单代码清理
tb_data_usage_record 不再写入后，相关代码路径全部删除：
internal/model/data_usage.go（DataUsageRecord model）internal/store/postgres/data_usage_record_store.go（Store）internal/bootstrap/中的引用scripts/cleanup/main.go中的引用
旧表数据暂保留在 DB（后续可通过数据清理功能清除），但代码层完全去除依赖。
11. 运营商管理接口变更
tb_carrier 新增 data_reset_day INT NOT NULL DEFAULT 1。创建/编辑运营商时新增此字段（1-28），前端显示为"每月 N 日重置流量"。
建议初始值：联通=27，移动/电信/广电=1。可通过迁移 SQL 直接 UPDATE 已有运营商记录。
Risks / Trade-offs
- [Redis 丢数据] Redis 重启导致今日缓冲丢失 → TTL 48h + 落盘任务可补偿；极端情况丢一天数据，业务可接受
- [首次轮询增量暴增]
last_gateway_reading_mb未初始化时第一次轮询增量=全量 → 通过初始化脚本消除 - [重置日误判] 运营商非预期时间重置 → 前一天容错 + Warn 日志，人工可介入
- [落盘任务失败] Redis key 在 48h TTL 内未消费 → 数据丢失。Asynq 有重试机制（MaxRetry=3），且可手动触发
- [跨自然月边界] 轮询恰好在 0 点附近：先检测跨月 → 重置
current_month_usage_mb = 0→ 再计算增量。两步原子完成
Migration Plan
- 迁移 1：
ALTER TABLE tb_carrier ADD COLUMN data_reset_day，UPDATE 已有运营商初始值 - 迁移 2：
ALTER TABLE tb_iot_card ADD COLUMN last_gateway_reading_mb - 迁移 3：
CREATE TABLE tb_card_daily_usage（usage_mb使用NUMERIC(12,2)类型） - 数据初始化：执行
UPDATE tb_iot_card SET last_gateway_reading_mb = current_month_usage_mb - 部署代码：低峰期发布
- 回滚策略：如果增量算法异常，可临时切回覆盖写（保留旧代码为注释或 feature flag）