主题
生成物漂移与自查
本页说明「代码改了、文档没跟上」这类漂移怎么被发现、怎么修,以及一次真实的演练记录。
1. 什么会漂移
知识库里有一批页面不是手写的,而是从源码与 SQL 里抽出来的:
| 生成物 | 来源 | 生成脚本 |
|---|---|---|
/code/api/{index,system,infra,...} | @RestController + 方法级映射 + @PreAuthorize | scan-knowledge.mjs |
/code/data/{index,system,infra,...} | @TableName 的 DO + sql/mysql/pmforge.sql | 同上 |
/cards/<ID>.md(53 张) | cards.data.mjs / cards.reserved.mjs + 代码索引 | 同上 |
/reference/配置项速查 | application*.yaml 的 pmforge.* | 同上 |
/reference/枚举字典 | *Enum.java 的常量与注释 | 同上 |
/reference/索引-按代码找功能 | 权限点 → 接口、表 → DO 的反查 | 同上 |
只要改了控制器、DO、枚举、YAML 或主库 SQL,上面这些页面就应该跟着变。手写页面(产品层、模块手册、机制页、功能卡的数据源)不受此影响。
2. 一条命令自查
bash
npm run docs:gen # 重新生成
npm run docs:check # 生成 + 校验:生成物是否有变更 + front-matter/链接/代码引用是否有效docs:check 做了三件事:
- 漂移检测:把生成物重新算一遍,与磁盘上的文件比对;有任何差异就列出文件名并返回退出码 1。
- 结构校验(
lint-knowledge.mjs):每个 md 必须有 front-matter 且id唯一;站内链接必须能解析到.md或目录的index.md;反引号里的路径#L行号必须真实存在且行号不越界。 - 缓存豁免:
docs/.generated/code-index.json带生成时间戳,不参与漂移比对,也不入库。
3. 一次真实演练
下面这组操作在仓库里真跑过,用来证明门禁不是摆设。
第 1 步:基线通过。
bash
node script/docs/scan-knowledge.mjs --check
# 退出码 0,无输出文件第 2 步:故意制造漂移。 在 pmforge-module-infra/src/main/java/com/pmforge/module/infra/controller/admin/config/ConfigController.java 末尾加一行:
java
@GetMapping("/drift-test")
public CommonResult<String> driftTest() {
return success("drift");
}第 3 步:门禁拦截。
bash
npm run docs:check
# 列出过期文件:
# docs/code/api/index.md
# docs/code/api/infra.md
# 退出码 1原因是接口索引由源码生成,多了一个 GET /infra/config/drift-test,生成结果与磁盘文件不再一致。同一时期还验证过 UserController 被脚本误写 BOM 的情况:git checkout HEAD -- 还原后门禁恢复通过。
第 4 步:还原并复验。
bash
git checkout -- pmforge-module-infra/src/main/java/com/pmforge/module/infra/controller/admin/config/ConfigController.java
node script/docs/scan-knowledge.mjs --check # 回到 0第 5 步:如果漂移是真的(改了代码要留),就重新生成并提交。
bash
npm run docs:gen
git diff --stat docs/code docs/reference docs/cards
git add docs && git commit -m "docs: 同步代码索引"4. 修复流程
- 先跑
npm run docs:check,看它列出的文件。 - 如果确实改了代码:
npm run docs:gen,人工扫一遍git diff(生成物里的表格行数、权限点、行号是否合理),再提交。 - 如果是误报:不要改生成物去迁就,先判断是扫描规则问题还是文档笔误。规则问题改
scan-knowledge.mjs;链接/引用问题改对应的手写页面。 - 生成物一律不要手改,文件头有
auto-generated ... do not edit;下次docs:gen会覆盖。
5. 常见误报与陷阱
| 现象 | 原因 | 处理 |
|---|---|---|
docs:check 每次都报 code-index.json 变化 | JSON 里有 generatedAt 时间戳 | 已在 check 模式跳过该文件,属预期行为 |
lint 报 pmforge-*/xxx、sql/*.sql 找不到 | 反引号里用了通配符或占位符 | lint 会跳过含 ...、*、|、{、<、xxx 的引用;真实文件路径必须写全 |
生成的中文乱码、VitePress 报 Unexpected token '\uFEFF' | 用 PowerShell Set-Content -Encoding utf8 写文件带 BOM | 一律用 UTF-8 无 BOM 写;package.json 用 Python 的 json.dump(ensure_ascii=False) 重写 |
| 注解解析不到权限点 | 本仓库注解顺序是「映射注解在前、@Operation/@PreAuthorize 在后」 | 扫描器从映射注解向后取到方法体 {,不要向前找 |
CRLF 文件里正则匹配不到 } | 源码是 CRLF | 扫描前把 \r\n 归一为 \n |
| 新增控制器没被扫到 | 模块包结构扁平(如 iot.admin),旧规则按 /controller/ 路径过滤 | 现已按 @RestController 注解识别,不依赖目录名 |
6. CI 行为
.github/workflows/docs.yml 在 PR 与 main 上都会执行:
bash
npm ci
node script/docs/scan-knowledge.mjs --check
node script/docs/lint-knowledge.mjs
npm run docs:build前两步失败即红,构建产物作为 artifact 保留 7 天。CI 不发布站点:发布走 Cloudflare Pages 的 Git 集成,构建命令 npm run docs:build、输出 docs/.vitepress/dist,详见发布与部署。