docs: 添加前端构建与部署规范文档

docs/frontend-build-deploy.md

@@ -0,0 +1,68 @@
+# 前端构建与部署规范
+
+## 构建输出配置
+
+| 配置项 | 值 | 说明 |
+|--------|-----|------|
+| `base` | `/admin/` | 构建时资源引用路径前缀 |
+| `outDir` | `src/CncWebApi/admin` | 构建产物输出目录 |
+| `emptyOutDir` | `true` | 允许清空目标目录 |
+
+## IIS 部署结构
+
+```
+E:\opencode\haoliang\src\CncWebApi\        ← IIS站点根目录
+├── admin\                                  ← 前端构建输出
+│   ├── index.html
+│   ├── assets\
+│   ├── favicon.svg
+│   └── icons.svg
+├── api\                                    ← 后端API
+├── bin\                                    ← 后端DLL
+└── ...other backend files...
+```
+
+## 资源路径映射
+
+- 浏览器访问 `/admin/login` → IIS物理路径 `E:\opencode\haoliang\src\CncWebApi\admin\index.html`
+- 前端资源引用 `/admin/assets/xxx.js` → IIS物理路径 `E:\opencode\haoliang\src\CncWebApi\admin\assets\xxx.js`
+
+## 构建命令
+
+```bash
+cd frontend
+npm run build
+```
+
+## 部署检查清单
+
+1. ✅ `vite.config.ts` 的 `base` 必须为 `/admin/`
+2. ✅ `vite.config.ts` 的 `outDir` 必须指向 `src/CncWebApi/admin`
+3. ✅ IIS 站点物理路径必须为 `E:\opencode\haoliang\src\CncWebApi`
+4. ✅ 构建后 `src/CncWebApi/admin/index.html` 存在
+5. ✅ 构建后 `src/CncWebApi/admin/assets/` 目录存在
+
+## 常见问题
+
+### 资源404
+- 症状：页面能加载，但 JS/CSS 返回 404
+- 原因：`base` 配置与 IIS 物理路径不匹配
+- 检查：浏览器 DevTools Network 面板，JS 引用路径是否为 `/admin/assets/xxx.js`
+
+### 页面404
+- 症状：首页能加载，但路由（如 `/admin/dashboard`）返回 404
+- 原因：IIS 缺少 URL Rewrite 规则，需配置通配符路由 fallback
+- 检查：`src/CncWebApi/Web.config` 是否存在且配置正确
+
+## vite.config.ts 参考配置
+
+```typescript
+export default defineConfig(({ command }) => ({
+  // build时部署到/admin/子路径，dev时用根路径
+  base: command === 'build' ? '/admin/' : '/',
+  build: {
+    outDir: path.resolve(__dirname, '../src/CncWebApi/admin'),
+    emptyOutDir: true,
+  },
+}))
+```