jim800121/visionA
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
102 Commits 1 Branch 0 Tags
Commit Graph

14 Commits

Author SHA1 Message Date
jim800121chen
8c27da7cca test(local-tool): M9-5 — three-platform validation plan + e2e scripts + MJ3 fix 
A 階段最後 milestone、出測試計畫 + 自動化腳本 + 三平台人工 checklist、使用者下週手動跑實機驗證。

Testing artifacts (8 檔、2630 行):
- .autoflow/06-testing/m9-5-validation-plan.md: 656 行（4 情境 × 3 平台 × 2 chip = 24 combo）
- 4 e2e specs (vitest + RTL + mock WS / mock fetch):
  - firmware-upgrade-happy-path.spec.ts (357 / 4 cases)
  - firmware-upgrade-error-recovery.spec.ts (356 / 4 cases + 8 reason it.each)
  - firmware-r-fw-11-modal-not-closable.spec.ts (303 / 6 cases)
  - wails-onbeforeclose-firmware-active.spec.ts (217 / 9 cases、含 5 todo 占位 M9-12)
- 3 manual checklists: macOS 264 / Windows 234 / Linux 243 行

設計取捨:
- 不引入 Playwright/Cypress (visionA-local frontend 沒裝、屬 architect 決策)、走 vitest + mock
- E2E 腳本放 06-testing/scripts/ 作 spec doc + 可選實作參考
- 實機驗證走人工 checklist (dongle 插拔 / kill process / SIGTERM 等需要實體互動)

MJ3 修復 (M9-4 reviewer round 1 留的 follow-up):
- server/internal/api/ws/firmware_ws_test.go: +16/-8
- "type": "firmware:progress" → "firmware_progress" (對齊 firmwareProgressMessage.Type)
- "phase" → "stage" (對齊 TDD §4.2 + FirmwareProgress.Stage)
- 不動 production code、只 test schema 對齊

執行建議 (給你下週):
- Day 1 P0: macOS+Win+Linux × KL520+KL720 happy path (~3h)
- Day 2 P1: R-FW-11 + disconnect_during_op + upgrade_mid_failed + 失敗注入 (4h)
- Day 3 P2: SIGTERM 延遲關閉 + Wails OnBeforeClose force-quit modal (2-3h)

測試:
- go test ./... -race 全綠 (server / wails / frontend 60 tests)
- MJ3 修復不破壞既有測試

A 階段開發 6/7 完成 (M9 文件 + M9-1 ~ M9-4.5)、剩 M9-5 實機驗證 (你下週跑)、跑完依結果決定 A 階段交付或派 sub-agent 修。

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-25 15:34:17 +08:00
jim800121chen
ff9bbc81ed feat(local-tool): M9-4.5 — server SIGTERM + Wails OnBeforeClose firmware-aware shutdown 
A 階段尾端 milestone、雙層防護避免使用者在 firmware 升級進行中關閉 app 造成 dongle brick。

Server 端 (3 改):
- main.go: SIGTERM/SIGINT goroutine 加 firmware-aware preamble
- server/internal/firmware/shutdown.go: 新 211 行（AwaitActiveTasksOrTimeout + 3 interfaces + shutdownBroadcastTask minimal struct + toBroadcastTasks helper）
- server/internal/firmware/shutdown_test.go: 新 384 行、8 tests

Wails 端 (3 新 + 2 改):
- visiona-local/main.go: OnBeforeClose 從 inline → app.OnBeforeClose
- visiona-local/app.go: App struct 加 firmwareCloseGuard
- visiona-local/firmware_close_guard.go: 新 244 行（CloseGuard + OnBeforeClose + ConfirmForceClose）
- visiona-local/firmware_close_guard_test.go: 新 280 行、8 tests
- visiona-local/query_firmware_active_tasks.go: 新 111 行（HTTP helper、fail-open、1s timeout）
- visiona-local/query_firmware_active_tasks_test.go: 新 250 行、7 tests

行為:
- Server SIGTERM 有 active task → broadcast `server:shutdown-pending` to "system" room → RequestShutdown + WaitForActiveTasks(220s) → 走原本 shutdownFn
- Wails OnBeforeClose 有 active task → emit Wails event `app:firmware-in-progress` + return true 擋住關閉
- ConfirmForceClose binding 給 frontend 第二層 FORCE 確認用、走 graceful 7+1s shutdown（不是 SIGKILL bypass、雙層防護）

