Principal 欄位：principal、user 與 social_client

適用情境

有三種欄位型別指向的是「人」而不是資料。後端把它們歸在同一個名字 PRINCIPAL_COLUMN_TYPES（src/schemas/enums.py）之下，因為從頭到尾的契約相同：寫入是身分字串、讀取是顯示物件、只能等值比較、永遠不能排序。

現在該選的是 principal。同一欄可以放「這筆指派實際上是什麼身分」，所以一位業務在某些列以 TS 帳號行動、在另一些列以 LINE 帳號行動時，不再需要兩個欄位再用 policy 去 or；而「這筆 deal 屬於北區業務室」也終於有了表示法，成員異動完全不必動到任何一列。

user 與 social_client 沒有任何改變，也繼續支援：它們存原始 id、加工成不帶 ref／kind 的 dict，既有的列、篩選、授權與匯出全部逐位元不變。它們沒有被淘汰，但新的負責人欄位應該用 principal。

三者都把單一字串直接存在 record.data 裡。和 link 不同，這裡沒有關聯表、也沒有搬移；基數固定為一。多負責人 cell 會是另一個獨立型別，永遠不會是這個型別上的一個開關。

當你需要的是屬於自己 schema 的豐富人員 metadata 時，人員表加 link 仍然是正確模型。Principal 欄位處理的是身分：它對照真實目錄解析、寫入時受租戶把關，而且它才是 $me row policy 比對的對象。

principal 的 cell 文法

principal cell 是恰好一個帶標籤的字串，不是陣列：

<tag>:<id>      tag ∈ { user, smc, room }      id 符合 [A-Za-z0-9_-]{1,64}

標籤詞彙就是 IaC 身分 token 的前綴去掉 $ 記號。id 本體既不允許 $ 也不允許 :，而且整個字串是用 fullmatch 比對、不是 $ 錨定的 regex——所以結尾多一個換行也會被拒絕。因此四個 id 空間在構造上互斥，任一空間的值都不可能被誤認成另一個：

• principal cell（user:u1）——有標籤；
• 舊的 user／social_client cell——裸 id，沒有標籤；
• row policy token（$me、$me.department）——以 $ 開頭；
• IaC 身分 token（$user:alice）與 actor key（client:<id>）——$ 記號與 client: 這個拼法都在文法之外。社群客戶的標籤之所以是 smc: 而不是 client:，正是為了這一點。

加工後的讀取契約講的仍然是 social_client 與 chatroom，不是 smc 與 room：標籤是傳輸拼法，kind 才是詞彙。

建立 schema

以下是 columns.create 的 body。三種型別都只接受 name、type、required、description：

{
  "name": "Assignee",
  "type": "principal",
  "required": false,
  "description": "這筆紀錄屬於哪個使用者、客戶或聊天室"
}

{
  "name": "Reviewer",
  "type": "user",
  "required": false,
  "description": "內部審核者"
}

default_value 被禁止，因為在編寫 schema 的當下無法驗證預設負責人是否屬於本租戶；max_length 與 options 對不透明的身分沒有意義；附件與計算欄的設定欄位一概不接受。required 可以使用。

寫入契約

送出身分字串——principal 要送帶標籤的那個。不是顯示名稱、不是 username，也不是讀取時拿到的那個物件。

{
  "data": {
    "Title": "印表機離線",
    "Assignee": "room:c8a91f22d0",
    "Reviewer": "44444444-4444-4444-8444-444444444444"
  }
}

records.create 回應 201，而且 cell 已經是加工過的顯示物件——回應的形狀和你送出的不一樣。

對選填 principal 欄而言，省略 key、null 與 "" 都是合法空值。必填欄在建立紀錄時拒絕空值，在更新時也拒絕明確送出的空值；局部更新仍可省略該 key。

每一個非空值都會跑兩道檢查。

形狀。 principal cell 必須能解析成帶標籤的 cell，否則寫入失敗並回 400 Field '<display name>' must be a principal cell (user:<id>, smc:<id> or room:<id>)。user／social_client cell 必須是非空字串：400 Field '<display name>' must be a principal id string。

