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

4.0 KiB

Raw Blame History

数据库操作规范

Purpose

本规范定义本服务对 PostgreSQL 的连接池配置、表结构初始化（含分区表）、分区预创建维护策略、批量写入与约束错误处理等行为。

Requirements

Requirement: 数据库连接管理

系统 MUST 能够建立和维护与 PostgreSQL 数据库的连接。

Scenario: 成功连接数据库

WHEN 系统启动时
THEN 应该成功连接到配置的PostgreSQL数据库
AND 应该监控连接状态

Scenario: 数据库连接断开重连

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

Requirement: 心跳数据写入

系统 MUST 能够将处理后的心跳数据写入 PostgreSQL 数据库。

Scenario: 写入单条心跳数据

WHEN 接收到单条处理后的心跳数据时
THEN 系统应该将数据写入数据库
AND 返回写入结果

Scenario: 批量写入心跳数据

WHEN 接收到批量处理后的心跳数据时
THEN 系统应该使用批量写入机制将数据写入数据库
AND 提高写入效率

Requirement: 数据完整性保障

系统 MUST 保障写入数据库的心跳数据完整性。

Scenario: 事务管理

WHEN 写入多条相关数据时
THEN 系统应该使用事务确保数据一致性
AND 要么全部写入成功，要么全部失败

Scenario: 数据约束验证

WHEN 写入的数据违反数据库约束时
THEN 系统应该捕获约束错误
AND 记录错误日志
AND 根据配置决定是否重试

Requirement: 数据库表结构管理

系统 MUST 提供数据库表结构的定义和管理机制。

Scenario: 表结构初始化（高吞吐分区表）

WHEN 系统首次启动或部署数据库时
THEN 应该存在按 ts_ms 日分区的心跳明细表
AND 必填字段应具备 NOT NULL 约束
AND 状态类字段应具备 CHECK 约束（限制取值范围）
AND 必需索引应存在（hotel_id/power_state/guest_type/device_id B-tree；service_mask BRIN）

Scenario: 自动分区

WHEN 写入某天数据而该日分区不存在
THEN 系统应能够自动创建对应日分区或确保分区被预创建
AND 不应影响持续写入（高吞吐场景）

Requirement: 数组字段存储与索引

系统 MUST 支持将电力与空调子设备数据以数组列形式存储，并为指定数组列建立针对元素查询的索引。

Scenario: 新增数组列用于存储电力与空调子设备数据

WHEN 系统初始化 v2 心跳明细表结构时
THEN 表结构应包含以下新增列：
- elec_address（text[]）
- air_address（text[]）
- voltage（double precision[]）、ampere（double precision[]）、power（double precision[]）、phase（text[]）、energy（double precision[]）、sum_energy（double precision[]）
- state（int2[]）、model（int2[]）、speed（int2[]）、set_temp（int2[]）、now_temp（int2[]）、solenoid_valve（int2[]）

Scenario: 针对数组元素的索引

WHEN 对 elec_address、air_address、state、model 执行“元素包含”类查询时
THEN 系统应提供 GIN 索引以优化查询

Requirement: 数据查询支持

系统 MUST 支持基本的数据查询操作，用于监控和调试。

Scenario: 查询最新心跳数据

WHEN 需要查询最新的心跳数据时
THEN 系统应该提供查询接口
AND 返回符合条件的数据

Scenario: 按条件查询心跳数据

WHEN 需要按特定条件查询心跳数据时
THEN 系统应该支持条件过滤
AND 返回符合条件的数据

Requirement: 高吞吐写入友好

系统 MUST 在高吞吐场景（约 5 万条/分钟量级）下避免单点瓶颈。

Scenario: 批量写入与分区裁剪

WHEN 进行批量写入
THEN 写入应路由到正确日分区
AND 常见查询（hotel_id + 时间范围）应触发分区裁剪

4.0 KiB Raw Blame History Unescape Escape