Merge pull request 'docs: 补充前端骨架屏部署验收规范' (#25) from codex/deploy-doc-frontend-smoke-0923 into main

服务器部署规范.md

@@ -7,7 +7,8 @@
 - 生产服务器项目根目录：`/opt/cangku`
 - 服务器代码目录：`/opt/cangku/app`
 - 生产编排文件：`/opt/cangku/app/deploy/production/docker-compose.yml`
-- 对外站点及注册接口：`https://ck.yydd.ai:8443`
+- 对外主站：`https://ck.yydd.ai`（标准 HTTPS 端口 `443`）
+- 兼容访问入口及注册接口：`https://ck.yydd.ai:8443`
 - 公网 TLS Redis：`ck.yydd.ai:6380`
 - 服务器 SSH 密钥目录位于开发者桌面：`~/Desktop/cangku-156.225.27.52-ssh-key`
 - 当前私钥文件：`~/Desktop/cangku-156.225.27.52-ssh-key/cangku-prod-root-ed25519`
@@ -64,6 +65,18 @@ git diff --stat origin/main...HEAD
 
 如果本次变更涉及数据表、索引、查询、数据映射或同步任务，部署者还必须确认 PR 已按《仓库提交与合并规范》记录索引与执行计划证据、分批/并发/超时边界、大表锁影响和回退方式。证据缺失、依赖全表扫描、可能对系统库或第三方云库造成不可控负载时，不得部署。
 
+### 3.1 前端发布必须阻断循环分块
+
+本项目曾因 Vite/Rollup 把 React、Ant Design、图表库和数据客户端按包路径拆成相互依赖的多个 chunk，生产构建虽然成功，浏览器却在 React 挂载前报错，页面永久停留在静态骨架屏。`curl` 返回 `200`、后端 `/health` 正常和静态资源可下载都无法发现这一故障。
+
+前端相关变更必须遵守以下要求：
+
+1. 保留 `frontend/vite.config.js` 中对 `CIRCULAR_CHUNK` 的构建阻断。不得为了让构建“通过”而删除、降级或忽略该检查。
+2. 第三方依赖默认保留在同一个 `vendor` chunk。不得仅按目录名把 React、Ant Design、图表库或 Cube/数据客户端强行拆成独立 vendor chunk；确需重新分包时，必须证明 chunk 依赖图无环，并完成本节和第 6 节的浏览器运行时验证。
+3. 出现 `Circular chunk`、`Cannot read properties of undefined`、`Cannot access ... before initialization` 等构建或浏览器错误时，停止发布并修正模块依赖或分包策略。禁止把它当成普通警告继续部署。
+4. 单个 vendor 文件较大的提示不等于可以直接按包名拆分。先使用路由级动态导入、页面级懒加载或经过验证的稳定边界减小首屏体积。
+5. 推送前至少执行 `npm --prefix frontend run check`。构建日志必须没有循环 chunk 警告；测试成功不能替代真实生产构建验证。
+
 有冲突时，AI 必须阅读共同基线和双方改动，保留双方仍然有效的行为。无法确定业务取舍时，停止该冲突的处理并请负责人决定。冲突解决后的代码必须重新测试、重新审核，不能沿用冲突前的结果。
 
 ## 4. 检查服务器是否正在更新
@@ -144,8 +157,10 @@ for attempt in $(seq 1 60); do
   sleep 2
 done
 
+curl -fsS https://ck.yydd.ai/ >/dev/null
+curl -fsS https://ck.yydd.ai/health
 curl -fsS https://ck.yydd.ai:8443/ >/dev/null
-curl -fsS https://ck.yydd.ai:8443/health
+curl -fsS https://ck.yydd.ai:8443/health >/dev/null
 docker compose -f deploy/production/docker-compose.yml ps
 git status --short
 git rev-parse HEAD
@@ -158,12 +173,25 @@ REMOTE
 
 ## 6. 部署完成标准
 
+### 6.1 必须验证浏览器真实运行，不能只检查 HTTP 200
+
+前端构建和容器启动后，必须使用一个不复用旧站点缓存和旧登录状态的全新浏览器上下文访问主站 `https://ck.yydd.ai/`。可以使用临时 Chrome 用户目录、全新的无痕窗口，或在开发者工具中清空站点数据后硬刷新。验证过程必须同时满足：
+
+1. 页面离开启动骨架屏，显示完整登录页或登录后的业务页面。
+2. 浏览器 Console 没有未捕获的 `TypeError`、`ReferenceError`、模块初始化错误或资源加载错误。
+3. Network 中入口 HTML、当前 HTML 引用的 JS/CSS 和关键接口均成功；不得只验证首页 HTML 返回 `200`。
+4. 当前 HTML 引用的资源文件名来自本次构建，页面展示的版本信息或接口 `/health` 中的 `SOURCE_GIT_SHA` 与待部署 SHA 一致。
+5. 至少完成一个关键用户路径；涉及数据页面时，要确认加载能结束并显示数据、空状态或明确错误，不能无限显示 loading/skeleton。
+
+如果全新浏览器上下文正常，而原有标签页仍停在旧骨架屏，先关闭旧标签并进行硬刷新或清除该站点缓存。不得通过回滚代码、固定旧资源文件名或长期关闭缓存来掩盖客户端旧资源。若全新上下文也失败，保留 Console、Network、容器日志和当前 SHA，在部署锁内停止报告完成并修复后重新发布。
+
 部署者和 AI 只有在以下项目全部确认后才能报告完成：
 
 - 服务器 `HEAD` 等于预先记录且已合并的 `origin/main` SHA。
 - `git status --short` 没有输出。
 - MySQL、Redis、Redis TLS 网关、后端和注册服务容器处于正常运行状态。
-- `https://ck.yydd.ai:8443/` 返回成功，`/health` 显示系统数据库、第三方数据库和 Redis 连接成功。
+- `https://ck.yydd.ai/` 与 `https://ck.yydd.ai:8443/` 返回成功，`/health` 显示系统数据库、第三方数据库和 Redis 连接成功。
+- 使用全新浏览器上下文完成第 6.1 节检查；页面已离开骨架屏，Console 无致命运行时错误，关键数据页面不会无限加载。
 - `ck.yydd.ai:6380` 的 TLS 证书校验通过；原始 Redis 端口没有对公网开放。
 - 新版本的关键用户路径已验证，没有覆盖其他开发者已经上线的功能。
 - 最终报告包含任务分支、PR、部署 SHA、实际检查结果和未解决问题。