require_approval 規則

require_approval 把符合條件的寫入從「立即落地」改成「先暫存、送 Review 模組、核准後重播」。它適合高風險資料變更，不是一般 validation error。

Payload

{
  "type": "require_approval",
  "name": "高額訂單需主管核准",
  "label": "高額訂單變更",
  "events": ["create", "update", "delete", "restore"],
  "template_id": "44444444-4444-4444-8444-444444444444",
  "when": [
    { "column": "金額", "op": "gte", "value": 100000 }
  ]
}

events 是 create、update、delete、restore 的非空子集合。template_id 必須是同公司、仍可用且 gates 有效的 Review template。每張表最多一條 require_approval。

Template 的 reviewer 在存檔當下就被驗證

存規則時會載入該 template，並執行與 Review 模組建立 template 時相同的 gate 驗證，因此「reviewer 根本無法登入」的 gate 會在這裡被擋下，而不是等到之後才發現流程卡在 in_review、票沒有人投得了。一位 reviewer 要同時滿足未刪除、未停用、已驗證、未過期才算數。

驗證失敗時 rules.set 回 400，detail 是一個把 Review 模組原訊息包起來的純字串：

review template '44444444-4444-4444-8444-444444444444' has invalid gate groups: review users not found or inactive: ['77777777-7777-4777-8777-777777777777']

冒號之後是實際觸發的那一項檢查 —— review groups not found: [...]、review groups have no active members: [...]、review users not found or inactive: [...]，或 gate {i} would assign {n} reviewers, exceeds max 500 —— id 只列出前五個。rules.preview 回完全相同的 400，所以 preview 不會接受存檔會拒絕的東西。Template 不存在、非 live 或屬於其他公司，則是另一則 400 review template '<id>' is not usable。

走 IaC rule line 的路徑時，同一段文字不是 HTTP 400：apply 會把它記成該行的 per-resource apply error 寫進 apply report，request 本身仍然成功。

Gate condition 現在也可以直接指名一個人 —— 一個 {"type": "user", "user_id": "<uuid>"} leaf，不需要 review group —— 這樣的 template 同樣是合法的 require_approval 對象。該使用者套用與群組成員相同的檢查，因此未驗證或已過期的直接 reviewer 一樣會讓存檔失敗。

409 是 staged success

第一次符合的寫入會建立 staged change，回傳：

{
  "detail": {
    "error": "approval_required",
    "process_id": "55555555-5555-4555-8555-555555555555",
    "rule_id": "rule_a1b2c3d4",
    "rule_label": "高額訂單變更",
    "staged_change_id": "66666666-6666-4666-8666-666666666666"
  }
}

前端應把它呈現成「已送審」，保存 process_id 與 staged_change_id，不要自動重送。同一目標已有待審變更時會收到 409 approval_pending。

每位 actor 在每張表最多保留 500 筆 pending staged changes；每張表跨所有 actors 最多 50 筆 pending create。任一上限超過時回傳 429：

{
  "detail": {
    "error": "staged_cap_exceeded",
    "scope": "actor",
    "limit": 500
  }
}

另一個 variant 是 {"scope":"table","limit":50}。前端必須依伺服器回傳的 scope 與 limit 呈現訊息；不要只寫死一種佇列上限，也不要假設所有 429 都是 actor cap。

有待審變更時，修改或移除 approval rule 會收到 409 approval_rule_locked。指向這張表的 trigger create/update action 也與 approval gate 互斥，避免無 acting reviewer 的自動寫入被無限暫存。

完整的 Review 管理、assignment decision 與 release/discard 流程見核准流程指南。端點資料見 rules.set、stagedChanges.list 與 stagedChanges.discard。