Reviewer 兩輪審查:
- Round 1: 0 Critical / 1 Major / 3 Minor / 4 Suggestion
- 第 2 輪修法（3 sub-agent 平行）:
  - Architect: TDD §8.6 改 event 名 `firmware:shutdown-rejected` → `server:shutdown-pending`、標題「拒絕」→「延遲」、補 payload schema 註明 tasks 不含 startTs
  - Design: control-panel.md §6a 改「SIGKILL bypass」→「graceful 7+1s 雙層防護」、補「為何不採 SIGKILL」5 點設計理由、§6a.11 IPC 規格對齊
  - Backend: MaxShutdownWait 180s → 220s（KL720 200s upgrade + 20s buffer）+ broadcast 過濾 startTs（shutdownBroadcastTask minimal struct + toBroadcastTasks helper）

測試:
- server: go test ./... -race 全綠（firmware 2.7s + api/ws/handlers）
- wails: go test ./... -race 全綠（visiona-local 11.2s、21 tests）
- 合計新增 23 unit tests race-clean、0 regression

下一步: M9-5 三平台實機驗證 + 順手修 MJ3（backend smoke test schema phase→stage / firmware:progress→firmware_progress）

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-25 15:07:29 +08:00
jim800121chen
06ff2fe987 feat(local-tool): M9-4 — Frontend FW badge + 升級 modal + WS hot-fix 
A 階段第四個 milestone、完整 Frontend FW UI（badge / modal / 8 種 reason 復原）+ backend WS hot-fix（補對稱於 flash 的 firmware WS endpoint）。

Frontend（13 修改 / 7 新檔）:
- 新 firmware/ component group (badge / upgrade-button / upgrade-dialog 4-phase / progress-view / error-view 8-reason / index)
- Zustand store (firmware-store.ts) + WS hook (use-firmware-progress.ts) 對齊既有 useFlashProgress pattern
- DeviceCard 整合 FirmwareBadge + FirmwareUpgradeButton
- i18n: settings.firmware.* namespace (對齊 Design Spec §9 SoT) + devices.card.fwBadge.* (zh-TW + en, 57 leaf keys × 2 lang = 114 strings)
- toast.ts ToastOptions interface (duration param)
- types/device.ts: FW 衍生欄位 + FirmwareStage/Reason/ProgressEvent/ActiveTask types

Backend WS hot-fix (3 檔):
- ws/firmware_ws.go (50 行、純對稱 flash_ws.go)
- ws/firmware_ws_test.go (165 行、2 smoke tests: broadcast + room isolation)
- router.go: GET /ws/devices/:id/firmware-progress

關鍵設計:
- R-FW-11 緩解: upgrading phase modal 不可關 (onInteractOutside/onEscapeKeyDown preventDefault + 隱藏 X)
- 多裝置隔離 defense in depth: store handleEvent activeDeviceId mismatch 直接 return
- 8 種 reason → 4 種 UX (recoverable/destructive/brick 警告/contactSupport)
- ContactSupport mailto handler (RFC 6068 + encodeURIComponent)

Reviewer 兩輪審查:
- Round 1: 0 Critical / 3 Major / 8 Minor / 5 Suggestion
- Round 2: 0 Critical / 0 Major / 0 Minor / 2 Suggestion（接受方案 A、不需 frontend 第 3 輪）
- MJ1 i18n namespace 採方案 A (settings.firmware.*)、Design SoT 優先、Reviewer 同意

測試:
- pnpm test --run: 60 tests pass (32 firmware: 22 store + 10 badge + 新 9 error-view + 19 既有)
- npx tsc --noEmit: 0 error
- pnpm build: production build 成功
- go test ./internal/api/ws/... -race: 1.964s 全綠
- pnpm lint firmware/: 0 hit (17 既有 lint 問題不屬 M9-4、follow-up)

未做（範圍外）:
- Settings 韌體面板 (M9-12 B 階段)
- 手動降版 UI (M9-12)
- 版本切換 dropdown (B 階段)
- Wails 控制台 force-quit modal (M9-4.5)

