openspec/project.md

# BLS RCU Action Server

## Overview
Backend service for processing RCU action events from Kafka, parsing them, and storing them in PostgreSQL. Includes error handling via Redis and heartbeat monitoring.

## Architecture
- **Input**: Kafka Topic (`blwlog4Nodejs-rcu-action-topic` or configured via env)
- **Processing**: Node.js Service
  - **Consumer**: `kafka-node` consumer group
  - **Parser**: Parses JSON messages, handles UDP raw data decoding
  - **Database**: PostgreSQL (Batch insert)
  - **Error Handling**: Redis List (`error_queue`) for failed messages + Retry mechanism
- **Output**: PostgreSQL Table (`rcu_action_events`)

## Features
- **Loop Name Enrichment**: Enriches event data with `loop_name` by matching `device_id` and `dev_addr` against metadata cached from `temporary_project` tables (refreshed daily).

## Configuration (Environment Variables)
The project is configured via `.env`. Key variables:
- **Kafka**: `KAFKA_BROKERS`, `KAFKA_TOPIC`, `KAFKA_SASL_USERNAME`, `KAFKA_SASL_PASSWORD`
- **Database**: `DB_HOST`, `DB_PORT`, `DB_USER`, `DB_PASSWORD`, `DB_DATABASE`, `DB_SSL`
- **Redis**: `REDIS_HOST`, `REDIS_PORT`, `REDIS_PASSWORD`

## Development Constraints
- **Schema**: Must strictly follow `docs/readme.md`.
- **Database**: Do not alter Schema Name (`rcu_action`) or Table Name (`rcu_action_events`) unless explicitly requested.
feat: 初始化后端服务基础架构与核心组件 - 添加项目基础结构，包括 .gitignore、package.json、Docker 配置和环境变量示例 - 实现核心模块：Kafka 消费者、PostgreSQL 数据库管理器、Redis 客户端与错误队列 - 添加工具类：日志记录器、指标收集器、UUID 生成器 - 实现数据处理器，支持 0x36 上报和 0x0F 命令的解析与存储 - 添加数据库初始化脚本和分区管理，支持按时间范围分区 - 引入 Zod 数据验证和 Vitest 单元测试框架 - 提供完整的项目文档，包括数据库设计、Kafka 格式规范和 Redis 集成协议 2026-01-30 11:05:00 +08:00			`# BLS RCU Action Server`

			`## Overview`
			`Backend service for processing RCU action events from Kafka, parsing them, and storing them in PostgreSQL. Includes error handling via Redis and heartbeat monitoring.`

			`## Architecture`
			- Input: Kafka Topic (`blwlog4Nodejs-rcu-action-topic` or configured via env)
			`- Processing: Node.js Service`
			- Consumer: `kafka-node` consumer group
			`- Parser: Parses JSON messages, handles UDP raw data decoding`
			`- Database: PostgreSQL (Batch insert)`
			- Error Handling: Redis List (`error_queue`) for failed messages + Retry mechanism
			- Output: PostgreSQL Table (`rcu_action_events`)

feat: 添加回路名称字段并实现元数据缓存查询在 RCU 事件处理中新增回路名称（loop_name）字段，用于标识具体设备回路。 - 在 rcu_action_events 表中添加 loop_name 字段 - 新增项目元数据缓存模块，每日从 temporary_project 表刷新房间与回路信息 - 处理消息时，根据 device_id、dev_addr 等字段查询缓存获取回路名称 - 若缓存未命中，则根据设备类型规则生成兜底名称 - 更新环境变量、文档及测试用例以适配新功能 2026-02-02 19:43:49 +08:00			`## Features`
			- Loop Name Enrichment: Enriches event data with `loop_name` by matching `device_id` and `dev_addr` against metadata cached from `temporary_project` tables (refreshed daily).

feat: 初始化后端服务基础架构与核心组件 - 添加项目基础结构，包括 .gitignore、package.json、Docker 配置和环境变量示例 - 实现核心模块：Kafka 消费者、PostgreSQL 数据库管理器、Redis 客户端与错误队列 - 添加工具类：日志记录器、指标收集器、UUID 生成器 - 实现数据处理器，支持 0x36 上报和 0x0F 命令的解析与存储 - 添加数据库初始化脚本和分区管理，支持按时间范围分区 - 引入 Zod 数据验证和 Vitest 单元测试框架 - 提供完整的项目文档，包括数据库设计、Kafka 格式规范和 Redis 集成协议 2026-01-30 11:05:00 +08:00			`## Configuration (Environment Variables)`
			The project is configured via `.env`. Key variables:
			- Kafka: `KAFKA_BROKERS`, `KAFKA_TOPIC`, `KAFKA_SASL_USERNAME`, `KAFKA_SASL_PASSWORD`
			- Database: `DB_HOST`, `DB_PORT`, `DB_USER`, `DB_PASSWORD`, `DB_DATABASE`, `DB_SSL`
			- Redis: `REDIS_HOST`, `REDIS_PORT`, `REDIS_PASSWORD`

			`## Development Constraints`
			- Schema: Must strictly follow `docs/readme.md`.
			- Database: Do not alter Schema Name (`rcu_action`) or Table Name (`rcu_action_events`) unless explicitly requested.