Boonlive_RD_Web/Web_BLS_Heartbeat_Server

Files

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

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

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

2026-01-16 14:45:36 +08:00

3.7 KiB

Raw Blame History

Kafka消息处理规范

Purpose

本规范定义本服务如何连接 Kafka 集群、订阅主题并消费消息（以 buffer 形式透传 payload），以及错误处理/重连与消费确认语义。

Requirements

Requirement: Kafka连接管理

系统 MUST 能够建立和维护与 Kafka 集群的连接。

Scenario: 成功连接Kafka集群

WHEN 系统启动时
THEN 应该成功连接到配置的Kafka集群
AND 应该监控连接状态

Scenario: Kafka连接断开重连

WHEN Kafka连接断开时
THEN 系统应该自动尝试重连
AND 重连失败时应该记录错误日志

Requirement: 心跳消息消费

系统 MUST 能够消费 Kafka 队列中的心跳消息。

Scenario: 消费心跳消息

WHEN Kafka队列中有心跳消息时
THEN 系统应该消费该消息
AND 将消息传递给处理器进行解包

Scenario: 二进制 payload 透传

WHEN Kafka 消息 value 可能为二进制压缩数据（非纯文本）
THEN Consumer 应使用 buffer 方式接收 value/key
AND 将原始 buffer 交由 Processor 执行解码/解压与反序列化

Scenario: 消息消费确认

WHEN 消息处理完成后
THEN 系统应该向Kafka确认消息已消费

Requirement: 消息过滤与路由

系统 MUST 能够根据消息类型过滤和路由心跳消息。

Scenario: 过滤无效消息

WHEN 接收到无效格式的消息时
THEN 系统应该丢弃该消息
AND 记录错误日志

Scenario: 路由有效消息

WHEN 接收到有效格式的心跳消息时
THEN 系统应该将消息路由到正确的处理器

Requirement: 心跳消息载荷格式（生产者约束）

Kafka 心跳消息 MUST 包含数据库落库所需的必填字段，并采用 UTF-8 编码。

Scenario: JSON 心跳消息

WHEN 生产者向主题推送心跳消息
THEN 消息 value 应为 JSON（UTF-8）
AND 至少包含 ts_ms、hotel_id、room_id、device_id、ip、power_state、guest_type、cardless_state、service_mask、pms_state、carbon_state、device_count、comm_seq
AND 可选包含 extra（json object）
AND 可选包含 electricity（array of object）
AND 可选包含 air_conditioner（array of object）

Scenario: electricity 数组字段结构

WHEN 生产者在心跳消息中携带 electricity 字段时
THEN electricity MUST 为数组
AND 数组每个元素 MUST 为对象，包含：
- address（string，设备地址）
- voltage（double，电压）
- ampere（double，电流）
- power（double，功率）
- phase（string，相位）
- energy（double，能耗）
- sum_energy（double，总能耗）

Scenario: air_conditioner 数组字段结构

WHEN 生产者在心跳消息中携带 air_conditioner 字段时
THEN air_conditioner MUST 为数组
AND 数组每个元素 MUST 为对象，包含：
- address（string，设备地址）
- state（int2，开关状态）
- model（int2，运行模式）
- speed（int2，风速设置）
- set_temp（int2，设定温度）
- now_temp（int2，当前温度）
- solenoid_valve（int2，电磁阀门状态）

Requirement: 分区键友好的 Kafka Key

系统 MUST 支持使用 hotel_id:device_id 作为 Kafka message key 以获得更好的分区与有序性。

Scenario: 缺失 key 仍可处理

WHEN 消息未携带 key
THEN 系统仍应能够消费与处理该消息

Scenario: 使用 device_id 作为 key

WHEN 生产者发送消息
THEN 建议使用 hotel_id:device_id 作为 Kafka message key
AND 以提升同设备有序性与消费侧批量聚合效率

3.7 KiB Raw Blame History Unescape Escape