Skip to Content
API 參考Root 維運操作

Root 維運操作

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

其中有幾個會直接寫入或刪除生產環境的資料。執行前請先讀該端點的注意事項；若該路由提供預覽模式（apply=false、dry_run=true），請先跑預覽並確認它回報的內容。

POST
路由範本/root/custom-tables/run-due-triggers

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

用途

認領到期的 schedule 觸發器、建立待執行 run，並順帶重新派送孤兒暫存變更。

適用時機

由每分鐘至少一次的內部 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
}

錯誤

狀態發生條件錯誤本文
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)"
}

錯誤

狀態發生條件錯誤本文
404資料表不存在。
{
  "detail": "Table not found"
}
409資料表尚未軟刪除，且未設定 force=true。
{
  "detail": "Table must be soft-deleted (in trash) before purge; pass force=true to override"
}
423資料表正被遷移鎖定。
{
  "detail": "Table is currently locked for operation: delete_table"
}
PUT
路由範本/root/ecommerce-tag-sync/chatrooms/{chatroom_id}/clients/{smc_id}/tags/{ecom_tag_id}

新增或更新單一電商標籤連結

用途

把一個電商標籤鏡像為聊天室標籤，並連結到指定社群客戶。

適用時機

電商後端收到單一標籤附加或名稱更新事件時使用。

實際掛載路徑
  • 完整路由/root/ecommerce-tag-sync/chatrooms/{chatroom_id}/clients/{smc_id}/tags/{ecom_tag_id}

範圍

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

參數

欄位位置型別必填說明
chatroom_idpathuuid是目標聊天室 UUID。
smc_idpathuuid是聊天室內的 SocialMediaClient UUID。
ecom_tag_idpathstring是電商系統中的 Tag.id。

請求結構

SmcTagUpsertPayload
欄位型別必填說明
namestring是未指定
scope"system" | "org"是未指定

回應結構

dict

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

範例

附加一個組織層級電商標籤

請求
{
  "pathParams": {
    "chatroom_id": "22222222-2222-4222-8222-222222222222",
    "smc_id": "33333333-3333-4333-8333-333333333333",
    "ecom_tag_id": "44444444-4444-4444-8444-444444444444"
  },
  "body": {
    "name": "VIP 客戶",
    "scope": "org"
  }
}
回應200
{
  "tag_id": "55555555-5555-4555-8555-555555555555"
}

錯誤

狀態發生條件錯誤本文
404聊天室或其社群客戶不存在。
{
  "detail": "SMC not found in chatroom"
}
DELETE
路由範本/root/ecommerce-tag-sync/chatrooms/{chatroom_id}/clients/{smc_id}/tags/{ecom_tag_id}

移除單一電商標籤連結

用途

從指定社群客戶移除一個電商鏡像標籤連結。

適用時機

電商後端收到單一標籤解除事件時使用。

實際掛載路徑
  • 完整路由/root/ecommerce-tag-sync/chatrooms/{chatroom_id}/clients/{smc_id}/tags/{ecom_tag_id}

範圍

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

參數

欄位位置型別必填說明
chatroom_idpathuuid是目標聊天室 UUID。
smc_idpathuuid是聊天室內的 SocialMediaClient UUID。
ecom_tag_idpathstring是電商系統中的 Tag.id。

回應結構

dict

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

範例

解除一個電商標籤

請求
{
  "pathParams": {
    "chatroom_id": "22222222-2222-4222-8222-222222222222",
    "smc_id": "33333333-3333-4333-8333-333333333333",
    "ecom_tag_id": "44444444-4444-4444-8444-444444444444"
  }
}
回應200
{
  "detached": true
}

錯誤

狀態發生條件錯誤本文
404指定社群客戶不存在於聊天室。
{
  "detail": "SMC not found in chatroom"
}
PUT
路由範本/root/ecommerce-tag-sync/chatrooms/{chatroom_id}/clients/{smc_id}/tags

重整社群客戶的電商標籤集合

用途

把一名社群客戶的完整電商鏡像標籤集合調整成 expected 清單。

適用時機

由電商後端每日對帳工作修復漏接或順序錯亂的事件。

實際掛載路徑
  • 完整路由/root/ecommerce-tag-sync/chatrooms/{chatroom_id}/clients/{smc_id}/tags

範圍

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

參數

欄位位置型別必填說明
chatroom_idpathuuid是目標聊天室 UUID。
smc_idpathuuid是聊天室內的 SocialMediaClient UUID。

請求結構

SmcTagSyncPayload
欄位型別必填說明
expectedExpectedTag[]否未指定

回應結構

SmcTagSyncResult
欄位型別必填說明
detachedinteger是未指定
syncedinteger是未指定

範例

以完整集合重整電商標籤

