Checkpoint: dependency-warning-hygiene

日期：2026-05-14
Controller：Labs-FinTecAI Admin
Lane：knowledge-refactor
状态：Completed

1. 本批完成

Batch 7D 对 Docs workflow 中剩余 warning 做了来源审计和最小可修复项处理。

本批只处理 tooling hygiene，不修改项目正文、公共入口语义、Controller 产品事实源或知识库 IA。

2. 结论

Warning	来源	本批处理
npm warn deprecated uuid@8.3.2	@docusaurus/core -> webpack-dev-server -> sockjs -> uuid	已通过 npm overrides.uuid=11.1.1 消除
[DEP0040] punycode	远端 actions/setup-node@v5 的 cache restore / post cleanup 阶段；本地依赖树仍含 @docusaurus/bundler -> file-loader -> schema-utils -> ajv -> uri-js -> punycode	登记为外部 action/cache 噪声；不为消除日志而关闭 npm cache
[DEP0169] url.parse()	远端 actions/setup-node@v5 cache restore 阶段	登记为外部 action/cache 噪声；等待 upstream action/cache 处理

3. 变更内容

package.json 的 overrides 增加：

"uuid": "11.1.1"

package-lock.json 中唯一的 node_modules/uuid 从 8.3.2 更新到 11.1.1，移除了 deprecated metadata。

该 override 的直接使用方是 sockjs@0.3.24。sockjs 通过 CommonJS require('uuid').v4 使用 uuid；uuid@11.1.1 仍提供 CommonJS require export。

4. 远端 warning 证据

Docs run 25813617654 中，warning 分布为：

Set up Node: actions/setup-node@v5, node-version: 24, cache: npm
[DEP0040] DeprecationWarning: The `punycode` module is deprecated.
[DEP0169] DeprecationWarning: `url.parse()` behavior is not standardized...
Install docs dependencies:
npm warn deprecated uuid@8.3.2...
Post Set up Node:
[DEP0040] DeprecationWarning: The `punycode` module is deprecated.

因此 uuid@8.3.2 是仓库 install warning；punycode / url.parse() 的可见 warning 属于 GitHub action cache runtime 阶段，不是 Docusaurus build 失败或发布阻断。

5. 验证

• npm ls punycode uuid --all：确认 uuid@11.1.1 overridden，punycode@2.3.1 仍仅来自 Docusaurus 间接依赖。
• npm ci：退出码 0，未匹配 DeprecationWarning、punycode、url.parse()、uuid@8.3.2、deprecated、npm warn deprecated。
• node -e "const {v4}=require('uuid'); console.log(typeof v4, v4().length)"：通过，CommonJS require('uuid').v4 可用。
• npm run build：通过，Docusaurus build 和 Pagefind 索引生成成功。
• npm run prepare:portal && npx -y node@24 node_modules/.bin/docusaurus build && npx -y node@24 node_modules/.bin/pagefind --site build：通过，Node.js 24 下 Docusaurus build 和 Pagefind 索引生成成功。
• DOC_CHANGE_SCOPE=public-entrypoints,controllers,tooling npm run verify:change-scope：通过。
• node -e "JSON.parse(require('fs').readFileSync('docs-manifest.json','utf8')); console.log('docs-manifest JSON parse OK')"：通过。
• git diff --check：通过。
• npm run verify:published-site：通过，公开站点 4 项检查均 OK。
• test -f build/controllers/labs-fintecai-admin/checkpoints/2026-05-14-dependency-warning-hygiene/index.html：通过，新 checkpoint 页面已进入本地 build。
• rg -n "dependency-warning-hygiene|Dependency warning hygiene|uuid@11.1.1" build/docs-manifest.json build/llms.txt build/controllers/labs-fintecai-admin/checkpoints/2026-05-14-dependency-warning-hygiene/index.html：通过，机器入口和页面产物均包含新 checkpoint。

6. 后续动作

1. 后续远端 Docs workflow 应不再出现 npm warn deprecated uuid@8.3.2；
2. 若 actions/setup-node cache 阶段仍输出 punycode / url.parse()，继续记录为外部 action/cache runtime 噪声；
3. 不为消除非阻断 action warning 关闭 npm cache，除非该 warning 升级为 CI failure 或影响发布判断。