feat: complete huihui square avatar workflows

overview-style-fix-2026-07-21.md

@@ -0,0 +1,44 @@
+# 全站样式消失事故 — 根因与修复（2026-07-21）
+
+## 现象
+用户反馈：线上 `http://192.168.1.188:8099`「样式都全没了」。
+
+## 根因（部署脚本 bug，非业务代码）
+早前部署使用：
+```
+docker cp /root/avatar-test/run-dist/. avatar-test-frontend:/usr/share/nginx/html/
+```
+这个 `SRC/.` 写法**不可靠**——它把新 JS 拷进容器，却**漏拷了新 CSS**。
+结果是容器内变成「新 JS + 旧 CSS」组合：
+
+- Vue `<style scoped>` 的样式靠 `data-v-xxxxxx` 作用域属性匹配；
+- 新 JS 渲染元素用 `data-v-732791c8`，但容器内唯一的 `AvatarCreate-CslCRBwi.css` 是旧构建、用 `data-v-8333551b`；
+- 二者 scope id 不一致 → 样式被浏览器静默丢弃 → **所有页面全站样式失效**。
+
+本地 `dist` 同源构建是自洽的（JS scope == CSS scope），证明问题只发生在 `docker cp` 拷贝环节。
+
+## 修复
+改用**显式子目录拷贝**（可靠）：
+```
+docker cp /root/avatar-test/run-dist/assets/.  avatar-test-frontend:/usr/share/nginx/html/assets/
+docker cp /root/avatar-test/run-dist/index.html  avatar-test-frontend:/usr/share/nginx/html/index.html
+```
+整体覆盖后，各页面 JS/CSS 的 scope id 全部对齐：
+- AvatarCreate = `data-v-732791c8`（JS==CSS ✅）
+- AvatarManage = `data-v-007cc632`（JS==CSS ✅）
+- SmsLogin    = `data-v-7851357e`（JS==CSS ✅）
+
+## 验证（无头浏览器实测）
+- Playwright(chromium) 渲染 `:8099`：控制台 **0 报错**，页面 DOM 正常渲染。
+- computed style 实测：
+  - `.hero` 背景 = `linear-gradient(135deg, rgb(249,115,22), rgb(251,146,60), rgb(253,186,116))`（暖色渐变生效）
+  - `.feature-card` 背景 = `rgb(255,255,255)`（白卡生效）
+
+→ 样式确凿恢复。
+
+## 部署铁律（写入项目记忆）
+Vite SPA 部署到 docker nginx 容器，**禁止** `docker cp run-dist/. html/`。
+一律拆成 `assets/.` 与 `index.html` 两条显式拷贝；或先 `rm -rf assets/*` 再 cp。
+每次部署后核对「线上 JS scope id == 同页 CSS scope id」，否则 scoped 样式会静默失效而难以察觉。
+
+测试地址：`http://192.168.1.188:8099`（建议硬刷新清掉旧 JS/CSS 缓存）。