visionA/docs/autoflow/04-architecture/conversion.md

Conversion — 轉檔功能整合（Phase 0.8 / Phase 0.8b）

角色：visionA-backend 端的「轉檔」實作 spec（內部模組設計 + API + flow）。 上位文件：adr/adr-015-server-to-server-api-key.md（Phase 0.8b 認證機制 — 部分 supersede ADR-014）、adr/adr-014-conversion-integration.md（仍有效：upload streaming、download 302 設計、模組劃分等）、TDD.md、security.md 同層文件：api/api-conversion.md（對 frontend 的 API 規格細節） 作者：Architect Agent 狀態：Phase 0.8b 修訂（v0.4）— OAuth client_credentials 改 pre-shared API key 最後更新：2026-05-11

---

索引

1. 整體 flow（端對端）
2. 模組設計 — internal/conversion/
3. 服務間認證（API key）— 取代 OAuth client_credentials
4. 新增 visionA-backend API
5. Streaming proxy 設計（upload）
6. 錯誤碼 mapping + i18n key
7. user_id 注入與 trust boundary
8. Non-Goals（Phase 0.8 不做）
9. 失敗模式 & retry 矩陣
10. 安全考量

---

1. 整體 flow（端對端）

Phase 0.8b 變更：服務間認證從「打 MC 換 OAuth service token + JWKS 驗簽 + scope」改為「visionA 帶 Authorization: Bearer <pre-shared-api-key> 直接打 converter / FAA」。詳見 §3 與 ADR-015。

sequenceDiagram
    participant B as Browser
    participant V as visionA-backend
    participant C as Converter
    participant F as FAA

    Note over B,F: Stage 1 — Init job（streaming upload）
    B->>V: POST /api/conversion/init (multipart)
    V->>V: AuthMiddleware → user_id (OIDC sub)
    V->>V: 檢查同 user active job
    V->>C: POST /api/v1/jobs<br/>Authorization: Bearer <VISIONA_CONVERTER_API_KEY><br/>(streamed multipart, user_id 注入)
    C->>C: middleware: ConstantTimeCompare(key, CONVERTER_API_KEY)
    C-->>V: 201 {job_id, status:created, stage:onnx}
    V->>V: 記錄 job_id ↔ user_id mapping
    V-->>B: 200 {job_id, status:running, stage:onnx}

    Note over B,F: Stage 2 — Poll status
    loop 直到 completed / failed
        B->>V: GET /api/conversion/{job_id}
        V->>V: ownership 檢查
        V->>C: GET /api/v1/jobs/{id}<br/>Authorization: Bearer <VISIONA_CONVERTER_API_KEY>
        C-->>V: {status, stage, progress, ...}
        V-->>B: 整形後 status
    end

    Note over B,F: Stage 3a — User 選「加到模型庫」
    B->>V: POST /api/conversion/{job_id}/promote-to-models
    V->>C: POST /api/v1/jobs/{id}/promote<br/>Authorization: Bearer <VISIONA_CONVERTER_API_KEY>
    C->>F: PUT /files/{key} (NEF — converter 內部認證，與 visionA 無關)
    C-->>V: {target_object_key}
    V->>F: GET /files/{key}<br/>Authorization: Bearer <VISIONA_FAA_API_KEY>
    F->>F: middleware: ConstantTimeCompare(key, FAA_API_KEY)
    F-->>V: NEF stream
    V->>V: /api/models/init → /api/models/finalize<br/>(Source=converted, SourceJobID=job_id)
    V-->>B: 201 {model_id}

    Note over B,F: Stage 3b — User 選「下載」（Phase 0.8b: server-side proxy；非 302 redirect）
    B->>V: GET /api/conversion/{job_id}/download
    V->>V: AuthMiddleware → user_id + ownership 檢查
    V->>C: POST /api/v1/jobs/{id}/promote (若還沒 promote)<br/>Authorization: Bearer <VISIONA_CONVERTER_API_KEY>
    C-->>V: {target_object_key}
    V->>F: GET /files/{key}<br/>Authorization: Bearer <VISIONA_FAA_API_KEY>
    F-->>V: NEF stream
    V-->>B: stream NEF（visionA backend 中轉，token 結構性不過 browser）

critical path 說明：

• visionA-backend 在 upload / download / promote 任一階段都先做 OIDC AuthMiddleware（既有）+ ownership 檢查
• promote 動作是冪等的（converter 端對同一 job 重複 promote 接受），visionA-backend 內部以 job_id ↔ promoted_object_key 記錄避免重複呼叫
• 加到模型庫流程：promote → FAA pull → /api/models/init 取得 model_id + presigned PUT URL → visionA-backend 自己 PUT 到 storage → /api/models/finalize（這條路徑要重用既有 handler 邏輯，不繞過）
• Phase 0.8b 認證鏈簡化：不再有 visionA ↔ MC 鏈路；不再有「token cache miss / scope mismatch / JWKS 不可達」失敗模式。converter / FAA 端 middleware 各自只比對單一字串。

Phase 0.8b 與 ADR-014 的差異說明：

面向	ADR-014（OAuth client_credentials）	Phase 0.8b（API key）
visionA → converter 認證	Authorization: Bearer <MC-issued service token>	Authorization: Bearer <VISIONA_CONVERTER_API_KEY>
visionA → FAA 認證	Authorization: Bearer <MC-issued service token>	Authorization: Bearer <VISIONA_FAA_API_KEY>
download 流程	server-side 302 redirect → browser 直連 FAA（拿 MC delegated token）	server-side proxy（visionA backend 中轉 stream）
visionA → MC service token 路徑	啟動 lazy init MCTokenClient + cache	完全移除
converter / FAA middleware	驗 JWKS 簽章 + 驗 scope + 驗 tenant	比對 env 字串（constant-time）

為什麼 download 不繼續走 302 redirect：API key 模式下沒有 MC 簽 short-TTL delegated token；visionA 自己簽 HMAC token 給 browser 的方案留給 Phase 1+（見 ADR-015 §7 選項 B）。

---

2. 模組設計 — internal/conversion/

Phase 0.8b 變更：移除 mc_token_client.go 整個檔案。converter / FAA client 直接從 config 讀預設 API key。

internal/conversion/
├── conversion.go        # Service interface + 對外暴露的 type
├── converter_client.go  # converter scheduler API client（直接帶 VISIONA_CONVERTER_API_KEY）
├── faa_client.go        # FAA API client（pull NEF；直接帶 VISIONA_FAA_API_KEY）
├── flow.go              # 整體 flow 協調
├── types.go             # request / response struct
└── errors.go            # error code 定義

Phase 0.8b 移除：

• ❌ mc_token_client.go（~440 行 — 整檔砍）— 不再需要與 MC 換 service token / delegated download token
• ❌ MCTokenClient 在 flow / converter_client / faa_client 上的所有 reference

2.1 conversion.go — 對外 interface

package conversion

import (
    "context"
    "io"
    "time"
)

