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>
199 lines
12 KiB
Markdown
199 lines
12 KiB
Markdown
# 8. 風險與相依性
|
||
|
||
本章節整合 PM 視角的產品風險與 Architect Round 1 的技術風險。所有 R1-R5 原始編號沿用 Architect 的定義，PM 補充 P1-P5。
|
||
|
||
## 8.1 技術風險（來自 Architect Round 1，交叉引用）
|
||
|
||
### R1 — KneronPLUS Linux wheel 的 glibc / ABI 相容性
|
||
|
||
| 項目 | 內容 |
|
||
|------|------|
|
||
| 描述 | KneronPLUS Linux wheel 綁定特定 glibc 版本，可能無法在所有 Ubuntu 22.04 / 24.04 執行 |
|
||
| 可能性 | 高 |
|
||
| 影響 | 高（Linux 平台無法使用） |
|
||
| 緩解 | 實測 Ubuntu 22.04 + 24.04；若不過，在 6.5.1 相容性需求中限定版本；AppImage 內帶 libusb |
|
||
| PM 補充 | 若 R1 發生，可考慮 Linux 為 Phase 2（先發 Mac / Win），但不推薦——會破壞「三平台齊發」定位 |
|
||
|
||
### R2 — Windows WinUSB driver 需 UAC 同意
|
||
|
||
| 項目 | 內容 |
|
||
|------|------|
|
||
| 描述 | Windows 首次啟動需安裝 WinUSB driver，若使用者拒絕 UAC 則 Kneron 裝置無法使用 |
|
||
| 可能性 | 中 |
|
||
| 影響 | 高（Windows 平台功能失效） |
|
||
| 緩解 | First-Run 明確說明原因；提供「手動安裝 driver」的後援文件；若拒絕 UAC 則引導進 Mock 模式 |
|
||
| PM 補充 | US-3 AC-3.5 已包含此 edge case 的驗收標準 |
|
||
|
||
### R3 — KneronPLUS macOS wheel 可能只有 x86_64
|
||
|
||
| 項目 | 內容 |
|
||
|------|------|
|
||
| 描述 | 若 KneronPLUS macOS wheel 只有 x86_64 而無 arm64，M 系 Mac 會走 Rosetta（KneronPLUS dylib 抗議） |
|
||
| 可能性 | 中 |
|
||
| 影響 | 高（M 系 Mac 無法使用） |
|
||
| 緩解 | Q4 已明確決定「三平台都只做 x86_64」，使用者目前是 Intel Mac。使用者若有 M 系需求再加 |
|
||
| PM 補充 | **此風險已被 Q4 決策降級為低優先**，但需在發佈說明寫明「目前只支援 Intel Mac」 |
|
||
|
||
### R4 — 離線 wheel 安裝失敗（無 pip / ensurepip）
|
||
|
||
| 項目 | 內容 |
|
||
|------|------|
|
||
| 描述 | Ubuntu 有時不預裝 `python3-venv`，導致離線 wheel 安裝失敗 |
|
||
| 可能性 | 中 |
|
||
| 影響 | 中（Linux 首次啟動失敗） |
|
||
| 緩解 | 沿用 `installer/app.go` 的 `installPython3Venv()` fallback，需 sudo；或引導使用者手動裝 |
|
||
| PM 補充 | Q1 決定 A + B（內嵌 Python + fallback 系統 Python），R4 的主要解法是優先走內嵌路線 |
|
||
|
||
### R5 — 預置模型 .nef 的授權限制（**發佈前必須確認**；對應 Architect R9）
|
||
|
||
| 項目 | 內容 |
|
||
|------|------|
|
||
| 描述 | Kneron 預置的 .nef 模型可能限制 re-distribution |
|
||
| 可能性 | 低—中（未知） |
|
||
| 影響 | 中（影響 73MB 預置模型的可打包性） |
|
||
| **狀態（第三輪 Q-B 決策）** | **不再是「阻斷開發」的風險**。使用者決定先**假設可重新散布**，開發階段繼續把預置模型內嵌到 payload 與打包流程中，讓 MVP 開發可以往前推進。**但這是一個「發佈前必須確認」的風險**——在正式 release 到 Gitea / GitHub Releases **之前**，PM 必須完成授權確認；否則不能對外發佈。 |
|
||
| **狀態（第四輪 R4-1 決策）** | 使用者決定**暫不主動問 Kneron**，維持第三輪「B4 假設可重新散布」路線繼續開發。理由：主動問若得到拒絕會立刻變阻斷；先開發到 M5/M6 有成品再談授權，談判籌碼與確認時機點更務實。**發佈前 gate 維持生效**——`v1.0.0` 到 Gitea / GitHub Releases 前必須完成授權確認，這條不變。此風險維持 P1 追蹤項。 |
|
||
| 緩解 | 1) 開發階段：先假設 OK，持續內嵌並測試打包；2) **發佈前 gate**：PM 完成 Kneron 官方 re-distribution 授權確認；3) 若最終不允許：fallback 方案改為「首次啟動線上下載預置模型」（會破壞完全離線承諾，需讓使用者知情），或移除預置模型、要求使用者自備 .nef。Architect TDD 需在 M2 前備齊 fallback 方案的極簡設計（對應 pm-cross-review A-01）。 |
|
||
| PM 行動 | **在 release `v1.0.0` 前**必須完成授權確認。第四輪決策：不主動聯繫 Kneron，但持續把本風險列入 `progress.md` 未解決問題，發佈前 gate 觸發時再啟動 |
|
||
| 追蹤 | 列入 `progress.md` 的「未解決問題」直到確認為止 |
|
||
|
||
### R11 — 發佈通路（內部 Gitea Releases / GitHub Releases）尚未確認可用（第四輪新增）
|
||
|
||
| 項目 | 內容 |
|
||
|------|------|
|
||
| 描述 | PRD 第 7 章（release-strategy）假設發佈到 Innovedus 內部 Gitea Releases 或 GitHub Releases。實際上這兩個通路是否已備好（repo 存在、release API 可用、存儲配額夠放 3 平台 × 每版本約 600MB 安裝檔）都尚未確認 |
|
||
| 可能性 | 中 |
|
||
| 影響 | 中（發佈日前才發現會導致臨時找替代通路，如 S3 直接連結 / 內部檔案伺服器） |
|
||
| 等級 | **P2 追蹤項** |
|
||
| 緩解 | 1) M1 啟動後第一週由 DevOps / PM 確認 Gitea Releases 可用性；2) 若不可用：退而求其次用 GitHub Releases（私有 repo）或 S3 pre-signed URL；3) 發佈腳本需支援至少兩種通路 |
|
||
| PM 行動 | M1 Week 1 完成通路確認並更新 release-strategy.md |
|
||
| 追蹤 | 列入 `progress.md` 的「未解決問題」直到確認為止 |
|
||
|
||
### R12 — CI runner 三平台齊備度未知（第四輪新增）
|
||
|
||
| 項目 | 內容 |
|
||
|------|------|
|
||
| 描述 | 三平台 build 需要 macOS / Windows / Linux CI runner。Innovedus 目前是否已有齊備的 self-hosted runner 或付費 GitHub Actions 額度尚未確認。macOS runner 尤其稀缺且昂貴 |
|
||
| 可能性 | 中—高 |
|
||
| 影響 | 中（若 runner 不齊備，會退化成「本地手動 build」，拖慢每次 release 時程，且不利於回歸測試） |
|
||
| 等級 | **P2 追蹤項** |
|
||
| 緩解 | 1) M1 啟動後第一週由 DevOps / PM 盤點 runner 現況；2) 短期可接受本地手動 build（開發者本機當 runner），但要有明確的 build SOP 與產物驗證腳本；3) 長期需在 M4-M5 前備好三平台自動化 runner，避免 release 時塞車 |
|
||
| PM 行動 | M1 Week 1 完成 runner 盤點，若缺則把補齊 runner 列為 M2/M3 的 infra 工作項 |
|
||
| 追蹤 | 列入 `progress.md` 的「未解決問題」直到確認為止 |
|
||
|
||
## 8.2 產品風險（PM 補充）
|
||
|
||
### P1 — 使用者因 Gatekeeper / SmartScreen 警告放棄安裝
|
||
|
||
| 項目 | 內容 |
|
||
|------|------|
|
||
| 描述 | Q2 決定不買程式碼簽章，Mac 會跳「unidentified developer」警告，Windows 會被 SmartScreen 攔截 |
|
||
| 可能性 | 高（每個新使用者第一次都會碰到） |
|
||
| 影響 | 中（有技術背景的使用者能克服，但非技術背景可能卡住） |
|
||
| 緩解 | First-Run 歡迎頁 + 發佈說明頁提供清晰的警告處理步驟；錄製 GIF / 截圖說明 |
|
||
| 責任 | Design Agent 負責 First-Run UX；PM 負責內部文件 |
|
||
|
||
### P2 — 內部 FAE 不知道有新版（因為無 auto-update）
|
||
|
||
| 項目 | 內容 |
|
||
|------|------|
|
||
| 描述 | Q6 決定不做 auto-update，舊版本可能永遠在外面跑，bug / 新功能無法觸達使用者 |
|
||
| 可能性 | 中 |
|
||
| 影響 | 中 |
|
||
| 緩解 | 每次 release 透過 Slack / Email 強力推播；在 Dashboard 下方顯示目前版本號，鼓勵自查；未來考慮加「check for updates」手動按鈕（不是 auto-update） |
|
||
| PM 行動 | 建立內部發佈通知機制 |
|
||
|
||
### P3 — 內部工具沒有 telemetry 導致無法知道使用者卡住在哪
|
||
|
||
| 項目 | 內容 |
|
||
|------|------|
|
||
| 描述 | Q12 決定不做遙測，若使用者首次安裝失敗可能直接放棄，PM / 工程師無感 |
|
||
| 可能性 | 中 |
|
||
| 影響 | 中（無法持續優化安裝體驗） |
|
||
| 緩解 | 每次新版發佈後主動問 5-10 位內部 FAE 的回饋；建立 Slack channel 接收主動回報；日誌會寫本地，請 FAE 遇問題時抓 log 送上來 |
|
||
| PM 行動 | 建立「新版發佈後主動 follow-up」的標準作業 |
|
||
|
||
### P4 — Scope creep：有人要求加回非目標清單裡的功能
|
||
|
||
| 項目 | 內容 |
|
||
|------|------|
|
||
| 描述 | 開發過程或發佈後，可能有人要求加 auto-update / 簽章 / cluster 回來 |
|
||
| 可能性 | 中 |
|
||
| 影響 | 高（會破壞「瘦身 50%」目標） |
|
||
| 緩解 | 本 PRD 第 3.2 節列出明確非目標；任何要求回加的功能必須回到三方討論重新評估 |
|
||
| PM 行動 | Orchestrator 主持三方討論時需嚴守非目標邊界 |
|
||
|
||
### P5 — KneronPLUS SDK 升版導致 wheel 不相容
|
||
|
||
| 項目 | 內容 |
|
||
|------|------|
|
||
| 描述 | KneronPLUS 未來新版 SDK 可能改 API / 改 ABI，導致 visionA-local 舊版裝置失效 |
|
||
| 可能性 | 低 |
|
||
| 影響 | 高（長期維護風險） |
|
||
| 緩解 | 固定 KneronPLUS wheel 版本，跟 edge-ai-platform 主線同步；升版前做 regression test |
|
||
| PM 行動 | 與 Architect 約定 KneronPLUS 版本升級的 review 流程 |
|
||
|
||
## 8.3 相依性
|
||
|
||
### 8.3.1 外部相依（核心）
|
||
|
||
| 相依 | 用途 | 風險 |
|
||
|------|------|------|
|
||
| KneronPLUS SDK（wheel） | 裝置 / 推論 | R1, R3, R5, P5 |
|
||
| Python 3.10+ | 執行 KneronPLUS | R4 |
|
||
| ffmpeg（LGPL build） | 攝影機 / 影片處理 | 低（已有靜態 binary） |
|
||
| libusb-1.0 | USB 存取 | R1（Linux） |
|
||
| Wails v2 | 桌面殼 | 低（已使用於 edge-ai-platform） |
|
||
| Go 1.26 | Server | 低 |
|
||
| Next.js 16 / React 19 | 前端 | 低 |
|
||
| yt-dlp | `/api/media/url` | 低（Q10 決定保留） |
|
||
|
||
### 8.3.2 內部相依
|
||
|
||
| 相依 | 用途 | 備註 |
|
||
|------|------|------|
|
||
| edge-ai-platform 主線 | 程式碼複製來源 | 需維持與主線的核心業務邏輯同步 |
|
||
| Innovedus 內部 Gitea | 發佈通路 | **R11 追蹤**：需確認 Release 機制可用 |
|
||
| 內部 CI runner（macOS / Windows / Linux） | 三平台 build | **R12 追蹤**：需確認三平台 runner 都可用 |
|
||
|
||
### 8.3.3 人員相依
|
||
|
||
| 角色 | 備註 |
|
||
|------|------|
|
||
| Architect | 負責打包與依賴策略 |
|
||
| Backend / Frontend 工程師 | 負責程式碼瘦身與改寫 |
|
||
| Design | 負責 First-Run UX、主視窗 menu bar 規格（原 Tray 規格已於第三輪 Q-A 取消） |
|
||
| PM | 負責 Kneron 授權確認（R5 緩解） |
|
||
| 內部 FAE | 首次發佈後的 5-10 位 beta 使用者 |
|
||
|
||
## 8.4 風險矩陣
|
||
|
||
```
|
||
影響 ↑
|
||
高 │ R1 R3 P5
|
||
│
|
||
│ R2 P1 P4
|
||
中 │ R4 R5 P2 P3
|
||
│
|
||
低 │
|
||
└───────────────────────────────→ 可能性
|
||
低 中 高
|
||
```
|
||
|
||
## 8.5 需要 Architect Round 2 驗證的風險點
|
||
|
||
進入第二輪架構設計前，Architect 必須實測並回報：
|
||
|
||
1. **R1**：在 Ubuntu 22.04 / 24.04 x86_64 實測 KneronPLUS wheel，確認 glibc 相容
|
||
2. **R3**：`lipo -info` 檢查 KneronPLUS macOS .dylib 的架構（確認是 x86_64 only 還是 Universal）
|
||
3. **R4**：實測 Ubuntu 22.04 離線 wheel 安裝流程，確認 venv 能建立
|
||
4. **R5**：PM 需在**發佈前**（非 Architect Round 2）提供 Kneron re-distribution license 確認結果；Round 2 只需確認「若發生 fallback，線上下載方案的技術可行性」
|
||
|
||
Architect Round 2 TDD 必須包含這四個風險的實測結果與緩解方案落地。
|
||
|
||
## 8.6 PM 需要進一步確認的事項（寫入 progress.md 未解決問題）
|
||
|
||
1. **R5 授權確認（發佈前 gate；P1）**：Kneron 預置 .nef 模型可否 re-distribution？需向 Kneron 官方詢問。**發佈 v1.0.0 前必須有結論**，開發階段先假設可行。**第四輪 R4-1 決策**：不主動聯繫，維持第三輪 B4 路線繼續開發，發佈前再啟動。
|
||
2. **R11 內部 Gitea Releases 機制（P2）**：是否已可用？是否需要申請新 repo？是否有儲存配額足以放 3 平台 × 每版本約 600MB？**第四輪 R4 新增**，M1 Week 1 前確認。
|
||
3. **R12 CI runner（P2）**：Innovedus 是否已有三平台 runner？若無，需評估自建 / GitHub Actions 成本。**第四輪 R4 新增**，M1 Week 1 前盤點。
|