Skip to Content
API 參考Root 維運操作

Root 維運操作

供維運人員內部使用的排程、永久清除、復原、索引建議、保留期清理、資料修復、composer 儲存設定與一次性回填操作；這些路由不是應用程式對外 API。

其中有幾個會直接寫入或刪除生產環境的資料。執行前請先讀該端點的注意事項；若該路由提供預覽模式（apply=false、dry_run=true、execute=false），請先跑預覽並確認它回報的內容。各路由的預設值不同：apply 與 execute 預設為預覽，但索引套用路由預設 dry_run=false，除非你要求 dry run，否則會直接執行 DDL。

Trigger-secrets 清理會跨租戶改寫次要 IaC-state 與 table-history 儲存中較舊的憑證。預設為 execute=false；先檢查各儲存區的 ticket 計數，再用 execute=true 改寫。即時 trigger/command 設定與讀取回應保持不變。原始碼已有此能力，不代表任何環境已執行這項操作人員遷移。

資料表的 write_policy: commands_only 不會擋下維運操作。永久清除資料表（table_lifecycle）與 sort-order 回填（platform_operator_maintenance）都是已公布的例外，而對這類資料表執行的每個例外操作都會寫入一筆 ct.write_policy.exemption 稽核事件。

POST
路由範本/root/hotfix/custom-table-trigger-secrets-scrub

清理次要儲存中的舊 trigger 憑證

用途

啟動跨租戶的操作人員遷移，處理舊 IaC trigger/command 基準與 schema_triggers_update history 列。預設 dry run 只統計；execute=true 才改寫。

適用時機

部署會遮罩次要憑證儲存的來源版本後，先檢查 dry run，再於該環境執行清理。文件不代表清理已執行。

實際掛載路徑
  • 完整路由/root/hotfix/custom-table-trigger-secrets-scrub

範圍

範圍是否提供驗證與權限
完整路由可使用CloudManager root keys (X-ADMIN-TOKEN + X-SUPER-TOKEN + X-CLOUD-TOKEN)

參數

欄位位置型別必填說明
executequeryboolean否預設 false，只統計。True 會改寫符合的資料列，每個 keyset 分頁使用一個交易。
batch_sizequeryint 1..1000否每個 keyset 分頁的列數；預設 200，最小 1，最大 1000。

回應結構

TaskResponse
欄位型別必填說明
messagestring否未指定
ticket_idstring是Ticket ID

範例

啟動 dry run（示意 ticket）

請求
{
  "pathParams": {},
  "query": {
    "execute": "false",
    "batch_size": "200"
  }
}
回應200
{
  "ticket_id": "66666666-6666-4666-8666-666666666666",
  "message": "Trigger secrets scrub started (dry run). Use the ticket ID to track progress."
}

錯誤

驗證錯誤範例列出識別欄位；部署中的驗證器也可能回傳 input 與 ctx。錯誤訊息 URL 的版本由建置決定，因此使用 pydantic-version 佔位符。

狀態發生條件錯誤本文
403需通過 BaseRoot、SuperRoot、CloudManager 的 root key 檢查；無效 key 回 403。範例顯示 CloudManager 拒絕。
{
  "detail": "CloudManager access denied: Invalid X-CLOUD-TOKEN"
}
422execute 不是布林值，或 batch_size 不在 1–1000。
{
  "detail": [
    {
      "type": "greater_than_equal",
      "loc": [
        "query",
        "batch_size"
      ],
      "msg": "Input should be greater than or equal to 1",
      "input": "0",
      "ctx": {
        "ge": 1
      }
    }
  ]
}
GET
路由範本/root/hotfix/custom-table-trigger-secrets-scrub/{ticket_id}

查看 trigger-secrets 清理進度

用途

回傳各儲存區的 scanned、needs_rewrite、rewritten 計數，不含任何憑證值。

適用時機

追蹤 root.triggerSecretsScrub 回傳的 ticket，直到 completed 或 failed。

實際掛載路徑
  • 完整路由/root/hotfix/custom-table-trigger-secrets-scrub/{ticket_id}

範圍

範圍是否提供驗證與權限
完整路由可使用CloudManager root keys (X-ADMIN-TOKEN + X-SUPER-TOKEN + X-CLOUD-TOKEN)

參數

欄位位置型別必填說明
ticket_idpathuuid是清理 POST 回傳、符合 UUID 格式的 ticket_id。

回應結構

TriggerSecretsScrubStatus
欄位型別必填說明
batch_sizeinteger是Rows per keyset page
errorstring | null否Exception type (+ numeric driver error code) of a failed run; never a value
executeboolean是False: dry run (counts only); true: rows rewritten
iac_state_commandTriggerSecretsScrubStoreCounts是custom_table_iac_state command rows stamped before callback redaction
iac_state_triggerTriggerSecretsScrubStoreCounts是custom_table_iac_state trigger rows (declared spec at rest)
status"processing" | "completed" | "failed"是Ticket state
store"iac_state_trigger" | "iac_state_command" | "table_history" | null否Store of the last finished page
table_historyTriggerSecretsScrubStoreCounts是custom_table_record_history schema_triggers_update rows
ticket_idstring是Ticket id returned by the POST

範例

完成的 dry run（示意計數）

請求
{
  "pathParams": {
    "ticket_id": "66666666-6666-4666-8666-666666666666"
  }
}
回應200
{
  "ticket_id": "66666666-6666-4666-8666-666666666666",
  "status": "completed",
  "execute": false,
  "batch_size": 200,
  "store": "table_history",
  "iac_state_trigger": {
    "scanned": 12,
    "needs_rewrite": 3,
    "rewritten": 0
  },
  "iac_state_command": {
    "scanned": 4,
    "needs_rewrite": 1,
    "rewritten": 0
  },
  "table_history": {
    "scanned": 20,
    "needs_rewrite": 6,
    "rewritten": 0
  },
  "error": null
}

錯誤

驗證錯誤範例列出識別欄位；部署中的驗證器也可能回傳 input 與 ctx。錯誤訊息 URL 的版本由建置決定，因此使用 pydantic-version 佔位符。

狀態發生條件錯誤本文
403需通過 BaseRoot、SuperRoot、CloudManager root key 檢查。範例顯示無效 CloudManager key。
{
  "detail": "CloudManager access denied: Invalid X-CLOUD-TOKEN"
}
404Ticket 不存在，或其狀態列已逾期。
{
  "detail": "Task not found or has expired"
}
422ticket_id 不符合 UUID 格式。
{
  "detail": [
    {
      "type": "string_pattern_mismatch",
      "loc": [
        "path",
        "ticket_id"
      ],
      "msg": "String should match pattern '^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$'",
      "input": "not-a-ticket",
      "ctx": {
        "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
      }
    }
  ]
}
POST
路由範本/root/custom-tables/run-due-triggers