租戶歸屬與存活。 每種 kind 各批次查一次、沒有 N+1；principal 依標籤分派，舊的兩種依欄位型別分派：

如果完全無法解析有效公司（表 → 部門 → 聊天室都是空），寫入 fail-closed 並回 400 Cannot resolve company for principal ownership check。

這道閘門接在所有寫入路徑上：單筆新增、單筆更新、批次新增、批次更新、非同步批次新增 worker、簽核暫存套用路徑，以及版本還原路徑。它同時也是 replay 與 bulk 路徑（那些路徑會跳過 schema 驗證）必經的匯流點，所以無法解析的 principal cell 在那裡也會拋錯——400 Column '<name>' principal cell '<value>' must be user:<id>, smc:<id> or room:<id>——而不是掉進「最後那一個」歸屬查詢。沒有任何後門能把跨租戶或格式錯誤的身分夾帶進來。

值得寫進前端表單驗證的拒絕情境：

讀取契約：加工後的顯示物件

所有私有 REST 讀取都會把儲存的字串換成解析後的顯示物件，每頁每種 principal kind 最多批次查一次——一次加工同時服務帶標籤的 cell 與兩種舊型別，因為挑目錄的是標籤，不是欄位型別。

{
  "data": {
    "Title": "印表機離線",
    "Assignee": {
      "ref": "room:c8a91f22d0",
      "kind": "chatroom",
      "id": "c8a91f22d0",
      "name": "北區業務",
      "department_id": "d1",
      "is_deleted": false
    },
    "Reviewer": {
      "id": "44444444-4444-4444-8444-444444444444",
      "name": "Alice Chen",
      "username": "alice",
      "is_deleted": false
    }
  }
}

principal cell 會解析成該 kind 的 dict，再加上 ref 與 kind：

ref 是來回契約：原封不動把這個字串寫回去，不要從 kind 反推標籤，也不要送裸 id。user 的 name 取暱稱、沒有就退回 username；social_client 的 name 是各通道的顯示名稱（可能為空）；chatroom 的 name 就是聊天室名稱。

加工是 fail-closed 而且不具破壞性。被軟刪除的使用者或聊天室仍然會解析出來，並帶 is_deleted: true，讓歷史指派保持可讀——存活與否是寫入閘門的事，永遠不是讀取過濾條件。無法在本租戶解析的值——懸空、跨租戶、格式錯誤，或是在租戶尚無法解析時寫入的——會維持原本的原始字串（含標籤）：既不捏造、也不丟棄。

加工只會轉換 data 裡已經存在的 key，因此被欄位 ACL 隱藏的欄位永遠不會被解析，也不會被重新加回去。它以顯示名稱為鍵，透過 settings.column_mapping 反查，所以即使寫入時用的是內部 col_<hex> 鍵，加工後的 cell 仍會出現在顯示名稱底下——請參閱欄位身分。

有三個讀取介面不會加工，而且就只有這三個：

• 公開讀取路徑只提供原始字串。
• 透過 lookup 帶出的 principal 欄位回傳原始字串——加工器只走訪本表自己的 principal 型別欄位，而 lookup cell 宣告的型別是 lookup。同一個人在擁有該欄位的表上顯示為姓名，透過 lookup 卻是 user:<id>（舊型別則是一串 UUID）。
• REST records/aggregate 的分組鍵是原始字串。要畫「每位負責人的紀錄數」圖表的前端，得自己把它換成姓名。

外部 agent 通道

在 agent 工具組的外部客戶通道上，加工後的聊天室 cell 會收斂成 {ref, kind, id}：聊天室名稱與 department_id 是內部組織結構，永遠不會送到客戶端。該通道上所有 principal dict 都會拿掉 username 與 is_deleted，資料 cell 也一樣。ref 在兩條通道都保留——那是呼叫端要寫回去的字串。

CSV 與 XLSX 匯出

