Project Context

本文件记录 nbtca/documents 的域语言和维护边界，帮助贡献者在提交文档、导航和治理规则时使用一致的概念。

项目定位

documents 是计算机协会的文档站点，使用 VitePress 构建，面向协会成员、维修队成员、活动组织者和需要查阅公开资料的读者。

站点内容以 Markdown 为主要源文件，VitePress 配置、sidebar 模块和 CI 共同组成文档发布的治理边界。

栏目语言

教程

教程是面向学习的说明文档，回答“如何完成某件技术或协作任务”。典型内容包括工具使用、服务接入、GitHub 工作流、教育邮箱、C 盘清理等。

教程目录位于 tutorial/。按年份组织的活跃教程位于 tutorial/<year>/，对应导航由 tutorial/sidebar.ts 维护。

流程

流程是面向协会事务办理的操作规范，回答“协会内部事务该按什么步骤处理”。典型内容包括借教室、申请第二课堂学分、报销、活动组织和博客发布。

流程目录位于 process/。按年份组织的活跃流程位于 process/<year>/，对应导航由 process/sidebar.ts 维护。

维修

维修是面向维修队、维修日和维修工单系统的操作文档，回答“如何处理设备维护和维修协作”。典型内容包括维修操作指南、工具索引、维修日检查单和工单系统说明。

维修目录位于 repair/。当前维修导航由 repair/sidebar.ts 维护。

存档

存档是历史材料的长期保存区，回答“过去发生过什么、有哪些旧资料仍值得保留”。典型内容包括会议纪要、年度计划、组织材料和旧版手册。

存档目录位于 archived/。年份目录用于历史记录，archived/manual/ 用于长期手册。存档导航由 archived/sidebar.ts 自动扫描生成。

资产模板

资产模板是文档流程中可下载或可引用的附件，例如图片、表格、申请文件模板和活动材料。资产应靠近使用它的栏目存放，并通过文档说明用途和更新时间。

治理边界

导航

导航决定读者如何发现页面。当前项目同时存在手写 sidebar 和自动扫描 sidebar。治理目标是让每个栏目有清晰的导航入口，并让新增页面时需要修改的位置可预测。

内容契约

内容契约描述文档最低可维护标准：标题清晰、路径稳定、维护信息可追踪、链接有效、资产来源明确。不同栏目可以有不同严格度；活跃教程、流程和维修文档应比历史存档更严格。

CI contract

CI contract 是合并前的质量门。它应覆盖 lint、测试和 VitePress 构建，确保文档格式、导航逻辑和站点构建不会被 PR 破坏。

ADR

ADR 是架构决策记录，用于保存已经接受的治理方向、取舍和后续影响。ADR 不替代 issue 或 PR 讨论；它只记录已经决定或正在执行的长期约束。

维护原则

• 公开页面必须有稳定入口，避免孤岛页面。
• 活跃文档优先保持清晰和可验证，存档文档优先保持历史原貌。
• 附件和模板优先集中管理，减少重复副本。
• 大范围治理变化应拆成小 PR，并通过 ADR 记录长期决策。
• 不同栏目的实现可以不同，但对贡献者暴露的规则应尽量一致。