執行到期的資料表排程觸發器

用途

認領到期的 schedule 觸發器、建立待執行 run、重新派送孤兒暫存變更，並回收遺失的 pending 與停滯的 running 觸發器 run（以 trigger_runs_requeued 回報；門檻 300 秒，每次 tick 最多 500 筆）。

適用時機

由每分鐘至少一次的內部 cron、EventBridge 或 Cloudflare 排程呼叫。

實際掛載路徑
  • 完整路由/root/custom-tables/run-due-triggers

範圍

範圍是否提供驗證與權限
完整路由可使用BaseRoot X-ADMIN-TOKEN

參數

欄位位置型別必填說明
table_limitqueryint 1..2000否本次最多認領幾張候選資料表，可填 1 到 2,000，預設為 200。
record_limitqueryint 1..10000否每個 date_column_reached 觸發器每一頁 cursor page 的實體 live 列數，可填 1 到 10,000，預設為 1,000。若整頁都沒有到期列，一次 tick 最多掃描 10 頁，因此每一筆 live 列都會被輪替到。

回應結構

RunDueTriggersResponse
欄位型別必填說明
runs_createdinteger是Pending trigger-run rows inserted and enqueued
staged_changes_requeuedinteger否Approval-gate recovery (spec §5 step 7): orphaned staged changes (pending under a terminal process, or stale-applying) re-dispatched this tick
tables_scannedinteger是Candidate tables claimed this tick
tables_with_schedulesinteger是Of those, tables carrying a schedule trigger
trigger_runs_requeuedinteger否Lost-pending or stale-running trigger runs reclaimed and re-dispatched this tick

範例

執行一次排程觸發器 tick

請求
{
  "pathParams": {},
  "query": {
    "table_limit": "200",
    "record_limit": "1000"
  }
}
回應200
{
  "tables_scanned": 12,
  "tables_with_schedules": 3,
  "runs_created": 4,
  "staged_changes_requeued": 1,
  "trigger_runs_requeued": 0
}

錯誤

驗證錯誤範例列出識別欄位；部署中的驗證器也可能回傳 input 與 ctx。錯誤訊息 URL 的版本由建置決定，因此使用 pydantic-version 佔位符。

狀態發生條件錯誤本文
403root token 缺少或無效。
{
  "detail": "BaseRoot access denied: Invalid X-ADMIN-TOKEN"
}
POST
路由範本/root/custom-tables/{table_id}/purge

永久清除自訂資料表

用途

永久刪除資料表、資料列、歷程及跨表相依設定。

適用時機

保留期結束且已確認不需還原垃圾桶資料表時，由維運人員執行。

實際掛載路徑
  • 完整路由/root/custom-tables/{table_id}/purge

範圍

範圍是否提供驗證與權限
完整路由可使用CloudManager root keys (X-ADMIN-TOKEN + X-SUPER-TOKEN + X-CLOUD-TOKEN)

參數

欄位位置型別必填說明
table_idpathuuid是要永久清除的資料表 UUID。
forcequeryboolean否設為 true 可略過「必須已在垃圾桶」的保護條件。

回應結構

PurgeTableResponse
欄位型別必填說明
messagestring是Human-readable outcome
purgedboolean是True when the table was permanently destroyed
table_idstring是The purged table's id

範例

永久清除垃圾桶資料表

請求
{
  "pathParams": {
    "table_id": "11111111-1111-4111-8111-111111111111"
  },
  "query": {
    "force": "false"
  }
}
回應200
{
  "table_id": "11111111-1111-4111-8111-111111111111",
  "purged": true,
  "message": "Table permanently purged (records, history, and dependent config removed)"
}

錯誤

驗證錯誤範例列出識別欄位；部署中的驗證器也可能回傳 input 與 ctx。錯誤訊息 URL 的版本由建置決定，因此使用 pydantic-version 佔位符。

狀態發生條件錯誤本文
404資料表不存在。
{
  "detail": "Table not found"
}
409資料表尚未軟刪除，且未設定 force=true。
{
  "detail": "Table must be soft-deleted (in trash) before purge; pass force=true to override"
}
423無法在此表，或 purge 必須改寫的表（link 來源表、incoming rollup 或 lookup fallback 的持有表、規則相依表）上取得遷移鎖。detail 會指出持有者目前的操作，例如 unlink_table 或 add_column。這些鎖要到 purge 提交前置效果之後才會嘗試取得（見 unique_tuple 的 400）；回 423 並不會撤銷那些效果。
{
  "detail": "Table is currently locked for operation: delete_table"
}
409另一張表的 same_dimension_reference 規則以此表為參照目標或維度表。請先移除該規則；這項檢查在任何變更之前進行，即使 force=true 也一樣。
{
  "detail": {
    "error": "same_dimension_reference_dependency"
  }
}
400存活表的 unique_tuple 規則用到 purge 會剝除的連結欄位。與 423 相同，這個拒絕發生在 purge 已提交前置效果之後，而這些效果會保持已提交：此表上或涉及此表的待審暫存變更已被捨棄（審核以 table purged 為由取消），仍在 pending 或 applying 的指令計畫已被標為失敗（執行稽核改為 failed，並送出失敗 callback），若以 force=true 清除現行資料表，資料表也已移入垃圾桶。
{
  "detail": "remove the dependent unique tuple rule before purging its link target"
}
400存活資料表的 `date_interval_exclusion` 規則把這次 purge 會剝除的 link 欄位當作分割。和 unique-tuple 拒絕一樣，它出現在 purge 已 commit 其前置效果之後，那些效果仍然保留。請先移除規則，再重新執行 purge。
{
  "detail": "remove the dependent date interval exclusion rule before purging its link target"
}
GET
路由範本/root/hotfix/custom-table-lock/{table_id}

查看自訂資料表鎖

用途

回傳此資料表目前存放在 Redis 中的遷移鎖：lock_id、operation（持有者正在進行的操作，例如 add_column）、acquired_at 與 expires_at（ISO 8601，UTC）。每把鎖取得時的 TTL 都是 600 秒；背景遷移執行期間會持續續期，因此 expires_at 會一直往後延。

適用時機

在判斷鎖是否真的卡住、以及是否需要強制釋放前使用。

實際掛載路徑
  • 完整路由/root/hotfix/custom-table-lock/{table_id}

範圍

範圍是否提供驗證與權限
完整路由可使用CloudManager root keys (X-ADMIN-TOKEN + X-SUPER-TOKEN + X-CLOUD-TOKEN)

參數

欄位位置型別必填說明
table_idpathuuid是要檢查的資料表 UUID。

回應結構

Dict[str, Any]

OpenAPI 快照中沒有此模型的頂層元件欄位。

範例

確認資料表目前未上鎖

請求
{
  "pathParams": {
    "table_id": "11111111-1111-4111-8111-111111111111"
  }
}
回應200
{}

