# visionA-local 設計規格（索引）

> Design Agent · 第二輪正式規格 · 2026-04-11（第三輪修訂 2026-04-11）
> 本文件為索引檔，各章節詳細內容請見 `spec/` 子檔。所有決策依據 progress.md（2026-04-11）定案。

## 文件結構

| # | 章節 | 檔案 | 一句話摘要 |
|---|------|------|-----------|
| 1 | 資訊架構（IA） | `spec/01-information-architecture.md` | 4 主區塊 + Settings，sidebar 導航，無 deep link |
| 2 | 頁面清單與變更對照 | `spec/02-pages-diff.md` | 對照原 edge-ai-platform 的保留／刪除／修改 |
| 3 | 主要頁面 Wireframe | `spec/03-wireframes.md` | Dashboard / Models / Devices / Workspace / Settings 結構描述 |
| 4 | First-Run Experience | `spec/04-first-run.md` | 歡迎 → 模式選擇 → 硬體偵測，可跳過 |
| 5 | ~~Tray 互動規格~~ | — | **已於第三輪決策 Q-A 砍除**（不做 tray）。編號保留以避免後續引用失效 |
| 6 | 跨平台 UX 差異 | `spec/06-cross-platform.md` | title bar、快捷鍵、對話框、通知 |
| 7 | Design Tokens | `spec/07-design-tokens.md` | 沿用 edge-ai-platform oklch tokens，補 L 級 elevation |
| 8 | 錯誤與空狀態 | `spec/08-states.md` | 全域錯誤分級 + 空狀態文案庫 |
| 9 | 無障礙（A11y） | `spec/09-accessibility.md` | **盡力而為**（R4-3 降級，非硬性目標）— 保留鍵盤、焦點、語意化 HTML 等低成本項目 |
| 10 | i18n 策略 | `spec/10-i18n.md` | 中英雙語，跟隨系統，沿用 react-i18next |

## 關鍵設計決策（摘要）

1. **視窗模型**：傳統桌面 app — **關閉視窗 = 結束程式**。**不做 tray icon**（第三輪決策 Q-A），省跨平台圖資產與 Wails tray 踩坑，也避免與「關閉 = 結束」的語意衝突。
2. **資訊架構扁平化**：從原 5 區（含 clusters）瘦身為 4 主區 + Settings。所有 cluster／relay 相關入口完全移除，**M1 就一次清乾淨**（第三輪決策 Q-C）。
3. **Dashboard 重定位**：原本是叢集總覽，現在改成「快速開始 + 單機狀態卡」，把首頁價值從「監看」轉為「起手」。
4. **預設真實硬體模式**：首次啟動不預設 Mock，但在模式選擇步驟提供 Mock 作為明確替代，且可隨時切換。
5. **First-Run 可全跳過**：三步流程（歡迎 / 模式 / 偵測），每一步右上都有「略過」，降低挫敗。
6. **深色模式跟隨系統**：不提供手動切換（Settings 僅顯示「目前跟隨系統」唯讀狀態，避免決策疲勞）。
7. **中英雙語**：預設跟隨系統 Locale（`zh-*` → 繁中；其他 → 英文），Settings 可手動切換。
8. **Logo 沿用 edge-ai-platform**：暫不重新設計品牌識別，僅把產品字樣改為「visionA-local」。
9. **Design Tokens 完全沿用**：原專案使用 shadcn + oklch 中性色盤，local 版無變更，只補 desktop 專用的 elevation 與 window chrome token。
10. **Settings 重構為分頁式**：**一般 / 硬體 / 模型 / 進階**（4 分頁，第三輪決策 Q-E3 取消「外觀」分頁，語言併入「一般」）。
11. **macOS 資料目錄**：`~/Library/Application Support/visiona-local/`（第三輪決策 Q-E1，遵循 OS 慣例；第四輪 R4-5 全小寫對齊 Bundle ID 與 Linux 慣例）。

## 第四輪決策採納對照（2026-04-11 交叉審閱後）

