view line

view 將 saved view 納入同一套 ref/state 管理。它描述可重建的 filter、sort、column set，以及可選的 list／matrix／timeline layout；建立者是 server-owned audit identity，不屬於可攜的 IaC spec。

JSONL Line

{"kind":"view","table":"orders","ref":"open_orders","spec":{"name":"Open orders","is_shared":true,"config":{"filters":{"status":"open"},"sort_by":"order_no","sort_order":"asc","columns":["order_no","status"]}}}

欄位契約

頂層對應 IacViewLine：必填 kind: "view"、table、ref；可選 state（預設 present）與 renamed_from；present 必須提供 object spec，只有純 rename 可省略；absent 禁止 spec。

IaC model 將 spec 保留為 dict，apply 會以 CustomTableSavedViewPayload 驗證：

config 可選欄位是 filters（預設 {}）、stored_filters（最多 20）、computed_filters（最多 3）、any_of（1–10 個 OR 群組，每組 1–10 條 predicate；空清單會被拒絕）、q（最多 200 字元）、sort_by、sort_order（asc/desc，預設 asc）、sort（多欄排序，最多 3 個 key，與 sort_by 互斥）、columns（最多 200，預設 []）、kind（list/matrix/timeline，預設 list），以及對應 kind 的 matrix 或 timeline 物件。不要提供 created_by、view ID、timestamps 或 response-only is_owner。

Layout kinds

Matrix line 的巢狀設定可全程使用 authored column refs：

{"kind":"view","table":"orders","ref":"weekly_matrix","spec":{"name":"Weekly order matrix","is_shared":true,"config":{"kind":"matrix","matrix":{"row_column":"owner","bucket_column":"due_at","column_bucket":"week","cell_column":"order_no"},"columns":["order_no","owner","due_at"]}}}

只有選到對應 kind 時，該子設定才是必填；其他 kind 一律禁止它。例如：

{"kind":"view","table":"orders","ref":"delivery_timeline","spec":{"name":"Delivery timeline","config":{"kind":"timeline","timeline":{"lane_column":"owner","start_column":"starts_at","end_column":"ends_at","label_column":"order_no","slot_minutes":30}}}}

Plan/apply 會 fail closed 地解析每個 layout column ref、持久化為內部鍵，並驗證與 REST 相同的 bucket／range type gates。後端保存的是 presentation config，apply 時仍執行一般 saved record query；matrix 與 timeline 完全由前端渲染。

Ref 與身分規則

Qualified identity 是 orders.open_orders，與同 table 的 column、rule、trigger、public_read refs 以及固定的 client_access identity 共用 namespace。IaC 中 filters object keys、predicate column、sort_by、columns entries，以及所有 matrix／timeline column fields 都使用 authored column refs；plan fail closed 地解析為 CRUD 所需的 internal/display representation。

View 名稱不是 identity。改 name 產生 update；改 IaC ref 應使用 renamed_from 產生 move。Export 不會把 server-owned created_by 放進 spec。

生命週期與規劃

Present line可規劃 create、adopt、move、update 或 noop；state: "absent" 規劃刪除 saved view。Apply 走 view CRUD，仍會以 caller ACL 驗證 saved filters/columns；is_shared: true 也會檢查 moderator 權限。

省略 view line 不會刪除 live view。若要撤除，保留同一 table/ref 並明確宣告 absent。

View 可以是 public_read token 的發佈對象，而這個綁定會限制它的生命週期。Token 的 view_id 外鍵是 ON DELETE CASCADE，因此在仍有 present token 指向它時把 view 宣告為 absent，會得到硬性的 validate 錯誤，而不是連帶刪除——請先撤銷 token 行。public_read 行的 view 宣告在後面是可以的；executor 會把它延到第二輪處理。

驗證錯誤

state=absent lines carry no spec (table lines are the sole adopt-then-delete exception)
state=present lines require a spec (unless a pure rename via renamed_from)
unknown table ref 'orders'
duplicate ref 'orders.open_orders' (already declared in this document)
unknown column ref 'orders.status'

最後一種 detail 可由 filters key、predicate column、sort_by、columns entry 或 matrix／timeline column field 觸發。Lifecycle 兩類目前為工作台 local-only validator contract；view payload/ACL 的完整錯誤由 apply 的 downstream view CRUD 回報。精確本機字串來源：components/iac/parse.ts。

自 2026-07-28 版起，apply 在任何 view CRUD 之前，會先對翻譯後的 spec.config key 做 fail-closed 驗證——config 在 parse 階段是自由 dict，工作台攔不到雜 key。未知 key 只讓那一行出錯：200 的 apply body 裡出現 view '{table}.{ref}': invalid configuration (N field error(s))；其他行照常執行，失敗那行不落任何東西。成功時保存的是翻譯後的原始 dict（不是 model 正規化輸出），所以套用過的 view replan 仍是零差異。讀取側是寬鬆的另一半：已經帶著雜 key 的存量 view 永遠讀得到——未知 key 在讀取時被剝除，絕不會 500。

動手試試

在 IaC 工作台建立 orders.status 與範例 view，把 sort_by 改成未知 ref，修正後執行 server plan。確認 is_shared 與 column visibility 符合預期使用者 ACL。