feat(analog): 新增ICC模拟量数据同步 - 重建electricity_data表（迁移20261024_icc_analog_data.sql：删除equip_id与electricity占位列、icc_device_code更名imei、新增analog_type/analog_name/analog_unit/analog_value、collect_time以同步时间填充、按月分区2026_10~2027_03、唯一键(line_code,analog_type,collect_time)）；同步服务IccAnalogSyncService复用OAuth2鉴权，按已同步线路line_code分批（≤50）拉取最新模拟量（POST /analog/subsystem/page，pageSize=500短页停止）幂等upsert并写icc_sync_log（sync_type=electricity_data）；新增POST /api/electricity-data/sync手动同步（RBAC device:list）；注册icc_analog_sync每5分钟定时任务与sys_job种子；同步db_init/db_seed与设计文档；无前端改动

2026-10-24 14:52:22 +08:00
1 parent 160ad85051
commit c92fc7f298
@@ -0,0 +1,63 @@
+# ICC 模拟量数据同步 Spec（add-icc-analog-data）
+
+## Why
+现有 `electricity_data`（线路用电信息表）仅有一版占位定义（单列 `electricity`），与 ICC 平台「消防最新模拟量信息分页查询」接口（`POST /evo-apigw/evo-fdbu/{version}/analog/subsystem/page`，实测返回 `{deviceCode, uniqueCode, analogType, analogName, analogUnit, analogValue}`，无时间字段）不对应。本次按接口返回数据重建表结构，并实现真实同步服务与定时任务，将已同步线路对应探测器的模拟量数据写入 electricity_data。
+
+## What Changes
+- **表结构重建（BREAKING）**：
+  - 删除占位列 `electricity` → 通用模拟量行：`analog_type`（analogType）、`analog_value` NUMERIC(14,4)（analogValue）、`analog_name`（analogName，如：剩余电流）、`analog_unit`（analogUnit，如：mA）
+  - `icc_device_code` 改为 `imei`（映射 uniqueCode）
+  - **删除 `equip_id`**（用户确认不需要客户设备关联）
+  - 保留：`line_id`（NOT NULL → electric_line）、`line_code`（NOT NULL，= deviceCode 冗余 + 幂等键）、`line_name`（冗余展示）、`customer_id`（NOT NULL，逻辑隔离键）、`collect_time`（NOT NULL，分区键）
+  - **collect_time 语义（实测确认）**：ICC「最新模拟量分页查询」接口实际不返回 reportTime 时间字段，经用户确认以**同步时间**作为采集时间（分区键）
+  - 唯一幂等键：`UNIQUE (line_code, analog_type, collect_time)`（同一次同步内重复上报覆盖更新）
+  - 按月 RANGE 分区（分区键 collect_time），迁移建当月及后续月份分区
+- **同步服务**（复用 icc_customer_auth 真实 OAuth2 鉴权）：
+  - 先读取已同步的 electric_line（line_code = detectorCode），按 deviceCodes 分批（每批 ≤50）POST 模拟量接口，pageSize=500 短页停止全量拉取
+  - 预取 deviceCode→(line_id, customer_id) 映射避免 N+1；imei=uniqueCode、analog_type=analogType、analog_name=analogName、analog_unit=analogUnit、analog_value=analogValue 数值解析、collect_time=同步时间
+  - 按唯一键 (line_code, analog_type, collect_time) 幂等 upsert；写 icc_sync_log（sync_type=electricity_data）；失败仅记日志不抛业务错
+- **定时任务**：jobKey=`icc_analog_sync`（默认每 5 分钟，cron `*/5 * * * *`，sys_job 种子幂等），注册进 job_registry/JobRuntime（syncIccAnalogs）
+- **同步接口**：`POST /api/electricity-data/sync`（JWT+RBAC device:list，返回 pulled/inserted/updated/skipped/synced）；不做前端页面/菜单
+- **迁移与文档**：新增 `database/migrations/20261024_icc_analog_data.sql`（建表/分区/索引/注释 + sys_job 种子），同步 `database/db_init.sql` 与 `系统设计/表结构新增及变更.md`
+
+## Impact
+- Affected specs：add-icc-line-sync（electric_line 为模拟量关联目标，先同步线路）
+- Affected code：
+  - 后端新增：`server/src/entity/electricity_data.entity.ts`、`server/src/task/icc_analog_mapper.ts`、`server/src/service/icc_analog_sync.service.ts`、`server/src/task/icc_analog_sync.task.ts`、`server/src/controller/electricity_data.controller.ts`
+  - 后端修改：`server/src/task/job_registry.ts`、`server/src/service/job_scheduler.service.ts`、`server/src/middleware/rbac.middleware.ts`
+  - 数据库：新增 `database/migrations/20261024_icc_analog_data.sql`；修改 `database/db_init.sql`、`database/db_seed.sql`（sys_job 种子）
+  - 设计文档：`系统设计/表结构新增及变更.md`
+  - 前端：无改动
+
+## ADDED Requirements
+
+### Requirement: electricity_data 表结构按 AnalogInfoVO 重建
+系统 SHALL 将 `electricity_data` 重建为按月分区时序表：id（复合主键含 collect_time）、line_id（NOT NULL FK→electric_line）、line_code（NOT NULL）、imei、line_name、customer_id（NOT NULL）、analog_type、analog_name、analog_unit、analog_value NUMERIC(14,4)、collect_time TIMESTAMPTZ（NOT NULL 分区键，同步时间），唯一键 `UNIQUE (line_code, analog_type, collect_time)`，索引 customer_id/line_id/collect_time。
+
+#### Scenario: 迁移执行成功
+- **WHEN** 执行迁移到生产库
+- **THEN** electricity_data 含上述字段/分区/唯一键/索引；db_init.sql 与迁移一致
+
+### Requirement: 真实 ICC 模拟量拉取同步
+系统 SHALL 复用 `getIccAccessToken`/`iccFetch`，以已同步线路的 line_code（detectorCode）分批作为 deviceCodes，POST 模拟量接口分页拉取（pageSize=500 短页停止），以同步时间作为 collect_time，按 (line_code, analog_type, collect_time) 幂等 upsert，写 icc_sync_log（sync_type=electricity_data），失败仅记日志不抛。
+
+#### Scenario: 同步成功
+- **WHEN** 定时任务或 POST /api/electricity-data/sync 触发
+- **THEN** 返回 {pulled, inserted, updated, skipped, synced}；同键重复上报覆盖更新；无线路匹配的行跳过
+
+#### Scenario: 同步失败
+- **WHEN** ICC 拉取异常
+- **THEN** 仅写 icc_sync_log 失败日志，接口返回 code 200 与当前计数
+
+### Requirement: 定时任务注册
+系统 SHALL 注册 `icc_analog_sync` 定时任务（默认每 5 分钟，cron `*/5 * * * *`），注册进 job_registry BUILTIN_JOBS 与 JobRuntime.syncIccAnalogs，sys_job 种子幂等。
+
+#### Scenario: 任务可执行
+- **WHEN** 任务调度触发
+- **THEN** 调用同步服务并将结果写入执行记录
+
+## REMOVED Requirements
+
+### Requirement: 占位 electricity 单列结构（旧 electricity_data）
+**Reason**：与模拟量接口返回结构不对应。
+**Migration**：electricity → analog_type/analog_value；icc_device_code → imei；equip_id 删除；collect_time 改由同步时间填充（接口实测无 reportTime）。