Skip to Content
API 參考歷程與版本

歷程與版本

稽核資料表變更、檢視資料列快照與差異，並安全還原歷史標量資料。

GET
路由範本/private/module/custom_tables/{scope}/tables/{table_id}/history

列出資料表歷程

用途

由新至舊回傳涵蓋資料列與結構變更的資料表稽核記錄。

適用時機

適合製作稽核時間軸，或在深入某筆資料列版本前先篩選變更。

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

範圍

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

參數

欄位位置型別必填說明
table_idpathuuid是要列出稽核記錄的資料表 UUID。
change_typequerystring否選填的變更類型，包含資料列與結構層級事件名稱。
record_idqueryuuid否選填的資料列 UUID；會排除其他資料列與整張表的結構記錄。
limitqueryint 1..1000否最多回傳幾筆歷程，可填 1 到 1,000。
offsetqueryint >= 0否略過前幾筆符合條件的歷程。

回應結構

TableHistoryListResponse
欄位型別必填說明
historyRecordHistoryEntry[]是History entries, newest first
table_idstring是Table UUID
totalinteger是Total number of history entries

範例

列出某筆資料列的更新記錄

請求
{
  "pathParams": {
    "chatroom_id": "11111111-1111-4111-8111-111111111111",
    "table_id": "22222222-2222-4222-8222-222222222222"
  },
  "query": {
    "change_type": "update",
    "record_id": "33333333-3333-4333-8333-333333333333",
    "limit": "50",
    "offset": "0"
  }
}
回應200
{
  "history": [
    {
      "id": "44444444-4444-4444-8444-444444444444",
      "record_id": "33333333-3333-4333-8333-333333333333",
      "table_id": "22222222-2222-4222-8222-222222222222",
      "version": 2,
      "data": {
        "col_77777777_7777_4777_8777_777777777777": "ORD-1001",
        "col_88888888_8888_4888_8888_888888888888": "已確認"
      },
      "diff": {
        "col_88888888_8888_4888_8888_888888888888": {
          "old": "草稿",
          "new": "已確認"
        }
      },
      "change_type": "update",
      "changed_by": {
        "id": "55555555-5555-4555-8555-555555555555",
        "created_at": "2026-01-15T01:00:00",
        "expired_at": "2027-01-15T01:00:00",
        "photo_url": null,
        "enabled": true,
        "is_verified": true,
        "username": "catalog.operator",
        "email": "operator@example.invalid",
        "nickname": "陳小安",
        "department_id": "66666666-6666-4666-8666-666666666666",
        "department_name": "營運部"
      },
      "changed_by_client": null,
      "changed_by_ai": false,
      "reverted_to": null,
      "created_at": "2026-07-19T04:05:00"
    }
  ],
  "total": 1,
  "table_id": "22222222-2222-4222-8222-222222222222"
}

錯誤

狀態發生條件錯誤本文
404資料表不存在，或不屬於指定範圍。
{
  "detail": "Table not found"
}
GET
路由範本/private/module/custom_tables/{scope}/tables/{table_id}/records/{record_id}/history

列出資料列歷程

用途

由新至舊回傳某筆資料列所有保留的版本快照。

適用時機

適合製作資料列時間軸，或挑選要檢視、比對或還原的版本。

實際掛載路徑
  • 聊天室/private/module/custom_tables/chatroom/{chatroom_id}/tables/{table_id}/records/{record_id}/history
  • 部門/private/module/custom_tables/department/{department_id}/tables/{table_id}/records/{record_id}/history
  • 公司/private/module/custom_tables/company/tables/{table_id}/records/{record_id}/history

範圍

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

參數

欄位位置型別必填說明
table_idpathuuid是上層資料表 UUID。
record_idpathuuid是要列出版本的資料列 UUID。
change_typequerystring否選填的資料列變更類型，例如 create、update、delete 或 revert。
limitqueryint 1..1000否最多回傳幾筆歷程，可填 1 到 1,000。
offsetqueryint >= 0否略過前幾個符合條件的版本。

