錯誤與驗證

回傳 Err(ActionError)，Agent 就會收到一個帶固定錯誤碼的結構化錯誤，而不是一段需要它自行解析的敘述文字。

建構函式	含意
ActionError::field(name, msg)	某個欄位無效
ActionError::validation([(f, e), …])	一次回報多個欄位——表單首選
ActionError::action_not_available()	在目前狀態下不可呼叫
ActionError::blocked_by_modal()	目前有模態視窗佔用輸入
ActionError::window_not_found()	目標視窗已不存在
ActionError::action_timeout()	操作耗時過長
ActionError::stale_state(version)	呼叫方的 expectedVersion 已過期
ActionError::custom(code, msg)	固定錯誤碼集合中的其他情況

一次回報所有問題

// Shared by the on-screen notice and the error path, so they never disagree.
fn problems(&self) -> Vec<(&'static str, &'static str)> {
    let mut out = Vec::new();
    if self.recipient.is_empty() { out.push(("recipient", "required")); }
    if self.amount <= 0          { out.push(("amount", "must be positive")); }
    out
}

// In the handler:
let problems = this.problems();
if !problems.is_empty() {
    return Err(ActionError::validation(problems));
}

小提示

讓畫面上的 notice 內容區塊與錯誤都由同一個 problems() 方法推導出來。這樣人類與 Agent 就永遠不會看到不一致的結論。

你很少需要自己建構 stale_state

Purview 會在你的處理器執行之前自行檢查 expectedVersion——參見免費獲得的協定行為。這個建構函式的存在，是為了少數情況：你自己的業務邏輯偵測到投影無法察覺的衝突。