loongcollector / workflows

---
description: Writing Design Document
globs: 
alwaysApply: false
---
# 设计文档编写规范

## 1. 需求背景 / 问题说明

### 1.1 背景与痛点
- 描述当前系统 / 业务的现状与不足。
- 列举触发本次设计的具体场景、业务指标或故障案例。

### 1.2 影响范围
- 受影响的模块、微服务、接口、数据存储、第三方依赖。
- 对性能、可靠性、成本、可维护性的潜在影响。
- 向前 / 向后兼容性分析（是否影响现有 API、数据格式等）。

### 1.3 约束条件
- 必须遵守的合规 / 安全 / 性能 / 资源限制。
- 外部系统或基础设施的依赖与限制。

---

## 2. 设计目标

### 2.1 功能目标
- 按优先级列出 Must / Should / Could 的核心能力。

### 2.2 非功能目标
- 性能（吞吐、延迟、并发量、资源占用）。
- 可扩展性、可维护性、可测试性、可观测性。
- 可靠性（容错、HA、降级、回滚策略）。

### 2.3 约束目标
- 向下兼容、接口稳定性。
- 安全与合规要求。

---

## 3. 技术设计

### 3.1 整体架构图
- 使用 Mermaid 或 PlantUML 绘制高层组件图，标注数据流和控制流。

### 3.2 详细流程图
- 展示关键业务流程、异常流程、重试 / 补偿流程，并标注时序与触发条件。

### 3.3 线程 / 并发模型
- 线程生命周期、线程间通信（锁、条件变量、队列、Actor 模式等）。
- 典型时序图展示并发交互。

### 3.4 核心类与数据结构

```cpp
// DataBuffer.hpp
class DataBuffer final {
public:
    explicit DataBuffer(size_t capacity);
    void push(LogRecord&& record);          // 线程安全
    std::vector<LogRecord> flush();         // 批量读取并清空
private:
    mutable std::mutex _mutex;
    std::vector<LogRecord> _buffer;
    const size_t _capacity;
};
```

- 类图说明主要类、接口、继承 / 组合关系。
- 关键数据结构字段含义、生命周期、线程安全策略。

### 3.5 关键算法或协议
- 发布订阅、负载均衡、重试退避等算法伪代码或流程。
- 状态机 / 协议状态转移图。
### 3.6 错误处理与恢复
- 错误分类、异常栈、重试策略、降级方案。
- 监控指标、告警触发条件与等级。

### 3.7 部署与运维考量
- 配置项、热更新机制、灰度与回滚策略。
- 依赖的 CI / CD、容器、Service Mesh、Kubernetes 资源等。

---

## 4. 单元测试

### 4.1 测试范围与目标
- 覆盖核心逻辑、边界条件、并发场景、异常路径。

### 4.2 测试环境与工具
- Google Test / Mock 版本，必要的第三方替身（Stub / Fake）。

### 4.3 测试场景与用例一览

| Case ID | 场景描述          | 输入                      | 预期输出 / 行为                               | Mock 依赖         |
|---------|-----------------|---------------------------|----------------------------------------------|-------------------|
| TC-01   | 正常推送单条日志 | 单条合法 LogRecord        | 返回 SUCCESS，缓冲区大小 +1                  | 无                |
| TC-02   | 缓冲区已满      | capacity=N 已填满         | 抛出 BufferOverflowException                 | 无                |
| TC-03   | 并发 push       | 多线程同时 push           | 无数据丢失，顺序或最终一致性符合设计        | MutexMock         |
| TC-04   | flush 清空      | 存在 M 条数据后调用 flush | 返回 M 条数据，缓冲区大小 =0                 | TimeProviderMock  |

### 4.4 边界与异常测试
- 空输入、非法输入、极端容量、网络 / 磁盘故障注入。

### 4.5 性能基准测试（可选）
- 吞吐、延迟、CPU / Memory Profile；对比旧实现或基线版本。

---

## 注意事项

- **禁止**在设计文档中包含工作量估算、人员排期、里程碑、甘特图等项目管理信息。
- 代码示例遵循团队 C++ 代码规范。
- 测试用例命名格式：`<模块>_<功能>_<序号>`，方便持续集成统计覆盖率。 

More agent context in alibaba/loongcollector

35 other files this repository gives its agents.