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
1 parent
17f55864bf
commit
9d5ac7adf9
172 files changed
+8761
-1896
No files matched your search
@@ -0,0 +1,86 @@
|
||||
import { Router } from 'express';
|
||||
import { sendOk } from '../../lib/http.js';
|
||||
import { authenticate, getAuthUser, requireRole } from '../../middleware/auth.js';
|
||||
import { validate, validatedBody, validatedQuery } from '../../middleware/validate.js';
|
||||
import { defineModule } from '../module.types.js';
|
||||
import {
|
||||
autoTermWeeksSchema,
|
||||
holidayQuerySchema,
|
||||
termQuerySchema,
|
||||
updateTermWeeksSchema,
|
||||
type AutoTermWeeksInput,
|
||||
type UpdateTermWeeksInput,
|
||||
} from './term.schemas.js';
|
||||
import * as termService from './term.service.js';
|
||||
|
||||
const router = Router();
|
||||
router.use(authenticate());
|
||||
|
||||
/**
|
||||
* 学期周次。
|
||||
*
|
||||
* - **读**：教师/管理员都能看自己可访问班级的周次（课表页要显示"第几周"）；
|
||||
* - **写**：仅管理员 —— 周次是全校口径，改错会让所有班的课表整体错位；
|
||||
* - `classId` 留空 = 全校默认；某个班有自己的配置时优先用它。
|
||||
*/
|
||||
router.get('/', requireRole('ADMIN', 'TEACHER'), validate({ query: termQuerySchema }), async (req, res) => {
|
||||
const user = getAuthUser(req);
|
||||
const { classId } = validatedQuery<{ classId?: string }>(req);
|
||||
sendOk(res, await termService.getTermWeeks(user, classId), '获取学期周次成功');
|
||||
});
|
||||
|
||||
/** PUT /api/term - 保存逐周区间（整表覆盖，仅管理员） */
|
||||
router.put(
|
||||
'/',
|
||||
requireRole('ADMIN'),
|
||||
validate({ body: updateTermWeeksSchema }),
|
||||
async (req, res) => {
|
||||
const user = getAuthUser(req);
|
||||
sendOk(
|
||||
res,
|
||||
await termService.updateTermWeeks(user, validatedBody<UpdateTermWeeksInput>(req)),
|
||||
'学期周次已保存，变更会随课表下发给教室的 ClassHelper 班级端',
|
||||
);
|
||||
},
|
||||
);
|
||||
|
||||
/**
|
||||
* POST /api/term/auto - 按学期开始日期一键生成逐周区间（仅管理员）
|
||||
*
|
||||
* 配置的起点：先生成一份"标准学期"，再把调休那几周改掉。
|
||||
*/
|
||||
router.post(
|
||||
'/auto',
|
||||
requireRole('ADMIN'),
|
||||
validate({ body: autoTermWeeksSchema }),
|
||||
async (req, res) => {
|
||||
const user = getAuthUser(req);
|
||||
sendOk(
|
||||
res,
|
||||
await termService.autoTermWeeks(user, validatedBody<AutoTermWeeksInput>(req)),
|
||||
'已按学期开始日期生成逐周区间，可继续手动微调',
|
||||
);
|
||||
},
|
||||
);
|
||||
|
||||
/**
|
||||
* GET /api/term/holidays?year= - 联网获取法定节假日安排（给建议，不改数据）
|
||||
*
|
||||
* **机房没有外网时 `ok:false` 是正常结果**，前端按"暂时取不到"呈现即可。
|
||||
*/
|
||||
router.get(
|
||||
'/holidays',
|
||||
requireRole('ADMIN'),
|
||||
validate({ query: holidayQuerySchema }),
|
||||
async (req, res) => {
|
||||
const { year } = validatedQuery<{ year?: number }>(req);
|
||||
const result = await termService.suggestHolidays(year);
|
||||
sendOk(res, result, result.ok ? '已获取当年的放假安排' : (result.error ?? '暂时无法获取放假安排'));
|
||||
},
|
||||
);
|
||||
|
||||
export const termModule = defineModule({
|
||||
name: 'term',
|
||||
basePath: '/term',
|
||||
router,
|
||||
});
|
||||
@@ -0,0 +1,37 @@
|
||||
import { z } from 'zod';
|
||||
import { isDayKey } from '@classhelper/shared';
|
||||
|
||||
/** 一个教学周的日期区间 */
|
||||
const termWeekItemSchema = z.object({
|
||||
weekNumber: z.coerce.number().int().min(1).max(60),
|
||||
startDate: z.string().trim().refine(isDayKey, { message: '开始日期格式应为 YYYY-MM-DD' }),
|
||||
endDate: z.string().trim().refine(isDayKey, { message: '结束日期格式应为 YYYY-MM-DD' }),
|
||||
note: z.string().trim().max(64).optional(),
|
||||
});
|
||||
|
||||
const termStartDateSchema = z.string().trim().refine(isDayKey, { message: '日期格式应为 YYYY-MM-DD' });
|
||||
|
||||
/** `classId` 为空表示全校默认 */
|
||||
export const termQuerySchema = z.object({
|
||||
classId: z.string().min(1).optional(),
|
||||
});
|
||||
|
||||
export const updateTermWeeksSchema = z.object({
|
||||
classId: z.string().min(1).nullish(),
|
||||
termStartDate: termStartDateSchema.optional(),
|
||||
/** 整表覆盖：传空数组 = 清空逐周配置，回到按开学日期线性推算 */
|
||||
weeks: z.array(termWeekItemSchema).max(60),
|
||||
});
|
||||
|
||||
export const autoTermWeeksSchema = z.object({
|
||||
classId: z.string().min(1).nullish(),
|
||||
termStartDate: termStartDateSchema.optional(),
|
||||
maxWeek: z.coerce.number().int().min(1).max(60).optional(),
|
||||
});
|
||||
|
||||
export const holidayQuerySchema = z.object({
|
||||
year: z.coerce.number().int().min(2000).max(2100).optional(),
|
||||
});
|
||||
|
||||
export type UpdateTermWeeksInput = z.infer<typeof updateTermWeeksSchema>;
|
||||
export type AutoTermWeeksInput = z.infer<typeof autoTermWeeksSchema>;
|
||||
@@ -0,0 +1,239 @@
|
||||
import {
|
||||
buildAutoTermWeeks,
|
||||
validateTermWeeks,
|
||||
type HolidaySuggestionDto,
|
||||
type TermWeeksDto,
|
||||
} from '@classhelper/shared';
|
||||
import { assertCanManageClasses, assertClassAccess } from '../../lib/access.js';
|
||||
import { env } from '../../config/env.js';
|
||||
import { prisma } from '../../lib/db.js';
|
||||
import { ApiError } from '../../lib/http.js';
|
||||
import type { TokenPayload } from '../../lib/jwt.js';
|
||||
import { logger } from '../../lib/logger.js';
|
||||
import { MAX_TERM_WEEK, loadTermContext, resolveCurrentWeek } from '../../lib/term.js';
|
||||
import { emitToClass } from '../../realtime/bus.js';
|
||||
import { SOCKET_EVENTS } from '@classhelper/shared';
|
||||
import { notifyScheduleChanged } from '../integrations/integrations.service.js';
|
||||
import type { AutoTermWeeksInput, UpdateTermWeeksInput } from './term.schemas.js';
|
||||
|
||||
/**
|
||||
* 学期周次（仅管理员可写）。
|
||||
*
|
||||
* 为什么需要逐周配置：`TERM_START_DATE + 每周七天`的线性推算遇到法定节假日调休、
|
||||
* 周末补课、错峰开学就会**整体错位**——而课表、作业、成绩都按周次组织，错一周就全错。
|
||||
* 因此管理员可以：
|
||||
* 1. 先按开学日期一键生成逐周区间（`autoTermWeeks`）；
|
||||
* 2. 再逐周微调（调休那一周拉长、开学前那几天并进第 1 周…）；
|
||||
* 3. 也可以直接改某个班的开学日期（`Class.termStartDate`）。
|
||||
*
|
||||
* `classId = ''` 表示**全校默认**；某个班有自己的配置时优先用它。
|
||||
* 改完之后会把新的课表口径（含周次区间）**下发给该班所有在线的 ClassIsland**。
|
||||
*/
|
||||
|
||||
/** 把 null/undefined 归一成空串（空串 = 全校默认） */
|
||||
function scopeOf(classId?: string | null): string {
|
||||
return classId ?? '';
|
||||
}
|
||||
|
||||
/** 读取某个范围的周次配置 */
|
||||
export async function getTermWeeks(user: TokenPayload, classId?: string | null): Promise<TermWeeksDto> {
|
||||
const scope = scopeOf(classId);
|
||||
if (scope) await assertClassAccess(user, scope);
|
||||
|
||||
const [weeks, cls] = await Promise.all([
|
||||
prisma.termWeek.findMany({ where: { classId: scope }, orderBy: { weekNumber: 'asc' } }),
|
||||
scope
|
||||
? prisma.class.findUnique({ where: { id: scope }, select: { termStartDate: true, termWeeks: true } })
|
||||
: Promise.resolve(null),
|
||||
]);
|
||||
|
||||
const context = await loadTermContext(scope || null);
|
||||
return {
|
||||
classId: scope,
|
||||
termStartDate: context.termStartDate || env.termStartDate,
|
||||
currentWeek: resolveCurrentWeek(new Date(), context),
|
||||
maxWeek: cls?.termWeeks && cls.termWeeks > 0 ? cls.termWeeks : MAX_TERM_WEEK,
|
||||
configured: weeks.length > 0,
|
||||
weeks: weeks.map((item) => ({
|
||||
weekNumber: item.weekNumber,
|
||||
startDate: item.startDate,
|
||||
endDate: item.endDate,
|
||||
note: item.note,
|
||||
})),
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* 保存逐周配置（整表覆盖）。仅管理员。
|
||||
*
|
||||
* 校验：日期格式、起止顺序、**区间不重叠**（重叠会让"当前第几周"出现歧义）。
|
||||
* 保存后把新的周次口径下发给该班所有在线设备。
|
||||
*/
|
||||
export async function updateTermWeeks(user: TokenPayload, input: UpdateTermWeeksInput): Promise<TermWeeksDto> {
|
||||
assertCanManageClasses(user);
|
||||
const scope = scopeOf(input.classId);
|
||||
|
||||
const errors = validateTermWeeks(input.weeks);
|
||||
if (errors.length > 0) throw ApiError.badRequest(errors[0]!, { errors });
|
||||
|
||||
// 重复的周次号会让唯一约束直接抛 500，这里给一句人话
|
||||
const seen = new Set<number>();
|
||||
for (const week of input.weeks) {
|
||||
if (seen.has(week.weekNumber)) {
|
||||
throw ApiError.badRequest(`第 ${week.weekNumber} 周出现了两次`);
|
||||
}
|
||||
seen.add(week.weekNumber);
|
||||
}
|
||||
|
||||
if (scope) {
|
||||
const exists = await prisma.class.findUnique({ where: { id: scope }, select: { id: true } });
|
||||
if (!exists) throw ApiError.notFound('班级不存在');
|
||||
}
|
||||
|
||||
await prisma.$transaction([
|
||||
prisma.termWeek.deleteMany({ where: { classId: scope } }),
|
||||
...(input.weeks.length > 0
|
||||
? [
|
||||
prisma.termWeek.createMany({
|
||||
data: input.weeks.map((week) => ({
|
||||
classId: scope,
|
||||
weekNumber: week.weekNumber,
|
||||
startDate: week.startDate,
|
||||
endDate: week.endDate,
|
||||
note: week.note ?? '',
|
||||
})),
|
||||
}),
|
||||
]
|
||||
: []),
|
||||
...(input.termStartDate && scope
|
||||
? [prisma.class.update({ where: { id: scope }, data: { termStartDate: input.termStartDate } })]
|
||||
: []),
|
||||
]);
|
||||
|
||||
logger.info(
|
||||
`学期周次已更新：范围=${scope || '全校默认'} 周数=${input.weeks.length} 由 ${user.name} 执行`,
|
||||
);
|
||||
await publishTermChange(scope);
|
||||
return getTermWeeks(user, scope || null);
|
||||
}
|
||||
|
||||
/**
|
||||
* 按学期开始日期**一键生成**逐周区间（管理员再逐周微调）。仅管理员。
|
||||
*
|
||||
* 这是配置的起点：先生成一份"标准学期"，再把调休那几周改掉，
|
||||
* 比从空白开始一周周填要快得多。
|
||||
*/
|
||||
export async function autoTermWeeks(user: TokenPayload, input: AutoTermWeeksInput): Promise<TermWeeksDto> {
|
||||
assertCanManageClasses(user);
|
||||
const scope = scopeOf(input.classId);
|
||||
const context = await loadTermContext(scope || null);
|
||||
const termStartDate = input.termStartDate || context.termStartDate || env.termStartDate;
|
||||
const maxWeek = input.maxWeek ?? context.maxWeek;
|
||||
|
||||
const weeks = buildAutoTermWeeks(termStartDate, maxWeek);
|
||||
if (weeks.length === 0) throw ApiError.badRequest('请先填写学期开始日期（第 1 教学周的周一）');
|
||||
|
||||
return updateTermWeeks(user, { classId: scope || null, termStartDate, weeks });
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------------------ 调休建议（联网，可选） */
|
||||
|
||||
/** 建议结果的缓存（1 小时）：节假日数据一年才变几次，不必每次点都打外网 */
|
||||
const holidayCache = new Map<number, { at: number; data: HolidaySuggestionDto }>();
|
||||
const HOLIDAY_CACHE_TTL_MS = 60 * 60 * 1000;
|
||||
|
||||
/**
|
||||
* 联网拉取法定节假日安排，给出「哪几天不上课」的建议。
|
||||
*
|
||||
* **`ok:false` 是设计内的结果**：机房与教室机器常常只有内网，离线 / 超时 / 限流
|
||||
* 一律收敛成 `ok:false` + 一句人话，绝不抛 500（与更新检查同一种处理思路）。
|
||||
* 而且它只**给建议**，不会自动改任何数据 —— 管理员确认后才应用到周次上。
|
||||
*/
|
||||
export async function suggestHolidays(year?: number): Promise<HolidaySuggestionDto> {
|
||||
const targetYear = year ?? new Date().getFullYear();
|
||||
const cached = holidayCache.get(targetYear);
|
||||
if (cached && Date.now() - cached.at < HOLIDAY_CACHE_TTL_MS) return cached.data;
|
||||
|
||||
const fallback = (error: string): HolidaySuggestionDto => ({
|
||||
ok: false,
|
||||
error,
|
||||
year: targetYear,
|
||||
holidays: [],
|
||||
checkedAt: new Date().toISOString(),
|
||||
});
|
||||
|
||||
try {
|
||||
const controller = new AbortController();
|
||||
const timer = setTimeout(() => controller.abort(), 8000);
|
||||
const response = await fetch(`https://timor.tech/api/holiday/year/${targetYear}`, {
|
||||
signal: controller.signal,
|
||||
headers: { 'user-agent': 'ClassHelper-TermWeeks' },
|
||||
}).finally(() => clearTimeout(timer));
|
||||
|
||||
if (!response.ok) {
|
||||
const data = fallback(`节假日服务返回 ${response.status}`);
|
||||
holidayCache.set(targetYear, { at: Date.now(), data });
|
||||
return data;
|
||||
}
|
||||
|
||||
const payload = (await response.json()) as {
|
||||
holiday?: Record<string, { holiday: boolean; name: string; date: string }>;
|
||||
};
|
||||
const holidays = Object.values(payload.holiday ?? {})
|
||||
.filter((item) => item.holiday === true)
|
||||
.map((item) => ({
|
||||
name: item.name,
|
||||
startDate: item.date,
|
||||
endDate: item.date,
|
||||
}))
|
||||
.sort((a, b) => a.startDate.localeCompare(b.startDate));
|
||||
|
||||
const data: HolidaySuggestionDto = {
|
||||
ok: true,
|
||||
error: null,
|
||||
year: targetYear,
|
||||
holidays,
|
||||
checkedAt: new Date().toISOString(),
|
||||
};
|
||||
holidayCache.set(targetYear, { at: Date.now(), data });
|
||||
return data;
|
||||
} catch (error) {
|
||||
const reason =
|
||||
error instanceof Error && error.name === 'AbortError'
|
||||
? '请求超时（服务器可能没有外网）'
|
||||
: `无法获取节假日数据：${error instanceof Error ? error.message : String(error)}`;
|
||||
const data = fallback(reason);
|
||||
// 失败结果同样进缓存：否则断网时点一次按钮就要白等一个超时
|
||||
holidayCache.set(targetYear, { at: Date.now(), data });
|
||||
return data;
|
||||
}
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------------------ 内部工具 */
|
||||
|
||||
/**
|
||||
* 周次变了要把新的口径**下发给教室的 ClassIsland**（需求：「对所有 ClassIsland 下发修改」）。
|
||||
*
|
||||
* 逐周区间没法直接塞进 ClassIsland 的模型（它按"教学周序号 + 单双周"组织课表），
|
||||
* 因此实际下发的是**学期开始日期**与**各周次的起止**，随镜像课表一起走：
|
||||
* 插件据此校正"现在是第几周"，并让课表的周次口径与教室里的实际日历对齐。
|
||||
*/
|
||||
async function publishTermChange(scope: string): Promise<void> {
|
||||
if (scope) {
|
||||
emitToClass(scope, SOCKET_EVENTS.classUpdated, { classId: scope, action: 'updated' });
|
||||
await notifyScheduleChanged(scope).catch((error) => {
|
||||
logger.warn(`周次变更后下发课表失败（数据已保存）：${String(error)}`);
|
||||
});
|
||||
return;
|
||||
}
|
||||
|
||||
// 全校默认：把每个在读班级都刷一遍
|
||||
const classes = await prisma.class.findMany({
|
||||
where: { archivedYearId: null },
|
||||
select: { id: true },
|
||||
});
|
||||
for (const item of classes) {
|
||||
emitToClass(item.id, SOCKET_EVENTS.classUpdated, { classId: item.id, action: 'updated' });
|
||||
await notifyScheduleChanged(item.id).catch(() => undefined);
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user