chore: 归档轮询系统实现变更 (polling-system-implementation)

已完成千万级卡规模轮询系统的完整实现和集成测试验证，将变更归档到 openspec/changes/archive/2026-02-10-polling-system-implementation/

主要成果：
- 三大轮询任务：实名检查、卡流量检查、套餐流量检查
- 快速启动（<10秒）和渐进式初始化
- 完整运营工具：配置管理、并发控制、监控面板、告警系统、数据清理、手动触发
- 任务完成度：215/216（99.5%）
- 所有 24 个新增接口已生成 OpenAPI 文档

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

openspec/changes/archive/2026-02-10-polling-system-implementation/specs/iot-card/spec.md

@@ -0,0 +1,199 @@
+## MODIFIED Requirements
+
+### Requirement: 月流量追踪字段
+
+系统 SHALL 在 IoT 卡模型中增加月流量追踪字段，用于处理跨月流量计算。
+
+#### Scenario: 新增字段定义
+
+- **WHEN** 系统需要追踪卡的月度流量使用情况
+- **THEN** 系统在 tb_iot_card 表增加以下字段：
+  - `current_month_usage_mb` (DECIMAL): 本月已用流量（MB），默认值 0
+  - `current_month_start_date` (DATE): 本月开始日期（自然月1日），默认值 NULL
+  - `last_month_total_mb` (DECIMAL): 上月结束时的总流量（MB），默认值 0
+
+#### Scenario: 字段用于跨月计算
+
+- **WHEN** Gateway 返回月总流量（自然月累计）
+- **THEN** 系统使用这 3 个字段计算本月增量流量，处理跨月重置逻辑
+
+#### Scenario: 兼容已有数据
+
+- **WHEN** 数据库迁移执行，已有卡记录
+- **THEN** 系统为已有卡初始化 current_month_usage_mb=0、current_month_start_date=NULL、last_month_total_mb=0
+
+### Requirement: 首次流量查询初始化
+
+系统 SHALL 在卡首次查询流量时初始化月流量追踪字段。
+
+#### Scenario: 首次查询初始化
+
+- **WHEN** 卡A首次查询流量，current_month_start_date 为 NULL，Gateway 返回 total_usage_mb=500
+- **THEN** 系统初始化 current_month_start_date=当前月1日（如 2024-01-01），current_month_usage_mb=500，last_month_total_mb=0
+
+#### Scenario: 非首次查询不重新初始化
+
+- **WHEN** 卡A再次查询流量，current_month_start_date 不为 NULL
+- **THEN** 系统使用已有的 current_month_start_date，不重新初始化
+
+### Requirement: 同月内流量增长
+
+系统 SHALL 在同月内正确计算流量增量。
+
+#### Scenario: 同月内流量增长
+
+- **WHEN** 卡A上次查询在本月（current_month_start_date=2024-01-01），Gateway 返回 total_usage_mb=500，数据库当前 current_month_usage_mb=400
+- **THEN** 系统计算增量 100 MB，更新 current_month_usage_mb=500
+
+#### Scenario: Gateway 返回值未变化
+
+- **WHEN** Gateway 返回 total_usage_mb=400，等于数据库当前值 current_month_usage_mb=400
+- **THEN** 系统判断无增量，不触发套餐检查
+
+#### Scenario: Gateway 返回值回退（异常）
+
+- **WHEN** Gateway 返回 total_usage_mb=300，小于数据库当前值 current_month_usage_mb=400
+- **THEN** 系统记录警告日志，但仍更新为 Gateway 值（信任 Gateway 数据源）
+
+### Requirement: 跨月流量重置
+
+系统 SHALL 在检测到跨月时正确重置月流量统计。
+
+#### Scenario: 跨月检测
+
+- **WHEN** 卡A上次查询在上月（current_month_start_date=2024-01-01），当前时间为 2024-02-05
+- **THEN** 系统检测到跨月（当前月1日 > current_month_start_date）
+
+#### Scenario: 跨月重置流程
+
+- **WHEN** 检测到跨月，当前 current_month_usage_mb=400，Gateway 返回 total_usage_mb=50
+- **THEN** 系统执行：
+  1. 保存 last_month_total_mb=400（上月结束值）
+  2. 更新 current_month_start_date=2024-02-01（新月1日）
+  3. 更新 current_month_usage_mb=50（新月流量）
+
+#### Scenario: 跨多月（异常长时间未检查）
+
+- **WHEN** 卡A上次查询在 2024-01-01，当前时间为 2024-04-05，跨越 3 个月
+- **THEN** 系统检测到跨月，重置到当前月（2024-04-01），记录警告日志（长时间未检查）
+
+### Requirement: 月流量历史记录
+
+系统 SHALL 在跨月时记录上月流量汇总到历史表。
+
+#### Scenario: 记录上月汇总
+
+- **WHEN** 检测到跨月，上月总流量为 400 MB
+- **THEN** 系统插入一条月度汇总记录到 data_usage_records 表（card_id、usage_mb=400、usage_type='monthly_summary'、recorded_at=上月最后一天）
+
+#### Scenario: 历史记录供报表使用
+
+- **WHEN** 管理员查询卡的月度流量报表
+- **THEN** 系统从 data_usage_records 表读取 usage_type='monthly_summary' 的记录
+
+### Requirement: API 响应包含月流量字段
+
+系统 SHALL 在卡详情和列表接口中返回月流量追踪字段。
+
+#### Scenario: 卡详情接口返回
+
+- **WHEN** 管理员请求查询卡详情
+- **THEN** 系统返回卡信息，包含 current_month_usage_mb、current_month_start_date、last_month_total_mb 字段
+
+#### Scenario: 卡列表接口返回
+
+- **WHEN** 管理员请求查询卡列表
+- **THEN** 系统返回卡列表，每张卡包含月流量追踪字段
+
+#### Scenario: 历史兼容
+
+- **WHEN** 客户端请求卡信息，旧版客户端不识别新字段
+- **THEN** 旧版客户端忽略新字段，不影响正常使用（向后兼容）
+
+### Requirement: 数据库迁移
+
+系统 SHALL 提供数据库迁移脚本增加月流量追踪字段。
+
+#### Scenario: 迁移脚本添加字段
+
+- **WHEN** 执行数据库迁移
+- **THEN** 系统执行 DDL：
+  ```sql
+  ALTER TABLE tb_iot_card
+  ADD COLUMN current_month_usage_mb DECIMAL(10,2) DEFAULT 0 COMMENT '本月已用流量(MB)',
+  ADD COLUMN current_month_start_date DATE DEFAULT NULL COMMENT '本月开始日期',
+  ADD COLUMN last_month_total_mb DECIMAL(10,2) DEFAULT 0 COMMENT '上月结束时总流量(MB)';
+  ```
+
+#### Scenario: 迁移回滚
+
+- **WHEN** 迁移失败需要回滚
+- **THEN** 系统执行回滚 DDL：
+  ```sql
+  ALTER TABLE tb_iot_card
+  DROP COLUMN current_month_usage_mb,
+  DROP COLUMN current_month_start_date,
+  DROP COLUMN last_month_total_mb;
+  ```
+
+#### Scenario: 迁移不影响已有数据
+
+- **WHEN** 迁移执行，表中有 1000 万条记录
+- **THEN** 系统添加字段使用默认值，不需要全表更新，迁移时间短（<5分钟）
+
+### Requirement: Redis 缓存同步
+
+系统 SHALL 在 Redis 缓存中同步月流量追踪字段。
+
+#### Scenario: 缓存包含月流量字段
+
+- **WHEN** 系统加载卡信息到 Redis 缓存（polling:card:{card_id}）
+- **THEN** 缓存包含 current_month_usage_mb、current_month_start_date、last_month_total_mb 字段
+
+#### Scenario: 更新缓存月流量字段
+
+- **WHEN** 流量检查任务更新数据库后
+- **THEN** 系统使用 HSET 同步更新 Redis 缓存的月流量字段
+
+#### Scenario: 缓存过期重新加载
+
+- **WHEN** Redis 缓存过期，重新从数据库加载
+- **THEN** 系统加载完整的卡信息，包含最新的月流量字段
+
+### Requirement: 数据一致性
+
+系统 SHALL 确保月流量追踪字段在数据库和缓存之间的一致性。
+
+#### Scenario: 更新事务保证一致性
+
+- **WHEN** 流量检查任务更新月流量字段
+- **THEN** 系统在数据库事务中更新，提交成功后再更新 Redis 缓存
+
+#### Scenario: 缓存更新失败不影响数据库
+
+- **WHEN** 数据库更新成功，但 Redis 更新失败
+- **THEN** 系统记录警告日志，数据库数据为准，下次缓存加载时恢复一致
+
+#### Scenario: 数据库更新失败回滚
+
+- **WHEN** 更新月流量字段时数据库失败
+- **THEN** 系统事务回滚，不更新 Redis 缓存，保持原有数据
+
+### Requirement: 监控和日志
+
+系统 SHALL 记录月流量追踪相关的关键操作日志。
+
+#### Scenario: 记录首次初始化日志
+
+- **WHEN** 卡首次查询流量，初始化月流量字段
+- **THEN** 系统记录 Info 日志，包含 card_id、initialized_month、initial_usage_mb
+
+#### Scenario: 记录跨月重置日志
+
+- **WHEN** 检测到跨月并重置月流量统计
+- **THEN** 系统记录 Info 日志，包含 card_id、old_month、new_month、last_month_total_mb
+
+#### Scenario: 记录异常日志
+
+- **WHEN** 检测到流量回退或跨多月未检查
+- **THEN** 系统记录 Warn 日志，包含详细上下文