端點

一切的 base 前綴：{BASE}/private/module/edge-workers。這個 router 刻意掛在一般 private router 之外：一般 private 通道也接受 x-api-key，Edge Workers 只收 JWT（只帶 API key 的請求會拿到 418，見驗證）。光有有效 JWT 還不夠：呼叫者必須是存活的真人使用者，所以服務帳號的 JWT 在每一條路由都會被 403 拒絕（成員路由回 Service accounts cannot invoke Edge Workers；管理者與公司管理者路由上，它的角色 0 已先過不了角色門檻，回 Insufficient permissions.）。以下路徑省略前綴。

OpenAPI tags：每個 sub-router 一個 Module: Edge Workers - <Resource> tag（Worker、Access Policy、API Key、Runtime Config、Operation Settings、Secrets、Versions、Deployments、OpenAPI、Starters、Service Accounts、Company Operations）；十條 invoke 路由是隱藏的（include_in_schema=False）。截至後端 5.22.0：文件化操作共 43 條 — 主 router 25 條、starter 路由 4 條、服務帳號路由 14 條（部門範圍 7 條 + 同樣 7 條鏡像在 /company/departments/{department_id} 之下）。

權限關卡（細節見驗證）：

• 成員 = 任何有存活所屬部門的 JWT 使用者；
• 管理者 = JWT 角色 ≥ CAN_MANAGE_DEPARTMENT（預設 2），且作用於自己的部門；
• 管理者 + 設定鎖 = 管理者，再取得部門的操作設定鎖（與部署請求、服務帳號重設／刪除共用）：已被持有 → 409 {"code": "deployment_in_progress", "message": "Another Worker settings mutation or deployment is in progress"}，鎖儲存無法使用 → 503 Operation-settings mutation lock is unavailable；
• 公司管理者 = JWT 角色 ≥ CAN_MANAGE_COMPANY（預設 3）。

在這些關卡之前，共用的 JWT dependency 會先回應：沒有 token、token 無法解碼，或非 JWT 憑證（例如 x-api-key，一律不讀取）→ 418 Could not validate credentials；JWT 對應的使用者不存在 → 404 User not found；帳號狀態 → 451 Account expired、401 Account not verified yet、409 Account disabled、410 Account deleted。接著成員與管理者關卡以 403 拒絕：服務帳號（Service accounts cannot invoke Edge Workers）、從資料庫重新讀取後已不存活的使用者（A live Edge Worker user is required）、缺少或已失效的部門（A department identity is required for Edge Workers、A live department identity is required for Edge Workers）；管理者關卡另有 Insufficient permissions.。模組的 403 Edge Workers require TeamSync JWT authentication 只是防禦性檢查，已發布的 JWT-only dependency 不會走到它。

指向 Worker 的 Durable Object 的路由還會解析是哪個位置在服務這個 Worker。若該紀錄不一致，它們回 503 Department Worker serving target is unavailable（存取政策與操作設定路由、執行期設定的讀取、機密清單與機密寫入、OpenAPI 文件、部署中的操作設定暫存，以及 invoke 路由）；後端根本沒有這個 Worker 已驗證的位置時，有稽核的控制變更與部署路由回 409 worker_serving_target_unavailable。平台維運者搬移該 Worker 期間，部署回 409 worker_migration_in_progress（Worker 已持有逐操作設定或請求帶有 operation_settings 時，則是 503 Department Worker control change is unavailable），有稽核的控制變更回 503 Department Worker control change is unavailable；搬移短暫暫停的期間，必須先讀取 Worker 狀態的呼叫 — 讀取、操作設定與金鑰、寫入機密，以及部署 — 則改回各自慣用的修訂版過期 409（錯誤、搬移 Worker）。

Worker

部門還沒有 Worker 時 404 Department Worker not found。

存取政策（前綴 /worker/access-policy）

