docs: update deployment instructions for Vuetify SPA

- Split backend/frontend deploy steps
- Add deploy-frontend.sh one-liner reference
- Document AppAuthMiddleware 404 and stale HTML troubleshooting
- Remove obsolete dist copy instructions

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

CLAUDE.md

@@ -205,35 +205,49 @@ Lint配置: `ruff.toml`
 
 **MCP deploy 不可用**（GitHub 等 SaaS 的远程服务器 git pull 无凭据），实际部署用 SSH 命令直接操作：
 
-```bash
-# 0. 准备：服务器已配置 Gitea Token（一次性）
-ssh nexus "cd /www/wwwroot/api.synaglobal.vip && git remote set-url origin http://admin:TOKEN@66.154.115.8:3000/admin/Nexus.git"
-# TOKEN: Gitea 用户设置 → 应用 → 生成令牌 (nexus-deploy-token, 26fee743...)
+### 后端部署
 
+```bash
 # 1. Push 本地到 Gitea
 git push origin main
 
-# 2. 服务器拉取最新代码
-ssh nexus "cd /www/wwwroot/api.synaglobal.vip && git fetch --all && git reset --hard origin/main"
+# 2. 服务器拉取最新代码 + 重启
+ssh nexus "cd /www/wwwroot/api.synaglobal.vip && git fetch --all && git reset --hard origin/main && supervisorctl restart nexus"
 
-# 3. 增量修复（如有 bandit/lint 问题已 fix 但未 push）
-scp server/api/file.py nexus:/www/wwwroot/api.synaglobal.vip/server/api/file.py
-
-# 4. 重启服务
-ssh nexus "cd /www/wwwroot/api.synaglobal.vip && supervisorctl restart nexus"
-
-# 5. 健康检查
-ssh nexus "sleep 2 && curl -s http://127.0.0.1:8600/health"
+# 3. 健康检查
+ssh nexus "sleep 3 && curl -s http://127.0.0.1:8600/health"
 # 预期: "ok"（纯文本，非 JSON）
+```
 
-# 6. 浏览器验证
-# Playwright 打开 https://api.synaglobal.vip/app/index.html
+### 前端部署（Vuetify SPA）
+
+Vite 直接输出到 `web/app/`（后端 StaticFiles 挂载点），无需 dist 复制步骤：
+
+```bash
+# 一键部署脚本（构建+打包+上传+提取+重启+验证）
+bash deploy/deploy-frontend.sh
+
+# 或手动步骤：
+cd frontend && npx vite build && cd ..
+tar czf /tmp/nexus-frontend.tar.gz -C web/app index.html assets/
+scp /tmp/nexus-frontend.tar.gz nexus:/tmp/nexus-frontend.tar.gz
+ssh nexus "cd /www/wwwroot/api.synaglobal.vip/web/app && tar xzf /tmp/nexus-frontend.tar.gz && rm /tmp/nexus-frontend.tar.gz"
+ssh nexus "supervisorctl restart nexus"
+```
+
+**注意**: 前端构建产物 (`web/app/index.html`, `web/app/assets/`) 已在 `.gitignore` 中，不进入 git。每次部署需重新构建+上传。
+
+### 浏览器验证
+```bash
+curl -s -o /dev/null -w "%{http_code}" http://47.254.123.106:8600/app/  # 预期: 200
 ```
 
 ### 部署常遇问题
 | 问题 | 解决 |
 |------|------|
-| MCP deploy → git pull 失败 `could not read Username` | 服务器 remote URL 没配 token，用上面的 `git remote set-url` |
+| `/app/` 返回 404 | AppAuthMiddleware 拦截 — 确认 `/app/` 和 `/app/index.html` 在 `_APP_PUBLIC_PATHS` 中 |
+| `/app/` 返回旧 HTML (Tailwind/Alpine) | `git reset --hard` 恢复了旧文件 — 需要重新 tar+scp 前端构建产物 |
+| MCP deploy → git pull 失败 `could not read Username` | 服务器 remote URL 没配 token，用 `git remote set-url` |
 | Gate 2 Audit BLOCKED | 创建 `docs/audit/YYYY-MM-DD-topic.md`，含 Step3+Closure+DoD |
 | Gate 3 Test BLOCKED (401) | 服务器 .env 中 `NEXUS_TEST_ADMIN_PASSWORD` 与数据库不一致 |
 | Gate 6 Security BLOCKED (bandit HIGH) | md5 → sha256 等，参看 bandit 报告修复 |