A 階段 MVP 後端 + 前端開發全部完成、剩 M9-4.5 (SIGTERM + Wails OnBeforeClose) + M9-5 (三平台實機驗證)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-25 12:57:21 +08:00
jim800121chen
5e281ed449 feat(local-tool): M9-3 — firmware API handlers + WebSocket progress room 
A 階段第三個 milestone、暴露 firmware service 給 Frontend / Wails control panel。

New / modified:
- server/internal/api/handlers/firmware_handler.go: 新檔 465 行（upgrade + active-tasks endpoint + WS broadcast goroutine）
- server/internal/api/handlers/firmware_handler_test.go: 新檔 938 行、26+ subtests
- server/internal/api/handlers/device_handler.go: +47 行（3 個 firmware 衍生欄位）
- server/internal/api/router.go: +23 行
- server/main.go: +10 行（wire firmware service + handler）

4 endpoints 全到位（對齊 TDD §3.1）:
- GET /api/devices: 加 firmwareIsLegacy / firmwareCanUpgrade / bundledFirmwareVersion（firmwareVersion 沿用既有 DeviceInfo 鍵）
- POST /api/devices/scan: 同步走 enrichDevices
- POST /api/devices/:id/firmware/upgrade: 202 + {taskId}
- GET /api/firmware/active-tasks: HasActiveTask + GetActiveTaskInfo
- WebSocket room firmware:<deviceID> broadcast 對齊 §4.2

關鍵設計：
- 3 層 interface（firmwareBroadcaster / firmwareService / deviceLookupSource）+ DeviceManagerAdapter 解 import cycle
- bundledVersion cache（只 cache success、避免 thundering herd / poison）
- isLegacyFirmware 對齊 bridge.py 規則（legacy_exact set + KDP1.x prefix + KDP2-9 forward-compat）+ parity 真值表測試
- 5 個錯誤碼齊全（DEVICE_NOT_FOUND / FW_UNSUPPORTED_CHIP / FW_DEVICE_BUSY / FW_UPGRADE_FAILED / FW_UPGRADE_BRICK_RISK）

Reviewer 兩輪審查：
- Round 1: 0 Critical / 1 Major / 3 Minor / 5 Suggestion
- Round 2: 0 Critical / 0 Major / 0 Minor / 3 極小 Suggestion（全部 backend 不需處理、純評估）
- Major 1（JSON 雙鍵衝突 firmwareVer vs firmwareVersion）方案 A 完全到位、3 個 test 鎖定 regression

TDD 同步：firmware-management.md §3.1 line 131 firmwareVer → firmwareVersion 對齊實作。

測試：go test ./... -race -count=1 全綠（handlers 2.489s / api 3.522s / ws 4.623s / device 1.931s / firmware 2.695s / driver/kneron 5.583s / model 5.022s）

SIGTERM main.go 整合留 M9-4.5（與 Wails OnBeforeClose 一起做）。

下一步：M9-4 Frontend Devices 頁 FW badge + 升級 modal + i18n（1.5 人天）

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-25 12:05:42 +08:00
jim800121chen
c03eb6fd0e feat(local-tool): M9-2 — Go driver UpgradeFirmware + firmware service module 
A 階段第二個 milestone、銜接 M9-1 bridge.py、暴露 service layer 給 M9-3 API/WebSocket。

New module `server/internal/firmware/`:
- types.go: 123 行（FirmwareVersion / FirmwareProgress / ActiveTaskInfo / UpgradeDriver interface / 8 reason const）
- progress.go: 147 行（仿 flash pattern 的 Tracker、Task.cancel 預留 SIGTERM force-cancel godoc）
- service.go: 373 行（核心 service：UpgradeFirmware / HasActiveTask / GetActiveTaskInfo / RequestShutdown / WaitForActiveTasks / ListBundledVersions / GetCurrentVersion）
- service_test.go: 676 行、13 個 test 含 MultiDeviceParallel

