Files
ClassHelper/packages/server/src/modules/clients/clients.service.ts
T

521 lines
19 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
import { assertClassDevice } from '../../lib/authz/index.js';
import {
CLIENT_COMMAND_EXPIRE_MS,
CLIENT_COMMAND_LABELS,
CLIENT_ONLINE_WINDOW_MS,
compareVersions,
type ClientUpdateProgressDto,
type ClientUpdateMode,
type ClientCommandAckRequest,
type ClientCommandDto,
type ClientCommandKind,
type ClientDeviceDto,
type ClientHeartbeatResponse,
type ClientPushResult,
type ClientTargetResult,
} from '@classhelper/shared';
import { resolveActiveClassPlan } from '../../lib/class-plan.js';
import { resolveClassScope, classScopeWhere } from '../../lib/access.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 * as clientReleases from '../update/client-releases.service.js';
import type {
ClientHeartbeatInput,
CreateClientCommandInput,
PushClientUpdateInput,
} from './clients.schemas.js';
/**
* ClassHelper 桌面客户端设备的心跳 / 远控命令 / 更新下发。
*
* 范式(AGENTS.md 的现行工程约定):**DB 记状态 + 客户端定时拉取** ——
* 因此本文件里没有任何"推送"动作:所有下发都只是改 `ClientDevice` / `ClientCommand` 的字段,
* 由客户端下一次心跳(30 秒内)带走。
*/
type DeviceRow = {
id: string;
classId: string | null;
deviceKey: string;
name: string;
clientVersion: string;
platform: string;
autoUpdate: boolean;
updateTargetVersion: string;
updateMode: ClientUpdateMode;
updateNotBefore: Date | null;
pendingVersion: string;
lastHeartbeatAt: Date | null;
lastIp: string;
stateNote: string;
updateProgress: string;
createdAt: Date;
updatedAt: Date;
class?: { id: string; name: string } | null;
};
type CommandRow = {
id: string;
deviceId: string;
kind: string;
payload: string;
createdAt: Date;
expiresAt: Date | null;
ackedAt: Date | null;
result: string;
};
/** 备注存 JSON 文本(`payload` 字段是预留结构,见 schema 注释) */
function encodePayload(note: string): string {
return JSON.stringify({ note });
}
function decodePayload(raw: string): string {
if (!raw) return '';
try {
const parsed = JSON.parse(raw) as { note?: unknown };
return typeof parsed.note === 'string' ? parsed.note : '';
} catch {
// 兼容手工写进库的纯文本
return raw;
}
}
function toCommandDto(row: CommandRow): ClientCommandDto {
const kind = row.kind as ClientCommandKind;
const label = CLIENT_COMMAND_LABELS[kind] ?? row.kind;
const note = decodePayload(row.payload);
return {
id: row.id,
deviceId: row.deviceId,
kind,
payload: note ? `${label}(${note})` : label,
createdAt: row.createdAt.toISOString(),
expiresAt: row.expiresAt ? row.expiresAt.toISOString() : null,
ackedAt: row.ackedAt ? row.ackedAt.toISOString() : null,
result: row.result,
};
}
/** 待执行的命令:未回执、未撤销、未过期 */
function pendingCommandWhere(deviceIds: string[], now: Date) {
return {
deviceId: { in: deviceIds },
ackedAt: null,
cancelledAt: null,
OR: [{ expiresAt: null }, { expiresAt: { gt: now } }],
};
}
function summarize(results: ClientTargetResult[]): ClientPushResult {
const succeeded = results.filter((item) => item.ok).length;
return { total: results.length, succeeded, failed: results.length - succeeded, results };
}
/** 班级端会话(含班级账号)的代表主体就是那个班;教师/管理员个人电脑不绑定班级 */
function resolveClassId(user: TokenPayload): string | null {
return user.classSession || user.role === 'CLASS_DEVICE' ? user.sub : null;
}
async function findPendingCommand(deviceId: string, now: Date): Promise<CommandRow | null> {
const rows = (await prisma.clientCommand.findMany({
where: pendingCommandWhere([deviceId], now),
orderBy: { createdAt: 'asc' },
take: 1,
})) as unknown as CommandRow[];
return rows[0] ?? null;
}
/**
* POST /api/clients/heartbeat - 客户端上报心跳,服务端在同一响应里带回
* 「要不要更新 + 目标版本的安装包信息 + 一条待执行命令」。
*/
export async function heartbeat(
user: TokenPayload,
input: ClientHeartbeatInput,
ip: string,
): Promise<ClientHeartbeatResponse> {
const boundClassId = resolveClassId(user);
assertClassDevice(user, boundClassId ?? '');
const previousDevice = await prisma.clientDevice.findUnique({ where: { deviceKey: input.deviceKey } });
if (previousDevice && previousDevice.classId !== boundClassId)
throw ApiError.forbidden('设备不属于当前班级');
const now = new Date();
const heartbeatAt = {
classId: resolveClassId(user),
name: input.name?.trim() || '未命名设备',
clientVersion: input.clientVersion?.trim() ?? '',
platform: input.platform?.trim() ?? '',
autoUpdate: input.autoUpdate !== false,
pendingVersion: input.pendingVersion?.trim() ?? '',
stateNote: input.stateNote?.trim() ?? '',
lastHeartbeatAt: now,
lastIp: ip,
};
const device = (await prisma.clientDevice
.upsert({
where: { deviceKey: input.deviceKey, classId: boundClassId },
create: { deviceKey: input.deviceKey, ...heartbeatAt },
update: heartbeatAt,
})
.catch(async (error: unknown) => {
const current = await prisma.clientDevice.findUnique({ where: { deviceKey: input.deviceKey } });
if (current && current.classId !== boundClassId) throw ApiError.forbidden('设备不属于当前班级');
throw error;
})) as unknown as DeviceRow;
const targetVersion = device.updateTargetVersion.trim();
if (targetVersion && input.clientVersion && compareVersions(input.clientVersion, targetVersion) >= 0) {
await prisma.clientDevice.updateMany({
where: { id: device.id, updateTargetVersion: targetVersion },
data: {
pendingVersion: '',
updateProgress: JSON.stringify({
version: input.clientVersion,
stage: 'completed',
downloadedBytes: 0,
totalBytes: 0,
percent: 100,
error: '',
updatedAt: now.toISOString(),
}),
},
});
} else if (input.updateProgress && input.updateProgress.stage !== 'idle') {
await reportUpdateProgress(user, input.deviceKey, input.updateProgress);
}
const [command, update] = await Promise.all([
findPendingCommand(device.id, now),
targetVersion ? clientReleases.resolveUpdateInfo(targetVersion) : Promise.resolve(null),
]);
return {
deviceId: device.id,
serverTime: now.toISOString(),
updateTargetVersion: targetVersion || null,
updateMode: device.updateMode,
updateNotBefore: device.updateNotBefore?.toISOString() ?? null,
// 旧客户端没有时机判断:到放学时间前不提供包,避免它提前安装。
update:
input.agentProtocol !== 2 &&
device.updateMode === 'after-school' &&
device.updateNotBefore &&
now < device.updateNotBefore
? null
: update,
command: command ? toCommandDto(command) : null,
};
}
export async function reportUpdateProgress(
user: TokenPayload,
deviceKey: string,
progress: ClientUpdateProgressDto,
) {
const device = await prisma.clientDevice.findUnique({ where: { deviceKey } });
assertClassDevice(user, device?.classId ?? '');
if (!device || device.classId !== resolveClassId(user)) throw ApiError.forbidden('设备不属于当前班级');
// 已取消或更换目标的迟到进度不得覆盖当前任务。
if (progress.version !== device.updateTargetVersion || progress.stage === 'completed') return;
const previous = readUpdateProgress(device.updateProgress);
if (previous?.version === progress.version && previous.stage === 'completed') return;
const stages = ['idle', 'downloading', 'verifying', 'ready', 'waiting', 'installing', 'completed'];
if (
previous?.version === progress.version &&
previous.stage !== 'failed' &&
progress.stage !== 'failed' &&
!progress.error &&
stages.indexOf(progress.stage) < stages.indexOf(previous.stage)
)
return;
await prisma.clientDevice.updateMany({
where: {
id: device.id,
updateTargetVersion: progress.version,
updateProgress: device.updateProgress,
},
data: {
updateProgress: JSON.stringify({ ...progress, updatedAt: new Date().toISOString() }),
},
});
}
function readUpdateProgress(raw: string): ClientUpdateProgressDto | null {
try {
return raw ? JSON.parse(raw) : null;
} catch {
return null;
}
}
/** POST /api/clients/commands/:id/ack - 客户端执行完远控命令后的回执 */
export async function ackCommand(
user: TokenPayload,
commandId: string,
input: ClientCommandAckRequest,
): Promise<ClientCommandDto> {
const command = (await prisma.clientCommand.findUnique({
where: { id: commandId },
include: { device: { select: { deviceKey: true, name: true, classId: true } } },
})) as (CommandRow & { device: { deviceKey: string; name: string; classId: string | null } }) | null;
if (!command) throw ApiError.notFound('命令不存在');
assertClassDevice(user, command.device.classId ?? '');
if (command.device.deviceKey !== input.deviceKey) {
throw ApiError.forbidden('这条命令不是发给这台电脑的');
}
// 幂等:客户端重试回执不报错,也不覆盖第一次的结果
if (command.ackedAt) return toCommandDto(command);
const detail = input.result?.trim();
const result = `${input.ok ? '已执行' : '执行失败'}${detail ? `:${detail}` : ''}`;
const updated = (await prisma.clientCommand.update({
where: { id: commandId },
data: { ackedAt: new Date(), result },
})) as unknown as CommandRow;
logger.info(`远控命令回执:${command.device.name || command.device.deviceKey} ${result}`);
return toCommandDto(updated);
}
/** GET /api/clients/devices - Web 端「客户端设备」列表(含待执行命令) */
export async function listDevices(
user: TokenPayload,
options: { classId?: string } = {},
): Promise<ClientDeviceDto[]> {
const scope = await resolveClassScope(user, options.classId, 'client:read');
const rows = (await prisma.clientDevice.findMany({
where: classScopeWhere(scope),
include: { class: { select: { id: true, name: true } } },
orderBy: [{ lastHeartbeatAt: 'desc' }, { createdAt: 'desc' }],
})) as unknown as DeviceRow[];
const now = new Date();
const commands = (await prisma.clientCommand.findMany({
where: pendingCommandWhere(
rows.map((row) => row.id),
now,
),
orderBy: { createdAt: 'asc' },
})) as unknown as CommandRow[];
// 每台设备只留最早的一条(与心跳取的是同一条,界面上看到的才是真会执行的那条)
const pendingByDevice = new Map<string, CommandRow>();
for (const command of commands) {
if (!pendingByDevice.has(command.deviceId)) pendingByDevice.set(command.deviceId, command);
}
// 「最近一条命令」:待执行的那条在取消 / 超时之后就从 pendingCommand 里消失了,
// Web 端于是看不出"我刚点的锁屏到底怎么了"。取最近 500 条(够覆盖一次批量下发)按设备分组。
const recent = (await prisma.clientCommand.findMany({
where: { deviceId: { in: rows.map((row) => row.id) } },
orderBy: { createdAt: 'desc' },
take: 500,
})) as unknown as CommandRow[];
const lastByDevice = new Map<string, CommandRow>();
for (const command of recent) {
if (!lastByDevice.has(command.deviceId)) lastByDevice.set(command.deviceId, command);
}
return rows.map((row) => {
const heartbeat = row.lastHeartbeatAt;
const pending = pendingByDevice.get(row.id);
const last = lastByDevice.get(row.id);
return {
id: row.id,
classId: row.classId,
className: row.class?.name ?? null,
deviceKey: row.deviceKey,
name: row.name,
clientVersion: row.clientVersion,
platform: row.platform,
autoUpdate: row.autoUpdate,
updateTargetVersion: row.updateTargetVersion,
updateMode: row.updateMode,
updateNotBefore: row.updateNotBefore?.toISOString() ?? null,
pendingVersion: row.pendingVersion,
lastHeartbeatAt: heartbeat ? heartbeat.toISOString() : null,
lastIp: row.lastIp,
stateNote: row.stateNote,
updateProgress: readUpdateProgress(row.updateProgress),
online: Boolean(heartbeat && now.getTime() - heartbeat.getTime() < CLIENT_ONLINE_WINDOW_MS),
pendingCommand: pending ? toCommandDto(pending) : null,
lastCommand: last ? toCommandDto(last) : null,
createdAt: row.createdAt.toISOString(),
updatedAt: row.updatedAt.toISOString(),
};
});
}
/** 命令去重后的目标设备(保持请求顺序,便于结果一一对应) */
async function findTargetDevices(user: TokenPayload, deviceIds: string[]): Promise<Map<string, DeviceRow>> {
const wanted = [...new Set(deviceIds)];
const scope = classScopeWhere(await resolveClassScope(user, undefined, 'remote:control'));
const rows = (await prisma.clientDevice.findMany({
where: { AND: [scope, { id: { in: wanted } }] },
select: { id: true, name: true, deviceKey: true },
})) as unknown as DeviceRow[];
if (rows.length !== wanted.length) throw ApiError.forbidden('部分设备超出管理范围');
return new Map(rows.map((row) => [row.id, row]));
}
/**
* POST /api/clients/commands - 下发远控命令(关机/重启/注销/锁屏)
*
* 同一台机器上还没执行的旧命令会被**自动撤销**:否则"先关机、后重启"会排队执行,
* 机器刚关就被下一条叫起来,看起来像失控。客户端收到即执行,并以设备标识回执真实结果。
*/
export async function createCommands(
user: TokenPayload,
input: CreateClientCommandInput,
): Promise<ClientPushResult> {
const targets = await findTargetDevices(user, input.deviceIds);
const expiresAt = new Date(Date.now() + CLIENT_COMMAND_EXPIRE_MS);
const note = input.note?.trim() ?? '';
const results: ClientTargetResult[] = [];
for (const deviceId of [...new Set(input.deviceIds)]) {
const device = targets.get(deviceId);
if (!device) {
results.push({
deviceId,
deviceName: '',
ok: false,
code: 'DEVICE_NOT_FOUND',
message: '设备不存在(可能已被移除)',
});
continue;
}
await prisma.clientCommand.updateMany({
where: { deviceId, ackedAt: null, cancelledAt: null },
data: { cancelledAt: new Date(), result: '已被新的命令取代' },
});
await prisma.clientCommand.create({
data: { deviceId, kind: input.kind, payload: encodePayload(note), createdBy: user.sub, expiresAt },
});
results.push({ deviceId, deviceName: device.name, ok: true });
}
const summary = summarize(results);
logger.info(
`下发远控命令 ${input.kind}:目标 ${summary.total} 台,成功 ${summary.succeeded} 台(发起人=${user.username})`,
);
return summary;
}
/** 更新推送的目标集合:优先设备,其次班级,最后"全部" */
async function resolveUpdateTargets(user: TokenPayload, input: PushClientUpdateInput): Promise<DeviceRow[]> {
const scope = classScopeWhere(await resolveClassScope(user, undefined, 'client:update-push'));
const deviceIds = [...new Set(input.deviceIds ?? [])];
if (deviceIds.length > 0) {
const rows = (await prisma.clientDevice.findMany({
where: { AND: [scope, { id: { in: deviceIds } }] },
select: { id: true, name: true, classId: true },
})) as unknown as DeviceRow[];
return rows;
}
const classIds = [...new Set(input.classIds ?? [])];
if (classIds.length > 0) {
return (await prisma.clientDevice.findMany({
where: { AND: [scope, { classId: { in: classIds } }] },
select: { id: true, name: true, classId: true },
})) as unknown as DeviceRow[];
}
if (input.all) {
return (await prisma.clientDevice.findMany({
where: scope,
select: { id: true, name: true, classId: true },
})) as unknown as DeviceRow[];
}
throw ApiError.badRequest('请选择要推送的设备、班级,或选择"全部设备"');
}
/**
* POST /api/clients/updates - 统一下发客户端更新
*
* `version` 省略时用服务端缓存里最新的那个版本;`clear: true` 取消下发。
* 保存目标版本和安装策略,下载、安装由客户端在心跳后执行。
*/
export async function pushUpdate(
user: TokenPayload,
input: PushClientUpdateInput,
): Promise<ClientPushResult> {
const clear = input.clear === true;
let target = '';
if (!clear) {
target = (input.version ?? '').trim() || (await clientReleases.latestReleaseVersion());
if (!target) {
throw ApiError.badRequest('服务端还没有缓存任何客户端安装包,请先下载或登记一份再推送');
}
const info = await clientReleases.resolveUpdateInfo(target);
if (!info) throw ApiError.badRequest(`服务端缺少 v${target} 的安装包文件,请重新下载或登记`);
}
const devices = await resolveUpdateTargets(user, input);
if (devices.length === 0) throw ApiError.badRequest('没有匹配到任何客户端设备');
const results: ClientTargetResult[] = [];
const notBeforeByClass = new Map<string | null, Date>();
for (const device of devices) {
let notBefore: Date | null = null;
if (!clear && input.mode === 'after-school') {
notBefore =
notBeforeByClass.get(device.classId) ?? (await afterSchoolAt(device.classId, input.afterSchoolTime));
notBeforeByClass.set(device.classId, notBefore);
}
await prisma.clientDevice.update({
where: { id: device.id },
data: {
updateTargetVersion: target,
updateProgress: '',
updateMode: clear ? 'idle' : input.mode,
updateNotBefore: notBefore,
},
});
results.push({ deviceId: device.id, deviceName: device.name, ok: true });
}
const summary = summarize(results);
logger.info(
clear
? `取消更新下发:${summary.total} 台设备(发起人=${user.username})`
: `推送客户端更新 v${target}:${summary.total} 台设备(发起人=${user.username})`,
);
return summary;
}
/** 按当前教学周、单双周与星期计算今天放学时间;未绑定班级使用明确的兜底时间。 */
async function afterSchoolAt(classId: string | null, fallback = '17:00'): Promise<Date> {
const now = new Date();
let end = fallback;
if (classId) {
const active = await resolveActiveClassPlan(classId, now);
const last = [...active.schedules].sort((a, b) => b.endTime.localeCompare(a.endTime))[0];
if (last && last.endTime > end) end = last.endTime;
}
const [hours, minutes] = end.split(':').map(Number);
const at = new Date(now);
at.setHours(hours!, minutes!, 0, 0);
return at;
}
/** DELETE /api/clients/devices/:id - 移除一台设备记录(换机 / 旧机器清理) */
export async function deleteDevice(user: TokenPayload, deviceId: string): Promise<{ id: string }> {
const scope = classScopeWhere(await resolveClassScope(user, undefined, 'client:manage'));
const device = await prisma.clientDevice.findFirst({
where: { AND: [scope, { id: deviceId }] },
select: { id: true, name: true, deviceKey: true },
});
if (!device) throw ApiError.notFound('设备不存在');
await prisma.clientDevice.delete({ where: { id: deviceId } });
logger.info(`移除客户端设备:${device.name || device.deviceKey}`);
return { id: deviceId };
}