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