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

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

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

docs/db-heartbeat-schema.md

@@ -22,9 +22,9 @@
 | id | bigserial | 否（自动生成） | 自增序列号（写入时可不提供） |
 | ts_ms | bigint | 是 | 毫秒级时间戳（epoch ms） |
 | hotel_id | int2 | 是 | 酒店编号 |
-| room_id | int4 | 是 | 房间编号（或房间唯一标识） |
+| room_id | varchar(50) | 是 | 房间编号（或房间唯一标识，按字符串存储） |
 | device_id | varchar(64) | 是 | 设备 ID（序列号/MAC/混合编码）；如明确为纯数字可改 bigint |
-| ip | inet | 是 | 设备/上报方 IP（PostgreSQL inet 类型自带格式校验） |
+| ip | varchar(21) | 是 | `IP:PORT`（IPv4）或纯 IP 字符串 |
 | power_state | int2 | 是 | 取电状态（枚举值待标准化） |
 | guest_type | int2 | 是 | 住客身份（住客/空房/保洁/维修等，枚举值待标准化） |
 | cardless_state | int2 | 是 | 无卡取电/无卡策略状态（枚举待定） |
@@ -33,6 +33,20 @@
 | carbon_state | int2 | 是 | 碳控状态（枚举待定） |
 | device_count | int2 | 是 | 设备数量/上报设备数量（语义待确认） |
 | comm_seq | int4 | 是 | 通讯序号（语义待确认） |
+| elec_address | text[] | 否 | 电力设备地址数组（与 voltage[] 等按下标对齐） |
+| voltage | double precision[] | 否 | 电压数组 |
+| ampere | double precision[] | 否 | 电流数组 |
+| power | double precision[] | 否 | 功率数组 |
+| phase | text[] | 否 | 相位数组 |
+| energy | double precision[] | 否 | 能耗数组 |
+| sum_energy | double precision[] | 否 | 总能耗数组 |
+| air_address | text[] | 否 | 空调设备地址数组（与 state[] 等按下标对齐） |
+| state | int2[] | 否 | 开关状态数组 |
+| model | int2[] | 否 | 运行模式数组 |
+| speed | int2[] | 否 | 风速设置数组 |
+| set_temp | int2[] | 否 | 设定温度数组 |
+| now_temp | int2[] | 否 | 当前温度数组 |
+| solenoid_valve | int2[] | 否 | 电磁阀门状态数组 |
 | extra | jsonb | 否 | 可扩展字段：电参/空调状态/版本/来源等 |
 
 ### 2.2 约束
@@ -67,6 +81,15 @@
 - B-tree：`hotel_id`, `power_state`, `guest_type`, `device_id`
 - BRIN：`service_mask`
 
+新增（数组元素查询）：
+- GIN：`elec_address`, `air_address`, `state`, `model`
+
+常用查询示例：
+- `SELECT * FROM heartbeat.heartbeat_events WHERE elec_address @> ARRAY['add11'];`
+- `SELECT * FROM heartbeat.heartbeat_events WHERE air_address @> ARRAY['ac1'];`
+- `SELECT * FROM heartbeat.heartbeat_events WHERE state @> ARRAY[1::int2];`
+- `SELECT * FROM heartbeat.heartbeat_events WHERE model @> ARRAY[2::int2];`
+
 额外建议（脚本默认包含，可按需移除）：
 - `btree (hotel_id, ts_ms)`：覆盖最常见过滤（酒店 + 时间范围），显著提升检索与分区内扫描效率。
 

docs/kafka-heartbeat-producer.md

@@ -21,7 +21,7 @@
 |---|---|---|---|
 | ts_ms | number/int64 | 1700000000123 | 毫秒级 epoch 时间戳 |
 | hotel_id | number/int | 12 | 酒店编号（int2 范围内） |
-| room_id | number/int | 1203 | 房间编号/房间标识（int4） |
+| room_id | string/number | "1203" | 房间编号/房间标识（服务端会归一化为字符串；落库为 varchar(50)） |
 | device_id | string | "A1B2C3D4" | 设备唯一 ID（序列号/MAC/自定义编码） |
 | ip | string | "192.168.1.10:8080" | `IP:PORT` 字符串（落库为 varchar(21)） |
 | power_state | number/int | 1 | 取电状态（枚举值需统一标准） |
@@ -37,6 +37,8 @@
 | 字段 | 类型 | 示例 | 说明 |
 |---|---|---|---|
 | extra | object | {"source":"gw","ver":"1.2.3"} | 扩展字段：电参、空调状态、版本、上报来源等 |
+| electricity | array<object> | [{"address":"add11","voltage":3.2,...}] | 电力设备数组（按原始顺序拆列落库为数组列） |
+| air_conditioner | array<object> | [{"address":"ac1","state":1,...}] | 空调设备数组（按原始顺序拆列落库为数组列） |
 
 ## 4. JSON 示例
 ```json
@@ -54,6 +56,28 @@
   "carbon_state": 0,
   "device_count": 1,
   "comm_seq": 7,
+  "electricity": [
+    {
+      "address": "add11",
+      "voltage": 3.2,
+      "ampere": 1.1,
+      "power": 704.3,
+      "phase": "A",
+      "energy": 10.5,
+      "sum_energy": 100.5
+    }
+  ],
+  "air_conditioner": [
+    {
+      "address": "ac1",
+      "state": 1,
+      "model": 2,
+      "speed": 3,
+      "set_temp": 26,
+      "now_temp": 25,
+      "solenoid_valve": 1
+    }
+  ],
   "extra": {
     "source": "gw",
     "ver": "1.2.3",
@@ -78,4 +102,7 @@
 ## 6. 与数据库字段的映射
 服务端落库目标表：`heartbeat.heartbeat_events`（位于既有数据库中，默认 log_platform）
 - 必填字段：与表字段同名
-- 弹性字段：写入 `extra`（jsonb）
+- 扩展数组字段：
+  - electricity[] → elec_address[]、voltage[]、ampere[]、power[]、phase[]、energy[]、sum_energy[]
+  - air_conditioner[] → air_address[]、state[]、model[]、speed[]、set_temp[]、now_temp[]、solenoid_valve[]
+- 弹性字段：其余未知字段写入 `extra`（jsonb）