跳到主要内容

ADR-002 — 架构文档结构：分层章节 + C4 画图 + 决策独立成档

决策​

FinBayes 工程架构文档按以下方式组织：

  1. 整体章节按分层文档模板（arc42 风格）：9 个部分 / 27 节，从立架 → 业务架构 → 系统全景 → 系统运行 → 部署 → 横切关注 → 质量与验收 → 缺口与决策 → 落地映射。每节回答一个具体疑问，章节长度按内容多寡定不按模板凑齐
  2. 静态视图按 C4 分层：
    • 系统上下文（1 张图）：FinBayes 与生态外部世界
    • 系统内部容器（1 张图）：进程 / 服务划分
    • 容器内组件（5-6 张图）：每个子系统一张
  3. 关键架构决策独立成 ADR 文档：主架构文档只列摘要 + 链接，"为什么这么定不那么定"的推理放在 decisions/ 下的独立 ADR
  4. 业务对象建模借领域驱动设计的实体 / 值对象 / 聚合概念梳理 Fin Object / Watchlist / Session / Judgment Record / 动态画像等业务对象的关系。不引入子域 / 领域事件 / 集成模式等更重型概念

上下文​

当前 projects/finbayes/engineering/architecture.md 存在结构性问题：拓扑图把组件目录画成关系图、业务 / 技术 / 部署三层架构混在一张图、流程流转完全缺失、并发模型不交代、概念边界混乱。需要重写时选定章节组织方式与画图标准。

后果​

收益：

  • 章节正交清晰，读者按需 zoom in 而非线性读全文
  • 图标准化（系统上下文 → 容器 → 组件三层），避免"一张大图说一切"
  • 关键决策推理独立成档，主文档保持简洁可读
  • 业务对象建模让产品到工程的转译清晰

成本：

  • 章节较多（27 节），新接手者需要时间熟悉结构（status.md 的章节追踪表降低此成本）
  • ADR 数量增长，需要 status.md 的 ADR 索引滚动维护
  • 业务建模需要前期投入梳理实体关系，但回报巨大

备选方案​

考虑过未采用：Google Design Doc 风格（轻量但失去章节正交性，长期维护质量下降）/ 4+1 视图分类法（1995 年方法，UML 偏重；现代项目通常借其分类思路不照搬）/ 视角与透视方法（更细但更重，适合长生命周期系统）/ TOGAF（企业级 IT 治理框架，单一产品 overkill）/ Zachman 框架（学术化）/ AWS Well-Architected（云特定 + 是 review checklist 不是文档结构）。

关联​

  • 章节结构详见 status.md 的章节追踪表
  • 写作纪律详见 status.md 的"共识但不必独立成 ADR 的小约定"段