zt-admin-template 1.0.0

package/template/INTEGRATION_GUIDE.md

@@ -0,0 +1,458 @@
+# 前后端集成完整指南
+
+## 项目架构
+
+```
+admin-system/
+├── 前端应用 (React + TypeScript + Vite)
+│   ├── src/
+│   │   ├── api/              # API 服务层
+│   │   │   ├── user.ts       # 用户 API
+│   │   │   ├── role.ts       # 角色 API
+│   │   │   └── menu.ts       # 菜单 API
+│   │   ├── utils/
+│   │   │   └── request.tsx    # axios 二次封装
+│   │   └── pages/system/      # 管理模块
+│   │       ├── user/User.tsx
+│   │       ├── role/Role.tsx
+│   │       └── menu/Menu.tsx
+│   └── .env.development      # 开发环境配置
+│
+└── 后端服务 (Koa)
+    └── koa-server/
+        ├── app.js            # 主应用文件
+        └── package.json      # 依赖配置
+```
+
+## 技术栈
+
+### 前端
+- React 19.2.4
+- TypeScript 5.9.3
+- Ant Design 6.3.2
+- Axios 1.6.0
+- Vite 5.4.0
+
+### 后端
+- Koa 2.14.2
+- Koa Router 12.0.0
+- Koa CORS 0.0.16
+- Koa Body Parser 4.4.1
+
+## 集成步骤
+
+### 第一步：环境准备
+
+1. **安装 Node.js**
+   - 版本要求：v20.18.0+
+   - 下载地址：https://nodejs.org/
+
+2. **克隆项目**
+   ```bash
+   git clone <项目地址>
+   cd admin-system
+   ```
+
+3. **安装前端依赖**
+   ```bash
+   npm install
+   ```
+
+4. **安装后端依赖**
+   ```bash
+   cd koa-server
+   npm install
+   cd ..
+   ```
+
+### 第二步：配置环境变量
+
+1. **前端开发环境配置** (`.env.development`)
+   ```
+   VITE_API_URL=http://localhost:8080
+   ```
+
+2. **前端测试环境配置** (`.env.test`)
+   ```
+   VITE_API_URL=http://localhost:8081
+   ```
+
+3. **前端生产环境配置** (`.env.production`)
+   ```
+   VITE_API_URL=http://47.113.230.113
+   ```
+
+### 第三步：启动服务
+
+#### 方式一：分别启动（推荐）
+
+**终端 1 - 启动后端服务**
+```bash
+cd koa-server
+npm run dev
+```
+
+输出应该显示：
+```
+Koa 服务器已启动: http://localhost:8080
+```
+
+**终端 2 - 启动前端应用**
+```bash
+npm run dev
+```
+
+输出应该显示：
+```
+VITE v5.4.21  ready in 518 ms
+➜  Local:   http://localhost:5173/
+```
+
+#### 方式二：使用 npm 脚本
+
+在 `package.json` 中添加：
+```json
+{
+  "scripts": {
+    "dev:all": "concurrently \"cd koa-server && npm run dev\" \"npm run dev\""
+  }
+}
+```
+
+然后运行：
+```bash
+npm run dev:all
+```
+
+### 第四步：验证集成
+
+1. **打开浏览器**
+   访问 `http://localhost:5173`
+
+2. **测试 API 连接**
+   - 打开浏览器开发者工具（F12）
+   - 切换到 Network 标签
+   - 点击左侧菜单"系统管理" > "用户管理"
+   - 观察网络请求，应该看到 `/system/user/list` 请求
+
+3. **验证数据加载**
+   - 用户列表应该显示 3 个用户
+   - 角色列表应该显示 3 个角色
+   - 菜单列表应该显示树形菜单
+
+## API 集成详解
+
+### 请求工具 (`src/utils/request.tsx`)
+
+```typescript
+import { request } from '@/utils/request';
+
+// GET 请求
+const data = await request.get('/system/user/list', { params: { pageNum: 1 } });
+
+// POST 请求
+const result = await request.post('/system/user', { username: 'test' });
+
+// PUT 请求
+const updated = await request.put('/system/user', { id: '1', username: 'new' });
+
+// DELETE 请求
+await request.delete('/system/user/1');
+```
+
+### API 服务层 (`src/api/user.ts`)
+
+```typescript
+import { request } from '@/utils/request';
+
+// 获取用户列表
+export const getUserList = (params) =>
+  request.get('/system/user/list', { params });
+
+// 新增用户
+export const addUser = (data) =>
+  request.post('/system/user', data);
+
+// 编辑用户
+export const updateUser = (data) =>
+  request.put('/system/user', data);
+
+// 删除用户
+export const deleteUser = (id) =>
+  request.delete(`/system/user/${id}`);
+```
+
+### 页面集成 (`src/pages/system/user/User.tsx`)
+
+```typescript
+import { getUserList, addUser, updateUser, deleteUser } from '@/api/user';
+
+// 获取列表
+const fetchUsers = async () => {
+  const response = await getUserList({ pageNum: 1, pageSize: 10 });
+  setUsers(response.rows);
+};
+
+// 新增
+const handleAdd = async (data) => {
+  await addUser(data);
+  fetchUsers();
+};
+
+// 编辑
+const handleEdit = async (data) => {
+  await updateUser(data);
+  fetchUsers();
+};
+
+// 删除
+const handleDelete = async (id) => {
+  await deleteUser(id);
+  fetchUsers();
+};
+```
+
+## 后端 API 文档
+
+### 用户管理
+
+| 方法 | 端点 | 说明 |
+|------|------|------|
+| GET | `/system/user/list` | 获取用户列表 |
+| GET | `/system/user/:id` | 获取用户详情 |
+| POST | `/system/user` | 新增用户 |
+| PUT | `/system/user` | 编辑用户 |
+| DELETE | `/system/user/:id` | 删除用户 |
+
+### 角色管理
+
+| 方法 | 端点 | 说明 |
+|------|------|------|
+| GET | `/system/role/list` | 获取角色列表 |
+| GET | `/system/role/:id` | 获取角色详情 |
+| POST | `/system/role` | 新增角色 |
+| PUT | `/system/role` | 编辑角色 |
+| DELETE | `/system/role/:id` | 删除角色 |
+
+### 菜单管理
+
+| 方法 | 端点 | 说明 |
+|------|------|------|
+| GET | `/system/menu/list` | 获取菜单列表 |
+| GET | `/system/menu/:id` | 获取菜单详情 |
+| POST | `/system/menu` | 新增菜单 |
+| PUT | `/system/menu` | 编辑菜单 |
+| DELETE | `/system/menu/:id` | 删除菜单 |
+
+## 测试场景
+
+### 场景 1：用户管理
+
+1. **查看用户列表**
+   - 访问 `/system/user`
+   - 应该显示 3 个用户
+
+2. **新增用户**
+   - 点击"新增"按钮
+   - 填写用户信息
+   - 点击"确定"
+   - 列表应该更新
+
+3. **编辑用户**
+   - 点击编辑图标
+   - 修改用户信息
+   - 点击"确定"
+   - 列表应该更新
+
+4. **删除用户**
+   - 点击删除图标
+   - 确认删除
+   - 列表应该更新
+
+### 场景 2：角色管理
+
+1. **查看角色列表**
+   - 访问 `/system/role`
+   - 应该显示 3 个角色
+
+2. **分配权限**
+   - 新增或编辑角色
+   - 在权限分配区域选择权限
+   - 点击"确定"
+   - 权限应该被保存
+
+### 场景 3：菜单管理
+
+1. **查看菜单树**
+   - 访问 `/system/menu`
+   - 应该显示树形菜单
+
+2. **添加子菜单**
+   - 点击"+"按钮
+   - 填写菜单信息
+   - 点击"确定"
+   - 菜单树应该更新
+
+## 错误处理
+
+### 常见错误
+
+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 或 Ctrl+Shift+I
+   ```
+
+2. **查看网络请求**
+   - 切换到 Network 标签
+   - 执行操作
+   - 查看请求和响应
+
+3. **查看控制台日志**
+   - 切换到 Console 标签
+   - 查看错误信息
+
+4. **使用 React DevTools**
+   - 安装浏览器扩展
+   - 查看组件状态
+
+### 后端调试
+
+1. **查看服务器日志**
+   ```
+   Koa 服务器已启动: http://localhost:8080
+   ```
+
+2. **测试 API**
+   ```bash
+   curl http://localhost:8080/system/user/list
+   ```
+
+3. **使用 Postman**
+   - 导入 API 集合
+   - 测试各个端点
+
+## 性能优化
+
+### 前端优化
+
+1. **代码分割**
+   ```typescript
+   const User = lazy(() => import('./pages/system/user/User'));
+   ```
+
+2. **缓存策略**
+   ```typescript
+   const cache = new Map();
+   ```
+
+3. **请求去重**
+   ```typescript
+   const pending = new Map();
+   ```
+
+### 后端优化
+
+1. **数据库索引**
+   - 为常用查询字段添加索引
+
+2. **缓存策略**
+   - 使用 Redis 缓存热数据
+
+3. **分页加载**
+   - 实现分页和懒加载
+
+## 部署指南
+
+### 前端部署
+
+1. **构建生产版本**
+   ```bash
+   npm run build
+   ```
+
+2. **部署到服务器**
+   ```bash
+   # 上传 dist 目录到服务器
+   scp -r dist/* user@server:/var/www/admin-system
+   ```
+
+### 后端部署
+
+1. **安装生产依赖**
+   ```bash
+   cd koa-server
+   npm install --production
+   ```
+
+2. **使用 PM2 启动**
+   ```bash
+   npm install -g pm2
+   pm2 start app.js --name admin-server
+   ```
+
+## 常见问题
+
+### Q: 如何修改 API 地址？
+A: 修改 `.env.development` 中的 `VITE_API_URL`
+
+### Q: 如何添加新的 API？
+A: 在 `src/api/` 目录下创建新文件，参考现有 API 的写法
+
+### Q: 如何处理认证？
+A: 在 `src/utils/request.tsx` 的请求拦截器中添加 token
+
+### Q: 如何处理错误？
+A: 在 `src/utils/request.tsx` 的响应拦截器中处理错误
+
+## 下一步
+
+1. **数据库集成**
+   - 连接 MongoDB 或 MySQL
+   - 实现数据持久化
+
+2. **用户认证**
+   - 实现登录功能
+   - 添加 JWT 认证
+
+3. **权限管理**
+   - 实现基于角色的访问控制
+   - 添加权限验证
+
+4. **监控和日志**
+   - 添加操作日志
+   - 实现性能监控
+
+## 支持
+
+如有问题，请查看：
+- 前端文档：`SYSTEM_MANAGEMENT.md`
+- 后端文档：`koa-server/README.md`
+- 启动指南：`START_ALL.md`