// Service 是 handler 層的單一進入點。
type Service interface {
    // InitJob 把 client 的 multipart stream 透傳給 converter，建立 job。
    // bodyReader 必須是「上層 handler 已 wrap 好的 multipart.Reader」— 由 handler 解多 part
    // 後重新組裝（見 §4），避免 service 層關心 multipart.NewReader。
    // 實際實作：handler 直接拿 raw request body + content-type，由 service 內部處理 streaming。
    InitJob(ctx context.Context, in InitJobInput) (*Job, error)

    // GetJob 查 converter status；ownership 檢查後 cache 1-2s。
    GetJob(ctx context.Context, userID, jobID string) (*Job, error)

    // PromoteToModels — 「加到模型庫」流程：promote → FAA pull → models repo finalize。
    // 回傳新建的 model_id。
    PromoteToModels(ctx context.Context, userID, jobID string) (modelID string, err error)

    // DownloadStream — 「下載」流程（Phase 0.8b：server-side proxy）：
    //   1. ownership 檢查
    //   2. promote (若需要)
    //   3. 從 FAA pull NEF stream
    //   4. handler 直接 io.Copy stream 給 client
    // 不再產生 302 redirect URL（API key 模式下無 MC delegated token）。
    // 詳見 ADR-015 §7 — Phase 1+ 量大時再評估「visionA 自簽 HMAC token + 302」升級路徑。
    DownloadStream(ctx context.Context, userID, jobID string) (stream io.ReadCloser, meta *DownloadMetadata, err error)

    // ActiveJob 查 user 當前是否有 active job（給 frontend pre-check 用）。
    ActiveJob(ctx context.Context, userID string) (*Job, error)
}

// InitJobInput 是 handler 傳給 service 的所有資料。
// MultipartBody 由 handler 從 request.Body 取得（已驗 content-type），service 內部處理 streaming。
type InitJobInput struct {
    UserID         string
    ContentType    string         // 含 boundary 的原始值
    Body           io.Reader      // request.Body
    ContentLength  int64
    TargetChip     string         // "520" / "720"
    // 其他 form fields（model_id, version, enable_*）由 handler 解多 part 後傳入
    // — 實作上在 §4 streaming 處理時把這些 field 也透傳給 converter
}

type Job struct {
    JobID         string    `json:"job_id"`
    Status        string    `json:"status"`        // created / running / completed / failed
    Stage         string    `json:"stage"`         // onnx / bie / nef
    Progress      int       `json:"progress"`      // 0-100
    StageProgress int       `json:"stage_progress"`// 0-100
    CreatedAt     time.Time `json:"created_at"`
    UpdatedAt     time.Time `json:"updated_at"`
    ErrorCode     string    `json:"error_code,omitempty"`
    ErrorMessage  string    `json:"error_message,omitempty"`
}

// Phase 0.8b：DownloadGrant 移除（不再有 MC delegated token 換取流程）。
// Download 走 server-side proxy；token 結構性不過 frontend。

// DownloadMetadata — DownloadStream 回傳的中介資料（沿用 §2.3 既定的型別）。
// （定義在 faa_client.go，避免重複）

2.2 converter_client.go

type ConverterClient struct {
    baseURL    string
    apiKey     string         // Phase 0.8b：pre-shared API key（VISIONA_CONVERTER_API_KEY）
    httpClient *http.Client
}

// CreateJobStream 把 io.Reader 當作 multipart body（content-type 含 boundary）透傳給 converter。
// caller 必須：
//   1. 已經把 user_id 透過 multipart.Writer 注入 body（在 streaming 過程中）
//   2. content-type 是合法的 multipart/form-data; boundary=...
func (c *ConverterClient) CreateJobStream(ctx context.Context, contentType string, body io.Reader, contentLength int64) (*Job, error)

func (c *ConverterClient) GetJob(ctx context.Context, jobID string) (*Job, error)

func (c *ConverterClient) PromoteJob(ctx context.Context, jobID string) (targetObjectKey string, err error)

// ListActiveJobsByUser — lazy rebuild ownership 用（§2.6.1）
func (c *ConverterClient) ListActiveJobsByUser(ctx context.Context, userID string) (*Job, error)

每個方法內部（Phase 0.8b 簡化）：

1. req.Header.Set("Authorization", "Bearer "+c.apiKey) — 直接帶 pre-shared API key，不查 cache、不打 MC、不重簽
2. 帶 X-Request-Id（從 ctx 取，沿用 visionA-backend 既有 request_id 中介層）
3. response 5xx / network error 走 retry（§9）；401/403 不 retry（API key 錯不會自己變對）

2.3 faa_client.go

type FAAClient struct {
    baseURL    string
    apiKey     string         // Phase 0.8b：pre-shared API key（VISIONA_FAA_API_KEY）
    httpClient *http.Client
}

// Download server-to-server 拉檔（給「加到模型庫」+「下載」兩個流程共用）。
// 帶 Authorization: Bearer <VISIONA_FAA_API_KEY>。
func (c *FAAClient) Download(ctx context.Context, objectKey string) (io.ReadCloser, *DownloadMetadata, error)

type DownloadMetadata struct {
    SizeBytes   int64
    ContentType string
    Checksum    string  // optional
}

Phase 0.8b：不再需要 DownloadGrant（無 MC delegated token）；download flow 用同一個 FAAClient.Download() 拉 stream 後由 handler 中轉給 client。

2.4 mc_token_client.go（Phase 0.8b 移除）

整個檔案在 Phase 0.8b 移除。詳見 ADR-015。

原本職責：跟 MC 換 service token（client_credentials grant）+ 換 delegated download token。

Phase 0.8b 後：

• 服務間認證直接帶 Authorization: Bearer <pre-shared API key> — 不需 cache、不需 refresh、不需 retry MC
• download flow 退回 server-side proxy（visionA backend 中轉 stream），不再有 delegated token 概念

Tenant 概念取消：visionA → converter / FAA 不再帶 tenant_id；converter 端的 user_id 仍由 visionA 灌入（§7 trust boundary 不變）。

2.5 flow.go — 流程協調

type Flow struct {
    converter *ConverterClient
    faa       *FAAClient
    // Phase 0.8b：不再需要 tokens *MCTokenClient
    models    model.Repository      // 沿用既有 model store
    storage   storage.Store         // 沿用既有 LocalFS / S3
    ownership ownershipStore        // job_id → user_id mapping (in-memory map)
    
    statusCache *jobStatusCache     // 1-2s short cache，避免 frontend polling 直接打爆 converter
}

// 主要 method 對應 Service interface。
// PromoteToModels 內部：
//   1. ownership.Check(userID, jobID)
//   2. promotedKey, err := flow.ensurePromoted(ctx, jobID)  // 冪等：若已 promote 過用 cache，否則打 converter
//   3. reader, meta, err := faa.Download(ctx, promotedKey)
//   4. modelID, putURL, _ := callModelsInit(...)            // 直接呼叫 internal/api 同 package 既有 helper（不走 HTTP）
//   5. PUT 到 storage（或直接 io.Copy 到 storage.Put）
//   6. callModelsFinalize(...)
//   7. 在 model record 補 Source="converted" + SourceJobID=jobID
//   8. 回 modelID

冪等性：flow.ensurePromoted(jobID) 內部用 sync.Map 記 job_id → target_object_key；同 job 第二次 promote 直接回 cache，不打 converter。