• 四條都要求 Worker 已部署且 active：否則 409 Department Worker must be deployed and active。
• CAS：請求帶 base_revision；過期 → 409 Access policy revision is stale。後端驗證 provider 回傳恰為 base_revision + 1（撤銷 no-op：+0、revoked: false）— provider 回應漂移是 503，不是 409。
• 輪替只回傳一次明文金鑰：tsw_ + 43 個 url-safe 字元（共 47）；只儲存 SHA-256 摘要 + 後四碼。header 名稱固定 X-TeamSync-Worker-Key。
• live release 以 builder policy department-worker-project-v2.8 或更新版本建置時，或 Worker 一旦持有任何操作設定表，輪替會被拒絕：409 {"code": "worker_wide_key_legacy_only", "message": "Rotate an operation key instead"}。請改用逐操作金鑰。撤銷在所有 release 上都仍可用。
• 讀取失敗：503 Department Worker public URL is unavailable、Department Worker access policy is unavailable、Deployed department Worker release is unavailable。變更操作另有 503 Department Worker control change is unavailable（稽核意圖無法提交）與 503 {"code": "worker_release_unavailable", "message": "Worker release changed; retry this request"}（已部署的 release 在後端讀取與呼叫之間變了）。
• 回應帶 Cache-Control: no-store + Pragma: no-cache。
• 超過 16 KiB → 413 Worker access policy request exceeds limit。

執行期設定（前綴 /worker/runtime-config）

同樣的「已部署且 active」409 與 CAS 409（Runtime config revision is stale）；後置驗證漂移（revision ≠ base+1，或 SHA-256 與後端自己的正規摘要不符）→ 503。讀取失敗 → 503 Department Worker runtime config is unavailable；變更操作另有 503 Department Worker control change is unavailable 與帶代碼的 503 worker_release_unavailable。超過 73 728 位元組 → 413。注意這裡兩個讀取都是管理者關卡，與 GET /worker 不同。

操作設定（前綴 /worker/operation-settings）

逐操作的入站存取與操作 API 金鑰，以及每個操作的服務帳號綁定。概念：逐操作存取；操作步驟：管理操作存取。

• Release 關卡。 live Worker 必須已部署且 active（409 Department Worker must be deployed and active；撤銷也接受 paused），且其 release 以 builder policy ≥ department-worker-project-v2.8 建置，否則 409 {"code": "operation_settings_require_supported_release", "message": "Re-upload and deploy this Worker with the operation-settings runtime policy before changing per-operation access"}。version_id 若不是這個 Worker 的 ready 或 deployed 版本 → 404 Department Worker not found；以低於 v2.8 建置者 → 409，代碼相同，message 為 The selected release does not support operation settings。
• 狀態。 legacy（從未寫過設定表：每個操作都繼承 Worker 層級政策，revision 0）、pending（已有設定表，但沒有屬於這個 release 的；公開呼叫一律拒絕）、reconciled。對尚無設定表的目標做 version_id 預覽時，會顯示不帶設定部署時會沿用的內容，狀態仍回報為 pending。
• PUT。 operations 必須恰好列出 live manifest 的所有操作 id，否則 422 {"loc": ["body", "operations"], "msg": "operation settings must list every manifest operation", "type": "operation_settings_incomplete"}；access: null 表示繼承 Worker 層級政策。base_revision 必須等於設定表目前的 revision，否則 409 Operation-settings revision is stale；provider 回應不是 base_revision + 1 → 503 Department Worker operation settings are unavailable。既有的操作金鑰摘要與金鑰所有權一律跟著操作 id，不受請求內容影響。部門只要有任何部署票證不是 completed／failed／cancelled（含 uncertain）就拒絕：409 {"code": "deployment_in_progress", "message": "Operation settings cannot change during a deployment"}。
• 服務帳號欄位（default_service_account_id、operations[].service_account_id）：省略 = 保留，null = 清除。指定的帳號不是本部門存活的服務帳號 → 422 {"loc": [...], "msg": "service_account_id is not a live service account of this department", "type": "service_account_not_found"}；live release 低於 v2.9 → 409 {"code": "service_account_credentials_require_supported_release", "message": "The live release does not support service-account bindings; re-upload and deploy the project first"}；HOST 不是單純的 HTTPS origin → 503 {"code": "api_base_unconfigured", "message": "This deployment's HOST is not a bare HTTPS origin"}。憑證會在設定表變更之前先送進 Worker：409 {"code": "service_account_limit_exceeded", "message": "Worker service-account credential limit was reached"}、409 Service-account credential delivery is stale、503 Department Worker service-account credentials are unavailable、503 {"code": "service_account_verifier_unavailable", "message": "Service-account credentials cannot be verified by this deployment"}。
• 輪替。 無 body，也沒有用戶端 base_revision。該操作必須存在於 live manifest（否則 404 Department Worker not found），且 live 設定表必須是 reconciled，否則 409 {"code": "operation_settings_pending", "message": "Write operation settings before assigning an operation API key"} — legacy 的 Worker 要先 PUT 一次設定表。部署進行中的 409 與 PUT 相同。明文金鑰（tsw_ + 43 個 url-safe 字元，共 47）只回傳一次；只儲存其 SHA-256 摘要與後四碼，且沒有任何管理回應會回傳操作金鑰的後四碼。輪替會讓 revision 加 1；provider 回應不符 → 503 Department Worker operation key is unavailable。操作一旦擁有過金鑰，就不會再退回使用 Worker 層級金鑰。
• 撤銷。 無 body；Worker 為 paused 時、部署進行中時也接受。該操作必須存在於 live manifest，或進行中部署的暫存目標 manifest（否則 404）。不是 reconciled → 409 Operation settings are pending。會清除該操作在所有已儲存 release 世代中的金鑰；重複撤銷回傳 revoked: false，revision 不前進。
• 四條共通：release 在呼叫途中變更時回帶代碼的 503 worker_release_unavailable，變更操作另有 503 Department Worker control change is unavailable；PUT／POST／DELETE 的 body 超過 65 536 B → 413 Worker operation settings request exceeds limit；回應帶 Cache-Control: no-store + Pragma: no-cache。

