# OpenSpec 规范文档 (OpenSpec Documentation)

此目录包含 BLS OldRCU Heartbeat Backend 项目的完整 OpenSpec 规范文档。

## 📋 文档导览

### 入门文档

1. **[OPENSPEC.md](./OPENSPEC.md)** - 主规范文档
   - 项目简介和核心功能
   - 总体架构设计
   - 快速开始命令
   - 适合**任何人**开始这里

### 深度设计文档

2. **[architecture.md](./architecture.md)** - 架构详解
   - 系统架构图
   - 消费者自动伸缩机制
   - 双层去重策略
   - 适合**架构师**和**系统设计讨论**

3. **[validation.md](./validation.md)** - 数据验证规范
   - 消息字段定义
   - 字段验证规则
   - Parser 实现
   - 适合**数据质量**和**验证相关**

4. **[deduplication.md](./deduplication.md)** - 去重策略规范
   - 5秒缓冲去重
   - 30秒写入冷却期
   - 去重命中率估算
   - 适合**性能优化**和**数据去重**

5. **[kafka.md](./kafka.md)** - Kafka 处理规范
   - 消费者配置
   - 分区感知伸缩
   - 偏移量管理
   - 适合 **Kafka **开发者**和**运维人员**

6. **[database.md](./database.md)** - 数据库规范
   - PostgreSQL 连接配置
   - Upsert 操作和类型转换
   - 批量处理实现
   - 适合**数据库开发者**和**DBA**

7. **[testing.md](./testing.md)** - 测试规范
   - 单元测试覆盖
   - Parser 和 Buffer 测试
   - 集成测试
   - 适合 **QA **和**测试工程师**

8. **[deployment.md](./deployment.md)** - 部署与运维规范
   - 环境配置
   - 启动流程
   - 监控和告警
   - 故障排查
   - 适合**运维工程师**和**SRE**

9. **[openspec-proposal.md](./openspec-proposal.md)** - OpenSpec 提案
   - 项目需求
   - 技术选型
   - 架构决策
   - 风险评估
   - 适合**项目管理**

10. **[openspec-apply.md](./openspec-apply.md)** - OpenSpec 应用规范
    - 设计原则
    - 代码组织和规范
    - 性能规范
    - 安全规范
    - 适合**所有开发者**

## 🚀 快速使用场景

### 场景 1: 新开发者入门
1. 阅读 OPENSPEC.md （5 分钟）
2. 运行快速开始命令 （15 分钟）
3. 浏览 architecture.md （30 分钟）

### 场景 2: 修改代码
- 修改 Parser → 读 validation.md
- 修改 Buffer → 读 deduplication.md
- 修改 Kafka → 读 kafka.md
- 修改 Database → 读 database.md

### 场景 3: 线上故障诊断
- 消费速度慢 → deployment.md 故障排查
- 消息验证失败 → validation.md
- 缓冲堆积 → deduplication.md
- DB 连接失败 → database.md

## 📊 文档统计

| 指标 | 值 |
|------|-----|
| 总文档数 | 11 个 |
| 总字数 | 50,000+ |
| 代码示例 | 200+ |
| 更新日期 | 2026-03-11 |

## ✅ 合规检查

- [x] OpenSpec 提案完整
- [x] OpenSpec 应用规范完整
- [x] 所有模块规范已生成
- [x] 测试规范已覆盖
- [x] 部署规范已说明
- [x] 文档导航完整

---

**维护者**: BLS OldRCU Heartbeat Team  
**上次更新**: 2026-03-11