Schema

核心 API 模型都用 extra="forbid"（未知欄位直接拒絕）、from_attributes=True、populate_by_name=True；機密模型用 extra="forbid" + from_attributes=True，服務帳號模型用 extra="forbid" + populate_by_name=True，starter 模型用 extra="forbid"。manifest 側模型另外設 validate_assignment、str_strip_whitespace、allow_inf_nan=False。manifest／契約模型見 Manifest 規格。

受約束別名

別名	約束
`ResourceId`	恰 36 字元，RFC-4122 UUID v1–v5
`Sha256Hex`	`^[0-9a-f]{64}$`
`ExactSemVer`	5–64 字元，完整 SemVer 2.0
`NpmPackageName`	1–129 字元，npm 名稱（可帶 scope）
`AccessPolicyCidr`	3–43 字元
`OpenApiPath`	1–2048 字元，以 `/` 開頭
`OperationId`	1–64 字元，`^[A-Za-z][A-Za-z0-9_]{0,63}$`（即 manifest 的 `operationId`）
`EdgeWorkerSecretName`	1–64 字元，`^[A-Z][A-Z0-9_]{0,63}$`；以 `TEAMSYNC_` 開頭的名稱保留，一律拒絕

Worker 與版本

EdgeWorkerView — id、status（draft/active/paused）、latest_revision（≥0）、current_version_id（可 null）、created_at、updated_at。

EdgeWorkerVersionSummary — id、worker_id、revision（≥1）、language、module_name（1–64）、module_version（SemVer）、entrypoint（1–256）、compatibility_date、manifest_digest、contract_digest、project_digest、project_size_bytes（1–2 097 152）、lock_digest、dependency_digest、build_policy_version（1–64）、bundle_digest、sbom_digest、build_receipt_digest、state（8 值列舉）、error_code/error_message（可 null；"" → None）、deployed_at、created_at、updated_at。

EdgeWorkerVersionView — summary + 型別化 sbom（EdgeWorkerCycloneDxSbom）與 build_receipt（EdgeWorkerBuildReceiptEvidence）；兩者可從儲存的 JSON 字串解析。

EdgeWorkerSubmissionResponse — {worker, version}（提交的 201 body）。

EdgeWorkerVersionsResponse — items（≤200）、total（≥ len(items)）、offset（0–1 000 000）、limit（1–200；len(items) ≤ limit）。

部署

EdgeWorkerDeployRequest — version_id: ResourceId、base_revision（≥0，無上限 — 唯一沒有上限的 base_revision）、operation_settings（EdgeWorkerOperationSettingsPutRequest，可 null，預設 null）。operation_settings 會在目標 release 開始服務前寫入它的暫存設定：列出的操作覆寫其現行列；兩個 release 都有、但未列出的操作保留完整的現行設定（存取、操作金鑰、服務帳號綁定）；服務帳號欄位的規則與 PUT 操作設定相同（省略 = 保留，null = 清除）。與 PUT 不同，這份清單可以只列出有變動的操作。見管理逐操作存取。

存取政策與 API 金鑰

EdgeWorkerAccessPolicyUpdate — base_revision（0…9 007 199 254 740 990）、mode（5 值列舉）、ip_allowlist（≤64 條 CIDR）。CIDR 正規化為 with_prefixlen 並排序；正規化後重複的項目會被拒絕（IP allowlist entries must be unique）；模式↔允許清單雙向強制：ip_allowlist/api_key_and_ip 需要 ≥1 條，其他模式必須為空。

EdgeWorkerAccessPolicyView — mode、ip_allowlist、api_key_configured、api_key_last_four（恰 4 字元，可 null — 與 api_key_configured 綁定）、revision、public_url（^https://）、updated_at。

EdgeWorkerAccessPolicyKeyMutationRequest — base_revision。