2.6 ownership store（in-memory）

type ownershipStore interface {
    Set(jobID, userID string, expiresAt time.Time)  // 對齊 converter 7d 過期
    Get(jobID string) (userID string, ok bool)
    CleanupExpired()                                  // background goroutine 每 60s
}

雛形 in-memory；visionA-backend 重啟 → 所有「我的 job 列表」消失，user 等同失去對未完成 job 的後續操作能力（接受的取捨 — converter 端用 user_id 仍可查到，但 visionA UX 上看不到）。Phase 0.9 之後可改 DB persist。

2.6.1 visionA-backend 重啟後的 cold start 恢復（Phase 0.8 MVP 行為）

問題：使用者 A 上傳了一個 job，正在 processing；visionA-backend 重啟（部署新版、crash recovery）→ in-memory ownership store 全空；使用者 A 重新打開 /conversion 頁面，前端打 GET /api/conversion/active → backend 找不到任何 ownership → 回 has_active=false → 前端顯示「沒有進行中的轉檔」。

結果：使用者 A 看到一個假的「乾淨」狀態，認為什麼都沒發生；但 converter 端那個 job 仍在跑（且 converter 端「同 user 1 active job」邏輯仍生效），使用者 A 重新 submit 會撞 409。

Phase 0.8 MVP 的決策（接受的取捨）：

選項	描述	採用？
A1	維持現狀：重啟即遺失。靠 converter 7 天 expires_at 自然兜底	✓ Phase 0.8 採用
A2	啟動時對 converter 打 GET /api/v1/jobs?status=in_progress 重建所有 ownership	✗ Phase 0.8 不做
A3	把 ownership 寫進 DB / Redis	✗ Phase 0.9+ 評估
A4	啟動時對特定 user 才 lazy 重建（GET /active 時若 in-memory 沒有，去 converter 查該 user 的 active job）	✓ Phase 0.8 補上（新增）

A4 實作（Phase 0.8 補強）：

// flow.go ActiveJob 內部：
func (f *Flow) ActiveJob(ctx context.Context, userID string) (*conversion.Job, error) {
    // 1. 先查 in-memory ownership
    if jobID, ok := f.ownership.GetByUser(userID); ok {
        return f.GetJob(ctx, userID, jobID)
    }
    // 2. in-memory miss → fallback 對 converter 查（lazy rebuild ownership）
    job, err := f.converter.ListActiveJobsByUser(ctx, userID)
    if err != nil { return nil, err }
    if job == nil { return nil, nil }
    // 重建 ownership（用 converter 回的 created_at + 7d 推算 expires_at）
    f.ownership.Set(job.JobID, userID, job.CreatedAt.Add(7*24*time.Hour))
    return job, nil
}

前提：converter Phase 1 的 GET /api/v1/jobs?user_id=<id>&status=in_progress 必須可用。見 §11 跨團隊依賴。

為什麼選 A4 不選 A2：

• A2 啟動時批次掃所有 in_progress jobs：對 converter 是 hammer（重啟頻繁時尤甚），且大部分 jobs 重啟期間使用者根本沒在等
• A4 是 lazy（只有使用者主動進 /conversion 才查），cost 對應 user 行為，不會打爆 converter
• 取捨：使用者進 /conversion 時多 1 次 round-trip（< 200ms），對 UX 可接受

Wireframe / UX 對齊：Design wireframe §3.3 已 cover「進入頁面打 /active、有 active 直接落 processing」，A4 行為對 frontend 完全透明（同樣 endpoint、同樣 response shape）。

2.6.2 expires_at 的來源

屬性	規格
定義	converter 端對 job 做 7 天 GC 的截止時間
來源	converter 的 job record created_at + 7 days（converter Phase 1 的 GC 邏輯）
是否回傳給 visionA-frontend	✓ 是 — GET /api/conversion/{job_id} response 與 GET /api/conversion/active response 都帶 expires_at
visionA-backend 怎麼知道	優先從 converter response 直接讀；若 converter 沒給（Phase 1 的 OpenAPI spec 待確認），visionA-backend 自行 created_at + 7d 推算

待確認（given to DevOps / Backend Agent）：

• 確認 converter Phase 1 的 GET /api/v1/jobs/{id} 是否在 response 含 expires_at 欄位
• 若有 → internal/conversion/converter_client.go 的 Job struct 加 ExpiresAt time.Time，直接透傳
• 若無 → backend 在 Job 上補 ExpiresAt = CreatedAt.Add(7 * 24 * time.Hour)，前端永遠拿到 expires_at（無論來源）

Frontend 用途：

• completed.success 畫面顯示「6 天 21 小時後自動清除」倒數提示
• expires_at - now() ≤ 0 時切「已過期」狀態（wireframe §8.2）

---

3. 服務間認證（API key）— 取代 OAuth client_credentials

Phase 0.8b 變更：本節為新增；對應 ADR-015。

歷史：ADR-014 §5 原本設計為「visionA → MC POST /oauth/token 換 service token + cache + 帶 JWT 給 converter / FAA」。Phase 0.8 stage e2e 卡關（MC scope 沒註冊、converter image 舊、跨 repo 配合複雜）後，使用者決策改用 pre-shared API key。

3.1 取得流程

visionA-backend 啟動
    ↓
讀 cfg.Conversion.ConverterAPIKey（env VISIONA_CONVERTER_API_KEY）
讀 cfg.Conversion.FAAAPIKey（env VISIONA_FAA_API_KEY）
    ↓
[轉檔請求進來]
    ↓
converter_client / faa_client 發 request 時：
    req.Header.Set("Authorization", "Bearer "+apiKey)
    ↓
converter / FAA middleware：
    - parse Authorization header → 取 token
    - subtle.ConstantTimeCompare(token, envKey)
    - match → 放行；mismatch → 401 + log（不附原因）

沒有 token cache、沒有 refresh、沒有 retry MC、沒有 scope 驗證。整條鏈路是「visionA → 下游」一步。

3.2 Config 對齊

visionA-backend/internal/config/config.go 變更：

type ConversionConfig struct {
    ConverterBaseURL string `env:"VISIONA_CONVERTER_BASE_URL"`
    FAABaseURL       string `env:"VISIONA_FAA_BASE_URL"`
    ConverterAPIKey  string `env:"VISIONA_CONVERTER_API_KEY"`  // Phase 0.8b 新增
    FAAAPIKey        string `env:"VISIONA_FAA_API_KEY"`        // Phase 0.8b 新增
    // Phase 0.8b 廢棄欄位（為 backward compat 保留 struct field 但 conversion 不再使用）：
    // TenantID string `env:"VISIONA_OIDC_TENANT_ID"`
}

func (c ConversionConfig) Enabled() bool {
    return c.ConverterBaseURL != "" &&
           c.FAABaseURL != "" &&
           c.ConverterAPIKey != "" &&
           c.FAAAPIKey != ""
}

OIDCConfig.ServiceClientID / ServiceClientSecret 兩個欄位 Phase 0.8b conversion 不再依賴；如其他模組未使用即可從 struct 移除。env 端從 .env*.example 移除以免誤導。

新增的 stage env：

