Skip to Content
API 參考資料表標籤

資料表標籤

以範圍限定的標籤整理相關資料表、安全管理指派關係，並可用兩步驟 purge 流程一次下線整個 tag 系統。

POST
路由範本/private/module/custom_tables/{scope}/table-tags

建立資料表標籤

用途

在單一範圍內建立帶有名稱與顏色的資料表群組。

適用時機

要把一組相關資料表歸入同一系統或流程前使用。

實際掛載路徑
  • 聊天室/private/module/custom_tables/chatroom/{chatroom_id}/table-tags
  • 部門/private/module/custom_tables/department/{department_id}/table-tags
  • 公司/private/module/custom_tables/company/table-tags

範圍

範圍是否提供驗證與權限
聊天室可使用ChatRoomAccessRequired
部門可使用DepartmentAccessRequired
公司可使用CompanyAccessRequired

請求結構

CustomTableTagPayload
欄位型別必填說明
colorstring否Optional display color, '#rgb', '#rgba', '#rrggbb' or '#rrggbbaa', or empty.
descriptionstring否Optional human description.
namestring是Tag name (unique per scope).

回應結構

CustomTableTagResponse
欄位型別必填說明
colorstring是Display color ('' when unset)
created_atstring (date-time)是Creation timestamp
descriptionstring是Human description ('' when unset)
idstring是Tag UUID
namestring是Tag name
table_countinteger是Number of tables assigned to this tag
updated_atstring (date-time)是Last modification timestamp

範例

建立營運標籤

請求
{
  "pathParams": {
    "chatroom_id": "11111111-1111-4111-8111-111111111111"
  },
  "body": {
    "name": "營運",
    "description": "日常營運相關資料表",
    "color": "#2563eb"
  }
}
回應201
{
  "id": "55555555-5555-4555-8555-555555555555",
  "name": "營運",
  "description": "日常營運相關資料表",
  "color": "#2563eb",
  "table_count": 0,
  "created_at": "2026-07-19T01:30:00",
  "updated_at": "2026-07-19T01:35:00"
}

錯誤

狀態發生條件錯誤本文
409同一範圍已有標籤使用指定名稱。
{
  "detail": "Tag name '營運' already exists in this scope"
}
GET
路由範本/private/module/custom_tables/{scope}/table-tags

列出資料表標籤

用途

依名稱排序回傳此範圍的標籤，以及目前指派的資料表數量。

適用時機

適合呈現標籤導覽，或在篩選資料表前先解析標籤 UUID。

實際掛載路徑
  • 聊天室/private/module/custom_tables/chatroom/{chatroom_id}/table-tags
  • 部門/private/module/custom_tables/department/{department_id}/table-tags
  • 公司/private/module/custom_tables/company/table-tags

範圍

範圍是否提供驗證與權限
聊天室可使用ChatRoomAccessRequired
部門可使用DepartmentAccessRequired
公司可使用CompanyAccessRequired

回應結構

CustomTableTagListResponse
欄位型別必填說明
tagsCustomTableTagResponse[]是Tags in this scope
totalinteger是Number of tags

範例

列出標籤與指派數量

請求
{
  "pathParams": {
    "chatroom_id": "11111111-1111-4111-8111-111111111111"
  }
}
回應200
{
  "tags": [
    {
      "id": "55555555-5555-4555-8555-555555555555",
      "name": "營運",
      "description": "日常營運相關資料表",
      "color": "#2563eb",
      "table_count": 0,
      "created_at": "2026-07-19T01:30:00",
      "updated_at": "2026-07-19T01:35:00"
    }
  ],
  "total": 1
}
PATCH
路由範本/private/module/custom_tables/{scope}/table-tags/{tag_id}

更新資料表標籤

用途

局部修改同一 scope 內標籤的名稱、說明或顏色；未提供任何欄位時請求會失敗。

適用時機

重新命名系統群組或調整顯示樣式時使用。

實際掛載路徑
  • 聊天室/private/module/custom_tables/chatroom/{chatroom_id}/table-tags/{tag_id}
  • 部門/private/module/custom_tables/department/{department_id}/table-tags/{tag_id}
  • 公司/private/module/custom_tables/company/table-tags/{tag_id}

範圍

