範圍、掛載與跨範圍存取

自訂資料表的「範圍」同時決定三件事：表由誰擁有、URL 掛在哪裡，以及請求先經過哪一層身分驗證。先判斷範圍，再組 URL；不要只拿到 table_id 就猜一條通用路徑。

三種擁有範圍

範圍	一般掛載前綴	適合的資料
聊天室	`/private/module/custom_tables/chatroom/{chatroom_id}`	只屬於一個協作室的工作資料
部門	`/private/module/custom_tables/department/{department_id}`	由部門維護、可分享給多個聊天室的系統資料
公司	`/private/module/custom_tables/company`	全公司的共用資料；路徑本來就沒有 `company_id`

例如，讀取一張聊天室表是：


GET /private/module/custom_tables/chatroom/11111111-1111-4111-8111-111111111111/tables/22222222-2222-4222-8222-222222222222

同一個 table_id 若屬於部門，必須改走該部門的掛載：


GET /private/module/custom_tables/department/33333333-3333-4333-8333-333333333333/tables/22222222-2222-4222-8222-222222222222

重點

分享只增加存取權，不會搬動或複製資料表。部門表分享給聊天室後，資料列 API 仍走 department/{department_id}，不是改走 chatroom/{chatroom_id}。

掛載規則與兩種例外

大多數端點共用相同的尾段，例如 /tables/{table_id}/records，只替換前面的範圍掛載。後端實際上把聊天室、部門、公司三套路由分別掛到 /chatroom、/department、/company，再由共用處理函式執行資料操作。要看哪個 family 掛在哪個 scope——包含 commands、附件、public-read tokens、publish sessions，以及那一條共用 ETL chunk 路徑——請從範圍與掛載路徑開始。

有兩組刻意採用「無範圍 ID」路徑：

附件 multipart 端點是 /{scopeName}/tables/{table_id}/blobs/...；聊天室與部門路徑都不帶 chatroom_id 或 department_id。詳見附件 Blob。
背景遷移狀態是 /{scopeName}/migrations/{migration_id}/status；它也不帶範圍 ID 或 table_id。詳見遷移與診斷。

這兩種路徑仍要選對 chatroom、department 或 company 掛載。伺服器會從表或全域唯一的 migration ID 找回擁有範圍，並重新驗證呼叫者，並不是繞過範圍。

驗證不是三個範圍都一樣

路徑尾段相同，不代表所需權限相同。常見的驗證層次如下：

操作層次	聊天室	部門	公司
列表／建立表	`ChatRoomJoinedRequired` 或 `ChatRoomAccessRequired`	`DepartmentAccessRequired`	`CompanyAccessRequired`
讀資料列	`CustomTableReadRequired`	`CustomTableReadRequired`	`CustomTableReadRequired`
新增資料列	`CustomTableInsertRequired`	`CustomTableInsertRequired`	`CustomTableInsertRequired`
編輯／刪除資料列	`CustomTableEditRequired`	`CustomTableEditRequired`	`CustomTableEditRequired`
任一寫入能力（附件共用 router）	`CustomTableWriteRequired`	`CustomTableWriteRequired`	`CustomTableWriteRequired`

驗證會先確認使用者能進入該擁有範圍，再依表管理者、使用者、部門、聊天室、預設 grant 的順序解析出有效的 can_read、can_insert、can_edit、列過濾與隱藏欄位——這是一道停在第一個命中來源的階梯，不是聯集；只有聊天室那一步會跨多列摺疊。精確順序見 effective permissions。相同 endpoint 在三個範圍也可能有不同管理門檻；例如新增欄位、執行 diagnosis、解析連結就是三組已知會分歧的操作。整合時應以各張參考卡片的 scope/auth matrix 為準，不要從 URL 推論角色。

部門介面不接受房間參數

部門表可以同時授權給多個聊天室。過去有一組 *Scoped dependency 變體，會讀取 ?acting_chatroom_id 這個 query parameter 來決定請求代表哪個房間；這五個變體已於 2026-07-29 全部刪除，該參數也從全部 57 個 custom-table 操作上移除。上表中的閘門名稱是這幾個層級現在僅存的版本；*Scoped 變體已完全不存在。

