Skip to content

生成物漂移与自查 ​

本页说明「代码改了、文档没跟上」这类漂移怎么被发现、怎么修,以及一次真实的演练记录。

1. 什么会漂移 ​

知识库里有一批页面不是手写的,而是从源码与 SQL 里抽出来的:

生成物来源生成脚本
/code/api/{index,system,infra,...}@RestController + 方法级映射 + @PreAuthorizescan-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. 漂移检测:把生成物重新算一遍,与磁盘上的文件比对;有任何差异就列出文件名并返回退出码 1。
  2. 结构校验(lint-knowledge.mjs):每个 md 必须有 front-matter 且 id 唯一;站内链接必须能解析到 .md 或目录的 index.md;反引号里的 路径#L行号 必须真实存在且行号不越界。
  3. 缓存豁免: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. 修复流程 ​

  1. 先跑 npm run docs:check,看它列出的文件。
  2. 如果确实改了代码:npm run docs:gen,人工扫一遍 git diff(生成物里的表格行数、权限点、行号是否合理),再提交。
  3. 如果是误报:不要改生成物去迁就,先判断是扫描规则问题还是文档笔误。规则问题改 scan-knowledge.mjs;链接/引用问题改对应的手写页面。
  4. 生成物一律不要手改,文件头有 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,详见发布与部署。

7. 相关 ​