範圍是否提供驗證與權限
聊天室可使用ChatRoomAccessRequired
部門可使用DepartmentAccessRequired
公司可使用CompanyAccessRequired

參數

欄位位置型別必填說明
tag_idpathuuid是指定範圍內的標籤 UUID。

請求結構

CustomTableTagUpdatePayload
欄位型別必填說明
colorstring | null否New display color, '#rgb', '#rgba', '#rrggbb' or '#rrggbbaa', or empty to clear.
descriptionstring | null否New description.
namestring | null否New tag name (unique per scope).

回應結構

CustomTableTagResponse
欄位型別必填說明
colorstring是Display color ('' when unset)
created_atstring (date-time)是Creation timestamp
descriptionstring是Human description ('' when unset)
idstring是Tag UUID
namestring是Tag name
table_countinteger是Number of tables assigned to this tag
updated_atstring (date-time)是Last modification timestamp

範例

重新命名並換色

請求
{
  "pathParams": {
    "chatroom_id": "11111111-1111-4111-8111-111111111111",
    "tag_id": "55555555-5555-4555-8555-555555555555"
  },
  "body": {
    "name": "核心營運",
    "color": "#1d4ed8"
  }
}
回應200
{
  "id": "55555555-5555-4555-8555-555555555555",
  "name": "核心營運",
  "description": "日常營運相關資料表",
  "color": "#1d4ed8",
  "table_count": 0,
  "created_at": "2026-07-19T01:30:00",
  "updated_at": "2026-07-19T01:35:00"
}

錯誤

狀態發生條件錯誤本文
400未提供任何要更新的欄位。
{
  "detail": "Provide at least one of 'name', 'description' or 'color'"
}
404指定範圍內找不到此標籤。
{
  "detail": "Tag not found in this scope"
}
DELETE
路由範本/private/module/custom_tables/{scope}/table-tags/{tag_id}

刪除資料表標籤

用途

刪除標籤與指派關係，不會刪除任何資料表。

適用時機

群組不再使用，但所屬資料表仍需保留時使用。

實際掛載路徑
  • 聊天室/private/module/custom_tables/chatroom/{chatroom_id}/table-tags/{tag_id}
  • 部門/private/module/custom_tables/department/{department_id}/table-tags/{tag_id}
  • 公司/private/module/custom_tables/company/table-tags/{tag_id}

範圍

範圍是否提供驗證與權限
聊天室可使用ChatRoomAccessRequired
部門可使用DepartmentAccessRequired
公司可使用CompanyAccessRequired

參數

欄位位置型別必填說明
tag_idpathuuid是要刪除的標籤 UUID。

回應結構

SuccessResponse
欄位型別必填說明
messagestring否未指定

範例

刪除標籤

請求
{
  "pathParams": {
    "chatroom_id": "11111111-1111-4111-8111-111111111111",
    "tag_id": "55555555-5555-4555-8555-555555555555"
  }
}
回應200
{
  "message": "Tag deleted successfully"
}

錯誤

狀態發生條件錯誤本文
404指定範圍內找不到此標籤。
{
  "detail": "Tag not found in this scope"
}
PUT
路由範本/private/module/custom_tables/{scope}/table-tags/{tag_id}/tables

整批取代標籤所屬資料表

用途

讓標籤指派集合精確等於送入的資料表 UUID 清單。

適用時機

儲存標籤成員編輯器的完整狀態時使用。

實際掛載路徑
  • 聊天室/private/module/custom_tables/chatroom/{chatroom_id}/table-tags/{tag_id}/tables
  • 部門/private/module/custom_tables/department/{department_id}/table-tags/{tag_id}/tables
  • 公司/private/module/custom_tables/company/table-tags/{tag_id}/tables

範圍

範圍是否提供驗證與權限
聊天室可使用ChatRoomAccessRequired
部門可使用DepartmentAccessRequired
公司可使用CompanyAccessRequired

參數

欄位位置型別必填說明
tag_idpathuuid是要取代指派集合的標籤 UUID。

請求結構

TagTablesReplacePayload
欄位型別必填說明
table_idsstring[]是Custom-table UUIDs; every id must exist in the tag's scope.

回應結構