EdgeWorkerApiKeyRotationResponse — api_key（恰 47 字元、^tsw_[A-Za-z0-9_-]{43}$、只回傳一次）、header_name: "X-TeamSync-Worker-Key"、policy。Worker 層級金鑰的輪替僅限舊版 release：現行 release 以 department-worker-project-v2.8 或更新版本建置後，此路由回 409 {"code": "worker_wide_key_legacy_only", "message": "Rotate an operation key instead"}。

EdgeWorkerApiKeyRevocationResponse — revoked: bool、policy。

操作設定

逐操作的進站存取與服務帳號綁定，依 release generation 分別儲存（現行 release 須以 department-worker-project-v2.8 或更新版本建置；綁定需要 v2.9）。見逐操作存取與服務帳號。

EdgeWorkerOperationAccessOverride — mode（與 Worker 層級存取政策相同的 5 值列舉）、ip_allowlist（每個操作 ≤64 條 CIDR，預設 []）。規則與 EdgeWorkerAccessPolicyUpdate 相同：CIDR 正規化為 with_prefixlen 並排序，重複即拒絕（IP allowlist entries must be unique），ip_allowlist/api_key_and_ip 需要 ≥1 條 CIDR（the selected access mode requires at least one CIDR），其他模式必須為空（IP allowlist is supported only by IP-restricted modes）。

EdgeWorkerOperationSettingsItem — operation_id: OperationId、access（EdgeWorkerOperationAccessOverride，可 null，預設 null = 沿用 Worker 層級存取政策）、service_account_id（ResourceId，可 null；省略此欄位會保留該操作目前的綁定，null 會清除綁定，讓該操作改沿用 default_service_account_id）。

EdgeWorkerOperationSettingsPutRequest — base_revision（0…9 007 199 254 740 990；現行操作設定的修訂版，用於比對後交換）、default_service_account_id（ResourceId，可 null；省略 = 保留目前的預設，null = 清除，沒有自身綁定的操作因此拿不到憑證）、operations（≤64 筆 EdgeWorkerOperationSettingsItem，預設 []）。驗證器：操作 id 不得重複（operation settings must contain unique operation ids）；所有操作的 CIDR 合計 ≤256 條（operation settings contain too many IP allowlist entries）。PUT 時清單必須列出現行 manifest 的每一個操作，否則回 422 operation_settings_incomplete。

EdgeWorkerOperationEffectiveAccess — mode、ip_allowlist_configured: bool、api_key_configured: bool、source（operation 或 worker）。

EdgeWorkerOperationServiceAccountView — id: ResourceId、username（≤64，可 null — 綁定的帳號已不再有效時為 null，該綁定因此失敗即關閉）、source（operation 或 default）、live: bool。

EdgeWorkerOperationSettingsOperationView — operation_id、method（GET/POST/PUT/PATCH/DELETE）、path（1–2048）、access（覆寫設定或 null）、service_account_id（該操作自身的綁定或 null）、effective_access（EdgeWorkerOperationEffectiveAccess）、effective_service_account（EdgeWorkerOperationServiceAccountView，未綁定任何帳號時為 null）。操作金鑰永遠不會回傳摘要值或末四碼提示，只有 effective_access.api_key_configured。

EdgeWorkerOperationSettingsView — state、version_id（可 null）、revision（0…2^53−1，依 release generation 各自計數）、default_service_account_id（可 null）、default_service_account（EdgeWorkerOperationServiceAccountView 或 null）、operations（≤64；manifest 的每個操作一筆，依 operation_id 排序）。state：legacy = 從未儲存過設定（revision 0，每個操作都沿用 Worker 層級存取政策）；pending = 有設定，但不是這個 release generation 的（revision 0）；reconciled = 這個 release generation 有自己的設定表。

EdgeWorkerOperationApiKeyRotationResponse — api_key（恰 47 字元、^tsw_[A-Za-z0-9_-]{43}$、只回傳一次）、header_name: "X-TeamSync-Worker-Key"、operation_id、access（EdgeWorkerOperationEffectiveAccess）。輪替請求沒有 body。