錯誤

驗證錯誤範例列出識別欄位；部署中的驗證器也可能回傳 input 與 ctx。錯誤訊息 URL 的版本由建置決定，因此使用 pydantic-version 佔位符。

狀態發生條件錯誤本文
403三組 CloudManager root token 之一缺少或錯誤。X-ADMIN-TOKEN 錯誤時，會先由 /root 路由以 BaseRoot access denied: Invalid X-ADMIN-TOKEN 拒絕。
{
  "detail": "CloudManager access denied: Invalid X-CLOUD-TOKEN"
}
DELETE
路由範本/root/hotfix/custom-table-lock/{table_id}

強制釋放自訂資料表鎖

用途

不論擁有者為何，強制移除一把仍存在的資料表遷移鎖。

適用時機

確認程序已崩潰、鎖已卡住且不能等待 TTL 時，作為緊急復原手段。

實際掛載路徑
  • 完整路由/root/hotfix/custom-table-lock/{table_id}

範圍

範圍是否提供驗證與權限
完整路由可使用CloudManager root keys (X-ADMIN-TOKEN + X-SUPER-TOKEN + X-CLOUD-TOKEN)

參數

欄位位置型別必填說明
table_idpathuuid是要強制解鎖的資料表 UUID。

回應結構

Dict[str, Any]

OpenAPI 快照中沒有此模型的頂層元件欄位。

範例

強制釋放卡住的遷移鎖

請求
{
  "pathParams": {
    "table_id": "11111111-1111-4111-8111-111111111111"
  }
}
回應200
{
  "message": "Lock force-released successfully",
  "released_lock": {
    "lock_id": "f1e2d3c4-b5a6-4978-8a69-5b4c3d2e1f00",
    "operation": "add_column",
    "acquired_at": "2026-09-04T02:11:07.123456+00:00",
    "expires_at": "2026-09-04T02:21:07.123456+00:00"
  }
}

錯誤

驗證錯誤範例列出識別欄位；部署中的驗證器也可能回傳 input 與 ctx。錯誤訊息 URL 的版本由建置決定，因此使用 pydantic-version 佔位符。

狀態發生條件錯誤本文
404資料表目前沒有有效鎖。
{
  "detail": "No active lock found for this table"
}
500路由讀取時鎖還在，但刪除時已經消失：持有者在這段期間釋放了它，或它的 600 秒 TTL 剛好到期。儘管訊息這樣寫，這其實是上述的時間差，而不是 Redis 故障（沒有 Redis 用戶端的 worker 會回上面的 404）。請再呼叫一次 lockGet；回傳 {} 代表資料表現在已解鎖。
{
  "detail": "Failed to release lock — Redis may be unavailable"
}
GET
路由範本/root/hotfix/custom-table-index-suggestions/{table_id}

取得單一資料表索引建議

用途

為一張自訂資料表的 JSON 篩選欄位產生 MySQL 虛擬欄位與索引 DDL 建議。

適用時機

分析熱欄位、評估索引預算並準備維運側 DDL 時使用。

實際掛載路徑
  • 完整路由/root/hotfix/custom-table-index-suggestions/{table_id}

範圍

範圍是否提供驗證與權限
完整路由可使用CloudManager root keys (X-ADMIN-TOKEN + X-SUPER-TOKEN + X-CLOUD-TOKEN)

參數

欄位位置型別必填說明
table_idpathuuid是要分析的資料表 UUID。

回應結構

CustomTableIndexPlan
欄位型別必填說明
already_appliedstring[]是未指定
company_idstring (uuid)是未指定
index_budgetCustomTableIndexBudget是未指定
notesstring[]是未指定
projectionsCustomTableIndexProjection[]是未指定
suggestionsstring[]是未指定
table_idstring (uuid)是未指定
table_namestring是未指定

範例

取得訂單資料表的索引建議

請求
{
  "pathParams": {
    "table_id": "11111111-1111-4111-8111-111111111111"
  }
}
回應200
{
  "table_id": "11111111-1111-4111-8111-111111111111",
  "table_name": "訂單",
  "suggestions": [],
  "already_applied": [],
  "index_budget": {
    "current_secondary_indexes": 8,
    "remaining_to_64_cap": 56
  },
  "notes": [
    "READ-ONLY advisory — these statements are NOT executed by this endpoint.",
    "Apply operator-side AFTER POST /root/hotfix/db/alembic (per-tenant dynamic DDL, not ORM autogen).",
    "Apply only to genuinely hot columns — InnoDB caps custom_table_records at 64 secondary indexes.",
    "Index names embed two UUIDs and may exceed MySQL's 64-char identifier limit; truncate if so.",
    "Runbook: docs/superpowers/runbooks/2026-06-16-custom-tables-json-index-optimization.md"
  ]
}

錯誤

驗證錯誤範例列出識別欄位；部署中的驗證器也可能回傳 input 與 ctx。錯誤訊息 URL 的版本由建置決定，因此使用 pydantic-version 佔位符。

狀態發生條件錯誤本文
404資料表不存在，或在垃圾桶中。
{
  "detail": "CustomTable Not found"
}
422資料表結構中有欄位的內部鍵不是系統產生的 col_<hex> 格式（舊版結構），或資料表 id 不是 36 字元的小寫 UUID。detail 會指出問題所在；這張資料表無法產生 DDL。
{
  "detail": "Cannot generate index suggestions: Invalid column name format: customer_name"
}
GET
路由範本/root/hotfix/custom-table-index-suggestions

取得一個範圍的索引建議

用途

彙整指定聊天室、部門或公司內每一張資料表（包括垃圾桶中的表）的索引建議與共用索引預算。無法產生建議的資料表仍會列出，但清單為空並附上 error 字串（「Cannot generate suggestions: …」），整個呼叫不會因此失敗。

適用時機

要以租戶範圍規劃一批 JSON 篩選索引時使用。

實際掛載路徑
  • 完整路由/root/hotfix/custom-table-index-suggestions

範圍

範圍是否提供驗證與權限
完整路由可使用CloudManager root keys (X-ADMIN-TOKEN + X-SUPER-TOKEN + X-CLOUD-TOKEN)

參數

欄位位置型別必填說明
scope_typequeryenum:chatroom|department|company是資料表範圍種類：chatroom、department 或 company。
scope_idqueryuuid是該範圍的聊天室、部門或公司 UUID。

回應結構

CustomTableScopedIndexPlan
欄位型別必填說明
index_budgetCustomTableIndexBudget是未指定
notesstring[]是未指定
reclaimable_orphansCustomTableIndexOrphanSummary是未指定
scope_idstring (uuid)是未指定
scope_type"chatroom" | "department" | "company"是未指定
table_countinteger是未指定
tablesCustomTableIndexPlan[]是未指定

