|
|
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 |
|
|
|
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 |
|
|
|
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 |
|
|
|
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 |
|
|
|
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 |
|