Driver layer:
- kl720_driver.go: 697 → 1054 行（+357、新 UpgradeFirmware method + tryRouteFirmwareEvent + sendCommandForUpgrade snapshot pattern）
- kl720_driver_test.go: 360 行、11 個 test（含 InfoNotBlockedDuringUpgrade / CtxCancelReleasesBridge / StderrEventAfterCtxCancel 100 round stress）

關鍵設計：
- flash 與 firmware 模組分離（不 import flash）
- UpgradeDriver interface 隔離 driver 細節、DeviceLookup interface 隔離 device manager
- 中介 channel pattern（service ↔ driver）方便 service 補欄位（DeviceID / Direction / BeforeVersion）
- timeout 雙保險：chip timeout + 30s margin
- 8 reason enum 對齊 bridge.py、stage 採 Design 命名

Concurrency race 修復（M9-2 Reviewer round 1 → round 2）:
- Major 1（mutex deadlock）：新 fwUpgradeMu 獨立鎖 + sendCommandForUpgrade snapshot stdin/stdout pattern、避開 d.mu field-level race + 升級期間 Info/Disconnect 不被卡 + timeout 路徑無死鎖
- Major 2（close-channel race）：tryRouteFirmwareEvent 持 fwMu 整段、配合 defer setFirmwareProgressCh(nil) 提供 happen-before、絕無 send on closed channel panic

Reviewer 兩輪審查：
- Round 1: 0 Critical / 2 Major / 5 Minor / 5 Suggestion
- Round 2: 0 Critical / 0 Major / 2 Minor / 2 Suggestion（11/12 issue 修到位、Suggestion 4 留 follow-up）

M9-1 follow-up 順手清：
- m5（test 死碼 _firmware_upgrade_start_ts 殘留兩行）已清
- s5（test 註解 idempotent shape 說明）已加

測試：
- go test ./... -race -count=1: 全綠（28s、無 regression）
- Python: 36 tests + 22 subtests 全綠（0.31s）
- go vet / build: 0 output

下一步：M9-3 API handler + WebSocket progress（CI 建議 `go test -race -count=3` 提升 race 偵測強度）

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-25 11:27:36 +08:00
jim800121chen
d7b5a2398a feat(local-tool): M9-1 — bridge.py firmware_upgrade handler（KL520+KL720 KDP1→KDP2） 
A 階段第一個 milestone、純 bridge.py 層 + ctypes 直接呼叫 KneronPLUS C symbol。

Source:
- server/scripts/kneron_bridge.py: 1207 → 2058 行（+851）
- server/scripts/test_kneron_bridge_firmware.py: 新檔 840 行、36 unit tests 全綠 0.076s

Firmware bundled:
- server/scripts/firmware/KL520/fw_loader.bin（90112 bytes、MD5 aef7cca17bc023abbd6152c46c18e774、與 warrenchen 一致）
- server/scripts/firmware/{KL520,KL720}/VERSION（v2.2.0）

實作對齊 TDD §6.1 規格（98% 對齊度）：
- handler input/output schema 100%
- stage enum: preparing/loading/flashing/verifying/done/error（採 Design 命名）
- reason enum 7/8（disconnect_during_op 留 M9-5 實機測試）
- ctypes binding 1:1 對齊 warrenchen legacy_plus121_runner.py
- 4 個情境 stage 序列驗證通過（KL520 KDP1+loader / KL520 KDP1 缺 loader / KL720 legacy / 已 KDP2）
- timeout 60s/200s、USB stable 5-8s wait、SIGTERM 拒絕邏輯
- progress event schema 完整（percent/stage/message/elapsed_ms/eta_ms/extra）

Reviewer 兩輪審查：
- 第 1 輪：0 Critical / 3 Major / 4 Minor / 4 Suggestion
- 第 2 輪：通過 with 1 Minor + 1 Suggestion（m5 test 死碼 / s5 test 註解、留 M9-2 順手清）
- M3 firmware 字串覆蓋從 substring → 顯式 enumeration + KDP3+ forward-compat（防未來 brick 風險）
- M2 控制流重構（needs_loader/should_run_loader_stage/loader_required_but_missing 三個顯式 bool）
- m3 single-owner disconnect 原則完整落地

既有 6 個 handler（scan/connect/disconnect/reset/load_model/inference）零改動、無 spillover risk。