回應結構

RecordHistoryListResponse
欄位型別必填說明
historyRecordHistoryEntry[]是History entries, newest first
record_idstring是Record UUID
totalinteger是Total number of history entries

範例

列出某筆資料列的版本

請求
{
  "pathParams": {
    "chatroom_id": "11111111-1111-4111-8111-111111111111",
    "table_id": "22222222-2222-4222-8222-222222222222",
    "record_id": "33333333-3333-4333-8333-333333333333"
  },
  "query": {
    "limit": "50",
    "offset": "0"
  }
}
回應200
{
  "history": [
    {
      "id": "44444444-4444-4444-8444-444444444444",
      "record_id": "33333333-3333-4333-8333-333333333333",
      "table_id": "22222222-2222-4222-8222-222222222222",
      "version": 2,
      "data": {
        "col_77777777_7777_4777_8777_777777777777": "ORD-1001",
        "col_88888888_8888_4888_8888_888888888888": "已確認"
      },
      "diff": {
        "col_88888888_8888_4888_8888_888888888888": {
          "old": "草稿",
          "new": "已確認"
        }
      },
      "change_type": "update",
      "changed_by": {
        "id": "55555555-5555-4555-8555-555555555555",
        "created_at": "2026-01-15T01:00:00",
        "expired_at": "2027-01-15T01:00:00",
        "photo_url": null,
        "enabled": true,
        "is_verified": true,
        "username": "catalog.operator",
        "email": "operator@example.invalid",
        "nickname": "陳小安",
        "department_id": "66666666-6666-4666-8666-666666666666",
        "department_name": "營運部"
      },
      "changed_by_client": null,
      "changed_by_ai": false,
      "reverted_to": null,
      "created_at": "2026-07-19T04:05:00"
    }
  ],
  "total": 2,
  "record_id": "33333333-3333-4333-8333-333333333333"
}

錯誤

狀態發生條件錯誤本文
404上層資料表不存在，或不屬於指定範圍。
{
  "detail": "Table not found"
}
404資料列不存在，或被資料列層級存取權隱藏。
{
  "detail": "Record not found"
}
GET
路由範本/private/module/custom_tables/{scope}/tables/{table_id}/records/{record_id}/history/{version}

取得單一資料列版本

用途

回傳某個資料列版本的不可變快照與變更資訊。

適用時機

適合在比對或還原前，先檢視確切的歷史狀態。

實際掛載路徑
  • 聊天室/private/module/custom_tables/chatroom/{chatroom_id}/tables/{table_id}/records/{record_id}/history/{version}
  • 部門/private/module/custom_tables/department/{department_id}/tables/{table_id}/records/{record_id}/history/{version}
  • 公司/private/module/custom_tables/company/tables/{table_id}/records/{record_id}/history/{version}

範圍

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

參數

欄位位置型別必填說明
table_idpathuuid是上層資料表 UUID。
record_idpathuuid是擁有該版本的資料列 UUID。
versionpathint >= 1是要取得的正整數資料列版本號。

回應結構

RecordHistoryEntry
欄位型別必填說明
change_typestring是Type of change: create | update | delete | revert | schema_add_column | schema_remove_column | schema_type_change
changed_byBaseUserInfo | null否User who made the change (null for external client changes)
changed_by_aiboolean是Whether the change was made by an AI agent
changed_by_clientSocialMediaClientBasicInfo | null否Social media client who made the change (null for internal user changes)
created_atstring (date-time)是Timestamp of the change
dataobject是Full record data snapshot at this version
diffobject | null否Field-level diff: {column_id: {old: ..., new: ...}}
idstring是History entry UUID
record_idstring | null否Record UUID (null for table-wide schema changes)
reverted_tointeger | null否Target version (only present for revert operations)
table_idstring是Parent table UUID
versioninteger是Record version at the time of this change

範例

取得資料列的第 2 版

