89 lines
6.0 KiB
Markdown
89 lines
6.0 KiB
Markdown
# 阶段 ② 架构设计（Architecture Design）
|
||
|
||
> **定义**：确定系统/改动的分层、模块边界、数据流、依赖方向与关键技术决策，让实现者知道"改哪里、往哪加、不能碰什么"。架构文档回答系统**为什么这样长**；详细设计（阶段 ③）回答**每个零件怎么做**。
|
||
> **输入**：① 的规格文档（验收标准是架构的约束）。
|
||
> **输出**：架构文档 + ADR（决策记录）+ 架构图。
|
||
> **进入下一阶段（③ 详细设计）**：模块边界与关键决策已定案，无未决阻塞项。
|
||
|
||
---
|
||
|
||
## 1. 要求（Requirements）
|
||
|
||
### 1.1 进入条件
|
||
- 规格已过六道完备性门（见 [01-requirement.md](01-requirement.md) §3.2）。
|
||
- 涉及跨模块/跨进程/硬件/网关/持久化的改动，必须走完整架构设计；纯单文件小改可走轻量路径。
|
||
|
||
### 1.2 完成条件（DoD）
|
||
- [ ] 分层与依赖方向明确：数据只能往哪个方向流、禁止哪些反向依赖
|
||
- [ ] 每个模块有唯一 owner 与清晰职责；没有"第二份 owner"（同一概念不复制两处实现）
|
||
- [ ] 关键决策以 ADR 形式记录（结论 + 被否方案 + 理由），决策号稳定（如 D1/D2）
|
||
- [ ] 数据流/主链路（含失败路径）有图或文字描述，与现有架构基线（`docs/architecture/architecture-overview.md` 分层图）能对上
|
||
- [ ] 风险与副作用边界已标注：哪些是高危操作（生产数据、硬件写、外发请求）、默认拒绝还是需审批
|
||
- [ ] 架构不变量可被机器验证的部分列出（对应 lint/architecture test/契约测试）
|
||
|
||
---
|
||
|
||
## 2. 规则（Rules）
|
||
|
||
| 编号 | 规则 |
|
||
|---|---|
|
||
| R-2.1 | **依赖单向**：renderer → preload → IPC handler → domain service → state / Pi runtime；service 不依赖 UI 层与宿主；禁止跨层绕行。本仓现状：`src/main/`（Electron 宿主：index/preload/app-menu/macos/update/host）· `packages/agent-sdk/`（服务主体，零 electron 导入）· `packages/web-ui/`（renderer SPA）· `packages/api/`（dk-api 契约）。 |
|
||
| R-2.2 | **唯一 owner**：跨进程/跨模块的类型只在共享层定义一次，其余侧只 `import type`；禁止本地镜像同一契约。 |
|
||
| R-2.3 | **架构不变量写入文档且可验证**：能用测试/静态检查强制的（模块边界、依赖方向、迁移追加、白名单），不许只写文档；验证不了的规则不写进"不可违背"清单。 |
|
||
| R-2.4 | **决策要留痕**：架构层面的每个取舍写成 ADR（背景/决策/被否方案/影响），不搞口头决定。被否方案是决策记录的一部分。 |
|
||
| R-2.5 | **分层不做多余抽象**：无第二调用方的接口不抽象；不为想象中的灵活性提前配置化（Karpathy 准则：最小代码解决当前问题）。 |
|
||
| R-2.6 | **边界即安全**：跨进程 IPC、硬件写、外发请求、文件写入都有明确边界与校验点；高危路径默认拒绝或显式审批（见 [07-delivery.md](07-delivery.md) 高风险审批）。 |
|
||
| R-2.7 | **架构图遵守作者契约**：用图时按下方 §3.2 的五类图规则（架构/工作流/时序/数据流/生命周期）绘制，只画验证过的事实，不画"可能"的关系。 |
|
||
|
||
---
|
||
|
||
## 3. 输出规范
|
||
|
||
### 3.1 架构文档结构
|
||
|
||
```text
|
||
1. 概览（一屏） 一句话定位 + 分层图 + 本改动在哪个层
|
||
2. 分层与模块边界 模块清单：职责 / owner / 依赖方向 / 禁止的反向依赖
|
||
3. 数据模型与持久化 表/文件/状态的归属与迁移策略（追加式迁移，禁改历史）
|
||
4. 关键流程 主链路 + 失败/恢复路径（任务运行、硬件发现、网关、升级等）
|
||
5. 接口与集成点 跨进程契约、外部依赖（硬件协议、网关、云服务）、版本约束
|
||
6. 风险与副作用边界 高危操作清单：触发条件 / 审批点 / 审计点 / 回滚
|
||
7. 决策记录（ADR） D1/D2…：决策 + 被否方案 + 影响
|
||
8. 验证方式 架构不变量对应的测试/门禁
|
||
```
|
||
|
||
> 本仓已有基线：`docs/architecture/architecture-overview.md`（分层总览）+ `docs/architecture/codemap.md`（模块地图，头部统计由 `scripts/repo-stats.mjs` 生成）。新架构文档放在 `docs/architecture/`（入库基线）或 `docs/plans/`（本地草稿，不入库，见 `.gitignore`），并保持与基线一致；基线变更要同步。
|
||
|
||
### 3.2 架构图规范（五类，摘要）
|
||
|
||
| 图类型 | 结构规则 |
|
||
|---|---|
|
||
| Architecture | 一条从左到右主干 + 短垂直分支；6–12 个主组件；只按真实归属/信任/进程边界分组；外部角色画在系统边界外 |
|
||
| Workflow | 泳道=职责/阶段，列=推进；happy path 单调；重试/异常走主走廊外 |
|
||
| Sequence | 参与者按会话角色排序；消息拥有纵向顺序 |
|
||
| Dataflow | 阶段=转换/保管；行=并行流；只标注数据契约与跨边界移动 |
|
||
| Lifecycle | 主相位列 0..4；可恢复失败必须有真实回迁转换 |
|
||
|
||
> 构图约定：图以 Mermaid / 文本图为主（见 `docs/architecture/flows.md`、`docs/release-process.md` 既有图例），只画代码检查证实的事实，不画"可能"的关系，并保证 lint/渲染校验可通过。
|
||
|
||
### 3.3 交付物清单
|
||
- 架构文档（含分层/边界/数据流/风险）
|
||
- ADR（每个决策一个记录，可内嵌架构文档或独立 `docs/adr/`）
|
||
- 架构图（适用时）
|
||
- 架构不变量对应的机器验证清单（测试/静态检查名）
|
||
|
||
---
|
||
|
||
## 4. 轻量路径（小改动）
|
||
|
||
- 单模块内、无跨进程/持久化/外部的改动：架构要求并入详细设计开头一小节（边界 + owner + 依赖方向），不单独成文。
|
||
- 改动触碰 `packages/api/src/contracts.ts`（跨进程契约）、IPC、迁移、安全边界时，**必须**走完整架构设计。
|
||
|
||
---
|
||
|
||
## 5. 相关文档
|
||
|
||
- 输入：阶段 ① [01-requirement.md](01-requirement.md)
|
||
- 输出到：阶段 ③ [03-detailed-design.md](03-detailed-design.md)
|
||
- 变更矩阵（架构文档随代码同步）：[05-implementation.md](05-implementation.md) §3.3
|