| # | 決策 | 落地位置 |
|---|------|---------|
| R4-2 | MJPEG 延遲目標：首次 ≤250ms / 穩定後 ≤150ms | `spec/03-wireframes.md` Workspace Perf 示例值改為 180ms |
| R4-3 | WCAG 2.2 AA 降級為「盡力而為」（非硬性目標） | `spec/09-accessibility.md` 全節改寫、design-spec 索引同步 |
| R4-5 | 資料目錄全小寫 `visiona-local`（對齊 Bundle ID 與 Linux 慣例） | `spec/06-cross-platform.md §6.7`、`spec/04-first-run.md §4.1/§4.6/§4.7`、`spec/03-wireframes.md §3.5`、`spec/10-i18n.md §10.2` |
| R4-6 | ⌘R → ⌘Shift+R；⌘Shift+W 取消 | `spec/06-cross-platform.md §6.2` |
| R4-8 | 通知策略：裝置連/斷 → App toast；Server 崩潰 → OS 原生通知 | `spec/06-cross-platform.md §6.4` |
| — | Single-instance 第二次啟動 → 靜默 raise（不彈 toast） | `spec/06-cross-platform.md §6.9`（新增） |
| — | Python sidecar crash loading + 自動重啟 | `spec/08-states.md §8.8`（新增） |
| — | Python 雙策略切換 UI 入口 | `spec/03-wireframes.md §3.5` Settings > 進階 |
| — | 深色模式：CSS `prefers-color-scheme`（不需 JS emit event） | `spec/06-cross-platform.md §6.8`、`spec/07-design-tokens.md §7.5` 註記 |
| — | i18n 即時切換 → M2 才做 | `spec/10-i18n.md §10.7` 明確標註 |

## 已知 contingency

- **R9 Kneron 預置模型 re-distribution**：第四輪 R4-1 決定繼續內嵌、不主動問 Kneron，發佈前 gate 維持。**若 R9 觸發**，First-Run 需插入「下載預置模型」步驟，完整 fallback 流程的 Wireframe 與互動規格草案保留在 `design-cross-review.md §「R9 Plan B 的 First-Run 下載流程草案」`，目前**不納入正式 design-spec**（避免誤導開發團隊）。若真的觸發，會把該草案升格為 `spec/04-first-run-plan-b.md`。

## 第三輪決策採納對照

| # | 原疑問 | 第三輪結果 |
|---|--------|----------|
| 1 | Tray 是否要做？ | **Q-A 砍掉 tray**。05-tray.md 已刪除；`⌘0 顯示主視窗` 等 tray 相關快捷鍵同步移除 |
| 3 | Workspace 升為 sidebar 一級 | **Q-E2 採納**。IA 已確定 4 主區塊含 Workspace |
| 4 | Settings「外觀」分頁取消 | **Q-E3 採納**。Settings 為 4 分頁（一般 / 硬體 / 模型 / 進階），語言在「一般」 |
| — | macOS 資料目錄 | **Q-E1**：`~/Library/Application Support/visiona-local/`（取代 `~/.visiona-local/`，R4-5 全小寫） |
| — | M1 範圍 | **Q-C**：M1 就要清乾淨前端 cluster/relay UI，不分期 |

## 第三輪修訂後仍待確認 / 仍需使用者回饋

1. **Mock 模式的視覺標記**（沿用第二輪建議）
   預設真實硬體模式後，Mock 變成明確的「次要體驗」。建議在 header 右側加一個永久性 `Mock` badge（黃色），避免使用者誤把假結果當成真推論。此項已寫入 wireframe，**未見使用者反對，視為採納**。

2. **簽章警示的 UX**（Q2 決策：不買憑證）
   macOS 會跳 Gatekeeper 警告、Windows 會跳 SmartScreen。這些是 **OS 層的對話框，App 內無法攔截**；但首次啟動完成後的「歡迎畫面」應該主動說明「你可能剛才看到警告，那是因為我們是內部工具，已經安全」，降低焦慮。文案已寫入 `04-first-run.md`。

3. **快捷鍵衝突（tray 砍除 + 第四輪 R4-6 重整後）**
   最小快捷鍵集：⌘, (Settings)、⌘W（關閉＝結束）、⌘Q（結束）、⌘1~4（切換主區塊，⌘4 即前往 Workspace）、⌘Shift+R（重新整理裝置）、⌘U（上傳模型）。
   **R4-6 變更**：
   - `⌘R` → **`⌘Shift+R`**（避免與 WebView 的 reload 衝突）
   - **取消 `⌘Shift+W`**（與 macOS 內建「關閉所有視窗」衝突；⌘4 已涵蓋前往 Workspace）
   - 原 `⌘0 顯示主視窗（從 tray）` 已於第三輪隨 tray 移除。

4. **[第三輪新增] Mock 模式切換入口的去留**
   砍掉 tray 後，原本 tray 選單提供的「一鍵切換 Mock ↔ Real」捷徑消失。目前 Mock 切換入口剩下：
   - Settings > 硬體（主要入口）
   - Devices 頁面右上角的「真實 / Mock」pill 切換
   - First-Run Step 2（僅首次）

   Design 認為這樣夠用（切換頻率不高），但若未來使用者抱怨「找不到切換入口」，可考慮在 Dashboard 的 Quick Start 區加一個二級行動。**目前不改**。

---

**下一步：**
- PM / Architect 交叉 review 本規格第三輪修訂版
- 三方確認後進入 Prototype 階段（HTML/CSS 原型，後續迭代處理）