refactor(ui): 拆 ClassroomPage 第 4-6 步 — 左栏/窗口/浮窗

Author: Aparencia

app/src/components/ClassroomSourceColumn.tsx

@@ -0,0 +1,157 @@
+/**
+ * ClassroomSourceColumn — 课堂助手左栏配置列（批 0-C2 Task 4 步 4 自
+ * ClassroomPage.tsx 抽出，纯搬运、行为等价）。
+ *
+ * @ai-context: 结构 = 折叠态单元素（ColumnBar 窄条）或展开态外壳 div（标题「📡 课堂助手」+
+ *              健康徽标 + 折叠钮 → 横幅插槽 → 滚动容器：就绪清单 / 系统窗口开关 /
+ *              窗口选择卡 / 捕获卡插槽 / 四条采集动线面板 / 状态行）。横幅与捕获卡由
+ *              页面以 ReactNode 注入（banners / capturePanel）——本文件不订阅任何事件、
+ *              不持有状态，全部输入经 props。
+ * @ai-context: ★ 顶层恰好返回**一个**元素（折叠态 ColumnBar，否则外壳 div）——根 flex
+ *              只有三个直接子元素（本列 + ColumnResizer + 右栏），多包一层或返回
+ *              Fragment 会改变 flex 分配与 borderRight/宽度语义，**且无编译错误**。
+ *              同理 `<ColumnResizer>` 是本列的**兄弟**、由页面在折叠三元之外无条件渲染，
+ *              不得搬进本文件（否则折叠态拖拽手柄消失）。
+ * @ai-context: 耦合逐字保留 —— 外壳内联样式键（width / flexShrink / borderRight /
+ *              display / flexDirection / minWidth）、`title="折叠侧栏"`、折叠钮 `⟨`、
+ *              文案「显示系统窗口（终端/资源管理器等）」、色值 #e5e7eb/#9ca3af/#6b7280、
+ *              间距 padding 10px 14px / gap 12 / padding 12 均为现状契约；本文件零
+ *              className / 零 id / 零 data-testid，不 token 化、不换 emoji。
+ * @ai-context: 边界 —— 就绪清单（ReadyCheckCard）与页内模型卡的矛盾（G6）、采集中仍可
+ *              改选窗口（G7）是既有缺陷，本批只搬不改。
+ */
+import { WindowSelectCard } from "./WindowSelectCard";
+import VideoImportPanel from "./VideoImportPanel";
+import ReadyCheckCard from "./ReadyCheckCard";
+import { SystemStatusBadge } from "./SystemStatusBadge";
+import ColumnBar from "./ColumnBar";
+import MaterialInputPanel from "./MaterialInputPanel";
+import PhotoCapturePanel from "./PhotoCapturePanel";
+import WebImportPanel from "./WebImportPanel";
+import type { ReactNode } from "react";
+import type { Note, WindowInfo } from "../types";
+
+interface Props {
+  /** 生效折叠态（useColumnLayout.folded：自动折叠或手动折叠任一成立） */
+  folded: boolean;
+  /** 生效列宽（useColumnLayout.width，已夹取 min..max） */
+  width: number;
+  /** 点窄条展开（useColumnLayout.expand：同时清自动/手动折叠态） */
+  onExpand: () => void;
+  /** 标题栏折叠钮（useColumnLayout.setManualFolded(true)） */
+  onFold: () => void;
+  /** 页面级提示横幅插槽（ClassroomBanners——须保持为左栏 div 的直接子元素） */
+  banners: ReactNode;
+  /** 实时捕获卡插槽（ClassroomCapturePanel） */
+  capturePanel: ReactNode;
+  /** 窗口枚举结果（系统窗口开关的可显性判据 + 列表数据源） */
+  windows: WindowInfo[];
+  selectedWindow: WindowInfo | null;
+  onSelectWindow: (win: WindowInfo) => void;
+  /** 重新枚举窗口（background=true 时不显示 loading——列表内刷新用） */
+  onRefreshWindows: (background?: boolean) => void;
+  windowsLoading: boolean;
+  /** 显示系统窗口（终端/资源管理器等）开关 */
+  showSystemWindows: boolean;
+  onShowSystemWindows: (show: boolean) => void;
+  onOpenSessions?: (sessionId: number) => void;
+  /** MaterialInputPanel 产物回填（页面 lastNote） */
+  onNote: (note: Note) => void;
+  /** 状态行（页面 status 单一状态源） */
+  status: string;
+  onStatus: (message: string) => void;
+}
+
+export default function ClassroomSourceColumn({
+  folded,
+  width,
+  onExpand,
+  onFold,
+  banners,
+  capturePanel,
+  windows,
+  selectedWindow,
+  onSelectWindow,
+  onRefreshWindows,
+  windowsLoading,
+  showSystemWindows,
+  onShowSystemWindows,
+  onOpenSessions,
+  onNote,
+  status,
+  onStatus,
+}: Props) {
+  return folded ? (
+    <ColumnBar icon="📡" title="课堂助手" onClick={onExpand} />
+  ) : (
+      <div
+        style={{
+          width,
+          flexShrink: 0,
+          borderRight: "1px solid #e5e7eb",
+          display: "flex",
+          flexDirection: "column",
+          minWidth: 0,
+        }}
+      >
+        <div style={{ padding: "10px 14px", borderBottom: "1px solid #e5e7eb", fontWeight: 600, display: "flex", alignItems: "center", justifyContent: "space-between" }}>
+          <span>📡 课堂助手</span>
+          <div style={{ display: "flex", alignItems: "center", gap: 4 }}>
+            {/* M7/REQ-042 F2/G2：健康徽标 + 诊断面板（开发期可见） */}
+            <SystemStatusBadge />
+            <button onClick={() => onFold()} style={{ fontSize: 12, cursor: "pointer", border: "none", background: "none", color: "#9ca3af" }} title="折叠侧栏">⟨</button>
+          </div>
+        </div>
+
+        {banners}
+
+        <div style={{ flex: 1, minHeight: 0, padding: 12, overflowY: "auto", display: "flex", flexDirection: "column", gap: 12 }}>
+          {/* 2026-08 C1：引擎与模型就绪清单（开始前准备流——缺什么一目了然） */}
+          <ReadyCheckCard />
+
+          {/* 目标窗口/进程选择（v0.2.0 实时捕获上下文） */}
+          {/* v0.19.2（用户实测）：系统窗口默认过滤，开关找回（能力不丢） */}
+          {windows.some((w) => w.systemWindow) && (
+            <label style={{ fontSize: 11, color: "#6b7280", display: "flex", alignItems: "center", gap: 4, cursor: "pointer" }}>
+              <input
+                type="checkbox"
+                checked={showSystemWindows}
+                onChange={(e) => onShowSystemWindows(e.target.checked)}
+              />
+              显示系统窗口（终端/资源管理器等）
+            </label>
+          )}
+          <WindowSelectCard
+            windows={showSystemWindows ? windows : windows.filter((w) => !w.systemWindow)}
+            selected={selectedWindow}
+            onSelect={onSelectWindow}
+            onRefresh={onRefreshWindows}
+            loading={windowsLoading}
+          />
+
+          {capturePanel}
+
+          {/* 视频文件导入（v0.3.0：REQ-015 第二入口，字幕优先 + ASR fallback） */}
+          <VideoImportPanel onOpenSessions={onOpenSessions} />
+
+          {/* 2026-08-21 用户需求：OCR 设备/音频预处理/备份/AI 服务/词表/模型管理等
+              设置类面板已迁出至「⚙ 设置」页——课堂助手左栏仅保留采集动线 */}
+
+          {/* 素材输入 + 提取按钮（v0.1.0 文件流水线；审查硬拆——MaterialInputPanel） */}
+          <MaterialInputPanel
+            windowTitle={selectedWindow?.title ?? null}
+            onNote={onNote}
+            onStatus={onStatus}
+          />
+
+          {/* v0.11.7：图文采集（第三动线：截屏导入图文内容 → 图文会话） */}
+          <PhotoCapturePanel onOpenSessions={onOpenSessions} onStatus={onStatus} />
+
+          {/* v0.20.4（REQ-303）：web 采集（第四条动线：URL 静态直取 → kind=web 会话） */}
+          <WebImportPanel onOpenSessions={onOpenSessions} onStatus={onStatus} />
+
+          {status && <p style={{ fontSize: 12, color: "#2563eb" }}>{status}</p>}
+        </div>
+      </div>
+  );
+}