TagTablesResponse
欄位型別必填說明
table_idsstring[]是Assigned custom-table UUIDs
totalinteger是Number of assigned tables

範例

整批取代標籤指派

請求
{
  "pathParams": {
    "chatroom_id": "11111111-1111-4111-8111-111111111111",
    "tag_id": "55555555-5555-4555-8555-555555555555"
  },
  "body": {
    "table_ids": [
      "22222222-2222-4222-8222-222222222222"
    ]
  }
}
回應200
{
  "table_ids": [
    "22222222-2222-4222-8222-222222222222"
  ],
  "total": 1
}

錯誤

狀態發生條件錯誤本文
404某個資料表 UUID 不存在，或屬於其他範圍。
{
  "detail": "One or more tables were not found in this scope"
}
POST
路由範本/private/module/custom_tables/{scope}/table-tags/{tag_id}/tables/{table_id}

將單一資料表加入標籤

用途

把一張同範圍資料表加入標籤，並回傳完整指派集合。

適用時機

互動式標籤編輯器中，單筆加入資料表時使用。

實際掛載路徑
  • 聊天室/private/module/custom_tables/chatroom/{chatroom_id}/table-tags/{tag_id}/tables/{table_id}
  • 部門/private/module/custom_tables/department/{department_id}/table-tags/{tag_id}/tables/{table_id}
  • 公司/private/module/custom_tables/company/table-tags/{tag_id}/tables/{table_id}

範圍

範圍是否提供驗證與權限
聊天室可使用ChatRoomAccessRequired
部門可使用DepartmentAccessRequired
公司可使用CompanyAccessRequired

參數

欄位位置型別必填說明
tag_idpathuuid是目標標籤 UUID。
table_idpathuuid是同一範圍內現行資料表的 UUID。

回應結構

TagTablesResponse
欄位型別必填說明
table_idsstring[]是Assigned custom-table UUIDs
totalinteger是Number of assigned tables

範例

把訂單資料表加入標籤

請求
{
  "pathParams": {
    "chatroom_id": "11111111-1111-4111-8111-111111111111",
    "tag_id": "55555555-5555-4555-8555-555555555555",
    "table_id": "22222222-2222-4222-8222-222222222222"
  }
}
回應201
{
  "table_ids": [
    "22222222-2222-4222-8222-222222222222"
  ],
  "total": 1
}

錯誤

狀態發生條件錯誤本文
404此範圍內找不到指定標籤或資料表。
{
  "detail": "Table not found in this scope"
}
DELETE
路由範本/private/module/custom_tables/{scope}/table-tags/{tag_id}/tables/{table_id}

從標籤移除單一資料表

用途

移除一筆資料表指派，並回傳標籤剩餘的資料表 UUID。

適用時機

互動式標籤編輯器中，單筆移除資料表時使用。

實際掛載路徑
  • 聊天室/private/module/custom_tables/chatroom/{chatroom_id}/table-tags/{tag_id}/tables/{table_id}
  • 部門/private/module/custom_tables/department/{department_id}/table-tags/{tag_id}/tables/{table_id}
  • 公司/private/module/custom_tables/company/table-tags/{tag_id}/tables/{table_id}

範圍

範圍是否提供驗證與權限
聊天室可使用ChatRoomAccessRequired
部門可使用DepartmentAccessRequired
公司可使用CompanyAccessRequired

參數

欄位位置型別必填說明
tag_idpathuuid是目標標籤 UUID。
table_idpathuuid是要從標籤移除的資料表 UUID。

回應結構

TagTablesResponse
欄位型別必填說明
table_idsstring[]是Assigned custom-table UUIDs
totalinteger是Number of assigned tables

範例

從標籤移除訂單資料表

請求
{
  "pathParams": {
    "chatroom_id": "11111111-1111-4111-8111-111111111111",
    "tag_id": "55555555-5555-4555-8555-555555555555",
    "table_id": "22222222-2222-4222-8222-222222222222"
  }
}
回應200
{
  "table_ids": [],
  "total": 0
}

錯誤

狀態發生條件錯誤本文
404指定範圍內找不到此標籤。
{
  "detail": "Tag not found in this scope"
}
POST
路由範本/private/module/custom_tables/{scope}/table-tags/{tag_id}/purge/preview