請求
{
  "pathParams": {
    "chatroom_id": "11111111-1111-4111-8111-111111111111",
    "table_id": "22222222-2222-4222-8222-222222222222",
    "record_id": "33333333-3333-4333-8333-333333333333",
    "version": "2"
  }
}
回應200
{
  "id": "44444444-4444-4444-8444-444444444444",
  "record_id": "33333333-3333-4333-8333-333333333333",
  "table_id": "22222222-2222-4222-8222-222222222222",
  "version": 2,
  "data": {
    "col_77777777_7777_4777_8777_777777777777": "ORD-1001",
    "col_88888888_8888_4888_8888_888888888888": "已確認"
  },
  "diff": {
    "col_88888888_8888_4888_8888_888888888888": {
      "old": "草稿",
      "new": "已確認"
    }
  },
  "change_type": "update",
  "changed_by": {
    "id": "55555555-5555-4555-8555-555555555555",
    "created_at": "2026-01-15T01:00:00",
    "expired_at": "2027-01-15T01:00:00",
    "photo_url": null,
    "enabled": true,
    "is_verified": true,
    "username": "catalog.operator",
    "email": "operator@example.invalid",
    "nickname": "陳小安",
    "department_id": "66666666-6666-4666-8666-666666666666",
    "department_name": "營運部"
  },
  "changed_by_client": null,
  "changed_by_ai": false,
  "reverted_to": null,
  "created_at": "2026-07-19T04:05:00"
}

錯誤

狀態發生條件錯誤本文
404資料列不存在，或被資料列層級存取權隱藏。
{
  "detail": "Record not found"
}
404這筆資料列不存在指定版本。
{
  "detail": "Version 2 not found"
}
GET
路由範本/private/module/custom_tables/{scope}/tables/{table_id}/records/{record_id}/history/{version}/diff

比對資料列版本

用途

回傳路徑版本與指定比較版本之間的欄位級差異。

適用時機

適合在使用者決定要還原的版本前，說明究竟改了什麼。

實際掛載路徑
  • 聊天室/private/module/custom_tables/chatroom/{chatroom_id}/tables/{table_id}/records/{record_id}/history/{version}/diff
  • 部門/private/module/custom_tables/department/{department_id}/tables/{table_id}/records/{record_id}/history/{version}/diff
  • 公司/private/module/custom_tables/company/tables/{table_id}/records/{record_id}/history/{version}/diff

範圍

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

參數

欄位位置型別必填說明
table_idpathuuid是上層資料表 UUID。
record_idpathuuid是要比對版本的資料列 UUID。
versionpathint >= 1是URL 中的來源版本號。
compare_toqueryint >= 1是要比較的目標版本號；聊天室路由必填。

回應結構

RecordDiffResponse
欄位型別必填說明
diffobject是Field-level changes: {column_id: {old: ..., new: ...}}
from_versioninteger是Source version number
to_versioninteger是Target version number

範例

將第 2 版與第 1 版比較

請求
{
  "pathParams": {
    "chatroom_id": "11111111-1111-4111-8111-111111111111",
    "table_id": "22222222-2222-4222-8222-222222222222",
    "record_id": "33333333-3333-4333-8333-333333333333",
    "version": "2"
  },
  "query": {
    "compare_to": "1"
  }
}
回應200
{
  "from_version": 2,
  "to_version": 1,
  "diff": {
    "col_88888888_8888_4888_8888_888888888888": {
      "old": "已確認",
      "new": "草稿"
    }
  }
}

錯誤

狀態發生條件錯誤本文
404資料列不存在，或被資料列層級存取權隱藏。
{
  "detail": "Record not found"
}
404指定的一個或兩個版本不存在。
{
  "detail": "One or both versions not found"
}
POST
路由範本/private/module/custom_tables/{scope}/tables/{table_id}/records/{record_id}/history/{version}/restore

還原資料列版本

用途

將歷史的標量快照複製到現行資料列，並把結果記錄為新的 revert 版本。

