jim800121/visionA
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
visionA/local-tool/.autoflow/03-design/design-spec-v2.md
jim800121chen 46514d77d7 docs(local-tool): M9 — Kneron Dongle FW 偵測 + 升降版（A+B、翻案 R5-Q9） 
L 級新功能、PRD/Design/TDD/ADR 三方協作 + 互審 + M9-6 SDK 雙驗證、總計 ~9000 行文件。

範圍：
- A 階段（MVP、5 人天）：KL520 + KL720 自動升級 KDP1 → KDP2
- B 階段（10.5 人天）：手動降版面向一般使用者 + KL630 / KL730 擴展
- 合計 15.5 人天、安裝包 +7MB（保守 bundle 策略）

關鍵決策：
- 翻案 R5-Q9（progress.md 第二輪使用者決策「韌體燒錄 flash → B 砍掉」）
- 跨平台用 KneronPLUS Python C API、不用 DFUT.exe
- 多版本目錄結構選 C metadata（firmware/<chip>/{version}/ + CURRENT_VERSION）
- Kneron firmware redistribution 授權與 R5-B4 預置模型同性質、發佈前評估

文件產出：
- PRD v2.2（PRD-v2.md 495 行 + features/feature-firmware-management.md 599 行）
- Design v2.2（firmware-management.md 948 行 + control-panel.md §6a graceful shutdown）
- TDD v2.2（v2/firmware-management.md 823 行 + ADR-001 218 行）
- 8 份 research（含 M9-6 弱驗證 + 強驗證、~3200 行）
- 3 份三方互審報告（PM/Design/Architect cross-review）

M9-6 強驗證重大發現（影響 B 階段）：
- KL730 product_id 實際是 0x732（不是 0x0730）
- KL630/KL730 firmware 是 embedded Linux rootfs（不是 .bin、不同代設計）
- KneronPLUS Python 沒 update_kdp_firmware_from_files 公開 API、warrenchen 走 ctypes
- 不影響 A 階段、B 階段 M9-8 需 spike

下一步：派 backend M9-1 起跑（bridge.py handle_firmware_upgrade）

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-25 07:40:56 +08:00