機密（前綴 /worker/secrets）

僅可寫入的具名值，handler 程式碼以 context.secrets.get(name) 讀取。概念：Worker 機密；操作步驟：管理機密。

• 三條都要求 Worker 已部署且 active（409 Department Worker must be deployed and active）。GET 需要 live release 以 builder policy ≥ department-worker-project-v2.6 建置，PUT 需要 ≥ v2.7，否則 409 {"code": "worker_secrets_unsupported", "message": "This deployed Worker release does not support Worker secrets; re-upload and deploy the project"}。DELETE 在所有 release 上都可用：低於 v2.6 時回 200 {"name": "<NAME>", "deleted": false}。
• 名稱：^[A-Z][A-Z0-9_]{0,63}$。不符 pattern 是標準 422 清單；以 TEAMSYNC_ 開頭的名稱 → 422 Worker secret name is invalid or reserved（字串 detail）。
• 值：非空、不含 NUL、≤ 65 536 個 UTF-8 位元組。PUT 的 FastAPI 422 絕不回顯值：每個項目恰為 {"loc": [...], "type": "<type>", "msg": "validation_error:<type>"}。
• 容量（寫入前檢查）：已有 256 個時再新增名稱 → 409 {"code": "secret_limit_exceeded", "message": "The department Worker secret count limit is exhausted"}；所有值合計超過 16 MiB → 413 {"code": "secret_size_exceeded", "message": "Department Worker secret storage exceeds its total size limit"}。若 Worker 在競態中拒絕：409 {"code": "secret_limit_exceeded", "message": "Worker secret limit was reached"}／413 {"code": "secret_size_exceeded", "message": "Worker secret storage limit was reached"}。替換既有名稱不計入 256 的上限。
• 409 Worker secret mutation is stale（控制衝突）；503 Department Worker secrets are unavailable、Deployed department Worker release is unavailable、Department Worker control change is unavailable、帶代碼的 worker_release_unavailable。值送出之後才發生的 503 不代表是否已寫入：重新列出並比對 updated_at，或重送 PUT。
• 沒有設定鎖，也不檢查部署是否進行中。變更不需重新部署，下一次呼叫即可看到。
• PUT 的 body 超過 409 600 B → 413 Worker secret request exceeds limit。回應帶 Cache-Control: no-store + Pragma: no-cache。