預覽整個 tag 系統的 purge

用途

計算一次銷毀 tag 所有成員表、綁定該 tag 的全部 commands、其 IaC state rows 以及 tag 本身的爆炸半徑——沒有 blocker 時同樣發出 15 分鐘一次性 ticket。

適用時機

當一整套已佈建的系統（通常由 IaC apply 產生、以 tag 綁成一組的表與 commands）要整體下線、而不是一張一張刪時使用。

實際掛載路徑
  • 聊天室/private/module/custom_tables/chatroom/{chatroom_id}/table-tags/{tag_id}/purge/preview
  • 部門/private/module/custom_tables/department/{department_id}/table-tags/{tag_id}/purge/preview
  • 公司/private/module/custom_tables/company/table-tags/{tag_id}/purge/preview

範圍

範圍是否提供驗證與權限
聊天室可使用ChatRoomAccessRequired
部門可使用DepartmentAccessRequired
公司可使用CompanyAccessRequired

參數

欄位位置型別必填說明
tag_idpathuuid是其成員表與 commands 構成待 purge 系統的那個 tag。

回應結構

PurgePreviewResponse
欄位型別必填說明
blockersPurgeBlocker[]是Conditions preventing a ticket (empty = ticket issued)
commands_affectedPurgeCommandInfo[]是OTHER live commands whose dependency set references a purged table — they become zombies (still deletable individually), NOT deleted by this purge
commands_to_deletePurgeCommandInfo[]是Commands the purge deletes (tag lane: every command bound to the tag; names release immediately)
cross_table_impactPurgeCrossTableImpact[]是Live tables outside the purge set whose schemas/rules the cascade mutates
expires_atstring (date-time) | null否Ticket expiry (UTC)
iac_state_rowsinteger是IaC state rows removed with the purged tables
tablesPurgeImpactTable[]是Tables that will be permanently destroyed (records + history + row)
ticketstring | null否One-shot purge ticket (null when blockers exist); bound to the previewing user
viewsinteger是Saved views destroyed with the purged tables

範例

預覽一個雙表系統的 purge

請求
{
  "pathParams": {
    "chatroom_id": "11111111-1111-4111-8111-111111111111",
    "tag_id": "55555555-5555-4555-8555-555555555555"
  }
}
回應200
{
  "tables": [
    {
      "id": "22222222-2222-4222-8222-222222222222",
      "name": "訂單",
      "record_count": 128,
      "is_deleted": false
    },
    {
      "id": "66666666-6666-4666-8666-666666666666",
      "name": "出貨單",
      "record_count": 54,
      "is_deleted": false
    }
  ],
  "cross_table_impact": [],
  "commands_to_delete": [
    {
      "id": "eeeeeeee-eeee-4eee-8eee-eeeeeeeeeeee",
      "name": "ship-order"
    }
  ],
  "commands_affected": [],
  "views": 3,
  "iac_state_rows": 6,
  "blockers": [],
  "ticket": "f1f1f1f1-f1f1-4f1f-8f1f-f1f1f1f1f1f1",
  "expires_at": "2026-07-28T03:15:00Z"
}

錯誤

狀態發生條件錯誤本文
404此 scope 內沒有這個 id 的 tag。
{
  "detail": "Tag not found in this scope"
}
403整系統 purge 會銷毀表與 commands，因此要求 scope-manager 權威——tag 刪除那道弱閘（任一成員即可）不夠格。
{
  "detail": "Purging a tagged system requires scope-manager authority"
}
POST
路由範本/private/module/custom_tables/{scope}/table-tags/{tag_id}/purge

核准並執行整系統 purge（消耗 ticket）

用途

永久銷毀所有成員表、軟刪綁定該 tag 的每個 command（名字立即釋放）、清除這些 commands 的 IaC state rows，並刪除 tag 本身。

適用時機

下線一個 tag 系統的第二步：preview 後 15 分鐘內、由同一位使用者執行。

實際掛載路徑
  • 聊天室/private/module/custom_tables/chatroom/{chatroom_id}/table-tags/{tag_id}/purge
  • 部門/private/module/custom_tables/department/{department_id}/table-tags/{tag_id}/purge
  • 公司/private/module/custom_tables/company/table-tags/{tag_id}/purge

