smart_grid_iot/.trae/specs/add-icc-analog-data/tasks.md

Tasks

• Task 1: 核对生产库 electricity_data 现状（表是否存在、旧表字段/分区/有无数据），确定迁移采用 CREATE IF NOT EXISTS 还是增量变更
  • SubTask 1.1: 查询生产库 information_schema 确认 electricity_data 是否存在及其字段/分区/数据量
• Task 2: 新建迁移 database/migrations/20261024_icc_analog_data.sql（无 equip_id）：
  • 无旧表 → CREATE TABLE IF NOT EXISTS electricity_data：id BIGSERIAL、line_id BIGINT NOT NULL（FK→electric_line）、line_code VARCHAR(64) NOT NULL、imei VARCHAR(64)、line_name VARCHAR(128)、customer_id BIGINT NOT NULL、analog_type VARCHAR(64)、analog_name VARCHAR(128)、analog_unit VARCHAR(32)、analog_value NUMERIC(14,4)、collect_time TIMESTAMPTZ NOT NULL；主键 (id, collect_time)；唯一键 UNIQUE (line_code, analog_type, collect_time)；PARTITION BY RANGE (collect_time)
  • 有旧表 → 幂等变更：删除 equip_id/electricity、icc_device_code 更名 imei、新增 analog_type/analog_name/analog_unit/analog_value（数据量小可 DROP 重建）
  • 建分区 2026_10 ~ 2027_03（IF NOT EXISTS）、索引 idx_ed_customer/idx_ed_line/idx_ed_time、表与列 COMMENT
  • 执行到远程生产库并验证（列/分区/唯一键/索引），同步更新 database/db_init.sql 基线定义
• Task 3: 后端实体与映射：新建 server/src/entity/electricity_data.entity.ts（字段 analog_name/analog_unit，FK→electric_line）、server/src/task/icc_analog_mapper.ts（AnalogInfoVO 映射：deviceCode→line_code、uniqueCode→imei、analogType→analog_type、analogName→analog_name、analogUnit→analog_unit、analogValue 数值解析→analog_value；分页解析兼容 data.pageData；接口实测无 reportTime，collect_time 由同步时间填充）
• Task 4: 同步服务：新建 server/src/service/icc_analog_sync.service.ts
  • 复用 getIccAccessToken/iccFetch；先读已同步 electric_line 取 line_code（detectorCode）与 (line_id, customer_id)
  • deviceCodes 分批（每批 ≤50）POST /analog/subsystem/page，pageSize=500 短页停止全量拉取
  • 按 (line_code, analog_type, collect_time) 幂等 upsert（collect_time 用同步时间，同一次同步内重复上报覆盖更新）；写 icc_sync_log（sync_type=electricity_data）；失败仅记日志不抛业务错
• Task 5: 同步接口 + RBAC + 定时任务：
  • 新建 server/src/controller/electricity_data.controller.ts：POST /api/electricity-data/sync 返回 {pulled, inserted, updated, skipped, synced}
  • server/src/middleware/rbac.middleware.ts 增加 /api/electricity-data → device:list
  • 新建 server/src/task/icc_analog_sync.task.ts（jobKey=icc_analog_sync，默认每 5 分钟 */5 * * * *）；job_registry.ts BUILTIN_JOBS 注册 + job_scheduler.service.ts JobRuntime.syncIccAnalogs 注入实现
  • database/db_seed.sql 增加 sys_job 种子（job_key=icc_analog_sync，幂等）
• Task 6: 同步更新 系统设计/表结构新增及变更.md：追加 electricity_data 新表结构（字段/类型/键/注释 + 与 customer/customer_equipment/electric_line 关联说明 + 同步服务与定时任务说明）
• Task 7: 验证：
  • SubTask 7.1: tsc 编译通过（server）
  • SubTask 7.2: 启动后端，调用 POST /api/electricity-data/sync（先确认线路已同步），确认拉到真实模拟量数据入库、幂等重跑 updated/skipped 正常
  • SubTask 7.3: 验证 icc_sync_log 落日志、定时任务注册存在（无前端改动，无需浏览器验证）

Task Dependencies

• Task 2 依赖 Task 1（确认生产库现状后写迁移）
• Task 3 依赖 Task 2（表结构定稿后建实体）
• Task 4 依赖 Task 3（实体与映射就绪后实现同步服务）
• Task 5 依赖 Task 4（同步服务实现后可接线 controller/定时任务）
• Task 6 依赖 Task 2（表结构定稿后写文档）
• Task 7 依赖 Task 4、Task 5