152 lines
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# visionA-local 設計規格 v2（索引）
> Design Agent · 第五輪正式規格 · 初版 2026-04-14
> **目前版本：v2.2（2026-05-24 補丁）** — 吸收 R5-Q9 翻案、新增 Kneron Dongle FW 管理規格（升級 + 版本切換、面向一般使用者）
> 前一版本：v2.1（2026-04-14 補丁）— 吸收 Architect 交叉審閱 Major 1+2 / Minor 1-5 修正 + R5-D1/D2/D3 / R5-E 追加決策
> 本版依 **R5 決策**重構：visionA-local 從「Wails 跑 Next.js 的單一桌面 app」轉為「**Wails Server Control Panel + 瀏覽器 Web UI**」雙 UI 架構。
> 本文件為 v2 索引檔，各章節詳細內容見 `v2/` 子檔。v1（`design-spec.md` + `spec/`）仍保留作為基準參考，未來的實作以 v2 為準。
---
## v2 範圍
本次 v2 只重新設計**因 R5 決策而改變的部分**，其餘 v1 章節（IA、Settings 分頁結構、design tokens、i18n 策略、A11y 等）**仍然有效**。
### R5 決策總表（本 v2 的立論基礎）
| # | 題目 | 使用者決定 | 對設計的影響 |
|---|------|----------|------------|
| R5-1 | 重構動機 | A+B+G（多視窗便利 + devtools + 需求方要求） | 確立雙 UI 架構 |
| R5-2 | 關閉 Wails 視窗行為 | **關閉 = 結束 server**，瀏覽器顯示「Local Server 已離線」覆蓋層 | 新增 Server Offline Overlay 設計 |
| R5-3 | Tray 復議 | **維持砍 tray**（T1） | 控制台無 tray 退縮選項 |
| R5-4 | 首次啟動自動開瀏覽器 | **A：首次自動開，Settings 可關** | 新增 Settings toggle + First-Run 流程變動 |
| R5-5 | Wails 控制台 scope | PM 清單 **拿掉 Mock 模式切換** | 控制台不顯示 Mock UI |
| R5-5a | Mock 模式歸處 | **完全砍掉 Mock 模式** | Settings 刪除硬體分頁的 Mock 相關項 / First-Run 砍模式選擇步驟 |
| R5-6 | ffmpeg 授權 | LGPL 混合（Win/Linux BtbN、macOS 自 build） | 不影響 UI 設計本身 |
| R5-7 | M7 Windows | 先不管 | 不影響 v2 |
---
## 文件結構
| # | 章節 | 檔案 | 一句話摘要 |
|---|------|------|-----------|
| v2.1 | Wails Server Control Panel | `v2/control-panel.md` | 桌面控制台完整規格（wireframe、狀態機、元件、i18n、A11y） |
| v2.2 | Server Offline Overlay | `v2/server-offline-overlay.md` | 瀏覽器端偵測到 server 斷線時的全螢幕覆蓋層 |
| v2.3 | source-selector 修改 | `v2/source-selector-update.md` | 砍 URL mode、重寫 video tab、要刪的 i18n key 清單 |
| v2.4 | First-Run 流程重定義 | `v2/first-run-update.md` | 砍 Mock 模式選擇步驟、自動開瀏覽器的起手流程圖 |
| v2.5 | Settings 頁更新 | `v2/settings-update.md` | 新增「啟動時自動開啟瀏覽器」toggle、Linux 預設 OFF、落地 `preferences.json`、砍 Mock 相關設定 |
| **v2.6** | **啟動進度面板**（v2.1 新增） | **`v2/startup-progress.md`** | **R5-E 階段化啟動進度面板：6 階段 wireframe、中英雙語文案、20 秒卡頓提示、60 秒 timeout Error 流程** |
| **v2.7** | **韌體管理**（v2.2 新增） | **`v2/firmware-management.md`** | **Kneron dongle FW 升級 + 版本切換完整規格：Settings 新分頁、Devices 頁 FW badge（紅/黃/綠 + deep-link）、二次確認流程（輸入 DOWNGRADE）、52 個 i18n keys、6 個新 component token、R-FW-11 設計緩解** |
---
## v2 未動到的章節（仍以 v1 為準）
- `spec/01-information-architecture.md` — IA 不變（4 主區塊 + Settings）
- `spec/02-pages-diff.md` — 頁面清單變動極小（僅 workspace 推論源砍 URL）
- `spec/03-wireframes.md` — Dashboard / Devices / Models / Workspace 主體不變
- `spec/06-cross-platform.md` — 跨平台 UX 差異不變
- `spec/07-design-tokens.md` — tokens 完全沿用
- `spec/08-states.md` — 全域錯誤分級、空狀態文案不變
- `spec/09-accessibility.md` — 盡力而為原則不變
- `spec/10-i18n.md` — i18n 策略不變
---
## Design Token 一致性（總則）
**Wails Server Control Panel 與瀏覽器 Web UI 共用同一套 shadcn oklch design tokens**（見 `spec/07-design-tokens.md`）。
具體做法：控制台前端是 vanilla HTML/JS/CSS（R5 三方共識），但仍引入與 Next.js Web UI 一致的 CSS variable 定義檔（從 `frontend/src/app/globals.css` 擷取 `:root` 與 `[data-theme='dark']` 的 token block），達到：
- 控制台與 Web UI 在 Light / Dark 下視覺語言一致
- 錯誤訊息紅、警告琥珀、成功綠完全相同（不會出現控制台紅和 Web 紅不同的 UX 破綻）
- 未來若 tokens 更新，只要同步 CSS variable 檔即可
**不另外定義控制台專屬 tokens**，唯一例外是控制台的 log panel 使用等寬字體 token（`font.mono`，v1 已存在），以及標題列 `window-chrome.height`（v1 `spec/07-design-tokens.md §7.5` 已定義）。
---
## v1 → v2 差異總覽
| 面向 | v1（第四輪） | v2（第五輪） | 來源決策 |
|------|-------------|-------------|---------|
| 主視窗呈現 | Wails 單視窗 = Next.js 主 UI | Wails 單視窗 = Server Control Panel；Web UI 跑在瀏覽器 | R5-1 |
| 視窗關閉 | 結束程式（第四輪 Q7） | 結束程式 **+** 瀏覽器顯示離線 Overlay | R5-2 |
| Tray | 無 | 無（維持） | R5-3 |
| 首次啟動 | Wails 開 → First-Run wizard 三步（歡迎 / 模式選擇 / 偵測） | Wails 控制台開 → 自動 start server → 自動 open 瀏覽器 → First-Run wizard **兩步**（歡迎 / 偵測） | R5-4、R5-5a |
| 首次啟動 Settings | — | 新增「首次啟動時自動開啟瀏覽器」toggle（預設 ON） | R5-4 |
| Mock 模式 | 預設真實硬體，可於 Settings > 硬體切換為 Mock | **完全砍除**，沒插硬體就空白 | R5-5a |
| Settings 分頁 | 一般 / 硬體 / 模型 / 進階 | 一般 / 硬體 / 模型 / 進階（結構不變，內容刪減） | v1 保留 |
| Workspace 推論源 | camera / image / video（file + url） | camera / image / video（僅 file） | R5 三方共識 |
| 支援影片副檔名 | `.mp4, .avi, .mov` | **`.mp4, .avi, .mov, .mpeg, .mpg`** | R5 三方共識 |
| 影片載入文案 | 「正在解析影片連結，YouTube 影片可能需要 10-30 秒…」 | 純檔案上傳，無解析文案 | R5 三方共識 |
| Wails 控制台 scope | 不存在 | Header 狀態列 + Primary controls + Log panel + Log actions + Footer | R5-5 |
| Server 狀態機 | 黑盒 | **五態視覺化**：Running / Starting / Stopping / Stopped / Error | v2 新增 |
| Server 崩潰通知 | Wails shell out native notification | 控制台內的 Error state 面板 + 紅字 log + OS notification | v2 細化 |
| 瀏覽器端 server 斷線 | 未定義 | 全螢幕 Server Offline Overlay（不可關閉、提供重試） | R5-2 |
---
## v2.1 → v2.2 差異總覽（2026-05-24 補丁輪）
v2.2 是吸收 R5-Q9 翻案（FW 管理面向一般使用者）後的補丁，新增 Kneron dongle FW 升級 + 版本切換的完整設計規格。**不改變 R5 雙 UI 架構立論**、只新增功能模組。
| 面向 | v2.1 | v2.2（2026-05-24 補丁）| 來源 |
|------|------|---------------------|------|
| Settings 分頁數 | 4（一般 / 硬體 / 模型 / 進階） | **5**（一般 / 硬體 / **韌體** / 模型 / 進階） | R5-Q9 + architect 42 |
| Devices 頁 FW 顯示 | 純文字 `FW 2.1.0` | **pill badge**（紅 / 黃 / 綠三色）+ deep-link ⚙ icon | R5-Q9 第 5 點 |
| FW 升級 UX | 未設計 | **單步驟確認 + 進度 modal**（不可中斷） | architect 30 §M9-4 |
| FW 降版 UX | 未設計 | **二次確認**（輸入「DOWNGRADE」字串）+ 進度 modal + 全螢幕 hover 攔截 | architect 42 §5.3 |
| 失敗復原 UX | 未設計 | **8 種失敗類型對應 friendly message + 復原行動** | architect 42 §5.5 |
| 新增 i18n keys | — | **52 keys**（zh-TW + en） | 本檔 `v2/firmware-management.md §9` |
| 新增 component tokens | — | **6 個 fw-badge token**（current / older / legacy × bg/fg） | 本檔 `v2/firmware-management.md §11.2` |
| UI 用語策略 | — | UI 一律稱「韌體管理」/「版本切換」（中性詞）、code/log/技術文件仍稱 downgrade | architect 42 §1.1 |
---
## v2 → v2.1 差異總覽（2026-04-14 補丁輪）
v2.1 是 v2 三方互審後的修正補丁，不改變 R5 雙 UI 架構立論，只處理 Architect 互審發現 + R5-D / R5-E 追加決策。
| 面向 | v2（2026-04-14 初版） | v2.1（2026-04-14 補丁） | 來源 |
|------|--------------------|----------------------|------|
| Settings 落地檔 | `settings.json` + 「走 Wails settings store」 | **`preferences.json` @ `<dataDir>/`** + Go server write-rename atomic | Architect Review Major 1 |
| 「啟動時自動開瀏覽器」預設值 | 三平台一致 ON | **macOS/Windows = ON，Linux = OFF**（依 `runtime.GOOS`） | R5-D2 |
| Toggle label 字面 | 「首次啟動時自動開啟瀏覽器」（待確認） | **「啟動時自動開啟瀏覽器」**（R5-D3 定案：每次啟動都開） | R5-D3 |
| Log panel 上限 | 1000 行 + rotate 7 天 / 10 MB | **2000 行 + 無落地 rotate**（in-memory ring buffer，使用者透過 Export log 手動匯出） | Architect Review Minor m-1、m-12 |
| Error banner 「Report...」按鈕 | 正常按鈕 | **【hold】** 待 PM 提供 GitHub Issue repo URL | Architect Review Minor m-11 |
| Error state OS 通知 | v2 模糊（控制台可見，通知視為次要重複） | **R5-D1 保留**：Error state 發 non-blocking toast notification，與控制台 Error banner 並存 | R5-D1 |
| Starting state 視覺 | 只有 header spinner，5 秒 timeout | **階段化啟動進度面板**（`v2/startup-progress.md`），6 階段 + 20 秒卡頓提示 + **60 秒總上限** | R5-E |
| 首次啟動流程 | 「首次」自動開瀏覽器 | **「每次」** 啟動都自動開瀏覽器（Wails 每次新啟動） | R5-D3 |
---
## 給 Orchestrator 的問題（懸而未決）
**v2 懸而未決已解決**：
- ~~Q2 Server 崩潰 OS 通知~~ → **R5-D1 保留**（已吸收至 `control-panel.md §6.2` + `startup-progress.md §3.7`）
- ~~Q3 Linux 預設值~~ → **R5-D2 Linux 預設 OFF**（已吸收至 `settings-update.md §2.2`）
- ~~R5-4 label 字面歧義「首次 vs 每次」~~ → **R5-D3 每次**（已吸收至 `settings-update.md §2.3` + `control-panel.md §7.1`）
**仍懸而未決**：
1. **控制台 header「port 變更 fallback」視覺字樣**：v1 第四輪決策「port 佔用則 fallback 到 3722/3723」，建議格式 `Port: 3722 (default 3721 in use)`，待使用者最終確認字樣。
2. **v2 是否要回頭作廢 v1 的 `spec/04-first-run.md`**：目前 v2 另開 `v2/first-run-update.md`，但未修改 v1 原檔。建議 v2 穩定後作廢 v1 原檔並改為索引到 v2；在此之前保持雙軌。
3. **R5-E startup-progress.md 新增 3 個小懸念**（`v2/startup-progress.md §11`）：
- (a) 20 秒卡頓 hint 文案「正在重試...」vs 中性「正在處理中，請稍候...」
- (b) 階段 6 WebSocket 連線被安全軟體擋的 Error 說明是否要特別提示
- (c) 使用者按 Retry 的語意：重置整個啟動流程 vs 重試當前階段（Design 建議前者）
**v2.2 新增懸而未決**（來自 `v2/firmware-management.md §14.4`）：
4. **降版 modal 字串「DOWNGRADE」未來 i18n 化處理**：當前 Design 規格要求所有語系使用者皆輸入字面字串 `DOWNGRADE`（en）。若未來改 i18n（如中文使用者輸入「降版」），需與 Architect / Frontend 確認後端 `confirmToken` 是否同步調整（architect 42 §2.3 後端固定接受 `confirmToken: "DOWNGRADE"`）。Design 建議**短期維持英文字串**（跨語言一致、避免後端多語對應）。
5. **bundled 版本「發布日期」資料源**：firmware-management.md §3.3 範例顯示「2024-08 發行」等文案，但 architect 42 §2.1 `FirmwareVersion.ReleaseDate` 為 optional。需 Backend 在 bundle firmware 時準備 metadata（每個 version 目錄附 `META.json` 含 releaseDate / notes）。metadata 缺則 UI fallback 為不顯示日期。
6. **降版進行中關閉 Wails 控制台視窗的攔截邏輯**：依 R5-2 控制台關閉 = 結束 server。降版進行中關控制台 = 中斷降版 = 可能 brick。Frontend / Backend 是否需要在控制台側偵測「降版進行中」並擋下關閉動作？建議 Architect 補充。
---
**下一步：**
- 三方對 v2.1 最終收斂確認（Architect 回看 Design v2.1 是否全部修正到位）
- 使用者最終審 `v2/startup-progress.md` 的 6 階段 wireframe + 文案定版
- 確認後進入開發階段 M8-1 ~ M8-10
- 所有 v2 文件的決策引用格式：`[R5-X]` / `[R5-D-X]` / `[R5-E-X]` 以便追溯
Reference in New Issue View Git Blame Copy Permalink