範例

取得聊天室內全部索引建議

請求
{
  "pathParams": {},
  "query": {
    "scope_type": "chatroom",
    "scope_id": "22222222-2222-4222-8222-222222222222"
  }
}
回應200
{
  "scope_type": "chatroom",
  "scope_id": "22222222-2222-4222-8222-222222222222",
  "table_count": 1,
  "tables": [
    {
      "table_id": "11111111-1111-4111-8111-111111111111",
      "table_name": "訂單",
      "suggestions": [],
      "already_applied": []
    }
  ],
  "index_budget": {
    "current_secondary_indexes": 8,
    "remaining_to_64_cap": 56
  },
  "reclaimable_orphans": null,
  "notes": [
    "READ-ONLY advisory — these statements are NOT executed by this endpoint.",
    "Apply operator-side AFTER POST /root/hotfix/db/alembic (per-tenant dynamic DDL, not ORM autogen).",
    "Apply only to genuinely hot columns — InnoDB caps custom_table_records at 64 secondary indexes.",
    "Index names embed two UUIDs and may exceed MySQL's 64-char identifier limit; truncate if so.",
    "Runbook: docs/superpowers/runbooks/2026-06-16-custom-tables-json-index-optimization.md"
  ]
}

錯誤

驗證錯誤範例列出識別欄位；部署中的驗證器也可能回傳 input 與 ctx。錯誤訊息 URL 的版本由建置決定，因此使用 pydantic-version 佔位符。

狀態發生條件錯誤本文
422scope_type 不是支援的三種範圍之一。
{
  "detail": "Unsupported scope_type: workspace. Must be one of: ['chatroom', 'department', 'company']"
}
GET
路由範本/root/hotfix/custom-table-index-orphans

取得孤兒虛擬索引欄位

用途

找出不再由任何有效自訂資料表欄位使用的 MySQL 虛擬欄位，並產生 DROP DDL。

適用時機

索引預算吃緊，或資料表與欄位大量刪除後清查遺留物件時使用。

實際掛載路徑
  • 完整路由/root/hotfix/custom-table-index-orphans

範圍

範圍是否提供驗證與權限
完整路由可使用CloudManager root keys (X-ADMIN-TOKEN + X-SUPER-TOKEN + X-CLOUD-TOKEN)

回應結構

CustomTableIndexOrphans
欄位型別必填說明
availableboolean是未指定
dropsstring[]是未指定
existing_virtual_columnsinteger是未指定
live_column_idsinteger是未指定
notesstring[]是未指定
orphan_countinteger是未指定

範例

檢查全域孤兒索引欄位

請求
{
  "pathParams": {}
}
回應200
{
  "available": true,
  "orphan_count": 0,
  "drops": [],
  "existing_virtual_columns": 8,
  "live_column_ids": 24,
  "notes": [
    "READ-ONLY advisory — DROP statements are NOT executed by this endpoint.",
    "Orphan detection is GLOBAL across all scopes (col_<hex> ids are not scope-scoped).",
    "DROP COLUMN <col>_virtual also drops the index that covers it.",
    "Apply operator-side AFTER POST /root/hotfix/db/alembic."
  ]
}

錯誤

驗證錯誤範例列出識別欄位；部署中的驗證器也可能回傳 input 與 ctx。錯誤訊息 URL 的版本由建置決定，因此使用 pydantic-version 佔位符。

狀態發生條件錯誤本文
403三組 CloudManager root token 之一缺少或錯誤。X-ADMIN-TOKEN 錯誤時，會先由 /root 路由以 BaseRoot access denied: Invalid X-ADMIN-TOKEN 拒絕。
{
  "detail": "CloudManager access denied: Invalid X-CLOUD-TOKEN"
}
POST
路由範本/root/hotfix/custom-table-index-suggestions/{table_id}/apply

套用單一資料表索引建議

用途

對指定資料表執行尚未套用的 MySQL 虛擬欄位與索引 DDL。

適用時機

維運人員檢查建議與索引預算後，才在受控維護時段執行。

實際掛載路徑
  • 完整路由/root/hotfix/custom-table-index-suggestions/{table_id}/apply

範圍

範圍是否提供驗證與權限
完整路由可使用CloudManager root keys (X-ADMIN-TOKEN + X-SUPER-TOKEN + X-CLOUD-TOKEN)

參數

欄位位置型別必填說明
table_idpathuuid是要套用索引的資料表 UUID。
dry_runqueryboolean否預設為 false，會直接執行尚未套用的 DDL。設為 true 只預覽 pending 與 already_applied，不執行 DDL。

回應結構

CustomTableIndexApplyResponse
欄位型別必填說明
already_appliedstring[]是未指定
appliedstring[]是未指定
dry_runboolean是未指定
errorsCustomTableIndexDdlError[]是未指定
index_budgetCustomTableIndexBudget是未指定
notesstring[]是未指定
pendingstring[]是未指定
table_idstring (uuid)是未指定
table_namestring是未指定

範例

以 dry run 預覽索引套用結果

請求
{
  "pathParams": {
    "table_id": "11111111-1111-4111-8111-111111111111"
  },
  "query": {
    "dry_run": "true"
  }
}
回應200
{
  "table_id": "11111111-1111-4111-8111-111111111111",
  "table_name": "訂單",
  "dry_run": true,
  "applied": [],
  "already_applied": [],
  "pending": [],
  "errors": [],
  "index_budget": {
    "current_secondary_indexes": 8,
    "remaining_to_64_cap": 56
  },
  "notes": [
    "Apply operator-side AFTER POST /root/hotfix/db/alembic (per-tenant dynamic DDL, not ORM autogen).",
    "Apply only to genuinely hot columns — InnoDB caps custom_table_records at 64 secondary indexes.",
    "Index names embed two UUIDs and may exceed MySQL's 64-char identifier limit; truncate if so.",
    "Runbook: docs/superpowers/runbooks/2026-06-16-custom-tables-json-index-optimization.md"
  ]
}

錯誤

驗證錯誤範例列出識別欄位；部署中的驗證器也可能回傳 input 與 ctx。錯誤訊息 URL 的版本由建置決定，因此使用 pydantic-version 佔位符。

狀態發生條件錯誤本文
404資料表不存在，或在垃圾桶中。
{
  "detail": "CustomTable Not found"
}
422資料表結構中有欄位的內部鍵不是系統產生的 col_<hex> 格式（舊版結構），或資料表 id 不是 36 字元的小寫 UUID。不會執行任何 DDL。
{
  "detail": "Cannot generate index suggestions: Invalid column name format: customer_name"
}
400無法存取 MySQL information_schema，因此不能保證冪等套用。
{
  "detail": "information_schema probe unavailable (MySQL-only path): <driver error>"
}
POST
路由範本/root/hotfix/custom-table-trigger-runs/requeue