EdgeWorkerOperationApiKeyRevocationResponse — operation_id、revoked: bool（該操作沒有金鑰時為 false）、access（EdgeWorkerOperationEffectiveAccess）。撤銷請求沒有 body。

執行期設定

EdgeWorkerRuntimeConfigPutRequest — base_revision、value: dict（≤256 個頂層鍵；鍵 1–256 UTF-8 位元組、無 NUL；整體 ≤64 KiB 正規 JSON、深度 ≤32、≤10 000 節點、整數 ±2^53−1 內）。

EdgeWorkerRuntimeConfigDeleteRequest — base_revision。

EdgeWorkerRuntimeConfigView — found、revision、value、sha256；found=true ⇒ value 與 sha256 皆在，found=false ⇒ 皆無。注意：沒有 updated_at（刻意從 provider 回答剝除）。

機密

僅可寫入：值只能出現在 PUT 的 body，任何回應模型都不含值。上限：每個部門 Worker ≤256 個機密（MAX_EDGE_WORKER_SECRETS）、每個值 ≤65 536 UTF-8 位元組（MAX_EDGE_WORKER_SECRET_VALUE_BYTES）、所有值合計 ≤16 777 216 UTF-8 位元組（16 MiB，MAX_EDGE_WORKER_SECRET_TOTAL_BYTES）。見 Worker 機密與管理 Worker 機密。

EdgeWorkerSecretPutRequest — value（非空字串、無 NUL、合法 Unicode、≤65 536 UTF-8 位元組）。名稱是路徑參數（EdgeWorkerSecretName）。

EdgeWorkerSecretInfo — name: EdgeWorkerSecretName、updated_at。

EdgeWorkerSecretsResponse — items（≤256 筆 EdgeWorkerSecretInfo；只有名稱與時間戳）。

EdgeWorkerSecretPutResponse — name、updated_at（絕不含值）。

EdgeWorkerSecretDeleteResponse — name、deleted: bool（沒有刪除任何東西時為 false）、updated_at（可 null，預設 null）。

服務帳號

部門服務帳號，即 Worker 各操作對外呼叫時的身分。見服務帳號與管理服務帳號。

ServiceAccountView — id、company_id、department_id（皆為 ResourceId）、username（≤32，^EdgeWorkerSA-[0-9]{8}T[0-9]{6}Z(?:-(?:[2-9]|[1-9][0-9]))?$）、nickname（1–64）、email（≤128，^sa-[0-9a-f-]{36}@service-account\.invalid$）、role_id: 0、auth_source: "service_account"、is_service_account: true、enabled: bool、is_verified: bool、created_at。

ServiceAccountListResponse — items（≤100 筆 ServiceAccountView，依 created_at、再依 id 排序）、next_cursor（^[0-9]{1,7}$，可 null；最後一頁為 null）。

ServiceAccountRoomView — id、name（≤64；聊天室沒有名稱時為 ""）、department_id（聊天室所屬部門）、department_name（≤32；未知時為 ""）、is_member: bool。

ServiceAccountCredentialView — present: bool、updated_at（可 null；Worker 儲存目前這份憑證的時間）。

ServiceAccountDetail — ServiceAccountView 再加上 rooms（≤500 筆 ServiceAccountRoomView）、rooms_truncated: bool（帳號所在聊天室超過 500 個時為 true）、bound_operations（≤64 個操作 id，各 1–64 字元，已排序：現行 release 中有效綁定為此帳號的操作；現行 release 不支援服務帳號憑證時為 []）、credential（ServiceAccountCredentialView 或 null；部門 Worker 未部署時為 null，release 建置於 v2.9 之前、或 Worker 未持有此帳號的憑證時為 present: false）。