# .env.stage
VISIONA_CONVERTER_BASE_URL=http://192.168.0.130:9501
VISIONA_FAA_BASE_URL=http://192.168.0.130:5081
VISIONA_CONVERTER_API_KEY=<openssl rand -hex 32 產的值，與 converter 端 CONVERTER_API_KEY 對齊>
VISIONA_FAA_API_KEY=<openssl rand -hex 32 產的值，與 FAA 端 FAA_API_KEY 對齊>

# Phase 0.8b 移除：
# VISIONA_OIDC_SERVICE_CLIENT_ID
# VISIONA_OIDC_SERVICE_CLIENT_SECRET
# VISIONA_OIDC_TENANT_ID（conversion 不依賴；其他模組未發現使用）

3.3 啟動時驗證

api-server 啟動時 log 一行（不可 log key 本身）：

[INFO] conversion config: converter=http://192.168.0.130:9501 (api_key_set=true) faa=http://192.168.0.130:5081 (api_key_set=true)

若 Enabled() == false → conversion 模組整個 disabled（與 Phase 0.8 「partial deploy」相容，sidebar tab 仍會顯示但會回 503 service_busy）。

3.4 Key 產生 / 部署 / Rotate

項目	規格
長度	64 字元 hex（256 bit 熵） — openssl rand -hex 32
環境隔離	dev / stage / prod 各自獨立的 key，不重用
兩個下游	converter / FAA 各自一把，不共用
儲存（dev）	.env.dev（gitignore）
儲存（stage）	stage host .env.stage（不進 git）
儲存（prod）	AWS Secrets Manager / Vault
Rotate	runbook Phase 0.9 補；流程：產新 key → 雙方同步 env → restart → 驗證 → 拔舊 key
Log policy	永遠不印 key 全文；可印 api_key_set=true/false 或前 8 字元 prefix

3.5 Trust boundary 對齊

API key 證明的是「caller 是 visionA」（machine 身份）；user_id 的真實性由 visionA 內部的 OIDC cookie session 保證（user 身份）。兩條獨立鏈：

• machine auth：visionA → converter / FAA 用 API key
• user auth：browser → visionA 用 OIDC cookie session（既有，未變）
• visionA 是橋樑：從 OIDC sub 解出 user_id → 透過 multipart body / API path 灌進對下游的請求

詳見 §7。

---

4. 新增 visionA-backend API

詳細請求 / 回應 schema 見 api/api-conversion.md；這裡列總覽。

Method	Path	Auth	用途
POST	/api/conversion/init	OIDC cookie	上傳 + 建 job（multipart streaming）
GET	/api/conversion/{job_id}	OIDC cookie	查 job 狀態
POST	/api/conversion/{job_id}/promote-to-models	OIDC cookie	「加到模型庫」
GET	/api/conversion/{job_id}/download	OIDC cookie	「下載」— server-side HTTP 302 redirect 到 FAA delegated URL
GET	/api/conversion/active	OIDC cookie	查當前 user 有無 active job（frontend pre-check）；in-memory miss 時 fallback 對 converter lazy rebuild（§2.6.1）

不對外暴露但內部使用的 converter endpoint：GET /api/v1/jobs?user_id=&status=in_progress（§2.6.1 lazy rebuild）。Phase 0.8 frontend 看不到「歷史列表」UI，但後端會用此內部 endpoint 做韌性處理。

POST /api/v1/jobs/{id}/cancel：converter Phase 1 尚未實作（已驗證 routes/v1/jobs.js 與 openapi.yaml）。Phase 0.8 失敗 cleanup 採「socket close 自然 abort」（§5.3.2）；Phase 1 待 converter 補上 endpoint 後再升級為 best-effort 主動 cancel。

所有 endpoint 通用：

• 走既有 AuthMiddleware（internal/api/middleware/auth.go）
• 從 UserContextFrom(c) 拿 uc.UserID（OIDC sub）
• response 用既有 WriteSuccess / WriteError helper
• request_id 透傳給 converter（X-Request-Id header）

4.1 GET /api/conversion/{job_id}/download — Phase 0.8b：server-side stream proxy handler

變更：Phase 0.8（ADR-014 v1.1）原本是 c.Redirect(302, FAA_URL_with_delegated_token)；Phase 0.8b API key 模式下無 MC delegated token，改為 visionA backend 中轉 stream。

// GET /api/conversion/{job_id}/download
func conversionDownloadHandler(deps Deps) gin.HandlerFunc {
    return func(c *gin.Context) {
        uc, _ := UserContextFrom(c)        // AuthMiddleware 已驗
        jobID := c.Param("job_id")

        // service 內部完成：ownership 檢查 → ensurePromoted → 從 FAA pull stream
        stream, meta, err := deps.Conversion.DownloadStream(c.Request.Context(), uc.UserID, jobID)
        if err != nil {
            writeConversionError(c, err)   // §6 錯誤碼分類
            return
        }
        defer stream.Close()

        // streaming proxy 給 client（io.Copy；不暫存 disk / RAM 全 buffer）
        c.Header("Content-Type", meta.ContentType)
        if meta.SizeBytes > 0 {
            c.Header("Content-Length", strconv.FormatInt(meta.SizeBytes, 10))
        }
        // 鼓勵 browser 觸發 save dialog（filename 來自 promote 結果）
        c.Header("Content-Disposition", `attachment; filename="`+sanitizeFilename(meta.Filename)+`"`)
        c.Header("Cache-Control", "no-store, no-cache, must-revalidate, max-age=0")
        c.Status(http.StatusOK)
        io.Copy(c.Writer, stream)
    }
}

為什麼仍用 GET：

• frontend 用 <a href="..." download> 觸發 — anchor tag 只能發 GET
• GET semantically 對應「拿一個資源」，符合「下載這個 job 的結果」語意
• 既有 OIDC AuthMiddleware 會自然處理 GET 上的 cookie session，無 CSRF 風險（沒有狀態變更，promote 是冪等的）

Frontend 使用範例（與 Phase 0.8 一致，無需改動）：

<!-- 推薦：anchor tag，browser 自動處理 navigation + 收 attachment -->
<a href={`/api/conversion/${jobId}/download`} download>下載</a>

或：

// 程式化觸發
window.location.href = `/api/conversion/${jobId}/download`;

安全性面比較（Phase 0.8 → Phase 0.8b）：

面向	Phase 0.8（302 redirect + MC delegated token）	Phase 0.8b（server-side stream proxy）
Token 在 frontend JS / URL bar	△ 短暫（Location header 流經 browser，nav 完即消失）	✓ 結構性不存在（無 token 概念）
要 FAA CORS	✓ 不需要（navigation 不適用 CORS）	✓ 同 — visionA 為 same-origin，FAA 直連在 server-side
跨 internet 流量（同 NEF 多次下載）	✓ 直連 FAA、N× 流量算 FAA 出	✗ 每次都繞 visionA backend，N× 流量算 visionA 出
visionA backend 是否變 streaming bottleneck	✓ 不是	✗ 是 — Phase 0.8 MVP user 量小可接受；Phase 1 量大需改 ADR-015 §7 選項 B
認證鏈簡化	✗ 需要 MC scope files:download.delegate	✓ 一把 API key 解決