版本（前綴 /worker/versions）

提交關卡依序：multipart 外層 ≤ 2 162 688 位元組（413 Worker submission request exceeds limit，在驗證之前即檢查）；provider 已設定（503 Edge Worker provider is not configured）；恰好一個 project part（422 project_multipart_invalid）；檔名恰為 department-worker.tar.gz（422 project_archive_filename_invalid）；content type 恰為 application/gzip（422 project_archive_content_type_invalid）；壓縮檔 ≤ 2 MiB（413 project archive exceeds 2097152 bytes）；gzip magic（422 project_archive_invalid）；然後是 builder。builder 的任何拒絕都呈現為同一個 422 {"loc": ["body", "project"], "msg": "project failed the locked Worker build policy", "type": "project_invalid"}；具體的拒絕代碼只在本機可見（teamsync-worker validate 會印出 authoritative builder rejected project: <code>）。建置出的 manifest 未通過後端的再驗證 → 422 type manifest_v2_invalid。builder 故障 → 503 {"code": "builder_unavailable", "message": "Department Worker builder is unavailable"}（builder 的失敗輸出無法解讀時代碼為 builder_invalid_output）；建置證據無效 → 503 {"code": "builder_invalid_output", "message": "Department Worker builder returned invalid evidence"}；artifact store 故障 → 503 Edge Worker artifact storage is unavailable。併發首次提交 → 409 a Worker already exists for this department。

原始碼下載

GET /worker/versions/{version_id}/source 回傳部門 Worker 任一版本所儲存的那份 department-worker.tar.gz，任何狀態皆可（含 superseded），回傳前會以版本的 project_digest 核對 SHA-256。能讀取版本的部門成員不能下載。壓縮檔就是提交格式，可原封不動再次提交（Starter 與原始碼）。

• 200 headers：Content-Type: application/gzip、Content-Disposition: attachment; filename="department-worker.tar.gz"、Cache-Control: private, no-store。
• 404 Department Worker not found — 沒有 Worker、未知 id，或其他租戶的版本（同一種回應）。
• 404 {"code": "edge_worker_version_source_unavailable", "message": "This version has no stored source archive"}。
• 500 {"code": "edge_worker_source_integrity_failed", "message": "The stored source archive failed its integrity check"} — 儲存的資料列損壞，或位元組與 project_digest 不符。
• 503 {"code": "edge_worker_artifact_unavailable", "message": "Edge Worker artifact storage is unavailable"} — 任何 artifact store 錯誤。

部署（前綴 /worker/deployments）

檢查順序：provider 已設定（503 Edge Worker provider is not configured）→ 完全相同的重試（同樣的 version_id、base_revision 與設定）回傳既有票證（202）→ 必須能驗證 Worker 的服務位置（409 worker_serving_target_unavailable）→ 設定鎖 → 其他任何未終結的票證（含 uncertain）→ 409 {"code": "deployment_in_progress", "message": "Operation settings cannot change during a deployment"}（即使沒送設定，措辭仍提到設定）→ 暫存操作設定 → 排入 outbox → 派送。