POST .../records/export 會串流一份已渲染的檔案，principal cell 會渲染成給人看的樣子，而不是 Python dict repr：

room: 判斷跑在 platform 判斷之前，所以聊天室指派絕不會被讀成某個人的名字。名稱為空時標籤退回 id，所以一格可能是 line:<uuid> 或 room:<uuid>。匯出與列表走同一條可見性管線——被隱藏的欄位不會變成檔案欄位，ACL 之外的列也不會進到檔案。

查詢矩陣：只能等值，永遠不能排序

Principal 身分是不透明的，因此字典序比較會給出「錯得很篤定」的答案而不是錯誤——而且 principal cell 會先依標籤排序（room:z 排在 user:a 前面），一個看起來有意義、其實沒有的順序。各處使用的運算子集合完全相同：

eq、neq、in、is_null、is_not_null——僅此而已。

伺服器端沒有辦法依 principal 欄位排序。請改用 group_by + count，或把姓名反正規化到一個 string 欄位再排序。principal 欄位的 group_by 以整個帶標籤字串為鍵，所以 user:x 永遠不會和 smc:x 混在一起。

Principal 欄位可以用的地方

三種型別都算已儲存純量，所以日常需求都是一級支援：

Agent 工具組與 REST 對齊，聚合集合稍寬。principal 的寫入只收一個帶標籤的 cell（Column '<name>' must be a single principal cell — user:<id>, smc:<id> or room:<id> (resolve the id first, not a name)）；舊型別的寫入收一個原始 id（Column '<name>' must be a single <user|social-media client> id string — pass the id (resolve it first), not a name）。principal 的 filter 運算元若未帶標籤，拒絕訊息會明確點名 ref——… must be a tagged principal cell (user:<id>, smc:<id> or room:<id>) — resolve the principal first and pass its ref. Reads return {ref,kind,id,name,…}: send value.get('ref') back verbatim, never the bare id or the whole dict.。在舊型別欄位上，把讀取得到的加工物件塞進 filter 會被明確拒絕並提示改傳 value['id']（不會默默拆解）。聚合允許 count、count_distinct、value_counts、mode、collect，但永遠不允許 min／max（principal id cells have no order. Supported: count, count_distinct, value_counts, mode, collect.）與 sum／avg。value_counts 上限 50 筆。

Row policy 與 $me

Principal 欄位加上 $me token 就是最標準的「只看到自己的資料」政策：

{
  "read_filter": {
    "and": [
      { "column": "col_a1a1a1a1_a1a1_4a1a_8a1a_a1a1a1a1a1a1", "op": "eq", "value": "$me" }
    ]
  }
}

$me 可用於 principal、user、social_client、string、text 欄位；$me.department 可用於 principal、string、text。在 user 或 social_client 欄位上，$me 解析成單一 id。在 principal 欄位上，它改為解析成一個帶標籤 cell 的集合——行為者自己的身分，加上他所屬的聊天室——所以 room: 指派的紀錄會送達每一位成員，而那一列從頭到尾沒有點名任何人。該解析、各通道的收斂方式與 fail-closed 上限記載於 Row policy 動態代號，本頁不重複。

在寫入 grant 時，principal 欄位條件會被收斂到同樣那五個運算子。每一則 row policy 錯誤都會冠上該葉節點的樹狀路徑：頂層葉節點是 row policy，巢狀葉節點則是 row policy <path>——例如 row policy and[0]、row policy not.or[1]，在 link_target 內則是 row policy target.and[0]。以下的 <label> 就代表這個前綴。

排序或 contains 運算子會被拒絕：422 <label> op '<op>' cannot be applied to column '<key>' — principal columns support only eq/neq/in/is_null/is_not_null in row policies。運算元不合法則是 <label> column '<key>' principal filter requires a non-empty string id operand 或 <label> column '<key>' principal 'in' filter requires a non-empty list of non-empty string ids。在 principal 欄位上，非 policy token 的常值運算元還必須能解析成帶標籤的 cell：<label> column '<key>' principal filter operand must be a tagged principal cell (user:<id>, smc:<id> or room:<id>)。把 $me 用在不適用的欄位型別上是 <label> token $me may only target user/social_client/principal/string/text columns — column '<key>' is type <type>，$me.department 則是 <label> token $me.department may only target string/text/principal columns — column '<key>' is type <type>。在這層收斂出現之前，負責人欄位上的排序條件會用字典序決定列的可見性——一個「已過濾」的授權卻悄悄放寬了範圍。