Phase 1 升級路徑：如量大需回 302 redirect 模式，採 ADR-015 §7 選項 B（visionA 自己簽 short-TTL HMAC token，FAA middleware 多支援「visionA HMAC」路徑）。

---

5. Streaming proxy 設計（upload）

5.1 為什麼要 streaming

• 模型上限 500MB；ref_images 100×10MB = 1GB 上限
• 全 buffer 在 RAM → 同時 N 個 user upload 直接 OOM
• 暫存 disk → 增加 IO 與磁碟空間需求；壞掉的 cleanup 麻煩

5.2 實作 pattern

// handler 收到 request：
func conversionInitHandler(deps Deps) gin.HandlerFunc {
    return func(c *gin.Context) {
        uc, _ := UserContextFrom(c)
        userID := uc.UserID
        
        ct := c.GetHeader("Content-Type")
        if !strings.HasPrefix(ct, "multipart/form-data") {
            WriteError(c, 400, ErrCodeValidationFailed, "expect multipart/form-data", nil)
            return
        }
        
        // 同 user active job pre-check
        if active, _ := deps.Conversion.ActiveJob(c.Request.Context(), userID); active != nil {
            WriteError(c, 409, ErrCodeActiveJobExists,
                "user has active job", map[string]any{"job": active})
            return
        }
        
        // service 內部做 streaming
        job, err := deps.Conversion.InitJob(c.Request.Context(), conversion.InitJobInput{
            UserID:        userID,
            ContentType:   ct,
            Body:          c.Request.Body,
            ContentLength: c.Request.ContentLength,
        })
        // ... error handling
    }
}

// service 內部 (flow.go InitJob)：
func (f *Flow) InitJob(ctx context.Context, in conversion.InitJobInput) (*conversion.Job, error) {
    pr, pw := io.Pipe()
    mw := multipart.NewWriter(pw)
    
    // goroutine：解 client 的 multipart，重新寫到 mw
    errCh := make(chan error, 1)
    go func() {
        defer pw.Close()
        defer mw.Close()
        
        mr, err := readerFromContentType(in.Body, in.ContentType)
        if err != nil { errCh <- err; return }
        
        // 先寫 user_id（重點：visionA backend 灌的，不是 client 灌的）
        if err := mw.WriteField("user_id", in.UserID); err != nil { errCh <- err; return }
        
        for {
            part, err := mr.NextPart()
            if err == io.EOF { break }
            if err != nil { errCh <- err; return }
            
            name := part.FormName()
            
            // 黑名單：client 不允許自己塞 user_id
            if name == "user_id" {
                continue  // 忽略，用我們自己灌的
            }
            
            if part.FileName() == "" {
                // form field：直接複製
                fw, err := mw.CreateFormField(name)
                if err != nil { errCh <- err; return }
                if _, err := io.Copy(fw, part); err != nil { errCh <- err; return }
            } else {
                // file part：streaming copy
                fw, err := mw.CreateFormFile(name, part.FileName())
                if err != nil { errCh <- err; return }
                if _, err := io.Copy(fw, part); err != nil { errCh <- err; return }
            }
        }
        errCh <- nil
    }()
    
    // 同步 POST 到 converter
    job, err := f.converter.CreateJobStream(ctx, mw.FormDataContentType(), pr, -1)
    
    // 等 goroutine 結束
    if goErr := <-errCh; goErr != nil && err == nil {
        err = goErr
    }
    
    if err != nil { return nil, mapConverterError(err) }
    
    f.ownership.Set(job.JobID, in.UserID, time.Now().Add(7*24*time.Hour))
    return job, nil
}

關鍵點：

1. io.Pipe 把「client 端 reader → converter 端 writer」串接，期間記憶體只有 multipart.Reader 的 buffer（≈ 64KB 預設）
2. 必須先寫 user_id field（順序：user_id 在 model file 之前，避免 converter multer 解析時 user_id 還沒到就拒絕）
3. 黑名單 user_id：忽略 client 帶的 user_id，永遠用 visionA-backend 自己灌的
4. context cancellation：handler 收到 client disconnect → ctx.Done() → goroutine 自動結束（pw.Close 觸發 reader EOF）
5. 不做 ContentLength forward（converter 自己 multer 算）

5.3 進度 / 取消

5.3.1 進度語意（重要：給 Frontend / Design 對齊）

XHR upload.onprogress 計算的是 browser → visionA-backend 的進度，不是 browser → backend → converter 的端到端進度。在 streaming proxy 模式下，這兩者有時間差：

T0: browser 開始上傳
    └─ XHR onprogress 持續更新（loaded / total）
T1: browser 已 send 完全部 bytes（XHR 進度 100%）
    └─ 但 backend → converter 的 io.Pipe 可能還在繼續流（buffer 內未消化）
T2: backend 把全部 bytes forward 完給 converter
    └─ 這時候才拿到 converter 的 201 + job_id
T3: backend 200 回 frontend

設計選擇（Phase 0.8 MVP）：visionA-backend 等到 T2（converter 回 201）才回 200，不 early-return。

屬性	選項 A：等 converter 201 才 200 ✓ 採用	選項 B：browser send 完就 200，背景 forward
Frontend 進度條精確度	100% 接近端到端真實狀態	進度 100% 後還有未知延遲 → 假象
UX 延遲感	多等 1-3 秒（io.Pipe drain）	立即切 processing 畫面
backend 實作複雜度	低（直接同步等）	高（需要 background goroutine + ownership 標 upload_in_progress + 額外狀態管理）
失敗處理複雜度	低（同步錯誤直接回 frontend）	高（背景 forward 失敗時 frontend 已切 processing，要額外 push 錯誤通知）

選項 A 的 UX 補償：當 XHR loaded === total 但 backend 還沒回 200 時，frontend 顯示 即將完成… / 伺服器處理中…（對齊 flow-conversion.md §5.3，本文件 §5.3.1）。這明確告訴使用者「browser 端已送完，正在等 server 收尾」，不是欺騙性的進度條。

Phase 1 升級路徑：若 Phase 1 量大需要更精準的端到端進度，可改成 SSE 推送 upload_progress 事件（backend 主動報「已 forward N bytes 給 converter」），但 Phase 0.8 MVP 不做。

5.3.2 Cancel 與 Cleanup 鏈（重要）

情境分類：

情境	觸發	backend 行為
C1：使用者按「取消上傳」	frontend xhr.abort()	TCP RST → backend c.Request.Context().Done() → goroutine cleanup（見下）
C2：使用者重新整理 / 關分頁	browser 中斷 connection	同 C1
C3：網路斷線	TCP timeout	同 C1
C4：backend 偵測 converter 拒絕（4xx/5xx）	converter response	立即回 frontend，不需特別 cleanup（converter 自己沒建 job）

C1-C3 的 cleanup 鏈：

client disconnect
    ↓
gin handler `c.Request.Context().Done()` 觸發
    ↓
streaming goroutine 的 `pw.Close()` defer 執行 → io.Pipe reader 收到 EOF/error
    ↓
converter HTTP request 的 body read 端拿到 EOF
    ↓
converter multer 偵測 incomplete multipart → 拒絕收 job（不會建 job_id）

