Phase 2：架构设计与模块拆分

需求清楚了，接下来要回答：系统由哪些部分组成？它们之间怎么通信？

好的架构不是画一张好看的图，而是让每个人都能独立理解一块东西，改起来不牵一发而动全身。

---

一、这个阶段要做什么

基于 PRD，设计系统整体结构。产出：

• 架构图
• 模块边界
• 接口契约
• 数据模型草案

---

二、几条实用的设计原则

单一职责

一个模块只做一件事。如果描述一个模块需要用"和"，那它可能该拆成两个。

依赖向内

上层可以调用下层，下层不要回调上层。这样底层改动不会影响上层。

可替换

今天用 PostgreSQL，明天想换 SQLite，应该只改一层。

可测试

每个模块能单独验证，不依赖其他模块跑起来。

可观察

关键操作要有日志、有追踪。出了问题能定位。

---

三、一个常见的分层

text
用户界面层      ← Web / App / CLI / Bot
API 网关层      ← 路由、认证、限流、日志
编排层          ← 任务分解、流程控制
业务服务层      ← 核心业务逻辑
工具/集成层     ← 外部 API、数据库、文件系统
数据层          ← 持久化存储、缓存、向量库

小项目不需要六层，合并几层没问题。但分层思想要有。

---

四、给 AI 的输入

hljs markdown
## 项目背景
[粘贴 PRD.md]

## 需要设计的架构
- 用户如何交互？
- 需要接哪些外部系统？
- 数据怎么存？
- 有没有 AI 模型调用？
- 有没有定时任务？

## 输出要求
1. 系统架构图（文字描述即可）
2. 模块列表和职责
3. 模块间接口契约
4. 数据模型草案
5. 潜在风险

---

五、AI 应该产出什么

ARCHITECTURE.md

不需要很复杂，但要有：

• 架构图
• 每层职责
• 一个典型数据流示例
• 核心接口契约
• 模块依赖关系

接口契约

先把核心 API 的输入输出定下来。比如：

hljs typescript
// POST /api/run
interface RunRequest {
  message: string;
  sessionId: string;
}

interface RunResponse {
  reply: string;
  actions: Action[];
}

数据模型草案

列出核心实体和字段，不用最终 Schema。先让各方对"有什么数据"达成一致。

---

六、模块边界怎么判断

对每个模块，问三个问题：

1. 它做什么？（一句话）
2. 它依赖谁？
3. 谁依赖它？

如果答不清楚，边界就还需要调整。

---

七、不同人关心什么

如果是一个人做所有角色，那就分别戴上这些帽子检查一遍。

---

八、什么时候算做完了

• 架构图清晰，模块边界明确
• 每个模块能用一句话描述
• 核心 API 的输入输出已定义
• 数据模型覆盖核心实体
• 主要技术风险已识别

---

九、几个常见错误

模块过大

• 表现：一个文件/服务做了五件事
• 修正：继续拆

循环依赖

• 表现：A 调 B，B 又调 A
• 修正：引入抽象层或重新划分职责

架构过度

• 表现：个人项目用上微服务
• 修正：按项目规模选择

不留替换点

• 表现：LLM 调用散落在各处
• 修正：封装统一 Provider

---

十、输出文件

text
/docs/
├── ARCHITECTURE.md
├── api-contract.md
└── data-model.md

---

十一、下一步

架构确定后，选择具体技术栈。

→ Phase 3 技术选型与工具链