fix(deploy): prevent Next.js chunk version skew

docs/BUG_HISTORY.md

@@ -3422,3 +3422,17 @@
 - 防复发：生产私有状态目录必须保持 `deploy:deploy 0700`，共享 lock 必须是普通非 symlink 文件且不可通过删除重建来“修复”；任何恢复流程失败都不得手填 `restore_verified=true` 或跳过恢复门禁。
 - 相关记录：生产迁移 runbook、Run 1865、Run 1869、Run 1873、Run 1877
 - 修复版本：待提交（精确 SHA 以重新发布后的远端分支与 production health 为准）
+
+## BUG-204 | 生产发布后报告页因 Next.js chunk 版本偏斜落入通用错误页
+
+- 状态：resolved（待 staging 与 production 精确 SHA 发布验收）
+- 首次发现：2026-08-16
+- 最近更新：2026-08-16
+- 影响面：发布切换期间已打开旧页面的用户进行客户端导航时，包括 `/reports` 等动态页面。
+- 用户现象：生产 `/reports` 显示 `This page couldn’t load`，只能点击 Reload 或手工刷新；同一登录会话刷新后报告列表恢复正常。
+- 根因：生产 Next.js Web 构建未设置 `deploymentId`。旧标签页仍运行上一发布的客户端 runtime，在新镜像切换后进行客户端导航时请求了当前发布无法匹配的静态 chunk，触发 `ChunkLoadError` 并落入 Next.js 通用错误页。报告 API、登录态和报告数据本身没有失败。
+- 修复：Web Docker build stage 接收并设置 `NEXT_DEPLOYMENT_ID`；Gitea 主发布链与 GitHub fallback 都把各自完整 commit SHA 作为 build argument 注入。Next.js 因而在构建产物中写入 deployment marker，并为静态资源请求附加 deployment query，使跨发布的客户端版本不一致能够触发完整导航，而不是继续加载不匹配的 chunk。新增 workflow 合同测试，锁定 Dockerfile 和两个构建入口都不能丢失该参数。
+- 验证：聚焦 workflow 合同测试 36/36 通过；使用固定 40 位测试 SHA 的真实 Next.js production build 成功，生成 HTML 含 `data-dpl-id`，JS/CSS URL 含同一 `?dpl=` 参数。远端仍需完成 staging quality/deploy、release gate、生产恢复点与 restore drill、migration gate、production deploy，以及登录态 `/reports` 浏览器验收。
+- 防复发：所有可发布 Web 镜像必须在 `next build` 阶段注入与镜像/发布清单相同的完整 Git SHA；仅设置容器运行时变量无效。发布验收必须覆盖已登录页面和静态资源 deployment marker，不能只看 `/api/health`。
+- 相关记录：`deploy/README.md`、`deploy/railway-web.Dockerfile`、staging/production exact-SHA release workflows
+- 修复版本：待提交（精确 SHA 以重新发布后的远端分支与 production health 为准）