docs: 补充规格文档（specs 01-15）

2026-09-08 13:39:10 +08:00
parent 4ac8f8b472
commit b12acf7793
16 changed files with 1462 additions and 0 deletions
@@ -0,0 +1,79 @@
+# 10 静态资源部署与 Nginx History 托管
+
+## 模块职责
+
+定义后台 Vue 构建产物、Nginx 静态目录、History fallback、Java API 代理和 `/admin` 入口重定向的发布契约。
+
+## 依赖关系
+
+上游：`admin-frontend-vue/vite.config.ts` 的 `base=/admin-vue/`、`dist` 输出；Java API。
+
+下游：浏览器访问后台、Vue Router 刷新、客户端 `/api/version/latest` 请求。
+
+参考文件：
+
+- `admin-frontend-vue/vite.config.ts`
+- `admin-frontend-vue/deploy/nginx-admin-vue.conf.example`
+- Java `AdminConsoleController.root/adminPage`
+
+## 核心接口：原实现 → 目标实现
+
+| 原实现 | 目标实现 |
+|---|---|
+| Java 重定向 `/admin.html` | Java 重定向 `/admin-vue/` |
+| Java classpath `admin.html` | Nginx 独立静态目录 `/var/www/admin-vue/` |
+| `admin.html` 内嵌 CSS/模板 | `dist/index.html` + hashed assets |
+| Flask `serve_static` | Nginx 静态资源 location |
+| 旧页面 hash 面板 | History route + fallback |
+
+## 目录契约
+
+```text
+/var/www/admin-vue/
+├── index.html
+├── assets/
+│   ├── index-<hash>.js
+│   ├── index-<hash>.css
+│   └── page-<hash>.js
+└── assets/logo.jpg
+```
+
+浏览器路径：
+
+- `/admin` → 302 `/admin-vue/`。
+- `/admin-vue/` → `index.html`。
+- `/admin-vue/account/users` → fallback `index.html`。
+- `/admin-vue/assets/<file>` → 真实文件。
+- `/api/*` → Java upstream。
+
+## 内部结构
+
+发布过程：
+
+1. 在 `admin-frontend-vue` 执行依赖安装、类型检查和生产构建。
+2. 对 `dist/index.html`、assets 清单和入口引用做一致性校验。
+3. 上传到带版本号的临时发布目录。
+4. 校验完整后原子切换 Nginx 当前目录。
+5. 保留上一个版本目录用于快速回滚。
+
+## 类型/路径映射
+
+| 配置 | 目标值 |
+|---|---|
+| Vite `base` | `/admin-vue/` |
+| Vite `outDir` | `dist` |
+| Router history base | `/admin-vue/` |
+| Nginx 静态前缀 | `/admin-vue/` |
+| Java API upstream | `/api/` |
+| 登录跳转 | `/login` |
+
+## 类型映射\n\n`dist/index.html` 映射为 `/admin-vue/` 入口；`dist/assets/*` 映射为 `/admin-vue/assets/*`；Vue Router 相对 route 映射为 `/admin-vue/<route>`；`/api/*` 不进入静态资源目录。\n\n## 迁移/实现注意事项
+
+1. Nginx 对 `/admin-vue/assets/` 必须优先匹配真实文件，不能被 fallback 到 HTML。
+2. 不存在的 JS/CSS/图片必须返回 404，避免浏览器收到 HTML 后产生难以诊断的 MIME 错误。
+3. `try_files` 的 fallback 只针对 `/admin-vue/` 页面路径。
+4. hashed assets 可配置长期缓存；`index.html` 必须 no-cache 或短缓存。
+5. 发布不能把 `dist` 复制到客户端 `frontend-vue/new_web_source`。
+6. 静态资源不打进 Java JAR；Java 只承担 API 和入口重定向。
+7. 生产切换前必须验证 Nginx upstream 的 Cookie、Host、X-Forwarded-* 和 HTTPS 行为。
+