下一步：M9-2 Go driver UpgradeFirmware + firmware/service.go

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-25 08:10:46 +08:00
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
jim800121chen
b71ff4cd3c perf(local-tool): Windows KL520 cold-boot connect 106s → ~40s（跳過多餘 reset） 
背景：
Windows 實測 KL520 首次 connect 耗時 106 秒，原因是 reset 流程內部重複
firmware load：
  1. 進來 Loader → load firmware (35s) → Comp/U
  2. reset 退回 Loader → bridge 重啟
  3. reconnect 進來又是 Loader → load firmware (30s) → Comp/U
  4. Loader reconnect 第一次常 fail（15s timeout）
總共 ~65s 花在「砍掉剛載好的 firmware、再載一次」的白工上。

根因：先前修的 needsReset 邏輯不管 firmware 新舊一律 reset。但 Error 15
只發生在「Comp/U 是上次 session 殘留」的情境；「本次 connect 內部剛載的
Comp/U」session 是乾淨的，不需要 reset。

修法（條件性 reset）：
- server/scripts/kneron_bridge.py：connect handler 新增追蹤本次有無走
  firmware load flow，return 多帶 `fresh_firmware_loaded` bool
- server/internal/driver/kneron/kl720_driver.go：Connect 讀 flag，若為
  true 就 skipReset（firmware 剛載的，session 已乾淨）

驗證（2026-04-21）：
- `/tmp/test_bridge.py` 拔插 USB 後跑 `connect (fw=Loader) →
  fresh_firmware_loaded=True → skip reset → load_model → inference`
  → 11 detections（person×8, tie×3, latency 332ms）
- Mac UI Comp/U 殘留路徑：reset → 11 bbox ✓
- Mac UI Loader cold-boot 路徑（拔插後）：skip reset → 11 bbox ✓

預期效益：
- Windows cold-boot（常見）：106s → ~40s（省 65s）
- Mac 跨 session（常見）：~15-20s 不變
- 極少數（Windows device 未斷電但跨 server session）：走完整 reset

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-04-21 11:09:25 +08:00
jim800121chen
30d0ff5695 fix(local-tool): 推論 bbox 標註不顯示 — 前端 canvas 尺寸 + KL520 reset + 延長 timeout 
症狀：Mac 版上傳單張圖推論，畫面完全沒有 bbox 標註。實測追根因後發現
兩層獨立問題疊加（前端 + 後端），擇一修復都無法解決。

## Layer 1: 前端 canvas 尺寸對不上 img 顯示尺寸
- camera-inference-view.tsx renderedSize 初始值硬寫 {w:640, h:480}
- ResizeObserver 理應在 <img> load 後 fire，但實測沒 fire 或時機不對
- 結果 overlay canvas 永遠用 640×480 畫，bbox 嚴重偏位或跑出 canvas

修法（camera-feed.tsx + camera-inference-view.tsx）：
- <img> 加 onLoad handler，decode 完立刻用 getBoundingClientRect 回報
- ResizeObserver effect 進來先檢查 img.complete && naturalWidth > 0，
  是就立刻 report（cover HMR / cached image）
- effect 依賴加 streamUrl / batchImageUrl，換圖會重觀察
- renderedSize 初始值改 null，overlay 改為拿到真實尺寸才 render
- setState callback 用 prev 比對，同尺寸不觸發 render
- camera-overlay.tsx 加 [bbox-debug] console.log 保留（debug 成本低，
  對未來排查有幫助）

## Layer 2: KL520 推論炸 ApiKPException Error 15
- kp.inference.generic_image_inference_send 回 SEND_DATA_TOO_LARGE
- 試過 image 尺寸（516×640 / 640×794 / 640×640 host pad）、numpy vs
  bytes、明確傳 width/height — 全部炸
- Python bridge 直接測試（/tmp/test_bridge.py）做完整
  `connect → reset → reconnect → load_model → inference` 序列 → 11 個
  detection 正常回傳
- Go driver 走 `connect → load_model → inference` 跳過 reset

根因：commit ddf0eb8（2026-04-16）「KL520 首次 connect 跳過 reset」當時
為解 Windows 60s HTTP timeout 的優化。但副作用：KL520 若 session 間
firmware 殘留（fw=KDP2 Comp/U），直接 load_model + inference 100% 炸
Error 15。必須走完整 reset → 退回 Loader → 重新載 firmware → Comp/U
流程才能得到能 inference 的 session。

