jim800121chen
c54f16fca0
local-tool/: visionA-local desktop app
- M1: Wails shell + Go server + Next.js UI + Mock mode (macOS dmg ready)
- M2: i18n (zh-TW/en) + Settings 4-tab refactor
- M3: Embedded Python 3.12 runtime (python-build-standalone) + KneronPLUS wheels
- M4: Windows Inno Setup script (build on Windows runner)
- M5: Linux AppImage script + udev rule (build on Linux runner)
- M6: ffmpeg (GPL, pending legal review) + yt-dlp bundled
- Lifecycle: watchServer health check, fatal native dialog,
Wails IPC raise endpoint, stale process cleanup
.autoflow/: full PRD / Design Spec / Architecture / Testing docs
(4 rounds tri-party discussion + cross review)
.github/workflows/: macOS / Windows / Linux build CI
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
69 lines
8.7 KiB
Markdown
69 lines
8.7 KiB
Markdown
# PM 交叉審閱報告
|
||
|
||
> 審閱者：PM Agent
|
||
> 日期：2026-04-11
|
||
> 審閱對象：Design 第三輪修訂版 + Architect 第三輪修訂版
|
||
> 基準：PRD v1.1（含第三輪決策 Q-A / Q-B / Q-C / Q-E1/E2/E3）
|
||
|
||
---
|
||
|
||
## ✅ 對齊的項目
|
||
|
||
- **6 個核心 User Story（US-1~US-5、US-7~US-9）**：Design 的 First-Run（spec/04）、Wireframes（spec/03）、狀態設計（spec/08）與 Architect 的 API 清單、依賴打包、lifecycle 章節，皆能找到對應落地。US-6（tray）已在 PRD v1.1 標註移除，兩端同步刪除。
|
||
- **IA 與 Settings 四分頁**：Design IA（4 主區 + 一般/硬體/模型/進階）與 PRD feature-inventory 4.2 完全一致；Workspace 升一級、外觀分頁取消並把語言併入一般分頁都正確落地。
|
||
- **資料目錄（macOS `~/Library/Application Support/visionA-local/`）**：PRD、Design First-Run、Architect TDD §6（Log 路徑）、lifecycle §2（single-instance lock）、api-endpoints §3（IPC port 檔案）全部一致，未見 `~/.visiona-local/` 殘留。
|
||
- **非功能需求落地**：Architect 的 packaging.md 預估 ~195-210MB（PRD 上限 300MB、目標 ≤ 220MB 內）、Python runtime 雙策略（PRD 6.3 的零預裝）、離線 wheel 安裝（PRD 6.4）、只 bind 127.0.0.1（PRD 6.6）、中英雙語 + 跟隨系統主題（PRD 6.8）皆完整對應。
|
||
- **三平台、x86_64、無簽章**：Architect D3/D4、packaging §1 與 PRD 6.5、release-strategy 一致。R3/R5 Gatekeeper / SmartScreen 的 workaround 已寫進 Design First-Run 歡迎頁 + `SignatureWarningNotice` 元件 + Architect packaging §2.5。
|
||
- **M1 一次清乾淨前端 cluster/relay UI（Q-C）**：Architect design-doc §5 M1-7 已明確列為 M1 必做，且 Design 02-pages-diff 的刪除清單一致。
|
||
- **Tray 整條已砍（Q-A）**：Design 05-tray.md 確認刪除、Architect `tray-and-lifecycle.md` 只保留 lifecycle 內容並加註、`server/internal/tray/` 列入 removed-code。
|
||
|
||
---
|
||
|
||
## ⚠️ 發現的問題
|
||
|
||
### 對 Design 的問題
|
||
|
||
- **D-01 [🟡 需修]** **sidebar 一級入口數量描述不一致**：PRD feature-inventory 4.3 寫「sidebar 為 **5 項一級入口**：Dashboard / Devices / Models / Workspace / Settings」，但 Design spec/01-IA §1.2 明確把 Settings 放在 sidebar **最下方並用 divider 與主導航區隔**（= 4 主 + Settings 特殊位置）。兩端語意其實一致，但字面上會引起工程師混淆。**建議 PM 端把 PRD 4.3 改為「4 個主導航 + Settings（底部獨立區）」與 Design 對齊**（由 PM 自行修）。
|
||
|
||
- **D-02 [🟡 需修]** **Mock 切換入口驗收條件未覆蓋 AC-2.4**：PRD AC-2.4 要求「Mock 與真實模式可隨時在 Settings 切換，切換不需重啟 app」。Design design-spec.md §「待確認 #4」列出切換入口為 Settings > 硬體 + Devices 頁右上 pill + First-Run Step 2，Wireframe 3.3 Devices 頁也有 pill，但 **沒有明確說「切換不需重啟」** 這個非功能條件。建議 Design 在 spec/08-states §8.7 的「切換 Mock/Real 模式」補一句：「切換透過 /api/system/restart 或純前端 state，無需關閉 app」，並與 Architect 確認該 API 行為。
|
||
|
||
- **D-03 [🟢 建議]** **US-3（AC-3.5 Windows UAC 說明 / AC-3.6 Linux udev 說明對話框）只散落在 First-Run Step 3 Phase 2B 的排錯清單**：PRD 明確要求「顯示說明對話框」，Design 只把這兩項做成「可點擊展開的排錯項目」。建議強化成 OS 偵測後的主動 modal（至少首次 connect 失敗時觸發一次），與 US-3 的 AC 更精準對齊。不做不至於違反 AC 文字，但體驗上可再好一點。
|
||
|
||
- **D-04 [🟢 建議]** **Workspace wireframe 缺少 AC-5.4「即時 FPS / 延遲 / CPU / RAM 占用」的明確位置**：spec/03-wireframes §3.4 Control 區只畫了 `Perf: FPS 24 / Latency: 42ms`，沒畫 CPU / RAM。建議在 Control Panel 下補一個小型資源監視區塊，或直接把 `performance-metrics` 元件畫進 wireframe，避免開發階段漏做。
|
||
|
||
### 對 Architect 的問題
|
||
|
||
- **A-01 [🔴 阻斷]** **R9 Plan B（Kneron 授權不過 → 首次啟動線上下載）沒有落地設計**：risks-and-mitigations R9 把 Plan B 寫成「改為首次啟動線上下載」，但 Architect 的 `dependency-bundling.md`、`packaging.md`、`build-pipeline.md` **完全沒有** 設計對應流程（例如：下載進度 UI、URL 設定、斷線重試、完整性 checksum、AppData 內的模型資料夾結構、跟 First-Run Step 1 的整合點）。這會讓「開發到一半才發現授權不過」變成**架構重做**的風險。**建議 Architect 補一份極簡的 R9 Plan B TDD**（不用實作，但要描述資料流與 fallback 時機），並且與 Design 討論 First-Run 要不要插入「下載模型」步驟（會影響 4.4 現有流程圖）。這一項直接影響能否安心進入開發。
|
||
|
||
- **A-02 [🟡 需修]** **Settings 頁 Server Port 改動缺 API 支援**：Design spec/03-wireframes §3.5「硬體」分頁有 `Server Port（預設 3721，衝突時可改）`，但 Architect 的 `api-endpoints.md` 保留的 `/api/system/*` 並沒有「變更 port」的 endpoint；packaging / lifecycle 也沒說明變更 port 之後 Wails 殼要怎麼重新連 WebView（因為 WebView URL 寫死在 lifecycle §1）。建議：(a) 增加 `POST /api/system/config` 或明確說明「port 只能從 Wails menu 改，改完要重啟 server」；(b) 在 TDD 補一段說明 port 衝突錯誤流程（PRD 5.4.1 有定義但 TDD 未對應）。
|
||
|
||
- **A-03 [🟡 需修]** **i18n 範圍未涵蓋 Wails 安裝精靈**：PRD 6.8.1 + Design spec/10 要求「所有 UI 字串、錯誤訊息、First-Run 文案都需雙語」，Architect `i18n.md` §1 雖然有寫「Wails app（安裝精靈、錯誤對話框）：Go 端 i18n map」，但 §2 之後只展開前端 locale 檔結構，**Go 端 i18n map 的具體實作未展開**（沒有檔案路徑、沒有 key 清單、沒有語系偵測方式）。建議補 §3「Go 端 i18n 實作」，至少說明：檔案位置、語系偵測 API、key 命名慣例。
|
||
|
||
- **A-04 [🟡 需修]** **idle 資源目標在 TDD 與 PRD 不一致**：PRD 6.1 要求 Mock idle CPU ≤ 3%（上限 5%）、RAM ≤ 400MB（上限 500MB）；Architect TDD §5 只寫「CPU < 5%、RAM < 500MB」——這是**上限**而非**目標**。會導致開發時只盯上限。建議 TDD §5 補上「目標值 / 上限值」兩欄與 PRD 對齊。
|
||
|
||
- **A-05 [🟢 建議]** **安裝時間目標（PRD 6.1 ≤ 3 分鐘 / 上限 5 分鐘）在 TDD 沒有對應的技術預算拆解**：Architect dependency-bundling / packaging 完全沒有「解壓 90MB python + pip install 5 個 wheel 要花多久」的估算。如果最後超過 5 分鐘，PRD 的北極星指標「5 分鐘內跑出第一次推論 ≥ 95%」會直接破功。建議 Architect 在 dependency-bundling.md 補一張「各步驟時間預算表」（解壓 / venv / pip install / 啟動 server / WebView load），即使是估算也好。
|
||
|
||
---
|
||
|
||
## ❓ 需要使用者或三方討論的問題
|
||
|
||
1. **R9 Plan B 什麼時候要做決定**：目前 R9 標為 P1 release blocker，但若等到 M6 才確認 Kneron 授權，屆時才發現要做 Plan B，可能要延宕 1-2 個月。**建議 Orchestrator 在進入 M1 前就請使用者 / Kneron 業務啟動授權溝通**，平行進行，不要等。
|
||
2. **port 衝突 UX 決策歸屬**：PRD 5.4.1 + Design 8.2 都畫了「更改 Port」按鈕，但 Architect 沒有對應 API。三方需要決定：(a) 做到底（加 API + 重啟流程）；(b) 簡化為「請使用者關閉占用程式後重啟」（砍掉按鈕）。Design / Architect 需同步。
|
||
3. **M1 端到端 smoke test 的驗收定義**：Architect M1-13 寫「Mock 模式看到 3 台假裝置跑推論，且 UI 完全沒有 cluster / relay / tunnel 入口」。建議使用者 / PM 確認這個就是 M1 的 Definition of Done，以免 M1 延伸到「連真實裝置也要通」。
|
||
|
||
---
|
||
|
||
## 結論
|
||
|
||
**是否可以進入開發階段？** — **有條件是**。
|
||
|
||
**條件清單（照順序處理）**：
|
||
|
||
1. **[阻斷] A-01**：Architect 補 R9 Plan B 的簡版設計（資料流 + First-Run 整合點），否則開發到後期有架構重做風險。
|
||
2. **[需修] D-02 / A-02**：Mock 切換與 Server Port 變更的 API / 重啟行為要三方對齊，否則 Wireframe 按鈕會變成空按鈕。
|
||
3. **[需修] A-03 / A-04**：Architect 補 Go 端 i18n 實作章節、TDD §5 效能目標對齊 PRD。
|
||
4. **[需修] D-01**：PM 自行把 PRD 4.3 sidebar 描述對齊 Design IA（5 項 → 4 主 + Settings）。
|
||
5. **[討論] Q1 Kneron 授權**：Orchestrator 在 M1 啟動前協助使用者聯繫 Kneron 平行確認，不要等到 M6。
|
||
|
||
以上條件完成後，三方文件可視為 ready，進入 Reviewer 審查 + 開發（M1）階段。其餘 🟢 建議項目可在 M1 / M2 迭代時處理，不作為開發阻斷。
|