fix(clients,client,web): 远控指令的两个修复 —— 执行失败不再谎报成功 + 「上次指令」让"点了没反应"可见（1.3.2）

背景：用户报「下发锁屏等等指令不生效」。先把服务端那条链路单独验了一遍
（模拟客户端：登记 → 下发 → 心跳带回 → 设备列表可见 → 回执 → 清除），**整条是通的**；
真正的问题在两处。

客户端：执行失败会谎报成功
- `spawn` 找不到可执行文件 / 没权限时**不抛异常**，而是在下一个 tick 发一个异步 `error` 事件 ——
  只包 `try/catch` 抓不到，代码一路走到 `return { ok: true }`，回执写着「已下达系统命令」，
  Web 端看起来一切正常而机器纹丝不动
- 现在等一个 200ms 的窗口确认没有立刻报错，失败如实回执（`client-agent.ts` 的 `executeCommand`）

Web 端：点了没生效，界面上什么都不说
- 一条命令被**取消 / 过期**之后就从 `pendingCommand` 里消失，页面留白 ——
  而最常见的两种"没反应"恰恰是「本机没人确认（客户端 60 秒自动按取消）」与「下达时机器离线」
- `GET /clients/devices` 增加 `lastCommand`（最近一条，不论状态）；
  「客户端」页的设备表多一列「上次指令」，由 `commandStateText()` 翻成一句人话
  （已执行 / 本机用户取消 / 已过期 —— 下达时机器不在线 / 待执行）
- 下发成功的提示补上「60 秒内没人点确认就按取消处理」

文档
- AGENTS.md §5 第 69 条记下这两条，并写明排查同类反馈的顺序：**先看那台机器的客户端版本是否 ≥ 1.3.0**
  （远控命令的处理 `client-agent.ts` 是 1.3.0 才有的，旧客户端连心跳都不发）
- docs/reference.md 4.15 的表格补上「二次确认」的准确口径与新增的「上次指令」列

验收：`lint` / `typecheck` / `check:icons` / `docs:check` 全绿；
后端端到端 **247/247**、联动链路 **44/44**、插件静态契约 **76/76**、
Web 真实点击 **34/34**、客户端冒烟 **90/90**；
远控链路另用模拟客户端跑通，并确认新增的「上次指令」在待执行与已回执两种状态下都显示正确。

packages/classisland-plugin/manifest.yml

@@ -14,6 +14,6 @@ description: |-
   4. 可选：把 ClassHelper上排好的课表镜像回 ClassIsland。
 entranceAssembly: 'ClassHelper.ClassIslandPlugin.dll'
 url: https://github.com/LoveChengke/ClassHelper
-version: 1.3.1.0
+version: 1.3.2.0
 apiVersion: 2.0.0.0
 author: ClassHelper

packages/classisland-plugin/src/Services/BridgeService.cs

@@ -514,7 +514,7 @@ public sealed class BridgeService : INotifyPropertyChanged, IDisposable
     /* ---------------------------------------------------------------- 内部实现 */
 
     /// <summary>插件版本（与 manifest.yml / csproj 保持一致）。</summary>
-    private const string PluginVersion = "1.3.1.0";
+    private const string PluginVersion = "1.3.2.0";
 
     /// <summary>ClassIsland 版本读不到时不该让上报失败（开发版可能为 null）。</summary>
     private static string SafeAppVersion()

packages/desktop-client/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classhelper/desktop-client",
-  "version": "1.3.1",
+  "version": "1.3.2",
   "private": true,
   "description": "ClassHelper EXE 客户端（Electron + Vue 3 + Element Plus + Socket.IO + IndexedDB 离线缓存）",
   "author": "Class Helper",

packages/desktop-client/src/main/client-agent.ts