ServiceAccountResetResponse — delivery ∈ delivered | not_deployed | unsupported_release | not_bound | failed：delivered = 新的機密已在 Worker 中；not_deployed / unsupported_release / not_bound = 目前沒有任何東西使用它，因此只撤銷舊的機密；failed = 遞送失敗或結果不確定，舊的機密已撤銷、新的已提交。任何回應都不會回傳機密。

ServiceAccountDeleteResponse — deleted: true、unbound_operations（≤64 個操作 id，已排序：現行 release 中有效綁定原為此帳號的操作；在重新綁定之前它們一律拒絕（fail closed））。

ServiceAccountChatroomsRequest — add、remove（各 ≤100 個 ResourceId，預設 []）；兩份清單不得重疊（add and remove must be disjoint）。

ServiceAccountChatroomsResult — results（≤200；先是依請求順序的 add 列，再來是 remove 列）、member_room_count（≥0；呼叫後此帳號所在、公司內仍有效的聊天室數）。

ServiceAccountChatroomCandidates — items（≤100 筆 ServiceAccountRoomView，每個聊天室各自標示 is_member）、next_cursor（同列表回應）。

建置證據

EdgeWorkerBuildReceiptEvidence — 恰為：builderPolicy、bundleDigest、dependencyDigest、lockDigest、manifestDigest、projectDigest、releaseGeneration、receiptVersion: "1"、sbom、sbomDigest、staticData（≤64 筆 {path, sha256, sizeBytes}）、staticDataDigest。

EdgeWorkerBuilderPolicyEvidence — 19 個釘死的政策欄位，多為 Literal：buildPlugins/dynamicCode/dynamicImports/installScripts/nativeModules/networkDuringBuild/wasm: false、zodJitless: true、lockfileVersion: 3、target: "es2022"、approvedDependencies（≤128，名稱 → 精確版本）、七個 max* 上限，以及 version（1–64，^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$；新的建置記錄為 department-worker-project-v2.10）。各政策版本開放哪些能力，見提交管線。

