91 lines
6.0 KiB
Markdown
91 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/兴邦金租对公智能评审平台技术路径与AgentLoop说明-v1.0.md` 及已检查代码）能对上
|
||
- [ ] 风险与副作用边界已标注：哪些是高危操作（生产数据、经验发布、外发请求）、默认拒绝还是需审批
|
||
- [ ] 架构不变量可被机器验证的部分列出（对应 lint/architecture test/契约测试）
|
||
|
||
---
|
||
|
||
## 2. 规则（Rules）
|
||
|
||
| 编号 | 规则 |
|
||
|---|---|
|
||
| R-2.1 | **依赖单向**：src页面/组件 → Next同源代理 → backend/api → backend/services → 受控工具/存储/模型；service不依赖UI。业务模型通过冻结快照和工具白名单访问事实，不能绕过授权直连数据库。 |
|
||
| R-2.2 | **唯一owner**：既有业务模型以backend/contracts/project_assistant.py及实际请求模型为基线；新契约明确唯一Pydantic定义和前端同步方式，不在多处手工维护冲突语义。自动生成链未实现前不能宣称已防漂移。 |
|
||
| R-2.3 | **架构不变量写入文档且可验证**：能用测试/静态检查强制的（模块边界、依赖方向、迁移追加、白名单），不许只写文档；验证不了的规则不写进"不可违背"清单。 |
|
||
| R-2.4 | **决策要留痕**：架构层面的每个取舍写成 ADR（背景/决策/被否方案/影响），不搞口头决定。被否方案是决策记录的一部分。 |
|
||
| R-2.5 | **分层不做多余抽象**：无第二调用方的接口不抽象；不为想象中的灵活性提前配置化（Karpathy 准则：最小代码解决当前问题）。 |
|
||
| R-2.6 | **边界即安全**：API、SQL数据卡、文件、模型出口、经验发布和部署都有校验/权限/审计；生产数据和外发依任务授权或已批准策略执行。 |
|
||
| R-2.7 | **架构图遵守作者契约**：用图时按下方 §3.2 的五类图规则（架构/工作流/时序/数据流/生命周期）绘制，只画验证过的事实，不画"可能"的关系。 |
|
||
|
||
---
|
||
|
||
## 3. 输出规范
|
||
|
||
### 3.1 架构文档结构
|
||
|
||
```text
|
||
1. 概览（一屏） 一句话定位 + 分层图 + 本改动在哪个层
|
||
2. 分层与模块边界 模块清单：职责 / owner / 依赖方向 / 禁止的反向依赖
|
||
3. 数据模型与持久化 表/文件/状态的归属与迁移策略（追加式迁移，禁改历史）
|
||
4. 关键流程 主链路 + 失败/恢复路径（任务运行、材料确认、经验发布、模型调用、补件重跑等）
|
||
5. 接口与集成点 跨进程契约、外部依赖（业务数据库、模型端点、数据出口和云服务）、版本约束
|
||
6. 风险与副作用边界 高危操作清单：触发条件 / 审批点 / 审计点 / 回滚
|
||
7. 决策记录（ADR） D1/D2…：决策 + 被否方案 + 影响
|
||
8. 验证方式 架构不变量对应的测试/门禁
|
||
```
|
||
|
||
> 当前基线见 [既有技术路径](../兴邦金租对公智能评审平台技术路径与AgentLoop说明-v1.0.md)，新版提案见 [v2架构](../v2/02-architecture.md)。架构草案入库并标状态；模块统计和调用关系要实际检查，不引用不存在的生成脚本。
|
||
|
||
### 3.2 架构图规范（五类，摘要）
|
||
|
||
| 图类型 | 结构规则 |
|
||
|---|---|
|
||
| Architecture | 一条从左到右主干 + 短垂直分支；6–12 个主组件；只按真实归属/信任/进程边界分组；外部角色画在系统边界外 |
|
||
| Workflow | 泳道=职责/阶段，列=推进；happy path 单调；重试/异常走主走廊外 |
|
||
| Sequence | 参与者按会话角色排序；消息拥有纵向顺序 |
|
||
| Dataflow | 阶段=转换/保管；行=并行流；只标注数据契约与跨边界移动 |
|
||
| Lifecycle | 主相位列 0..4；可恢复失败必须有真实回迁转换 |
|
||
|
||
> 构图以 Mermaid / 文本图为主。现状图只画代码证实的事实；目标图单独标“候选/未实现”，不能混画。验证结构和可读性，未实际渲染时如实说明。
|
||
|
||
### 3.3 交付物清单
|
||
- 架构文档（含分层/边界/数据流/风险）
|
||
- ADR（每个决策一个记录，可内嵌架构文档或独立 `docs/adr/`）
|
||
- 架构图（适用时）
|
||
- 架构不变量对应的机器验证清单（测试/静态检查名）
|
||
|
||
---
|
||
|
||
## 4. 轻量路径（小改动）
|
||
|
||
- 单模块内、无跨进程/持久化/外部的改动：架构要求并入详细设计开头一小节（边界 + owner + 依赖方向），不单独成文。
|
||
- 触碰 `backend/contracts/`、公开API/事件、数据迁移、权限或模型数据出口时，必须走完整架构设计。
|
||
|
||
---
|
||
|
||
## 5. 相关文档
|
||
|
||
- 输入：阶段 ① [01-requirement.md](01-requirement.md)
|
||
- 输出到：阶段 ③ [03-detailed-design.md](03-detailed-design.md)
|
||
- 变更矩阵（架构文档随代码同步）：[05-implementation.md](05-implementation.md) §3.3
|
||
|
||
变更：XB-1.0 / 2026-09-28，按兴邦 Next.js + FastAPI 项目事实适配；稳定规则编号保留。
|