請求
{
  "pathParams": {
    "chatroom_id": "22222222-2222-4222-8222-222222222222",
    "smc_id": "33333333-3333-4333-8333-333333333333"
  },
  "body": {
    "expected": [
      {
        "ecom_tag_id": "44444444-4444-4444-8444-444444444444",
        "name": "VIP 客戶",
        "scope": "org"
      }
    ]
  }
}
回應200
{
  "synced": 1,
  "detached": 0
}

錯誤

狀態發生條件錯誤本文
404指定社群客戶不存在於聊天室。
{
  "detail": "SMC not found in chatroom"
}
GET
路由範本/root/hotfix/custom-table-lock/{table_id}

查看自訂資料表鎖

用途

供 CloudManager 以三組 root keys 檢查資料表遷移鎖；沒有鎖時回傳空物件，不代表端點失敗。

適用時機

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

實際掛載路徑
  • 完整路由/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
{}

錯誤

狀態發生條件錯誤本文
403root token 缺少或無效。
{
  "detail": "CloudManager access denied: Invalid X-ADMIN-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": {
    "table_id": "11111111-1111-4111-8111-111111111111",
    "owner": "migration-worker"
  }
}

錯誤

狀態發生條件錯誤本文
404資料表目前沒有有效鎖。
{
  "detail": "No active lock found for this table"
}
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。

回應結構

Dict[str, Any]

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

範例

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

請求
{
  "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."
  ]
}

錯誤

狀態發生條件錯誤本文
404資料表不存在。
{
  "detail": "Custom table not found"
}
GET
路由範本/root/hotfix/custom-table-index-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。

回應結構

Dict[str, Any]

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

範例

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

請求
{
  "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."
  ]
}

錯誤

狀態發生條件錯誤本文
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)

回應結構

Dict[str, Any]

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

範例

檢查全域孤兒索引欄位

請求
{
  "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."
  ]
}

錯誤

狀態發生條件錯誤本文
403root token 缺少或無效。
{
  "detail": "CloudManager access denied: Invalid X-ADMIN-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否設為 true 只預覽 pending 與 already_applied，不執行 DDL。

回應結構

Dict[str, Any]

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

範例

以 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 only after reviewing generated DDL."
  ]
}

錯誤

狀態發生條件錯誤本文
404資料表不存在。
{
  "detail": "Custom table not found"
}
400無法存取 MySQL information_schema，因此不能保證冪等套用。
{
  "detail": "information_schema probe unavailable (MySQL-only path)"
}
POST
路由範本/root/hotfix/custom-table-trigger-runs/requeue

重新派送卡住的觸發器 run

用途

把超過門檻仍為 pending 的自訂資料表觸發器 run 重新排入佇列。

適用時機

程序可能在資料提交後、佇列發布前崩潰，造成 pending 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 超過幾秒的 run，預設為 300。
limitqueryint 1..2000否本次最多重新派送幾筆，可填 1 到 2,000，預設為 500。

回應結構

Dict[str, Any]

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

範例

重新派送逾時 pending run

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

錯誤

狀態發生條件錯誤本文
403root token 缺少或無效。
{
  "detail": "CloudManager access denied: Invalid X-ADMIN-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
}

錯誤

狀態發生條件錯誤本文
403root token 缺少或無效。
{
  "detail": "CloudManager access denied: Invalid X-ADMIN-TOKEN"
}
POST
路由範本/root/hotfix/custom-table-sort-order-backfill

啟動資料列排序回填

用途

為所有自訂資料表既有資料列依 created_at 指派連續 sort_order。

適用時機

加入 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"
}

錯誤

狀態發生條件錯誤本文
403root token 缺少或無效。
{
  "detail": "CloudManager access denied: Invalid X-ADMIN-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": []
}

錯誤

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

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

用途

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

適用時機

當某個房間回報「所有變更類指令都回覆寫入保護失敗」時使用：pending 卡了好幾小時的標記就是卡死的元兇。也可以用 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:07",
      "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
    }
  ]
}

錯誤

狀態發生條件錯誤本文
403三個 CloudManager root token 之中有一個缺少或錯誤。
{
  "detail": "CloudManager access denied: Invalid X-ADMIN-TOKEN"
}
422state 不是 pending 或 expired、older_than_hours 為負數，或 limit 超出 1..500 範圍。
{
  "detail": [
    {
      "type": "literal_error",
      "loc": [
        "query",
        "state"
      ],
      "msg": "Input should be 'pending' or 'expired'",
      "input": "acknowledged"
    }
  ]
}
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"
    }
  ]
}

錯誤

狀態發生條件錯誤本文
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
}

錯誤

狀態發生條件錯誤本文
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 時間點。

適用時機

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

實際掛載路徑
  • 完整路由/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"
}

錯誤

狀態發生條件錯誤本文
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"
    }
  ]
}

錯誤

狀態發生條件錯誤本文
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": "yes"
    }
  ]
}
Last updated on
建立、診斷與遷移工具