feat(integrations,classisland,server,web,desktop): ClassIsland 联动插件——上报课表与上课状态、下发提醒并回执、教室端推送通道

教室机器上的 ClassIsland 现在可以直接和班级小助手互通：插件走 /api/integrations/classisland/*，用设备令牌（X-ClassIsland-Token，库里只存 sha256）独立鉴权，不占用 JWT 通道。

- 服务端：新增 integrations 模块（上报 / 待弹出 / 回执 / 课表镜像 / 回写），两个迁移（设备令牌表、Class.notificationChannel）；通知、叫人、联动页下发统一复用 pushToClassIsland，避免"某个页面发的通知不联动"
- 插件：packages/classisland-plugin（.NET 8，独立于 pnpm workspace）——BridgeService 上报与提醒轮询、ScheduleMapper/ClassPlanWriter 课表镜像、Avalonia 设置页、ClassHelperNotificationProvider 在 ClassIsland 上弹出提醒；本地/内网地址强制直连，躲开系统代理返回的假 404
- 客户端：设置页可选提醒通道（both / client / classisland），并订阅相应实时事件
- Web 端：新增「ClassIsland 联动」页（设备管理与提醒下发）
- 校验与打包：verify:classisland（需后端）、verify:classisland-plugin（静态契约 54 项）、build/dist:classisland-plugin 产出 .cipx
- 文档：README 与 AGENTS.md 同步新增联动说明，docs/screenshots/classisland 留三张真机截图

门禁：pnpm lint 0 error、pnpm typecheck 四包通过、verify:classisland-plugin 54/54 通过。运行期仍需在装了 ClassIsland 的机器上实测（步骤见 AGENTS.md §8）。

packages/server/src/modules/classes/classes.module.ts

@@ -2,7 +2,12 @@ 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';
-import { validate, validatedParams, validatedQuery } from '../../middleware/validate.js';
+import {
+  validate,
+  validatedBody,
+  validatedParams,
+  validatedQuery,
+} from '../../middleware/validate.js';
 import { defineModule } from '../module.types.js';
 import {
   addStudentSchema,
@@ -14,10 +19,12 @@ import {
   listClassesQuerySchema,
   updateClassAccountSchema,
   updateClassSchema,
+  updateNotificationChannelSchema,
   type AddStudentInput,
   type CreateClassInput,
   type UpdateClassAccountInput,
   type UpdateClassInput,
+  type UpdateNotificationChannelInput,
 } from './classes.schemas.js';
 import * as classService from './classes.service.js';
 
@@ -106,6 +113,42 @@ router.patch(
   },
 );
 
+/**
+ * GET /api/classes/:id/notification-channel - 读取"通知显示到哪个端"
+ *
+ * 教室的班级客户端登录后会拉这个值，据此决定自己是弹窗/上岛还是静默；
+ * 教师/管理员也能读（Web 端展示用）。
+ */
+router.get('/:id/notification-channel', validate({ params: idParamSchema }), async (req, res) => {
+  const user = getAuthUser(req);
+  const { id } = validatedParams<{ id: string }>(req);
+  sendOk(res, await classService.getNotificationChannel(user, id), '获取通知显示位置成功');
+});
+
+/**
+ * PATCH /api/classes/:id/notification-channel - 设置"通知显示到哪个端"
+ *
+ * **由教室的班级客户端自己选**（班级账号可改），教师/管理员也可改；
+ * 普通学生账号被拒（见 service 内的断言）。
+ */
+router.patch(
+  '/:id/notification-channel',
+  validate({ params: idParamSchema, body: updateNotificationChannelSchema }),
+  async (req, res) => {
+    const user = getAuthUser(req);
+    const { id } = validatedParams<{ id: string }>(req);
+    sendOk(
+      res,
+      await classService.updateNotificationChannel(
+        user,
+        id,
+        validatedBody<UpdateNotificationChannelInput>(req),
+      ),
+      '通知显示位置已更新',
+    );
+  },
+);
+
 /** GET /api/classes/:id/students - 班级学生名单 */
 router.get('/:id/students', validate({ params: idParamSchema }), async (req, res) => {
   const user = getAuthUser(req);

packages/server/src/modules/classes/classes.schemas.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { CLASSISLAND_NOTIFICATION_CHANNELS } from '@classhelper/shared';
 import { keywordSchema } from '../../lib/schemas.js';
 
 export const createClassSchema = z.object({
@@ -54,6 +55,17 @@ export const assignHeadTeacherSchema = z.object({
   teacherId: z.string().min(1, '请选择班主任'),
 });
 
+/**
+ * 通知显示位置（both / client / classisland）。
+ * 由**教室的班级客户端**在设置页里改，教师/管理员也可以在 Web 端改。
+ */
+export const updateNotificationChannelSchema = z.object({
+  notificationChannel: z.enum(
+    CLASSISLAND_NOTIFICATION_CHANNELS as unknown as [string, ...string[]],
+    { message: '显示位置只能是 both / client / classisland' },
+  ),
+});
+
 export const classStudentParamSchema = z.object({
   id: z.string().min(1),
   userId: z.string().min(1),
@@ -67,4 +79,5 @@ export const classTeacherParamSchema = z.object({
 export type CreateClassInput = z.infer<typeof createClassSchema>;
 export type UpdateClassInput = z.infer<typeof updateClassSchema>;
 export type UpdateClassAccountInput = z.infer<typeof updateClassAccountSchema>;
+export type UpdateNotificationChannelInput = z.infer<typeof updateNotificationChannelSchema>;
 export type AddStudentInput = z.infer<typeof addStudentSchema>;

packages/server/src/modules/classes/classes.service.ts

@@ -1,4 +1,9 @@
-import type { ClassDetailDto, ClassDto, StudentDto } from '@classhelper/shared';
+import type {
+  ClassDetailDto,
+  ClassDto,
+  ClassIslandNotificationChannel,
+  StudentDto,
+} from '@classhelper/shared';
 import { env } from '../../config/env.js';
 import {
   assertClassAccess,
@@ -6,6 +11,7 @@ import {
   assertCanManageClasses,
   assertCanManageRoster,
   classScopeIdFilter,
+  isStaff,
   resolveClassScope,
 } from '../../lib/access.js';
 import {
@@ -15,11 +21,25 @@ import {
 import { prisma } from '../../lib/db.js';
 import { ApiError } from '../../lib/http.js';
 import type { TokenPayload } from '../../lib/jwt.js';
-import { toClassDto, toCourseDto, toStudentDto, toTeacherBrief } from '../../lib/mappers.js';
+import {
+  toClassDto,
+  toCourseDto,
+  toNotificationChannel,
+  toStudentDto,
+  toTeacherBrief,
+} from '../../lib/mappers.js';
 import { hashPassword } from '../../lib/password.js';
 import { emitToClass } from '../../realtime/bus.js';
 import { SOCKET_EVENTS } from '@classhelper/shared';
-import type { AddStudentInput, CreateClassInput, UpdateClassInput } from './classes.schemas.js';
+import type {
+  AddStudentInput,
+  CreateClassInput,
+  UpdateClassInput,
+  UpdateNotificationChannelInput,
+} from './classes.schemas.js';
+import { attachIntegrationFlag } from '../integrations/integrations.service.js';
+import { logger } from '../../lib/logger.js';
+import { isClassSession } from '../../lib/session.js';
 
 const countSelect = {
   students: true,
@@ -76,7 +96,8 @@ export async function listClasses(user: TokenPayload, keyword?: string): Promise
     orderBy: [{ grade: 'asc' }, { name: 'asc' }],
   });
 
-  return classes.map((item) => toClassDtoWithAccount(user, item));
+  // 附上「是否已接入 ClassIsland」徽标：Web 端班级列表/课表页据此提示
+  return attachIntegrationFlag(classes.map((item) => toClassDtoWithAccount(user, item)));
 }
 
 /** 班级详情：学生名单 + 课程 + 协作教师 */
@@ -333,3 +354,48 @@ export async function removeTeacher(user: TokenPayload, classId: string, teacher
 
   await prisma.classTeacher.deleteMany({ where: { classId, teacherId } });
 }
+
+/* ---------------------------------------------------------------- 通知显示位置 */
+
+/**
+ * 读取班级的通知显示位置（both / client / classisland）。
+ *
+ * 这是**教室客户端**要读的值：客户端登录后拉一次，把自己的弹窗行为对齐到同一个选择。
+ * 学生也能读自己班的（只读），便于排查"为什么教室没弹"。
+ */
+export async function getNotificationChannel(
+  user: TokenPayload,
+  classId: string,
+): Promise<{ notificationChannel: ClassIslandNotificationChannel }> {
+  await assertClassAccess(user, classId);
+  const record = await prisma.class.findUnique({
+    where: { id: classId },
+    select: { notificationChannel: true },
+  });
+  return { notificationChannel: toNotificationChannel(record?.notificationChannel) };
+}
+
+/**
+ * 设置班级的通知显示位置。
+ *
+ * 允许两类人改：**该班的班级账号**（教室机器的客户端 —— 需求就是"由客户端自己选"）
+ * 与教师 / 管理员（Web 端也能改，便于老师统一要求）。
+ * 普通学生账号不允许：否则"教室里到底弹哪个端"会变成任意学生都能改的开关。
+ */
+export async function updateNotificationChannel(
+  user: TokenPayload,
+  classId: string,
+  input: UpdateNotificationChannelInput,
+): Promise<{ notificationChannel: ClassIslandNotificationChannel }> {
+  await assertClassAccess(user, classId);
+  if (!isClassSession(user) && !isStaff(user)) {
+    throw ApiError.forbidden('只有班级账号或教师/管理员可以修改通知显示位置');
+  }
+
+  const channel = toNotificationChannel(input.notificationChannel);
+  await prisma.class.update({ where: { id: classId }, data: { notificationChannel: channel } });
+  // 广播出去：其他端（Web 列表 / 同班客户端）能立刻看到这个选择变了
+  emitToClass(classId, SOCKET_EVENTS.classUpdated, { classId, action: 'updated' });
+  logger.info(`班级通知显示位置已更新：classId=${classId} channel=${channel} by=${user.sub}`);
+  return { notificationChannel: channel };
+}