3.1 KiB
3.1 KiB
数据库操作规范
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 需要查询最新的心跳数据时
- THEN 系统应该提供查询接口
- AND 返回符合条件的数据
Scenario: 按条件查询心跳数据
- WHEN 需要按特定条件查询心跳数据时
- THEN 系统应该支持条件过滤
- AND 返回符合条件的数据
Requirement: 高吞吐写入友好
系统 MUST 在高吞吐场景（约 5 万条/分钟量级）下避免单点瓶颈。
Scenario: 批量写入与分区裁剪
- WHEN 进行批量写入
- THEN 写入应路由到正确日分区
- AND 常见查询（hotel_id + 时间范围）应触发分区裁剪