0011. 章节内部组织模式¶

Reference · 速查

背景¶

ADR-0006 定了章节归属规则（哪类内容放哪章），但没定章节内部如何组织子页。结果是各章按不同模式组织：

章	组织模式
`lakehouse/`	5 子组：核心协议 / 运维机制 / 扩展前沿 / 系统实现 / 横向对比（主题轴 + 产品轴混合）
`retrieval/`	6 子组：基础概念 / 多模专题 / ANN 索引 / 检索流水线 / 产品实现 / 横向对比（主题轴 + 产品轴）
`ai-workloads/`	3 子组：应用模式 / 应用-Runtime 桥 / 工程纪律（抽象层轴）
`ml-infra/`	3 子组：数据与特征 / 模型生命周期 / 训练基础设施（生命周期轴）
`ops/`	6 子组：日常运维 / 容量目标 / 成本效益 / 安全治理 / DR / 反模式（关注点轴）
`catalog/`	4 子组：协议层 / OSS 实现层 / 商业托管层 / 存量历史（层级轴）
`pipelines/`	4 子组：架构总览 / 入湖模式 / 模态管线 / 韧性 / 编排（职能轴）
`bi-workloads/`	平铺 6 页（无子组）
`query-engines/`	5 子组：通用原理 / 纯查询 / 通用框架 / MPP OLAP / 接入协议（类型轴）
`unified/`	3 页平铺（跨章 orchestrator · 极小章节）
`scenarios/`	3 子组：BI/分析 / RAG/AI / 流/实时 / ML/推荐（业务领域轴）
`cases/`	3 子组：商业产品平台 / 大厂内部数据平台 / 业务系统案例（样本类型轴 · S32 修订）

读者反馈："为什么 ai-workloads 是 3 层而 retrieval 是 6 组？" —— 误以为是治理失败。

决策¶

不强求章节统一组织模式。允许每章按其领域内在结构组织 · 但要求 index.md 显式列出本章子组与定位 · 并指向 docs/references// 的外部权威背书。

章节 index.md 必含声明¶

每章 index.md 顶部必须有一段直接列子组 + 定位（不写抽象"轴名"——读者不需要先理解"轴"概念，直接看子组列表更受益）：

!!! info "本章组织"
    本章按 N 个子组：

    - **子组 A**：page1 / page2 —— 一句话定位
    - **子组 B**：page3 / page4 / page5 —— 一句话定位
    ...

    外部参考：[docs/references/<chapter>/](../references/<chapter>/index.md) 的论文 / 官方文档 / 综述。

不再要求"X 轴"标签¶

[ADR-0011 v1] 原要求标"抽象层轴 / 生命周期轴 / 主题+产品轴"等抽象标签 · 实践证明：

多数章节是多维度组合而非单轴 · 强行单标签是简化失真
读者要的是知道有哪些子组 + 子组定位 · 不是先理解"轴"概念
"主题 + 产品轴"这类妥协标签反而增加认知负担

修订为直接列子组 + 一句话定位。

自检触发¶

每季度自检（contributing.md §更新节奏）顺手检查： - 每章 index.md 仍有"本章组织"声明 - 新增子页归属到既有某子组（或显式 PR 加新子组） - 子组数量合理（3-6 个，超过 8 个考虑拆章） - references// 仍指向当前权威

依据¶

为什么不强求统一¶

不同领域有不同内在结构——LLM 应用按抽象层（call → bridge → discipline），ML 平台按生命周期，运维按关注点，强行统一会破坏自然分类
类比：操作系统教科书按"进程 / 内存 / 文件 / IO"组织，编译器教科书按"词法 / 语法 / 语义 / 优化"组织——没人要求两本书结构一致
ADR-0006 已强力约束章节归属（横向 MECE），章节内部允许灵活是合理代价

为什么显式声明轴¶

读者打开新章时立刻知道这章按什么找
防止治理漂移（写新页时容易加到"不属于任何子组"，必须先看声明）
季度自检有抓手

为什么不写代码强制¶

章节 index 写法多样，正则 / linter 难精确判断
自检 + 人工 review 已足够（小项目）

后果¶

正面：

解决"读者误以为章节失败"的认知摩擦
给后续章节扩张提供组织判据
无强制成本，作者每章自由

负面：

12 个章节 index.md 要逐个加"组织轴"声明（一次性）
后续每加新章要遵守（边际成本低）

后续：

12 个章节 index.md 加"组织轴"声明（本 ADR 落地后跟进 · 当前作为约定记录）
contributing.md 加"新章节自检 3 问"