6.0 KiB
6.0 KiB
阶段 ② 架构设计（Architecture Design）
定义：确定系统/改动的分层、模块边界、数据流、依赖方向与关键技术决策，让实现者知道"改哪里、往哪加、不能碰什么"。架构文档回答系统为什么这样长；详细设计（阶段 ③）回答每个零件怎么做。 输入：① 的规格文档（验收标准是架构的约束）。 输出：架构文档 + ADR（决策记录）+ 架构图。 进入下一阶段（③ 详细设计）：模块边界与关键决策已定案，无未决阻塞项。
1. 要求（Requirements）
1.1 进入条件
- 规格已过六道完备性门（见 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 高风险审批）。 |
| R-2.7 | 架构图遵守作者契约：用图时按下方 §3.2 的五类图规则（架构/工作流/时序/数据流/生命周期）绘制，只画验证过的事实，不画"可能"的关系。 |
3. 输出规范
3.1 架构文档结构
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
- 输出到：阶段 ③ 03-detailed-design.md
- 变更矩阵（架构文档随代码同步）：05-implementation.md §3.3