重新派送卡住的觸發器 run

用途

把超過門檻仍為 pending 的自訂資料表觸發器 run 重新排入佇列，並回收最後更新時間早於門檻（至少 300 秒）的 running run：它們會被重設為 pending，並從第一個未成功的 action 繼續。

適用時機

程序可能在資料提交後、佇列發布前崩潰，造成 pending run 孤立時使用；或是 worker 在執行中途停止，留下停滯的 running run 時使用。

實際掛載路徑
  • 完整路由/root/hotfix/custom-table-trigger-runs/requeue

範圍

範圍是否提供驗證與權限
完整路由可使用CloudManager root keys (X-ADMIN-TOKEN + X-SUPER-TOKEN + X-CLOUD-TOKEN)

參數

欄位位置型別必填說明
older_than_secondsqueryint >= 0否pending 超過幾秒（以 created_at 起算）的 run 會重新排入；running run 以 updated_at 起算，並有固定的 300 秒下限。預設為 300。
limitqueryint 1..2000否單次最多重新派送幾筆，可填 1 到 2,000，預設為 500。這是 pending 與 running 共用的單一額度，由最舊的開始消耗（running 以 updated_at、pending 以 created_at 計算），因此某一類的大量舊積壓可能讓另一類留到下一次呼叫才處理。

回應結構

Dict[str, Any]

OpenAPI 快照中沒有此模型的頂層元件欄位。

範例

重新派送逾時 pending run

請求
{
  "pathParams": {},
  "query": {
    "older_than_seconds": "300",
    "limit": "500"
  }
}
回應200
{
  "requeued": 2
}

錯誤

驗證錯誤範例列出識別欄位；部署中的驗證器也可能回傳 input 與 ctx。錯誤訊息 URL 的版本由建置決定，因此使用 pydantic-version 佔位符。

狀態發生條件錯誤本文
403三組 CloudManager root token 之一缺少或錯誤。X-ADMIN-TOKEN 錯誤時，會先由 /root 路由以 BaseRoot access denied: Invalid X-ADMIN-TOKEN 拒絕。
{
  "detail": "CloudManager access denied: Invalid X-CLOUD-TOKEN"
}
POST
路由範本/root/hotfix/custom-table-staged-changes/requeue

重新派送孤兒暫存變更

用途

重新派送終止流程下仍 pending，或 worker 逾時卡在 applying 的自訂資料表暫存變更。

適用時機

覆核已結束但變更沒有套用，或套用 worker 中途死亡時使用。

實際掛載路徑
  • 完整路由/root/hotfix/custom-table-staged-changes/requeue

範圍

範圍是否提供驗證與權限
完整路由可使用CloudManager root keys (X-ADMIN-TOKEN + X-SUPER-TOKEN + X-CLOUD-TOKEN)

參數

欄位位置型別必填說明
limitqueryint 1..2000否本次最多重新派送幾筆，可填 1 到 2,000，預設為 500。

回應結構

StagedChangeRequeueResponse
欄位型別必填說明
requeuedinteger是Orphaned staged changes re-dispatched this call

範例

重新派送孤兒暫存變更

請求
{
  "pathParams": {},
  "query": {
    "limit": "500"
  }
}
回應200
{
  "requeued": 1
}

錯誤

驗證錯誤範例列出識別欄位；部署中的驗證器也可能回傳 input 與 ctx。錯誤訊息 URL 的版本由建置決定，因此使用 pydantic-version 佔位符。

狀態發生條件錯誤本文
403三組 CloudManager root token 之一缺少或錯誤。X-ADMIN-TOKEN 錯誤時，會先由 /root 路由以 BaseRoot access denied: Invalid X-ADMIN-TOKEN 拒絕。
{
  "detail": "CloudManager access denied: Invalid X-CLOUD-TOKEN"
}
POST
路由範本/root/hotfix/custom-table-sort-order-backfill

啟動資料列排序回填

用途

替所有自訂資料表（包括垃圾桶中的表）裡 sort_order 為 NULL 的現行資料列，依 created_at 順序在每張表內編號 1..N。已有值的 sort_order 不會變動。

適用時機

在加入 sort_order 欄位的資料庫遷移完成後、所有資料列的 sort_order 仍為 NULL 時執行一次。每張表的編號都從 1 重新開始，因此若資料表已有部分 sort_order 值，回填的資料列會與既有編號重複。

實際掛載路徑
  • 完整路由/root/hotfix/custom-table-sort-order-backfill

範圍

範圍是否提供驗證與權限
完整路由可使用CloudManager root keys (X-ADMIN-TOKEN + X-SUPER-TOKEN + X-CLOUD-TOKEN)

回應結構

TaskResponse
欄位型別必填說明
messagestring否未指定
ticket_idstring是Ticket ID

範例

啟動 sort_order 回填工作

請求
{
  "pathParams": {}
}
回應200
{
  "message": "Sort order backfill task started. Use the ticket ID to track progress.",
  "ticket_id": "66666666-6666-4666-8666-666666666666"
}

錯誤

驗證錯誤範例列出識別欄位；部署中的驗證器也可能回傳 input 與 ctx。錯誤訊息 URL 的版本由建置決定，因此使用 pydantic-version 佔位符。

狀態發生條件錯誤本文
403三組 CloudManager root token 之一缺少或錯誤。X-ADMIN-TOKEN 錯誤時，會先由 /root 路由以 BaseRoot access denied: Invalid X-ADMIN-TOKEN 拒絕。
{
  "detail": "CloudManager access denied: Invalid X-CLOUD-TOKEN"
}
GET
路由範本/root/hotfix/custom-table-sort-order-backfill/{ticket_id}

取得排序回填狀態

用途

以 ticket_id 取得 sort_order 回填工作的進度、結果或錯誤。

適用時機

啟動回填後輪詢，直到 status 變成 completed 或 failed。

實際掛載路徑
  • 完整路由/root/hotfix/custom-table-sort-order-backfill/{ticket_id}

範圍

範圍是否提供驗證與權限
完整路由可使用CloudManager root keys (X-ADMIN-TOKEN + X-SUPER-TOKEN + X-CLOUD-TOKEN)

參數

欄位位置型別必填說明
ticket_idpathuuid是啟動回填時回傳的工作 ticket UUID。

回應結構

Dict[str, Any]

OpenAPI 快照中沒有此模型的頂層元件欄位。

範例

取得已完成的回填結果

請求
{
  "pathParams": {
    "ticket_id": "66666666-6666-4666-8666-666666666666"
  }
}
回應200
{
  "ticket_id": "66666666-6666-4666-8666-666666666666",
  "status": "completed",
  "progress": 100,
  "tables_processed": 3,
  "total_tables": 3,
  "total_rows_updated": 42,
  "results": [
    {
      "table_id": "11111111-1111-4111-8111-111111111111",
      "updated": 30
    },
    {
      "table_id": "12121212-1212-4212-8212-121212121212",
      "updated": 12
    },
    {
      "table_id": "13131313-1313-4313-8313-131313131313",
      "updated": 0,
      "reason": "no records with NULL sort_order"
    }
  ]
}