但：上面的鏈在「backend 已經把 multipart header 寫進去、converter 已建 job_id、stream 還在 forward 中」這個區間斷線時，converter 端可能已經建立 job 但收不完 body。實測上 converter（Phase 1）的行為是：

• 收不完 body → multer 拋錯 → 該 job 留在 failed 狀態 + error_code=invalid_multipart
• 該 user 的 active_job 邏輯：converter 把 failed 視為 active job 結束，下次 init 不會撞 409

為了避免「converter 視為 active 但 visionA 不知道」的孤立 job 風險，依 converter 是否提供 /cancel endpoint 採不同策略：

Phase 0.8 限制（重要 — 已驗證實作狀態）

converter Phase 1 並未實作 POST /api/v1/jobs/{id}/cancel endpoint。

已驗證範圍：apps/task-scheduler/src/routes/v1/jobs.js 只有以下路由：

• POST /api/v1/jobs/（建立 job）
• GET /api/v1/jobs/（list）
• GET /api/v1/jobs/:id（單一狀態）
• POST /api/v1/jobs/:id/download-tokens（issue download token）
• DELETE /api/v1/jobs/:id（刪 job — 是 hard delete 而不是 cancel running job）

openapi.yaml 也沒有 cancel 路徑或 example。

因此 Phase 0.8 採「socket close 自然 abort」策略：

client disconnect / streaming body 中斷
    ↓
converter multer 拋 invalid_multipart
    ↓
該 job 留 failed + error_code=invalid_multipart
    ↓
converter 對 active_job 邏輯視為已結束（failed 不算 active）
    ↓
下次 init 不會撞 409

visionA-backend 在 InitJob 失敗時不主動發 cancel（沒有對應 endpoint 可發）；只在 log 紀錄失敗事件，依靠 converter 自然 abort 收尾。

Phase 1+ 升級路徑（converter 補上 /cancel 之後）

當 converter 上線 POST /api/v1/jobs/{id}/cancel 後，visionA-backend 升級為 best-effort 主動 cancel：

// flow.go InitJob 內部，goroutine 結束後若 err != nil 且我們已拿到 job_id：
if goErr != nil && job != nil && job.JobID != "" {
    // 用獨立 timeout（不繼承已 cancel 的 ctx），失敗只 log
    cancelCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
    defer cancel()
    if cancelErr := f.converter.CancelJob(cancelCtx, job.JobID); cancelErr != nil {
        logger.Warn("best-effort cancel failed", "job_id", job.JobID, "err", cancelErr)
    }
}

動工項：

1. T3 ConverterClient interface 新增 CancelJob(ctx context.Context, jobID string) error
2. flow.go InitJob 失敗路徑加上面的 best-effort cancel block
3. 補對應 unit test（mock converter 收到 cancel call）
4. 對齊 §9.1 retry 矩陣的「Converter POST /jobs/{id}/cancel（內部 cleanup）」row

C1 特別處理（使用者按「取消上傳」）：frontend 在 xhr.abort() 之前不應先打 cancel API（多此一舉，TCP RST 即已觸發 cleanup）；後端會自動處理。

5.3.3 既有 4.3 內容（保留）

• 進度：visionA-backend 不做進度回報；frontend 用 XHR upload.onprogress 自己顯示（既有前端模式）
• 取消：context.Cancel（client 斷線）→ 連帶 cancel converter request（如上 cleanup 鏈）；converter 端 multer 收到 socket close 會自動 abort multipart parsing

5.4 Timeout

• handler 整體不設總 timeout（500MB upload 可能 5-10 分鐘）
• 但每個 io.Copy 之間用 http.Server.WriteTimeout/IdleTimeout 控制 keep-alive；具體值由 DevOps 在 Nginx / ingress 設定（建議 600s）

---

6. 錯誤碼 mapping + i18n key

Phase 0.8b 變更：移除所有「MC token」相關錯誤碼（idp_misconfigured / idp_unavailable / download_token_failed / mc_token_unavailable）— 服務間認證已不再經 MC。新增「API key 驗證失敗」錯誤碼（visionA 端不直接面對，但下游若回 401 要處理）。

Converter / FAA error	visionA error code	HTTP	i18n key	user-friendly 訊息（zh-TW）
converter validation_error	validation_failed	400	conversion.error.validation	上傳的檔案不符合要求（請查看詳細欄位錯誤）
converter invalid_multipart	validation_failed	400	conversion.error.invalid_multipart	上傳格式錯誤，請重新嘗試
converter user_has_active_job	active_job_exists	409	conversion.error.active_job	你目前已有進行中的轉檔任務
converter file_too_large	payload_too_large	413	conversion.error.too_large	檔案超過大小限制
converter service_busy	service_busy	503	conversion.error.busy	系統繁忙，請稍後再試
converter storage_unavailable	converter_unavailable	502	conversion.error.converter_down	轉檔服務暫時無法使用
converter 5xx / network	converter_unavailable	502	conversion.error.converter_down	同上
converter 401（API key 不對 / 過期 / rotate 未同步）	converter_auth_failed	502	conversion.error.converter_down	轉檔服務暫時無法使用（內部 log 區分 auth_failed vs 5xx）
FAA 5xx / network	faa_unavailable	502	conversion.error.faa_down	檔案存取服務暫時無法使用
FAA 401（API key 不對 / 過期 / rotate 未同步）	faa_auth_failed	502	conversion.error.faa_down	檔案存取服務暫時無法使用（內部 log 區分 auth_failed vs 5xx）
job 不屬於當前 user	forbidden	403	conversion.error.forbidden	你無權存取此轉檔任務
job_id 不存在	not_found	404	conversion.error.not_found	轉檔任務不存在
job 還沒 completed	job_not_completed	409	conversion.error.not_completed	任務尚未完成，請等轉檔完成再下載

Phase 0.8b 移除的錯誤碼（與 MC token 相關，認證路徑取消後不會發生）：

已移除	原來語意	Phase 0.8b 替代
idp_misconfigured（500）	MC token endpoint 回 4xx（scope 沒註冊 / client 設錯）	—
idp_unavailable（503）	MC token endpoint 5xx	—
download_token_failed（502）	MC delegated token 4xx	—
mc_token_unavailable（502）	MC 持續失敗	—

下游 401 對待原則：

• 對 visionA 端而言，下游 401 是「部署設定錯誤」（API key 不對齊）— 跟「使用者沒登入」（visionA → frontend 401）完全不同層次
• visionA 從 converter_client / faa_client 收到 401 → log error（含 request_id，方便 SRE 排查）→ 回 frontend 502 converter_auth_failed / faa_auth_failed，不要對 frontend 暴露「API key 不對」這個內部細節
• 401 不 retry（同 §9）— rotate 流程不同步是運維事件，需人工介入

i18n key 命名：conversion.error.<short-name>，前端 i18n 字典在 visionA-frontend/messages/{zh-TW,en}.json 補。

/download endpoint 錯誤回應策略（GET + server-side stream proxy 場景）：

由於 GET /api/conversion/{job_id}/download 採 server-side stream proxy（Phase 0.8b 變更），錯誤情況直接走既有 WriteError helper 依 Accept header 回應：

