feat(shared,server,web,client,plugin)!: 角色与权限重构 + 学期周次 + 课表方向反转（1.2.0）

学生、任课关系、周次口径三处长期靠约定维持的事情，改为由数据模型保证。学生不是账号 - 拆出独立 Student 表，没有 passwordHash / role / 任何登录字段 - 「学生不能登录」由表结构保证，不再靠「登录前判 role 再 403」的代码分支 - 三张个人数据表外键 userId → studentId；删掉 Enrollment 与 ClassTeacher - 学生一律称「学号」、教师一律称「工号」，「学生账号」这个概念消失任课关系唯一来源 = Course（班级 + 科目 + 教师） - 班主任 = Class.teacherId，科任 = Course.teacherId，同一人两处指向同一账号、不重复建号 - 作业与成绩按科目再收一道：挂科目只由该科任课老师改，没挂科目归班主任 / 管理员 - 新增「任课教师分配」与「班级教师批量导入」（带「使用工号匹配」开关）成绩与名单 - 成绩等级：百分制 / 等级制 A·B·C·D / 自定义，支持单个与批量改等级 - 按学号查成绩明细（教师端 + 班级端 + 设备令牌），受按班开关控制 - 调班 / 转出（单个与批量）+ 可查历史；学号不变、历史作业成绩留原归属 - 毕业归档页（按年度记录毕业班级 / 毕业生 / 转出学生 / 该届通知与作业） - 学年升级（未毕业不归档、数据沿用）；班级称呼改为「2026级1班」 ClassHelper 班级端在线状态 - Web 端显示班级 / 设备名 / 设备号 / 在线离线 / 最后在线 / 最后心跳 - lastHeartbeatAt 驱动 60 秒在线窗口，与只表示「带状态上报」的 lastSeenAt 分开学期周次 - 新增 TermWeek（classId 空串 = 全校默认），管理员可用日期范围选择器逐周配置 - 一键按开学日期生成整学期；联网拉取调休建议（只给建议、不改数据，无外网失败属正常） - 改周次后随课表下发给教室的 ClassHelper 班级端课表方向反转 - 主方向改为「服务端 → 教室」自动下发；教室不再自动回传 - 取教室课表改为手动动作（点击前弹警告），插件按待办标记在下一次心跳补报改名 - 班级小助手 → ClassHelper：界面、窗口标题、托盘、灵动岛、EXE、安装包、安装目录、systemd 描述、插件清单与设置页、官网、文档站、README BREAKING CHANGE: 产品名与 EXE 名变更（班级小助手.exe → ClassHelper.exe），安装目录随之改变，不支持覆盖安装，需先卸载旧版。服务端首次启动会自动应用 6 个数据库迁移（学生行按 id 原样搬迁，历史数据不丢），升级前请先备份。
2026-10-06 19:41:18 +08:00
1 parent 17f55864bf
commit 9d5ac7adf9
@@ -1,4 +1,4 @@
-import { Router } from 'express';
+import { Router } from 'express';
 import { sendCreated, sendOk } from '../../lib/http.js';
 import { idParamSchema } from '../../lib/schemas.js';
 import { authenticate, getAuthUser, requireRole } from '../../middleware/auth.js';
@@ -7,41 +7,114 @@ import { defineModule } from '../module.types.js';
 import {
  createStudentSchema,
  listStudentsQuerySchema,
+  listTransfersQuerySchema,
+  transferOutStudentsSchema,
+  transferStudentsSchema,
  updateStudentSchema,
  type CreateStudentInput,
+  type ListStudentsQuery,
+  type ListTransfersQuery,
+  type TransferOutStudentsInput,
+  type TransferStudentsInput,
  type UpdateStudentInput,
 } from './students.schemas.js';
 import * as studentService from './students.service.js';
+
 const router = Router();
 router.use(authenticate());

 /**
- * GET /api/students?classId=&keyword= - 学生名单
+ * 学生名单。
 *
- * 注意是**仅管理员**（不是教师/管理员）：学生名单自带用户名，而学生初始密码是统一的默认值，
- * 因此名单属于管理员专属数据；教师查看本班学生请用 `GET /api/classes/:id/students`
- * （那条按班级权限校验，班级设备也能读）。
+ * - 学生**没有账号**：这里是"名单记录"的增删改，没有任何密码/角色字段；
+ * - 读：教师/管理员按自己可访问的班级过滤（服务层 `resolveClassScope`）；
+ *   教室机器读本班名单请用 `GET /api/classes/:id/students`；
+ * - 写：管理员或**本班班主任**（服务层逐班判权限），调班与转出仅管理员。
 */