錯誤

驗證錯誤範例列出識別欄位；部署中的驗證器也可能回傳 input 與 ctx。錯誤訊息 URL 的版本由建置決定，因此使用 pydantic-version 佔位符。

狀態發生條件錯誤本文
404ticket 不存在或狀態資料已過期。
{
  "detail": "Task not found or has expired"
}
GET
路由範本/root/hotfix/custom-table-agent-deliveries

列出仍待確認的 agent 派送標記

用途

列出每筆已確認的 agent 指令寫入所留下的私有 per-execution 標記——這些標記會保留到自然語言結果跨過頻道可見性邊界為止——並附上標記狀態、絕對到期時間、replay guard 是否仍有效、所屬指令與範圍，以及該列的存在時間。

適用時機

當某個 agent 指令對同一個人、在同一個頻道上一直回覆寫入保護失敗（confirmation_unavailable）時使用。調解查找以指令、呼叫的使用者或客戶，以及頻道（LINE 另加群組）為鍵，所以積壓的標記只會卡住這個人使用的這個指令，而不是整個聊天室的所有指令：該指令 pending 卡了好幾小時的標記就是候選，可用 command_id 把列表縮小到它們。也可以用 state=expired 查看惰性到期已經釋放了哪些。

實際掛載路徑
  • 完整路由/root/hotfix/custom-table-agent-deliveries

範圍

範圍是否提供驗證與權限
完整路由可使用CloudManager root keys (X-ADMIN-TOKEN + X-SUPER-TOKEN + X-CLOUD-TOKEN)

參數

欄位位置型別必填說明
command_idquerystring 1..36否只列出單一 command id 的標記，長度 1 到 36 字元。省略則掃描所有指令。
statequeryenum:pending|expired否要列出的標記狀態：pending（預設）或 expired。惰性到期的標記仍可被確認，所以整理流程需要能把它們列出來。
older_than_hoursquerynumber >= 0否只回傳執行紀錄超過這麼多小時的標記，預設 0 代表全部回傳。可以填小數。
limitqueryint 1..500否單次最多回傳幾筆，可填 1 到 500，預設 100。結果由舊到新排序。

回應結構

AgentDeliveryMarkerListResponse
欄位型別必填說明
rowsAgentDeliveryMarkerRow[]是未指定
total_listedinteger是未指定

範例

列出超過兩小時的 pending 標記

請求
{
  "pathParams": {},
  "query": {
    "state": "pending",
    "older_than_hours": "2",
    "limit": "100"
  }
}
回應200
{
  "total_listed": 1,
  "rows": [
    {
      "execution_id": "88888888-8888-4888-8888-888888888888",
      "command_id": "77777777-7777-4777-8777-777777777777",
      "command_name": "排班登記",
      "execution_status": "succeeded",
      "channel_scope": "line_group",
      "marker_state": "pending",
      "expires_at": "2026-09-04T02:26:07Z",
      "in_window": false,
      "scope_chatroom_id": "22222222-2222-4222-8222-222222222222",
      "scope_department_id": null,
      "scope_company_id": null,
      "created_at": "2026-09-04T02:11:07",
      "age_hours": 5.4
    }
  ]
}

錯誤

驗證錯誤範例列出識別欄位；部署中的驗證器也可能回傳 input 與 ctx。錯誤訊息 URL 的版本由建置決定，因此使用 pydantic-version 佔位符。

狀態發生條件錯誤本文
403三個 CloudManager root token 之中有一個缺少或錯誤。
{
  "detail": "CloudManager access denied: Invalid X-CLOUD-TOKEN"
}
422state 不是 pending 或 expired、older_than_hours 為負數、limit 超出 1..500 範圍，或 command_id 不在 1..36 字元之間。
{
  "detail": [
    {
      "type": "literal_error",
      "loc": [
        "query",
        "state"
      ],
      "msg": "Input should be 'pending' or 'expired'",
      "input": "acknowledged",
      "ctx": {
        "expected": "'pending' or 'expired'"
      }
    }
  ]
}
POST
路由範本/root/hotfix/custom-table-agent-deliveries/acknowledge

確認過期的 agent 派送標記（含預覽模式）

用途

把指定的派送標記從 pending 或 expired 翻成 acknowledged，讓對應的執行紀錄不再佔用調解容量，並逐一回報每個 execution id 的結果。execute=false 只預覽結果、不寫入。

適用時機

在與租戶確認過已執行的寫入確實可見或被接受之後，對列表端點顯示為 pending 且早已超過視窗的標記執行。

實際掛載路徑
  • 完整路由/root/hotfix/custom-table-agent-deliveries/acknowledge

範圍

範圍是否提供驗證與權限
完整路由可使用CloudManager root keys (X-ADMIN-TOKEN + X-SUPER-TOKEN + X-CLOUD-TOKEN)

請求結構

AgentDeliveryAckRequest
欄位型別必填說明
executeboolean否False previews per-id outcomes; true flips the markers.
execution_idsstring[]是未指定
forceboolean否Required to acknowledge a pending marker whose reconciliation window is still live — that cancels an active replay guard and re-enables an in-window duplicate execution. Expired or past-window markers never need it.

回應結構

AgentDeliveryAckResponse
欄位型別必填說明
executedboolean是未指定
resultsAgentDeliveryAckResult[]是未指定

範例

只預覽結果、不寫入（execute=false）

請求
{
  "pathParams": {},
  "body": {
    "execution_ids": [
      "88888888-8888-4888-8888-888888888888"
    ],
    "execute": false
  }
}
回應200
{
  "executed": false,
  "results": [
    {
      "execution_id": "88888888-8888-4888-8888-888888888888",
      "outcome": "would_acknowledge"
    }
  ]
}

正式提交確認（execute=true）

請求
{
  "pathParams": {},
  "body": {
    "execution_ids": [
      "88888888-8888-4888-8888-888888888888"
    ],
    "execute": true
  }
}
回應200
{
  "executed": true,
  "results": [
    {
      "execution_id": "88888888-8888-4888-8888-888888888888",
      "outcome": "acknowledged"
    }
  ]
}

錯誤

驗證錯誤範例列出識別欄位；部署中的驗證器也可能回傳 input 與 ctx。錯誤訊息 URL 的版本由建置決定，因此使用 pydantic-version 佔位符。

