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 原样搬迁,历史数据不丢),
升级前请先备份。
This commit is contained in:
LoveChengke committed 2026-10-06 19:41:18 +08:00
1 parent 17f55864bf
commit 9d5ac7adf9
172 files changed
+8761 -1896

No files matched your search

@@ -11,7 +11,7 @@ const dayKeySchema = z
export const listHomeworksQuerySchema = z.object({
classId: z.string().min(1).optional(),
courseId: z.string().min(1).optional(),
/** 学生端:只看未完成 */
/** ClassHelper 班级端:只看未完成 */
pendingOnly: booleanFlagSchema,
keyword: z.string().trim().max(64).optional(),
/** 只看某一天的作业(按 Homework.assignDate,本地日期) */
@@ -48,13 +48,16 @@ export const updateHomeworkSchema = z.object({
export const updateHomeworkStatusSchema = z.object({
completed: z.boolean(),
/** 教师代学生标记时使用;学生只能标记自己 */
userId: z.string().min(1).optional(),
/**
* 教师代学生标记时必填(学生不是账号,必须显式指定本班学生);
* ClassHelper 班级端**不要传** —— 它代全班标记。
*/
studentId: z.string().min(1).optional(),
});
/** 保存"未交名单":列出未交的学生 id(其余学生一律标记为已交) */
export const updateHomeworkSubmissionsSchema = z.object({
notSubmittedUserIds: z.array(z.string().min(1)).max(200).default([]),
notSubmittedStudentIds: z.array(z.string().min(1)).max(500).default([]),
});
export type ListHomeworkDaysInput = z.infer<typeof listHomeworkDaysQuerySchema>;
@@ -9,22 +9,17 @@ import {
type HomeworkSubmissionsDto,
} from '@classhelper/shared';
import {
assertCanPublishContent,
assertCanManageSubjectContent,
assertClassAccess,
classScopeWhere,
isStudent,
isClassDevice,
resolveClassScope,
} from '../../lib/access.js';
import { prisma } from '../../lib/db.js';
import { ApiError } from '../../lib/http.js';
import type { TokenPayload } from '../../lib/jwt.js';
import { toHomeworkDto, toHomeworkStatusDto } from '../../lib/mappers.js';
import {
classSessionClassId,
isClassSession,
personalIdWhere,
resolvePersonalIds,
} from '../../lib/session.js';
import { personalIdWhere, resolvePersonalIds } from '../../lib/session.js';
import { emitToClass } from '../../realtime/bus.js';
import type {
CreateHomeworkInput,
@@ -47,7 +42,7 @@ export interface ListHomeworkOptions {
/**
* 作业列表。
* - 学生:附带自己的完成状态,可通过 pendingOnly 只看未完成
* - ClassHelper 班级端:附带本班的完成情况,可通过 pendingOnly 只看未完成
* - 教师/管理员:附带完成人数统计
*/
export async function listHomeworks(
@@ -55,9 +50,9 @@ export async function listHomeworks(
options: ListHomeworkOptions,
): Promise<HomeworkDto[]> {
const scope = await resolveClassScope(user, options.classId);
const student = isStudent(user);
// 班级账号(班级设备)以全班学生为范围;普通学生即自己
const personalIds = student ? await resolvePersonalIds(user) : [];
const device = isClassDevice(user);
// ClassHelper 班级端以全班学生为范围;教师/管理员没有"自己的完成状态"
const personalIds = device ? await resolvePersonalIds(user) : [];
const personalWhere = personalIdWhere(personalIds);
const homeworks = await prisma.homework.findMany({
@@ -67,7 +62,7 @@ export async function listHomeworks(
...(options.keyword
? { OR: [{ title: { contains: options.keyword } }, { content: { contains: options.keyword } }] }
: {}),
...(student && options.pendingOnly
...(device && options.pendingOnly
? { statuses: { none: { ...personalWhere, completed: true } } }
: {}),
// 按天查看:作业「属于哪一天」看 assignDate(本地日期),不是 createdAt
@@ -76,14 +71,14 @@ export async function listHomeworks(
include: {
course: courseSelect,
creator: creatorSelect,
statuses: student ? { where: personalWhere } : true,
statuses: device ? { where: personalWhere } : true,
},
orderBy: [{ assignDate: 'desc' }, { createdAt: 'desc' }],
take: 200,
});
return homeworks.map((item) =>
toHomeworkDto(item, { userIds: student ? personalIds : [], withStatus: !student }),
toHomeworkDto(item, { studentIds: device ? personalIds : [], withStatus: !device }),
);
}
@@ -118,44 +113,48 @@ export async function listHomeworkDays(
.sort((a, b) => a.date.localeCompare(b.date)),
};
}
export async function getHomework(user: TokenPayload, homeworkId: string): Promise<HomeworkDto> {
const student = isStudent(user);
const personalIds = student ? await resolvePersonalIds(user) : [];
const device = isClassDevice(user);
const personalIds = device ? await resolvePersonalIds(user) : [];
const homework = await prisma.homework.findUnique({
where: { id: homeworkId },
include: {
course: courseSelect,
creator: creatorSelect,
statuses: student ? { where: personalIdWhere(personalIds) } : true,
statuses: device ? { where: personalIdWhere(personalIds) } : true,
},
});
if (!homework) throw ApiError.notFound('作业不存在');
await assertClassAccess(user, homework.classId);
return toHomeworkDto(homework, {
userIds: student ? personalIds : [],
withStatus: !student,
studentIds: device ? personalIds : [],
withStatus: !device,
});
}
/* ------------------------------------------------------------------ 发布 / 修改 / 删除 */
/**
* 发布作业并实时推送到班级房间。
*
* 权限:管理员 / 班主任 / 科任老师,**以及本班的班级账号**(教室机器的客户端录入 ——
* 需求就是「支持作业在客户端录入」,老师在教室电脑上顺手就能记一条)。
* 权限走 `assertCanManageSubjectContent`(`allowClassDevice: true`):
* - **选了科目** → 必须是该科的任课老师(班主任不教这一科也发不了);
* - **没选科目** → 本班班主任或管理员;
* - **ClassHelper 班级端** → 可以录(老师在教室电脑上顺手记一条是常见需求,
* 见 AGENTS.md §5 第 20 条),班级端录入的作业归属该班班主任。
*/
export async function createHomework(user: TokenPayload, input: CreateHomeworkInput): Promise<HomeworkDto> {
if (isClassSession(user) && classSessionClassId(user) === input.classId) {
await assertClassAccess(user, input.classId);
} else {
await assertCanPublishContent(user, input.classId);
}
await assertCanManageSubjectContent(user, input.classId, input.courseId ?? null, '布置作业', {
allowClassDevice: true,
});
if (input.courseId) await assertCourseInClass(input.courseId, input.classId);
// 班级账号的 sub 是**班级 id**(不是用户 id),直接写 createdBy 会撞外键;
// ClassHelper 班级端的 sub 是**班级 id**(不是账号 id),直接写 createdBy 会撞外键;
// 教室机器录入的作业归属该班班主任,Web 端看到的作者才是真人。
let createdBy = user.sub;
if (isClassSession(user)) {
if (isClassDevice(user)) {
const owner = await prisma.class.findUnique({
where: { id: input.classId },
select: { teacherId: true },
@@ -190,16 +189,20 @@ export async function updateHomework(
): Promise<HomeworkDto> {
const current = await prisma.homework.findUnique({ where: { id: homeworkId } });
if (!current) throw ApiError.notFound('作业不存在');
await assertCanPublishContent(user, current.classId);
if (input.courseId) await assertCourseInClass(input.courseId, current.classId);
// 改科目等于把这条作业挪到另一个科目的权限域下,两端都要判
const nextCourseId = input.courseId === undefined ? current.courseId : (input.courseId ?? null);
await assertCanManageSubjectContent(user, current.classId, nextCourseId, '修改作业', {
allowClassDevice: true,
});
if (nextCourseId) await assertCourseInClass(nextCourseId, current.classId);
const updated = await prisma.homework.update({
where: { id: homeworkId },
data: {
...(input.title ? { title: input.title } : {}),
...(input.content ? { content: input.content } : {}),
...(input.courseId !== undefined ? { courseId: input.courseId ?? null } : {}),
...(input.courseId !== undefined ? { courseId: nextCourseId } : {}),
...(input.attachmentUrl !== undefined ? { attachmentUrl: input.attachmentUrl ?? null } : {}),
...(input.assignDate !== undefined ? { assignDate: input.assignDate } : {}),
},
@@ -217,7 +220,9 @@ export async function deleteHomework(user: TokenPayload, homeworkId: string): Pr
include: { course: courseSelect, creator: creatorSelect },
});
if (!current) throw ApiError.notFound('作业不存在');
await assertCanPublishContent(user, current.classId);
await assertCanManageSubjectContent(user, current.classId, current.courseId, '删除作业', {
allowClassDevice: true,
});
await prisma.homework.delete({ where: { id: homeworkId } });
emitToClass(current.classId, SOCKET_EVENTS.homeworkUpdated, {
@@ -226,11 +231,12 @@ export async function deleteHomework(user: TokenPayload, homeworkId: string): Pr
});
}
/* ------------------------------------------------------------------ 完成状态 */
/**
* 标记完成 / 取消完成。
* - 普通学生:标记自己;
* - 班级账号(班级设备):为全班学生写入完成状态(代全班操作);
* - 教师 / 管理员:可代指定学生标记。
* - ClassHelper 班级端:为**全班学生**写入完成状态(代全班操作,因此教师端的完成人数依然准确);
* - 教师 / 管理员:必须显式指定该班的学生(学生不是账号,不能落到操作者自己身上)。
*/
export async function updateHomeworkStatus(
user: TokenPayload,
@@ -242,47 +248,45 @@ export async function updateHomeworkStatus(
await assertClassAccess(user, homework.classId);
if (isStudent(user)) {
const personalIds = await resolvePersonalIds(user);
let result: {
id: string;
homeworkId: string;
userId: string;
completed: boolean;
updatedAt: Date;
} | null = null;
if (isClassDevice(user)) {
const studentIds = await resolvePersonalIds(user);
let result: HomeworkStatusDto | null = null;
for (const userId of personalIds) {
for (const studentId of studentIds) {
const status = await prisma.homeworkStatus.upsert({
where: { homeworkId_userId: { homeworkId, userId } },
create: { homeworkId, userId, completed: input.completed },
where: { homeworkId_studentId: { homeworkId, studentId } },
create: { homeworkId, studentId, completed: input.completed },
update: { completed: input.completed },
});
result ??= status;
result ??= toHomeworkStatusDto(status);
}
if (!result) throw ApiError.forbidden('当前班级还没有学生账号,无法标记作业完成状态');
if (!result) throw ApiError.badRequest('当前班级还没有学生,请先在名单里添加学生');
const dto = toHomeworkStatusDto(result);
emitToClass(homework.classId, SOCKET_EVENTS.homeworkStatus, { ...dto, classId: homework.classId });
return dto;
emitToClass(homework.classId, SOCKET_EVENTS.homeworkStatus, {
...result,
classId: homework.classId,
});
return result;
}
// 教师 / 管理员分支:必须落到**该班学生**身上。旧实现允许不传 userId 并默默写到
// 操作者自己的账号上(教师时 user.sub 就是教师 id),那条记录既不在学生名单里,
// 又会被教师视角的 completedCount 计入,导致"完成人数 > 班级人数"。
const targetUserId = input.userId ?? user.sub;
const target = await prisma.user.findUnique({
where: { id: targetUserId },
select: { role: true, classId: true },
// 教师 / 管理员分支:必须落到**该班学生**身上。旧实现允许不传 id 并默默写到操作者自己的账号上
// (教师时 sub 就是教师 id),那条记录既不在学生名单里、又会被 completedCount 计入,
// 导致"完成人数 > 班级人数"。
if (!input.studentId) {
throw ApiError.badRequest('请指定该作业所在班级的学生(studentId)');
}
const target = await prisma.student.findUnique({
where: { id: input.studentId },
select: { classId: true },
});
if (!target || target.role !== 'STUDENT' || target.classId !== homework.classId) {
throw ApiError.badRequest('请指定该作业所在班级的学生(userId),未指定时只能操作自己的账号');
if (!target || target.classId !== homework.classId) {
throw ApiError.badRequest('请指定该作业所在班级的学生(studentId)');
}
const status = await prisma.homeworkStatus.upsert({
where: { homeworkId_userId: { homeworkId, userId: targetUserId } },
create: { homeworkId, userId: targetUserId, completed: input.completed },
where: { homeworkId_studentId: { homeworkId, studentId: input.studentId } },
create: { homeworkId, studentId: input.studentId, completed: input.completed },
update: { completed: input.completed },
});
@@ -293,21 +297,21 @@ export async function updateHomeworkStatus(
/* ------------------------------------------------------------------ 未交名单 */
/** 组装某次作业的全班提交名单(未交名单 = completed=false 的那些) */
/** 组装某次作业的全班提交名单(未交名单 = completed=false 的那些),按学号排序 */
async function buildSubmissions(classId: string, homeworkId: string): Promise<HomeworkSubmissionsDto> {
const [students, statuses] = await Promise.all([
prisma.user.findMany({
where: { classId, role: 'STUDENT' },
select: { id: true, name: true, username: true },
orderBy: { username: 'asc' },
prisma.student.findMany({
where: { classId, archivedYearId: null },
select: { id: true, name: true, studentNo: true },
orderBy: { studentNo: 'asc' },
}),
prisma.homeworkStatus.findMany({ where: { homeworkId }, select: { userId: true, completed: true } }),
prisma.homeworkStatus.findMany({ where: { homeworkId }, select: { studentId: true, completed: true } }),
]);
const completedBy = new Map(statuses.map((item) => [item.userId, item.completed]));
const completedBy = new Map(statuses.map((item) => [item.studentId, item.completed]));
const list: HomeworkSubmissionDto[] = students.map((item) => ({
userId: item.id,
name: item.name || item.username,
username: item.username,
studentId: item.id,
studentNo: item.studentNo,
name: item.name || item.studentNo,
completed: completedBy.get(item.id) === true,
}));
return {
@@ -320,14 +324,14 @@ async function buildSubmissions(classId: string, homeworkId: string): Promise<Ho
};
}
/** 只有教师 / 管理员 / 班级设备可以维护"未交名单"(普通学生只能标记自己) */
/** 只有教师 / 管理员 / ClassHelper 班级端可以维护"未交名单" */
function assertCanManageSubmissions(user: TokenPayload): void {
if (user.role === 'ADMIN' || user.role === 'TEACHER') return;
if (isClassSession(user)) return;
throw ApiError.forbidden('只有教师或班级设备可以维护未交名单');
if (isClassDevice(user)) return;
throw ApiError.forbidden('只有教师或 ClassHelper 班级端可以维护未交名单');
}
/** 读取作业提交名单(教师 / 班级设备) */
/** 读取作业提交名单(教师 / 班级端) */
export async function listHomeworkSubmissions(
user: TokenPayload,
homeworkId: string,
@@ -344,7 +348,7 @@ export async function listHomeworkSubmissions(
/**
* 保存"未交名单":勾选的学生标记未完成,其余学生一律标记完成。
* 这样班级设备的操作语义是"点名谁没交",比逐个勾"谁交了"更省事。
* 这样教室机器的操作语义是"点名谁没交",比逐个勾"谁交了"更省事。
*/
export async function updateHomeworkSubmissions(
user: TokenPayload,
@@ -359,13 +363,13 @@ export async function updateHomeworkSubmissions(
await assertClassAccess(user, homework.classId);
assertCanManageSubmissions(user);
const students = await prisma.user.findMany({
where: { classId: homework.classId, role: 'STUDENT' },
const students = await prisma.student.findMany({
where: { classId: homework.classId, archivedYearId: null },
select: { id: true },
});
if (students.length === 0) throw ApiError.badRequest('当前班级还没有学生账号');
if (students.length === 0) throw ApiError.badRequest('当前班级还没有学生,请先在名单里添加学生');
const notSubmitted = new Set(input.notSubmittedUserIds);
const notSubmitted = new Set(input.notSubmittedStudentIds);
const studentIds = new Set(students.map((item) => item.id));
const outsiders = [...notSubmitted].filter((id) => !studentIds.has(id));
if (outsiders.length > 0) throw ApiError.badRequest('未交名单里包含非本班学生');
@@ -373,15 +377,15 @@ export async function updateHomeworkSubmissions(
await prisma.$transaction(
students.map((item) =>
prisma.homeworkStatus.upsert({
where: { homeworkId_userId: { homeworkId, userId: item.id } },
create: { homeworkId, userId: item.id, completed: !notSubmitted.has(item.id) },
where: { homeworkId_studentId: { homeworkId, studentId: item.id } },
create: { homeworkId, studentId: item.id, completed: !notSubmitted.has(item.id) },
update: { completed: !notSubmitted.has(item.id) },
}),
),
);
const result = await buildSubmissions(homework.classId, homeworkId);
// 实时刷新教师端/学生端的完成情况
// 实时刷新教师端/班级端的完成情况
emitToClass(homework.classId, SOCKET_EVENTS.homeworkStatus, {
homeworkId,
classId: homework.classId,