$me、$today、$now 只是 row policy 的 token：在 rollup filter、規則、SCP 純量葉節點或臨時的 REST aggregate 上，它們會被直接拒絕，訊息是 filter value '$me' on column '<display>' — identity/date tokens ($me, $today…) are only valid in ACL row policies. use a literal value here; tokens resolve only inside grant read_filter/edit_filter row policies。Trigger 的 source.filter 有自己的對應訊息：source.filter identity/date tokens ($me, $today…) are not valid (triggers evaluate with no acting user; use a literal value)。

把 $me 當成寫入值——只限 agent 通道

儲存用的 cell 文法沒有變動：它依然既不接受 $ 也不接受第二個 :，REST 寫入仍然必須帶已解析的 id 或 ref。自 backend PR #1190 起，agent 工具組接受一個例外，而那是在驗證之前完成的一次翻譯，不是文法放寬。

custom_tables_insert_record、custom_tables_update_record，以及 custom_tables_bulk_record_actions 的 insert 與 update 兩個分支，都允許人員 cell 寫成 $me 這個 token——去除前後空白、不分大小寫、僅此一種寫法。工具箱會在 _validate_insert_data 與 CRUD 歸屬閘門之前把它改寫成當事人，因此下游的一切（包含本頁的寫入契約）看到的都是普通的 cell，資料庫也永遠不會存進任何長得像 token 的東西。

兩個舊型別各自綁定單一種身分、只存一個裸 id，所以「我」只在對應的通道上存在；無法為該欄位解析時，token 會原樣留著，接著被上面那條一般形狀檢查擋下來，而不是無聲地寫成另一個人。伺服器沒有同義詞表——「我」「me」「myself」是模型的責任，由它的協定來教——而租戶歸屬與存活檢查仍然套用在解析後的 id 上。見 agent 工具箱。

IaC 的可攜身分

原始資料庫 id 會把 IaC 文件綁死在單一安裝環境。因此 principal cell 接受可攜的身分 token，在 plan 與 apply 時解析，以公司為錨點並且 fail-closed：

• user 欄位用 $user:<username>——username 在公司內唯一，存下來是裸的 user id。
• social_client 欄位用 $smc:<platform>:<platform_user_id>，存下來是裸的 social client id。
• principal 欄位用 $user:、$smc:，或 $room:<聊天室名稱>／$room:<部門名稱>/<聊天室名稱>。三者都會存成該欄位文法要求的帶標籤 cell——user:<id>、smc:<id> 或 room:<id>——因為標籤就是 token 前綴去掉 $。

Trigger 的 when 條件值也帶同樣的 token：user／social_client 欄位上的 $user:／$smc: 解析成裸 id，principal 欄位上的三種前綴則解析成帶標籤 cell（"value": "room:<id>"，運算子維持不變）。identity 型別的 invoke_command 輸入常值只接受 $user: 與 $smc:——沒有 identity:principal 這種輸入型別，所以那裡一律解析成裸 id。Grant principal 依 principal.type 使用四種前綴：user 用 $user:、department 用 $dept:<部門名稱>、client 用 $smc:、chatroom 用 $room:<聊天室名稱> 或 $room:<部門名稱>/<聊天室名稱>。insight_selection.chatroom 也接受 $room:。kind 對前綴的對照表是封閉的：表上沒有的 kind 會得到明確的 unknown principal kind '<kind>' for token '<tok>'，而不是靜默退回 $smc:。