狀態發生條件錯誤本文
403三個 CloudManager root token 之中有一個缺少或錯誤。
{
  "detail": "CloudManager access denied: Invalid X-CLOUD-TOKEN"
}
422execution_ids 是空陣列或超過 200 筆，或其中某個 id 為空字串、超過 36 字元。
{
  "detail": [
    {
      "type": "too_short",
      "loc": [
        "body",
        "execution_ids"
      ],
      "msg": "List should have at least 1 item after validation, not 0",
      "input": [],
      "ctx": {
        "field_type": "List",
        "min_length": 1,
        "actual_length": 0
      }
    }
  ]
}
POST
路由範本/root/hotfix/custom-table-command-callback-runs/requeue

重新派送卡住的指令 callback run

用途

一次清掉指令 callback 卡住的三種狀態：發布佇列時遺失的 pending、仍未達重試上限的 failed、以及 worker 死掉的 running；後兩者會先重設為 pending，再全部重新發布。

適用時機

指令已完成但 callback 沒有送達呼叫方時使用：指令成功很久之後 callback run 仍停在 pending 或 running，或 worker 部署中斷了進行中的派送。

實際掛載路徑
  • 完整路由/root/hotfix/custom-table-command-callback-runs/requeue

範圍

範圍是否提供驗證與權限
完整路由可使用CloudManager root keys (X-ADMIN-TOKEN + X-SUPER-TOKEN + X-CLOUD-TOKEN)

參數

欄位位置型別必填說明
older_than_secondsqueryint >= 0否只處理停滯超過幾秒的 run，預設為 300；判斷依據是 pending 的 created_at 與 failed 的 updated_at。
limitqueryint 1..2000否單次最多復原幾筆，可填 1 到 2,000，預設為 500。

回應結構

CommandCallbackRequeueResponse
欄位型別必填說明
requeuedinteger是未指定

範例

清掉停滯超過五分鐘的 callback

請求
{
  "pathParams": {},
  "query": {
    "older_than_seconds": "300",
    "limit": "500"
  }
}
回應200
{
  "requeued": 7
}

錯誤

驗證錯誤範例列出識別欄位；部署中的驗證器也可能回傳 input 與 ctx。錯誤訊息 URL 的版本由建置決定，因此使用 pydantic-version 佔位符。

狀態發生條件錯誤本文
403三個 CloudManager root token 之中有一個缺少或錯誤。
{
  "detail": "CloudManager access denied: Invalid X-CLOUD-TOKEN"
}
422limit 超出 1..2,000 範圍，或 older_than_seconds 為負數。
{
  "detail": [
    {
      "type": "less_than_equal",
      "loc": [
        "query",
        "limit"
      ],
      "msg": "Input should be less than or equal to 2000",
      "input": "5000",
      "ctx": {
        "le": 2000
      }
    }
  ]
}
POST
路由範本/root/hotfix/custom-table-command-executions/prune

清除超過 180 天保留期的指令稽核紀錄

用途

硬刪除已達終態（succeeded 或 failed）且 created_at 超過 180 天的自訂資料表指令執行稽核紀錄，並回報刪除筆數、保留天數與這次實際使用的 cutoff 時間點。被 effect identity claim 參照的執行是該業務事件持久的 replay receipt，永遠不會被刪除：超過 cutoff 後只會清空它私有的 lifecycle_snapshot。

適用時機

以較低頻率的維護節奏執行，控制指令稽核表的大小；或在該表開始造成儲存壓力、稽核清單查詢變慢時執行。

實際掛載路徑
  • 完整路由/root/hotfix/custom-table-command-executions/prune

範圍

範圍是否提供驗證與權限
完整路由可使用CloudManager root keys (X-ADMIN-TOKEN + X-SUPER-TOKEN + X-CLOUD-TOKEN)

回應結構

CommandExecutionPruneResponse
欄位型別必填說明
cutoffstring (date-time)是未指定
prunedinteger是未指定
retention_daysinteger否未指定

範例

清除超過保留期的終態指令稽核

請求
{
  "pathParams": {}
}
回應200
{
  "pruned": 1284,
  "retention_days": 180,
  "cutoff": "2026-01-26T11:04:07"
}

錯誤

驗證錯誤範例列出識別欄位；部署中的驗證器也可能回傳 input 與 ctx。錯誤訊息 URL 的版本由建置決定，因此使用 pydantic-version 佔位符。

狀態發生條件錯誤本文
403三個 CloudManager root token 之中有一個缺少或錯誤。
{
  "detail": "CloudManager access denied: Invalid X-CLOUD-TOKEN"
}
POST
路由範本/root/hotfix/custom-table-crossref-repair

掃描並修復損壞的公式跨表參照

用途

走訪所有含跨表 hop 的 FORMULA 欄位，透過 column_mapping 與權威的 link 定義重新解析配對的兩側，回報——或在 apply=true 時改寫——沒有存成應有內部鍵的配對。

適用時機

在動到連結資料表的改名或改型之後執行，或在跨表公式開始算出錯誤、空值時執行，用來判斷是不是儲存的運算式本身損壞了。

實際掛載路徑
  • 完整路由/root/hotfix/custom-table-crossref-repair

範圍

範圍是否提供驗證與權限
完整路由可使用CloudManager root keys (X-ADMIN-TOKEN + X-SUPER-TOKEN + X-CLOUD-TOKEN)

參數

欄位位置型別必填說明
applyqueryboolean否false（預設）只回報、完全不寫入；true 才會就地改寫損壞的運算式。請一律先跑預設值。

回應結構

CrossRefRepairResponse
欄位型別必填說明
appliedboolean是Whether repairs were committed
corrupted_pairsinteger是Cross-ref pairs found corrupted
itemsCrossRefRepairItem[]是Per-pair detail, capped at 500 entries
repaired_pairsinteger是Pairs rewritten (apply=true) or rewritable (apply=false)
scanned_formula_columnsinteger是FORMULA columns containing a cross-ref token
scanned_tablesinteger是Tables whose schema was inspected
skipped_locked_tablesinteger否Tables skipped because a schema-migration lock was held — rerun the sweep after the migration finishes
unrepairable_pairsinteger是Pairs needing manual attention (reported, never touched)

範例

不寫入、只預覽損壞的跨表參照（apply=false）

請求
{
  "pathParams": {},
  "query": {
    "apply": "false"
  }
}
回應200
{
  "scanned_tables": 214,
  "scanned_formula_columns": 37,
  "corrupted_pairs": 4,
  "repaired_pairs": 3,
  "unrepairable_pairs": 1,
  "skipped_locked_tables": 0,
  "applied": false,
  "items": [
    {
      "table_id": "11111111-1111-4111-8111-111111111111",
      "column_key": "col_9f2a1c",
      "pair_before": "[col_4b7e08->單價]",
      "pair_after": "[col_4b7e08->col_c31d5a]",
      "status": "repaired",
      "reason": null
    },
    {
      "table_id": "11111111-1111-4111-8111-111111111111",
      "column_key": "col_77b0e4",
      "pair_before": "[供應商->金額]",
      "pair_after": null,
      "status": "unrepairable",
      "reason": "rhs '金額' resolves to non-numeric target column 'col_2ea9f1'"
    }
  ]
}