伺服器改為從呼叫者本身解析 channel floor：表管理者豁免；其他人拿到的是「所屬、存活、且對該表持有 internal grant 的每個聊天室」的 scope_values 聯集。被兩個房間授權的成員，一次請求就讀到兩個房間的範圍——這也是為什麼資料表清單與詳情頁的 record_count 就是這個聯集計數，以及為什麼多房間成員在詳情頁會拿到 200，而不再是過去的 400。

Warning

仍然送 ?acting_chatroom_id=<id> 不會報錯，也不是你察覺得到的 no-op：FastAPI 會丟棄未知的 query parameter，所以請求照樣 200，而你指名的房間根本不被採用。仍在釘選房間的用戶端，其實靜默地拿到了聯集。請把參數從呼叫端移除；不會有任何訊息告訴你它失效了。

沒有任何合格房間的呼叫者，不會被要求去指定一個。讀取回 200 零列或 uniform 404，只有寫入會被 403 {"error": "scp_scope_undeclared"} 拒絕。完整 floor 行為見 SCP；agent session 的不對稱見 union 契約。

清單上的 `record_count` 現在與詳情計數用同一套底線

資料表清單上的 record_count——GET .../chatroom/{chatroom_id}/tables 以及走同一個 helper 的部門與公司版本——過去是該表未經過濾的存活列數。授權為 own 或 filtered 的成員因此會看到一個涵蓋自己打不開的資料列的數字；這是一種雖小但真實的揭露：它等於告訴對方 policy 後面藏了幾列。自 backend PR #1172 起，清單改為套用與詳情計數完全相同的條件，並逐表解析：

呼叫者在該表上的身分	`record_count`
表管理者，或 `can_read: "all"` 且沒有 SCP 收窄	完整存活列數——不變，而且該頁上所有這類表仍然由單一批次查詢一次算完
`can_read: "own"`	自己建立的列；沒有建立者的列仍然看不到
`can_read: "filtered"`	編譯後的 row policy；無法執行的 policy 會讓整棵樹 fail closed
受 SCP 規則管轄、但沒有任何被授權房間	`0`，與被遮蔽的詳情讀取一致

由此得到兩件事。清單上的計數是逐呼叫者的數字：同一個房間、兩個人看到不同的值是合理的，用戶端絕不可以把某位使用者的清單快取給另一位使用者。另外，SCP 會自己逐表重新判定管理者身分，而不是從權限階梯上讀取，所以 SCP 判定豁免的呼叫者，即使階梯會收窄，也仍然拿到完整計數。

跨範圍 ACL 路由

跨範圍分享有兩個方向，端點永遠掛在「表的擁有範圍」：

目的	擁有表	路由族群
讓一個部門存取聊天室表	聊天室	`/chatroom/{chatroom_id}/tables/{table_id}/department-permissions/{department_id}`
讓一個聊天室／audience 存取部門表	部門	`/department/{department_id}/tables/{table_id}/chatroom-permissions/{chatroom_id}`

第一組 departmentPermissions.* 只存在聊天室範圍；第二組 chatroomPermissions.* 只存在部門範圍。聊天室成員可用 GET .../chatroom/{chatroom_id}/tables/shared 發現已授權給該聊天室的部門表，之後仍用回傳表的部門掛載讀寫。

Grant 可以縮限列權限與可見欄位，但不會被 Insight system 開關取代。Insight 開關只決定哪些已授權的部門表載入聊天分析上下文；ACL 仍是每次 API 與資料載入的安全邊界。

組路徑前的檢查順序

從表回應的 chatroom_id、department_id、company_id 判斷擁有範圍。
選用該範圍的掛載與 endpoint 參考卡片。
受治理的部門表：呼叫者的房間未宣告 scope 時，預期看到空頁而不是錯誤——而且永遠不要送 acting_chatroom_id。
跨範圍分享後保留原擁有範圍，只更新 grant 與本地的可用表清單。

可在 API Playground 選擇 scope，確認實際展開的 URL 與 auth 說明；完整 grant 端點見權限參考。