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

5 Commits

Author SHA1 Message Date
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
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
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