資料表規則

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

先建立正確的心智模型

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

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

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

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

18 種規則如何選

一般 predicate 規則可用 when 縮小套用範圍。unique、unique_tuple、same_dimension_reference、date_interval_exclusion、period_fence、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、exists、check 等一般 predicate rules 套到既有列上；這些 bucket 必須另以針對性的 record query 稽核。它也從不回填 unique／unique_tuple 約束，所以既有資料的碰撞只會在 PUT 的 409 出現。唯一的例外是 same_dimension_reference：preview 會執行與 PUT 相同的既有列准入檢查（在交易範圍的 guard 下進行，之後回滾），並回相同的 409 same_dimension_reference_violation。Preview 不寫入規則、不修改資料，也會忽略 expected_rules_digest。

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

成功後，以回應中的正規化清單與新的 rules_digest 更新前端狀態；欄位名稱可能已轉成伺服器的可重送表示。常見失敗：

防止覆寫他人的修改

GET 與 PUT 都會回傳 rules_digest，也就是對已儲存的正規化清單計算的 64 位 hex SHA-256。下次 PUT 時把它放進 expected_rules_digest：若期間有其他編輯者改了規則，寫入會以 409 {"detail": {"error": "rules_changed", "message": "Table rules changed; reload before saving."}} 拒絕，規則與 history 都不會寫入。省略此欄位（或送 null）則維持原本的無條件取代。這個摘要在候選清單驗證通過、取得資料表鎖之後才比對，早於 approval 鎖檢查與任何 unique 回填；把沒有變動的 GET 回傳重新存檔，摘要不會改變。

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

與寫入錯誤整合

佇列中的 bulk insert/update worker 會在母表鎖內重新讀取目前規則。工作啟動後才提交的期間、筆數與區間規則仍會生效；進入佇列不代表規則快照被凍結。有序同步 bulk 也會在同一把鎖內更新規則 context。詳見批次操作。

一般 predicate 違規會拒絕寫入；前端應顯示伺服器訊息，同時保留使用者尚未送出的表單。每種規則各有自己的狀態碼與形狀；400 的文字前面會加上 Rule '<label>' violated: ，label 依序取規則的 name、id，最後才是 type：

require_approval 的 409 approval_required 則不是失敗：它表示變更已被暫存，應切換到「待審」狀態。完整流程見核准流程指南。

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