範圍

範圍是否提供驗證與權限
聊天室可使用ChatRoomAccessRequired
部門可使用DepartmentAccessRequired
公司可使用CompanyAccessRequired

參數

欄位位置型別必填說明
tag_idpathuuid是要 purge 的 tag——必須與 ticket 的標的一致。
ticketqueryuuid是tag purge preview 回應中的一次性 ticket。任何走到 ticket 驗證那一步的嘗試都會燒掉它，成敗皆然——唯一例外是 purge_blocked 的拒絕，它發生在消耗 ticket 之前。

回應結構

TagPurgeResponse
欄位型別必填說明
deleted_commandsinteger是Commands soft-deleted with the system (names released)
messagestring是Human-readable outcome
purged_tablesstring[]是Ids of the tables permanently destroyed, in execution order
tag_idstring是The deleted tag's id

範例

執行已預覽的系統 purge

請求
{
  "pathParams": {
    "chatroom_id": "11111111-1111-4111-8111-111111111111",
    "tag_id": "55555555-5555-4555-8555-555555555555"
  },
  "query": {
    "ticket": "f1f1f1f1-f1f1-4f1f-8f1f-f1f1f1f1f1f1"
  }
}
回應200
{
  "tag_id": "55555555-5555-4555-8555-555555555555",
  "purged_tables": [
    "22222222-2222-4222-8222-222222222222",
    "66666666-6666-4666-8666-666666666666"
  ],
  "deleted_commands": 1,
  "message": "System permanently purged (tables, commands, and tag removed)"
}

錯誤

狀態發生條件錯誤本文
404ticket 不存在或已過期（效期 15 分鐘）。請重新 preview。
{
  "detail": {
    "error": "purge_ticket_not_found",
    "message": "purge ticket not found or expired — run the purge preview again"
  }
}
403ticket 屬於另一位使用者。誰 preview，誰執行。
{
  "detail": {
    "error": "purge_ticket_actor_mismatch",
    "message": "purge ticket belongs to a different user — the previewer must execute"
  }
}
409preview 之後系統漂移了——表被還原或改名、command 增減、或 tag 掛載變動。重新 preview 並重新核准。
{
  "detail": {
    "error": "purge_preview_stale",
    "message": "the system changed after the preview (table/command/tag set drifted) — run the purge preview again and re-approve what you see"
  }
}
409ticket 是為另一個標的簽發的——別的 tag，或單表 lane。ticket 已燒掉；請對這個 tag 重新 preview。
{
  "detail": {
    "error": "purge_ticket_mismatch",
    "message": "purge ticket was issued for a different target"
  }
}
409blocker 在 execute 時會重驗一次（縱深防禦）。preview 之後成員表又掛上別的 tag，就算 ticket 有效也會被擋下。
{
  "detail": {
    "error": "purge_blocked",
    "blockers": [
      {
        "code": "table_in_other_tags",
        "table_id": "22222222-2222-4222-8222-222222222222",
        "message": "table is also assigned to tag '財務' — purging this system would destroy another system's member; untag it or purge the table individually"
      }
    ]
  }
}
423一或多張成員表持有 migration 鎖；preflight 會點名它們。等 migration 結束後重新 preview——這次嘗試花掉的 ticket 不會回來。若鎖是在執行中途才撞上，回應會是掛著這個狀態碼的 purge_partial_failure 內容，而不是 500。
{
  "detail": "Table is currently locked for operation: purge preflight (1 member table(s) hold a migration lock: 66666666-6666-4666-8666-666666666666)"
}
500每張成員表的 cascade 獨立 commit，所以系統中途失敗時，前面的成員已經永久消失。回應會精確列出哪些表已 purge、哪張失敗——千萬不要丟掉這份結果。復原路徑是對縮小後的系統重新 preview。
{
  "detail": {
    "error": "purge_partial_failure",
    "purged_tables": [
      "22222222-2222-4222-8222-222222222222"
    ],
    "failed_table_id": "66666666-6666-4666-8666-666666666666",
    "message": "member-table purge failed after earlier members were destroyed",
    "recovery": "re-run the purge preview and re-approve the remaining system"
  }
}
Last updated on
檢視資料列