gongxiangp2/docs/api-testing-guide-stages-3-4.md

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: 获取部门列表（检查新字段）

请求:

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: 创建带父部门的子部门

请求:

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: 创建顶级部门

请求:

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: 更新部门信息

请求:

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: 获取单个部门详情（包含层级关系）

请求:

GET http://192.168.58.20:5320/api/departments/[部门ID]

预期结果:

• 返回部门详情
• 如果部门有父部门或子部门，应该能查询到层级关系

验证点:

• ✅ 返回完整的部门信息
• ✅ 包含层级相关字段

---

🧪 阶段四测试：角色枚举扩展

测试6: 查看用户列表（检查角色字段）

请求:

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

请求:

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

请求:

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: 设置部门管理员

请求:

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: 取消部门管理员

请求:

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标签页直接调用

// 获取部门列表
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脚本：

# 运行自动化测试（数据库层面）
.\scripts\test-api-stages-3-4-shadow.ps1

# 运行完整测试（包括数据库和验证）
.\scripts\test-stages-3-4-shadow.ps1

---

📝 测试记录

测试完成后，请记录：

• 测试时间
• 测试结果（通过/失败）
• 发现的问题
• API响应示例

---

最后更新: 2025-12-30