Insight systems 與載入開關

一個聊天室可能被授權讀取許多部門表，但聊天分析不一定要每次載入全部資料。Insight systems 讓聊天室管理者以「部門 tag 組成的系統」為單位選擇載入內容，同時保留原本 ACL 不變。

System 是部門 tag 的即時投影

Insight endpoint 只考慮兩者交集：

部門範圍中以 tag 分組的資料表。
目前已透過 chatroom grant 分享給這個聊天室的資料表。

每個 eligible 部門 tag 會成為一個 system，回應帶 tag_id、名稱、部門、enabled 與目前屬於這個 tag 且已授權的 tables。它不是複製出來的資料 bundle，也不保存 table ID 快照。


{
  "systems": [
    {
      "tag_id": "33333333-3333-4333-8333-333333333333",
      "name": "訂單系統",
      "department_id": "22222222-2222-4222-8222-222222222222",
      "enabled": true,
      "tables": [
        {
          "table_id": "44444444-4444-4444-8444-444444444444",
          "name": "訂單"
        }
      ]
    }
  ],
  "untagged": []
}

管理者的 opt-in 開關

聊天室管理者從這個 absolute endpoint 讀取與替換選擇：


GET /private/chatrooms/setting/custom-table-tags/{chatroom_id}
PUT /private/chatrooms/setting/custom-table-tags/{chatroom_id}

PUT body 是完整 replace-set，不是增量 patch：


{
  "tag_ids": ["33333333-3333-4333-8333-333333333333"]
}

送空陣列代表關閉所有「有 tag」的 systems。重複 ID 會被去重；不是這個聊天室 eligible system 的 tag ID 會被拒絕。成功後請以回傳或再 GET 的結果更新 UI，不要在本地只翻轉一個 boolean。

只有載入行為改變

Flip row 存在代表載入，缺少代表不載入。它不會建立、修改或撤銷 chatroom grant，也不會改 can_read、can_insert、can_edit、row filter 或可見欄位。

Untagged 永遠載入

已分享給聊天室、但沒有任何 eligible 部門 tag 的表會出現在 untagged。這些表沒有 system switch，因此永遠載入。要讓管理者能切換它，必須先在部門範圍把表加入一個 tag；不能用送一個不存在的 tag ID 來隱藏。

聊天室自己擁有的表與 client-specific 載入也不受這組部門 tag flip 縮限。這個功能專門控制「已授權的部門系統」是否進入聊天分析的載入集合。

Bundle drift 會跟著 live 狀態走

伺服器只保存選中的 tag_id。每次讀設定或建立 insight 載入集合時，都重新查看 live grants 與 live tag assignments。因此：

已啟用 tag 新增一張已授權表後，新表會自動加入載入 bundle。
表從已啟用 tag 移出後，會自動離開該 bundle；若它變成 untagged，反而改走「永遠載入」。
聊天室 grant 被撤銷後，表會立即失去 eligibility，即使 tag flip row 還存在也不會載入。
尚未啟用 tag 之後新增表，仍維持不載入，直到管理者選取該 tag。

這種 drift 是預期行為。管理 UI 應顯示 endpoint 當下回傳的 tables，並在 tag/grant 管理完成後重新抓取；不要把第一次看到的 bundle 固定在前端。

安全心智模型

把兩層分開看最清楚：


ACL / grant：這個聊天室與使用者「可以」存取哪些資料
Insight flip：在已可存取集合中，聊天分析「要載入」哪些 tagged systems

即使 system 已啟用，實際載入仍再次套用呼叫者的 row/column ACL。即使 system 關閉，擁有 grant 的使用者仍可直接用 API 存取允許的資料；關閉不是安全撤權功能。

完整請求與錯誤見 Insight 參考與 Tags 參考。實作「授權 → tag → flip」流程請看Grants + Insight 指南與建立系統精靈。