公司管理員

誰：公司管理者（JWT 角色 ≥ CAN_MANAGE_COMPANY，預設 3）。前綴：/company/departments，tag Module: Edge Workers - Company Operations。

清單總覽


GET /company/departments?offset=0&limit=50

offset 為 0…1 000 000，limit 為 1…200（預設 50）。分頁列出存活部門（name ASC、再 id ASC — 二進位 collation，大小寫敏感），包含沒有 Worker 的部門（configured: false）。每筆：department_id、department_name、configured、health、recommended_action，加上 worker、current_version、latest_version、latest_deployment 摘要。刻意排除：摘要值、object key、script 名稱；error_message 是消毒過的 TeamSync 文字，絕非原始 provider 輸出（地端：因 host 的 Worker 容量已滿而被拒絕的部署，會顯示 host 的固定指引文字）。

latest_version 取最高修訂版；latest_deployment 依准入順序（created_at，同秒再比 admission_sequence，再比 id — 沒有序號的舊列排在有序號的之後）。兩者可能指向不同版本；正是這種組合驅動 health: draft + recommended_action: deploy_ready_version。

健康 → 動作（先中先贏）

`health`	條件	`recommended_action`
`not_configured`	沒有 Worker	`submit_version`
`uncertain`	部署或最新版本 `uncertain`	`reconcile_uncertain_deployment`
`deploying`	部署 `pending`/`leased`，或版本 `deploy_pending`/`deploying`	`wait_for_automatic_recovery`
`failed`	最新部署／版本失敗	`submit_new_version`
`paused`	worker 暫停（不屬於上述情況）	`none`
`active`	active + current 版本 `deployed`	有更新的 `ready` 修訂版時 `deploy_ready_version`，否則 `none`
`draft`	其他情況	最新版是 `ready` 時 `deploy_ready_version`，否則 `submit_version`

單一部門


GET /company/departments/{department_id}

同樣的快照，單一部門。異公司、已刪除或不存在的部門統一 404。

修復 uncertain 部署

公司管理者唯一的寫入。uncertain 部署讓 Worker 維持 paused 並擋掉該部門所有新部署；自動復原已用盡預算。


POST /company/departments/{department_id}/repairs
{ "action": "reconcile_uncertain_deployment",
  "ticket_id": "<the uncertain ticket>",
  "observed_worker_revision": <current worker.latest_revision> }

202 {action, deployment} — 票證回到佇列（submitting/pending；地端在備份圍欄期間為 pending 且 error_code: "edge_host_fenced"），下一次任務執行對 Cloudflare 跑 GET-only 調解（永不盲目重新上傳）：回讀完全吻合且 release 在就緒輪詢中通過唯讀檢查（最長 600 秒）→ completed；可證明的不吻合／讀不到，或 release 仍未回應（worker_readiness_timeout）→ 再次 uncertain（可用完全相同的請求再次修復）；服務位置已無法再對應到該 Worker 的票證，則以 failed legacy_serving_target_unavailable 結束，或以 uncertain deployment_target_unavailable／deployment_target_release_changed 結束（錯誤）。

409 分支：{"code":"worker_serving_target_unavailable",…}（後端無法驗證是哪個位置在服務該 Worker；重試一次，再告知平台維運者）、Only an uncertain deployment can be reconciled／Only an uncertain deployment version can be reconciled（狀態已前進）、Worker revision is stale; refresh department state／Deployment revision is stale; refresh department state（重新 GET 部門並帶觀察到的修訂版重送）、Repair parameters do not match the original request（這張票證先前的修復用了不同參數 — 修復只對完全相同的標記冪等）。body > 8 KiB → 413。票證不存在、不是部署票證，或屬於其他部門 → 404。稽核為 deployment.reconciliation_submitted。

Provider 閘門與 POST /worker/deployments 相同：平台的 EDGE_WORKERS_PROVIDER 設定無效時回 503 Edge Worker provider is not configured；僅限地端：resync epoch 進行中回 409 edge_workers_maintenance，還原保護開啟中回 409 edge_workers_restore_pending（雲端永遠不會回這兩個；見地端）。修復不會取得該部門的設定鎖，也不會暫存操作設定。

修復回應的 deployment 是完整票證狀態（可能是 submitting）；清單總覽的 latest_deployment.status 永遠不會出現 submitting（該值不落庫）。

刪除部門會讓其 Worker 退役

DELETE /private/company/departments/{department_id}（公司管理者）會軟刪除該部門，然後盡力讓其 Worker 退役；無論退役結果如何，回應都是 200。對 Worker 而言這是不可逆的。在雲端，script 會被替換為回 404 worker_not_found 的墓碑（退役後保留，之後自動移除），且 Worker 的執行期資料（儲存、存取政策與金鑰、操作設定、執行期設定、Worker 機密、服務帳號憑證）會被銷毀；在地端，edge host 讓 script 退役但保留資料。兩種情況下，部門資料列都只是軟刪除，TeamSync 的資料列（Worker、修訂版、部署、稽核）都會保留。該部門的服務帳號會隨之軟刪除；其真人成員會搬到 fallback 部門。此後該部門不再出現在上述清單總覽中，其詳情與修復路由回 404，而在雲端，仍在佇列中的部署會以 department_deleted 結束為 failed。機制、呼叫端可見的狀態與重試迴圈：退役。