From d10bedb7e70395f5797105e92f351e93a213354a Mon Sep 17 00:00:00 2001 From: XuJiacheng Date: Tue, 3 Feb 2026 08:41:40 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=BD=92=E6=A1=A3=E5=BF=83=E8=B7=B3?= =?UTF-8?q?=E6=95=B0=E7=BB=84=E6=89=A9=E5=B1=95=E4=BB=BB=E5=8A=A1=E5=B9=B6?= =?UTF-8?q?=E6=9B=B4=E6=96=B0=E8=A7=84=E8=8C=83=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 将已完成的任务清单、提案及规范从变更目录移至归档目录，并更新主规范文档以包含新增的数组字段与处理要求。这标志着该功能变更已从开发阶段进入完成归档阶段。 --- .../proposal.md | 0 .../specs/db/spec.md | 0 .../specs/kafka/spec.md | 0 .../specs/processor/spec.md | 0 .../tasks.md | 11 +++++++++++ .../changes/update-heartbeat-arrays-v3/tasks.md | 11 ----------- openspec/specs/db/spec.md | 7 +++++++ openspec/specs/kafka/spec.md | 11 +++++++++++ openspec/specs/processor/spec.md | 15 +++++++++++++++ 9 files changed, 44 insertions(+), 11 deletions(-) rename openspec/changes/{update-heartbeat-arrays-v3 => archive/2026-02-03-update-heartbeat-arrays-v3}/proposal.md (100%) rename openspec/changes/{update-heartbeat-arrays-v3 => archive/2026-02-03-update-heartbeat-arrays-v3}/specs/db/spec.md (100%) rename openspec/changes/{update-heartbeat-arrays-v3 => archive/2026-02-03-update-heartbeat-arrays-v3}/specs/kafka/spec.md (100%) rename openspec/changes/{update-heartbeat-arrays-v3 => archive/2026-02-03-update-heartbeat-arrays-v3}/specs/processor/spec.md (100%) create mode 100644 openspec/changes/archive/2026-02-03-update-heartbeat-arrays-v3/tasks.md delete mode 100644 openspec/changes/update-heartbeat-arrays-v3/tasks.md diff --git a/openspec/changes/update-heartbeat-arrays-v3/proposal.md b/openspec/changes/archive/2026-02-03-update-heartbeat-arrays-v3/proposal.md similarity index 100% rename from openspec/changes/update-heartbeat-arrays-v3/proposal.md rename to openspec/changes/archive/2026-02-03-update-heartbeat-arrays-v3/proposal.md diff --git a/openspec/changes/update-heartbeat-arrays-v3/specs/db/spec.md b/openspec/changes/archive/2026-02-03-update-heartbeat-arrays-v3/specs/db/spec.md similarity index 100% rename from openspec/changes/update-heartbeat-arrays-v3/specs/db/spec.md rename to openspec/changes/archive/2026-02-03-update-heartbeat-arrays-v3/specs/db/spec.md diff --git a/openspec/changes/update-heartbeat-arrays-v3/specs/kafka/spec.md b/openspec/changes/archive/2026-02-03-update-heartbeat-arrays-v3/specs/kafka/spec.md similarity index 100% rename from openspec/changes/update-heartbeat-arrays-v3/specs/kafka/spec.md rename to openspec/changes/archive/2026-02-03-update-heartbeat-arrays-v3/specs/kafka/spec.md diff --git a/openspec/changes/update-heartbeat-arrays-v3/specs/processor/spec.md b/openspec/changes/archive/2026-02-03-update-heartbeat-arrays-v3/specs/processor/spec.md similarity index 100% rename from openspec/changes/update-heartbeat-arrays-v3/specs/processor/spec.md rename to openspec/changes/archive/2026-02-03-update-heartbeat-arrays-v3/specs/processor/spec.md diff --git a/openspec/changes/archive/2026-02-03-update-heartbeat-arrays-v3/tasks.md b/openspec/changes/archive/2026-02-03-update-heartbeat-arrays-v3/tasks.md new file mode 100644 index 0000000..f3ebfad --- /dev/null +++ b/openspec/changes/archive/2026-02-03-update-heartbeat-arrays-v3/tasks.md @@ -0,0 +1,11 @@ +## 1. Implementation +- [x] 1.1 更新 OpenSpec 增量规范（Kafka/Processor/DB） +- [x] 1.2 数据库脚本与初始化：新增数组列与索引 +- [x] 1.3 Processor：数组字段校验与聚合转换 +- [x] 1.4 DB 写入：扩展批量 insert 列与参数 +- [x] 1.5 测试：新增单元测试覆盖顺序与类型/缺失处理 +- [x] 1.6 文档：更新 producer 与 DB schema + +## 2. Validation +- [x] 2.1 运行单元测试与 lint +- [x] 2.2 在可用 PostgreSQL 环境执行冒烟（含数组列插入） diff --git a/openspec/changes/update-heartbeat-arrays-v3/tasks.md b/openspec/changes/update-heartbeat-arrays-v3/tasks.md deleted file mode 100644 index e78f685..0000000 --- a/openspec/changes/update-heartbeat-arrays-v3/tasks.md +++ /dev/null @@ -1,11 +0,0 @@ -## 1. Implementation -- [ ] 1.1 更新 OpenSpec 增量规范（Kafka/Processor/DB） -- [ ] 1.2 数据库脚本与初始化：新增数组列与索引 -- [ ] 1.3 Processor：数组字段校验与聚合转换 -- [ ] 1.4 DB 写入：扩展批量 insert 列与参数 -- [ ] 1.5 测试：新增单元测试覆盖顺序与类型/缺失处理 -- [ ] 1.6 文档：更新 producer 与 DB schema - -## 2. Validation -- [ ] 2.1 运行单元测试与 lint -- [ ] 2.2 在可用 PostgreSQL 环境执行冒烟（含数组列插入） diff --git a/openspec/specs/db/spec.md b/openspec/specs/db/spec.md index d212bd0..913c9d1 100644 --- a/openspec/specs/db/spec.md +++ b/openspec/specs/db/spec.md @@ -95,3 +95,10 @@ - **THEN** 写入应路由到正确日分区 - **AND** 常见查询（hotel_id + 时间范围）应触发分区裁剪 +## ADDED Requirements +### Requirement: 分区表新增数组列与数组元素索?系统 SHALL ?`heartbeat.heartbeat_events` 中新增用于存储电力与空调子设备的数组列，并为指定数组列提供数组元素级查询索引? +#### Scenario: 新增数组?- **WHEN** 部署或升级数据库结构?- **THEN** 表应包含 elec_address、air_address、voltage、ampere、power、phase、energy、sum_energy、state、model、speed、set_temp、now_temp、solenoid_valve + +#### Scenario: 数组元素索引 +- **WHEN** 需要按 elec_address/air_address/state/model 的数组元素进行查?- **THEN** 数据库应具备 GIN 索引以优化包含类查询 + diff --git a/openspec/specs/kafka/spec.md b/openspec/specs/kafka/spec.md index 1284c11..846ca3b 100644 --- a/openspec/specs/kafka/spec.md +++ b/openspec/specs/kafka/spec.md @@ -92,3 +92,14 @@ Kafka 心跳消息 MUST 包含数据库落库所需的必填字段，并采用 U - **THEN** 建议使用 `hotel_id:device_id` 作为 Kafka message key - **AND** 以提升同设备有序性与消费侧批量聚合效率 +## ADDED Requirements +### Requirement: 心跳消息扩展数组字段 +Kafka 心跳消息 SHALL 支持携带电力与空调子设备的数组字段，以便消费端拆列落库与查询优化? +#### Scenario: 携带 electricity 数组 +- **WHEN** 生产者需要上报电力设备明细时 +- **THEN** 消息可选包?`electricity`（array of object?- **AND** 每个元素包含 address、voltage、ampere、power、phase、energy、sum_energy + +#### Scenario: 携带 air_conditioner 数组 +- **WHEN** 生产者需要上报空调设备明细时 +- **THEN** 消息可选包?`air_conditioner`（array of object?- **AND** 每个元素包含 address、state、model、speed、set_temp、now_temp、solenoid_valve + diff --git a/openspec/specs/processor/spec.md b/openspec/specs/processor/spec.md index e0c1695..fc55291 100644 --- a/openspec/specs/processor/spec.md +++ b/openspec/specs/processor/spec.md @@ -98,3 +98,18 @@ - **THEN** 系统应继续写入同批次其他合法记录 - **AND** 失败记录应按错误日志规则写入 Redis 项目控制台 +## ADDED Requirements +### Requirement: 数组字段聚合为列数组 +系统 SHALL ?`electricity[]` ?`air_conditioner[]` 按原始顺序聚合为数据库写入结构的列数组? +#### Scenario: electricity 聚合 +- **WHEN** 输入包含 `electricity` 数组 +- **THEN** 输出应包?elec_address[]、voltage[]、ampere[]、power[]、phase[]、energy[]、sum_energy[] +- **AND** 各数组下标与输入数组下标一一对应 + +#### Scenario: air_conditioner 聚合 +- **WHEN** 输入包含 `air_conditioner` 数组 +- **THEN** 输出应包?air_address[]、state[]、model[]、speed[]、set_temp[]、now_temp[]、solenoid_valve[] +- **AND** 各数组下标与输入数组下标一一对应 + +#### Scenario: 类型与缺失处?- **WHEN** electricity ?air_conditioner 存在但不是数?- **THEN** 系统应丢弃该消息并记录错?- **WHEN** 数组元素字段缺失或无法转?- **THEN** 系统应保持长度对齐并写入 null +