ben-eddy74/agent-skills

Quarkus BCE 後端工作流程

範圍與目錄邊界

• 嚴格邊界： 僅在 backend/ 目錄內操作。絕不碰觸 frontend/ 檔案。
• 架構： 嚴格遵循 Adam Bien BCE 模式（com.app.<domain>.{boundary, control, entity}）。
• 技術棧： Quarkus、Jakarta EE（僅使用 jakarta.*——絕不使用 javax.* 或 org.springframework.*）。

2 階段執行閘門

階段 1：合約與主幹（暫停供人工審查）

1. entity： 在 ..<domain>.entity 內創建/更新不可變的 Java record 負載（包含 @NotNull、@NotBlank、@Schema）以及 JPA/Panache 實體。對 control 或 boundary 零依賴。
2. boundary： 在 ..<domain>.boundary 內創建/更新 JAX-RS @Path 資源簽名（@Transactional、@RolesAllowed、@Operation）。
3. 測試： 在 backend/src/test/java/..<domain>/boundary/ 內創建/更新失敗的 JUnit @QuarkusTest 或單元測試樁。
4. 暫停： 向用戶顯示 entity、boundary 及測試的差異。在編寫 control 實作前等待批准。

階段 2：實作與結構匯出

1. control： 在 ..<domain>.control（@ApplicationScoped）內實作業務邏輯。絕不直接呼叫另一個領域的 control；一律通過其 boundary。
2. 驗證並匯出合約： 在 backend/ 內執行：

   ./mvnw test
   

Java 25 LTS 語言與 JVM 規則（強制）

目標僅限 Java 25 LTS（<maven.compiler.release>25</maven.compiler.release>）。絕不編寫傳統 Java 8/11/17 樣板：

1. 窮舉 switch 與記錄解構（control 與 entity）：
   • 在 entity 中使用 sealed interface 加 record 實作來建模領域結果與狀態機。
   • 在 control 中，使用帶記錄模式解構與守護 when 子句的窮舉 switch 表達式處理它們（例如，case PaidOrder(var id, var total) when total > 1000 -> ...）。
   • 絕不在 sealed interface 的 switch 中包含 default 分支，這樣 Java 25 編譯器在新增狀態時才會強制窮舉性。
2. 彈性建構子主體（JEP 513）：
   • 直接在建構子內，在呼叫 super(...) 或 this(...) 之前，執行快速失敗驗證與數據正規化，而不是建立龐大的靜態輔助方法。
3. 未命名變數（_）：
   • 對於未使用的 lambda 參數、忽略的例外變數或未使用的解構記錄元件，一律使用 _（例如，case Order(var id, _, _)）。
4. 虛擬執行緒與作用域值（JEP 506）：
   • 對於 Quarkus boundary 中的阻塞 I/O 端點，除非需要串流，否則優先使用 @RunOnVirtualThread 而非反應式 Uni<T> 鏈。
   • 絕不使用 ThreadLocal；如果必須在執行緒作用域內傳遞上下文狀態，一律使用 Java 25 的 ScopedValue<T>。
5. 現代集合與串流收集器（JEP 485）：
   • 使用 SequencedCollection 方法（.getFirst()、.getLast()、.reversed()）而非索引運算 list.get(list.size() - 1)。
   • 使用 Stream.gather(Gatherers.windowFixed(...)) 而非手動分塊迴圈。
6. 除非要求，否則不啟用預覽標記：
   • 堅持使用已定案的 Java 25 LTS 功能（除非明確要求，否則不要為 JEP 507 基本類型模式或 JEP 505 結構化並發啟用 --enable-preview）。