修法（kl720_driver.go）：
- 移除「KL520 跳過 reset」特例，讓 KL520 和 KL720 都走 needsReset → restartBridge
- 註解記錄 trade-off：KL520 connect 時間 ~2s → ~15-20s（macOS），
  Windows 可能 60s+

## HTTP timeout 配套調整
- device_handler.go ConnectDevice timeout 60s → 120s
- Windows worst-case（~65s：Loader reconnect 16s + firmware load 31s +
  reboot 8s + reconnect 5s）留 buffer，避免 504 CONNECT_TIMEOUT

## Bridge 清理
- kneron_bridge.py 清掉中途試驗遺留的 `_host_preproc` 死碼
  （還原成原版 _correct_bbox_for_letterbox）
- 加了 debug log（Inference: sending / parse done / EXCEPTION with
  traceback）保留，未來排查 inference 路徑很有用

## 驗證（function 層）
/tmp/test_bridge.py 三種尺寸全通過：
- 516×640 直式 → 11 detections (person×8, tie×3) latency 308ms
- 1920×1080 横式 → 0 detections（合成圖，正常）
- 512×512 正方 → 0 detections

## 待使用者驗證
- Mac UI 實測：上傳 ~/Downloads/000000000459.jpg 應見 11 個 bbox 精準框住
- Windows 實測 connect 耗時 + timeout 是否足夠
- Linux 實測

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-04-21 01:12:10 +08:00
jim800121chen
d7cddf364b fix(local-tool): 拆 built-in / user data dir — 修預設模型永遠載入 0 個 
M8-10a smoke test 抓到 M1 就潛藏的 P0 latent bug：server 預設 dataDir =
<binary>/data，bundle 內解析成 Contents/Resources/bin/data/（空目錄），
實際 models.json + 8 個 .nef 住在 Contents/Resources/data/（上一層）。
Wails 又傳 --data-dir 成 user home（writable），同樣沒 models.json。
結果任何正式啟動路徑下 /api/models 都回 total: 0，M1-M7 smoke 從沒
跑過這個 endpoint 才漏抓。

修法：把「read-only bundle 內資料」和「writable user 資料」語意拆開。

- 新增 findFirstExisting(candidates, sentinel) helper
- 新增 resolveBuiltInDataDir：①VISIONA_BUNDLE_LIB_DIR/data（AppImage）
  ②<base>/data ③<base>/../data ④<base>/../Resources/data
  ⑤<base>/../lib/visiona-local/data（Linux FHS）。命中條件是
  models.json 存在為 regular file，避開 Wails build artifact 留下的
  空 data/ 目錄
- main() 拆 builtInDataDir（modelRepo + flash.Service 用）與 dataDir
  （custom-models / sentinel / logs 用），職責分明
- flash.NewService 改吃 builtInDataDir — 它要解析 models.json 裡的
  相對路徑 "data/nef/kl520/xxx.nef"，來源是 bundle 不是 user home
- resolveBridgeScript 同步修（同樣的技術債一起清），候選 env var 優先
  + FHS fallback，避免 Linux AppImage 上 kneron_bridge.py 也找不到
- fallback 全 filepath.Abs 化，log.Printf 印嘗試過的路徑清單便於除錯

驗證（build / vet / test + smoke）全綠：
- macOS bundle：/api/models → 15 models ✅
- dev mode（server/ 下 go run）：15 models ✅
- Linux AppImage 模擬 + env var：命中候選 1 ✅
- Linux AppImage 模擬 + 無 env var：命中候選 5（FHS）✅
- 全不命中：log 印完整 tried 清單 + server 不 crash ✅

Reviewer 兩輪通過。第一輪抓到 Linux AppImage 未覆蓋（Major-1）+ 2 Minor
+ 2 Suggestion；第二輪確認全部處理到位、新發現兩項非阻擋風格建議列為
技術債。報告見 .autoflow/05-implementation/reviews/review-m8-10a-*.md。

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-15 20:23:25 +08:00
jim800121chen
8cd5751ce3 feat(local-tool): M8 重構 — Wails 控制台 + 瀏覽器 Web UI（R5 決策） 
依 R5 五輪決策把 visionA-local 從「Wails 內嵌 Next.js」重構為「Wails
本機伺服器控制台 + 瀏覽器 Web UI」模式（類比 Docker Desktop / Ollama）。