• operation_settings 只列出要變更的操作：列出的資料列會覆寫；兩個 release 都有而未列出的操作保留其完整 live 資料列（存取、金鑰、金鑰所有權、服務帳號綁定）；目標 manifest 沒有的操作會被移除。不帶這個區塊時，既有的 live 設定表以同樣方式沿用。列出的 id 不在目標 manifest → 422 {"loc": ["body", "operations"], "msg": "operation_id is not present in the target release manifest", "type": "operation_not_found"}；operation_settings.base_revision ≠ live revision → 409 Operation-settings revision is stale。
• 帶代碼的 409：operation_settings_require_supported_release（Deploy the Worker once before adding operation settings · The live release does not support operation settings · The target release does not support operation settings — 最後一項即使沒帶設定也會出現：v2.8+ 的 release 上線後，就無法部署低於 v2.8 建置的 release）· {"code": "operation_settings_pending", "message": "Reconcile the live release before deploying settings"} · {"code": "operation_settings_dedupe_mismatch", "message": "Deployment settings differ from the existing ticket"}（完全相同的重試卻帶不同設定）· service_account_credentials_require_supported_release（The target release does not support service-account bindings; re-upload and deploy the project first · The live release does not support service-account bindings; re-upload and deploy the project first · Unbind every service account (PUT operation-settings) before deploying a release without service-account support）· service_account_limit_exceeded · {"code": "worker_serving_target_unavailable", "message": "Worker deployment target cannot be verified"}（後端無法驗證是哪個位置在服務 Worker 的現行 release；沒有排入任何工作）。
• outbox 的 409 字串：Worker revision changed; refresh before deploying · Worker version cannot deploy from state '<state>' · uncertain deployment requires company reconciliation · Worker version was superseded; V2 rollback is not supported · Worker deployment sequence is exhausted · deployment intent already exists · worker_migration_in_progress（平台維運者正在搬移該 Worker）· Worker deployment target cannot be verified · Worker deployment target is unavailable（也包括所設定的預設位置無法使用的第一次部署）· 僅在競態時：a deployment is already active for this department Worker、operation-settings digest differs from the existing deployment。
• 422 service_account_not_found（同 PUT 操作設定）。503：{"code": "operation_settings_live_read_unavailable", "message": "Retry the deployment after the live settings read recovers"} · api_base_unconfigured · service_account_verifier_unavailable · Department Worker service-account credentials are unavailable · Department Worker serving target is unavailable · Deployment dispatch is unavailable（確定的派送拒絕）。
• 僅限地端：主機的維護或還原閘門關閉時 409 edge_workers_maintenance／edge_workers_restore_pending；主機執行被圍欄時請求仍會被接受（202），但票證維持 pending 並帶 error_code: "edge_host_fenced"，直到圍欄解除（地端）。
• POST /worker/deployments 沒有路由層級的 body 上限。輪詢語意與狀態字彙：版本與部署。

OpenAPI

draft／inactive 時 409 Department Worker must be deployed and active；沒有已部署版本時 404（未寫入文件但可觸及）；完整性失敗 503 Deployed department Worker contract is unavailable；EDGE_WORKERS_GATEWAY_PUBLIC_URL 與 HOST 皆未設定時 Department Worker gateway URL is not configured（任何存取模式下都可能發生）。live release 以 builder policy ≥ v2.8 建置時，這條路由也會讀取操作設定表：讀取失敗時 503 Department Worker operation settings are unavailable 或帶代碼的 worker_release_unavailable。

存取政策與操作設定在每次請求都重新讀取，所以政策、操作設定或服務帳號綁定的變更不需重新部署，即可更新 servers[0].url、安全機制、逐操作的擴充欄位與 ETag。每份文件都帶根層擴充欄位 x-teamsync-operation-settings-state（低於 v2.8 的 release 為 legacy、revision 0）。狀態為 reconciled 時，每個操作都帶 x-teamsync-service-account（物件或 null），因此帳號 id 與使用者名稱對每位部門成員都可見；有自己的設定資料列、或曾經擁有金鑰的操作還會帶 x-teamsync-access-policy（含 source）；其模式與 Worker 不同或 source 為 operation 時，另帶自己的 security（基礎 URL 與根層不同時再帶 servers）。components.securitySchemes 可同時包含 TeamSyncBearer 與 TeamSyncWorkerApiKey。欄位形狀：Schemas。

Starter（前綴 /starters）

不需要已有 Worker。starter_id 為 department-users-api，language 為 javascript 或 typescript；其他值，或目錄裡沒有的組合 → 404 Edge Worker starter not found（不是 422）。目錄缺少或無效 → 503 Edge Worker starter catalog is unavailable；檔案大小或 SHA-256 與目錄不符 → 503 Edge Worker starter artifact is unavailable。下載只送 Content-Disposition 與 Content-Length（沒有快取 header）；請以目錄的 size_bytes 與 sha256 核對。操作步驟：Starter 與原始碼。

