XuJiacheng
e45d14b720
- 新增 HeartbeatBuffer 类，用于收集和去重 Kafka 心跳消息，并定期将数据刷新到数据库。 - 新增 HeartbeatDbManager 类，负责与 PostgreSQL 数据库的交互，支持批量 upsert 操作。 - 新增配置文件 config.js，支持从环境变量加载配置。 - 新增 Kafka 消费者模块，支持从 Kafka 中消费心跳消息。 - 新增 Redis 集成模块，支持将日志和心跳信息推送到 Redis。 - 新增心跳消息解析器，负责解析 Kafka 消息并提取心跳字段。 - 新增日志记录工具，支持不同级别的日志输出。 - 新增指标收集器，跟踪 Kafka 消息处理和数据库操作的指标。 - 新增单元测试，覆盖 HeartbeatBuffer 和 HeartbeatDbManager 的主要功能。 - 新增数据库表结构 SQL 文件，定义 room_status_moment_g5 表的结构。 - 配置 Vite 构建工具，支持 Node.js 环境的构建。
3.0 KiB
3.0 KiB
OpenSpec 应用规范 (OpenSpec Applied Specification)
1. 规范概述
本文档记录 BLS OldRCU Heartbeat Backend 的详细技术规范，涵盖系统设计、实现标准、最佳实践和质量保证指标。
2. 设计原则
2.1 核心原则
P1. 性能优先 (Performance First)
- 热路径优化（Parser 手写验证器）
- 批量处理（Kafka 批量消费、DB 批量 Upsert）
- 异步非阻塞（async/await，Event Loop 友好）
P2. 可靠性为主 (Reliability Paramount)
- 时间序列保护（WHERE ts_ms 条件）
- 冗余去重（5秒 + 30秒双层）
- 失败重试（缓冲重入队）
P3. 可维护性设计 (Maintainability)
- 清晰的模块划分
- 完整的单元测试覆盖
- 详细的 OpenSpec 文档
P4. 成本优化 (Cost Efficiency)
- 最小化 DB 写入频率
- 内存占用控制
- 开源依赖优先
3. 实现标准
3.1 代码组织标准
// 文件头必须包含用途注释
/**
* HeartbeatParser - Kafka 消息验证与解析
*
* 职责:
* - JSON 格式验证
* - 字段类型检查（ts_ms, hotel_id, room_id, device_id）
* - 返回规范化对象或 null
*/
export function parseHeartbeat(rawMessage) {
// ... implementation
}
3.2 命名规范
// 常量：UPPER_SNAKE_CASE
const MAX_BUFFER_SIZE = 5000;
const COOLDOWN_MS = 30000;
// 函数：camelCase，动词开头
const parseHeartbeat = (raw) => {};
const upsertBatch = (records) => {};
// 类：PascalCase
class HeartbeatBuffer {}
// 私有方法：_camelCase
_getCooldownDelayMs() {}
3.3 错误处理标准
// ✓ 推荐：使用 try-catch 包装 async 操作
try {
const result = await pool.query(sql, params);
} catch (err) {
logger.error(`Query failed: ${err.message}`, err);
throw err;
}
// ✓ 推荐：验证失败返回 null
function parseHeartbeat(raw) {
if (validation_fails) {
return null;
}
}
4. 性能规范
4.1 关键路径性能要求
// Parser 解析单条消息 < 1ms
// Buffer 添加单条记录 < 0.5ms
// Buffer 刷新 5000 条记录 < 100ms
4.2 吞吐量目标
理论最大: 30,000 msg/s
当前建议监控: 消费速率应 >= 25K msg/s
5. 安全规范
5.1 SQL 注入防护
// ✓ 使用参数化查询
const result = await pool.query(query, [userInput1, userInput2]);
// ✗ 字符串拼接（危险！）
const result = await pool.query(`INSERT VALUES ('${userInput1}')`);
5.2 环境变量管理
// ✓ 使用 dotenv
const dbPassword = process.env.POSTGRES_PASSWORD_G5;
// ✗ 硬编码敏感信息
const dbPassword = "password123";
6. 可测试性规范
6.1 单元可测性设计
// ✓ 纯函数，易于测试
export function parseHeartbeat(raw) {
// 无副作用
return parsed || null;
}
7. 部署规范
7.1 构建标准
npm ci # 精确依赖安装
npm run test # 单元测试
npm run build # Vite 构建
文档版本: 1.0.0
最后更新: 2026-03-11