feat: 扩展心跳消息支持电力与空调设备数组字段

新增 Kafka 消息中 electricity[] 和 air_conditioner[] 数组字段支持，用于存储电力与空调设备明细数据。数据库表新增对应数组列并创建 GIN 索引优化查询性能，processor 实现数组字段校验与聚合转换逻辑。

主要变更：
- Kafka 消息规范新增 electricity 和 air_conditioner 数组字段定义
- 数据库 heartbeat_events 表新增 14 个数组列并创建 4 个 GIN 索引
- processor 实现数组字段解析、校验及聚合转换逻辑
- 更新相关文档与测试用例，确保端到端功能完整

.trae/documents/扩展心跳数据以支持电力与空调数组.md

@@ -0,0 +1,202 @@
+## 目标与范围
+
+* 扩展 Kafka 心跳消息以支持 electricity\[] 与 air\_conditioner\[] 两类数组字段，并保持顺序一致性
+
+* 数据库 heartbeat.heartbeat\_events 新增对应的数组列，并为指定列建立“针对数组元素”的索引
+
+* Processor 增强：解析/校验/转换并输出数组列；DB 写入批量适配
+
+* 补充 OpenSpec 规格、文档与测试，完成端到端验证
+
+## OpenSpec 变更
+
+* 创建变更（changes）：`update-heartbeat-arrays-v3`
+
+* 修改以下规格文件（新增/修改 Requirements + 场景）：
+
+  * specs/kafka/spec.md：
+
+    * ADDED：Kafka 消息 MUST 支持 electricity\[] 与 air\_conditioner\[]
+
+    * electricity.item 结构：{ address:string, voltage:double, ampere:double, power:double, phase:string, energy:double, sum\_energy:double }
+
+    * air\_conditioner.item 结构：{ address:string, state:int2, model:int2, speed:int2, set\_temp:int2, now\_temp:int2, solenoid\_valve:int2 }
+
+  * specs/processor/spec.md：
+
+    * ADDED：数组聚合转换规则（逐项按原始顺序提取出列数组）；顺序一致性；缺失/类型校验；转换到 DB 列
+
+  * specs/db/spec.md：
+
+    * ADDED：表结构新增数组列；为 elec\_address(text\[]), air\_address(text\[]), state(int2\[]), model(int2\[]) 建立 GIN 索引（数组元素级查询建议 `@> ARRAY[...]`）
+
+  * specs/redis/spec.md：无需改动（协议不变）
+
+* docs 更新：
+
+  * docs/kafka-heartbeat-producer.md：补充数组字段示例与类型说明（示例以数值 ampere 为准；若上游偶有字符串，需按数值可解析策略）
+
+  * docs/db-heartbeat-schema.md：补充新增列与索引说明、查询示例（`col @> ARRAY['addr']`、`state @> ARRAY[1]`）
+
+## 数据库结构调整
+
+* 在父分区表 heartbeat.heartbeat\_events 添加新列（所有分区自动继承）：
+
+  * 电力类：
+
+    * elec\_address text\[]{索引}
+
+    * voltage double precision\[]
+
+    * ampere double precision\[]
+
+    * power double precision\[]
+
+    * phase text\[]
+
+    * energy double precision\[]
+
+    * sum\_energy double precision\[]
+
+  * 空调类：
+
+    * air\_address text\[]{索引}
+
+    * state int2\[]  {索引}
+
+    * model int2\[]  {索引}
+
+    * speed int2\[]
+
+    * set\_temp int2\[]
+
+    * now\_temp int2\[]
+
+    * solenoid\_valve int2\[]
+
+* 索引（在父表上创建分区索引）：
+
+  * CREATE INDEX IF NOT EXISTS idx\_he\_events\_elec\_address\_gin ON heartbeat.heartbeat\_events USING GIN (elec\_address);
+
+  * CREATE INDEX IF NOT EXISTS idx\_he\_events\_air\_address\_gin ON heartbeat.heartbeat\_events USING GIN (air\_address);
+
+  * CREATE INDEX IF NOT EXISTS idx\_he\_events\_state\_gin ON heartbeat.heartbeat\_events USING GIN (state);
+
+  * CREATE INDEX IF NOT EXISTS idx\_he\_events\_model\_gin ON heartbeat.heartbeat\_events USING GIN (model);
+
+* 约束与空值策略：
+
+  * 新增数组列默认可为空（NULL）；长度不限制；类型按上述定义
+
+  * 不引入新 CHECK 约束（避免上游演进时写入失败）；后续可在枚举稳定后收紧
+
+* 迁移实现：
+
+  * 在 initTables 后追加“ALTER TABLE ... ADD COLUMN IF NOT EXISTS ...”
+
+  * 创建分区索引（父表）并确认落于各分区（PostgreSQL 11+ 支持分区索引）
+
+## Processor 处理逻辑调整
+
+* 解析：
+
+  * 在 normalizeHeartbeat 阶段读取 obj.electricity 与 obj.air\_conditioner（兼容 camelCase/PascalCase）
+
+* 转换：
+
+  * electricity\[]：按原始顺序聚合为列：elec\_address\[], voltage\[], ampere\[], power\[], phase\[], energy\[], sum\_energy\[]
+
+  * air\_conditioner\[]：聚合为列：air\_address\[], state\[], model\[], speed\[], set\_temp\[], now\_temp\[], solenoid\_valve\[]
+
+  * 值类型转换：
+
+    * address/phase → string（trim 且空串视为缺失）
+
+    * 数值列：若为 string 可解析为数字则接受；不可解析则标记为缺失（跳过该项）
+
+  * 顺序保证：按输入数组原始顺序放入各列数组；对缺失字段以“跳过该项”或“插入 null”策略统一（建议插入 null 保持长度对齐）
+
+* 校验：
+
+  * 若两类数组存在，则至少 address 有内容；其余数值/枚举字段允许包含 null
+
+  * 不影响 v2 原有必填字段校验
+
+* 输出：
+
+  * 在 transformData 返回对象中携带新增数组列；insertHeartbeatEvents 扩展列清单并写入
+
+## Kafka 消费者调整
+
+* Consumer 本身不改（仍以 buffer 透传）
+
+## 写库逻辑调整
+
+* insertHeartbeatEvents：
+
+  * 扩展 columns 列表与 values/占位符生成；数组列直接作为参数传入（pg 支持将 JS 数组映射到 Postgres 数组）
+
+  * 事务语义与分区预建逻辑保持不变
+
+## 校验与质量保证
+
+* 顺序一致性：
+
+  * 单元测试：给定 3 项 electricity/air\_conditioner 输入，断言各列数组按顺序聚合
+
+* 类型与缺失校验：
+
+  * 单元测试：混合数值字符串（"3.2"）与非法字符串（"N/A"），确保解析并对非法项填 null，数组长度与 address 对齐
+
+* 端到端验证：
+
+  * 伪造 Kafka message.value（UTF-8 JSON）走 Processor → DB 插入（使用测试隔离库或事务回滚）
+
+* 文档更新：
+
+  * 更新 API（Producer）与 DB schema 文档；给出查询示例：
+
+    * `SELECT * FROM heartbeat.heartbeat_events WHERE elec_address @> ARRAY['add11'];`
+
+    * `SELECT * FROM heartbeat.heartbeat_events WHERE state @> ARRAY[1];`
+
+## 风险与兼容
+
+* 分区索引构建时间与磁盘占用：
+
+  * 在父表创建分区索引；按分区数指数增长，需结合实际分区策略与 autovacuum 调优
+
+## 交付清单
+
+* OpenSpec 变更集：`openspec/changes/update-heartbeat-arrays-v3/`（proposal、tasks、spec deltas）
+
+* 代码修改：
+
+  * src/processor/heartbeatProcessor.js（normalize+transform+校验与聚合）
+
+  * src/db/databaseManager.js（新增列 + 索引 + insert 扩展）
+
+  * src/kafka/consumer.js（无需改动）
+
+* 测试：
+
+  * test/processor.arrays.test.js（顺序与类型/缺失校验）
+
+  * 如需：test/db.insert.arrays.test.js（占位符与 rowCount 校验）
+
+* 文档：
+
+  * docs/kafka-heartbeat-producer.md（数组示例）
+
+  * docs/db-heartbeat-schema.md（新增列与索引查询示例）
+
+## 实施步骤
+
+1. 编写 OpenSpec 变更（ADDED Requirements + 场景）并验证
+2. 数据库父表追加列 + 创建分区索引（初始化流程集成）
+3. Processor：实现解析/校验/聚合/转换；保持与现有 v2 字段兼容
+4. DB 写入：扩展 insertHeartbeatEvents 列与占位符映射
+5. 编写并运行单元测试；必要时写端到端冒烟
+6. 更新文档；准备部署说明（分区索引创建时间提示）
+
+请确认以上方案，确认后我将按该计划开始实施（含规格增量、代码修改、测试与文档）。