提交版本

誰：部門管理者。端點： POST /worker/versions（multipart）。CLI 會幫你做完這一切（teamsync-worker submit）；這一頁是線上契約。還沒有 CLI？可以從範本開始，或取得你的後端所提供的 CLI：範本與原始碼下載。

請求

恰好一個 multipart part：


POST {BASE}/private/module/edge-workers/worker/versions
Authorization: Bearer <jwt>
Content-Type: multipart/form-data; boundary=…

field name:    project
filename:      department-worker.tar.gz     (exactly)
content type:  application/gzip             (exactly)
body:          the deterministic archive (≤ 2 MiB)

用 teamsync-worker pack --out department-worker.tar.gz 產生壓縮檔 — 必須是確定性格式（gzip 時間戳歸零、tar metadata 固定、路徑排序）；一般 tar czf 產生的壓縮檔會被拒絕：API 回應 422 project_invalid（見下），其背後的 builder 代碼是 project_archive_not_deterministic。CLI 不會為手工建出的壓縮檔顯示該代碼，因為 teamsync-worker validate、pack 與 submit 一律自己從專案目錄建出確定性壓縮檔。三種壓縮檔可以原封不動上傳：pack 的輸出、範本現成的 department-worker.tar.gz，以及從 GET /worker/versions/{version_id}/source 下載的壓縮檔（範本與原始碼下載）。

成功 — 201


{
  "worker":  { "id": "…", "status": "draft|active|paused", "latest_revision": N, "current_version_id": …, … },
  "version": { "id": "…", "revision": N, "state": "ready", "manifest_digest": "…", "bundle_digest": "…",
               "sbom": { /* CycloneDX 1.6 */ }, "build_receipt": { /* receiptVersion "1" */ }, … }
}

首次提交也會建立單例 Worker（status: "draft"）。記下 version.id 與 worker.latest_revision — 部署要用。此時還沒部署任何東西。

失敗分支

狀態	意義	你會看到
413	外層 > 2 162 688 B，或壓縮檔 part > 2 MiB	`Worker submission request exceeds limit`／`project archive exceeds 2097152 bytes`
422	外層形狀	`project_multipart_invalid`、`project_archive_filename_invalid`、`project_archive_content_type_invalid`、`project_archive_required`、`project_archive_invalid`（非 gzip）
422	builder 拒絕（任何原因）	`detail: [{loc: ["body","project"], type: "project_invalid", msg: "project failed the locked Worker build policy"}]` — 具體的 builder 代碼（例如 `manifest_route_ambiguous`）不會出現在回應裡。用同一個後端提供的 CLI 執行 `teamsync-worker validate` 才看得到（目錄）
422	manifest 重新驗證	`type: "manifest_v2_invalid"`，`msg` 為 `root teamsync.worker.json is not a valid Worker manifest v2`（或 `root teamsync.worker.json must contain valid Unicode`）— builder 接受了專案，但後端對回傳 manifest 的自我檢查失敗
409	併發的首次提交比你快	`a Worker already exists for this department` — 重新 `GET /worker` 再提交；修訂版計數器現在屬於那個 Worker
503	builder 無法使用，或其證據被拒絕	帶代碼的 `detail`：`{"code": "builder_unavailable", "message": "Department Worker builder is unavailable"}`；`{"code": "builder_invalid_output", "message": "Department Worker builder is unavailable"}` 或 `{"code": "builder_invalid_output", "message": "Department Worker builder returned invalid evidence"}` — 稍後重試；什麼都沒建立
503	產物儲存無法使用	`Edge Worker artifact storage is unavailable`、`Edge Worker artifact compensation is unavailable` — 稍後重試；什麼都沒建立
503	provider 未設定	`Edge Worker provider is not configured` — 最先檢查，在任何壓縮檔檢查之前；是部署環境的 `EDGE_WORKERS_PROVIDER` 設定或地端設定有誤，屬於營運方的問題；什麼都沒建立

伺服器端發生的事

provider 關卡 → 外層關卡 → 無憑證建置（驗證 + 打包 + SBOM + 回執）→ 提交清理意圖 → 產物儲存上傳 → 單一交易建立 ready 修訂版並收養意圖。確定性：同一壓縮檔在同一 builder 政策下重新提交會得到相同摘要（但新的修訂版 — 修訂版是只增的階梯）。每個修訂版都以後端目前的 builder 政策建置（5.22.0 為 department-worker-project-v2.10），政策決定它的 release 能用什麼：要讓較舊的 Worker 使用 Worker 機密、逐操作存取或服務帳號，請重新上傳專案並部署新的修訂版（能力表）。細節：提交管線。

取回已提交的壓縮檔

GET /worker/versions/{version_id}/source（部門管理者）會回傳 Worker 任何版本（含已被取代的版本）所儲存的壓縮檔：200 application/gzip，位元組與提交時完全相同，檔名 department-worker.tar.gz。它的 SHA-256 等於該版本的 project_digest。可以編輯後把結果當作新修訂版提交，或原封不動重新提交。完整契約、錯誤表與壓縮檔內容：範本與原始碼下載。

下一步：部署與輪詢。