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

7 Commits

Author SHA1 Message Date
jim800121chen
4d0b870480 feat(visionA-backend): DB 接入 — 6 store 接 PostgreSQL/Redis 持久化（塊 0-5） 
把 visionA-backend 6 個 in-memory store 接到資料庫持久化，範圍=完整
（PG 全接 + session 接 Redis + 交易韌性）。interface / handler 不動，
只加 DB 實作 + 換 wiring，config 未設 DB 時保留 in-memory fallback。

- 塊 0 基礎建設：pgx/v5 連線池 + DatabaseConfig/RedisConfig + golang-migrate
  runner（embed）+ cmd/migrate + testcontainers 測試基礎建設
- 塊 1 model → Postgres：array 映射、upsert 保留 CreatedAt、faa_object_key、
  三維 filter（owner/chip/source）、soft-delete partial index
- 塊 2 device → Postgres：partial unique（已刪 serial 可重註冊）、雙狀態欄位
- 塊 3 token → Postgres：pairing_tokens + session_tokens 分表、token_hash 當 PK
- 塊 4 userSession → Redis：idle + absolute 雙 TTL 取代 cleanup goroutine
  （tunnel session 維持 in-memory，yamux handle 不可序列化）
- 塊 5 交易/韌性：WithTx helper + 刪 device cascade 撤銷 token（同 tx 原子）
  + /healthz ping PG/Redis（fail-fast 503）+ pgx error 統一映射（不洩漏 raw error）

降級策略（fail-fast）：PG 掉 → 持久資料 API 回 503；Redis 掉 → session 失敗
不自動 fallback in-memory（避免多機 session 不同步）。

DB：PostgreSQL 14.23（gen_random_uuid 內建、無 citext → email 用 lower() unique
index）。每塊經 Reviewer 審查 + 真 PG/Redis testcontainers 全量 dbtest 綠燈，
in-memory fallback 未受影響。

docs: 同步更新 database.md（schema/config/migration 清單）+ api-spec.md
（409/503 錯誤碼、/healthz 新行為、device unpair cascade）。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
 2026-06-20 18:28:04 +08:00
jim800121chen
c63886a194 feat(visionA-backend): Phase 0.9 模型庫存取 — FAA delegated download token（B1+B2） 
對齊 ADR-017 v1.2：模型庫下載走 visionA 簽 MC delegated token → Client 直連 FAA。

B2 — MC download token client（internal/fileaccess）:
- DownloadTokenIssuer: GetServiceToken（打 MC /oauth/token，client_credentials +
  scope files:download.delegate，含 token cache）+ IssueDownloadToken（打 MC Issue 簽 fdt_）
- secret / service token / fdt token 三層全程用 hashShort 遮罩不 log
- FileAccessConfig + VISIONA_FILE_ACCESS_* env + main.go wire（Enabled() 才接）

B1 — object_key 斷層:
- model.Model 加 FAAObjectKey（json:"-" 不揭露前端）
- PromoteToModels 寫入（用 promote response TargetObjectKey = models/{userID}/{jobID}.nef）
- 三方對映天然一致（visionA Issue / FAA path / MC validate）
- 第一階段框死只 Source=converted 類 model，上傳類 download 回 501

download endpoint:
- GET /api/models/:id/download（owner-only）→ {download_url, token, expires_at}
- 前端帶 Authorization: Bearer 直連 FAA（不經 visionA、不經 AWS）
- 401/403/404/501/502 分明，502 對外 mask 不洩漏 MC 內部狀態

測試: 13 + 8 unit test（mock MC + fake issuer，httptest 驗真 HTTP）；go build/vet/test 全綠。
Reviewer: 0 Critical / 0 Major / 3 Minor / 4 Suggestion，通過。

技術債（正式上線前）: 第一階段 PoC 共用 FAA service client，MC 規範禁止 client 混用
usage、secret 不共用，須 MC 配發 visionA 專屬 usage=file_api client。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
 2026-06-07 04:06:09 +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
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
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
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