feat: 升级心跳数据库为高吞吐日分区模型（v2）

- 新增 heartbeat 数据库与表结构文档，描述心跳明细表设计及字段约束。
- 新增 OpenSpec 符合性说明文档，指出与规范的一致点及偏差。
- 新增 Kafka 心跳数据推送说明文档，定义消息格式与推送方式。
- 更新数据库创建脚本，支持 UTF-8 编码与中文排序规则。
- 更新心跳表结构脚本，定义主表及索引，采用 ts_ms 日分区。
- 实现自动分区机制，确保按天创建分区以支持高吞吐写入。
- 添加数据库应用脚本，自动执行 SQL 文件并验证表结构。
- 添加运行时烟雾测试脚本，验证数据库连接与基本操作。
- 添加完整的烟雾测试脚本，验证数据插入与分区创建。

openspec/changes/update-heartbeat-db-v2/proposal.md

@@ -0,0 +1,20 @@
+# Change: 升级心跳数据库为高吞吐日分区模型（v2）
+
+## Why
+现有实现仅包含简化的 `heartbeat` 表（component/status/timestamp），无法满足“每分钟约 5 万条记录、按酒店/时间范围检索、按状态聚合”的高吞吐与长期存储需求。
+
+## What Changes
+- **DB**：在既有数据库（默认 `log_platform`）内新增/升级为按 `ts_ms`（毫秒 epoch）日分区的心跳明细表，并提供分区预创建机制
+- **DB**：补齐指定索引（hotel_id/power_state/guest_type/device_id B-tree；service_mask BRIN）与约束（NOT NULL、CHECK、IP 格式）
+- **Docs**：补充 Kafka 生产者推送数据结构与推送方式说明
+
+## Impact
+- Affected specs: `openspec/specs/db`, `openspec/specs/kafka`, `openspec/specs/processor`
+- Affected code: 未来 `src/db/databaseManager.js` 的表初始化/写入字段将需要适配（本变更提案先聚焦 DB 结构与脚本）
+
+## Key Decisions / Risks (需要明确)
+- **分区 + 主键冲突风险**：PostgreSQL 分区表的全局唯一/主键通常需要包含分区键；需求写“主键仅 id(bigserial)”。
+  - 本次脚本将采用 `PRIMARY KEY (ts_ms, id)` 来保证可创建与可执行。
+- **device_id 类型待确认**：脚本暂定为 `varchar(64)`（兼容序列号/MAC/混合编码）；若确定为纯数字，可改为 `bigint` 获得更紧凑索引。
+- **中文排序规则**：不新建库时无法修改数据库级 collation；若需要中文排序建议使用 ICU collation（列级/表达式级）。
+- **自动建分区方式**：PostgreSQL 在单条 INSERT 执行过程中动态 `CREATE PARTITION` 会触发“对象正在使用”限制；因此采用“预创建分区（安装/定时任务/启动时调用）”。

openspec/changes/update-heartbeat-db-v2/specs/db/spec.md

@@ -0,0 +1,26 @@
+## MODIFIED Requirements
+
+### Requirement: 数据库表结构管理
+系统必须包含数据库表结构的定义和管理机制。
+
+#### 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** 不应影响持续写入（高吞吐场景）
+
+## ADDED Requirements
+
+### Requirement: 高吞吐写入友好
+系统在高吞吐场景（约 5 万条/分钟量级）下应避免单点瓶颈。
+
+#### Scenario: 批量写入与分区裁剪
+- **WHEN** 进行批量写入
+- **THEN** 写入应路由到正确日分区
+- **AND** 常见查询（hotel_id + 时间范围）应触发分区裁剪

openspec/changes/update-heartbeat-db-v2/specs/kafka/spec.md

@@ -0,0 +1,17 @@
+## ADDED Requirements
+
+### Requirement: 心跳消息载荷格式（生产者约束）
+Kafka 心跳消息必须包含数据库落库所需的必填字段，并采用 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
+
+#### Scenario: 使用 device_id 作为 key
+- **WHEN** 生产者发送消息
+- **THEN** 建议使用 `hotel_id:device_id` 作为 Kafka message key
+- **AND** 以提升同设备有序性与消费侧批量聚合效率

openspec/changes/update-heartbeat-db-v2/specs/processor/spec.md

@@ -0,0 +1,9 @@
+## MODIFIED Requirements
+
+### Requirement: 心跳数据转换
+系统必须能够将解包后的心跳数据转换为数据库存储格式。
+
+#### Scenario: 转换为 v2 明细表字段
+- **WHEN** 心跳数据验证通过时
+- **THEN** 系统应输出与 v2 明细表字段一致的数据结构
+- **AND** 缺失必填字段时应判定为无效数据并丢弃

openspec/changes/update-heartbeat-db-v2/tasks.md

@@ -0,0 +1,10 @@
+## 1. Implementation
+- [ ] 提供 PostgreSQL 建库脚本（UTF-8 + 中文排序规则可选）
+- [ ] 提供心跳明细表结构（必填字段、可选字段、约束、索引）
+- [ ] 实现按 `ts_ms` 日分区与自动建分区机制
+- [ ] 补充性能建议（索引策略、分区影响、聚合/物化视图建议）
+- [ ] 产出 docs：DB 表结构文档 + Kafka 生产者推送数据结构与方式
+
+## 2. Validation
+- [ ] 在可访问的 PostgreSQL 环境执行脚本并验证对象创建成功
+- [ ] 检查约束与索引是否符合要求

openspec/specs/db/spec.md

@@ -50,6 +50,12 @@
 - **THEN** 系统应该检查数据库表是否存在
 - **AND** 不存在时应该创建表结构
 
+#### Scenario: 分区预创建（无人值守）
+- **WHEN** 系统启动完成数据库初始化后
+- **THEN** 系统应该预创建未来一段时间（例如未来 30 天）的日分区
+- **AND** 系统应该周期性执行该预创建以保证长期运行不中断
+- **AND** 当分区预创建失败时应记录错误日志
+
 #### Scenario: 表结构迁移
 - **WHEN** 表结构需要变更时
 - **THEN** 系统应该支持平滑的表结构迁移