• Accept: application/json → 回標準 visionA error JSON {success:false, error:{code, message}}
• Accept: text/html（一般 anchor tag / window.location.href 觸發）→ 回 HTML 錯誤頁；browser 直接顯示
• 其他 → 預設 JSON

frontend 用 <a href> 觸發時，若失敗 browser 會把錯誤頁顯示在頁面上。Phase 0.8 不要求 inline 錯誤 UX。

---

7. user_id 注入與 trust boundary

7.1 唯一可信任點

┌──────────────────────────────────────────────────────────────┐
│  visionA-backend conversion handler                          │
│                                                              │
│   AuthMiddleware → UserContext (OIDC sub from cookie)        │
│         ↓                                                    │
│   conversion.Service.InitJob(InitJobInput{UserID: <sub>})    │
│         ↓                                                    │
│   flow.go InitJob                                            │
│     ├─ multipart streaming 重組（黑名單 client 帶的 user_id）│
│     ├─ mw.WriteField("user_id", <sub>) ← 唯一灌入點         │
│     └─ POST converter /api/v1/jobs                          │
└──────────────────────────────────────────────────────────────┘

7.2 Ownership 檢查

每個 GET / promote / download / models 操作都先檢查 ownership.Get(jobID) == userCtx.UserID，不符 → 403 forbidden。

7.3 客戶端不可信原則

• frontend / browser 帶來的 user_id 永遠忽略（streaming 重組時黑名單）
• frontend / browser 帶來的 object_key 永遠忽略（GET /download 不接受 client 指定 object_key，從 visionA 內部 promote 結果反查）
• frontend 只能告訴我們 job_id，其他都從 server side 推

---

8. Non-Goals（Phase 0.8 不做）

對齊 PRD Phase 0.8 邊界：

項目	Phase 0.8 行為	Phase 1+ 計畫
SSE / WebSocket 進度推送	frontend HTTP polling，間隔 2s	SSE endpoint /api/conversion/{id}/events
取消 job	不提供；user 等 converter 自己跑完或 7 日後 expires	POST /api/conversion/{id}/cancel
Job 歷史列表	不提供；in-memory map 重啟即清	DB persist + GET /api/conversion/history
同 user 多個 active job	強制 1 個（pre-check + converter 409 透傳）	沿用 converter 限制（短期內無計畫放寬）
多 chip 同時轉	一次只能選一個 target_chip	Phase 1 後評估
Webhook（converter 完成 push）	不接收	converter Phase 2 才提供
大量批次 upload	不支援	不在路線圖

---

9. 失敗模式 & retry 矩陣

9.1 retry 規則

Phase 0.8b 變更：移除 MC 兩 row；下游 401/403（API key 不對）一律不 retry。

操作	401 / 403	4xx 其他	5xx	network / timeout	max retry	退避
Converter POST /jobs	不重試（auth_failed）	透傳	retry	retry	2	1s, 2s
Converter GET /jobs/{id}	不重試	透傳	retry	retry	3	0.5s, 1s, 2s
Converter POST /jobs/{id}/cancel（內部 cleanup，Phase 1+）	不重試	不重試	不重試	不重試	0	best-effort（失敗只 log）；Phase 0.8 converter 未實作此 endpoint，靠 socket close 兜底（§5.3.2）
Converter GET /jobs?user_id=&status=in_progress（lazy rebuild）	不重試	透傳	retry	retry	1	0.5s
Converter POST /promote	不重試	透傳	retry	retry	2	1s, 2s
FAA GET /files/{key}（s2s download / s2s pull）	不重試	透傳	retry	retry	2	1s, 2s

每次 retry 之間檢查 ctx.Done()；ctx cancel → 立即 return ctx.Err()。

401 不重試的理由：API key 是 long-lived secret，rotate 同步是運維事件、不是瞬時抖動。401 通常意味「visionA env 與下游 env 不同步」，retry 100 次也不會自己變對，反而浪費 latency 並掩蓋運維事件。直接回 502 *_auth_failed 讓 SRE 看到。

9.2 graceful degradation

場景	處理
converter 完全不可達（持續 5xx）	502 converter_unavailable，UI 提示「轉檔服務暫時無法使用，請稍後再試」
converter 回 401（API key 不同步）	502 converter_auth_failed，UI 同上文字；SRE 從 log 看到 auth_failed 計數異常 → 檢查 env
完成後 promote 失敗（converter 5xx）	job 留在 completed 狀態（FAA 上沒檔但 visionA 知道），UI 給 user 「重試 promote」按鈕（重打 promote-to-models / download）
FAA pull 失敗 — 加到模型庫流程（5xx）	model record 不寫入；UI 提示重試
FAA pull 失敗 — 下載流程（5xx）	visionA backend 中轉時 503 / 502，UI 提示重試（Phase 0.8b 兩條 download path 都共用 visionA → FAA pull）
FAA 回 401（API key 不同步）	502 faa_auth_failed，UI 文字「檔案存取服務暫時無法使用」；SRE 從 log 排查
visionA-backend 重啟	in-memory ownership 與 promoted_key cache 全失，frontend 進 /conversion 時 /active lazy rebuild（§2.6.1）；rebuild 不到的 job 由 converter 7 天 expire 自然兜底

9.3 同 user active job 衝突

[Frontend init] → [visionA POST /api/conversion/init]
       ↓
   visionA pre-check (ownership store)
       ├── 有 active job → 409 active_job_exists（不打 converter）
       └── 沒 → 透傳給 converter
                 ├── converter 200 → 寫 ownership → return
                 └── converter 409 user_has_active_job → 透傳 frontend
                     （罕見：visionA 的 ownership 與 converter 不同步，
                     例如 visionA 重啟後遺失 mapping；以 converter 為準）

---

10. 安全考量

10.1 visionA-backend 是 user_id 灌入唯一點

詳見 §7。任何繞過此原則的設計都必須先過 ADR review。

10.2 Delegated download token TTL（Phase 0.8b 移除）

Phase 0.8b 不再有 delegated download token；download 走 server-side stream proxy。原段落（5 分鐘 TTL、VISIONA_FAA_DELEGATED_TTL_SECONDS env）刪除。

Phase 1+ 若量大改 ADR-015 §7 選項 B（visionA 自簽 HMAC token），那時再回設 TTL 規格。

10.3 Pre-shared API key 保護（取代 Service token 保護）

• VISIONA_CONVERTER_API_KEY / VISIONA_FAA_API_KEY 不可進 git（既有 .gitignore 含 .env*，配合 !.env*.example）
• 部署用 AWS Secrets Manager / k8s Secret 注入
• log 永遠不印 key 全文；可印 api_key_set=true 或前 8 字元 prefix（debug 用）
• 若 key 洩漏：產新 key → 雙方同步 env → restart visionA / converter（或 FAA）→ 驗證 → 拔舊 key（runbook Phase 0.9 補）
• 已洩漏的 stage service client secret RciRUyi... 改 API key 後直接作廢，無 rotate 動作

10.4 Object key 不暴露給 frontend JS

