refactor(openspec): 归档心跳数据库v2更新相关文档
将update-heartbeat-db-v2目录下的文档迁移至archive目录 更新specs目录下的相关规范文件以反映最新变更
This commit is contained in:
@@ -2,9 +2,7 @@
|
||||
|
||||
## Purpose
|
||||
本规范定义本服务对 PostgreSQL 的连接池配置、表结构初始化（含分区表）、分区预创建维护策略、批量写入与约束错误处理等行为。
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: 数据库连接管理
|
||||
系统 MUST 能够建立和维护与 PostgreSQL 数据库的连接。
|
||||
|
||||
@@ -48,21 +46,17 @@
|
||||
### Requirement: 数据库表结构管理
|
||||
系统 MUST 提供数据库表结构的定义和管理机制。
|
||||
|
||||
#### Scenario: 表结构初始化
|
||||
- **WHEN** 系统首次启动时
|
||||
- **THEN** 系统应该检查数据库表是否存在
|
||||
- **AND** 不存在时应该创建表结构
|
||||
#### 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** 系统应该预创建未来一段时间（例如未来 30 天）的日分区
|
||||
- **AND** 系统应该周期性执行该预创建以保证长期运行不中断
|
||||
- **AND** 当分区预创建失败时应记录错误日志
|
||||
|
||||
#### Scenario: 表结构迁移
|
||||
- **WHEN** 表结构需要变更时
|
||||
- **THEN** 系统应该支持平滑的表结构迁移
|
||||
- **AND** 不影响现有数据
|
||||
#### Scenario: 自动分区
|
||||
- **WHEN** 写入某天数据而该日分区不存在
|
||||
- **THEN** 系统应能够自动创建对应日分区或确保分区被预创建
|
||||
- **AND** 不应影响持续写入（高吞吐场景）
|
||||
|
||||
### Requirement: 数据查询支持
|
||||
系统 MUST 支持基本的数据查询操作，用于监控和调试。
|
||||
@@ -76,3 +70,12 @@
|
||||
- **WHEN** 需要按特定条件查询心跳数据时
|
||||
- **THEN** 系统应该支持条件过滤
|
||||
- **AND** 返回符合条件的数据
|
||||
|
||||
### Requirement: 高吞吐写入友好
|
||||
系统 MUST 在高吞吐场景（约 5 万条/分钟量级）下避免单点瓶颈。
|
||||
|
||||
#### Scenario: 批量写入与分区裁剪
|
||||
- **WHEN** 进行批量写入
|
||||
- **THEN** 写入应路由到正确日分区
|
||||
- **AND** 常见查询（hotel_id + 时间范围）应触发分区裁剪
|
||||
|
||||
|
||||
@@ -2,9 +2,7 @@
|
||||
|
||||
## Purpose
|
||||
本规范定义本服务如何连接 Kafka 集群、订阅主题并消费消息（以 buffer 形式透传 payload），以及错误处理/重连与消费确认语义。
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: Kafka连接管理
|
||||
系统 MUST 能够建立和维护与 Kafka 集群的连接。
|
||||
|
||||
@@ -46,3 +44,25 @@
|
||||
#### 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）
|
||||
|
||||
### 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** 以提升同设备有序性与消费侧批量聚合效率
|
||||
|
||||
|
||||
@@ -2,11 +2,9 @@
|
||||
|
||||
## Purpose
|
||||
本规范定义心跳处理器对 Kafka 消息 value 的解码/解压（含两层以内组合）、字段校验、转换为分区表写入结构，以及批量写库与失败丢弃/记录策略。
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: 心跳数据解包
|
||||
系统 MUST 能够解包 Kafka 消息中的心跳数据。
|
||||
系统 MUST 能够将 Kafka 消息 value 解码/解压并还原为 JSON 对象或数组，支持两层以内的编码/压缩组合。
|
||||
|
||||
#### Scenario: 支持常见编码/压缩（两层以内）
|
||||
- **WHEN** Kafka 消息 value 为下列任意形式时：
|
||||
@@ -48,11 +46,15 @@
|
||||
### Requirement: 心跳数据转换
|
||||
系统 MUST 能够将解包后的心跳数据转换为数据库存储格式。
|
||||
|
||||
#### Scenario: 转换心跳数据格式
|
||||
#### Scenario: 转换为 v2 明细表字段
|
||||
- **WHEN** 心跳数据验证通过时
|
||||
- **THEN** 系统应该将数据转换为数据库表结构所需的格式
|
||||
- **THEN** 系统应输出与 v2 明细表字段一致的数据结构
|
||||
- **AND** 添加必要的元数据
|
||||
|
||||
#### Scenario: 缺失必填字段
|
||||
- **WHEN** 心跳数据缺失必填字段时
|
||||
- **THEN** 系统应判定为无效数据并丢弃
|
||||
|
||||
### Requirement: 批量处理支持
|
||||
系统 MUST 支持批量处理心跳数据，提高处理效率。
|
||||
|
||||
@@ -64,3 +66,4 @@
|
||||
#### Scenario: Kafka 单条消息携带批量心跳
|
||||
- **WHEN** Kafka 消息 value 为 JSON 数组（批量心跳）
|
||||
- **THEN** 系统应将数组内每条心跳作为独立项进入批处理队列
|
||||
|
||||
|
||||
Reference in New Issue
Block a user