跳转至

0000 采用代码化文档工程作为工作室唯一事实源 (Docs-as-Code)

Status (状态)

Accepted (已采纳)

Context and Problem Statement (背景与问题)

工作室过去使用富文本 Wiki 与零散表格记录管线规矩,面临严重问题: 1. 权限无法精细受控,任何人可随意编辑主文档,缺乏物理防劫持(VES Ch. 10 核心风险); 2. 缺乏自动化门禁,死链、错格式和超期版本无人清理,发生典型 Wiki 腐烂; 3. 文档与实际 DCC/引擎版本严重脱节,无法在变更时强制留痕。

Decision Drivers (决策考量)

  • 需要支持物理分支保护(PR 审核制)与变更审计追踪;
  • 需要无感嵌入开发者的日常工作流(Git、PR、代码审查);
  • 必须具备离线极速检索与静态部署能力,杜绝外部重型 SaaS 席位费。

Considered Options (备选方案评估)

  • 方案 A (在线协同 Wiki,如 Notion / Confluence): 权限模型无法物理阻止单点修改,易产生断链和格式腐烂,且产生持续商业席位税。
  • 方案 B (Docs-as-Code,基于 Git + Markdown + MkDocs Material): 源码存入私有 Git 仓库,结合 PR 门禁进行自动化严格构建,彻底实现文档即代码。

Decision Outcome (决策结果)

Chosen option: 方案 B (Docs-as-Code)。

Positive Consequences (正面收益)

  • 物理防篡改:核心规范修改必须经过 PR 审查与负责人批准;
  • 自动化门禁:通过 CI 自动阻断大文件误提、死链与未附带 ADR 的突发变更;
  • 高性能离线交付:基于 jieba 分词的离线检索能力,纯静态分发至全局边缘节点。

Negative Consequences / Trade-offs (负面影响或妥协)

  • 美术创作者若需新建正式文档,需要通过网页端 Edit this page 发起 Pull Request;
  • 为缓解此阻力,设立 sandbox/ 免检缓冲沙盒并支持网页直接编辑。