# API测试指南:阶段三和阶段四 > **测试环境**: 影子系统 `http://192.168.58.20:5320` > **测试日期**: 2025-12-30 --- ## 📋 测试概述 本指南说明如何通过浏览器开发者工具或API工具测试阶段三(部门层级结构)和阶段四(角色枚举扩展)的后端功能。 --- ## 🔧 测试前准备 ### 1. 登录系统 1. 访问 `http://192.168.58.20:5320/login` 2. 使用管理员账号登录 3. 打开浏览器开发者工具(F12) 4. 在 Network 标签页中查看API请求 ### 2. 获取Session Cookie 登录后,在浏览器开发者工具的 Application 标签页中找到: - Cookie: `next-auth.session-token`(或 `__Secure-next-auth.session-token`) - 复制这个cookie值,用于API测试 --- ## 🧪 阶段三测试:部门层级结构 ### 测试1: 获取部门列表(检查新字段) **请求**: ```http GET http://192.168.58.20:5320/api/departments ``` **预期结果**: - 返回部门列表(JSON数组) - 每个部门对象应包含: - `id`: 部门ID - `name`: 部门名称 - `code`: 部门编码(如:DEPT-001) - `parentId`: 父部门ID(如果有) - `level`: 部门层级(1、2、3) - `status`: 部门状态(active/disabled/archived) - `managerId`: 部门负责人ID(如果有) - `description`: 部门描述 - `sortOrder`: 排序字段 **验证点**: - ✅ 所有部门都有 `code` 字段 - ✅ 所有部门都有 `level` 字段(默认1) - ✅ 所有部门都有 `status` 字段(默认active) --- ### 测试2: 创建带父部门的子部门 **请求**: ```http POST http://192.168.58.20:5320/api/departments Content-Type: application/json Cookie: next-auth.session-token=YOUR_SESSION_TOKEN { "name": "测试子部门", "parentId": "父部门ID", "description": "这是测试子部门", "code": "DEPT-TEST-001" } ``` **获取父部门ID的方法**: 1. 先调用 `GET /api/departments` 获取部门列表 2. 选择一个部门的 `id` 作为 `parentId` **预期结果**: - 返回创建的部门对象 - `level` 应该是父部门的 `level + 1` - `parentId` 应该是指定的父部门ID **验证点**: - ✅ 子部门的 `level` 正确(父部门level + 1) - ✅ 子部门的 `parentId` 正确 - ✅ 最多支持3级部门(level <= 3) --- ### 测试3: 创建顶级部门 **请求**: ```http POST http://192.168.58.20:5320/api/departments Content-Type: application/json Cookie: next-auth.session-token=YOUR_SESSION_TOKEN { "name": "测试顶级部门", "description": "这是测试顶级部门", "code": "DEPT-TOP-001" } ``` **预期结果**: - 返回创建的部门对象 - `level` 应该是 1 - `parentId` 应该是 null **验证点**: - ✅ 顶级部门的 `level` 为 1 - ✅ 顶级部门的 `parentId` 为 null --- ### 测试4: 更新部门信息 **请求**: ```http PATCH http://192.168.58.20:5320/api/departments/[部门ID] Content-Type: application/json Cookie: next-auth.session-token=YOUR_SESSION_TOKEN { "description": "更新后的描述", "status": "active", "sortOrder": 10 } ``` **预期结果**: - 返回更新后的部门对象 - 只有指定的字段被更新 **验证点**: - ✅ 更新成功 - ✅ 未指定的字段保持不变 --- ### 测试5: 获取单个部门详情(包含层级关系) **请求**: ```http GET http://192.168.58.20:5320/api/departments/[部门ID] ``` **预期结果**: - 返回部门详情 - 如果部门有父部门或子部门,应该能查询到层级关系 **验证点**: - ✅ 返回完整的部门信息 - ✅ 包含层级相关字段 --- ## 🧪 阶段四测试:角色枚举扩展 ### 测试6: 查看用户列表(检查角色字段) **请求**: ```http GET http://192.168.58.20:5320/api/admin/users Cookie: next-auth.session-token=YOUR_SESSION_TOKEN ``` **预期结果**: - 返回用户列表 - 每个用户的 `role` 字段应该是以下之一: - `USER`: 普通用户 - `ADMIN`: 管理员(向后兼容) - `DEPT_ADMIN`: 部门管理员(阶段四新增) - `SYSTEM_ADMIN`: 系统管理员(阶段四新增) **验证点**: - ✅ 现有用户的角色字段正确 - ✅ API支持新的角色值 --- ### 测试7: 设置用户角色为 DEPT_ADMIN **请求**: ```http POST http://192.168.58.20:5320/api/admin/users/set-role Content-Type: application/json Cookie: next-auth.session-token=YOUR_SESSION_TOKEN { "userId": "用户ID", "role": "DEPT_ADMIN" } ``` **获取用户ID的方法**: 1. 先调用 `GET /api/admin/users` 获取用户列表 2. 选择一个用户的 `id` **预期结果**: - 返回更新后的用户对象 - 用户的 `role` 字段应该是 `DEPT_ADMIN` **验证点**: - ✅ 角色更新成功 - ✅ 新角色 `DEPT_ADMIN` 被正确设置 --- ### 测试8: 设置用户角色为 SYSTEM_ADMIN **请求**: ```http POST http://192.168.58.20:5320/api/admin/users/set-role Content-Type: application/json Cookie: next-auth.session-token=YOUR_SESSION_TOKEN { "userId": "用户ID", "role": "SYSTEM_ADMIN" } ``` **预期结果**: - 返回更新后的用户对象 - 用户的 `role` 字段应该是 `SYSTEM_ADMIN` **验证点**: - ✅ 角色更新成功 - ✅ 新角色 `SYSTEM_ADMIN` 被正确设置 --- ### 测试9: 设置部门管理员 **请求**: ```http POST http://192.168.58.20:5320/api/admin/users/set-department-manager Content-Type: application/json Cookie: next-auth.session-token=YOUR_SESSION_TOKEN { "userId": "用户ID", "departmentId": "部门ID", "isManager": true } ``` **预期结果**: - 用户被设置为部门管理员 - 用户的 `role` 自动更新为 `DEPT_ADMIN`(如果之前是 `USER`) - 部门的 `managerId` 字段更新为该用户ID **验证点**: - ✅ 部门管理员设置成功 - ✅ 用户角色自动更新 - ✅ 部门 `managerId` 字段更新 --- ### 测试10: 取消部门管理员 **请求**: ```http POST http://192.168.58.20:5320/api/admin/users/set-department-manager Content-Type: application/json Cookie: next-auth.session-token=YOUR_SESSION_TOKEN { "userId": "用户ID", "departmentId": "部门ID", "isManager": false } ``` **预期结果**: - 部门管理员被取消 - 部门的 `managerId` 字段更新为 null - 用户角色保持不变(不会自动降级) **验证点**: - ✅ 部门管理员取消成功 - ✅ 部门 `managerId` 字段更新为 null --- ## 🔍 使用浏览器开发者工具测试 ### 方法1: 在Network标签页查看 1. 打开浏览器开发者工具(F12) 2. 切换到 Network 标签页 3. 在系统中进行操作(创建部门、设置角色等) 4. 查看对应的API请求和响应 ### 方法2: 在Console标签页直接调用 ```javascript // 获取部门列表 fetch('/api/departments') .then(r => r.json()) .then(data => console.log('部门列表:', data)); // 创建部门(需要先登录) fetch('/api/departments', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ name: '测试部门', code: 'DEPT-TEST-001' }) }) .then(r => r.json()) .then(data => console.log('创建的部门:', data)); ``` --- ## 📊 测试结果验证 ### 阶段三验证清单 - [ ] 所有部门都有 `code` 字段(100%覆盖率) - [ ] 所有部门都有 `level` 字段(默认1) - [ ] 所有部门都有 `status` 字段(默认active) - [ ] 可以创建带 `parentId` 的子部门 - [ ] 子部门的 `level` 正确(父部门level + 1) - [ ] 最多支持3级部门 - [ ] 可以更新部门的层级信息 ### 阶段四验证清单 - [ ] API支持 `DEPT_ADMIN` 角色 - [ ] API支持 `SYSTEM_ADMIN` 角色 - [ ] 可以设置用户为 `DEPT_ADMIN` - [ ] 可以设置用户为 `SYSTEM_ADMIN` - [ ] 设置部门管理员时,用户角色自动更新 - [ ] 取消部门管理员时,部门 `managerId` 更新为 null - [ ] 权限检查函数正确识别新角色 --- ## ⚠️ 注意事项 1. **认证要求**: 大部分API需要管理员权限,需要先登录获取session token 2. **向后兼容**: `ADMIN` 角色仍然保留,现有代码继续工作 3. **数据完整性**: 测试时注意不要删除重要数据 4. **层级限制**: 部门层级最多3级(level <= 3) --- ## 🎯 快速测试脚本 如果需要快速验证功能,可以使用以下PowerShell脚本: ```powershell # 运行自动化测试(数据库层面) .\scripts\test-api-stages-3-4-shadow.ps1 # 运行完整测试(包括数据库和验证) .\scripts\test-stages-3-4-shadow.ps1 ``` --- ## 📝 测试记录 测试完成后,请记录: - 测试时间 - 测试结果(通过/失败) - 发现的问题 - API响应示例 --- **最后更新**: 2025-12-30