2026-09-12 15:51:08 +08:00
|
|
|
import { Router } from 'express';
|
2026-10-23 22:55:21 +08:00
|
|
|
import { ApiError, sendCreated, sendOk } from '../../lib/http.js';
|
2026-09-11 21:57:38 +08:00
|
|
|
import { idParamSchema } from '../../lib/schemas.js';
|
2026-10-23 22:55:21 +08:00
|
|
|
import {
|
|
|
|
|
authenticate,
|
|
|
|
|
getAuthUser,
|
2026-10-31 09:40:23 +08:00
|
|
|
requirePermissionOrClassDevice,
|
2026-10-23 22:55:21 +08:00
|
|
|
requirePermission,
|
2026-10-31 09:40:23 +08:00
|
|
|
requireAdmin,
|
2026-10-23 22:55:21 +08:00
|
|
|
} from '../../middleware/auth.js';
|
2026-10-17 03:06:46 +08:00
|
|
|
import { validate, validatedBody, validatedParams, validatedQuery } from '../../middleware/validate.js';
|
2026-09-11 21:57:38 +08:00
|
|
|
import { defineModule } from '../module.types.js';
|
|
|
|
|
import {
|
|
|
|
|
addStudentSchema,
|
2026-09-13 10:34:46 +08:00
|
|
|
assignHeadTeacherSchema,
|
2026-10-06 19:41:18 +08:00
|
|
|
assignSubjectTeachersSchema,
|
2026-09-11 21:57:38 +08:00
|
|
|
classStudentParamSchema,
|
|
|
|
|
createClassSchema,
|
|
|
|
|
listClassesQuerySchema,
|
2026-10-06 19:41:18 +08:00
|
|
|
promoteClassesSchema,
|
2026-09-12 15:51:08 +08:00
|
|
|
updateClassAccountSchema,
|
2026-11-18 17:46:26 +08:00
|
|
|
updateClassIslandLayoutSchema,
|
2026-09-11 21:57:38 +08:00
|
|
|
updateClassSchema,
|
2026-10-31 09:40:23 +08:00
|
|
|
updateClassSettingsSchema,
|
|
|
|
|
type UpdateClassSettingsInput,
|
2026-10-06 19:41:18 +08:00
|
|
|
updateStudentGradeQuerySchema,
|
2026-09-11 21:57:38 +08:00
|
|
|
type AddStudentInput,
|
2026-10-06 19:41:18 +08:00
|
|
|
type AssignSubjectTeachersInput,
|
2026-09-11 21:57:38 +08:00
|
|
|
type CreateClassInput,
|
2026-09-12 15:51:08 +08:00
|
|
|
type UpdateClassAccountInput,
|
2026-11-18 17:46:26 +08:00
|
|
|
type UpdateClassIslandLayoutInput,
|
2026-09-11 21:57:38 +08:00
|
|
|
type UpdateClassInput,
|
2026-10-06 19:41:18 +08:00
|
|
|
type UpdateStudentGradeQueryInput,
|
2026-09-11 21:57:38 +08:00
|
|
|
} from './classes.schemas.js';
|
|
|
|
|
import * as classService from './classes.service.js';
|
|
|
|
|
|
|
|
|
|
const router = Router();
|
|
|
|
|
|
|
|
|
|
// 班级相关接口统一需要登录
|
|
|
|
|
router.use(authenticate());
|
|
|
|
|
|
2026-10-06 19:41:18 +08:00
|
|
|
/**
|
|
|
|
|
* GET /api/classes - 班级列表
|
|
|
|
|
*
|
|
|
|
|
* 只列**在读**班级(毕业归档的班级属于「归档管理」页);
|
|
|
|
|
* 教师/管理员看自己可访问的班级(班主任 ∪ 任课),ClassHelper 班级端看自己绑定的那个。
|
|
|
|
|
*/
|
2026-10-23 22:55:21 +08:00
|
|
|
router.get(
|
|
|
|
|
'/',
|
2026-10-31 09:40:23 +08:00
|
|
|
requirePermissionOrClassDevice('class:read'),
|
2026-10-23 22:55:21 +08:00
|
|
|
validate({ query: listClassesQuerySchema }),
|
|
|
|
|
async (req, res) => {
|
|
|
|
|
const user = getAuthUser(req);
|
|
|
|
|
const { keyword } = validatedQuery<{ keyword?: string }>(req);
|
|
|
|
|
sendOk(res, await classService.listClasses(user, keyword), '获取班级列表成功');
|
|
|
|
|
},
|
|
|
|
|
);
|
2026-09-11 21:57:38 +08:00
|
|
|
|
2026-10-06 19:41:18 +08:00
|
|
|
/**
|
2026-10-23 22:55:21 +08:00
|
|
|
* POST /api/classes/promote - 学年升级(批量改年级,按功能权限及范围校验)
|
2026-10-06 19:41:18 +08:00
|
|
|
*
|
|
|
|
|
* **升级不归档、数据沿用**:只改 `grade`(高一 → 高二),班级记录、学生名单、学号、
|
2026-10-23 22:55:21 +08:00
|
|
|
* 作业与成绩全部原样。毕业归档只由年度升级执行。
|
2026-10-06 19:41:18 +08:00
|
|
|
*/
|
|
|
|
|
router.post(
|
|
|
|
|
'/promote',
|
2026-10-31 09:40:23 +08:00
|
|
|
requireAdmin(),
|
2026-10-23 22:55:21 +08:00
|
|
|
requirePermission('promotion:manage'),
|
2026-10-06 19:41:18 +08:00
|
|
|
validate({ body: promoteClassesSchema }),
|
|
|
|
|
async (req, res) => {
|
|
|
|
|
const user = getAuthUser(req);
|
2026-10-23 22:55:21 +08:00
|
|
|
const body = validatedBody<{ classIds: string[] }>(req);
|
2026-10-06 19:41:18 +08:00
|
|
|
sendOk(res, await classService.promoteClasses(user, body), '班级已升级,数据继续沿用');
|
|
|
|
|
},
|
|
|
|
|
);
|
|
|
|
|
|
|
|
|
|
/** GET /api/classes/:id - 班级详情(学生名单 + 课程 + 班主任 + 各科任课老师) */
|
2026-10-23 22:55:21 +08:00
|
|
|
router.get(
|
|
|
|
|
'/:id',
|
2026-10-31 09:40:23 +08:00
|
|
|
requirePermissionOrClassDevice('class:read'),
|
2026-10-23 22:55:21 +08:00
|
|
|
validate({ params: idParamSchema }),
|
|
|
|
|
async (req, res) => {
|
|
|
|
|
const user = getAuthUser(req);
|
|
|
|
|
const { id } = validatedParams<{ id: string }>(req);
|
|
|
|
|
sendOk(res, await classService.getClassDetail(user, id), '获取班级详情成功');
|
|
|
|
|
},
|
|
|
|
|
);
|
2026-09-11 21:57:38 +08:00
|
|
|
|
2026-10-06 19:41:18 +08:00
|
|
|
/** POST /api/classes - 创建班级(称呼由入学年份 + 班号生成,如「2026级1班」) */
|
2026-10-17 03:06:46 +08:00
|
|
|
router.post(
|
|
|
|
|
'/',
|
2026-10-31 09:40:23 +08:00
|
|
|
requireAdmin(),
|
2026-10-17 03:06:46 +08:00
|
|
|
requirePermission('class:manage'),
|
|
|
|
|
validate({ body: createClassSchema }),
|
|
|
|
|
async (req, res) => {
|
|
|
|
|
const user = getAuthUser(req);
|
|
|
|
|
sendCreated(res, await classService.createClass(user, req.body as CreateClassInput), '班级创建成功');
|
|
|
|
|
},
|
|
|
|
|
);
|
2026-09-11 21:57:38 +08:00
|
|
|
|
2026-10-23 22:55:21 +08:00
|
|
|
/** PATCH /api/classes/:id - 编辑班级(年级 / 届别 / 教学周数),按功能权限及范围校验 */
|
2026-09-11 21:57:38 +08:00
|
|
|
router.patch(
|
|
|
|
|
'/:id',
|
2026-10-31 09:40:23 +08:00
|
|
|
requireAdmin(),
|
2026-10-11 11:49:32 +08:00
|
|
|
requirePermission('class:manage'),
|
2026-10-23 22:55:21 +08:00
|
|
|
(req, _res, next) => {
|
|
|
|
|
if (req.body && 'grade' in req.body) return next(ApiError.badRequest('年级请通过学年升级入口修改'));
|
|
|
|
|
next();
|
|
|
|
|
},
|
2026-09-11 21:57:38 +08:00
|
|
|
validate({ params: idParamSchema, body: updateClassSchema }),
|
|
|
|
|
async (req, res) => {
|
|
|
|
|
const user = getAuthUser(req);
|
|
|
|
|
const { id } = validatedParams<{ id: string }>(req);
|
|
|
|
|
sendOk(res, await classService.updateClass(user, id, req.body as UpdateClassInput), '班级更新成功');
|
|
|
|
|
},
|
|
|
|
|
);
|
|
|
|
|
|
2026-10-31 09:40:23 +08:00
|
|
|
router.patch(
|
|
|
|
|
'/:id/settings',
|
|
|
|
|
requirePermission('class:settings'),
|
|
|
|
|
validate({ params: idParamSchema, body: updateClassSettingsSchema }),
|
|
|
|
|
async (req, res) => {
|
|
|
|
|
sendOk(
|
|
|
|
|
res,
|
|
|
|
|
await classService.updateClassSettings(
|
|
|
|
|
getAuthUser(req),
|
|
|
|
|
String(req.params.id),
|
|
|
|
|
validatedBody<UpdateClassSettingsInput>(req),
|
|
|
|
|
),
|
|
|
|
|
);
|
|
|
|
|
},
|
|
|
|
|
);
|
2026-11-18 17:46:26 +08:00
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* GET /api/classes/:id/island-layout - 班级级灵动岛方案(班级端可只读本班)
|
|
|
|
|
* PATCH 同路径 - Web 管理端保存;仅本班班主任或管理员,班级端不可写
|
|
|
|
|
*/
|
|
|
|
|
router.get(
|
|
|
|
|
'/:id/island-layout',
|
|
|
|
|
requirePermissionOrClassDevice('class:read'),
|
|
|
|
|
validate({ params: idParamSchema }),
|
|
|
|
|
async (req, res) => {
|
|
|
|
|
const user = getAuthUser(req);
|
|
|
|
|
const { id } = validatedParams<{ id: string }>(req);
|
|
|
|
|
sendOk(res, await classService.getClassIslandLayout(user, id), '获取班级灵动岛方案成功');
|
|
|
|
|
},
|
|
|
|
|
);
|
|
|
|
|
|
|
|
|
|
router.patch(
|
|
|
|
|
'/:id/island-layout',
|
|
|
|
|
requirePermission('class:settings'),
|
|
|
|
|
validate({ params: idParamSchema, body: updateClassIslandLayoutSchema }),
|
|
|
|
|
async (req, res) => {
|
|
|
|
|
const user = getAuthUser(req);
|
|
|
|
|
const { id } = validatedParams<{ id: string }>(req);
|
|
|
|
|
sendOk(
|
|
|
|
|
res,
|
|
|
|
|
await classService.updateClassIslandLayout(user, id, validatedBody<UpdateClassIslandLayoutInput>(req)),
|
|
|
|
|
'班级灵动岛方案已保存',
|
|
|
|
|
);
|
|
|
|
|
},
|
|
|
|
|
);
|
2026-09-11 21:57:38 +08:00
|
|
|
/** DELETE /api/classes/:id - 删除班级 */
|
|
|
|
|
router.delete(
|
|
|
|
|
'/:id',
|
2026-10-31 09:40:23 +08:00
|
|
|
requireAdmin(),
|
2026-10-11 11:49:32 +08:00
|
|
|
requirePermission('class:manage'),
|
2026-09-11 21:57:38 +08:00
|
|
|
validate({ params: idParamSchema }),
|
|
|
|
|
async (req, res) => {
|
|
|
|
|
const user = getAuthUser(req);
|
|
|
|
|
const { id } = validatedParams<{ id: string }>(req);
|
|
|
|
|
await classService.deleteClass(user, id);
|
|
|
|
|
sendOk(res, { id }, '班级已删除');
|
|
|
|
|
},
|
|
|
|
|
);
|
|
|
|
|
|
2026-09-12 15:51:08 +08:00
|
|
|
/**
|
|
|
|
|
* PATCH /api/classes/:id/class-account - 设置 / 重置班级账号(班级码 + 班级密码)
|
2026-10-23 22:55:21 +08:00
|
|
|
* 按功能权限及范围校验:教室机器「ClassHelper 班级端」登录用的就是这个班级码
|
2026-09-12 15:51:08 +08:00
|
|
|
*/
|
|
|
|
|
router.patch(
|
|
|
|
|
'/:id/class-account',
|
2026-10-31 09:40:23 +08:00
|
|
|
requirePermission('class:account'),
|
2026-09-12 15:51:08 +08:00
|
|
|
validate({ params: idParamSchema, body: updateClassAccountSchema }),
|
|
|
|
|
async (req, res) => {
|
|
|
|
|
const user = getAuthUser(req);
|
|
|
|
|
const { id } = validatedParams<{ id: string }>(req);
|
|
|
|
|
sendOk(
|
|
|
|
|
res,
|
|
|
|
|
await classService.updateClassAccount(user, id, req.body as UpdateClassAccountInput),
|
|
|
|
|
'班级账号已更新',
|
|
|
|
|
);
|
|
|
|
|
},
|
|
|
|
|
);
|
|
|
|
|
|
2026-09-13 10:34:46 +08:00
|
|
|
/**
|
2026-10-06 19:41:18 +08:00
|
|
|
* PATCH /api/classes/:id/head-teacher - 设置 / 更改班主任(每班 1 人)
|
2026-10-23 22:55:21 +08:00
|
|
|
* 按功能权限及范围校验:班主任决定谁能管这个班的学生名单与课表,属于人员分配权限
|
2026-09-13 10:34:46 +08:00
|
|
|
*/
|
|
|
|
|
router.patch(
|
|
|
|
|
'/:id/head-teacher',
|
2026-10-31 09:40:23 +08:00
|
|
|
requireAdmin(),
|
2026-10-11 11:49:32 +08:00
|
|
|
requirePermission('class:manage'),
|
2026-09-13 10:34:46 +08:00
|
|
|
validate({ params: idParamSchema, body: assignHeadTeacherSchema }),
|
|
|
|
|
async (req, res) => {
|
|
|
|
|
const user = getAuthUser(req);
|
|
|
|
|
const { id } = validatedParams<{ id: string }>(req);
|
|
|
|
|
const { teacherId } = req.body as { teacherId: string };
|
|
|
|
|
sendOk(res, await classService.updateHeadTeacher(user, id, teacherId), '班主任已更新');
|
|
|
|
|
},
|
|
|
|
|
);
|
|
|
|
|
|
2026-09-27 16:34:01 +08:00
|
|
|
/**
|
2026-10-06 19:41:18 +08:00
|
|
|
* PUT /api/classes/:id/subject-teachers - 设置各科任课老师(班级 + 科目 + 教师)
|
2026-09-27 16:34:01 +08:00
|
|
|
*
|
2026-10-23 22:55:21 +08:00
|
|
|
* 按功能权限及范围校验。这是「科任老师」这条关系的唯一写入口 —— 作业与成绩能不能被某位老师改动,
|
2026-10-06 19:41:18 +08:00
|
|
|
* 查的就是这里写下的 `Course.teacherId`。
|
|
|
|
|
* 班主任同时是某科科任老师时,两条记录指向同一个账号:不重复建号、权限自动合并。
|
|
|
|
|
*/
|
|
|
|
|
router.put(
|
|
|
|
|
'/:id/subject-teachers',
|
2026-10-31 09:40:23 +08:00
|
|
|
requireAdmin(),
|
2026-10-11 11:49:32 +08:00
|
|
|
requirePermission('class:manage'),
|
2026-10-06 19:41:18 +08:00
|
|
|
validate({ params: idParamSchema, body: assignSubjectTeachersSchema }),
|
|
|
|
|
async (req, res) => {
|
|
|
|
|
const user = getAuthUser(req);
|
|
|
|
|
const { id } = validatedParams<{ id: string }>(req);
|
|
|
|
|
sendOk(
|
|
|
|
|
res,
|
|
|
|
|
await classService.assignSubjectTeachers(user, id, validatedBody<AssignSubjectTeachersInput>(req)),
|
|
|
|
|
'任课老师已更新',
|
|
|
|
|
);
|
|
|
|
|
},
|
|
|
|
|
);
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* GET /api/classes/:id/student-grade-query - 本班是否允许班级端按学号查成绩明细
|
2026-10-17 03:06:46 +08:00
|
|
|
* PATCH 同路径 - 教师/管理员按班级管理权限设置,班级端只读
|
2026-10-06 19:41:18 +08:00
|
|
|
*/
|
2026-10-23 22:55:21 +08:00
|
|
|
router.get(
|
|
|
|
|
'/:id/student-grade-query',
|
2026-10-31 09:40:23 +08:00
|
|
|
requirePermissionOrClassDevice('class:read'),
|
2026-10-23 22:55:21 +08:00
|
|
|
validate({ params: idParamSchema }),
|
|
|
|
|
async (req, res) => {
|
|
|
|
|
const user = getAuthUser(req);
|
|
|
|
|
const { id } = validatedParams<{ id: string }>(req);
|
|
|
|
|
sendOk(res, await classService.getStudentGradeQuery(user, id), '获取成绩查询开关成功');
|
|
|
|
|
},
|
|
|
|
|
);
|
2026-09-11 21:57:38 +08:00
|
|
|
|
2026-10-06 19:41:18 +08:00
|
|
|
router.patch(
|
|
|
|
|
'/:id/student-grade-query',
|
2026-10-23 22:55:21 +08:00
|
|
|
requirePermission('grade:write'),
|
2026-10-06 19:41:18 +08:00
|
|
|
validate({ params: idParamSchema, body: updateStudentGradeQuerySchema }),
|
2026-09-11 21:57:38 +08:00
|
|
|
async (req, res) => {
|
|
|
|
|
const user = getAuthUser(req);
|
|
|
|
|
const { id } = validatedParams<{ id: string }>(req);
|
2026-10-06 19:41:18 +08:00
|
|
|
sendOk(
|
|
|
|
|
res,
|
2026-10-17 03:06:46 +08:00
|
|
|
await classService.updateStudentGradeQuery(user, id, validatedBody<UpdateStudentGradeQueryInput>(req)),
|
2026-10-06 19:41:18 +08:00
|
|
|
'成绩查询开关已更新',
|
|
|
|
|
);
|
2026-09-11 21:57:38 +08:00
|
|
|
},
|
|
|
|
|
);
|
|
|
|
|
|
2026-10-06 19:41:18 +08:00
|
|
|
/** GET /api/classes/:id/students - 班级学生名单 */
|
2026-10-23 22:55:21 +08:00
|
|
|
router.get(
|
|
|
|
|
'/:id/students',
|
2026-10-31 09:40:23 +08:00
|
|
|
requirePermissionOrClassDevice('roster:read'),
|
2026-10-23 22:55:21 +08:00
|
|
|
validate({ params: idParamSchema }),
|
|
|
|
|
async (req, res) => {
|
|
|
|
|
const user = getAuthUser(req);
|
|
|
|
|
const { id } = validatedParams<{ id: string }>(req);
|
|
|
|
|
sendOk(res, await classService.listClassStudents(user, id), '获取学生名单成功');
|
|
|
|
|
},
|
|
|
|
|
);
|
2026-09-11 21:57:38 +08:00
|
|
|
|
2026-10-06 19:41:18 +08:00
|
|
|
/** POST /api/classes/:id/students - 把学生加入班级(按学号,已存在则转入并留调班痕迹) */
|
2026-09-11 21:57:38 +08:00
|
|
|
router.post(
|
2026-10-06 19:41:18 +08:00
|
|
|
'/:id/students',
|
2026-10-11 11:49:32 +08:00
|
|
|
requirePermission('roster:manage'),
|
2026-10-06 19:41:18 +08:00
|
|
|
validate({ params: idParamSchema, body: addStudentSchema }),
|
2026-09-11 21:57:38 +08:00
|
|
|
async (req, res) => {
|
|
|
|
|
const user = getAuthUser(req);
|
|
|
|
|
const { id } = validatedParams<{ id: string }>(req);
|
2026-10-06 19:41:18 +08:00
|
|
|
sendCreated(res, await classService.addStudent(user, id, req.body as AddStudentInput), '学生已加入班级');
|
2026-09-11 21:57:38 +08:00
|
|
|
},
|
|
|
|
|
);
|
|
|
|
|
|
2026-10-06 19:41:18 +08:00
|
|
|
/** DELETE /api/classes/:id/students/:studentId - 移出学生(回到「未分班」,名单记录保留) */
|
2026-09-11 21:57:38 +08:00
|
|
|
router.delete(
|
2026-10-06 19:41:18 +08:00
|
|
|
'/:id/students/:studentId',
|
2026-10-11 11:49:32 +08:00
|
|
|
requirePermission('roster:manage'),
|
2026-10-06 19:41:18 +08:00
|
|
|
validate({ params: classStudentParamSchema }),
|
2026-09-11 21:57:38 +08:00
|
|
|
async (req, res) => {
|
|
|
|
|
const user = getAuthUser(req);
|
2026-10-06 19:41:18 +08:00
|
|
|
const { id, studentId } = validatedParams<{ id: string; studentId: string }>(req);
|
|
|
|
|
await classService.removeStudent(user, id, studentId);
|
|
|
|
|
sendOk(res, { classId: id, studentId }, '学生已移出班级');
|
2026-09-11 21:57:38 +08:00
|
|
|
},
|
|
|
|
|
);
|
|
|
|
|
|
|
|
|
|
export const classesModule = defineModule({
|
|
|
|
|
name: 'classes',
|
|
|
|
|
basePath: '/classes',
|
|
|
|
|
router,
|
|
|
|
|
});
|