適用時機

檢視目標快照與差異，並確認目前連結與結構相容後使用。

實際掛載路徑
  • 聊天室/private/module/custom_tables/chatroom/{chatroom_id}/tables/{table_id}/records/{record_id}/history/{version}/restore
  • 部門/private/module/custom_tables/department/{department_id}/tables/{table_id}/records/{record_id}/history/{version}/restore
  • 公司/private/module/custom_tables/company/tables/{table_id}/records/{record_id}/history/{version}/restore

範圍

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

參數

欄位位置型別必填說明
table_idpathuuid是上層資料表 UUID。
record_idpathuuid是要還原的資料列 UUID。
versionpathint >= 1是要還原標量資料的歷史版本號。

回應結構

RestoreResponse
欄位型別必填說明
links_not_restoredboolean否True when the table has link columns: version restore reverts only scalar cells — the record's CURRENT link relations were NOT reverted to the target version. Surface this so the user knows relations differ.
messagestring是Status message
new_versioninteger是The new version number after restore
recordCustomTableRecordResponse是The restored record (now at a new version)
restored_from_versioninteger是The version that was restored from

範例

還原第 1 版的標量資料

請求
{
  "pathParams": {
    "chatroom_id": "11111111-1111-4111-8111-111111111111",
    "table_id": "22222222-2222-4222-8222-222222222222",
    "record_id": "33333333-3333-4333-8333-333333333333",
    "version": "1"
  }
}
回應200
{
  "record": {
    "id": "33333333-3333-4333-8333-333333333333",
    "data": {
      "訂單編號": "ORD-1001",
      "狀態": "草稿"
    },
    "version": 3,
    "is_deleted": false,
    "created_by_ai": false,
    "created_by": {
      "id": "55555555-5555-4555-8555-555555555555",
      "created_at": "2026-01-15T01:00:00",
      "expired_at": "2027-01-15T01:00:00",
      "photo_url": null,
      "enabled": true,
      "is_verified": true,
      "username": "catalog.operator",
      "email": "operator@example.invalid",
      "nickname": "陳小安",
      "department_id": "66666666-6666-4666-8666-666666666666",
      "department_name": "營運部"
    },
    "created_by_client": null,
    "sort_order": null,
    "table_id": "22222222-2222-4222-8222-222222222222",
    "created_at": "2026-07-19T04:00:00",
    "updated_at": "2026-07-19T04:10:00",
    "expanded": null,
    "incoming_links": null,
    "can_edit": true,
    "pending_approval": null
  },
  "restored_from_version": 1,
  "new_version": 3,
  "message": "Record restored to version 1",
  "links_not_restored": false
}

錯誤

狀態發生條件錯誤本文
404指定範圍中找不到資料列、資料表或目標版本。
{
  "detail": "Record not found"
}
409歷史快照與目前結構衝突，無法安全還原。
{
  "detail": {
    "detail": "Cannot restore to version 1: schema has changed incompatibly",
    "conflicts": [
      {
        "column_id": "col_88888888_8888_4888_8888_888888888888",
        "reason": "column_removed"
      }
    ]
  }
}
409資料表的 require_approval 規則把此次還原暫存為 staged change，等待覆核核准（GA 預設開啟）。
{
  "detail": {
    "error": "approval_required",
    "process_id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb",
    "rule_id": "cccccccc-cccc-4ccc-8ccc-cccccccccccc",
    "rule_label": "require_approval",
    "staged_change_id": "dddddddd-dddd-4ddd-8ddd-dddddddddddd"
  }
}
423資料表目前被結構遷移鎖定。
{
  "detail": "Table is currently locked for operation: add_column"
}
429此表或此操作者的待覆核暫存變更已達上限（staged_cap_exceeded）。
{
  "detail": {
    "error": "staged_cap_exceeded",
    "scope": "actor",
    "limit": 500
  }
}
Last updated on
資料列垃圾桶權限與存取控制