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

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

主要变更:
- Kafka 消息规范新增 electricity 和 air_conditioner 数组字段定义
- 数据库 heartbeat_events 表新增 14 个数组列并创建 4 个 GIN 索引
- processor 实现数组字段解析、校验及聚合转换逻辑
- 更新相关文档与测试用例,确保端到端功能完整
This commit is contained in:
2026-01-16 14:45:36 +08:00
parent 7d5b9c50ea
commit 455185ac5d
16 changed files with 693 additions and 8 deletions

View File

@@ -0,0 +1,11 @@
## ADDED Requirements
### Requirement: 分区表新增数组列与数组元素索引
系统 SHALL 在 `heartbeat.heartbeat_events` 中新增用于存储电力与空调子设备的数组列,并为指定数组列提供数组元素级查询索引。
#### Scenario: 新增数组列
- **WHEN** 部署或升级数据库结构时
- **THEN** 表应包含 elec_address、air_address、voltage、ampere、power、phase、energy、sum_energy、state、model、speed、set_temp、now_temp、solenoid_valve
#### Scenario: 数组元素索引
- **WHEN** 需要按 elec_address/air_address/state/model 的数组元素进行查询
- **THEN** 数据库应具备 GIN 索引以优化包含类查询

View File

@@ -0,0 +1,13 @@
## ADDED Requirements
### Requirement: 心跳消息扩展数组字段
Kafka 心跳消息 SHALL 支持携带电力与空调子设备的数组字段,以便消费端拆列落库与查询优化。
#### Scenario: 携带 electricity 数组
- **WHEN** 生产者需要上报电力设备明细时
- **THEN** 消息可选包含 `electricity`array of object
- **AND** 每个元素包含 address、voltage、ampere、power、phase、energy、sum_energy
#### Scenario: 携带 air_conditioner 数组
- **WHEN** 生产者需要上报空调设备明细时
- **THEN** 消息可选包含 `air_conditioner`array of object
- **AND** 每个元素包含 address、state、model、speed、set_temp、now_temp、solenoid_valve

View File

@@ -0,0 +1,19 @@
## ADDED Requirements
### Requirement: 数组字段聚合为列数组
系统 SHALL 将 `electricity[]``air_conditioner[]` 按原始顺序聚合为数据库写入结构的列数组。
#### Scenario: electricity 聚合
- **WHEN** 输入包含 `electricity` 数组
- **THEN** 输出应包含 elec_address[]、voltage[]、ampere[]、power[]、phase[]、energy[]、sum_energy[]
- **AND** 各数组下标与输入数组下标一一对应
#### Scenario: air_conditioner 聚合
- **WHEN** 输入包含 `air_conditioner` 数组
- **THEN** 输出应包含 air_address[]、state[]、model[]、speed[]、set_temp[]、now_temp[]、solenoid_valve[]
- **AND** 各数组下标与输入数组下标一一对应
#### Scenario: 类型与缺失处理
- **WHEN** electricity 或 air_conditioner 存在但不是数组
- **THEN** 系统应丢弃该消息并记录错误
- **WHEN** 数组元素字段缺失或无法转换
- **THEN** 系统应保持长度对齐并写入 null