zt-admin-template 1.0.0

package/template/DEPLOYMENT_GUIDE.md

@@ -0,0 +1,391 @@
+# 完整部署和测试指南
+
+## 项目完成情况
+
+### ✅ 已完成
+
+1. **二次封装 axios** (`src/utils/request.tsx`)
+   - 请求拦截器（添加 token）
+   - 响应拦截器（统一处理错误）
+   - 支持所有 HTTP 方法
+
+2. **多环境配置**
+   - `.env.development` - 开发环境
+   - `.env.test` - 测试环境
+   - `.env.production` - 生产环境
+
+3. **API 服务层** (`src/api/`)
+   - `user.ts` - 用户 API
+   - `role.ts` - 角色 API
+   - `menu.ts` - 菜单 API
+
+4. **后端 Koa 服务** (`koa-server/app.js`)
+   - 用户管理接口
+   - 角色管理接口
+   - 菜单管理接口
+   - CORS 支持
+
+5. **前端集成**
+   - 用户管理页面 - API 集成完成
+   - 角色管理页面 - API 集成完成
+   - 菜单管理页面 - API 集成完成
+
+## 快速启动
+
+### 方式一：分别启动（推荐）
+
+**步骤 1：启动后端服务**
+```bash
+cd koa-server
+npm install
+npm run dev
+```
+
+输出：
+```
+Koa 服务器已启动: http://localhost:8080
+```
+
+**步骤 2：启动前端应用**
+```bash
+npm install
+npm run dev
+```
+
+输出：
+```
+VITE v5.4.21  ready in 463 ms
+➜  Local:   http://localhost:5174/
+```
+
+### 方式二：使用 npm 脚本
+
+在项目根目录创建 `start-all.bat`：
+
+```batch
+@echo off
+start cmd /k "cd koa-server && npm install && npm run dev"
+timeout /t 3
+start cmd /k "npm install && npm run dev"
+```
+
+运行：
+```bash
+start-all.bat
+```
+
+## 测试流程
+
+### 1. 验证后端服务
+
+```bash
+curl http://localhost:8080/health
+```
+
+预期响应：
+```json
+{"status":"ok"}
+```
+
+### 2. 验证前端应用
+
+访问 `http://localhost:5174`
+
+### 3. 测试用户管理
+
+1. 点击左侧菜单"系统管理" > "用户管理"
+2. 应该看到 3 个用户列表
+3. 测试功能：
+   - **新增**：点击"新增"按钮，填写信息，点击"确定"
+   - **编辑**：点击编辑图标，修改信息，点击"确定"
+   - **删除**：点击删除图标，确认删除
+   - **刷新**：点击"刷新"按钮，重新加载数据
+
+### 4. 测试角色管理
+
+1. 点击左侧菜单"系统管理" > "角色管理"
+2. 应该看到 3 个角色列表
+3. 测试功能：
+   - **新增**：创建新角色并分配权限
+   - **编辑**：修改角色信息和权限
+   - **删除**：删除角色
+   - **权限分配**：在弹窗中选择权限
+
+### 5. 测试菜单管理
+
+1. 点击左侧菜单"系统管理" > "菜单管理"
+2. 应该看到树形菜单
+3. 测试功能：
+   - **新增**：添加新菜单
+   - **编辑**：修改菜单信息
+   - **删除**：删除菜单
+   - **展开/折叠**：展开或折叠菜单树
+
+## 环境变量配置
+
+### 开发环境 (`.env.development`)
+```
+VITE_API_URL=http://localhost:8080
+```
+
+### 测试环境 (`.env.test`)
+```
+VITE_API_URL=http://localhost:8081
+```
+
+### 生产环境 (`.env.production`)
+```
+VITE_API_URL=http://47.113.230.113
+```
+
+## 构建命令
+
+### 开发
+```bash
+npm run dev
+```
+
+### 测试构建
+```bash
+npm run build:test
+```
+
+### 生产构建
+```bash
+npm run build
+```
+
+### 代码检查
+```bash
+npm run lint
+```
+
+## 后端 API 文档
+
+### 基础 URL
+```
+http://localhost:8080
+```
+
+### 用户管理
+
+| 方法 | 端点 | 请求体 | 响应 |
+|------|------|--------|------|
+| GET | `/system/user/list?pageNum=1&pageSize=10` | - | `{rows: [], total: 0}` |
+| GET | `/system/user/:id` | - | `{id, username, ...}` |
+| POST | `/system/user` | `{username, nickName, ...}` | `{id, ...}` |
+| PUT | `/system/user` | `{id, username, ...}` | `{id, ...}` |
+| DELETE | `/system/user/:id` | - | `{msg: "删除成功"}` |
+
+### 角色管理
+
+| 方法 | 端点 | 请求体 | 响应 |
+|------|------|--------|------|
+| GET | `/system/role/list?pageNum=1&pageSize=10` | - | `{rows: [], total: 0}` |
+| GET | `/system/role/:id` | - | `{id, roleName, ...}` |
+| POST | `/system/role` | `{roleName, roleKey, ...}` | `{id, ...}` |
+| PUT | `/system/role` | `{id, roleName, ...}` | `{id, ...}` |
+| DELETE | `/system/role/:id` | - | `{msg: "删除成功"}` |
+
+### 菜单管理
+
+| 方法 | 端点 | 请求体 | 响应 |
+|------|------|--------|------|
+| GET | `/system/menu/list` | - | `[{id, menuName, children: []}]` |
+| GET | `/system/menu/:id` | - | `{id, menuName, ...}` |
+| POST | `/system/menu` | `{menuName, path, ...}` | `{id, ...}` |
+| PUT | `/system/menu` | `{id, menuName, ...}` | `{id, ...}` |
+| DELETE | `/system/menu/:id` | - | `{msg: "删除成功"}` |
+
+## 响应格式
+
+所有 API 响应格式：
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {}
+}
+```
+
+## 错误处理
+
+### 常见错误
+
+1. **CORS 错误**
+   ```
+   Access to XMLHttpRequest blocked by CORS policy
+   ```
+   解决：确保后端已启用 CORS
+
+2. **连接超时**
+   ```
+   Network Error: timeout of 10000ms exceeded
+   ```
+   解决：检查后端服务是否启动
+
+3. **404 错误**
+   ```
+   404 Not Found
+   ```
+   解决：检查 API 端点是否正确
+
+4. **500 错误**
+   ```
+   500 Internal Server Error
+   ```
+   解决：查看后端日志
+
+## 调试技巧
+
+### 前端调试
+
+1. 打开浏览器开发者工具（F12）
+2. 切换到 Network 标签查看请求
+3. 切换到 Console 标签查看日志
+4. 使用 React DevTools 查看组件状态
+
+### 后端调试
+
+1. 查看服务器启动日志
+2. 使用 curl 测试 API：
+   ```bash
+   curl http://localhost:8080/system/user/list
+   ```
+3. 使用 Postman 测试 API
+
+## 生产部署
+
+### 前端部署
+
+1. 构建生产版本
+   ```bash
+   npm run build
+   ```
+
+2. 上传 `dist` 目录到服务器
+   ```bash
+   scp -r dist/* user@server:/var/www/admin-system
+   ```
+
+3. 配置 Web 服务器（Nginx）
+   ```nginx
+   server {
+     listen 80;
+     server_name example.com;
+     root /var/www/admin-system;
+     index index.html;
+     
+     location / {
+       try_files $uri $uri/ /index.html;
+     }
+   }
+   ```
+
+### 后端部署
+
+1. 安装生产依赖
+   ```bash
+   cd koa-server
+   npm install --production
+   ```
+
+2. 使用 PM2 启动
+   ```bash
+   npm install -g pm2
+   pm2 start app.js --name admin-server
+   pm2 save
+   pm2 startup
+   ```
+
+3. 配置反向代理（Nginx）
+   ```nginx
+   server {
+     listen 80;
+     server_name api.example.com;
+     
+     location / {
+       proxy_pass http://localhost:8080;
+       proxy_set_header Host $host;
+       proxy_set_header X-Real-IP $remote_addr;
+     }
+   }
+   ```
+
+## 性能优化
+
+### 前端优化
+
+1. 代码分割
+2. 懒加载
+3. 缓存策略
+4. 压缩资源
+
+### 后端优化
+
+1. 数据库索引
+2. 缓存策略
+3. 分页加载
+4. 连接池
+
+## 监控和日志
+
+### 前端日志
+
+- 浏览器控制台
+- 错误追踪服务（如 Sentry）
+
+### 后端日志
+
+- 应用日志
+- 访问日志
+- 错误日志
+
+## 常见问题
+
+### Q: 如何修改 API 地址？
+A: 修改对应的 `.env.*` 文件中的 `VITE_API_URL`
+
+### Q: 如何添加新的 API？
+A: 在 `src/api/` 目录下创建新文件，参考现有 API 的写法
+
+### Q: 如何处理认证？
+A: 在 `src/utils/request.tsx` 的请求拦截器中添加 token
+
+### Q: 如何处理错误？
+A: 在 `src/utils/request.tsx` 的响应拦截器中处理错误
+
+### Q: 如何实现权限控制？
+A: 在路由或组件中检查用户权限
+
+## 下一步
+
+1. **数据库集成**
+   - 连接 MongoDB 或 MySQL
+   - 实现数据持久化
+
+2. **用户认证**
+   - 实现登录功能
+   - 添加 JWT 认证
+
+3. **权限管理**
+   - 实现基于角色的访问控制
+   - 添加权限验证
+
+4. **监控和日志**
+   - 添加操作日志
+   - 实现性能监控
+
+## 支持
+
+- 前端文档：`SYSTEM_MANAGEMENT.md`
+- 后端文档：`koa-server/README.md`
+- 集成指南：`INTEGRATION_GUIDE.md`
+- 启动指南：`START_ALL.md`
+
+---
+
+**项目状态**: ✅ 完成并可部署
+**最后更新**: 2026-01-18
+**版本**: 1.0.0