把業務規則寫成可執行檢查¶

你的 authoring source 可以 target Java 17、21 或 25，但載入 ToppleCat 並執行 compiler 的 Gradle daemon 必須使用 JDK 21 或 25。這是 source 相容性選擇，不代表支援 Java 17 runtime：只使用 JDK 17 的環境不能執行以 Java 21 為 target 的 ToppleCat artifact。目前 contract source 使用 daemon 的 system compiler；沒有獨立且經測試的 compiler seam 前，不要假設可以使用不同的 consumer toolchain。

在請 AI 實作功能前，先用看得見的結果回答一個問題：發生什麼情況時，你會相信這條規則真的有作用？

先寫規則，再談程式標記¶

假設規則是：「訂單成立後，系統要回傳含有正確總額的收據。」接著寫一筆具體例子，讓開發者、產品負責人和 AI 都能讀懂：這台購物車送進去，應該拿到這張收據。

ToppleCat 不會替你定義什麼叫訂單成立。它保存人選定的規則和例子，在實作完成後檢查雙方原本同意的內容。

在 ToppleCat 裡，描述流程的 Java 方法叫做 Acceptance Method（驗收方法），JSON 或 YAML 例子叫做 Typed Case Row（型別案例資料列）。兩者合在一起，就是公開的 Executable Contract（可執行契約）。

用 Java 描述行為¶

每條選定規則，也就是 Acceptance Condition，都有一個公開的 @ToppleAcceptanceTest("AC-...") 方法。方法名稱要說清楚業務結果：

@ToppleAcceptanceTest("AC-CART-COUPON")
@DisplayName("SAVE100 reduces the order subtotal")
void appliesCoupon(ToppleCase c, ToppleScenario scenario, CouponStage coupon) {
    scenario.given(coupon).a_payable_cart(c.input("cart", Cart.class));
    scenario.when(coupon).checks_out();
    scenario.then(coupon).receipt_shows_discount_and_discounted_subtotal(c);
}

這個方法應該短到可以當成一段故事閱讀。ToppleCase 提供當次例子， ToppleScenario 記錄 Given、When、Then 的順序，CouponStage 裡的方法負責真正的準備工作、服務呼叫與斷言。

想看能實際執行的完整寫法，可以選擇閱讀 JUnit cart-orders 學習專案。它使用已發布的 0.2.0，並提供五項完全合成的保障課程；每一項完成後都會留下該課程的本機 HTML 驗證報告於 build/topplecat/demo-reports/。不需要先執行範例才能照著本頁撰寫。

方法格式有明確限制：ToppleCase 必須放第一個，後面是一個 ToppleScenario，再接一個或多個不同的具體 Stage。Stage 不能是 final，並且要有可存取的無參數 constructor。每一行直接呼叫 scenario.given|when|then|and(stage).step(...)；條件判斷、helper 與 assertions 放在 Stage 方法裡。

@DisplayName 與 @As 應使用審閱者看得懂的業務文字。這些人寫的句子會原樣保留在契約與報告中。

加入輸入與預期結果¶

公開案例列放在 src/test/resources/topplecat/cases/：

- caseId: order-public-example
  acId: AC-ORDER-CREATE
  inputs:
    request: {items: [{sku: example-sku, quantity: 1}]}
  expected:
    response: {accepted: true}

每一列有四個部分：案例自己的 ID、它所屬的規則、輸入，以及預期結果。公開案例讓實作 AI 知道規則長什麼樣子。審閱者控制的案例重用同一條規則與同一個方法，但會選擇不同的邊界。它們不是祕密的新需求。

AI 收到的是公開契約。正式驗證之後執行的也是同一份公開內容，ToppleCat 不會在交付後偷換另一套公開規格。

確認預期結果真的有比較¶

讀取預期值不等於驗證它。使用 c.verify("receipt", actual)，把實際收據和人寫下的完整預期收據比較。ToppleCat 會記錄每個最上層預期值是否真的被斷言、只是被讀取，或根本沒有執行到。

如果一條規則應該對很多輸入都成立，可以再寫公開的 @ToppleProperty。例如：商品順序改變不應影響訂單總額。性質檢查使用有界的產生輸入，透過自己的獨立檢查回報；它不會取代具體案例。

決定要交給 AI 什麼¶

AI 可以依照人已確認的規則，完成 Java 接線和案例檔案。把本頁、選定的業務規則與公開例子交給它，要求每條規則只用一個 Acceptance Method，並比較完整、可觀察的結果。

規則與例子是否完整，仍由人決定。契約裡沒寫退款例外、VIP 折扣或法規要求， ToppleCat 不會自行推論，也不會替組織批准交付。

接著閱讀ToppleCat 如何檢查交付，了解同一份公開契約如何變成這次執行的證據。精確的參數與輸入產生器規則保留在 repository 的 authoring guide。