@@ -166,15 +169,41 @@ export function DeviceDetailClient({ id }: DeviceDetailClientProps) {
{/* flash（載入模型）：裝置在線才可 flash；離線時 disable 觸發鈕。
+ WP-C（ADR-018）：flash 走 serial 路由，serial 為空時同樣 disable + tooltip。
flash 完成後 dialog 內部呼叫 fetchDevice → flashedModel 有值 → 下方
「開啟工作區」按鈕自動出現（gate 解鎖，無需改 gate 邏輯）。 */}
-
+ {hasSerial ? (
+
+ ) : (
+
+
+
+
+
+
+ {t("devices.serial.missingHint")}
+
+ )}
- {isOnline && selectedDevice.flashedModel && (
+ {isOnline && selectedDevice.flashedModel && hasSerial && (
)}
+ {isOnline && selectedDevice.flashedModel && !hasSerial && (
+
+
+
+
+
+
+ {t("devices.serial.missingHint")}
+
+ )}
{!isOnline && (
@@ -253,6 +282,21 @@ export function DeviceDetailClient({ id }: DeviceDetailClientProps) {
{selectedDevice.id}} />
+ {/* WP-C（ADR-018）：顯示硬體序號（kn_number）；未回報時提示需重新配對 */}
+
+ {selectedDevice.serialNumber}
+
+ ) : (
+
+ {t("devices.serial.missing")}
+
+ )
+ }
+ />
["selectedDevice"],
+ isLoading: false,
+ });
+}
+
+/** WP-C：seed 一台線上但「未回報序號」的裝置（舊資料 / 假序號 → null）。 */
+function seedOnlineDeviceWithoutSerial() {
+ useDeviceStore.setState({
+ selectedDevice: {
+ id: "dev-1",
+ name: "KL520",
+ remoteStatus: "online",
+ lastSeenAt: null,
+ serialNumber: null,
} as ReturnType["selectedDevice"],
isLoading: false,
});
@@ -181,8 +197,11 @@ describe("WorkspaceClient — 切 tab 時 camera 串流 / WS 正確關閉（S-1
await switchTab("圖片");
// handleTabChange 應自動停掉 camera（POST /api/camera/stop）
+ // WP-C（ADR-018）：body 的 deviceId 欄位帶 serialNumber（非雲端 UUID）
await waitFor(() => {
- expect(post).toHaveBeenCalledWith("/api/camera/stop", { deviceId: "dev-1" });
+ expect(post).toHaveBeenCalledWith("/api/camera/stop", {
+ deviceId: "KN00123456",
+ });
});
// camera 串流已清（isRunning=false）→ camera 的 useInferenceStream enabled 變 false（不殘留連線）
await waitFor(() => {
@@ -214,3 +233,50 @@ describe("WorkspaceClient — 切 tab 時 camera 串流 / WS 正確關閉（S-1
expect(lastCameraWsEnabled()).toBe(false);
});
});
+
+describe("WorkspaceClient — serial 路由（WP-C / ADR-018）", () => {
+ it("camera start 的 body deviceId 帶 serialNumber、camera WS 識別值也是 serialNumber", async () => {
+ post.mockResolvedValue({ streamUrl: "/api/camera/stream", sourceType: "camera" });
+ renderClient();
+
+ fireEvent.click(screen.getByText("開始推論"));
+ await waitFor(() => {
+ expect(post).toHaveBeenCalledWith("/api/camera/start", {
+ deviceId: "KN00123456",
+ });
+ });
+
+ // camera WS 的第一個參數（識別值）= serial，且 enabled=true
+ const wsCall = vi.mocked(useInferenceStream).mock.calls.at(-1);
+ expect(wsCall?.[0]).toBe("KN00123456");
+ expect(wsCall?.[1]).toBe(true);
+ });
+
+ it("serial 為空：開始推論 disabled + 顯示 no-serial banner、不打 camera start", () => {
+ seedOnlineDeviceWithoutSerial();
+ renderClient();
+
+ const startBtn = screen.getByText("開始推論").closest("button");
+ expect(startBtn).toBeDisabled();
+ expect(screen.getByTestId("workspace-no-serial-banner")).toBeInTheDocument();
+
+ fireEvent.click(screen.getByText("開始推論"));
+ expect(post).not.toHaveBeenCalled();
+ });
+
+ it("serial 為空：media tab 顯示 no-serial 提示、不出現上傳區", async () => {
+ seedOnlineDeviceWithoutSerial();
+ renderClient();
+
+ await switchTab("圖片");
+ expect(screen.getByTestId("media-no-serial")).toBeInTheDocument();
+ expect(screen.queryByTestId("media-uploader-image")).not.toBeInTheDocument();
+ });
+
+ it("serial 有值：media tab 正常顯示上傳區", async () => {
+ renderClient();
+ await switchTab("圖片");
+ expect(screen.getByTestId("media-uploader-image")).toBeInTheDocument();
+ expect(screen.queryByTestId("media-no-serial")).not.toBeInTheDocument();
+ });
+});
diff --git a/visionA-frontend/src/app/workspace/[deviceId]/workspace-client.tsx b/visionA-frontend/src/app/workspace/[deviceId]/workspace-client.tsx
index c71a53f..d7d1114 100644
--- a/visionA-frontend/src/app/workspace/[deviceId]/workspace-client.tsx
+++ b/visionA-frontend/src/app/workspace/[deviceId]/workspace-client.tsx
@@ -20,6 +20,14 @@
*
* 重要：雲端版 Workspace 對「裝置離線」極敏感 —
* 任何時刻若收到 remoteStatus != online 都要立刻顯示 offline 遮罩並停止串流。
+ *
+ * ADR-018 serial 路由（WP-C）：
+ * - 路由到 local agent 的操作（camera start/stop、media upload、inference WS）
+ * 識別值一律帶 `device.serialNumber`（kn_number），不是雲端 UUID。
+ * - 路由段 `[deviceId]` 仍是雲端 UUID（fetchDevice 是純 DB 操作、FE-A 混合模型），
+ * serial 從 fetch 回來的 selectedDevice 取。
+ * - serial 為空（舊資料未回報 / 假序號）→ 無法路由：顯示提示 banner、
+ * 「開始推論」disable、media tab 顯示提示不給上傳。
*/
import { useCallback, useEffect, useRef, useState } from "react";
@@ -101,6 +109,11 @@ export function WorkspaceClient({ deviceId }: WorkspaceClientProps) {
// 塊 2：裝置線上性（hooks 必須無條件呼叫，故在此處先算，早退前）
const isOnline = selectedDevice?.remoteStatus === "online";
+ // WP-C（ADR-018）：路由到 local agent 的操作一律用 serial 當識別值。
+ // serial 為空（舊資料 / 未回報序號）→ 操作全部 disable（無法路由）。
+ const serialNumber = selectedDevice?.serialNumber ?? null;
+ const hasSerial = !!serialNumber;
+
// 塊 3：切換 tab。離開 camera tab 時若正在推論 → 停掉（避免 camera 與 media 兩套 WS 同時灌 store）。
const handleTabChange = useCallback(
(value: string) => {
@@ -112,25 +125,32 @@ export function WorkspaceClient({ deviceId }: WorkspaceClientProps) {
[isRunning],
);
- // 塊 2/3：訂閱 camera WS `inference:`（只在 camera tab + 推論中 + 線上時連線）。
+ // 塊 2/3：訂閱 camera WS `inference:`（只在 camera tab + 推論中 + 線上 + 有 serial 時連線）。
// media tab 有自己的 useInferenceStream（在 MediaTab 內），兩者靠 activeTab 互斥。
- useInferenceStream(deviceId, activeTab === "camera" && isRunning && isOnline);
+ // WP-C：WS 識別值用 serial（與 camera start 的 body deviceId 一致，room key 才對得上）。
+ useInferenceStream(
+ serialNumber ?? "",
+ activeTab === "camera" && isRunning && isOnline && hasSerial,
+ );
// 塊 2：最新結果的偵測框（供 overlay 繪製）
const liveResult = useInferenceStore((s) => s.result);
const confidenceThreshold = useInferenceStore((s) => s.confidenceThreshold);
async function handleStart() {
+ // WP-C：serial 為空無法路由（按鈕已 disable；此為防禦性 guard）。
+ if (!serialNumber) return;
setBusy(true);
try {
// 契約修正（評估 §3.1 R-C1）：camera pipeline 入口為 POST /api/camera/start
// body 帶 deviceId；後端回傳 { streamUrl, sourceType }（camera_handler.go:119-125）
+ // WP-C（ADR-018）：deviceId 欄位帶 serial（欄位名不動、值換 serialNumber）。
const data = await api.post("/api/camera/start", {
- deviceId,
+ deviceId: serialNumber,
});
const url = data?.streamUrl ?? "/api/camera/stream";
// cache-bust：每次 start 換一個值，避免瀏覽器重用已結束的 MJPEG 連線
- setStreamUrl(buildStreamUrl(url, `${deviceId}-${Date.now()}`));
+ setStreamUrl(buildStreamUrl(url, `${serialNumber}-${Date.now()}`));
setIsRunning(true);
} catch (err) {
// 後端尚未接上 proxy 時可能 501；不當致命錯誤，僅提示
@@ -147,7 +167,11 @@ export function WorkspaceClient({ deviceId }: WorkspaceClientProps) {
async function handleStop() {
setBusy(true);
try {
- await api.post("/api/camera/stop", { deviceId });
+ // WP-C（ADR-018）：與 start 一致，deviceId 欄位帶 serial。
+ // serial 為空時不可能已 start（handleStart 有 guard），直接清本地串流即可。
+ if (serialNumber) {
+ await api.post("/api/camera/stop", { deviceId: serialNumber });
+ }
} catch (err) {
if (!(err instanceof ApiError && err.code === "NOT_IMPLEMENTED")) {
toast.error(err instanceof Error ? err.message : String(err));
@@ -179,6 +203,20 @@ export function WorkspaceClient({ deviceId }: WorkspaceClientProps) {
// 用 render 期衍生而非 effect + setState，避免 cascading render。
const effectiveStreamUrl = isOnline ? streamUrl : "";
+ // WP-C：media tab 在 serial 為空時的占位提示（無法上傳——上傳的識別值就是 serial）。
+ const noSerialNotice = (
+
+
+
+
{t("workspace.noSerial.title")}
+
+ {t("workspace.noSerial.description")}
+
+
@@ -206,13 +244,30 @@ export function WorkspaceClient({ deviceId }: WorkspaceClientProps) {
{t("workspace.inference.stop")}
) : (
-
+ {/* WP-C（ADR-018）：serial 為空 → 無法路由到 local agent，說明原因與解法 */}
+ {device && !hasSerial && (
+
+
+
{t("workspace.noSerial.title")}
+
+ {t("workspace.noSerial.description")}
+
+
+