bp-architecture-design

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），但不强制要求所有场景都能量化。

---

模块划分

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

划分原则

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

边界定义

// ✅ 明确的模块边界
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	逐步引入边界