Skip to Content
核心概念規則規則總覽

資料表規則

規則是在資料進入自訂資料表之前執行的伺服器端契約。前端驗證可以改善操作體驗，但不能取代規則：callback、批次作業、觸發器與核准後重播都可能走不同寫入入口，最後仍由伺服器決定資料是否可落地。

先建立正確的心智模型

一張表的 rules 是一份完整、排序過的清單。PUT 會整份取代，而不是增量新增；送出前應先 GET、保留既有規則與穩定的 rule_<hex> ID、在本地修改，再預覽及回寫。每張表最多 10 條規則。

GET 現有規則 → 本地修改完整清單 → POST preview → PUT 完整清單 → GET 驗證

Warning 送出只有一條規則的 PUT，會移除清單中其他規則。伺服器只會替沒有 id 的新規則產生 ID；編輯時請原樣保留既有 ID。

詳細 wire contract 請查閱 rules.get、rules.preview 與 rules.set。

13 種規則如何選

類型回答的問題頁面
compare同一列的兩個欄位是否維持大小或相等關係？compare
unique一至三個欄位組成的鍵是否不重複？unique
no_overlap同一範圍內的時間或數值區間是否不重疊？no_overlap
count_limit一個 live-row bucket 是否維持在設定上限內？count_limit
exists另一張表是否至少有一列符合關聯條件？exists
not_exists另一張表是否沒有任何列符合關聯條件？not_exists
transition狀態是否只沿允許的路徑改變？transition
check單一欄位值是否符合比較、集合或 regex 條件？check
require條件成立時，欄位是否一定有值？require
require_approval寫入是否應先暫存並送 Review 模組？require_approval
channel部門表的列是否落在呼叫者解析出的 channel scope（授權他這張表的所有房間之聯集）內？channel
invariant不論寫入者與入口，列的最終形狀是否都合法？invariant
immutable_when列一旦進入這個狀態，指定欄位是否就凍結？immutable_when

一般 predicate 規則可用 when 縮小套用範圍。unique、transition、channel、invariant 與 immutable_when 不接受有效的 when；需要條件式 SCP 時，請把 if 節點寫在 policy 內，鎖定條件則寫在 immutable_when 自己的 prior_when，它以列的 pre-image 而非 post-image 判斷。

預覽再發布

Preview 一律會驗證候選清單；有上限的 row-impact pass 則只處理 channel／invariant，回報各 room 的 SCP 差異與 invariant 違規。它不會把 no_overlap、count_limit 等一般 predicate rules 套到既有列上；這些 bucket 必須另以針對性的 record query 稽核。Preview 不寫入規則，也不修改資料。

curl -X POST \
  "$BASE_URL/private/module/custom_tables/chatroom/11111111-1111-4111-8111-111111111111/tables/22222222-2222-4222-8222-222222222222/rules/preview" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "rules": [
      {
        "type": "compare",
        "name": "實付不得超過報價",
        "left": "實付金額",
        "op": "lte",
        "right": "報價金額"
      }
    ]
  }'
{
  "table_id": "22222222-2222-4222-8222-222222222222",
  "sampled_rows": 120,
  "total_rows": 120,
  "sample_cap": 200,
  "rooms": [],
  "invariant_violations": 0,
  "warnings": []
}

把 sampled_rows 與 total_rows 一起顯示；若前者較小，UI 應標示「抽樣結果」，不要呈現成全表保證。SCP 預覽還會提供房間別結果與 invariant 違規數。

發布完整清單

curl -X PUT \
  "$BASE_URL/private/module/custom_tables/chatroom/11111111-1111-4111-8111-111111111111/tables/22222222-2222-4222-8222-222222222222/rules" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @rules.json

成功後，以回應中的正規化清單更新前端狀態；欄位名稱可能已轉成伺服器的可重送表示。常見失敗包括：規則 shape 無效的 400、仍有待審變更時修改 approval rule 的 409 approval_rule_locked，以及資料表正在 schema 作業時的 423。

部門表含 enforcing channel 規則時，非管理員不再需要指名房間：floor 由「授權他這張表的所有房間」聯集解析。沒有東西可以重試，也沒有 candidates 可挑——見 union 契約。

與寫入錯誤整合

一般 predicate 違規會拒絕寫入；前端應顯示伺服器訊息，同時保留使用者尚未送出的表單。require_approval 的 409 approval_required 則不是失敗：它表示變更已被暫存，應切換到「待審」狀態。完整流程見核准流程指南。

若要互動式試走完整流程，可使用流程精靈。

Last updated on
用 REST 補完compare