{"kind":"column","table":"tickets","ref":"assignee","spec":{"name":"Assignee","type":"principal"}}
{"kind":"column","table":"tickets","ref":"reviewer","spec":{"name":"Reviewer","type":"user"}}
{"kind":"record","table":"tickets","data":{"ticket_no":"T-100","assignee":"$room:Support Desk/Tier 1","reviewer":"$user:alice"},"on_drift":"update"}
{"kind":"grant","table":"tickets","principal":{"type":"user","id":"$user:alice"},"spec":{"can_read":"filtered","read_filter":{"and":[{"column":"assignee","op":"eq","value":"$me"}]},"can_insert":true,"can_edit":"none"}}

解析在 pass 0 執行，早於 record 分類，整份文件每種 kind 批次查一次，每個 token 得到的結果恰好是「一個 id」或「一則錯誤」二選一。永遠不會靜默跳過。principal 型別的 cell 裡任何以 $ 開頭的值都會被當成 token，所以格式錯誤的那一個會浮現自己的逐行錯誤，而不是以假的原始 id 流到寫入閘門。不以 $ 開頭的字串會原樣通過：user／social_client 欄位上的舊型原始 id，以及 principal 欄位上的原始帶標籤 cell，兩者都合法，但也都只是由寫入閘門（而非解析器）把關的同環境捷徑——可攜的寫法是 token。因為分類比對的是解析後的正規值，重新匯出已套用的文件會 plan 出 0 差異。

失敗模式全都是明確的：

$smc: token 也可能合理地無法解析：SocialMediaClient 的唯一性是以聊天室為單位，所以同一組 (platform, platform_user_id) 出現在兩個聊天室就是模稜兩可，會 fail-closed 而不是挑第一筆。

IacGrantPrincipal.id 為此放寬了限制。現在是 1–160 字元、符合 ^([a-z0-9][a-z0-9_.-]{0,35}|\$(user|dept|smc|room):[^\r\n]{1,150})$——原始 id 仍然必須不含冒號與空白，好讓推導出的 grant:<type>:<id> ref 保持合法；而 token 的內容是最多 150 字元的自由文字，因此含空白與冒號的部門與聊天室名稱都寫得出來。Token 會在推導那個 ref 之前先正規化成解析後的原始 id；無法解析的 token 會得到佔位 ref <prefix>unresolved-<8 位十六進位>，讓 plan 回報逐行錯誤而不是 500。

匯出會把原始 id 反向對應回 token，每種 kind 批次查一次並限定租戶，涵蓋 user／social_client 的 record cell、principal cell、trigger when 值、identity command 輸入、link 自然鍵清單，以及四種 grant principal。principal cell 會先被解析，再用它自己的標籤查對應的表——user: 查使用者、smc: 查 social client、room: 查聊天室。聊天室在公司內存活房間中裸名唯一時輸出 $room:<聊天室名稱>；否則在該 (部門, 聊天室) 組合唯一、且部門名稱本身不含 / 時，輸出 $room:<部門名稱>/<聊天室名稱>。對應不出來的一律原樣輸出：principal 欄位輸出原始帶標籤 cell（user:<id>、smc:<id>、room:<id>），舊型別欄位與 grant 則輸出原始 id。這涵蓋兩種形式都模稜兩可的聊天室、名稱本身含 / 的聊天室、被軟刪除或懸空的聊天室、(platform, platform_user_id) 在公司內對到多筆的 smc、模稜兩可或已軟刪除的部門，以及跨租戶或 username 為空的 id。被軟刪除的使用者仍然會被 token 化，這樣重新套用時會在解析器大聲失敗，而不是把一個死掉的原始 id 帶下去。同一個未變動系統的兩次匯出是位元相同的；帶有原始帶標籤退路的匯出，在原本的 scope 重新 plan 依然是 0 差異。

匯出與公開曝光

公開讀取 token 把 principal 欄位當成整個功能的 PII 邊界，而且這道閘門是從「家族」推導出來的——所以 principal 上線的第一天就繼承了預設隱藏。除非管理員明確指名——同時出現在檢視的 columns 與／或 token 的 visible_columns，並通過兩者的交集——否則三種型別一律被強制隱藏。即使公開，公開路徑也只提供原始字串；它從不執行顯示加工器，所以匿名讀者永遠拿不到姓名。沒有任何方式可以公開一個人或一個聊天室的名稱。