EdgeWorkerCycloneDxSbom — bomFormat: "CycloneDX"、specVersion: "1.6"、version: 1、metadata.component（根元件 type: "application"、bom-ref 為 urn:teamsync:department-worker:<name>@<version>）、components（≤192；library 項帶一個來自 npm integrity 的 SHA-512 hash、一個 SPDX license id、一個 pkg:npm/... purl；data 項每個 src/data/**.json 檔一個 SHA-256）、dependencies（1–193 條邊）。

生成的 OpenAPI 文件

EdgeWorkerOpenApiDocument — openapi: "3.1.1"、jsonSchemaDialect（draft 2020-12）、info（title/version/description 來自 manifest）、servers（恰 1 個，僅 https://）、tags（1–32，各帶 x-teamsync-slug）、security（≤1；Worker 層級的要求）、paths（1–64）、components（securitySchemes ≤2 — TeamSyncBearer（HTTP bearer JWT，teamsync_internal）和／或 TeamSyncWorkerApiKey（apiKey 標頭 X-TeamSync-Worker-Key，所有 api_key/api_key_and_ip 操作共用；標頭帶該操作自己的金鑰，沿用 Worker 政策且沒有自身金鑰的操作則帶 Worker 層級金鑰）；schemas 2–130 — 呼叫者 schema 加注入的 EdgeWorkerError 與 TeamSyncGatewayError；responses 恰 1 — StandardError）、x-teamsync-access-policy（Worker 層級：mode、ipAllowlistConfigured、apiKeyConfigured）、x-teamsync-max-query-bytes: 1024、x-teamsync-operation-settings-state（EdgeWorkerOpenApiOperationSettingsState：state 為 legacy/reconciled/pending，revision 0…2^53−1；模型中為選填，生成器一律輸出，不支援操作設定的 release 為 legacy、revision 0）。

模型中 paths 內的操作物件不具型別。只有操作設定狀態為 reconciled 時，生成器才會加上：

有設定列、或曾經擁有操作金鑰的每個操作，帶 x-teamsync-access-policy：mode、ipAllowlistConfigured、apiKeyConfigured、source（operation 或 worker）。
當該操作的有效模式與 Worker 模式不同，或其 source 為 operation 時，帶操作層級的 security：teamsync_internal 用 TeamSyncBearer，api_key/api_key_and_ip 用 TeamSyncWorkerApiKey，public/ip_allowlist 為 []。其基礎 URL 與文件層級不同時，另帶自己的 servers（一個 url）：teamsync_internal 為後端 invoke 基礎 URL，其他模式為公開 URL。
每個操作都帶 x-teamsync-service-account：id、username、source（operation 或 default），未綁定任何帳號時為 null。

Starter

由 GET /starters 提供。見 Starter 與原始碼。

EdgeWorkerStarterCatalog — builder_policy_version（1–128，^[0-9A-Za-z][0-9A-Za-z._-]*$；5.22.0 映像中為 department-worker-project-v2.10）、starters（1–32 筆 EdgeWorkerStarter）、cli（EdgeWorkerCliArtifact）。

EdgeWorkerStarter — id（EdgeWorkerStarterId，只有一個值：department-users-api）、language（javascript/typescript）、title（1–128）、description（1–2048）、source_zip、project_archive（皆為 EdgeWorkerStarterArtifact）。

EdgeWorkerStarterArtifact — size_bytes（1–67 108 864，即 64 MiB）、sha256（^[0-9a-f]{64}$）。

EdgeWorkerCliArtifact — version（1–128，^[0-9A-Za-z][0-9A-Za-z._+-]*$）、size_bytes（1–67 108 864）、sha256（^[0-9a-f]{64}$）。

EdgeWorkerBinaryResponse — RootModel[bytes]（OpenAPI type: string、format: binary）；cli.tgz、source.zip 與 department-worker.tar.gz 下載所宣告的 body。

公司管理

EdgeWorkerCompanyDepartmentStatus／…Detail — department_id、department_name（1–32，可 null）、configured（必須等於 worker is not None）、health、recommended_action、worker（EdgeWorkerCompanyWorkerSummary）、current_version/latest_version（EdgeWorkerCompanyVersionSummary — 刻意不含摘要值、object key、script 名稱；error_message 是消毒過的 TeamSync 文字，絕非原始 provider 回應）、latest_deployment（EdgeWorkerCompanyDeploymentSummary：ticket_id、version_id、status — 6 個資料庫值、無 submitting —、attempts、error_code、時間戳）。

EdgeWorkerCompanyDepartmentsResponse — 與版本相同的分頁契約（items ≤200、total/offset/limit 驗證器）。

EdgeWorkerCompanyRepairRequest — action: "reconcile_uncertain_deployment"、ticket_id、observed_worker_revision（0…2^53−1）。EdgeWorkerCompanyRepairResponse — action、deployment（完整的 EdgeWorkerDeploymentStatus — 這一個可以說 submitting）。

錯誤模型

EdgeWorkerHttpErrorResponse — detail: str（1–2048）。EdgeWorkerCodedErrorDetail — code（^[a-z0-9][a-z0-9_]{0,63}$）、message（1–256）。EdgeWorkerSubmissionServiceErrorResponse — detail: str | EdgeWorkerCodedErrorDetail（無標記 union）。EdgeWorkerSecretsErrorResponse — detail: str | EdgeWorkerCodedErrorDetail；機密路由宣告的 409/413 body。EdgeWorkerValidationErrorResponse — detail: list[EdgeWorkerValidationErrorItem]（1–512；項目 extra="allow"，含 loc、msg、type）。

後端自己的 OpenAPI 對其餘所有 4xx/5xx 回應（422 除外）都宣告為 EdgeWorkerHttpErrorResponse，但存取政策、執行期設定、操作設定、部署、OpenAPI 與服務帳號路由（以及機密路由的 503）的 409/503 也可能帶有編碼的 {code, message} detail：在這些路由上同樣要把 detail 當作 string | {code, message} 解析。