用户管理 API 快速参考

快速了解用户管理API的主要端点和使用方法

---

🚀 快速开始

认证方式

# 所有API都需要在请求头中携带JWT Token
Authorization: Bearer <your_jwt_token>

基础URL

http://localhost:8000

---

📋 主要端点概览

用户查询

端点	方法	权限要求	说明
/users	GET	老师/学校管理员/平台管理员	通用用户查询
/users/students	GET	老师/学校管理员/平台管理员	获取学生列表
/users/teachers	GET	学校管理员/平台管理员	获取教师列表
/users/school_admins	GET	平台管理员	获取学校管理员列表
/users/platform_admins	GET	平台管理员	获取平台管理员列表
/users/{user_id}	GET	根据角色限制	获取用户详情

用户管理

端点	方法	权限要求	说明
/schools/{school_id}/users:student	POST	学校管理员/平台管理员	创建学生账号
/schools/{school_id}/users:teacher	POST	学校管理员/平台管理员	创建教师账号
/schools/{school_id}/users:school_admin	POST	平台管理员	创建学校管理员
/users/{user_id}	PUT	根据角色限制	更新用户信息
/users/{user_id}:reset_password	POST	根据角色限制	重置用户密码
/users/{user_id}:status	POST	学校管理员/平台管理员	启用/禁用账号
/users/{user_id}	DELETE	根据角色限制	删除用户

班级管理

端点	方法	权限要求	说明
/classes/{class_id}/members	GET	班级教师/学校管理员/平台管理员	获取班级成员
/classes/{class_id}/members	POST	班级教师/学校管理员/平台管理员	添加班级成员
/classes/{class_id}/members/{user_id}	DELETE	班级教师/学校管理员/平台管理员	移除班级成员
/classes/{class_id}/teachers	GET	班级教师/学校管理员/平台管理员	获取班级教师
/classes/{class_id}/teachers	POST	学校管理员/平台管理员	指派班级教师
/classes/{class_id}/teachers/{teacher_id}	DELETE	学校管理员/平台管理员	移除班级教师

学校管理

端点	方法	权限要求	说明
/schools	GET	学校管理员/平台管理员	获取学校列表
/schools	POST	平台管理员	创建学校
/schools/{school_id}	PUT	学校管理员/平台管理员	更新学校信息
/schools/{school_id}	DELETE	平台管理员	删除学校
/schools/{school_id}/admins	GET	平台管理员	获取学校管理员
/schools/{school_id}/admins	POST	平台管理员	指派学校管理员
/schools/{school_id}/admins/{user_id}	DELETE	平台管理员	撤销学校管理员

---

💡 常用操作示例

1. 创建学生账号

curl -X POST "http://localhost:8000/schools/1/users:student" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "student001",
    "password": "Init@123",
    "real_name": "张三",
    "class_ids": [1, 2]
  }'

2. 获取学生列表

# 老师获取本班学生
curl -X GET "http://localhost:8000/users/students?class_id=1&page=1&size=20" \
  -H "Authorization: Bearer <token>"

# 学校管理员获取本校学生
curl -X GET "http://localhost:8000/users/students?school_id=1&page=1&size=20" \
  -H "Authorization: Bearer <token>"

3. 重置用户密码

curl -X POST "http://localhost:8000/users/123:reset_password" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"new_password": "NewPass@123"}'

4. 添加班级成员

curl -X POST "http://localhost:8000/classes/1/members" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"user_ids": [1, 2, 3]}'

---

🔐 权限说明

角色权限矩阵

操作	学生	老师	学校管理员	平台管理员
查看自己信息	✅	✅	✅	✅
查看本班学生	❌	✅	✅	✅
查看本校用户	❌	❌	✅	✅
查看全平台用户	❌	❌	❌	✅
创建学生账号	❌	❌	✅	✅
创建教师账号	❌	❌	✅	✅
创建学校管理员	❌	❌	❌	✅
管理学校	❌	❌	❌	✅

作用域限制

• 学生：只能访问自己的信息
• 老师：只能管理任教班级的学生
• 学校管理员：只能管理本校的用户和班级
• 平台管理员：可以管理全平台的用户和学校

---

⚠️ 注意事项

安全要求

1. 所有API都需要JWT认证
2. 密码必须符合复杂度要求（8位以上，包含大小写字母、数字、特殊字符）
3. 敏感操作会记录审计日志

数据限制

1. 用户名必须唯一
2. 删除用户前会检查关联数据
3. 建议使用软删除（禁用账号）而不是硬删除

性能考虑

1. 大量数据查询时使用分页
2. 支持按角色、学校、班级等条件筛选
3. 支持模糊搜索用户名和真实姓名

---

📚 相关文档

• 完整API设计文档
• 数据库设计文档
• 认证授权文档
• 课程管理API

---

🆘 常见问题

Q: 如何获取用户的上级信息？

A: 通过 parent_user_id 字段可以知道用户的直接上级，形成权限继承链。

Q: 学生可以自己修改密码吗？

A: 学生不能直接修改密码，需要通过老师或管理员重置。

Q: 如何批量导入用户？

A: 可以通过批量调用创建用户API，或使用班级成员批量添加功能。

Q: 删除学校前需要做什么？

A: 需要先删除或迁移学校下的所有用户和班级，确保没有关联数据。