From 72544d00ba62644d324e9211852420e620cca33d Mon Sep 17 00:00:00 2001 From: jim800121chen Date: Sat, 11 Jul 2026 08:39:32 +0800 Subject: [PATCH] =?UTF-8?q?docs(adr):=20ADR-018=20=C2=A78=20addendum=20?= =?UTF-8?q?=E2=80=94=20C5=20=E5=AF=A6=E4=BD=9C=E5=81=8F=E5=B7=AE=E5=9B=9E?= =?UTF-8?q?=E5=A1=AB=EF=BC=88=E8=B7=AF=E7=94=B1=E6=AE=B5=E7=B6=AD=E6=8C=81?= =?UTF-8?q?=20UUID=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - §5.5 加補註指向、原文一字未動（ADR 不可變原則） - §8.1 記錄 C5 偏差證據鏈（fetchDevice 純 DB / API 無 GetBySerial / 帶 serial deep-link 必 404）與最終實作（路由段 UUID、serial 頁內派生、 入口 disable 全落實）；決策本體 FE-A 與 C1–C4/C6–C8 不變 - 裁定來源：wp-c-frontend-serial-routing-review.md（reviewer 獨立驗證） Co-Authored-By: Claude Fable 5 --- .../adr/adr-018-agent-device-model.md | 30 +++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/docs/autoflow/04-architecture/adr/adr-018-agent-device-model.md b/docs/autoflow/04-architecture/adr/adr-018-agent-device-model.md index 3eda890..2f496f0 100644 --- a/docs/autoflow/04-architecture/adr/adr-018-agent-device-model.md +++ b/docs/autoflow/04-architecture/adr/adr-018-agent-device-model.md @@ -150,6 +150,8 @@ session_tokens（物理 schema 不動） ### 5.5 前端 WP-C 逐檔（FE-A 混合） C1 `device-store.ts` 加 `serialNumber` type + normalize；C2 `workspace-client.tsx` camera/media/inference 識別改 serial + disable；C3 `use-inference-stream.ts` 註解；C4 `lib/media.ts` 註解；C5 `workspace/[deviceId]` 連結改帶 serial；C6 `device-card.tsx` 工作區按鈕加 `hasSerial`；C7 `device-detail-client.tsx` 工作區用 serial（詳情頁本身 fetchDevice 維持 UUID）；C8 flash（F8 接時用 serial）。**不改（保持 UUID）**：fetchDevices/fetchDevice/unpair/connect/disconnect、詳情頁路由 `/devices/[id]`。 +> ⚠️ 補註（2026-07-11）：上列 C5「連結改帶 serial」一句於 WP-C 實作時證實與 §2.2 FE-A 自相矛盾，實作偏差已裁定接受——路由段維持 UUID、serial 頁內派生。詳見 §8 補註（本段原文依 ADR 不可變原則保留、不改寫）。 + --- ## 6. 合規性 @@ -165,3 +167,31 @@ C1 `device-store.ts` 加 `serialNumber` type + normalize；C2 `workspace-client. ## 7. 一句話總結 讀 code 後推翻「`session_tokens.device_id` 單一 FK 是硬傷」的假設——推論路由根本不靠它，真正缺口是「雲端 device.id ↔ local agent 本地 id」從不對齊。故採 **走向 A'**：新增 `agents` 表、`devices` 改為實體 USB 掛 `agent_id`、`session_tokens.device_id` 保留物理 schema 但改綁「agent 代表 device」（避開破壞性 FK migration）、路由統一用 serial（kn_number）並在 local agent 端加 serial→本地 key 雙查（純加法、保護推論）。前端採 **FE-A 混合模型**：DB 操作用 UUID、路由到 local agent 的操作用 serial（serial 值替換 UUID、傳輸位置不動），serial 空的 device 路由類操作 disable。 + +--- + +## 8. 補註（Addendum） + +> ADR 為不可變決策紀錄：以下補註只增不刪，§1–§7 原文一字未動。 + +### 8.1 C5 實作偏差回填（2026-07-10 實作定案、2026-07-11 回填） + +**偏差內容**：§5.5 原句「C5 `workspace/[deviceId]` 連結改帶 serial」於 WP-C 前端實作時證實與本 ADR §2.2 FE-A 混合模型**自相矛盾**： + +1. workspace 進頁第一件事是 `fetchDevice(路由段值)`，屬「純雲端 DB 操作」——依 FE-A 分流表本應歸 **UUID** 組。 +2. api-server 只有 `GET /devices/:id` 一個讀取端點、handler 直接按 DB 主鍵（UUID）查（`visionA-backend/internal/api/devices.go:26-42`），**不存在任何 GetBySerial 端點**。 +3. 路由段若帶 serial：直接輸入 URL / 重新整理 / 書籤進入 workspace → `fetchDevice(serial)` → 404 → 整頁卡占位態。要救就得 api-server 加 serial 查 DB——正是本 ADR §3 否決 FE-B 時列出的理由。 + +R-Route 查證報告 §3.2 第 4 點當時已標注此張力，但 §4 C5 與本 ADR §5.5 C5 的行文未回頭同步，屬**文件內部殘留矛盾、非實作漏做**。 + +**最終實作（經 reviewer 獨立驗證、裁定偏差成立並接受）**： + +- workspace 路由段 `[deviceId]` **維持 UUID**（`device-card.tsx` / `device-detail-client.tsx` / `workspace/page.tsx` 連結仍帶 `device.id`）。 +- serial 由頁內 `selectedDevice.serialNumber` 派生，供 camera / media / inference WS 等路由類操作使用。FE-A 精神（「路由到 local agent 的操作識別值 = serial」）100% 達成——路由段只是「取 device 資料的 key」、本身不路由到 local agent。 +- C5 的「serial 空時工作區入口 disable + tooltip」行為全數落實，另加頁內 no-serial banner。 + +**決策本體不變**：§2.2 FE-A 混合模型、§5.5 其餘各條（C1–C4 / C6–C8）均維持原決策；本補註僅將 C5 中「連結 href 改帶 serial」一句更正為「路由段維持 UUID、serial 頁內派生」。 + +**參照**： +- 裁定證據鏈：`.autoflow/05-implementation/review/wp-c-frontend-serial-routing-review.md` §二（C5 偏差獨立驗證）與 Minor #2（本回填的來源指令）。 +- 同步修正文件：`.autoflow/04-architecture/personal-device-mgmt-R-Route-frontend-verification.md` §4 C5（該檔非 ADR、直接於原條目修正 + 表下加修正註記）。