app/src/hooks/useClassroomFloat.ts

@@ -0,0 +1,78 @@
+/**
+ * useClassroomFloat — 课堂助手采集浮窗状态与浮窗快捷键（批 0-C2 Task 4 步 6 自
+ * ClassroomPage.tsx 抽出，纯搬运、行为等价）。
+ *
+ * @ai-context: 浮窗三态（浮窗化 ⇄ 收起 ⇄ 解锁点击穿透）的唯一真源是 Rust
+ *              （ADR-025 float_toggle_core）——本 hook 只做三件事：①挂载拉取
+ *              `float_state`；②订阅 `float:state` 事件回流；③按钮与快捷键统一调
+ *              `float_toggle`，前端不自行推导状态。
+ * @ai-context: ★ R4 —— Ctrl+Shift+F 是**两个** window keydown 中的第二个（第一个
+ *              Ctrl+Shift+S 在 useClassroomShortcuts），deps 必须逐字保持
+ *              `[active, floatSnap.open, toggleFloat]` 且保留 `active && !floatSnap.open`
+ *              守卫：浮窗打开期间该键已升级为 Rust 全局快捷键，主窗必须让位，
+ *              否则一次按键双触发双翻转。preventDefault 位置与成对 cleanup 不变。
+ * @ai-context: 副作用与边界 —— invoke `float_state` / `float_toggle`；挂载拉取带
+ *              `disposed` 守卫（卸载后不 setState）；切换失败**不吞**，经
+ *              `onLiveError` 写页面错误横幅（「浮窗切换失败: …」逐字保留）。
+ */
+import { useCallback, useEffect, useState } from "react";
+import { invoke } from "@tauri-apps/api/core";
+import { listen } from "@tauri-apps/api/event";
+import type { FloatSnapshot } from "./useFloatWindow";
+
+interface Options {
+  /** 采集中（未采集时 Ctrl+Shift+F 不生效——与拆分前一致） */
+  active: boolean;
+  /** 错误横幅写入（页面 liveError 单一状态源） */
+  onLiveError: (message: string) => void;
+}
+
+export function useClassroomFloat({ active, onLiveError }: Options) {
+  // v0.12.3：浮窗状态（按钮语义：浮窗化 ⇄ 收起 ⇄ 解锁穿透；Rust 单一来源）
+  const [floatSnap, setFloatSnap] = useState<FloatSnapshot>({ open: false, locked: false, topmost: true });
+
+  // v0.12.0 M6：浮窗化快捷键 Ctrl+Shift+F（采集中一键浮窗——全屏看视频不中断）
+  // v0.12.6（ADR-025）：三态语义收拢到 Rust float_toggle（单一来源，防主窗键与
+  // 全局快捷键双触发双翻转）——前端按钮/键只调 toggle，状态由 float:state 事件回流
+  const toggleFloat = useCallback(() => {
+    void invoke<FloatSnapshot>("float_toggle")
+      .then(setFloatSnap)
+      .catch((err) => onLiveError(`浮窗切换失败: ${err}`));
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  // v0.12.3：浮窗状态同步（挂载拉取 + float:state 事件订阅——Rust 单一来源）
+  useEffect(() => {
+    let disposed = false;
+    const unlisteners: Promise<() => void>[] = [];
+    void invoke<FloatSnapshot>("float_state")
+      .then((s) => {
+        if (!disposed) setFloatSnap(s);
+      })
+      .catch(() => undefined);
+    unlisteners.push(
+      listen<FloatSnapshot>("float:state", (e) => {
+        if (!disposed) setFloatSnap(e.payload);
+      }),
+    );
+    return () => {
+      disposed = true;
+      unlisteners.forEach((p) => void p.then((fn) => fn()));
+    };
+  }, []);
+
+  useEffect(() => {
+    const onKey = (e: KeyboardEvent) => {
+      // v0.12.6：仅浮窗关闭时生效——浮窗打开期间快捷键已升级为全局快捷键
+      // （Rust 侧统一处理，语义见 float_toggle_core），此处拦截避免双触发
+      if (active && !floatSnap.open && e.ctrlKey && e.shiftKey && (e.key === "F" || e.key === "f")) {
+        e.preventDefault();
+        toggleFloat();
+      }
+    };
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  }, [active, floatSnap.open, toggleFloat]);
+
+  return { floatSnap, toggleFloat };
+}

app/src/hooks/useClassroomShortcuts.ts

@@ -0,0 +1,41 @@
+/**
+ * useClassroomShortcuts — 课堂助手页面级快捷键（批 0-C2 Task 4 步 6 自
+ * ClassroomPage.tsx 抽出，纯搬运、行为等价）。
+ *
+ * @ai-context: v0.5.0 M6（REQ-051）用户截图快捷键 Ctrl+Shift+S——最高权重关键图
+ *              信号：采集中按下即 `save_user_screenshot`，成功写状态行、失败写错误
+ *              横幅（文案「📷 截图已保存（关键图候选置顶）」/「截图失败: …」逐字保留）。
+ * @ai-context: ★ R4 —— 本监听是**两个** window keydown 中的第一个，deps 必须保持
+ *              `[]`（拆分前即 `[]`；onStatus/onLiveError 都是稳定 setter，不入 deps
+ *              不改变重订阅时机）。`preventDefault()` 在 invoke 之前、成对 cleanup
+ *              不变。**不得**与 useClassroomFloat 的 Ctrl+Shift+F 合并成一个监听
+ *              （浮窗打开时主窗键必须让位 Rust 全局键，合并即行为变更）。
+ * @ai-context: 已知缺陷 B1（只搬不改）：正文 Ctrl+Shift+S 与 NoteEditView 拆段同键
+ *              双义（textarea 未 stopPropagation），本批行为等价、原样保留。
+ */
+import { useEffect } from "react";
+import { invoke } from "@tauri-apps/api/core";
+
+interface Options {
+  /** 状态行写入（页面 status 单一状态源） */
+  onStatus: (message: string) => void;
+  /** 错误横幅写入（页面 liveError 单一状态源） */
+  onLiveError: (message: string) => void;
+}
+
+export function useClassroomShortcuts({ onStatus, onLiveError }: Options) {
+  // v0.5.0 M6（REQ-051）：用户截图快捷键 Ctrl+Shift+S（最高权重关键图信号）
+  useEffect(() => {
+    const onKey = (e: KeyboardEvent) => {
+      if (e.ctrlKey && e.shiftKey && (e.key === "S" || e.key === "s")) {
+        e.preventDefault();
+        void invoke<string>("save_user_screenshot")
+          .then(() => onStatus("📷 截图已保存（关键图候选置顶）"))
+          .catch((err) => onLiveError(`截图失败: ${err}`));
+      }
+    };
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+}

app/src/hooks/useClassroomWindows.ts

@@ -0,0 +1,42 @@
+/**
+ * useClassroomWindows — 课堂助手目标窗口/进程枚举与选中态（批 0-C2 Task 4 步 5 自
+ * ClassroomPage.tsx 抽出，纯搬运、行为等价）。
+ *
+ * @ai-context: 职责 = `list_windows` 枚举 + 选中窗口：首挂载自动枚举一次，供左栏
+ *              窗口选择卡（含"系统窗口"过滤开关）与右栏档案检测消费；刷新入参
+ *              `background=true` 时不动 loading（列表内手动刷新不闪加载态）。
+ * @ai-context: 副作用与边界 —— 挂载时一次 invoke；枚举失败**不吞**，以
+ *              「窗口枚举失败: …」写回页面状态行（`onStatus`：页面 status 单一
+ *              状态源，D5）。本 hook 不订阅事件、不持有列宽/折叠（属 useColumnLayout），
+ *              也不管采集目标锁（G7「采集中仍可改选窗口」是既有缺陷，只搬不改）。
+ */
+import { useCallback, useEffect, useState } from "react";
+import { invoke } from "@tauri-apps/api/core";
+import type { WindowInfo } from "../types";
+
+export function useClassroomWindows(onStatus: (message: string) => void) {
+  // ── 窗口/进程选择 ──
+  const [windows, setWindows] = useState<WindowInfo[]>([]);
+  const [selectedWindow, setSelectedWindow] = useState<WindowInfo | null>(null);
+  const [windowsLoading, setWindowsLoading] = useState(false);
+
+  const refreshWindows = useCallback(async (background = false) => {
+    if (!background) setWindowsLoading(true);
+    try {
+      const list = await invoke<WindowInfo[]>("list_windows");
+      setWindows(list);
+    } catch (e) {
+      onStatus(`窗口枚举失败: ${e}`);
+    } finally {
+      if (!background) setWindowsLoading(false);
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  // 首次进入自动枚举一次窗口
+  useEffect(() => {
+    void refreshWindows();
+  }, [refreshWindows]);
+
+  return { windows, selectedWindow, setSelectedWindow, windowsLoading, refreshWindows };
+}