---
name: bp-architecture-design
description: 提供架构设计原则，包括模块划分、依赖管理、数据架构、接口设计。在系统设计阶段讨论方案概览时使用，或在 code review 中评估架构合理性时使用。
---

# 架构设计

> **使用场景**：`workflow-system-design` skill 在讨论 spec.md **4.1 方案概览** 时加载本 skill。

## 第一性原理

> **架构设计的本质**：在约束条件下，选择最优的 trade-off 来满足业务目标。

---

## 设计前：回顾 spec.md 前三节

在提出架构方案前，**确保已理解**：

| spec.md 章节 | 要回答的问题 |
|-------------|-------------|
| **1. 背景** | 要解决什么问题？现状是怎样的？ |
| **2. 目标 & 非目标** | 成功的标准是什么？什么不做？ |
| **3.1 功能性需求** | 系统需要具备哪些能力？ |
| **3.2 非功能性需求** | 性能、兼容性、可维护性约束？ |

> **如果非功能性需求可以量化，尽量量化**（如 p99 延迟 < 100ms），但不强制要求所有场景都能量化。

---

## 模块划分

**好的划分 = 减少协调成本 + 包含变化。**

### 划分原则

| 原则 | 说明 | 检查点 |
|------|------|--------|
| **按功能域划分** | 围绕业务能力而非技术层 | 相关的代码是否在一起？ |
| **高内聚** | 一起变化的代码放一起 | 修改一个功能要改几个模块？ |
| **低耦合** | 模块间依赖最小化 | 模块能否独立理解和测试？ |
| **明确所有权** | 每个模块有明确的数据和不变量 | 谁负责维护这块数据的一致性？ |

### 边界定义

```cpp
// ✅ 明确的模块边界
namespace compaction {
    // 公开接口
    class CompactionScheduler { ... };
    
    // 内部实现（不暴露）
    namespace internal {
        class CompactionTask { ... };
    }
}
```

---

## 依赖管理

### 依赖方向

**层次结构**（从高到低）：
1. **应用层** - 业务逻辑、用例编排
2. **领域层** - 核心抽象、接口定义
3. **基础设施层** - 具体实现（RocksDB、网络等）

**依赖原则**：高层依赖低层，依赖抽象接口而非具体实现

### 依赖规则

| 规则 | 说明 |
|------|------|
| **单向依赖** | 只能向下依赖，禁止向上依赖 |
| **禁止循环** | A→B→C→A 必须打破 |
| **依赖抽象** | 依赖接口而非具体实现 |

---

## 数据架构

> **数据决策决定正确性和运维复杂度。**

| 决策点 | 需要明确 |
|--------|----------|
| **数据所有权** | 哪个模块是这份数据的 source of truth？ |
| **一致性模型** | 强一致 vs 最终一致？ |
| **Schema 演进** | 向前/向后兼容？回滚方案？ |

---

## 接口设计

> 架构层关注接口原则，详细设计参见 `bp-component-design` 的 4.2.2 节。

| 原则 | 说明 |
|------|------|
| **最小化** | 只暴露必要的接口 |
| **不泄露内部** | 使用专用 DTO |
| **版本兼容** | 接口变更需考虑向后兼容 |

---

## 与其他 Skill 协同

| 场景 | 加载 Skill |
|------|-----------|
| 涉及网络通信、多节点、一致性、故障恢复 | `bp-distributed-systems` |
| 涉及类/接口详细设计 | `bp-component-design`（4.2 节使用） |

---

## 4.1 方案概览 Checklist

在 spec.md 4.1 节，确认以下内容已讨论：

- [ ] **整体思路**：用 1-2 句话描述方案核心
- [ ] **模块划分**：涉及哪些模块？边界在哪？
- [ ] **依赖方向**：模块间的依赖关系
- [ ] **数据流**：数据如何流转？
- [ ] **关键 trade-off**：为什么这样设计？牺牲了什么？

---

## 反模式

| 反模式 | 改进 |
|--------|------|
| 循环依赖 (A→B→C→A) | 引入接口打破循环 |
| 边界模糊（多模块修改同一份数据） | 明确数据所有权 |
| 过度抽象 | 简单优先，按需抽象 |
| Big Ball of Mud | 逐步引入边界 |