文档治理政策
状态：已实现
最后复核：2026-08-15
长期讨论：GitHub Discussions
目的与权威来源
文档是安全、开发和运维控制面的一部分。实现、测试、图表和文档必须描述同一系统事实；已经背离实现的文档不得以“后续补充”为由进入 ship。
- Markdown 是正文权威源。
.excalidraw是架构图和时序图的权威可编辑源；同名.svg是派生预览。SUMMARY.md是文档站唯一目录来源。book/是可删除、可重建的 HTML 产物，不提交 Git。- Issue 定义任务契约，PR 中通过审查的文档才会改变项目权威描述。
- Discussion 只保存长期讨论上下文，不能替代 Issue、PR、ADR 或已合并文档。
内容规则
- 面向人的文档默认使用简体中文；代码标识符、协议字段、命令和难以准确翻译的标准术语可以保留英文。
- 文档必须明确区分
规划、已实现、已验证和已废弃，不得把目标状态写成当前能力。 - 架构、治理、运行手册等长期文档必须在标题后记录状态、最后复核日期、关联 Issue/PR；存在长期讨论时附 Discussion 链接。
- 没有可复现证据时，不得声称 production-ready、延迟、吞吐、盈利或故障恢复能力。
- 不得记录 API Key、Token、私钥、账户凭证、真实生产数据或其他秘密。
- 不得引用外部图片或公开 Excalidraw 分享地址；文档所需资源必须随仓库保存。
- 架构图、模块图、数据流图和时序图使用 Excalidraw，不以 Mermaid 替代。
必须更新文档的变更
| 变更 | 至少检查或更新 |
|---|---|
| Module 职责、依赖方向、线程或状态所有权 | ARCHITECTURE.md、MODULES.md、对应架构图 |
| Event、Command、状态机和顺序语义 | 领域契约、对应时序图 |
| 行情、order book、sequence、gap 或 stale 行为 | 市场数据架构与恢复时序 |
| OMS、订单生命周期和成交处理 | 订单生命周期文档与时序图 |
| 风控、限额、kill switch 或 fail-closed | 架构、安全说明与运行手册 |
| 重连、恢复、重放、对账或审计 | 恢复时序与运行手册 |
| 配置、CLI、环境变量、构建或部署 | README、工作流或运行手册 |
| 阶段门禁和当前能力 | ROADMAP.md 与首页状态 |
| 长期有效且影响广泛的设计选择 | 新增或更新 ADR |
没有可观察行为、契约或运维影响的内部重构可以不修改正文，但 PR 必须说明 Documentation Impact: not-required 的具体理由。
人工审阅与讨论边界
mdBook：阅读最终效果
mdBook 提供目录、搜索、页面导航、SVG 渲染以及返回仓库/建议修改入口。它只负责阅读，不承载审批、评论或身份授权。
GitHub PR：当前变更的正式审查
逐行评论、suggestion、Standard Review、Ponytail Review、Documentation Consistency Review 和 QA 证据都归属于当前 PR 的精确最终 SHA。任何新 commit 都会使受影响的证据失效。
GitHub Discussions：跨版本长期讨论
Discussion 用于尚未形成任务契约的架构问题、备选方案和跨 PR 讨论。被接受的结论必须创建或关联 Issue，并通过 PR 回写权威文档；未回写的 Discussion 结论不生效。不得自动为每页创建 Discussion，也不嵌入第三方评论系统。
GitHub 私有仓库权限和 Cloudflare Access 权限彼此独立。能够阅读 Cloudflare 文档站但没有仓库权限的用户，不能访问私有 PR、编辑入口或 Discussion。
Ship 前文档扫描
Implementer 在 PR 从 Draft 转为 Ready for review 前必须：
- 阅读
git diff --name-status <base>...HEAD和完整 diff。 - 确认 PR 中的
Documentation Impact为required或给出not-required理由。 - 逐项检查模块职责、数据流、状态机、配置、风控、恢复、对账、审计、阶段状态和图表是否仍与实现一致。
- 修正目标能力被误写成已实现、已经实现却仍标为规划、以及没有证据的性能或安全声明。
- 运行文档校验器、测试和
mdbook build，并在 PR 中记录命令与结果。 - 将需要长期讨论的未决事项链接到 Discussion；已经采纳的 Discussion 结论必须在本 PR 回写。
Reviewer 对最终 SHA 报告 Documentation Consistency Review: PASS / FAIL，检查语义一致性而非仅检查格式。QA 构建 HTML，并实际检查首页、导航、中文、关键页面和 SVG。Reviewer 或 QA finding 导致新 commit 后，受影响步骤必须重跑。
自动检查与人工判断的边界
tools/validate_docs.py 检查目录完整性、相对资源、图表格式与配对、禁用内容、状态栏和不可提交的构建产物。CI 运行同一校验器、测试和 mdBook 构建。
当前 caasxyz 组织私有仓库已启用 Protect main ruleset，但尚未把 docs 配置为 required status check。现阶段仍由用户依据 PR 上的成功检查与最终 SHA 审查证据执行合并门禁；只有独立 Issue 完成配置和真实验收后，才能声称该门禁由平台强制。
中文表达质量、架构语义、图形布局和实现一致性不能可靠地用简单规则判断，继续由 Reviewer 与 QA 人工验收；不得增加脆弱的中文字符比例或自动语义评分门禁。