1

API.md

@@ -0,0 +1,489 @@
+# 后台管理API文档
+
+## 基础说明
+
+- **基础URL**: `/api/admin`
+- **认证方式**: Session（与现有后台保持一致）
+- **数据格式**: JSON
+- **字符编码**: UTF-8
+
+## 响应格式
+
+### 成功响应
+```json
+{
+    "code": 200,
+    "message": "操作成功",
+    "data": {}
+}
+```
+
+### 错误响应
+```json
+{
+    "code": 400,
+    "message": "错误信息",
+    "data": null
+}
+```
+
+## 接口列表
+
+### 1. 登录相关
+
+#### 1.1 管理员登录
+- **URL**: `POST /api/admin/login`
+- **说明**: 管理员登录
+- **参数**:
+  - `username` (string, 必填): 用户名
+  - `password` (string, 必填): 密码
+- **返回**: 管理员信息
+
+#### 1.2 获取当前管理员信息
+- **URL**: `GET /api/admin/login/info`
+- **说明**: 获取当前登录的管理员信息
+- **需要登录**: 是
+
+#### 1.3 退出登录
+- **URL**: `POST /api/admin/login/logout`
+- **说明**: 退出登录
+- **需要登录**: 是
+
+### 2. 首页相关
+
+#### 2.1 获取系统信息
+- **URL**: `GET /api/admin/index/systemInfo`
+- **说明**: 获取系统信息（PHP版本、MySQL版本、磁盘空间等）
+- **需要登录**: 是
+
+### 3. 个人信息
+
+#### 3.1 获取个人信息
+- **URL**: `GET /api/admin/profile/info`
+- **说明**: 获取当前管理员个人信息
+- **需要登录**: 是
+
+#### 3.2 更新个人信息
+- **URL**: `POST /api/admin/profile/update`
+- **说明**: 更新个人信息
+- **需要登录**: 是
+- **参数**:
+  - `nickname` (string): 昵称
+  - `email` (string): 邮箱
+  - `avatar` (file): 头像文件（可选）
+
+#### 3.3 修改密码
+- **URL**: `POST /api/admin/profile/updatePassword`
+- **说明**: 修改密码
+- **需要登录**: 是
+- **参数**:
+  - `old_password` (string, 必填): 当前密码
+  - `new_password` (string, 必填): 新密码
+  - `confirm_password` (string, 必填): 确认新密码
+
+### 4. 教室管理
+
+#### 4.1 获取教室列表
+- **URL**: `GET /api/admin/classroom/list`
+- **说明**: 获取教室列表（支持分页和筛选）
+- **需要登录**: 是
+- **参数**:
+  - `page` (int): 页码，默认1
+  - `limit` (int): 每页数量，默认10
+  - `name` (string): 教室名称（模糊搜索）
+  - `building` (string): 楼栋
+  - `type` (string): 教室类型（normal/multimedia/lab）
+  - `school_id` (int): 分校ID（仅超级管理员可用）
+
+#### 4.2 获取教室详情
+- **URL**: `GET /api/admin/classroom/detail`
+- **说明**: 获取教室详细信息
+- **需要登录**: 是
+- **参数**:
+  - `id` (int, 必填): 教室ID
+
+#### 4.3 保存教室（新增/编辑）
+- **URL**: `POST /api/admin/classroom/save`
+- **说明**: 新增或编辑教室
+- **需要登录**: 是
+- **参数**: 教室信息（包含id则为编辑，不包含则为新增）
+
+#### 4.4 删除教室
+- **URL**: `POST /api/admin/classroom/delete`
+- **说明**: 删除教室
+- **需要登录**: 是
+- **参数**:
+  - `id` (int, 必填): 教室ID
+
+#### 4.5 批量删除教室
+- **URL**: `POST /api/admin/classroom/batchDelete`
+- **说明**: 批量删除教室
+- **需要登录**: 是
+- **参数**:
+  - `ids` (array, 必填): 教室ID数组
+
+#### 4.6 保存座位布局
+- **URL**: `POST /api/admin/classroom/saveLayout`
+- **说明**: 保存教室座位布局
+- **需要登录**: 是
+- **参数**:
+  - `id` (int, 必填): 教室ID
+  - `layout` (json, 必填): 布局数据
+
+#### 4.7 获取教室座位状态
+- **URL**: `GET /api/admin/classroom/status`
+- **说明**: 获取教室座位状态（包含预订信息）
+- **需要登录**: 是
+- **参数**:
+  - `id` (int, 必填): 教室ID
+
+#### 4.8 分配座位
+- **URL**: `POST /api/admin/classroom/assignSeat`
+- **说明**: 为学生分配座位
+- **需要登录**: 是
+- **参数**:
+  - `classroomId` (int, 必填): 教室ID
+  - `studentId` (int, 必填): 学生ID
+  - `row` (int, 必填): 行号
+  - `col` (int, 必填): 列号
+  - `number` (string, 必填): 座位号
+
+#### 4.9 随机分配座位
+- **URL**: `POST /api/admin/classroom/randomAssignSeats`
+- **说明**: 为未分配座位的学生随机分配座位
+- **需要登录**: 是
+- **参数**:
+  - `classroomId` (int, 必填): 教室ID
+
+#### 4.10 获取未分配座位的学生列表
+- **URL**: `GET /api/admin/classroom/getUnassignedStudents`
+- **说明**: 获取未分配座位的学生列表
+- **需要登录**: 是
+- **参数**:
+  - `classroomId` (int, 必填): 教室ID
+
+#### 4.11 取消选座
+- **URL**: `POST /api/admin/classroom/cancelBooking`
+- **说明**: 取消选座
+- **需要登录**: 是
+- **参数**:
+  - `id` (int, 必填): 预订ID
+
+#### 4.12 批量取消选座
+- **URL**: `POST /api/admin/classroom/cancelBookingAuto`
+- **说明**: 批量取消选座
+- **需要登录**: 是
+- **参数**:
+  - `ids` (array, 必填): 预订ID数组
+
+#### 4.13 获取分校列表
+- **URL**: `GET /api/admin/classroom/getSchoolList`
+- **说明**: 获取分校列表（根据权限过滤）
+- **需要登录**: 是
+
+#### 4.14 上传图片
+- **URL**: `POST /api/admin/classroom/upload`
+- **说明**: 上传教室相关图片
+- **需要登录**: 是
+- **参数**:
+  - `file` (file, 必填): 图片文件
+
+### 5. 预订管理
+
+#### 5.1 获取预订列表
+- **URL**: `GET /api/admin/booking/list`
+- **说明**: 获取预订记录列表
+- **需要登录**: 是
+- **参数**:
+  - `page` (int): 页码
+  - `limit` (int): 每页数量
+  - `classroom_id` (int): 教室ID
+  - `booking_date` (string): 预订日期
+  - `type` (string): 类型
+
+#### 5.2 同意座位变更申请
+- **URL**: `POST /api/admin/booking/approve`
+- **说明**: 同意座位变更申请
+- **需要登录**: 是
+- **参数**:
+  - `id` (int, 必填): 申请ID
+
+#### 5.3 拒绝座位变更申请
+- **URL**: `POST /api/admin/booking/reject`
+- **说明**: 拒绝座位变更申请
+- **需要登录**: 是
+- **参数**:
+  - `id` (int, 必填): 申请ID
+  - `reason` (string, 必填): 拒绝原因
+
+### 6. 系统设置
+
+#### 6.1 获取系统设置
+- **URL**: `GET /api/admin/setting/get`
+- **说明**: 获取系统设置
+- **需要登录**: 是（仅超级管理员）
+
+#### 6.2 保存系统设置
+- **URL**: `POST /api/admin/setting/save`
+- **说明**: 保存系统设置
+- **需要登录**: 是（仅超级管理员）
+- **参数**: 设置项键值对
+
+#### 6.3 上传图片
+- **URL**: `POST /api/admin/setting/upload`
+- **说明**: 上传系统设置相关图片（如轮播图）
+- **需要登录**: 是（仅超级管理员）
+- **参数**:
+  - `file` (file, 必填): 图片文件
+
+### 7. 班级管理
+
+#### 7.1 获取班级列表
+- **URL**: `GET /api/admin/classmanager/list`
+- **说明**: 获取班级列表
+- **需要登录**: 是
+- **参数**:
+  - `page` (int): 页码
+  - `limit` (int): 每页数量
+  - `name` (string): 班级名称
+  - `teacher_name` (string): 班主任姓名
+  - `school_id` (int): 分校ID
+
+#### 7.2 获取班级详情
+- **URL**: `GET /api/admin/classmanager/detail`
+- **说明**: 获取班级详细信息
+- **需要登录**: 是
+- **参数**:
+  - `id` (int, 必填): 班级ID
+
+#### 7.3 获取班主任列表
+- **URL**: `GET /api/admin/classmanager/getTeachers`
+- **说明**: 获取班主任列表
+- **需要登录**: 是
+
+#### 7.4 获取教室列表
+- **URL**: `GET /api/admin/classmanager/getClassrooms`
+- **说明**: 获取可用教室列表
+- **需要登录**: 是
+
+#### 7.5 保存班级（新增/编辑）
+- **URL**: `POST /api/admin/classmanager/save`
+- **说明**: 新增或编辑班级
+- **需要登录**: 是
+- **参数**: 班级信息
+
+#### 7.6 删除班级
+- **URL**: `POST /api/admin/classmanager/deleteClass`
+- **说明**: 删除班级
+- **需要登录**: 是
+- **参数**:
+  - `id` (int, 必填): 班级ID
+
+### 8. 学生管理
+
+#### 8.1 获取学生列表
+- **URL**: `GET /api/admin/student/list`
+- **说明**: 获取学生列表
+- **需要登录**: 是
+- **参数**:
+  - `page` (int): 页码
+  - `limit` (int): 每页数量
+  - `student_id` (string): 学号
+  - `name` (string): 姓名
+  - `class_id` (int): 班级ID
+  - `school_id` (int): 分校ID
+
+#### 8.2 获取学生详情
+- **URL**: `GET /api/admin/student/detail`
+- **说明**: 获取学生详细信息
+- **需要登录**: 是
+- **参数**:
+  - `id` (int, 必填): 学生ID
+
+#### 8.3 保存学生（新增/编辑）
+- **URL**: `POST /api/admin/student/save`
+- **说明**: 新增或编辑学生
+- **需要登录**: 是
+- **参数**: 学生信息
+
+#### 8.4 删除学生
+- **URL**: `POST /api/admin/student/delete`
+- **说明**: 删除学生
+- **需要登录**: 是
+- **参数**:
+  - `id` (int, 必填): 学生ID
+
+#### 8.5 更新学生状态
+- **URL**: `POST /api/admin/student/status`
+- **说明**: 更新学生状态
+- **需要登录**: 是
+- **参数**:
+  - `id` (int, 必填): 学生ID
+  - `status` (int, 必填): 状态（0/1）
+
+#### 8.6 解绑学生
+- **URL**: `POST /api/admin/student/unbind`
+- **说明**: 解绑学生与用户的关联
+- **需要登录**: 是
+- **参数**:
+  - `id` (int, 必填): 学生ID
+
+#### 8.7 上传学生导入文件
+- **URL**: `POST /api/admin/student/upload`
+- **说明**: 上传学生导入Excel文件
+- **需要登录**: 是
+- **参数**:
+  - `file` (file, 必填): Excel文件
+
+#### 8.8 导入学生数据
+- **URL**: `POST /api/admin/student/import`
+- **说明**: 导入学生数据
+- **需要登录**: 是
+- **参数**:
+  - `class_id` (int, 必填): 班级ID
+  - `file` (string, 必填): 文件路径（通过upload接口获取）
+
+### 9. 用户管理（仅超级管理员）
+
+#### 9.1 获取用户列表
+- **URL**: `GET /api/admin/user/list`
+- **说明**: 获取用户列表
+- **需要登录**: 是（仅超级管理员）
+- **参数**:
+  - `page` (int): 页码
+  - `limit` (int): 每页数量
+  - `keyword` (string): 关键词（昵称/手机/邮箱）
+  - `status` (int): 状态
+
+#### 9.2 获取用户详情
+- **URL**: `GET /api/admin/user/detail`
+- **说明**: 获取用户详细信息
+- **需要登录**: 是（仅超级管理员）
+- **参数**:
+  - `id` (int, 必填): 用户ID
+
+#### 9.3 保存用户（新增/编辑）
+- **URL**: `POST /api/admin/user/save`
+- **说明**: 新增或编辑用户
+- **需要登录**: 是（仅超级管理员）
+- **参数**: 用户信息
+
+#### 9.4 删除用户
+- **URL**: `POST /api/admin/user/delete`
+- **说明**: 删除用户
+- **需要登录**: 是（仅超级管理员）
+- **参数**:
+  - `ids` (array, 必填): 用户ID数组
+
+#### 9.5 修改用户状态
+- **URL**: `POST /api/admin/user/status`
+- **说明**: 修改用户状态
+- **需要登录**: 是（仅超级管理员）
+- **参数**:
+  - `id` (int, 必填): 用户ID
+  - `status` (int, 必填): 状态（0/1）
+
+### 10. 学校管理（仅超级管理员）
+
+#### 10.1 获取学校列表
+- **URL**: `GET /api/admin/school/list`
+- **说明**: 获取学校列表
+- **需要登录**: 是（仅超级管理员）
+- **参数**:
+  - `page` (int): 页码
+  - `limit` (int): 每页数量
+  - `name` (string): 学校名称
+
+#### 10.2 获取学校详情
+- **URL**: `GET /api/admin/school/detail`
+- **说明**: 获取学校详细信息
+- **需要登录**: 是（仅超级管理员）
+- **参数**:
+  - `id` (int, 必填): 学校ID
+
+#### 10.3 保存学校（新增/编辑）
+- **URL**: `POST /api/admin/school/save`
+- **说明**: 新增或编辑学校
+- **需要登录**: 是（仅超级管理员）
+- **参数**: 学校信息
+
+#### 10.4 删除学校
+- **URL**: `POST /api/admin/school/delete`
+- **说明**: 删除学校
+- **需要登录**: 是（仅超级管理员）
+- **参数**:
+  - `id` (int, 必填): 学校ID
+
+#### 10.5 获取分校账号列表
+- **URL**: `GET /api/admin/school/accountList`
+- **说明**: 获取分校账号列表
+- **需要登录**: 是（仅超级管理员）
+- **参数**:
+  - `school_id` (int, 必填): 学校ID
+
+#### 10.6 保存分校账号
+- **URL**: `POST /api/admin/school/saveAccount`
+- **说明**: 新增或编辑分校账号
+- **需要登录**: 是（仅超级管理员）
+- **参数**: 账号信息
+
+#### 10.7 删除分校账号
+- **URL**: `POST /api/admin/school/deleteAccount`
+- **说明**: 删除分校账号
+- **需要登录**: 是（仅超级管理员）
+- **参数**:
+  - `id` (int, 必填): 账号ID
+
+### 11. 教师管理
+
+#### 11.1 获取教师列表
+- **URL**: `GET /api/admin/teacher/list`
+- **说明**: 获取教师列表
+- **需要登录**: 是
+- **参数**:
+  - `page` (int): 页码
+  - `limit` (int): 每页数量
+  - `teacher_id` (string): 工号
+  - `name` (string): 姓名
+  - `department_id` (int): 部门ID
+  - `nickname` (string): 昵称
+
+#### 11.2 获取教师详情
+- **URL**: `GET /api/admin/teacher/detail`
+- **说明**: 获取教师详细信息
+- **需要登录**: 是
+- **参数**:
+  - `id` (int, 必填): 教师ID
+
+#### 11.3 保存教师（新增/编辑）
+- **URL**: `POST /api/admin/teacher/save`
+- **说明**: 新增或编辑教师
+- **需要登录**: 是
+- **参数**: 教师信息
+
+#### 11.4 删除教师
+- **URL**: `POST /api/admin/teacher/delete`
+- **说明**: 删除教师
+- **需要登录**: 是
+- **参数**:
+  - `id` (int, 必填): 教师ID
+
+### 12. 通用功能
+
+#### 12.1 获取必应每日壁纸
+- **URL**: `GET /api/admin/common/getBingWallpaper`
+- **说明**: 获取必应每日桌面壁纸
+- **需要登录**: 是
+
+## 权限说明
+
+- **超级管理员**: 可以访问所有接口，可以管理所有分校的数据
+- **分校管理员**: 只能访问和操作本分校的数据，无法访问系统设置、用户管理、学校管理等接口
+
+## 注意事项
+
+1. 所有需要登录的接口都需要在请求时携带有效的Session
+2. 分校管理员在操作数据时，系统会自动限制只能操作本分校的数据
+3. 文件上传接口支持的文件类型和大小限制请参考具体接口说明
+4. 分页接口默认返回格式为layui table格式（code, msg, count, data）
+