Skip to content

十四、文档维护约束 ​

本章速览:本文档由机器校验。改代码时按这里的 8 条做,就不会出现"文档写错/漏写导致闸门变红"。

本文档本身是机器校验的。改项目时请遵守:

  1. 数字不要手写:§1.4 的规模数字由架构规则 17 逐项比对; 改完代码先跑 cd vite-cosmos-server && mvn -B -o test -Dtest=ArchitectureGuardTest。

  2. 表清单只写现存表:§7.2 与附录 M 由文档检查器与生产库逐表核对; 已删除的表不要写成现状(要提历史,就在迁移说明里带"已删除"字样)。

  3. 接口路径要真实:文档里反引号包起来的 /api 前缀路径由架构规则与文档检查器校验, 必须是真实路径或其前缀;端点全量清单是附录 L。

  4. 迁移版本号要真实:形如 V163 的引用必须能在 db/migration/ 找到。

  5. 机械清单怎么更新:附录 L(端点)、附录 M(数据字典)、§6.2(配置键)、 附录 A–E 都是从源码/生产库导出的快照,不是手写维护的;更新方式是重跑对应查询后替换段落。 改完务必跑:

    bash
    npm run docs:check          # 覆盖度检查(退出码 0,报告缺口)
    npm run docs:check:strict   # 有缺口即非 0(发布前/CI 用)
    npm run docs:wire           # 前后端接线检查

    它会从源码与生产库取权威清单,核对文档是否完整覆盖:全部端点、全部表、全部配置键、 前后端全部路由、全部定时任务、全部错误码、全部部署脚本,并做结构/锚点/附录逐行校验。

  6. 改了部署事实就改 §11.1:容器名/端口/挂载/用户变了,doctor.sh 与 check-deploy-guards.sh 会先报错,文档跟着改,别让两者说法打架。

  7. 新增已知缺口写进 §十三,并说明"要补需要动哪些地方";需要人拍板的写进 §十五。

  8. 审查记录是文档的一部分:每轮修复的「症状 → 根因 → 修法 → 验证」写进 docs/全项目审查记录.md,不要在说明书里堆流水账。

  9. 文档站不手改:docs-site/ 只是本文的视图层(按二级标题拆页、生成侧栏与搜索)。 改完文档跑 npm --prefix docs-site run build 验证能生成;生成物不提交。 发布用 deploy-docs-site.sh(默认只构建+校验;PUBLISH=1 才构建并以 base=/ 发布到 docs.vite66.cn,宝塔面板站点可管 SSL/日志/备份)。

本页由 docs/vite-cosmos-项目说明.md 自动生成;请改源文件,不要改生成物。