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
..
2026-04-11 22:10:38 +08:00
2026-05-25 08:10:46 +08:00
2026-05-25 08:10:46 +08:00
2026-04-11 22:10:38 +08:00
2026-05-25 11:27:36 +08:00