115 lines
2.9 KiB
Markdown
115 lines
2.9 KiB
Markdown
|
# 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
|