• Phase 0.8b：visionA-backend 透過 server-side stream proxy 把 NEF stream 中轉回 browser，FAA URL / object_key 都不出現在任何 frontend response
• frontend JS 對 object_key / 內部 FAA 路徑完全沒有 reference
• 防快取：handler 設 Cache-Control: no-store, no-cache, must-revalidate，避免 browser cache NEF stream
• 不需 FAA CORS：visionA → FAA 是 server-side 同進程內 outbound HTTP call，不適用 CORS（CORS 只管 browser JS fetch / XHR）
• visionA backend 是 attack surface：任何能拿到 visionA cookie session 的 attacker 都能下載自己 user_id 的 NEF — 但這本來就是 user 自己的檔，無 escalation

10.4b Phase 0.8 → Phase 0.8b 安全面遷移摘要

面向	Phase 0.8（302 + delegated token）	Phase 0.8b（server-side proxy）
Token 結構是否存在	是（MC issue，5 分鐘 TTL）	否
攻擊者攔截 visionA → browser response 拿到 token	短期可用 5 分鐘	結構性無 token
Frontend XSS 影響範圍	短 TTL token	無 token 可竊
Server compromise（visionA backend 被攻破）	攻擊者可簽任意 MC delegated token	攻擊者拿到 API key 後可任意打 converter / FAA
Defense in depth	Token TTL + scope 限制	API key + visionA OIDC 上游 user auth
結論	兩者都安全可接受；Phase 0.8b 取捨「實作簡化 + bottleneck」換「無 token in browser 的更乾淨模型」

10.5 Race condition

• 同 user 同時兩 tab init → 第一個成功寫 ownership / converter 接受；第二個 pre-check 通過但 converter 409
• 兩 tab 同時 promote-to-models → 第一個寫 model record 成功；第二個重複呼叫 ensurePromoted（cache hit）→ FAA pull 兩次（接受的取捨；FAA 端冪等）→ models repo 寫入時可能撞 model_id 衝突 — 改用 model_id 在 finalize 前 SELECT 檢查
• 兩 tab 同時 download → visionA backend 各自獨立 FAA pull（無 cache）；兩條 stream 同時跑、兩條都成功（FAA 端冪等讀）— Phase 0.8b 可接受，量大時再加 server-side stream cache

10.6 DoS 防護（最小集，Phase 1 強化）

• 同 user 1 個 active job 的限制本身就是 DoS 防護（user 不能 init 1000 個 job）
• visionA-backend conversion endpoint 不額外 rate limit（Phase 1 補；對齊 security.md §4）
• converter 端有 process semaphore（max 5 concurrent upload）保底

---

變更影響清單

實作此 spec 會動到的檔案（給 Backend Agent 參考；Backend 自己拆任務）：

Phase 0.8b 變更（在 Phase 0.8 已上的 code 上面動）：

• 砍：visionA-backend/internal/conversion/mc_token_client.go（~440 行整檔刪除）
• 砍：visionA-backend/internal/conversion/mc_token_client_test.go（對應 test）
• 改：visionA-backend/internal/conversion/converter_client.go — 移除 tokens *MCTokenClient 欄位，改 apiKey string；每個 method 內 Authorization: Bearer <apiKey> 直接 set
• 改：visionA-backend/internal/conversion/faa_client.go — 同上模式
• 改：visionA-backend/internal/conversion/flow.go — 移除 tokens 欄位；download path 從 DownloadRedirectURL 改為 DownloadStream（從 FAA pull stream 回給 caller）
• 改：visionA-backend/internal/conversion/conversion.go — Service interface DownloadRedirectURL 改為 DownloadStream(...) (io.ReadCloser, *DownloadMetadata, error)
• 改：visionA-backend/internal/api/conversion.go — conversionDownloadHandler 從 c.Redirect(302, ...) 改為 io.Copy(c.Writer, stream) + 設好 Content-Type / Content-Disposition / Cache-Control
• 改：visionA-backend/internal/config/config.go —
  • ConversionConfig：新增 ConverterAPIKey / FAAAPIKey 兩欄位
  • ConversionConfig.Enabled() 加入兩個 API key 非空檢查
  • OIDCConfig.ServiceClientID / ServiceClientSecret：conversion 不再依賴；如其他模組未使用即從 struct 移除（檢查 grep）
  • ConversionConfig.TenantID：conversion 不再依賴；如其他模組未使用即移除
• 改：visionA-backend/cmd/api-server/main.go — wire conversion.Flow 時不再傳 MCTokenClient；改傳兩個 API key
• 改：.env.stage.example / .env.dev.example — 移除 VISIONA_OIDC_SERVICE_CLIENT_ID / _SECRET / VISIONA_OIDC_TENANT_ID；新增 VISIONA_CONVERTER_API_KEY / VISIONA_FAA_API_KEY
• 改：對應的 unit test / integration test — 移除 MC mock；改用 fake converter / FAA server，驗 Authorization: Bearer <apiKey> header 正確帶上
• 不動：internal/model/*（schema 不變）
• 不動：internal/api/models.go（既有 init/finalize 不動，flow.PromoteToModels 內部呼叫 helper）
• 不動：OIDC user login 相關全部（internal/oidc/、internal/usersession/、/api/auth/* handlers）

---

版本記錄

日期	版本	變更
2026-04-30	0.1	初稿 — Phase 0.8 轉檔整合 TDD
2026-04-30	0.2	Download flow 改為 server-side HTTP 302 redirect：endpoint 從 POST /{job}/download-token 改為 GET /{job}/download、Service interface DownloadToken → DownloadRedirectURL、DownloadGrant 改為 mc_token_client 內部 struct（不對外 JSON）、補 §3.1 handler 範例、補 §10.4 token 不過 frontend JS 的安全分析、§6 補 /download 錯誤回應策略
2026-04-30	0.3	Phase 0.8 三方交叉審閱回饋整合：§2.6.1 補「visionA-backend 重啟後 lazy rebuild ownership」（議題 #2，A4 方案）；§2.6.2 補 expires_at 來源（議題 #7）；§4.3.1 streaming proxy 進度語意明確化（議題 #6，採選項 A：等 converter 201 才回 200）；§4.3.2 補 cancel cleanup 鏈與 best-effort cancel converter（議題 #5）
2026-05-11	0.4	Phase 0.8b：服務間認證從 OAuth client_credentials 改為 pre-shared API key（對應 ADR-015）。主要變更：(1) §1 端對端 sequence 拿掉 MC node；(2) §2 砍 mc_token_client.go 整個檔；(3) §3 新增「服務間認證（API key）」章節（原 §5 OAuth 章節整段刪除，章節編號 4→5）；(4) §4.1 /download handler 從 c.Redirect(302) 改 server-side stream proxy（Service interface DownloadRedirectURL → DownloadStream）；(5) §6 錯誤碼 mapping 移除 MC 4 個 code、新增 converter_auth_failed / faa_auth_failed；(6) §9.1 retry 矩陣移除 MC 2 row、所有下游 401/403 不重試；(7) §10.2 刪除 delegated token TTL、§10.3 改為 pre-shared API key 保護、§10.4 改為 server-side stream proxy 安全模型；(8) 變更影響清單列出 backend agent 後續實作要動的 .go 檔。OIDC user login 完全不動。