feat: 支持班级灵动岛云端配置与跨端同步
发布官网与文档站 / build (push) Blocked by required conditions
发布官网与文档站 / deploy (push) Blocked by required conditions

This commit is contained in:
LoveChengke committed 2026-11-18 17:46:26 +08:00
1 parent 4449fbd0a1
commit f6dd59aa25
40 files changed
+1208 -719

No files matched your search

@@ -0,0 +1,3 @@
-- 班级级自定义灵动岛:由 Web 管理端编辑,教室客户端只读同步。
ALTER TABLE `Class` ADD COLUMN `islandLayoutJson` TEXT;
ALTER TABLE `Class` ADD COLUMN `islandLayoutUpdatedAt` DATETIME;
+4
View File
@@ -236,6 +236,10 @@ model Class {
/// 是否允许 ClassHelper 班级端按学号查询本班学生的成绩明细(默认开启)。
/// 关闭后班级端查成绩一律 403;教师端不受影响。
studentGradeQueryEnabled Boolean @default(true)
/// Web 管理端下发的班级级自定义灵动岛方案(shared 的 IslandLayoutSettings 归一化 JSON)。
/// 空值表示尚未配置,教室端沿用本机默认方案。
islandLayoutJson String?
islandLayoutUpdatedAt DateTime?
/// 毕业归档所属届别;null = 在读(常规班级列表只显示未归档的)
archivedYearId String?
archivedAt DateTime?
+28
View File
@@ -15,6 +15,7 @@ import { readFileSync } from 'node:fs';
* VERIFY_BASE_URL 默认 http://127.0.0.1:4000
*/
import { io } from 'socket.io-client';
import { defaultIslandLayouts } from '@classhelper/shared';
import { verifyClassPlanYamlApi } from './verify-class-plan-yaml-api.mjs';
const BASE_URL = process.env.VERIFY_BASE_URL ?? `http://127.0.0.1:${process.env.PORT ?? 4000}`;
@@ -161,6 +162,33 @@ async function main() {
process.exit(1);
}
// ---------------------------------------------------------------- 班级灵动岛同步与只读边界
const classIslandBaseline = await api(`/classes/${classId}/island-layout`, { token: teacherToken });
const classIslandLayout = defaultIslandLayouts();
classIslandLayout.layout = 'custom';
classIslandLayout.residentEnabled = true;
const saveClassIsland = await api(`/classes/${classId}/island-layout`, {
method: 'PATCH',
token: teacherToken,
body: { layout: classIslandLayout },
});
const classDeviceIsland = await api(`/classes/${classId}/island-layout`, { token: studentToken });
const classDeviceWrite = await api(`/classes/${classId}/island-layout`, {
method: 'PATCH',
token: studentToken,
body: { layout: classIslandLayout },
});
record(
'班级灵动岛:班主任保存、班级端只读同步、班级端写入被拒',
classIslandBaseline.status === 200 &&
saveClassIsland.status === 200 &&
saveClassIsland.payload?.data?.layout?.layout === 'custom' &&
classDeviceIsland.status === 200 &&
classDeviceIsland.payload?.data?.layout?.schemes?.[0]?.rows?.length > 0 &&
classDeviceWrite.status === 403,
`baseline=${classIslandBaseline.status} save=${saveClassIsland.status} read=${classDeviceIsland.status} write=${classDeviceWrite.status}`,
);
// teacher2 名下但 teacher1 无权访问的班级,用于验证教师间权限隔离。
// 注意:演示库里可能被人工改过(管理员自己建班、给别的班加协作教师),
// 因此这里**不允许依赖种子数据的班级布局**:没有现成的就现建一个临时班级,收尾删除。
@@ -19,6 +19,7 @@ import {
listClassesQuerySchema,
promoteClassesSchema,
updateClassAccountSchema,
updateClassIslandLayoutSchema,
updateClassSchema,
updateClassSettingsSchema,
type UpdateClassSettingsInput,
@@ -27,6 +28,7 @@ import {
type AssignSubjectTeachersInput,
type CreateClassInput,
type UpdateClassAccountInput,
type UpdateClassIslandLayoutInput,
type UpdateClassInput,
type UpdateStudentGradeQueryInput,
} from './classes.schemas.js';
@@ -128,6 +130,36 @@ router.patch(
);
},
);
/**
* 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)),
'班级灵动岛方案已保存',
);
},
);
/** DELETE /api/classes/:id - 删除班级 */
router.delete(
'/:id',
@@ -53,6 +53,11 @@ export const updateClassSettingsSchema = z.strictObject({
termWeeks: z.coerce.number().int().min(1).max(60).optional(),
});
/** 班级级灵动岛方案:具体结构由 shared 的 normalizeIslandLayouts 统一收敛。 */
export const updateClassIslandLayoutSchema = z.strictObject({
layout: z.unknown(),
});
/** 学年升级(批量改年级,不归档) */
export const promoteClassesSchema = z.strictObject({
classIds: z.array(z.string().min(1)).min(1, '请至少选择一个班级').max(200),
@@ -130,3 +135,4 @@ export type AddStudentInput = z.infer<typeof addStudentSchema>;
export type AssignSubjectTeachersInput = z.infer<typeof assignSubjectTeachersSchema>;
export type UpdateClassSettingsInput = z.infer<typeof updateClassSettingsSchema>;
export type UpdateClassIslandLayoutInput = z.infer<typeof updateClassIslandLayoutSchema>;
@@ -1,8 +1,14 @@
import { disconnectUserSessions, refreshClassSubscriptions } from '../../realtime/bus.js';
import { assertHeadOnly, assertManage } from '../../lib/authz/index.js';
import { auditData } from '../permissions/permissions.service.js';
import type { ClassDetailDto, ClassDto, StudentDto, SubjectTeacherDto } from '@classhelper/shared';
import { SOCKET_EVENTS, formatClassName } from '@classhelper/shared';
import type {
ClassDetailDto,
ClassDto,
ClassIslandLayoutDto,
StudentDto,
SubjectTeacherDto,
} from '@classhelper/shared';
import { SOCKET_EVENTS, formatClassName, normalizeIslandLayouts } from '@classhelper/shared';
import { env } from '../../config/env.js';
import {
assertCanAssignTeachers,
@@ -26,6 +32,7 @@ import type {
AssignSubjectTeachersInput,
CreateClassInput,
UpdateClassInput,
UpdateClassIslandLayoutInput,
UpdateClassSettingsInput,
UpdateStudentGradeQueryInput,
} from './classes.schemas.js';
@@ -441,6 +448,94 @@ export async function updateClassSettings(
emitToClass(classId, SOCKET_EVENTS.classUpdated, { classId, action: 'updated' });
return toClassDto(updated);
}
/**
* 读取班级级灵动岛方案。
*
* 班级端必须能读自己的方案(allowClassDevice),教师/管理员仍按 class:read + 班级范围判定。
* 尚未配置时返回 `layout: null`,不能在读取阶段把服务端默认值写回班级,避免管理页一打开就产生写操作。
*/
export async function getClassIslandLayout(
user: TokenPayload,
classId: string,
): Promise<ClassIslandLayoutDto> {
await assertClassAccess(user, classId, 'class:read');
const record = await prisma.class.findUnique({
where: { id: classId },
select: { id: true, islandLayoutJson: true, islandLayoutUpdatedAt: true },
});
if (!record) throw ApiError.notFound('班级不存在');
const layout = parseStoredIslandLayout(record.islandLayoutJson, classId);
return {
classId: record.id,
layout,
updatedAt: record.islandLayoutUpdatedAt?.toISOString() ?? null,
};
}
/**
* 保存班级级灵动岛方案。
*
* 编辑入口只在 Web 管理端;班级端没有写接口。班主任可维护本班,管理员不受班主任关系限制。
* 保存后广播 class:updated,教室端重新拉取并更新常驻岛。
*/
export async function updateClassIslandLayout(
user: TokenPayload,
classId: string,
input: UpdateClassIslandLayoutInput,
): Promise<ClassIslandLayoutDto> {
await assertHeadOnly(user, 'class:settings', classId);
if (!input.layout || typeof input.layout !== 'object') throw ApiError.badRequest('灵动岛方案格式不正确');
const layout = normalizeIslandLayouts(input.layout);
// 班级方案是“Web 端自由编辑的常驻岛”,不把 fixed 模式误下发成关闭自定义布局。
layout.layout = 'custom';
layout.residentEnabled = true;
const before = await prisma.class.findUniqueOrThrow({
where: { id: classId },
select: { islandLayoutJson: true, islandLayoutUpdatedAt: true },
});
const updated = await prisma.class.update({
where: { id: classId },
data: {
islandLayoutJson: JSON.stringify(layout),
islandLayoutUpdatedAt: new Date(),
},
select: { id: true, islandLayoutJson: true, islandLayoutUpdatedAt: true },
});
const summary = (value: ClassIslandLayoutDto['layout']) => ({
configured: Boolean(value),
schemeCount: value?.schemes.length ?? 0,
rowCount: value?.schemes.reduce((count, scheme) => count + scheme.rows.length, 0) ?? 0,
activeSchemeId: value?.activeSchemeId ?? null,
});
await prisma.permissionAudit.create({
data: auditData(
user,
'class-island-layout',
'class',
classId,
summary(parseStoredIslandLayout(before.islandLayoutJson, classId)),
summary(layout),
),
});
emitToClass(classId, SOCKET_EVENTS.classUpdated, { classId, action: 'island-layout' });
return {
classId: updated.id,
layout,
updatedAt: updated.islandLayoutUpdatedAt?.toISOString() ?? null,
};
}
function parseStoredIslandLayout(value: string | null, classId: string): ClassIslandLayoutDto['layout'] {
if (!value) return null;
try {
return normalizeIslandLayouts(JSON.parse(value));
} catch {
logger.warn(`班级灵动岛方案 JSON 无法解析,已按未配置处理:classId=${classId}`);
return null;
}
}
/**
* 学年升级(按升级权限与班级范围):把若干班级的年级改掉,**不归档、数据沿用**。
*