程式碼變動
  - M8-1 砍 yt-dlp 全套（後端 resolver / URL handler / 前端 URL tab /
    Makefile vendor / installer / bootstrap / CI workflow，-555 行）
  - M8-2 砍 Mock 模式全套（driver/mock、mock_camera、Settings runtimeMode、
    VISIONA_MOCK 環境變數，-528 行）
  - M8-3 ffmpeg 從 GPL 切換到 LGPL 混合方案：Windows/Linux 用 BtbN 現成
    LGPL binary，macOS 自 build minimal decoder-only 進 git
    （vendor/ffmpeg/macos/ffmpeg 5.7MB + ffprobe 5.6MB，比 GPL 版省 85% 空間）
  - M8-4 Wails Server Controller：state machine、log ring buffer 2000 行、
    preferences.json atomic write、boot-id、Gin SkipPaths、shutdown 7+1 秒、
    notify_*.go 三平台 OS 通知、watchServer 改 Error state 不 os.Exit
  - M8-4b 啟動階段管線 R5-E：6 階段進度 event、20s soft / 60s hard timeout、
    stage 5/6 skip 規則、sentinel file、RestartStartupSequence 5 步驟
  - M8-5 Wails 控制台 vanilla HTML/JS/CSS（9 檔 ~2012 行）取代 M7-B splash：
    state 視覺、log panel、startup progress panel、Stage 6 manual CTA
    pulse、shutdown modal、Settings、Dark Mode、i18n 中英雙語
  - M8-6 上傳影片副檔名擴充（mp4/avi/mov/mpeg/mpg）
  - M8-7 Web UI Server Offline Overlay（role=alertdialog + focus trap +
    wsEverConnected 容錯 + Page Visibility）
  - M8-8 CORS middleware（127.0.0.1/localhost only + suffix attack 防護）+
    ws/origin.go 獨立 WebSocket CheckOrigin 避 package cycle
  - MAJ-4 server:shutdown-imminent WebSocket broadcast 機制
    （/ws/system endpoint + notifyShutdownImminent helper）
  - M8-9 Boot-ID + 瀏覽器 tab 自動重連（sessionStorage loop guard）

品質
  - ~105+ 新 unit test + race detector (-count=2) 全綠
  - 10 個 milestone 全部通過 Reviewer 審查
  - 三方 v2 + v2.1 文件（PRD / Design Spec / TDD）+ 交叉互審紀錄
    收錄在 .autoflow/

交付前待處理（M8-10）
  - 重跑 make payload-macos 把舊 GPL 77MB binary 換成新 LGPL
  - 三平台 end-to-end build 驗證

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-15 17:57:54 +08:00
jim800121chen
83981e5b1b docs(local-tool): progress.md 記錄 M7 Windows 一鍵 build + splash regression 
- 新增 M7-A：Windows 一鍵 build 工具鏈踩坑紀錄（11 項修好）
- 新增 M7-B：splash regression P0 修復（visiona-local/frontend 殘留 wizard → 改為 splash+redirect）
- 補「M1 驗收流程漏看 Wails 視窗內容」到未解決問題，作為後續 M 任務驗收 checklist
- 補 ffmpeg GPL release blocker 到未解決問題清單

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-12 03:35:20 +08:00
jim800121chen
5a8d2797c2 chore(local-tool): rename local_tool → local-tool, add linux/windows bootstrap scripts 
- 統一目錄名為 local-tool（連字號），修正所有文件中殘留的底線版本
- 新增 scripts/bootstrap-linux.sh 與 scripts/bootstrap-windows.ps1
  一鍵安裝依賴（Go/Node/pnpm/Wails/MSYS2）並執行 payload + installer build

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-11 23:23:29 +08:00
jim800121chen
c54f16fca0 Initial commit: visionA monorepo with local-tool subproject 
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>
 2026-04-11 22:10:38 +08:00