-router.get('/', requireRole('ADMIN'), validate({ query: listStudentsQuerySchema }), async (req, res) => {
-  const user = getAuthUser(req);
-  const query = validatedQuery<{ classId?: string; keyword?: string }>(req);
-  sendOk(res, await studentService.listStudents(user, query), '获取学生列表成功');
-});
+router.get(
+  '/',
+  requireRole('ADMIN', 'TEACHER'),
+  validate({ query: listStudentsQuerySchema }),
+  async (req, res) => {
+    const user = getAuthUser(req);
+    const query = validatedQuery<ListStudentsQuery>(req);
+    sendOk(res, await studentService.listStudents(user, query), '获取学生列表成功');
+  },
+);

-/** POST /api/students - 新建学生账号 */
-router.post('/', requireRole('ADMIN'), validate({ body: createStudentSchema }), async (req, res) => {
-  const user = getAuthUser(req);
-  sendCreated(
-    res,
-    await studentService.createStudent(user, req.body as CreateStudentInput),
-    '学生账号创建成功',
-  );
-});
+/** GET /api/students/transfers - 调班 / 转出历史（管理员看全部，也可按学生或班级过滤） */
+router.get(
+  '/transfers',
+  requireRole('ADMIN', 'TEACHER'),
+  validate({ query: listTransfersQuerySchema }),
+  async (req, res) => {
+    const user = getAuthUser(req);
+    const query = validatedQuery<ListTransfersQuery>(req);
+    sendOk(res, await studentService.listTransfers(user, query), '获取调班历史成功');
+  },
+);
+
+/**
+ * POST /api/students/transfer - 调班（单个与批量同一接口）
+ *
+ * 只改学生当前班级：**学号不变、不创建账号**，原班级/新班级/操作人/时间记入历史；
+ * 历史作业与成绩保留原归属。
+ */
+router.post(
+  '/transfer',
+  requireRole('ADMIN'),
+  validate({ body: transferStudentsSchema }),
+  async (req, res) => {
+    const user = getAuthUser(req);
+    const result = await studentService.transferStudents(user, req.body as TransferStudentsInput);
+    sendOk(res, result, `已调动 ${result.moved} 名学生`);
+  },
+);
+
+/** POST /api/students/transfer-out - 学生转出（学籍离开本校，不是调班） */
+router.post(
+  '/transfer-out',
+  requireRole('ADMIN'),
+  validate({ body: transferOutStudentsSchema }),
+  async (req, res) => {
+    const user = getAuthUser(req);
+    const result = await studentService.transferOutStudents(user, req.body as TransferOutStudentsInput);
+    sendOk(res, result, `已办理 ${result.transferred} 名学生转出`);
+  },
+);
+
+/** GET /api/students/:id/transfers - 单个学生的调班 / 转出历史 */
+router.get(
+  '/:id/transfers',
+  requireRole('ADMIN', 'TEACHER'),
+  validate({ params: idParamSchema }),
+  async (req, res) => {
+    const user = getAuthUser(req);
+    const { id } = validatedParams<{ id: string }>(req);
+    const result = await studentService.listTransfers(user, { studentId: id, pageSize: 200 });
+    sendOk(res, result, '获取该生调班历史成功');
+  },
+);
+
+/** POST /api/students - 新建学生（名单记录，不是账号） */
+router.post(
+  '/',
+  requireRole('ADMIN', 'TEACHER'),
+  validate({ body: createStudentSchema }),
+  async (req, res) => {
+    const user = getAuthUser(req);
+    sendCreated(
+      res,
+      await studentService.createStudent(user, req.body as CreateStudentInput),
+      '学生已加入名单',
+    );
+  },
+);

 /** PATCH /api/students/:id - 修改学生信息 / 调班 */
 router.patch(
  '/:id',
-  requireRole('ADMIN'),
+  requireRole('ADMIN', 'TEACHER'),
  validate({ params: idParamSchema, body: updateStudentSchema }),
  async (req, res) => {
    const user = getAuthUser(req);
@@ -54,13 +127,18 @@ router.patch(
  },
 );

-/** DELETE /api/students - 删除学生名单记录 */
-router.delete('/:id', requireRole('ADMIN'), validate({ params: idParamSchema }), async (req, res) => {
-  const user = getAuthUser(req);
-  const { id } = validatedParams<{ id: string }>(req);
-  await studentService.deleteStudent(user, id);
-  sendOk(res, { id }, '学生账号已删除');
-});
+/** DELETE /api/students/:id - 删除学生名单记录 */
+router.delete(
+  '/:id',
+  requireRole('ADMIN', 'TEACHER'),
+  validate({ params: idParamSchema }),
+  async (req, res) => {
+    const user = getAuthUser(req);
+    const { id } = validatedParams<{ id: string }>(req);
+    await studentService.deleteStudent(user, id);
+    sendOk(res, { id }, '学生记录已删除');
+  },
+);

 export const studentsModule = defineModule({
  name: 'students',