鑄造公開 token 時也會拒絕引用 $me 或 $me.department 的 read_filter：read_filter may not reference $me / $me.department on a public token (no principal exists); $today is allowed（422；IaC public_read line 回報的同一錯誤字尾是 …; $today and $now are allowed）。讀取時公開路徑會把 $me 解析成永不命中——在 principal 欄位上也一樣，因為兩個 principal 集合的 getter 都刻意不傳。若過濾或排序指向 token 與檢視未公開的 principal 欄位，會回傳統一的防探測 404，與未知、已撤銷或已過期的 token 完全相同。

型別轉換

還有兩個相關邊界。必填欄位完全無法轉成 principal 型別：型別變更驗證器要求非空欄位必須提供 default_value，而 principal 欄位禁止 default_value，這是一個死路（Type change from '<old>' to 'principal' requires a default value for required (non-nullable) columns. Please provide a default_value.）。若該欄位被計算欄引用，轉型會是結構化的 409 {"detail": "Column is referenced by computed columns", "conflicts": [...]}，而不是 400。

還原歷史版本時，principal cell 會被以字串做型別檢查，而還原路徑會對這次還原會變更的 principal cell 重跑歸屬閘門——所以簽核的時間差無法把已刪除、已關閉聊天室或跨租戶的身分洗回一列裡。還原一個負責人已離職的版本會明確失敗。

常見陷阱

• 寫入形狀不等於讀取形狀。 寫進去是字串，讀回來是物件。把剛 GET 到的物件直接 PUT 回去會被拒絕。在 principal 欄位上要送 value.ref，在舊型別欄位上要送 value.id。這是最常見的整合錯誤。
• 讀取的 cell 是 string | object，兩種都要處理。
• principal cell 一定要有標籤。裸 id 不是簡寫，而是 400。
• 有沒有 ref 就是分辨 principal cell 與舊 cell 的方法。舊 cell 從來沒有 ref／kind。
• principal filter 上未帶標籤的運算元在所有地方都是 400，這是刻意的：否則 eq 會靜默回零列、neq 會回每一列。
• name_eq／name_contains 在 user／social_client 上可用，在 principal 上被拒絕——先解析，再用 ref 過濾。
• 任何地方都不能依 principal 欄位排序。
• 轉成或轉離 principal 型別會清空整欄資料。
• 負責人欄位上的 $me 政策會讓所有人都看不到未指派的列。
• lookup 帶出的 principal 欄位，以及 REST aggregate 的分組鍵，都是原始字串——不會加工。
• IaC 身分 token 只在 IaC 有效。在 principal 欄位上它現在會解析——$room:Support Desk/Tier 1 會存成 room:<id>——但把 $user:alice 送進 REST 紀錄 API 仍然會被拒絕。
• 指派 room:<rid> 不需要成員身分——但該聊天室必須存活且屬於本租戶。
• 含必填 principal 欄位的表完全無法使用測試資料產生器：產生器對 principal 欄位輸出 null，不會捏造身分。≤2000 列的路徑會在 schema 驗證失敗；背景路徑則在插入任何資料前拋出 Cannot generate test data: required principal column '<internal key>' cannot be auto-populated。做展示時請把該欄位設為選填。
• lookup 的設定錯誤訊息仍然列出加入 principal 之前的純量清單。不要把那段錯誤文字當成允許型別的參考——principal 欄位是合法的 lookup 目標。

試試看

在 API Playground 用 columns.create 加一個 principal 欄位，用 room:<某個存活聊天室的 id> 寫一筆紀錄，比較回應的 cell 與你送出的內容——接著在更新時把 ref 原封不動送回去。然後在該欄位上鑄造一個 "value": "$me" 的過濾式授權，再以該聊天室成員的身分讀取整張表——請見 Grant 類型與 row policy。