正式提交修復（apply=true）

請求
{
  "pathParams": {},
  "query": {
    "apply": "true"
  }
}
回應200
{
  "scanned_tables": 214,
  "scanned_formula_columns": 37,
  "corrupted_pairs": 4,
  "repaired_pairs": 3,
  "unrepairable_pairs": 1,
  "skipped_locked_tables": 1,
  "applied": true,
  "items": [
    {
      "table_id": "11111111-1111-4111-8111-111111111111",
      "column_key": "col_9f2a1c",
      "pair_before": "[col_4b7e08->單價]",
      "pair_after": "[col_4b7e08->col_c31d5a]",
      "status": "repaired",
      "reason": null
    },
    {
      "table_id": "11111111-1111-4111-8111-111111111111",
      "column_key": "",
      "pair_before": "",
      "pair_after": null,
      "status": "unrepairable",
      "reason": "table busy (migration lock held) — rerun the sweep"
    }
  ]
}

錯誤

驗證錯誤範例列出識別欄位；部署中的驗證器也可能回傳 input 與 ctx。錯誤訊息 URL 的版本由建置決定，因此使用 pydantic-version 佔位符。

狀態發生條件錯誤本文
403三個 CloudManager root token 之中有一個缺少或錯誤。
{
  "detail": "CloudManager access denied: Invalid X-CLOUD-TOKEN"
}
422apply 的值無法被 FastAPI 解讀為布林值。
{
  "detail": [
    {
      "type": "bool_parsing",
      "loc": [
        "query",
        "apply"
      ],
      "msg": "Input should be a valid boolean, unable to interpret input",
      "input": "maybe"
    }
  ]
}
POST
路由範本/root/hotfix/custom-table-composer/checkpointer/setup

建立 composer checkpoint 資料表（operator）

用途

一次性、可重複執行地建立指令 composer 用來存放持久狀態的 LangGraph checkpoint 資料表。重跑安全。

適用時機

每個環境在開始回合或讀取／刪除 checkpoint history 前執行一次。若完全沒有設定 composer Postgres，這些 REST route 回 `503 composer_unavailable`，WebSocket 以 1013 關閉；若已設定但尚未執行此 setup，缺少的資料表會表現為這些呼叫本身的失敗——請先執行這條 route。`GET …/turn` 與 `GET …/ws/docs` 不需要 checkpointer。

實際掛載路徑
  • 完整路由/root/hotfix/custom-table-composer/checkpointer/setup

範圍

範圍是否提供驗證與權限
完整路由可使用CloudManager root keys (X-ADMIN-TOKEN + X-SUPER-TOKEN + X-CLOUD-TOKEN)

回應結構

ComposerCheckpointerSetupResponse
欄位型別必填說明
configuredboolean是未指定
messagestring是未指定
setup_ranboolean是未指定

範例

資料表已建立（或本來就存在）

請求
{
  "pathParams": {}
}
回應200
{
  "configured": true,
  "setup_ran": true,
  "message": "checkpoint tables ready"
}

這個環境沒有設定 composer 儲存

請求
{
  "pathParams": {}
}
回應200
{
  "configured": false,
  "setup_ran": false,
  "message": "MEMSTORE_POSTGRES_* is not configured"
}

錯誤

驗證錯誤範例列出識別欄位；部署中的驗證器也可能回傳 input 與 ctx。錯誤訊息 URL 的版本由建置決定，因此使用 pydantic-version 佔位符。

狀態發生條件錯誤本文
403Root operator 憑證被拒。
{
  "detail": "CloudManager access denied: Invalid X-CLOUD-TOKEN"
}
500Setup 因 120 秒上限以外的原因失敗，例如帳密錯誤、連線被拒，或在 composer Postgres 上權限不足。這條 route 不會攔截這類錯誤，所以回的是不帶原因的通用 500：請查看伺服器 log、修正設定後，再重跑這個 idempotent setup。
{
  "detail": "Internal Server Error"
}
504Setup 在 120 秒內未完成——後端 Postgres 無法連線、封包被丟棄或反應太慢。是否完成無法確認；連線恢復後可安全重跑這個 idempotent setup。
{
  "detail": {
    "error": "composer_setup_timeout"
  }
}
POST
路由範本/root/hotfix/custom-table-composer/threads/prune

清理閒置的 composer thread（預設只預覽）

用途

掃出閒置超過指定時間的 composer thread 並刪除其 checkpoints。預設只預覽：不加 `execute=true` 就不會刪除任何東西。

適用時機

排程維護 composer 狀態，或事故後的一次性清理。

實際掛載路徑
  • 完整路由/root/hotfix/custom-table-composer/threads/prune

範圍

範圍是否提供驗證與權限
完整路由可使用CloudManager root keys (X-ADMIN-TOKEN + X-SUPER-TOKEN + X-CLOUD-TOKEN)

參數

欄位位置型別必填說明
older_than_hoursqueryint 1..720否只處理閒置超過這麼多小時的 thread（1–720）。預設 24。
executequeryboolean否設為 true 才會真的刪除。預設 false，只回報會被刪除的內容。

回應結構

ComposerThreadPruneResponse
欄位型別必填說明
candidatesinteger是未指定
deletedinteger是未指定
executedboolean是未指定
older_than_hoursinteger是未指定
threadsstring[]否未指定
truncatedboolean是未指定

範例

預覽閒置超過 24 小時的 thread

請求
{
  "pathParams": {},
  "query": {
    "older_than_hours": "24",
    "execute": "false"
  }
}
回應200
{
  "executed": false,
  "older_than_hours": 24,
  "candidates": 2,
  "deleted": 0,
  "threads": [
    "ctcomposer:11111111-1111-4111-8111-111111111111:22222222-2222-4222-8222-222222222222:33333333-3333-4333-8333-333333333333:tab-1",
    "ctcomposer:11111111-1111-4111-8111-111111111111:22222222-2222-4222-8222-222222222222:44444444-4444-4444-8444-444444444444:ws-3a0f"
  ],
  "truncated": false
}

錯誤

驗證錯誤範例列出識別欄位；部署中的驗證器也可能回傳 input 與 ctx。錯誤訊息 URL 的版本由建置決定，因此使用 pydantic-version 佔位符。

狀態發生條件錯誤本文
403Root operator 憑證被拒。
{
  "detail": "CloudManager access denied: Invalid X-CLOUD-TOKEN"
}
503無法建構 composer checkpointer——這個環境沒有設定它的 Postgres。
{
  "detail": {
    "error": "composer_unavailable"
  }
}
Last updated on
建立、診斷與遷移工具