@@ -317,7 +317,22 @@ async function executeCommand(kind: ClientCommandKind): Promise<{ ok: boolean; r
 
   try {
     // detached + unref：不能等它退出（关机/注销会把本进程一起带走）
-    spawn(plan.file, plan.args, { detached: true, stdio: 'ignore', windowsHide: true }).unref();
+    const child = spawn(plan.file, plan.args, { detached: true, stdio: 'ignore', windowsHide: true });
+    /**
+     * **必须监听 `error` 事件**：`spawn` 找不到可执行文件（或没权限）时不是抛异常，而是在
+     * next tick 上发一个 `error` 事件 —— 只包 `try/catch` 的话，这种情况会一路走到
+     * `return { ok: true }`，回执写着"已下达系统命令"，Web 端看起来一切正常，机器却纹丝不动。
+     * 等一个很短的窗口（200ms）确认没有立刻报错；真执行成功时子进程本来也要跑一会儿。
+     */
+    const failure = await new Promise<string | null>((resolve) => {
+      child.once('error', (error) => resolve(error.message));
+      setTimeout(() => resolve(null), 200);
+    });
+    child.unref();
+    if (failure) {
+      logger.warn(`远控命令「${CLIENT_COMMAND_LABELS[kind] ?? kind}」无法执行：${failure}`);
+      return { ok: false, result: failure };
+    }
     return { ok: true, result: '已下达系统命令' };
   } catch (error) {
     return { ok: false, result: error instanceof Error ? error.message : String(error) };

packages/server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classhelper/server",
-  "version": "1.3.1",
+  "version": "1.3.2",
   "private": true,
   "description": "ClassHelper后端服务：REST API + Socket.IO 实时推送 + Prisma 数据访问",
   "type": "module",

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

@@ -209,9 +209,22 @@ export async function listDevices(options: { classId?: string } = {}): Promise<C
     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,
@@ -228,6 +241,7 @@ export async function listDevices(options: { classId?: string } = {}): Promise<C
       stateNote: row.stateNote,
       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(),
     };

packages/shared/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classhelper/shared",
-  "version": "1.3.1",
+  "version": "1.3.2",
   "private": true,
   "description": "ClassHelper - 三端共享的类型、常量与工具函数",
   "type": "module",

packages/shared/src/types.ts

@@ -1901,6 +1901,14 @@ export interface ClientDeviceDto {
   online: boolean;
   /** 该设备当前待执行（未回执、未撤销、未过期）的命令；没有则 null */
   pendingCommand: ClientCommandDto | null;
+  /**
+   * **最近一条**远控命令（不管什么状态），用于回答「我刚点了锁屏，怎么没反应？」。
+   *
+   * 待执行的那条在取消 / 超时之后就从 `pendingCommand` 里消失了，Web 端于是一片空白 ——
+   * 而最常见的两种失败恰恰是"本机没人确认（60 秒自动取消）"和"设备当时离线"。
+   * 把结果摆出来，老师才知道该去哪儿补上那一下确认。
+   */
+  lastCommand?: ClientCommandDto | null;
   createdAt: string;
   updatedAt: string;
 }

packages/web-admin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classhelper/web-admin",
-  "version": "1.3.1",
+  "version": "1.3.2",
   "private": true,
   "description": "ClassHelper Web 管理端（Vue 3 + Vite + Element Plus）",
   "type": "module",

packages/web-admin/src/views/ClientHubView.vue

@@ -11,6 +11,7 @@ import {
   relativeTime,
   type ClassDto,
   type ClassHelperStatusDto,
+  type ClientCommandDto,
   type ClientCommandKind,
   type ClientDeviceDto,
   type IntegrationDeviceDto,
@@ -280,8 +281,27 @@ async function pushUpdateToClass(): Promise<void> {
   await loadAll();
 }
 
-async function sendCommand(kind: ClientCommandKind): Promise<void> {
-  const current = detail.value;
+/** 命令种类的中文名。包一层是因为表格插槽里的 `row` 是 any，直接索引常量表过不了类型检查 */
+function commandLabel(command: ClientCommandDto): string {
+  return CLIENT_COMMAND_LABELS[command.kind] ?? command.kind;
+}
+
+/**
+ * 一条远控命令"现在究竟怎么样了"。
+ *
+ * 待执行的那条会在**取消 / 超时**之后从 `pendingCommand` 里消失，界面上不留痕迹 ——
+ * 而最常见的两种"点了没反应"恰恰是：本机没人确认（客户端 60 秒自动按取消）与设备当时离线。
+ * 服务端把最近一条也返回（`lastCommand`），这里把它翻成一句人话。
+ */
+function commandStateText(command: ClientCommandDto): string {  if (command.result) return command.result;
+  if (command.ackedAt) return '已执行';
+  if (command.expiresAt && Date.parse(command.expiresAt) < Date.now()) {
+    return '已过期 —— 下达时机器不在线（命令有效期 10 分钟）';
+  }
+  return '待执行（等这台机器的下一次心跳）';
+}
+
+async function sendCommand(kind: ClientCommandKind): Promise<void> {  const current = detail.value;
   if (!current || current.clients.length === 0) return;
   const label = CLIENT_COMMAND_LABELS[kind];
   await ElMessageBox.confirm(
@@ -295,7 +315,10 @@ async function sendCommand(kind: ClientCommandKind): Promise<void> {
     kind,
     note: `由 ${auth.user?.name ?? '管理员'} 下达`,
   });
-  ElMessage.success(`已下发：成功 ${result.succeeded} / 共 ${result.total} 台`);
+  ElMessage.success(
+    `已下发：成功 ${result.succeeded} / 共 ${result.total} 台 —— ` +
+      '机器上会弹出默认选中「取消」的确认框，60 秒内没人点「确认执行」就按取消处理（详情表里能看到结果）',
+  );
   await loadAll();
 }
 
@@ -577,6 +600,14 @@ onUnmounted(() => {
               </template>
             </el-table-column>
             <el-table-column prop="stateNote" label="状态说明" min-width="140" />
+            <el-table-column label="上次指令" min-width="200">
+              <template #default="{ row }">
+                <span v-if="!row.lastCommand" class="row-value muted">—</span>
+                <span v-else>
+                  {{ commandLabel(row.lastCommand) }} · {{ commandStateText(row.lastCommand) }}
+                </span>
+              </template>
+            </el-table-column>
             <el-table-column label="操作" width="90" fixed="right">
               <template #default="{ row }">
                 <el-button link type="danger" :disabled="!canManageDevices" @click="removeClient(row)">