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)。
This commit is contained in:
LoveChengke committed 2026-09-27 14:59:12 +08:00
1 parent fe41ebb7d6
commit d0830f6830
61 files changed
+7026 -93

No files matched your search

@@ -0,0 +1,100 @@
import crypto from 'node:crypto';
import type { Request, RequestHandler } from 'express';
import { prisma } from '../../lib/db.js';
import { ApiError } from '../../lib/http.js';
/**
* 联动设备的令牌工具。
*
* 为什么不用 JWT:
* - 令牌是「设备级长期凭证」,插件装在教室机器上,长时间无人值守,
* 需要一个"管理员在 Web 端点了重置才失效"的凭证,而不是有固定过期时间的会话;
* - 明文只在创建/重置接口返回一次,服务端只存 sha256 —— 库被读走也无法反推出可用令牌。
*/
export function generateDeviceToken(): string {
// 32 字节随机 -> 64 位十六进制,前缀便于在日志/设置页里一眼认出
return `chci_${crypto.randomBytes(32).toString('hex')}`;
}
export function hashDeviceToken(token: string): string {
return crypto.createHash('sha256').update(token, 'utf8').digest('hex');
}
/** 令牌前缀提示(chci_ + 前 8 位),用于设备列表里人眼识别 */
export function tokenHintOf(token: string): string {
return `${token.slice(0, 13)}…`;
}
/** 从 \`X-ClassIsland-Token\` 或 \`Authorization: Bearer\` 中取出设备令牌 */
export function extractDeviceToken(headerValue: string | undefined, custom: unknown): string | null {
if (typeof custom === 'string' && custom.trim()) return custom.trim();
if (!headerValue) return null;
const [scheme, value] = headerValue.split(' ');
if (!value || scheme.toLowerCase() !== 'bearer') return null;
return value.trim();
}
/** 设备上下文(与 Express.Request.device 的结构一致) */
export interface DeviceContext {
deviceId: string;
classId: string;
name: string;
enabled: boolean;
syncScheduleToServer: boolean;
mirrorScheduleToClassIsland: boolean;
}
/** 插件侧路由统一挂这个中间件:解析设备令牌并回查设备记录 */
export function authenticateDevice(): RequestHandler {
return (req, _res, next) => {
void (async () => {
try {
const token = extractDeviceToken(req.headers.authorization, req.headers['x-classisland-token']);
if (!token) throw ApiError.unauthorized('缺少设备令牌(X-ClassIsland-Token)');
const record = await prisma.integrationDevice.findFirst({
where: { tokenHash: hashDeviceToken(token) },
select: {
id: true,
classId: true,
name: true,
enabled: true,
syncScheduleToServer: true,
mirrorScheduleToClassIsland: true,
},
});
if (!record) throw ApiError.unauthorized('设备令牌无效,请在「ClassIsland 联动」里重新生成');
const context: DeviceContext = {
deviceId: record.id,
classId: record.classId,
name: record.name,
enabled: record.enabled,
syncScheduleToServer: record.syncScheduleToServer,
mirrorScheduleToClassIsland: record.mirrorScheduleToClassIsland,
};
req.device = context;
next();
} catch (error) {
next(error);
}
})();
};
}
/** 取出当前设备上下文,未鉴权时抛 401 */
export function getDevice(req: Request): DeviceContext {
const device = req.device;
if (!device) throw ApiError.unauthorized('缺少设备上下文');
return device;
}
/** 设备被管理员停用:插件上报与下发一律拒绝(403 而不是 401,便于插件提示"请管理员开启") */
export function assertDeviceEnabled(device: DeviceContext): void {
if (!device.enabled) {
throw ApiError.forbidden('该设备已在「ClassIsland 联动」中被停用,请联系管理员开启');
}
}
/** 生成的令牌字符串的字面量前缀,供测试与文档引用 */
export const DEVICE_TOKEN_PREFIX = 'chci_';