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

92 Commits

This Branch
This Branch
All Branches
Author SHA1 Message Date
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
2d629f3ba2 fix(visionA-backend): DownloadStream 移除 dead ensurePromoted call (Bug #11) 
ADR-016 v0.6 後 visionA download 直接從 converter MinIO 拿 NEF、不需先 promote 推上 FAA；
原 Phase 0.8 / v0.4-v0.5 設計的 ensurePromoted 是 dead call。

stage e2e 證實：
- visionA DownloadStream → f.ensurePromoted → converter.Promote
- converter Promote → faa.putFile (OAuthClientError 401 — converter↔FAA OAuth 鏈獨立 bug)
- converter Promote 回 500、visionA DownloadStream 因 ensurePromoted 失敗回 502
- user 看到下載失敗

修法：flow.go DownloadStream 移除 ensurePromoted call、直接 GetResult（converter MinIO
已在 worker `_upload_output` 寫進 NEF、不需 promote 把 NEF 推 FAA）。

PromoteToModels（line 531）流程仍會呼叫 Promote、這是「加到模型庫」的合理步驟、不動。

驗證：
- 17 packages race -count=3 全綠
- 新 test TestDownloadStream_DoesNotCallPromote 取代舊 TestDownloadStream_PromoteError_Propagation
  （故意把 promoteFunc 設成 t.Fatalf、確保 download path 完全不打 promote）

關聯 follow-up（未在本 commit 修）：
- converter↔FAA OAuth 401 仍是 promote-to-models 流程的 bug、需 converter / MC scope debug
- 但 download 解耦後 user 至少能下載

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-18 16:33:23 +08:00
jim800121chen
78c1343e9a fix(visionA-frontend): conversion init multipart 對齊 converter 規格 — ref_images + model_id 
Phase 0.8b stage e2e 連環 2 個跨層 schema mismatch（5/2 寫 frontend 時對 converter spec 沒驗、5/16 stage e2e 第一次跑通才暴露）。

Bug #5 ref_images field name PHP-style 不對齊
- 現象：converter multer LIMIT_UNEXPECTED_FILE、visionA 透傳 → 400 validation_failed
- 原因：frontend `form.append('ref_images[]', img)`、converter `uploader.fields([{name:'ref_images',...}])`（Express/multer 標準、無 []）
- 修法：frontend `form.append('ref_images', img)`（FormData 多筆同 key、multer 自動收成陣列）

Bug #6 model_id 用 taskName 當值、converter 要 integer
- 現象（修完 Bug #5 後暴露）：converter validator → 400 validation_error 「model_id 必須為非負整數」
- 原因：frontend `args.taskName ?? args.file.name` → 字串 "input" / "yolov5s_test"；
       converter validator (`createJob.js:153-164`) 規定 integer 1-65535（KTC tool 內部 model 編號）
- 修法：新增 `generateConverterModelId()` helper（Math.random 1-65535）、每次 init 自動生成；
       taskName 留給 visionA UX（promote 後 model store 的 name），與 converter model_id 解耦

驗證：
- pnpm test src/lib/api/conversion.test 22/22 pass
- pnpm build 通過
- stage redeploy 兩次（commit ce6a657 後跑出 Bug #5、fix Bug #5 deploy 後跑出 Bug #6、fix Bug #6 已 deploy）

剩餘 e2e 待 user browser 真實上傳 ONNX file 驗證。

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-18 11:21:23 +08:00
jim800121chen
9ebf46112b feat(visionA-frontend): AuthGuard — 未登入自動導 /login + 記住原本 path 
需求：
  使用者未登入訪 protected route（如 /conversion、/devices）→ 卡在空 UI、無 redirect。
  使用者反映「希望未登入直接跳登入頁、登入完跳回原本要去的頁」。

實作：
  - 新增 src/components/auth-guard.tsx：
    * public routes allowlist：/login, /register
    * protected route + user=null + hydrate 完成 → router.replace('/login?next=<path>')
    * hydrate 進行中 → render null（避免閃過 protected UI）
    * buildNextParam helper：排除 public routes 和純 / 路徑

  - 改 src/app/layout.tsx：
    * 用 <Suspense fallback={null}> 包 AuthGuard（next/navigation useSearchParams 規範）
    * AuthGuard 包 AppShell

  - 改 src/app/login/page.tsx：
    * buildLoginUrl 接受 returnTo param、組進 backend `/api/auth/login?return_to=<path>`
    * sanitizeNext helper：對齊 backend oidc_auth.go:382 sanitizeReturnTo（"/" 開頭、無 "//"、無 "://"）
    * 已登入 redirect：從 query ?next= 跳該 path（不再固定 /）

  - 改 src/app/login/login.test.tsx：
    * mock 補 useSearchParams（next/navigation mock 既有只 mock useRouter）

  - backend oidc_auth.go:88 sanitizeReturnTo 已支援 return_to query param、無需改 backend code

驗證：
  - tsc --noEmit 0 errors
  - pnpm lint 0 errors
  - pnpm build 通過（13 pages prerendered）
  - login.test.tsx 12/12 pass
  - stage deploy verify：SSR HTML 含 AuthGuard component bundle

不在本 commit 範圍：
  - .env.stage CORS fix（VISIONA_CORS_ALLOWED_ORIGINS、stage host .env 直接改、不進 git）
  - 5/16 deploy script typo fix（已在 commit fad17dd）
  - converter multipart field mismatch（converter scheduler 跨 repo 處理）

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-18 10:38:16 +08:00
jim800121chen
fad17ddde9 fix(deploy): scripts/deploy-stage-v2.sh — 修兩個全形右括號 typo 卡 shell parsing 
兩處 `\$STAGE_VERSION）` / `\$status）` 含 UTF-8 U+FF09 全形右括號（mojibake / 中文輸入法殘留）；shell 把全形 `）` 當 var name 一部分、解析成 `$STAGE_VERSION）` / `$status）` 變數、unbound variable 中斷 script。

為什麼今天才暴露：5/9 第一次 v2 trial 卡在 build context 上傳階段（VPN 下 docker daemon 大 POST hang）、從沒跑到 line 120 / 196。今天 VPN 順、第一次 build + deploy 整段跑通才撞兩個 typo。

修法：兩處全形 `（）` 改半形 `()`、不影響日誌可讀性。

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-16 23:49:30 +08:00
jim800121chen
9e29ebf767 feat(visionA-backend): Phase 0.8b v0.6 T4 — config FAA 欄位砍 + .env 清 + i18n/godoc polish 
對齊 ADR-016 / conversion.md v0.6.1 §3.1：visionA 端不再需要 FAA 設定（v0.5 T1 加的 FAAAPIKey/FAABaseURL 撤回）。

config 砍除：
- internal/config/config.go: ConversionConfig.FAABaseURL + FAAAPIKey 兩欄位
- internal/config/load.go: VISIONA_FAA_BASE_URL + VISIONA_FAA_API_KEY 兩 env 讀取
- Enabled() 簡化為「ConverterBaseURL + ConverterAPIKey 兩個非空」
- internal/config/load_test.go: TestLoad_ConversionEnabled 從 6 case 簡化為 4 case (all_set / missing_converter_url / missing_converter_key / all_empty)

.env*.example 對齊（3 個檔）:
- visionA-backend/.env.example: 砍 2 個 FAA env row + 註解；header 改「2 欄位啟用」
- .env.stage.example: 同上；VISIONA_CONVERTER_API_KEY 保留 CHANGE_ME_OPENSSL_RAND_HEX_32 placeholder
- .env.dev.example: 註解區塊統一對齊

T3 review polish:
- m-2 internal/api/conversion.go: i18n message map 砍 4 個 dead case (download_token_failed / mc_token_unavailable / idp_misconfigured / idp_unavailable) — 對應 v0.5 mc_token_client 撤回時砍的 sentinel；落入 default「內部錯誤」、行為不變
- m-3 internal/conversion/util.go: hashObjectKey godoc 補「設計約束（重要）」段 + 3 條「不應做的事」（不出現在 response body/header / 不組 URL / 不寫進 user-facing 錯誤訊息）— 明示用途限定於 slog 欄位內、避免 misuse vector
- cmd/api-server/main.go: godoc 對齊 T4 完成狀態

驗證:
- B 層 verification 主動跑（T3 reviewer 接受暫緩、backend 主動跑避免 reviewer 二次要求）：
  * 跨檔 grep: production code 0 functional 命中（殘留全是註解 audit trail / test fixture name）
  * 17 packages race -count=3 全綠
  * 3 個 .env 環境一致性驗證
- go build ./... exit 0
- go test -race -count=3 ./... 17 packages 全綠
- Reviewer 5 軸（v0.6-t4-review）✅ 通過（0 Critical / 0 Major / 2 Minor / 4 Suggestion）

v0.6 對齊改造事實上完工：
- T1 ConverterClient.GetResult method
- T2 flow.go DownloadStream/PromoteToModels 改用 GetResult + e2e endpoint
- T3 faa_client 整檔砍 + ErrFAA* sentinel 清 + s-3/s-4/s-5 必補 + mockFAA regression-only
- T4 config FAA 欄位砍 + .env 清 + i18n/godoc polish

main.go startup log 已是「converter_api_key_set only」、無 FAA 殘留 / 無 tenant_id（T2-T3 已處理）。e2e regression 防護由 mockFAA negative assertion 守住（T3）。

下一步:
- visionA backend 端 ADR-016 對齊完工，等使用者跨 repo 加 converter GET /api/v1/jobs/{id}/result endpoint
- stage redeploy + e2e 完整測試

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-16 19:16:28 +08:00
jim800121chen
6024c294d3 feat(visionA-backend): Phase 0.8b v0.6 T3 — 砍 faa_client + ErrFAA* + s-3/s-4/s-5 
對齊 ADR-016：visionA backend 不再直連 FAA、download 改走 converter GetResult。T3 砍除 v0.5 階段為 FAA delegated token 路線留的 faa_client.go 整檔 + 對應 sentinel + flow / e2e 殘留。

砍除：
- internal/conversion/faa_client.go（整檔）
- internal/conversion/faa_client_test.go（整檔）
- errors.go: ErrFAAFileNotFound + ErrFAAAuthFailed 2 sentinel（+ ErrorCode/HTTPStatus mapping）
- flow.go: faa FAAClient 欄位 + FlowOpts.FAA 必填 + a-h T3 預期清單 godoc
- flow_test.go: flowStubFAA struct + newFlowStubFAA helper + fixture.faa
- internal/api/conversion_test.go: TestConversion_Download_FAAAuthFailed
- cmd/api-server/main.go: NewFAAClient wire + FAA: faaAPIClient field

保留：
- ErrFAAUnavailable（converter promote 仍 PUT FAA、502 透傳路徑需要）
- hashObjectKey helper 搬到 util.go（ownership 仍用）
- e2e mockFAA 精簡為 regression-only（保留 negative assertion: FAA 0 命中）— reviewer 推薦雙層防護

新增（T3 必補，T1/T2 reviewer 累積）：
- s-3 TestDownloadStream_ConverterValidationFailed_Propagation（converter 4xx fallback → ErrValidationFailed 透傳）
- s-4 TestPromoteToModels_StorageError_StreamClosed（instrumented stream wrapper 驗 fd leak 防護）
- s-5 TestParseFilenameFromContentDisposition 9 個 sub-case（3 RFC 5987 + 5 hostile-input + 1 empty quoted）
  發現：Go stdlib 自動 percent-decode RFC 5987 並寫入 params["filename"]、RFC 5987 優先於 ASCII filename

T3 review M-1 修補（commit 內含）：
- internal/api/conversion.go:51,56 godoc + 501 user-facing message 從「FAA_BASE_URL」改為「VISIONA_CONVERTER_BASE_URL + VISIONA_CONVERTER_API_KEY」
- 對齊 ADR-016 visionA 端不再有 FAA 直連設計

驗證:
- B 層 verification 強制跑（reviewer 規定 T3 不接受暫緩）：
  * 跨檔 grep: MC chain 0 / FAA functional refs 0 / TenantID 0
  * API contract test: TestConversionE2E_DownloadStream 6 斷言含 FAA negative
  * 安全 manual review: path traversal / unbounded read / secret in log / error mask 4 項
- go build ./... exit 0
- go test -race -count=3 ./... 17 packages 全綠
- Reviewer 5 軸（v0.6-t3-review）⚠️→ ✅ 通過（M-1 已修）

a-h 8 條清單 100% 達成（逐條 grep 驗收）；mockFAA 選方案 1（保留 + negative assertion）— 雙層防護。

下一步:
- T4 砍 ConversionConfig.FAAAPIKey/FAABaseURL + load.go env 讀取 + .env*.example + m-2 i18n dead case 一併
- T5 main.go startup log 整理 + e2e regression 防護

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-16 18:56:01 +08:00
jim800121chen
ce6a657df4 feat(visionA-backend): Phase 0.8b v0.6 對齊 — T1+T2 download 改走 converter.GetResult 
對齊 ADR-016：visionA download 不再經 FAA delegated token、改用 converter GET /api/v1/jobs/{id}/result 中轉。

T1 — converter_client.go 加 GetResult method:
- 新增 GetResult(ctx, jobID) (io.ReadCloser, *DownloadMetadata, error)
- 新增 ErrResultExpired sentinel + ErrorCode("result_expired") + HTTPStatus 410 mapping
- 獨立 StreamHTTPClient (無 timeout / dial+response header timeout) 給 streaming 大檔
- doStreamWithRetry / doStreamOnce / mapGetResultError / resultRetryBackoff helpers
- parseFilenameFromContentDisposition (RFC 5987 quoted/unquoted/encoded)
- 9 個 GetResult test + 6 個 parseFilename sub-test
- Reviewer 0 Critical / 0 Major / 3 Minor (M-1/M-2/M-3 全部 T2 順手修)

T2 — flow.go + e2e 改造:
- DownloadStream / PromoteToModels 移除 f.faa.GetFile(...) 改 f.converter.GetResult(ctx, jobID)
- filename 仍由 defaultDownloadFilename(cj) 覆寫 (visionA source-of-truth)
- 8 個 flow_test 既有 test 改寫 + 2 個改名 (FAA → Converter) + 2 個 410 透傳 test 新增
- e2e mock converter 加 GET /api/v1/jobs/{id}/result endpoint + 3 helper + 6 斷言更新 (含 negative: FAA 0 命中 / converter /result ≥1 命中)
- T1 reviewer 3 個 Minor 全處理 (mapGetResultError 設計取捨 godoc / 指數退避→線性退避 / 401+403 mask 驗證)
- 保留 faa FAAClient 欄位 + FlowOpts.FAA 必填 (T3 才砍 faa_client.go 整檔)

T2 修補 (architect + backend 平行)：
- M-1 conversion.go Service interface DownloadStream/PromoteToModels godoc 對齊 v0.6 (從 flow.go layer 搬上來)
- M-2 conversion.md v0.6 → v0.6.1 — §2.5 ensurePromoted cache 描述「sync.Map cache」改為「Phase 0.8 簡化 (不實作 cache)」+ 4 簡化理由 + 3 Phase 1+ 升級選項 (in-memory / DB / model store 推論)；連動修改 line 169 / 300 / 1187 cross-reference
- 3 Minor + 2 Suggestion 順手做 (resultRetryBaseDelay godoc / fixture 註解過渡狀態 / e2e route table 4→5 / flow.go struct T3 預期清單 / e2e negative assertion 強化)

驗證:
- go build ./... exit 0
- go test -race -count=3 ./... 17 packages 全綠
- Reviewer 5 軸 (v0.6-t1-review + v0.6-t2-review + v0.6-t2-fix-review) 全 ✅ 通過

對齊 ADR-016 §1 / conversion.md v0.6.1 §2.5 §4.1 / api-conversion.md v0.6 §4 / oidc-tdd.md v0.4 §13.1.3

下一步:
- T3 砍 faa_client.go + faa_client_test.go + 對應 ErrFAA* sentinel (B 層強制跑 / s-3/s-4/s-5 必補)
- T4 砍 ConversionConfig FAA* 欄位 + main.go wire 點 + .env*.example
- T5 main.go wire 點全切 + e2e regression 防護

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-16 15:09:20 +08:00
jim800121chen
dab13ed984 docs(autoflow): ADR-016 — visionA download 改走 converter GetResult，撤回 FAA delegated token 鏈 
致命發現（grep MC + FAA source 確認）：
- MC source 沒有 issue delegated download token endpoint
- MC source 沒有 validate delegated download token endpoint
- FAA MemberCenterDelegatedDownloadTokenValidator.cs 假設的 MC introspection endpoint 不存在
- ADR-014 §2 從 5/2 寫完到現在這條鏈一直是斷的、只是因為從未實際 e2e 跑通過所以沒被發現

使用者拍板硬約束：不動 MC + 不動 FAA

新增 ADR-016：
- visionA download 改用 converter GET /api/v1/jobs/{id}/result（新 endpoint）
- visionA backend 用既有 ConverterAPIKey 認證（不需新增 secret）
- 維持 T4 已實作的 stream proxy 結構（io.CopyN + Content-Disposition + size cap）
- promote 仍 PUT FAA（converter 內部用自己的 OAuth、與 visionA 無關）
- 不需動 MC + FAA + warrenchen
- 6 個替代方案逐一說明排除理由

修訂既有文件：
- ADR-014 v1.1 → v1.2：§2 download flow 標註被 ADR-016 部分 supersede
- ADR-015 v2.0 → v2.1：§2 visionA → FAA delegated token 設計（v2.0 從 v1.x 撤回的設計）再次撤回；§9 env 表撤回 v2.0 加回的 OIDC ServiceClient* / TenantID / FAABaseURL；visionA 端 server-to-server 只剩 ConverterAPIKey 一把
- conversion.md v0.5 → v0.6：§1 sequence diagram 重畫（移除 MC node）、§2 模組設計（mc_token_client.go 整檔刪除確認、faa_client.go 改名 converter_result_client.go）、§3.2 visionA → FAA 整段標撤回、§4.1 download handler 改 converter.GetResult、§6 錯誤碼撤回 mc/faa 三個 code 加 result_not_found / result_expired
- api-conversion.md v0.5 → v0.6：檔頭 Auth 段落改寫、§4 download endpoint 改述、error code 表撤回 mc_token_unavailable / download_token_failed
- oidc-tdd.md v0.3 → v0.4：§13.1 環境變數表 OIDC ServiceClient* / TenantID / FAABaseURL 從「重新啟用」改回「再次廢棄」、§13.1.1 stage env 範例移除 service client / tenant_id / FAA URL、§13.1.3 改寫為「v0.4 單線設計」說明

整體影響：
- 不需復活 mc_token_client.go（commit 86b7175 砍除狀態維持）
- 不需復活 OIDCConfig.ServiceClientID/Secret/TenantID（commit 86b7175 移除狀態維持）
- visionA backend faa_client.go 要改名為 converter_result_client.go、改呼叫 converter.GetResult
- visionA backend flow.go DownloadStream / PromoteToModels 改用 converter.GetResult
- jimchen 跨 repo 任務：converter scheduler 加 GET /api/v1/jobs/{id}/result endpoint

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-16 12:30:46 +08:00
jim800121chen
86b7175649 feat(visionA-backend): Phase 0.8b 步驟 2 — visionA → converter / FAA 改 API key 認證 
對齊 ADR-015：visionA backend 從 OAuth client_credentials 改 pre-shared API key 服務間認證。Phase 0.8 stage e2e 撞 4 個 blocker（MC scope 沒註冊 / converter image 舊版 / converter 缺 env / FAA 不確定）後，使用者拍板 1:1 internal trust 用 OAuth 過度設計，改 API key。

實作（5 個增量 task，T1-T5 全綠 + Reviewer 5 輪 + final cross-task review）：

T1 config + env：
- ConversionConfig 新增 ConverterAPIKey / FAAAPIKey 欄位
- Enabled() 改判定 4 欄位齊全（含兩個 API key）
- .env*.example 移除 OIDC service client / OIDC tenant / FAA delegated TTL env、新增 API key env
- TenantID / DelegatedTTLSeconds T1 暫留、T5 整批清

T2 client 改造：
- converter_client / faa_client 移除 MCTokenClient 依賴
- 直接讀 cfg.Conversion.{Converter,FAA}APIKey、set Authorization: Bearer <key>
- NewConverterClient / NewFAAClient APIKey 為空時 panic（fail-fast，對齊 ADR-015 §3.5.3 #1）
- 新增 ErrConverterAuthFailed / ErrFAAAuthFailed sentinel
- 對外 mask 成 converter_unavailable / faa_unavailable（不洩漏 401 細節，對齊 ADR-015 §3.5.3 #3）

T3 砍 mc_token_client：
- mc_token_client.go (624 行) + mc_token_client_test.go (864 行) 整檔砍
- 砍 5 個僅 mc_token_client 用的 sentinel（ErrServiceClientUnauthorized / ErrMCTokenUnavailable / ErrIDPMisconfigured / ErrIDPUnavailable / ErrDownloadTokenFailed）
- helper（truncate / silentLogger）搬到 util.go / testing_helpers_test.go

T4 flow + handler stream proxy：
- Service interface DownloadRedirectURL → DownloadStream(ctx) (io.ReadCloser, *DownloadMetadata, error)
- flow.DownloadStream 用 faa.GetFile 直接 stream NEF binary（取代 MC delegated token + 302）
- handler conversionDownloadHandler 改 io.Copy + Content-Type/Disposition/Cache-Control header
- 新增 sanitizeDownloadFilename helper 防 HTTP header injection
- 跨 package handler test (conversion_test.go) 改測 ErrFAAUnavailable + 補 *_AuthFailed 對稱 test

T5 wire 切換 + cleanup：
- main.go 砍 mcTokenClient wire、改 APIKey 注入、startup log 用 *_api_key_set boolean（不印 key）
- ConverterClient/FAAClient struct Tokens 欄位移除
- mc_token_stub.go (T4 過渡期) 整檔砍
- ConversionConfig TenantID / DelegatedTTLSeconds 欄位移除
- e2e_test.go TestConversionE2E_Download302Redirect 改寫為 TestConversionE2E_DownloadStream
- 補 MaxDownloadStreamBytes = 1 GiB size cap（io.CopyN，T4 reviewer Minor M-1）
- escapeObjectKeyPath Phase 1+ 預留 godoc + //nolint:unused（T4 reviewer Minor M-2）
- conversion.md §4.1 line 502 filename 來源描述歧義修訂（T4 reviewer Minor M-3，由 architect 處理）
- conversion_e2e_test.go 檔頭 docstring 更新（final reviewer Minor #1）

驗證：
- go build ./... exit 0
- go test -race -count=3 ./... 17 packages 全綠
- ADR-015 §6 砍除清單 100% cover（reviewer 獨立 grep 確認 MC chain / TenantID / DelegatedTTLSeconds 全清）
- ADR-015 §3.5.3 部署檢查清單 visionA 範圍 4/4 達成（fail-fast / mask / 不印 token / placeholder env）

不動：
- OIDCConfig.ServiceClientID/Secret 欄位保留（使用者拍板 backward compat）
- user login OIDC 完全不動

下一步：
- 步驟 4 — converter scheduler middleware 改 API key（jimchen 跨 repo，ADR-015 §3.5.1 Go snippet）
- 步驟 5 — FAA middleware 改 API key（warrenchen 跨 repo，ADR-015 §3.5.2 C# snippet）
- 步驟 6 — stage redeploy + e2e 完整測試

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-15 09:45:45 +08:00
jim800121chen
b9c228df4f docs(autoflow): Phase 0.8b ADR-015 + TDD 修訂 — server-to-server 改 API key 
新增 ADR-015：visionA → converter / FAA 從 OAuth client_credentials 改 pre-shared API key
- §1-§9 決策、4 個替代方案、後果分析、合規性
- §3.5 reference middleware snippet（Go converter + C# FAA 兩種寫法）+ 部署檢查清單
- 部分 supersede ADR-014 §5/§6/§7（service token / scope / MC retry rows）
- 觸發背景：Phase 0.8 stage e2e 撞 4 個 blocker，1:1 internal trust 用 OAuth client_credentials 過度設計

3 份 TDD 配合修訂：
- conversion.md：重寫 §3 服務間認證、§4.1 download 退回 server-side stream proxy、刪 §2.4 mc_token_client、§5.3 補 cancel 鏈、§10.3 改 pre-shared key 保護
- api-conversion.md：error code idp_unavailable → converter_auth_failed/faa_auth_failed；download response 從 302 redirect 改 200 + Content-Disposition: attachment + NEF stream
- oidc-tdd.md：標廢棄 service client env 兩 row、新增 API key env 兩 row、§13.1.3 user login 與 server-to-server 脫鉤說明、v0.2 changelog

未動：source code（步驟 2 由 backend agent 處理；範圍含 mc_token_client 刪除、TenantID 移除、API key 改造，含 test files）

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-15 06:39:45 +08:00
jim800121chen
700b7b08ba chore(stage): 新增 v2 deploy 流程（remote build via DOCKER_HOST） 
v1 (deploy-stage.sh) 走 docker save | gzip | docker load 模式，需要把 81MB
tarball 一次性 POST 到 stage docker daemon /images/load API。5/4 / 5/9 兩次
驗證 VPN 下 docker daemon 對單一大 POST hang（卡 30+ 分鐘 / i/o timeout），
公司網段直連才可靠。

v2 仿 edge-ai-platform/scripts/deploy-docker.sh 改用 DOCKER_HOST=stage
docker build — multi-stage build 完全在 stage daemon 上執行：
- 跨網路只傳 build context（~44 MB streaming，VPN 友善）
- alpine base / nodejs / go mod / pnpm install 都由 stage daemon 自己 pull
- layer cache 留在 stage daemon，後續 incremental build 更快
- 5/9 VPN 下實測 work：first build ~3min、redeploy(layer cache) ~10s

連帶修：
- pnpm-workspace.yaml: 加 onlyBuiltDependencies (sharp / unrs-resolver /
  @tailwindcss/oxide / esbuild) — pnpm 10 預設拒跑依賴 build script、
  乾淨環境第一次 install 撞 ERR_PNPM_IGNORED_BUILDS
- package.json: 加 packageManager: pnpm@10.30.1 — 鎖 pnpm 版本，corepack
  在 stage daemon 第一次跑時不會拉到最新 pnpm 11（行為差異）
- Dockerfile.stage: COPY pnpm-workspace.yaml 進 builder context、否則
  容器內 install 看不到 trust list

v1 (deploy-stage.sh) 保留作為公司網段直連備援；v2 是 VPN / 預設模式。
 2026-05-11 10:35:21 +08:00
jim800121chen
fb7da5d180 chore(autoflow): migrate .autoflow/ 共享層文件至 docs/autoflow/ 
依 autoflow-agent workspace v2 設計把 PRD / 設計 / 架構 / 交付類
共享文件從個人層 .autoflow/（ignored）搬到 docs/autoflow/（進 git），
讓團隊可共享產品與架構文件，個人層只留 progress / review / testing 等
per-branch 筆記。

- 02-prd/        21 個檔（PRD、features、market-analysis 等）
- 03-design/     18 個檔（design-spec、wireframes、flows 等）
- 04-architecture/ 31 個檔（TDD、design-doc、ADR×14、API 規格等）
- 07-delivery/   3 個檔（project-summary、phase-0.6-handover、stage-deployment-setup）

合計 73 檔。原檔已從 .autoflow/ 移除（migration 工具執行 git mv，
但因 .autoflow/ 在 .gitignore 中、git 將此操作視為新增、無 rename history）。
 2026-05-04 16:55:55 +08:00
jim800121chen
7575d4f8ee chore(stage): 補 Phase 0.8 conversion 環境變數設定範例 
- VISIONA_CONVERTER_BASE_URL / VISIONA_FAA_BASE_URL（轉檔服務端點）
- VISIONA_SERVICE_CLIENT_ID / VISIONA_SERVICE_CLIENT_SECRET（service token）
- 對齊 .autoflow/04-architecture/conversion.md §5.3 啟用判定邏輯
 2026-05-04 16:55:17 +08:00
jim800121chen
e02059eff2 feat(visionA-frontend): Phase 0.8 conversion UI — sidebar tab + 6 view + 5 e2e flow tests 
Phase 0.8 對應後端轉檔功能的 frontend UI。完整 state machine（idle / uploading /
queued / running / succeeded / failed / expired）+ XHR upload progress + polling +
half-auto result handling（加到模型庫 / 下載）。

新增 src/app/conversion/（11 元件 + 12 test files，~5,000 行 prod+test，310/310 tests 全綠）：

- page.tsx：state router（mount → bootstrap → 依 store.uiState 切換 view）+ toast on
  store.error（aborted / active_job_exists 不 toast，避免雙重提示）
- IdleForm.tsx + FileDropzone.tsx + ChipSelector.tsx：上傳表單（拖放 + .onnx/.tflite
  format 驗證 + 500MB 大小限制 + KL520/630/720/730 chip 選擇 + ref images ≤100×10MB）
- UploadingView.tsx：XHR upload progress 0-100% + EWMA ETA（alpha=0.3 平滑，<5s 顯示
  「即將完成」避抖動）+ beforeunload warning + AlertDialog 取消
- ProcessingView.tsx：StageIndicator 三段式（解析模型 → 量化編譯 → 編譯 NEF）+
  Progress bar 三模式（queued / determinate / indeterminate）+ tab title `(轉檔中)` 防疊加 +
  409 active_job_exists banner（switchedFromActiveJob flag）
- SuccessView.tsx + PromoteDialog.tsx：兩按鈕（加到模型庫 / 下載）視覺平衡不暗示預設答案 +
  7 天 expires_at 倒數（mount 時 setTimeout 鎖過期那刻 + 60s tick）+ PromoteDialog 單欄位
  name 驗證（≤100 字元 / 無 /\\）+ spinner-during-close 阻擋 + 409 already_imported 特殊
  訊息 + toast.success router.push 跳模型清單
- FailedView.tsx：5 個 known error code 翻譯（UNSUPPORTED_FORMAT / INVALID_CHECKSUM /
  QUANTIZATION_FAILED / MODEL_TOO_LARGE / QUOTA_EXCEEDED）+ unknown fallback +
  3 個建議解決方法 + Job ID 前 8 字元（供回報）+ 「重新開始」
- ExpiredView.tsx：橘色 hero（過期不 alarming）+ source/chip 摘要 + 「重新轉檔」→
  store.reset()

新增 src/stores/conversion-store.ts（Zustand store + 29 tests）：
- 7 個 UI state machine（不允許跳階段）
- recursive setTimeout polling（running 5s / queued 10s / 5xx 指數退避 cap 30s）+
  visibilitychange 暫停/恢復
- 不持久化 jobId（純靠 backend getActiveConversion() lazy rebuild ownership）
- AbortController 防 stale request + 取消上傳
- switchedFromActiveJob flag（409 自動切到既存 job + UI 顯示 banner）
- formDraft（chip / taskName 提到 store，failed→idle 後保留設定，file picker 重選；
  File 物件不能序列化只留 local）

新增 src/lib/api/conversion.ts + types/conversion.ts（5 client 函式 + 22 tests）：
- initConversion：XHR multipart + onUploadProgress + AbortSignal
- getActiveConversion / getConversion / promoteConversionToModels：標準 fetch
- getConversionDownloadURL：純函式，回 `/api/conversion/{job_id}/download` 給 anchor
  download 觸發（server-side 302 → FAA，token 不過 frontend JS）
- ConversionAPIError(status, code, message, requestId?)，code 統一全小寫對齊
  conversion.error.<code> i18n key 命名

新增 src/lib/utils/eta.ts（EWMA 演算法純函式 + 19 tests）：抽出 smoothSpeed /
estimateRemainingSeconds / instantSpeedBytesPerSec / computeEtaUpdate（test 友善）。

新增 src/app/conversion/e2e-conversion-flow.test.tsx（5 e2e flow tests）：
- happy path .onnx + KL720 + 0 ref images（idle → upload → polling → succeeded → 加到模型庫）
- variant 5 ref images
- upload fail → retry（form 設定保留）
- polling 5xx 指數退避 → 恢復繼續
- expired job → ExpiredView → 重新轉檔

修改 sidebar.tsx：左側 nav 新增「轉檔」tab（Wand2 icon，模型庫之後）。
修改 i18n 字典：新增 ~150 個 conversion.* keys（中英雙語對齊）。

PRD §9 14 條功能驗收條件全達成（4 條整合驗收等 stage 部署）。

驗證：pnpm lint / test (310/310) / build 全綠。

對齊文件：
- .autoflow/02-prd/features/feature-converter-integration.md
- .autoflow/03-design/wireframes/wireframe-conversion.md
- .autoflow/03-design/flows/flow-conversion.md
- .autoflow/04-architecture/api/api-conversion.md

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-04 13:56:54 +08:00
jim800121chen
1231bf0ed2 feat(visionA-backend): Phase 0.8 conversion package — 5 endpoint + 8 個內部模組 
Phase 0.8 把 kneron_model_converter 的轉檔功能整合進 visionA Cloud。
visionA backend 當 streaming proxy（upload）+ delegated download token broker（download）+
ownership trust boundary，converter / FAA / MC 三方零修改。

新增 internal/conversion/ 套件（8 個檔，~10,000 行 prod+test，117+ test cases，race -count=3 全綠）：

- conversion.go：Service interface 5 method、Job/PromoteResult/InitJobInput types
- errors.go：13+ sentinel errors + ErrorCode/HTTPStatus mapping，對齊 conversion.md §6
- mc_token_client.go：service-to-service token (client_credentials grant) + DCL cache
  （exp - 15s 重取，per-scope cache），IssueDelegatedDownload(MC delegated download token)
  錯誤分 idp_misconfigured (4xx) / idp_unavailable (5xx) / download_token_failed / mc_token_unavailable
- converter_client.go：對 converter scheduler 4 method（InitJob multipart streaming /
  GetJob / Promote / ListInProgressJobs），InitJob 不 retry 5xx（streaming body 無法 replay）
- faa_client.go：對 FAA GET /files/{key} server-to-server pull，Phase A retry（GET 無 body
  可 replay）對齊 §9.1 retry 矩陣，streaming io.ReadCloser 透傳避 OOM
- ownership.go：in-memory job_id → user_id map + per-user mutex 防 thundering herd lazy rebuild
  （不同 user 平行 fetch，同 user 100 caller 收斂成 1 次），visionA 重啟靠 converter
  ListInProgressJobs(user) 重建
- flow.go：Service interface 整合層（5 method 串接 converter/FAA/MC/ownership）
  - InitJob 用 io.Pipe + multipart.Reader/Writer 重組 streaming proxy（黑名單 client user_id
    + 灌入 OIDC sub）
  - DownloadRedirectURL 自動觸發 promote（spec §1 Stage 3b），用 ensurePromoted helper
  - PromoteToModels 冪等（modelStore.FindBySourceJobID 為 source-of-truth）
  - OwnershipMismatch → ErrJobNotFound 不 forbidden（§7.2 防枚舉）
  - storage / modelStore 失敗包 ErrStorageUnavailable / ErrModelStoreUnavailable
    （視為 visionA 自身 500 而非 502 gateway，SRE alarm 才打對 team）

新增 internal/api/conversion.go（5 endpoint handler + main.go wire）：
- POST /api/conversion/init（multipart streaming proxy，不呼叫 c.MultipartForm()）
- GET  /api/conversion/active（lazy rebuild ownership）
- GET  /api/conversion/{job_id}（poll status）
- POST /api/conversion/{job_id}/promote-to-models（FAA pull → models 三段式）
- GET  /api/conversion/{job_id}/download（server-side HTTP 302 → FAA，token 不過 frontend
  JS，仿 FAA TestSite DownloadFileDirect pattern；Cache-Control: no-store）

5 個 endpoint 全部走 OIDC AuthMiddleware；user_id 從 cookie session 灌（trust boundary），
從不接受 client multipart form / JSON / query 的 user_id。
TestAllAPIEndpointsRequire401WithoutCookie 自動覆蓋新 5 endpoint regression 防呆。

新增 cmd/api-server/conversion_e2e_test.go（4 個 e2e 場景）：
- TestConversionE2E_StreamingProxy（10MB body + trust boundary regression）
- TestConversionE2E_LazyRebuildAfterRestart（visionA 重啟仍能 /active）
- TestConversionE2E_Download302Redirect（驗 302 + Location header + token 不在 body）
- TestConversionE2E_ActiveJobConflict（409 + active_job 詳情）

修改 internal/config/{config,load}.go：新增 ConversionConfig 5 欄位
（ConverterBaseURL / FAABaseURL / TenantID / ServiceClientID / ServiceClientSecret）+
Enabled() helper（雙非空判定）。
修改 cmd/api-server/main.go：條件 wire（cfg.Conversion.Enabled() 為 true 才建 client + Service；
否則 Deps.Conversion=nil，handler 自動回 501）。
修改 .env.example：新增 Phase 0.8 區塊註解。
新增 cmd/api-server/conversion_adapters.go：narrow interface adapter（接既有
internal/model.Repository / internal/storage.Store → conversion.ModelStore / Storage，避免 import cycle）。

驗證：go test -race -count=3 ./... 17 packages 全綠 / go vet 0 warning / go build 成功。

對齊文件：
- .autoflow/04-architecture/adr/adr-014-conversion-integration.md
- .autoflow/04-architecture/conversion.md (TDD)
- .autoflow/04-architecture/api/api-conversion.md
- .autoflow/02-prd/features/feature-converter-integration.md
- .autoflow/03-design/wireframes/wireframe-conversion.md
- .autoflow/03-design/flows/flow-conversion.md

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-04 13:56:07 +08:00
jim800121chen
72672972c8 chore(local-agent): 從 git 移除誤 commit 的 wails build binary（10MB Mach-O） 
3f0175f commit local-agent/ 時連帶把 wails build 出的執行檔
local-agent/visiona-agent/visiona-agent（10MB Mach-O 64-bit x86_64）
一起進 git，違反「build artifact 不進 git」原則：

- 可重新產生：source 已在 git，clone 後 wails build 即可
- 平台特定：x86_64 macOS 執行檔對其他平台無用
- repo 變胖：git history 永遠保留這 10MB

修法：
- git rm --cached（保留磁碟上檔案，下次 wails build 還會用）
- local-agent/.gitignore 補 /visiona-agent/visiona-agent 防再犯

注意：3f0175f 的 history 仍含此 binary，徹底清除需 git filter-repo
（local-only repo、未 push、暫不處理）。

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-01 18:29:22 +08:00
jim800121chen
d9d8f03fba chore: visionA Cloud monorepo 根目錄設定（Makefile + README + .gitignore） 
- Makefile：top-level convenience targets（呼叫各子專案的 Makefile）
- README.md：擴充為 monorepo 索引（local-tool / visionA-backend /
  visionA-frontend / local-agent 各組件說明 + dev-with-mc / stage 部署 quickstart）
- .gitignore：
  - .env.dev / .env.dev.generated / .env.stage 排除（dev 與 stage 環境檔不進 git）
  - .autoflow/ 整包 ignore（個人/per-branch 工作目錄；progress.md 與 review 報告
    皆 ignored；共享產品文件已搬到 docs/ 進 git）
  - graphify-out/ 排除

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-01 11:22:57 +08:00
jim800121chen
eb66a7287a feat(deploy): visionA Cloud dev / stage docker compose + Caddy/nginx + 部署腳本 
新增雲端版部署設定（Phase 0.6 dev + Phase 0.7 stage 分兩套）：

dev 環境（docker-compose.dev.yml）：
- 5 service all-in-one（postgres + member-center + visionA-backend + frontend + Caddy）
- Caddy 自動 HTTPS for localhost
- .env.dev.example 範本（使用者拷出 .env.dev 後 docker compose up -d）
- Makefile dev-with-mc 9 個 target

stage 環境（docker-compose.stage.yml + docker/Dockerfile.stage）：
- multi-stage build（node22 frontend + go1.26 backend × 2 + nginx-alpine runtime）
  最終 image 319 MB，含 nginx + nodejs + tini + bash
- entrypoint.stage.sh 4 process 共命運（nginx + api-server + remote-proxy +
  next.js standalone）用 wait -n + SIGTERM trap
- nginx.stage.conf：白名單 server_name stage-9527.innovedus.com + 444 default_server
  + /healthz 例外（127.0.0.0/8 only）+ /api/ 與 /storage/ 強制 no-store
  + /tunnel/connect WS upgrade + 100M body / 3600s timeout
- 對外 mapping 0.0.0.0:9527:80（公司 host nginx 在外層處理 HTTPS termination
  — Let's Encrypt stage-9527.innovedus.com 自動續簽）
- named volume visiona-data（不用 bind mount，因 stage docker daemon 在 host root
  無 mkdir 權限）

部署腳本（scripts/deploy-stage.sh）：
- 仿 edge-ai-platform/scripts/deploy-docker.sh 早期 save/load 模式
- 為什麼不用 internal registry：公司 192.168.0.130:5000 開了 auth、無帳密
- 流程：buildx --load → docker save | gzip → DOCKER_HOST docker load → compose up
- 含 --rollback &lt;tag&gt; / --skip-build / --no-push / --skip-deploy 選項
- timestamp + git SHA tag 留 rollback 餘地

文件（docs/）：
- DEV-SETUP.md：dev 環境一鍵起步驟
- SMOKE-TEST.md：手動煙測 checklist（OIDC flow / pairing / tunnel）
- STAGE-DEPLOY.md：stage 完整手冊（架構圖 / 環境前置 / 部署 step / rollback /
  7 種故障排除 / 緊急救回 POC）

.env.stage.example 對齊 backend A1 改造：
- VISIONA_OIDC_CLIENT_SECRET 留空（PKCE-only public client）
- VISIONA_OIDC_SERVICE_CLIENT_ID/_SECRET 留空（Phase 1 預留鉤子）
- 所有 secret 用 placeholder（CHANGE_ME_OPENSSL_RAND_HEX_32）

.dockerignore：避免 node_modules / .next / .git 等進 build context

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-01 11:22:44 +08:00
jim800121chen
3f0175f1a9 feat(local-agent): Phase 0.5 visionA Agent — Wails 桌面 + tunnel client + 配對 UI 
從 local-tool 複製出獨立的「visionA Agent」桌面應用（A3 純橋樑：
tunnel client + 配對 UI + 設定，不開 HTTP port、不做本機裝置/推論 UI）。
Bundle ID 與 local-tool 不同（com.innovedus.visiona-agent vs visiona-local），
雙 app 可共存。fork 後不主動 sync，需要時手動 cherry-pick。

Backend / Wails Go（AB1-AB13）：
- internal/tunnel：6 狀態機（Idle/Connecting/Connected/Reconnecting/Failed/Stopped）
  + Pair/Unpair/Reconnect/Disconnect binding + ClientHooks event
- internal/auth：encrypted file token store（AES-GCM + scrypt + machineID
  fallback salt + 13 tests）
- internal/config：YAML validation + atomic write + 11 tests
- internal/log：ring buffer + ExportLog 升級 zip
- visionA-backend /api/pairing/exchange：SessionTokenStore + 17 new tests
- 三平台 build 驗證（macOS DMG 160 MB / Windows EXE / Linux AppImage）
- end-to-end 5 milestone 全綠（pairing → tunnel → forward → reuse 防護
  → tunnel drop failover）

Frontend / Next.js（AF1-AF7，沿用 visionA-frontend 基礎）：
- AppShell + Header + TabNav（StatusView / PairView / SettingsView 三 tab）
- ConnectionStatusBadge 5 種狀態
- TokenInput regex 驗證 + 7 種錯誤 + 0.5s auto-switch 到狀態頁
- 設定頁 4 區塊（含重新配對 AlertDialog）
- agent-api.ts 封裝 Wails bindings（mock/real 雙實作）+ 90 tests

Phase 0.7 review-driven fix（Round 2）：
- A1 Session fixation 防護（RotateSessionID）
- A3 mock pairing 預設改 false（必須明確 opt-in）+ startup log
- A4 Pair 失敗後 state 清理矩陣（exchange/Save/Start fail 各自終態）
- A5 Pair/Unpair/Reconnect lifecycleMu + 50 goroutine race test
- F1 重新配對次按鈕 / F2 PairView Esc cancel / F3 Wails BrowserOpenURL
  / F4 Settings draft 持久 + 未儲存 badge

驗證：agent backend go test -race -count=3 ./... 4 packages 全綠 /
agent frontend pnpm test 119 tests 全綠

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-01 11:22:01 +08:00
jim800121chen
99dea42239 feat(visionA-frontend): Phase 0 → 0.7 雲端前端（Next.js + OIDC redirect 流程） 
visionA 雲端版前端 — 沿用 local-tool 既有 UI（原則 4：先抄 local-tool）+
新增雲端特有的登入 / 配對 / 設定流程，含以下整合階段：

- Phase 0：13 頁 + 30+ 元件 + 雛形 banner
  - dashboard / devices / models / workspace / clusters / settings 等頁
  - AppShell + Sidebar + Header + tokens + i18n（中英雙語 96 keys）
  - API client + 5 stores + 3 hooks
- Phase 0.6：OIDC redirect 改造
  - login 頁改為 OIDC redirect（`window.location.href = /api/auth/login`）
  - register 改說明頁、account 改唯讀（user 資料來源是 MC）
  - api client 改 cookie session（credentials: include）+ 完全清掉 localStorage
- Phase 0.7：stage 部署 + nil guard
  - getApiBaseUrl() 修：browser 環境視為 same-origin（與 login 頁一致）
  - login 頁加「已登入 → router.replace('/')」effect
  - User type email/name 改 optional（MC id_token 不一定回 email/name claim）
  - header.tsx UserMenu displayName 4 層 fallback：name → email → id → i18n
  - 雛形 banner 文案更新（已接 Innovedus 帳號中心）+ 版號 Phase 0.7

驗證：pnpm lint / test (125/125) / build 全綠

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-01 11:21:36 +08:00
jim800121chen
22f0837ba8 feat(visionA-backend): Phase 0 → 0.7 雲端後端（雙 binary + OIDC BFF + stage 部署） 
從 edge-ai-platform POC 轉為正式產品的雲端後端，含以下整合階段：

- Phase 0：雛形骨架 — `cmd/api-server` (REST :3721) + `cmd/remote-proxy`
  (tunnel :3800 / internal :3801) 雙 binary 共用 internal/，沿用 POC 的
  WebSocket+yamux tunnel 協定但解耦 relay 與 API
- Phase 0.6：OIDC BFF 接 Innovedus Member Center
  - internal/oidc package（coreos/go-oidc + PKCE S256 + state + nonce）
  - internal/usersession package（HMAC-SHA256 cookie + RotateSessionID
    防 session fixation, OWASP ASVS V3.2.1）
  - 4 個 OIDC handler（/api/auth/login｜callback｜me｜logout）+ AuthMiddleware
  - 完全拔除 StaticAuthProvider，OIDC 是唯一認證路徑
  - 9 個 ADR（含 ADR-010 BFF / ADR-011 取代 static auth /
    ADR-012 pending session shared cookie / ADR-013 PKCE-only public client）
- Phase 0.7：A1 改造 + security audit 修復
  - OIDC ClientSecret 變選填，支援 stage MC 的 public PKCE-only client
    （AuthStyleInParams 強制 token endpoint 不送 client_secret）
  - 預留 ServiceClient* 欄位給未來 client_credentials grant
  - 移除 13+ 處 resolveUserID(uc, StaticUserID) fallback 改 strict mode
    （Audit C1：multi-tenant 隔離破口）
  - Pairing exchange MarkUsed 失敗 abort + revoke session token（Audit M3）
  - 新增 all_endpoints_require_auth_test 整合測試（51 endpoint × 401）

驗證：go test -race -count=3 ./... 17 packages 全綠 / go vet 0 warning

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-01 11:21:20 +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
c1d2e2ddaa feat(local-tool): macOS DMG 美化（create-dmg 背景圖 + Applications 捷徑） 
需求：Mac 端 installer 體驗類比 Windows .exe — 進 DMG 就看到漂亮的視窗
背景 + 拖到 Applications 的視覺引導。

實作：
- installer/macos/ 新資料夾
  - make-dmg-background.py：動態生成 640×400 深色背景，配色對齊 Wails
    控制台 splash（#111827→#0B0F19 漸層 + #38BDF8 accent）
  - background.png + background@2x.png（1x + 2x Retina）
- Makefile dmg 拆三 target：
  - dmg：auto-detect，有 create-dmg 走 fancy，沒有 fallback plain（CI 無痛）
  - dmg-fancy：強制美化版（需 `brew install create-dmg`）
  - dmg-plain：原 hdiutil UDZO（保留為 fallback）
- Windows / Linux 流程零改動

驗證：
- `make dmg-fancy` 產出 157MB DMG，mount 後內容：app + Applications 捷徑
  + .background/background.png + .DS_Store（視窗樣式）
- `hdiutil verify` 通過

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-04-21 01:11:22 +08:00
jim800121chen
d0b33f8c71 fix(local-tool): macOS 掃不到 Kneron 裝置 — PythonModeAuto 先 bundled 
症狀：Mac 版 app 啟動後，前端顯示沒有裝置（實際 KL520 透過 USB 連上）。

根因：
PythonModeAuto 原本「先 system 後 bundled」，但系統 python3 通常沒裝
KneronPLUS wheel → `import kp` 失敗 → HAS_KP=False → bridge 降級 pyusb →
pyusb 找不到 libusb → scan 空陣列。表面看起來啟動成功但 detector 是空的。

修法：
- visiona-local/app.go PythonModeAuto 語意翻轉 → 先 bundled（已預裝 kp wheel），
  失敗才 fallback system。Local-tool 架構就是整包內嵌 Python + wheels，
  系統 python 不會裝 kp，不該優先。
- server/scripts/kneron_bridge.py 在 `import kp` 前新增
  `_preload_kneron_dylibs_macos()` — 用 ctypes.CDLL 絕對路徑預載 wheel 內
  `kp/lib/libusb-1.0.0.dylib` + `libkplus.dylib`，避開 macOS hardened
  runtime 剝掉 DYLD_LIBRARY_PATH 的風險。Windows/Linux 守門不執行。

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-04-21 01:10:59 +08:00
jim800121chen
b76acbe227 fix(local-tool): build-appimage.sh wheel 檢查改用 grep -i 不分大小寫 
上一輪誤把關鍵字寫成 'kp'，但 wheel 檔名是 'KneronPLUS-2.0.0-*.whl'，
shell glob *kp*.whl 匹配不到，導致即使 wheel 實際存在仍 exit 1。

改用 ls | grep -i 不分大小寫比對「KneronPLUS」，同時更正錯誤訊息
從「kp wheel」改為「KneronPLUS wheel」。

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-04-18 23:40:17 +08:00
jim800121chen
6c21beb7b6 fix(local-tool): Linux AppImage bundled Python + udev 單次密碼 
Linux AppImage 掃不到 Kneron 裝置的根因是 Wails app 端三個 locator
完全沒讀 AppRun 已 export 的 VISIONA_BUNDLE_LIB_DIR，導致：

- locateBundleDataDir 找不到 models.json → seed user data dir 失敗
- locateBundledPythonAssets 找不到 python tarball + wheels
  → ensurePythonRuntime(Auto) fallback 到 system Python
  → system Python 缺 numpy / kp / pyusb → bridge scan silent fail
  → "No Kneron devices detected"

修復：

1. 三個 locator 優先讀 VISIONA_BUNDLE_LIB_DIR / VISIONA_BUNDLE_BIN_DIR
   （AppRun 已 export），AppImage 佈局 usr/lib/visiona-local/{data,python,wheels}
   一次到位

2. AppRun 加 VISIONA_PYTHON_MODE=bundled — Linux AppImage 強制走內嵌
   Python，避免 system Python 環境差異（符合 R4「完全離線內嵌」決策）

3. InstallUdevRule 合併 pkexec：cp + reload-rules + trigger 用
   pkexec sh -c 一次提權，使用者只需輸入 1 次密碼（原本 3 次）

4. build-appimage.sh 加硬檢查：
   - python tarball 缺失 → 自動 make vendor-python-linux，仍缺就 exit 1
   - wheels 數量 < 4 → 自動 make vendor-wheels-linux，仍不足就 exit 1
   - 驗證關鍵 wheel（numpy / opencv / pyusb / kp）存在，少任一 exit 1

5. Makefile payload-linux 同步加硬檢查（python tarball 必存在，
   wheels ≥ 4 個）

6. 參照 edge-ai-platform POC 補齊 visiona-local/wheels/linux/ 的
   KneronPLUS-2.0.0-py3-none-any.whl（POC 已驗過可用）

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-04-18 23:15:52 +08:00
jim800121chen
4e3dc3e504 fix(local-tool): Linux udev rule 自動偵測安裝 + pkexec FUSE 修復 
兩個修復：

1. pkexec cp 失敗：AppImage 的 FUSE mount（/tmp/.mount_vision*）有特殊
   權限，pkexec 提權後的 root process 無法讀取 user mount 的 FUSE 檔案。
   修法：先用 os.ReadFile 把 rule 讀到 /tmp/visiona-local-99-kneron.rules
   （普通使用者權限可寫 /tmp），再 pkexec cp 從 /tmp 到 /etc/udev/rules.d/。
   同時修 server API endpoint 和 Wails 啟動流程兩處。

2. 啟動流程自動偵測 udev：Stage 4 probeDeviceListAndComplete 解析
   /api/devices response 的 udevHint 欄位。Linux + 0 裝置 + udevHint=true
   → 自動找 bundle 裡的 99-kneron.rules → 複製到 /tmp → pkexec cp 安裝
   到 /etc/udev/rules.d/ → reload udev。會彈 Linux 圖形化密碼框，使用者
   輸入密碼即完成。取消密碼不阻擋啟動流程（log 記錄跳過）。

   Wails 控制台 Stage 4 會顯示細步文案：「偵測到 USB 權限未設定，正在
   安裝（請在密碼視窗輸入密碼）...」

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-17 00:02:37 +08:00
jim800121chen
372259b4b1 fix(local-tool): 載入模型 dialog 點灰色區域不再關閉 
使用者回報點 dialog 周圍灰色 overlay 會誤關 popup。

修法：flash-dialog 的 DialogContent 加：
- onInteractOutside: 永遠 preventDefault（灰色區域點擊不關）
- onEscapeKeyDown: 載入中 preventDefault（載入完成後可 Esc 關）

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-16 23:43:34 +08:00
jim800121chen
db272cac5a feat(local-tool): Linux udev rule 未安裝偵測 + 一鍵安裝 UX 
使用者在 Ubuntu 上 scan 不到 Kneron 裝置。根因：Linux 預設 USB 裝置
權限是 root only，非 root 使用者的 kp.core.scan_devices 因 permission
denied 而 silently 回傳 0 裝置。需要安裝 udev rule。

修法三層：
1. Server：GET/POST /api/devices 在 Linux + 0 裝置 + udev rule 不存在
   時帶 udevHint: true
2. 新增 POST /api/system/install-udev：用 pkexec 提權安裝 99-kneron.rules
   + reload udev（彈 Linux 圖形化密碼對話框）
3. 前端 devices page：udevHint=true 時顯示 amber 色 banner 提示 +
   一鍵安裝按鈕，成功後自動 rescan

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-16 23:20:28 +08:00
jim800121chen
ddf0eb8147 fix(local-tool): KL520 首次 connect 跳過不必要的 device reset 
使用者 Windows 上 connect KL520 耗時 60+ 秒且前端收到 504 timeout。

根因分析（從 log 逐行推斷）：
  1. server 啟動後首次 connect → needsReset=true → restartBridge()
  2. reset 送出 → KL520 reboot → 退回 KDP2 Loader 模式（USB Boot 裝置，
     reset = firmware 從 RAM 清掉）
  3. USB 重新枚舉 8 秒 → 新 bridge process → 嘗試 reconnect
  4. Loader 模式的 connect_devices_without_check 不穩定 → attempt 1 fail
     (16 秒 timeout) → attempt 2 成功 (4 秒)
  5. 載 firmware fw_scpu.bin → 31 秒
  6. firmware loaded → 再次 reboot → 5 秒後 reconnect
  7. 總時：8 + 16 + 4 + 31 + 5 = 64 秒 > 前端 60 秒 HTTP timeout → 504

但 KL520 是 USB Boot 裝置，每次斷電 firmware + model 就會清掉，connect
時本來就是 clean state。server 啟動後主動 reset 是多餘的——它把完整
firmware 砍掉再重載一次，浪費 60 秒且 Loader 模式 connect 不穩定。

這個 reset 邏輯最初是為 KL720 設計的：KL720 是 flash-based 裝置，
firmware 和 model 保留在 flash，reset 清 stale model 才有意義。

修法：needsReset 條件加上 chipType == "KL720"。KL520 跳過 reset，
直接使用已有的 firmware。如果 KL520 真的有殘留 model 要清（理論上
不會因為它是 RAM-based），下次 load_model 前的 restartBridge 會處理。

修復後 KL520 connect 預期時間：2-5 秒（一次 connect + set_timeout）。

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-16 22:49:01 +08:00
jim800121chen
abbe9d4c0b fix(local-tool): DeviceGroup.__del__ access violation 全面修復 
上一個 commit (a6a121a) 只修了 script 結束時的 cleanup，但使用者仍在
connect 重試路徑看到 access violation：

  connect attempt 1 failed → 新 connect attempt 2 → GC 回收 attempt 1
  的舊 DeviceGroup → __del__ → kp_disconnect_devices 對已失效的 native
  handle → OSError: access violation

根因：`_device_group = None` 只是清掉 Python reference，舊物件的 __del__
會延遲到下一次 GC cycle（可能發生在新 connect call 的 allocation 時），
此時 native handle 已 invalid。

修法：
- 新增 `_clear_device_group()` helper：先 kp.core.disconnect_devices 把
  native handle 正常釋放（errors silenced），再設 None
- 全檔搜 `_device_group = None` 共 12 處，除了初始宣告（L40）和兩個 helper
  自身（_clear_device_group / _cleanup）以外全部替換為 _clear_device_group()
- 涵蓋所有 code path：connect retry / firmware load reconnect / disconnect
  handler / reset handler / error fallback

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-16 17:20:12 +08:00
jim800121chen
a6a121ae86 fix(local-tool): suppress KneronPLUS DeviceGroup.__del__ access violation 
Windows 上 bridge script 結束時 Python GC 呼叫 DeviceGroup.__del__ →
kp_disconnect_devices 對已釋放的 native handle 操作 → OSError: access
violation reading 0x00...0C。這是 KneronPLUS SDK 的 destructor 沒做
null check 的已知問題，不影響功能但會印嚇人的 stack trace 到 stderr。

修法：
- 新增 _cleanup() 函式：明確 kp.core.disconnect_devices + 把
  _device_group 設 None（讓 __del__ 成 no-op）
- atexit.register(_cleanup) 確保 interpreter 關閉前 cleanup
- main() return 後也同步呼叫一次（belt-and-suspenders）

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-16 15:40:30 +08:00
jim800121chen
14d5a0ed2f docs(local-tool): Build 指引 → Installer Build 指引 
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-16 15:04:38 +08:00
jim800121chen
041d872fa0 docs(local-tool): 移除 M8 重構變更紀錄 section 
使用者不需要在功能文件中看到 commit changelog。章節重新編號 6-8。

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-16 15:02:56 +08:00
jim800121chen
4f9a193782 chore(local-tool): 移除模型 FPS/latency/accuracy 預估值 
使用者要求拿掉 FPS 預估數字（未經實測，不準確）。

- docs/LOCAL-TOOL-SPEC.md: 模型表格移除 FPS 欄位
- server/data/models.json: 7 個模型全部移除 fps / latencyMs / accuracy 欄位

前端 model-detail / model-card 有讀這些欄位的 UI，移除後會顯示 — 或不顯示
該列，不需要額外前端改動（已有 null/undefined fallback）。

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-16 15:01:25 +08:00
jim800121chen
61f9b8bf6b docs(local-tool): 功能規格文件 LOCAL-TOOL-SPEC.md 
涵蓋：
- 概述（三平台 + 完全離線安裝）
- Wails 控制台（5 階段啟動進度、timeout 機制、控制台功能、single-instance）
- Web UI（頁面路由、推論來源、結果顯示、模型管理、裝置管理、離線覆蓋層）
- 預設模型清單（KL520 × 4 + KL720 × 3）
- 內嵌依賴（Python/numpy/opencv/KneronPLUS/ffmpeg LGPL）
- Server API 摘要（系統/模型/裝置/媒體/WebSocket）
- M8 重構變更紀錄（15 個 commit 的完整 changelog）
- 資料目錄結構（三平台路徑 + 檔案說明）
- Build 指引（macOS/Windows/Linux）
- 除錯指引（Windows 啟動問題 + 常見問題）

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-16 14:46:09 +08:00
jim800121chen
9793a2efc1 chore(local-tool): models.json 只保留有實體 .nef 的 7 個預設模型 
使用者要求：前端模型庫只保留有適配裝置的模型（KL520 4 個 + KL720 3 個）。

原本 models.json 有 15 筆：
  - 8 筆 ONNX framework 的 demo 模型（yolov5-face-detection /
    imagenet-classification / person-detection / vehicle-classification /
    hand-gesture-recognition / coco-object-detection / face-mask-detection /
    license-plate-detection）— 都沒有實體 .nef 檔，是 placeholder metadata
  - 7 筆 NEF framework 的實體模型（每個都有 filePath 指向 data/nef/）

現在只保留 7 筆實體模型：
  KL520（4 個）：
    - kl520-yolov5-detection (yolov5 no-upsample 640x640)
    - kl520-fcos-detection (fcos-drk53s 512x512)
    - kl520-ssd-face-detection (ssd_fd_lm 320x240)
    - kl520-tiny-yolov3 (tiny_yolo_v3 416x416)
  KL720（3 個）：
    - kl720-yolov5-detection (yolov5 no-upsample 640x640)
    - kl720-resnet18-classification (resnet18 224x224)
    - kl720-fcos-detection (fcos-drk53s 512x512)

server/data/models.json 是 runtime 讀取，三平台（macOS/Windows/Linux）
共用同一份，改一次三平台全部生效。

驗證：
- python3 json.load 解析正常，7 筆 entries
- 每筆 filePath 指向的 .nef 實體檔都存在於 server/data/nef/{kl520,kl720}/
- 檔案大小：1-13 MB，合計 ~64 MB
- macOS dmg 重 build 163MB OK
- Bundle 內 Contents/Resources/data/models.json 更新為 7 筆

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-16 08:44:16 +08:00
jim800121chen
ad9beab0ca fix(local-tool): Restart / StopServer+StartServer 後前端 5 階段 UI 不更新 
使用者在 Windows 版 local tool 按「重新啟動伺服器」或 Stop 再 Start 後，
畫面中間的 5 階段面板停留在「等待中」不更新，但實際上 server 已經
成功啟動完成。

根因：
  Restart / StartServer 路徑 → ctrl.Restart() / ctrl.Start() →
  ctrl.startInternal() → startServerV2()

  但 StartupPipeline 已經 markReady (current=7)，所以 startServerV2 內
  所有 CompleteStage(2/3/4) / EmitStageDetail / IsInColdStart 檢查都
  early return 或 no-op，Go 端完全不 emit 任何 startup:progress event。
  前端 resetStartupPanel 後開始等事件，但事件根本沒來 → UI 停留在
  pending「等待中」。

  RestartStartupSequence（Retry 按鈕）有自己完整重建 pipeline 的 5 步
  邏輯，所以 Retry 路徑沒事。但 Restart / Stop+Start 走的是 ctrl.Restart
  / ctrl.Start 不走 RestartStartupSequence。

修法：

1. 抽 helper rebuildStartupPipeline() — 把 RestartStartupSequence 裡
   「重建 pipeline + emit Stage 1 completed + 啟 watcher + 前進 Stage 2」
   那 20 多行邏輯抽出來，讓 startInternal 也能呼叫。

2. startInternal 進場時偵測 pipeline 狀態：
   - cold start 路徑 (current ∈ [1..6]) → 不動
   - 已 ready (current > totalStages) 或 已 failed (current == -1)
     → 清 sentinel file + 呼叫 rebuildStartupPipeline()，記 didRebuild=true

3. startInternal 成功返回前，Stage 5 openBrowser 處理改成三分支：
   - didRebuild=true → 呼叫 runStartupStage5（Restart 路徑）
   - cold start (IsInColdStart && !didRebuild) → skip 由上層呼叫
     runStartupStage5（app.startup 冷啟動路徑或 RestartStartupSequence）
   - fallback (pipeline == nil) → 自己 openBrowser 一次

四條路徑的分流現在完整：

  (A) cold start           : app.startup → Pipeline.Start 自己前進到 2 →
                             startInternal 看 current=2 不 rebuild →
                             didRebuild=false → app.startup 呼叫 stage5
  (B) Restart / Stop+Start : ctrl.Restart/Start → startInternal 看
                             current=7 rebuild → didRebuild=true →
                             startInternal 自己呼叫 stage5
  (C) RestartStartupSequence: 自己 rebuild 前進到 2 → ctrl.Start →
                             startInternal 看 current=2 不 rebuild →
                             didRebuild=false → RestartStartupSequence
                             後續呼叫 stage5
  (D) pipeline == nil       : 走舊 fallback 自己 openBrowser

驗證：
- visiona-local 套件 go build / vet / test -race 全綠
- 關鍵 test TestRestartStartupSequence_ColdStartOpenBrowser_OnlyOnce
  仍 pass（驗證 browser 不會被 cold start 開兩次）
- macOS dmg 163MB 重 build OK

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-16 08:19:33 +08:00
jim800121chen
485a2e01ff fix(local-tool): bootstrap-linux.sh 自動安裝 appimagetool 
使用者在 Linux build 時遇到「appimagetool 未安裝」錯誤（wails binary
已產出 9.3M，但打包 AppImage 失敗）。原本 bootstrap-linux.sh 只裝 Go /
Node / Wails CLI，沒裝 appimagetool，build-appimage.sh 到打包步驟才
fail。

修法：

1. bootstrap-linux.sh 新增 [5/6] 步驟自動下載 + 安裝 appimagetool
   - 從 AppImage/appimagetool 官方 continuous release 拉
     appimagetool-x86_64.AppImage
   - chmod +x + sudo mv 到 /usr/local/bin/appimagetool
   - 已安裝則跳過

2. build-appimage.sh 的 appimagetool not found 錯誤訊息更新
   - 提供一鍵安裝 curl 指令（不需重跑整個 bootstrap）
   - 提示可重跑 bootstrap-linux.sh 一併補所有依賴
   - 舊訊息裡的 URL 指向已 archived 的 AppImageKit repo，換成
     AppImage/appimagetool（新 repo 位置）

使用者立即可用（不想重跑 bootstrap）:
  curl -fsSL https://github.com/AppImage/appimagetool/releases/download/continuous/appimagetool-x86_64.AppImage \\
    -o /tmp/appimagetool && chmod +x /tmp/appimagetool && sudo mv /tmp/appimagetool /usr/local/bin/appimagetool
  make appimage

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-16 08:11:49 +08:00
jim800121chen
fbd585ab73 fix(local-tool): Linux build 支援 webkit2gtk-4.1（Ubuntu 22.10+ / Debian 12+） 
使用者在 Linux build 看到：
  pkg-config --cflags ... webkit2gtk-4.0
  Package 'webkit2gtk-4.0' not found

根因：Wails v2.11 預設 cgo pkg-config 指定 webkit2gtk-4.0，但 Ubuntu
22.10 之後的版本已經把系統 package 從 webkit2gtk-4.0 改名為 4.1
（API 大致相容）。使用者 bootstrap 裝的是 libwebkit2gtk-4.1-dev，
pkg-config 找不到 4.0.pc 就 fail。

修法：

1. Makefile wails-linux target 自動偵測 webkit2gtk 版本
   - 優先 pkg-config --exists webkit2gtk-4.1 → wails build -tags webkit2_41
     （Wails v2.10+ 支援的 build tag，切換到 4.1 的 cgo 宣告）
   - 退回 pkg-config --exists webkit2gtk-4.0 → wails build 預設
   - 兩者都沒有 → 清楚錯誤訊息 + 建議安裝指令

2. scripts/bootstrap-linux.sh 裝 webkit2gtk dev package 時也做版本偵測
   - apt-cache show 優先查 4.1，退回 4.0
   - Ubuntu 22.04 及之前 repo 有 4.0；22.10+ / 24.04 repo 只有 4.1
   - 兩個都試過才 err

驗證：
- make -n wails-linux dry-run 正常 parse
- bash -n scripts/bootstrap-linux.sh 語法 OK
- macOS 端 make dmg 仍 work（未改 darwin target）

使用者待做：Linux 端 git pull 拉新版 → 重跑 bootstrap-linux.sh
（確保 webkit2gtk-4.1-dev 安裝）→ make appimage。

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-16 04:11:53 +08:00
jim800121chen
f5655e38b1 feat(local-tool): hard timeout 5min + Stage 6 隱藏到 header + 全屏 splash 
回應使用者三項需求：

1. 整體 hard timeout 180s → 300s（5 分鐘）
   每個 stage 已有 soft timeout 20s 提示機制，整體 budget 不需緊湊。
   5 分鐘是「使用者點完一杯咖啡都還沒好」的心理上限。pause 機制
   （Stage 1 seed / Stage 2 Python bootstrap / Stage 3 waitHealthy）
   仍維持作為「一次性 bootstrap 完全不算 budget」的快速通道。
   - 同步更新 i18n 紅 banner 文案 180 → 5 分鐘
   - 同步更新 unit tests（HardTimeout 用 -305s，SkipBypass 用 -320s，
     PreventsHardTimeout 註解 effective<300s）

2. Stage 6「等待 Web UI 連線」從 6 階段面板隱藏到 header 連線指示燈
   Go 端 pipeline 仍保持 6 階段（不動），前端 UI 只顯示 5 階段：
   - startup-panel.js: TOTAL_STAGES=5 顯示用，PIPELINE_STAGES=6 內部
     state 用。renderStages / paintProgressBar / 進度數字都用 5。
   - updateStage 仍會收 stage 6 events 更新內部 state（控 collapse 時機）
     但 stage 6 不 paint UI（n > TOTAL_STAGES early return）
   - 新增 onConnectionStatusChange listener 機制：stage 6 status 變化
     時通知外層
   - control-panel.js: setWebUIStatus 把連線狀態 (pending/running/
     completed/failed) 渲染到 header 的 meta-webui 指示燈：圓點顏色
     + 文字 (等待連線/已連線/未連線)
   - index.html: server-meta 新增 <dd id="meta-webui"> 指示燈位置
   - i18n: control.meta.webui / control.webui.{connected,waiting,disconnected}
   - style.css: .webui-status::before 圓點 + pulse 動畫 + 顏色對應
     state (pending=灰 / running=warning+pulse / connected=success / failed=destructive)
   - app.js: 註冊 onConnectionStatusChange listener，初始化呼叫
     setWebUIStatus('pending')

3. 全屏 spinner splash 取代「啟動中...」三個字
   原本 app 啟動最一開始的「啟動中」狀態只有 header 上三個字很不
   明顯，使用者體感像沒反應。改為 DOM ready 時就顯示 fullscreen
   spinner overlay，收到第一個 startup:progress event 才隱藏。
   - index.html: <div id="boot-splash"> 內含 logo + spinner-lg + 文字
   - style.css: .boot-splash position:fixed inset:0 z-index:1000，
     .boot-splash.hidden { display:none } 用 class 控制（避免和
     [hidden]!important 衝突）
   - app.js: hideBootSplash() helper，4 個 hide 觸發點：
     (a) 收到 startup:progress event
     (b) snapshot 補漏發現 pipeline 已啟動
     (c) 收到 startup:error event（即使失敗也要看到錯誤）
     (d) handleServerStatus 收到非 idle 狀態（restart wails app
         server 還活著的情境）

更新 fix marker 為「d946561+ (5min hard timeout + 5-stage UI + fullscreen splash)」

驗證：
- visiona-local 套件 go build / vet / test -race 全綠
- macOS dmg 163MB 重 build OK

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-16 01:23:55 +08:00
jim800121chen
d946561362 fix(local-tool): Stage 順序亂跳修復 + 移除秒數顯示 
兩個問題一次修：

1. Stage 順序亂跳 — 「Stage 1 等待中、Stage 2 完成、Stage 3 進行中」
   根因：Wails Webview JS load 需 1-3 秒（Windows 乾淨環境更慢），這段
   期間 Go 的 Pipeline.Start 已經 emit Stage 1 running event 甚至跑完
   Stage 1 / Stage 2，但前端 EventsOn 還沒掛上去，events 全被丟掉。前端
   接到的第一個 event 可能是 Stage 2 completed 或 Stage 3 running，
   stages[1].status 仍是初始 pending 值，UI 顯示亂序。

   修法：
   - 新增 Go binding GetStartupSnapshot() 回傳 pipeline 當前所有 stages
     狀態（含 current / startedAt / status）。
   - 前端 init 流程在 subscribeEvents 後立即拉一次 snapshot，補上漏掉
     的 stage 狀態。
   - updateStage 加 monotonic 模式：snapshot 補漏時不會用較舊狀態覆蓋
     已收到的較新狀態（避免 race condition 倒退）。
   - status 優先級 STAGE_STATUS_RANK = pending<running<{skipped,failed}<completed

2. 進度條已等待秒數顯示錯誤 — 「進度 3 / 6 · 已等待 20 秒」
   根因：pause 機制讓 elapsed 計算失準（pause 期間 wall clock 仍走但
   stages[i].startedAt 沒重設，會顯示明顯比真實還久的數字）。使用者
   覺得不需要顯示秒數。
   修法：
   - paintProgressBar 移除 elapsedText 邏輯，永遠顯示 progressLabel
   - i18n 文案移除 {elapsed} placeholder（zh-TW + en）：
     stage.1.detail.seedSlow / stage.3.detail.waitHealth /
     stage.3.detail.waitHealthSlow 都改為固定文案
   - Go 端 emit 仍會傳 elapsed（waitProgress callback 不變），但前端
     i18n template 不再用該變數，自然就不顯示

驗證：
- visiona-local 套件 go build / vet / test -race 全綠
- macOS dmg 163MB 重 build OK
- Wails bindings 自動 regen 含 GetStartupSnapshot

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-16 01:14:21 +08:00
jim800121chen
ff5cab6b0e feat(local-tool): hard timeout 180s + 全 stage 細步 detail emit + Stage1 seed pause 
使用者回報 Windows 仍看到「啟動時間超過 60 秒」紅 banner，且要求每個
階段做什麼都印出來給使用者知道。三件事一次到位：

1. startupHardTimeout 60s → 180s（直接放寬到 3 分鐘）
   即使三段 pause 機制（Stage 1 seed / Stage 2 Python bootstrap / Stage 3
   waitHealthy）都生效，Windows 乾淨環境段落間累積延遲仍可能超過 60 秒。
   180s 給意料之外的延遲足夠 buffer，搭配 pause + 細步進度 emit 涵蓋
   99% 情境。日常啟動只要幾秒，放寬不影響正常情境。
   - 同步更新 i18n 紅 banner 文案 60 → 180
   - 同步更新 unit tests（HardTimeout 用 -185s、SkipBypass 用 -200s、
     PreventsHardTimeout 用 wall=-300/paused=-250 對應 effective=50s）

2. Stage 1 seedUserDataDir 包進 PauseHardTimeout
   Windows 乾淨環境首次跑會被 Defender real-time scan 對 8 個 nef 檔
   逐個掃 5-30 秒。屬一次性 bootstrap，和 Stage 2/3 同理應豁免 hard
   timeout。第二次啟動 fileExists 早 early return，pause 影響 0ms。
   配套：seed 期間每 5 秒 emit slow hint 帶 elapsed 秒數，避免使用者
   看 spinner 不動以為當機。

3. 全 stage 細步 detail emit
   原本只有 Stage 3 有 sub-step 文案（spawn / waitHealth / waitHealthSlow）。
   現在 Stage 1/2/4/5/6 都有：

   Stage 1: migrate / lock / ipc / seed / seedSlow
   Stage 2: detect / bootstrap / venv / pip / driver
   Stage 3: spawn / waitHealth / waitHealthSlow
   Stage 4: probe
   Stage 5: open
   Stage 6: wait

   每個 detail 對應一段使用者能讀懂的中英文文案（i18n.js zh-TW + en）。
   前端 startup-panel 收到 startup:stage-detail event 後在對應 stage 列
   下方顯示文案，比看著「進行中...」靜止文字直觀很多。

   Stage 2 driver install 因為發生在 CompleteStage(2) 之後 current=3，
   emit 到 stage 3 而非 stage 2，避免被前端忽略（detail 只在 stage
   running 時顯示）。

更新 fix marker 為「9c9e005+ (180s hard timeout + all-stage sub-step
detail + Stage1 seed pause)」讓使用者拉新版後能從 wails.log 確認版本。

驗證：
- visiona-local 套件 go build / vet / test -race 全綠
- macOS dmg 163MB 重 build OK

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-16 00:45:50 +08:00
jim800121chen
9c9e005d33 feat(local-tool): Stage 3 sub-step 進度 + 啟動完成後面板可收合 
回應使用者三項需求：
1. healthCheckTimeout 60s → 180s（涵蓋 Defender + EDR 串行延遲最壞情境）
2. Stage 3「啟動本機伺服器」期間顯示細步在做什麼，並在 15 秒後改為「首次
   啟動較久屬正常」slow hint，避免使用者看著 spinner 不動以為 app 掛了
3. 啟動完成後 6 階段面板自動收合成一行 summary，使用者點擊可展開檢視歷
   史紀錄；Restart / Retry 會重置並展開新一輪

實作：

Go 端
- healthCheckTimeout 60s → 180s（理由註解寫清楚 Defender + EDR 各自延遲）
- waitHealthy() 加 progress callback，每 5 秒呼叫一次傳入 elapsedSeconds
- StartupPipeline 加 StartupStageDetailEvent + EmitStageDetail() API
- startServerV2 在 spawn 前 emit detail.spawn，等 health check 期間 callback
  emit detail.waitHealth（< 15s）或 detail.waitHealthSlow（>= 15s）

前端
- 新訂 startup:stage-detail event → updateStageDetail() 把 i18n key 解析為
  文案存到 stages[n].detail，paintStageRow 優先顯示 detail（蓋過 slow hint）
- collapseStartupPanel() / expandStartupPanel() / resetStartupPanel() 三個新
  API 取代 hideStartupPanel；startup:ready 觸發 collapse、Retry/Restart 觸
  發 reset+expand
- collapsed CSS：保留 panel 但縮成一行 summary（標題改「啟動完成」+ ✓ +
  「點此展開檢視」hint），整個 panel 可點擊；hover 加亮
- i18n 加 6 個 keys（zh-TW + en）

驗證：
- visiona-local 套件 go build / vet / test -race 全綠
- macOS dmg 重 build 163MB OK
- 乾淨 dataDir 啟動 wails app：startup 1 秒內完成（macOS 已 cache binary
  + Python venv），server listen 3721，Chrome 自動連上 — 整條 cold start
  正常

Windows 首次安裝預期行為（修復後）：
- Stage 1 → Stage 2（首次 bootstrap pause hard timeout，跑 1-3 分鐘）→ Stage
  3 spawn → 等 health check 30-90 秒（Defender 掃 binary）期間有「已等 N
  秒」即時更新 → ready → 自動 collapse → 瀏覽器自動開啟

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-16 00:17:37 +08:00
jim800121chen
a6cd1c12b2 fix(local-tool): Wails 控制台一打開就看到 modal — CSS specificity bug 
使用者回報：Windows 乾淨環境安裝後，一打開 app 就看到「Settings modal +
shutdown-modal「正在停止伺服器…」+ 紅 banner「伺服器無法啟動」」三個應該
hidden 的 element 同時可見。

前面幾個 commit 一直往 Go 端找為什麼 ctrl.Stop 會被意外呼叫，全都沒對。
真正的 bug 是 CSS specificity：

  .modal-backdrop { display: flex; ... }  /* L587，specificity (0,1,0) */
  .error-banner   { display: flex; ... }  /* L488，specificity (0,1,0) */

這兩個 class 的 `display: flex` 規則和 user agent stylesheet 內建的
`[hidden] { display: none }` specificity 相同，但因為我們的 CSS 寫在
cascade 後段勝出——結果是即使 DOM 裡元素有 `hidden` 屬性，瀏覽器依然
渲染成 `display: flex` 可見。

三個受害元素：
  <div class="modal-backdrop" id="settings-modal" hidden>
  <div class="modal-backdrop shutdown-modal" id="shutdown-modal" hidden>
  <section class="error-banner" id="error-banner" hidden>

全部從 DOM 載入第一刻就可見，和 Go 端 ctrl.Stop 是否被呼叫無關。M7
splash 時代前端沒 modal 所以沒人踩到，M8 新加的控制台 UI（8cd5751）
引入這個 bug，但 macOS dev 測試時我只看 server 端 log + api 回應，
沒真的看 Wails 視窗長什麼樣，所以也漏抓。

修法：加全域 `[hidden] { display: none !important; }`。這是 W3C 規範
的標準寫法，保證任何帶 hidden 屬性的元素都會被隱藏，不管其他 CSS
規則怎麼寫。!important 在這情境是正確的——hidden 屬性代表「該元素
不應被顯示」是規範強制語意，不該被任何樣式覆蓋。

驗證：
- macOS dmg 重 build 163MB OK
- binary 內 strings 確認 `[hidden] { display: none !important; }` 已 embed
- 清乾淨 user dataDir 後啟動 wails app，wails.log 整條 startup 流程正常：
  Stage 1 complete → Stage 2 → ctrl.Start returned successfully
- Chrome 建立 2 條 ESTABLISHED 連線到 127.0.0.1:3721
- dataDir 有完整檔案（lock / ipc-port / wails-ipc-port / sentinel / models.json / nef/）

前幾個 commit 修的東西（Stage 2 pause、waitHealthy pause、shutdown modal
safety net、Bug A killStaleServerOnPort）仍然有防禦價值，但都不是使用者
截圖症狀的 root cause。

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-15 23:20:33 +08:00