qiaoqichaoandClaude Code
d56c699ce6
按 docs/v2/05-implementation-plan.md §1 候选迁移表与 claude_use/T00 白名单， 从 55e2cdb 抽取 224 个文件（2.48 MB）到独立目录 F:/mini-OpenClaw-v2。 - 排除：凭据(.env/server-deploy.conf/旧DELIVERY.md)、运行数据(xingbang_data 等 4 个 SQLite)、依赖(venv/node_modules 符号链接)、归档(_backup*/test-evidence/ ori_file)、Office 临时文件 - 目标目录独立 git 仓库，初始恢复点；Gitea 远程与分支待 OQ-06 Q2 定案 - 未部署、未启动服务、未调用模型 Co-Authored-By: Claude Code <noreply@anthropic.com>
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/兴邦金租对公智能评审平台技术路径与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 架构文档结构
1. 概览（一屏） 一句话定位 + 分层图 + 本改动在哪个层
2. 分层与模块边界 模块清单：职责 / owner / 依赖方向 / 禁止的反向依赖
3. 数据模型与持久化 表/文件/状态的归属与迁移策略（追加式迁移，禁改历史）
4. 关键流程 主链路 + 失败/恢复路径（任务运行、材料确认、经验发布、模型调用、补件重跑等）
5. 接口与集成点 跨进程契约、外部依赖（业务数据库、模型端点、数据出口和云服务）、版本约束
6. 风险与副作用边界 高危操作清单：触发条件 / 审批点 / 审计点 / 回滚
7. 决策记录（ADR） D1/D2…：决策 + 被否方案 + 影响
8. 验证方式 架构不变量对应的测试/门禁
当前基线见 既有技术路径，新版提案见 v2架构。架构草案入库并标状态；模块统计和调用关系要实际检查，不引用不存在的生成脚本。
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
- 输出到：阶段 ③ 03-detailed-design.md
- 变更矩阵（架构文档随代码同步）：05-implementation.md §3.3
变更：XB-1.0 / 2026-09-28，按兴邦 Next.js + FastAPI 项目事实适配；稳定规则编号保留。