主题
十四、文档维护约束
本章速览:本文档由机器校验。改代码时按这里的 8 条做,就不会出现"文档写错/漏写导致闸门变红"。
本文档本身是机器校验的。改项目时请遵守:
数字不要手写:§1.4 的规模数字由架构规则 17 逐项比对; 改完代码先跑
cd vite-cosmos-server && mvn -B -o test -Dtest=ArchitectureGuardTest。表清单只写现存表:§7.2 与附录 M 由文档检查器与生产库逐表核对; 已删除的表不要写成现状(要提历史,就在迁移说明里带"已删除"字样)。
接口路径要真实:文档里反引号包起来的
/api前缀路径由架构规则与文档检查器校验, 必须是真实路径或其前缀;端点全量清单是附录 L。迁移版本号要真实:形如
V163的引用必须能在db/migration/找到。机械清单怎么更新:附录 L(端点)、附录 M(数据字典)、§6.2(配置键)、 附录 A–E 都是从源码/生产库导出的快照,不是手写维护的;更新方式是重跑对应查询后替换段落。 改完务必跑:
bashnpm run docs:check # 覆盖度检查(退出码 0,报告缺口) npm run docs:check:strict # 有缺口即非 0(发布前/CI 用) npm run docs:wire # 前后端接线检查它会从源码与生产库取权威清单,核对文档是否完整覆盖:全部端点、全部表、全部配置键、 前后端全部路由、全部定时任务、全部错误码、全部部署脚本,并做结构/锚点/附录逐行校验。
改了部署事实就改 §11.1:容器名/端口/挂载/用户变了,
doctor.sh与check-deploy-guards.sh会先报错,文档跟着改,别让两者说法打架。新增已知缺口写进 §十三,并说明"要补需要动哪些地方";需要人拍板的写进 §十五。
审查记录是文档的一部分:每轮修复的「症状 → 根因 → 修法 → 验证」写进
docs/全项目审查记录.md,不要在说明书里堆流水账。文档站不手改:
docs-site/只是本文的视图层(按二级标题拆页、生成侧栏与搜索)。 改完文档跑npm --prefix docs-site run build验证能生成;生成物不提交。 发布用deploy-docs-site.sh(默认只构建+校验;PUBLISH=1才构建并以 base=/ 发布到docs.vite66.cn,宝塔面板站点可管 SSL/日志/备份)。