服務帳號（前綴 /service-accounts）

部門擁有的身分，Worker 的 context.teamsync.authHeaders() 以它登入。概念：服務帳號；操作步驟：服務帳號流程。下表的 {id} 即 {service_account_id}，是一個 ResourceId。

• 部門範圍：自己部門的管理者（七條路由全部，兩條 GET 也是）。公司鏡像：同樣七條路由位於 /company/departments/{department_id}/service-accounts… 之下，供公司管理者使用；部門不存在、已刪除或屬於其他公司 → 404 Department not found。
• 未知、已刪除、其他租戶或真人使用者的 id → 404 Service account not found（同一種回應）；執行操作的管理者資料列已不存在 → 403 A live manager identity is required。
• 建立：409 Service account name is unavailable（該 UTC 秒的 99 個名稱都已被占用）。列表與候選：cursor 大於 1 000 000 → 422 Invalid cursor。聊天室：add／remove 各 ≤ 100 個 id 且不得重疊（否則 422，其 msg 含 add and remove must be disjoint）。
• 詳細資料在 Worker 執行可持有憑證的 release 時會讀取 Worker：503 Department Worker service-account credentials are unavailable、Department Worker operation settings are unavailable、Deployed department Worker contract is unavailable。
• 重設：Worker 可持有憑證時會取得部門的設定鎖（被持有時 409 帶代碼的 deployment_in_progress，503 Operation-settings mutation lock is unavailable）；所有遞送問題都在 200 內以 delivery: "failed" 回報。刪除即使 Worker 清理失敗或延後，仍回 200。
• 詳細資料、重設、刪除、聊天室與候選路由送出 Cache-Control: no-store（沒有 Pragma）。這些路由使用一般 router：沒有路由層級的 413。

Invoke（隱藏路由）

沒有 HEAD/OPTIONS。Worker 自己的回應會串流回來。存取政策與操作設定不適用於這條簽章通道。部門已刪除時，後端會先拒絕（403 A live department identity is required for Edge Workers）；runtime 的 403 worker_retired 是 Worker 公開 URL 在退役後的回應。完整管線、圍欄與錯誤對映：呼叫流程與調度協定。

公司操作（前綴 /company/departments）

細節、健康推導與修復語意：公司管理員流程。修復的 409 字串：Repair parameters do not match the original request · Worker revision is stale; refresh department state · Deployment revision is stale; refresh department state · Only an uncertain deployment can be reconciled · Only an uncertain deployment version can be reconciled；僅限地端另有 edge_workers_maintenance／edge_workers_restore_pending。provider 未設定 → 503 Edge Worker provider is not configured。修復 body 超過 8 KiB → 413 Worker repair request exceeds limit。這個前綴下的服務帳號鏡像列在上方的服務帳號一節。

橫切行為

• 413 在驗證之前觸發，適用於模組的有界路由（存取政策、執行期設定、操作設定、機密 PUT、提交、修復）— 有界 route class 在 dependency 解析前檢查 Content-Length 並計數實際位元組。服務帳號與 starter 路由沒有路由層級的 413。
• 除了四條 starter 路由，每條路由都記載 422（EdgeWorkerValidationErrorResponse）與 default 消毒錯誤；沒有明確 model 的 ≥400 狀態預設為 EdgeWorkerHttpErrorResponse（{"detail": string}）。許多路由的實際 detail 是 string | {code, message}（存取政策、執行期設定、操作設定、機密、版本、部署、OpenAPI、服務帳號）；生成的後端 OpenAPI 只在機密路由、提交的 503 與原始碼下載宣告這個聯集，所以請在每條路由都檢查 detail 的型別（錯誤）。
• 租戶錨定：每個讀寫都以 principal 的 company_id 與 department_id 過濾；異租戶與不存在的資源回同一個 404。
• 公司管理者路由不執行服務帳號拒絕；服務帳號（角色 0）會在角色門檻被拒，回 403 Insufficient permissions.。