birc-generator 0.5.5

package/project-docs/AGENTS.md.hbs

@@ -0,0 +1,12 @@
+# {{projectName}} — Agent 目錄
+
+BIRC 產出的 Spring Boot 專案。人跟 AI coding agent 先讀這份，再只打開這次用得到的那一份。
+
+| 文件 | 何時讀 |
+| --- | --- |
+| [ponytail](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail/SKILL.md) | 實作時決定**做多大**。這才是 implement 的手感。專案裡的梯子寫在 [PROJECT.md](PROJECT.md) 的「夠用就停」。 |
+| [PROJECT.md](PROJECT.md) | 架構、分層、CRUD 慣例、opt-in。規範只活在這裡。 |
+| [implement.md](implement.md) | 計畫已定，要把功能做成 diff。 |
+| [test.md](test.md) | 開始寫或改測試。 |
+
+功能模組（email / sso / oauth）用 `birc add`，不要從別的專案抄設定。

package/project-docs/PROJECT.md.hbs

@@ -0,0 +1,128 @@
+# {{projectName}} — 專案架構與規範
+
+## 夠用就停
+
+先讀這次要動的程式與資料流，再決定要不要寫新的。從上往下，停在第一個站得住的：
+
+1. 這次真的要做嗎？推測以後用得到的先不做。
+2. 專案裡已經有了嗎？繼承 `BaseService`，用現成 Mapper / DAO，功能模組走 `birc add`。
+3. Spring、Jakarta、JDK 已經有了嗎？驗證、MapStruct、`Specification` 用現成的，不要自製框架。
+4. `build.gradle` 裡的依賴夠不夠？不要為了對稱再加套件。
+5. 只缺一個行為？在 `XxxService` 加方法，不要新 class、新資料夾。
+6. 以上都不夠，才寫最小能跑的。
+
+驗證、權限、資料不能丟的錯誤處理不算「可以少寫」。CRUD 繼承是第 2 階的預設答案。
+
+## 預設節奏：CRUD 繼承，方法外加
+
+標準增刪改查只寫在 `BaseServiceImpl`。`XxxService` 繼承 `BaseService<CreateRequest, Response, Long>`，不要把 create / getById / update / deleteById 再抄一次。多出來的業務（送審、審核、統計）才在 `XxxService` 加方法，在 `XxxServiceImpl` 實作，直接用繼承下來的 `dao`、`mapper`。
+
+資料流：
+
+```
+HTTP JSON → XxxCreateRequest → Mapper → Entity → DAO
+DB → Entity → Mapper → XxxResponse → Result<T>
+```
+
+新增一張表用 `birc make`。先讓 CRUD 能跑；有規則再加方法。不要為了彈性先上 Clean Architecture 資料夾或一個操作一個 UseCase class。
+
+## 技術棧
+
+- Spring Boot 4 / Java 21
+- Spring Data JPA + MySQL
+- MapStruct（DTO 轉換）
+
+## 目錄結構
+
+（依 `.bircrc.json` 的 `basePackage` 展開）
+
+- `entity/`（多模組時在 `databaseconfig.entity`）
+- `dao/`（`XxxDAO extends BaseDAO`；多模組時在 `databaseconfig.dao`）
+- `dto/`（`XxxCreateRequest` / `XxxResponse`）
+- `mapper/`（`EntityMapper`；`XxxMapper extends EntityMapper`）
+- `service/`、`service/impl/`（`BaseService`；`XxxService extends BaseService`）
+- `controller/`
+- `web/Result`
+
+## 分層（baseline）
+
+- `entity`：JPA，多模組時在 `databaseconfig`。只放欄位與 getter/setter。沒有 `BaseEntity`。
+- `dto`：Java record。`XxxCreateRequest` 進來（`jakarta.validation` + `ValidGroup.Create` / `ValidGroup.Update`），`XxxResponse` 出去。這是 API 與 Service 的語言，不是 Entity。
+- `mapper`：`XxxMapper extends EntityMapper<Entity, CreateRequest, Response>`，MapStruct、`componentModel = "spring"`。跨欄位計算才寫 `default method`。轉換一律走 Mapper，不走 `JavaBeanUtils`、不手寫 Transformer。
+- `dao`：`XxxDAO extends BaseDAO<Entity, ID>`。自訂查詢才在介面加方法。資料庫 VIEW 不能寫入時，那個 DAO `extends BaseViewDAO`（沒有 save / delete）。不要為了跟 DAO 對稱再做一個 `BaseViewService`。
+- `service`：Controller 注入 `XxxService` 介面。一對一 `XxxServiceImpl` 是正常的；介面的價值是額外方法的掛點與 Spring 注入，不是預先準備第二套實作。查詢 API 大到該獨立時，另開一個查詢介面（例如只含 search / count），不要把八十個方法塞進同一個 Service。
+- `controller`：參數驗證與呼叫 Service。回傳專案內 `web.Result<T>`。不回 Entity、不注入 DAO、不引用 `birc-spring-boot-starter`。
+
+## 統一規範
+
+- 例外丟 `ProjectException` 子類（例如 `NotFoundException`），由 `ExceptionHandleController` 轉成回應。Controller 不手動 try-catch 包錯誤訊息。
+- 整組骨架用 `birc make`；單層用 `birc make:entity` / `make:model` / `make:mapper` / `make:service` / `make:controller` / `make:exception`。`make:entity` 只生 Entity 與 DAO；`--dto` 與 `--mapper` 一併生 Mapper 與 DTO。`make:model` 可加 `--migration` / `--seed` / `--controller`。`--soft-delete` 用 Hibernate `@SoftDelete` 的 `deleted_at`，查詢自動排除已刪；不要自寫 `@SQLDelete`。預設是初稿，完整範例加 `--example`。不要複製其他 Entity 的程式碼來改名。
+- 欄位驗證用專案內 `validation/ValidGroup`。CRUD 用 `Create` / `Update`。`Delete` 給「刪除還要帶原因、確認碼、樂觀鎖 version」的 body。`Submit` 給草稿可少填、送審要全填（活動送審就是這組）。Controller 的 `@Validated` 與欄位 `groups` 對同一組。
+- email / sso / oauth / validGroup 用 `birc add`，不要從別的專案抄設定。
+- 格式化走 Spotless（`./gradlew spotlessApply`），不要另裝 Checkstyle。
+
+## 已啟用的功能模組
+
+見 `.bircrc.json` 的 `features` 欄位。要加新的模組用 `birc add`。
+
+## SSO / Sentry
+
+在 `application.yml` 設定：
+
+```yaml
+birc:
+  sso:
+    enabled: true
+    login-url: ...
+    validate-url: ...
+```
+
+沒有 SSO 的專案就不用設定這段，`SsoAutoConfiguration` 不會被啟用。
+
+## 進階模式（opt-in）
+
+只在對應條件出現時才用。判斷不出來就停在 baseline，之後再重構。這是「夠用就停」的第 6 階，不是每個 entity 的起手式。
+
+### 1. 把邏輯搬進 Entity（rich entity）
+
+**何時：** 有明確狀態機，且轉換規則會被多個 service 方法重複檢查。
+
+**怎麼做：** 做成 `activity.approve()`、`activity.reject(String reason)` 這類方法，由 entity 檢查是否允許轉換。允許關係收成一張表，不要散成 `if/else`。`ServiceImpl` 只做 load、權限、呼叫 entity、save。只套在真的有狀態機的 entity。
+
+### 2. Domain Event
+
+**何時：** 成功後要做跟核心無關、失敗也不該讓主流程失敗的事（發信、稽核）。
+
+**怎麼做：** `ApplicationEventPublisher.publishEvent(...)`，監聽用 `@TransactionalEventListener(phase = AFTER_COMMIT)`。主流程裡用 try-catch 包住通知來「避免發信失敗」就是該改成 event 的訊號。
+
+### 3. Value Object
+
+**何時：** 一組欄位有自己的驗證，且多處重複（email 格式、日期區間）。
+
+**怎麼做：** 獨立 record，建構子裡驗證失敗就丟例外。沿用 DTO 用 record 的慣例。純顯示字串不必包。
+
+### 4. Specification
+
+**何時：** DAO 出現大量 `findByXAndYAndZ` 名稱組合爆炸。
+
+**怎麼做：** Spring Data `Specification<T>`，條件拆成靜態方法，在 Service 組合。
+
+### 5. Port / Adapter
+
+**何時：** 串專案外部系統（第三方 API、SSO、檔案儲存），不是資料庫。
+
+**怎麼做：** Service 只看 interface；實作放 `client` 或對應 infra。資料庫繼續用 `BaseDAO`，不必再包一層 repository port。
+
+## 禁止事項
+
+- 業務規則失敗繼續丟 `ProjectException` 子類，不要另做 `Either` / `Result<T, E>` 兩套錯誤處理。
+- Entity 上的業務方法只在「進階模式 1」成立時才加。
+- Controller 不直接注入 DAO、不回傳 Entity。
+- 不把 Transformer / `JavaBeanUtils.copy` 加回來。
+- 不為了對稱新增 `BaseViewService`、`BaseEntity`，也不把 Clean Architecture 四層當每個 CRUD 的起手式。
+
+## 待辦 / 已知限制
+
+（這裡列目前專案的 TODO 或已知技術債，讓後續接手的人或 AI agent 一看就懂現狀，不用重新問一次）
+
+- [ ]

package/project-docs/implement.hbs

@@ -0,0 +1,54 @@
+# implement
+
+把**已經決定**的工作做成可合併的 diff。不重開計畫。
+
+## 跟其它文件
+
+| 先讀 | 再做 |
+| --- | --- |
+| ponytail + [PROJECT.md](PROJECT.md) 的夠用就停 | 決定這次寫哪些檔。手感在梯子，不在這份。 |
+| [PROJECT.md](PROJECT.md) | 對齊分層與慣例。 |
+| [test.md](test.md) | 步驟走到「寫測試」時打開。 |
+
+## 何時用
+
+人叫「照 implement 做」，或把已定案的票丟過來。計畫還不存在就先問。
+
+## 步驟
+
+1. 讀已定案行為。公開邊界通常是 `XxxService`、Controller 的 HTTP 契約、`Result` 外殼。
+2. 爬夠用就停：能繼承 `BaseService`、能 `birc add`、能在現有方法加行為，就停在那一階。
+3. 依 [test.md](test.md) 一條紅 → 剛好夠綠 → 下一條。
+4. 最後跑一次 `./gradlew test`（Windows `gradlew.bat test`）。
+5. 人要求 commit、或這次明確說「做完並提交」才提交。格式見下面。沒說就停在回報。
+
+完成條件：能說出停在梯子第幾階；`./gradlew test` 綠；沒有順便新資料夾或第二套錯誤處理。
+
+## Commit
+
+Commit 前跑 `./gradlew spotlessApply`（Windows `gradlew.bat spotlessApply`）。
+
+Conventional Commits，標題與本文一律中文：
+
+- 類型：`feat:` / `fix:` / `refactor:` / `chore:` / `test:` / `docs:`
+- 標題寫為什麼，一行。本文用編號列做了什麼。
+- 不要加 `Ultraworked by AI`、`Co-authored-by:` 或其它 AI 後綴。
+
+```text
+feat: 新增使用者驗證功能
+
+1. 使用 JWT 實作 Token 管理
+2. 加入密碼強度驗證 (Model Validator)
+3. 補充 Unit Tests，覆蓋率達 85%
+```
+
+## 回報
+
+```text
+梯子停在: …
+測試檔: …
+圍住: …
+人工突變: 改了 X，Y 測試轉紅
+仍需人看: …
+跳過: …
+```

package/project-docs/test.hbs

@@ -0,0 +1,31 @@
+# test
+
+這個 Spring 專案裡測試怎麼寫。流程在 [implement.md](implement.md)；規範在 [PROJECT.md](PROJECT.md)。
+
+目標不是「讓測試變綠」，是「有問題的碼過不了關」。
+
+## 工具
+
+沿用專案已有的 `./gradlew test`（JUnit、`spring-boot-starter-test`）。不要為了某一張票引入 Cucumber、PITest，除非票本身就是加那道門檻。
+
+Given-When-Then 寫在**測試方法名稱**，例如 `create_whenEmailMissing_rejectsWithValidGroupCreate`。
+
+## 打在哪
+
+優先打 `XxxService` 的公開方法：CRUD 繼承來的不用再抄一遍；多出來的業務（送審、審核、名額）才測。Controller 只在 HTTP 契約或 `ValidGroup` 分組是這次改動時才測。
+
+不斷言 Mapper 的欄位對欄位清單，除非轉換本身有跨欄位規則。預期值來自規格，不要用實作自己算一遍。
+
+每條關鍵測試要寫得出「這條防住什麼」。
+
+## 關鍵路徑 vs 低風險
+
+關鍵：狀態轉換、名額／計數、權限、錢、取消後要精確回退。這類用**業務不變量**斷言（不得為負、不得超過上限、回滾後與事前相同），並附反向案例（狀態不允許、權限不足要丟對應的 `ProjectException` 子類）。
+
+低風險：純 getter、空的初稿 Controller、只改文案。零測試或一條鎖定契約即可。
+
+有共享計數（報名、庫存）才測競態。時間邊界注入可控時鐘，不用 `Thread.sleep`。
+
+至少一次**人工突變**：改壞剛寫的關鍵規則，確認測試轉紅，再改回來。
+
+完成條件：這次改動的關鍵路徑有正反案例；低風險沒被拿去湊數量。

package/scripts/install-bin.sh

@@ -0,0 +1,72 @@
+# 給 install.sh / update.sh source。把 birc 掛到使用者寫得到的 bin，不呼叫 sudo。
+
+birc_is_windows() {
+    [ -n "${WINDIR:-}" ] || [[ "${OSTYPE:-}" == msys* || "${OSTYPE:-}" == cygwin* || "${OSTYPE:-}" == mingw* ]]
+}
+
+birc_try_bin_dir() {
+    local dir="$1"
+    [ -n "$dir" ] || return 1
+    mkdir -p "$dir" 2>/dev/null || return 1
+    [ -w "$dir" ] || return 1
+    printf '%s\n' "$dir"
+}
+
+birc_detect_bin_dir() {
+    local npm_prefix="" npm_bin=""
+    npm_prefix="$(npm config get prefix 2>/dev/null || true)"
+    if [ -n "$npm_prefix" ]; then
+        if [ -d "$npm_prefix/bin" ]; then
+            npm_bin="$npm_prefix/bin"
+        else
+            npm_bin="$npm_prefix"
+        fi
+    fi
+
+    if birc_is_windows; then
+        birc_try_bin_dir "$npm_bin" && return 0
+        birc_try_bin_dir "$HOME/.local/bin" && return 0
+    else
+        birc_try_bin_dir /usr/local/bin && return 0
+        birc_try_bin_dir "$npm_bin" && return 0
+        birc_try_bin_dir "$HOME/.local/bin" && return 0
+    fi
+
+    error "找不到可寫入的 bin 目錄。請先確認 npm 可用，或自行把 $HOME/.local/bin 加進 PATH。"
+}
+
+birc_install_command() {
+    local script_path="$1"
+    local bin_dir escaped win_path
+    bin_dir="$(birc_detect_bin_dir)"
+    escaped="${script_path//\'/\'\\\'\'}"
+
+    cat > "$bin_dir/birc" <<EOF
+#!/usr/bin/env bash
+_birc_js='$escaped'
+if command -v cygpath >/dev/null 2>&1; then
+    exec node "\$(cygpath -w "\$_birc_js")" "\$@"
+fi
+exec node "\$_birc_js" "\$@"
+EOF
+    chmod +x "$bin_dir/birc"
+
+    if birc_is_windows; then
+        if command -v cygpath >/dev/null 2>&1; then
+            win_path="$(cygpath -w "$script_path")"
+        else
+            win_path="$script_path"
+        fi
+        printf '@echo off\nnode "%s" %%*\n' "$win_path" > "$bin_dir/birc.cmd"
+    fi
+
+    info "已安裝指令: $bin_dir/birc"
+    case ":$PATH:" in
+        *":$bin_dir:"*) ;;
+        *)
+            export PATH="$bin_dir:$PATH"
+            warn "已暫時把 $bin_dir 加進 PATH。若關掉終端後找不到 birc，把下面這行加進 ~/.bashrc："
+            warn "export PATH=\"$bin_dir:\$PATH\""
+            ;;
+    esac
+}

package/scripts/update.sh

@@ -0,0 +1,11 @@
+#!/bin/bash
+set -e
+
+# 相容入口。實際更新改走 Node，讓 PowerShell 裝的 Windows 不必再找 bash。
+# 由 checkout 執行: bash scripts/update.sh
+# `birc update` 直接 require bin/home-install.js。
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+export BIRC_CURRENT_ROOT="${BIRC_CURRENT_ROOT:-$ROOT}"
+export BIRC_INSTALL_DIR="${BIRC_INSTALL_DIR:-$HOME/.birc-generator}"
+exec node "$ROOT/bin/home-install.js" update

package/templates/aop/OperationLog.hbs

@@ -0,0 +1,18 @@
+package {{basePackage}}.annotation;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * 標在 Controller / Service 方法上，用來記錄操作事件（誰、做了什麼、對哪筆資料）。
+ * 實際落地方式（存 DB / 送 log 系統）在 OperationLogAspect 裡實作，這裡先印 log。
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.METHOD)
+public @interface OperationLog {
+
+    /** 操作說明，例如 "建立活動"、"刪除使用者" */
+    String value();
+}

package/templates/aop/OperationLogAspect.hbs

@@ -0,0 +1,95 @@
+package {{basePackage}}.aspect;
+
+import java.util.Arrays;
+import lombok.extern.slf4j.Slf4j;
+import org.aspectj.lang.JoinPoint;
+import org.aspectj.lang.annotation.AfterReturning;
+import org.aspectj.lang.annotation.AfterThrowing;
+import org.aspectj.lang.annotation.Aspect;
+import org.aspectj.lang.annotation.Pointcut;
+import org.aspectj.lang.reflect.MethodSignature;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.stereotype.Component;
+import org.springframework.web.context.request.RequestContextHolder;
+import org.springframework.web.context.request.ServletRequestAttributes;
+import {{basePackage}}.annotation.OperationLog;
+
+@Slf4j
+@Aspect
+@Component
+public class OperationLogAspect {
+
+    // X-Forwarded-User 是客戶端可偽造的標頭，只有部署在會覆寫此標頭的
+    // 可信反向代理（如 SSO gateway）後面才允許採信，預設關閉。
+    @Value("${operation-log.trust-forwarded-user:false}")
+    private boolean trustForwardedUser;
+
+    @Pointcut("@annotation({{basePackage}}.annotation.OperationLog)")
+    public void operationLogPointcut() {
+    }
+
+    @AfterReturning(pointcut = "operationLogPointcut()")
+    public void logAfterReturning(JoinPoint joinPoint) {
+        OperationLog annotation = annotation(joinPoint);
+        log.info(
+                "[OperationLog] operator={}, ip={}, action={}, method={}, args={}",
+                resolveOperator(),
+                resolveIp(),
+                annotation.value(),
+                joinPoint.getSignature().toShortString(),
+                Arrays.toString(joinPoint.getArgs()));
+    }
+
+    @AfterThrowing(pointcut = "operationLogPointcut()", throwing = "error")
+    public void logAfterThrowing(JoinPoint joinPoint, Throwable error) {
+        OperationLog annotation = annotation(joinPoint);
+        log.error(
+                "[OperationLog] failed operator={}, ip={}, action={}, method={}, error={}",
+                resolveOperator(),
+                resolveIp(),
+                annotation.value(),
+                joinPoint.getSignature().toShortString(),
+                error.getMessage());
+    }
+
+    private OperationLog annotation(JoinPoint joinPoint) {
+        return ((MethodSignature) joinPoint.getSignature()).getMethod().getAnnotation(OperationLog.class);
+    }
+
+    private String resolveOperator() {
+        try {
+            org.springframework.security.core.Authentication authentication =
+                    org.springframework.security.core.context.SecurityContextHolder.getContext()
+                            .getAuthentication();
+            if (authentication != null
+                    && authentication.isAuthenticated()
+                    && !"anonymousUser".equals(authentication.getPrincipal())) {
+                return authentication.getName();
+            }
+        } catch (Throwable ignored) {
+            // 沒有 Spring Security 時略過
+        }
+        ServletRequestAttributes attributes =
+                (ServletRequestAttributes) RequestContextHolder.getRequestAttributes();
+        if (trustForwardedUser && attributes != null) {
+            String forwardedUser = attributes.getRequest().getHeader("X-Forwarded-User");
+            if (forwardedUser != null && !forwardedUser.isBlank()) {
+                return forwardedUser;
+            }
+        }
+        return "anonymous";
+    }
+
+    private String resolveIp() {
+        ServletRequestAttributes attributes =
+                (ServletRequestAttributes) RequestContextHolder.getRequestAttributes();
+        if (attributes == null) {
+            return "unknown";
+        }
+        String forwarded = attributes.getRequest().getHeader("X-Forwarded-For");
+        if (forwarded != null && !forwarded.isBlank() && !"unknown".equalsIgnoreCase(forwarded)) {
+            return forwarded.split(",")[0].trim();
+        }
+        return attributes.getRequest().getRemoteAddr();
+    }
+}

package/templates/aop/build-gradle-dep.hbs

@@ -0,0 +1 @@
+    implementation 'org.springframework.boot:spring-boot-starter-aspectj'

package/templates/base/Application.hbs

@@ -0,0 +1,11 @@
+package {{basePackage}};
+
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+
+@SpringBootApplication
+public class Application {
+    public static void main(String[] args) {
+        SpringApplication.run(Application.class, args);
+    }
+}

package/templates/base/ApplicationTests.java.hbs

@@ -0,0 +1,11 @@
+package {{basePackage}};
+
+import org.junit.jupiter.api.Test;
+import org.springframework.boot.test.context.SpringBootTest;
+
+@SpringBootTest
+class ApplicationTests {
+
+    @Test
+    void contextLoads() {}
+}

package/templates/base/BaseService.hbs

@@ -0,0 +1,15 @@
+package {{basePackage}}.service;
+
+/**
+ * 標準 CRUD。XxxService 繼承這個介面；多出來的業務方法寫在 XxxService 上，不要改這裡。
+ */
+public interface BaseService<Request, Response, ID> {
+
+    Response create(Request request);
+
+    Response getById(ID id);
+
+    Response update(ID id, Request request);
+
+    void deleteById(ID id);
+}

package/templates/base/BaseServiceImpl.hbs

@@ -0,0 +1,53 @@
+package {{basePackage}}.service.impl;
+
+import java.io.Serializable;
+import org.springframework.transaction.annotation.Transactional;
+import {{daoPackage}}.BaseDAO;
+import {{basePackage}}.exception.NotFoundException;
+import {{basePackage}}.mapper.EntityMapper;
+import {{basePackage}}.service.BaseService;
+
+/**
+ * CRUD 實作。XxxServiceImpl 把 DAO、Mapper 丟進 super，額外邏輯寫在子類，可直接用 dao、mapper。
+ */
+@Transactional
+public abstract class BaseServiceImpl<E, ID extends Serializable, Request, Response>
+        implements
+            BaseService<Request, Response, ID> {
+
+    protected final BaseDAO<E, ID> dao;
+    protected final EntityMapper<E, Request, Response> mapper;
+
+    protected BaseServiceImpl(BaseDAO<E, ID> dao, EntityMapper<E, Request, Response> mapper) {
+        this.dao = dao;
+        this.mapper = mapper;
+    }
+
+    @Override
+    public Response create(Request request) {
+        return mapper.toResponse(dao.save(mapper.toEntity(request)));
+    }
+
+    @Override
+    @Transactional(readOnly = true)
+    public Response getById(ID id) {
+        return mapper.toResponse(dao.findById(id)
+                .orElseThrow(() -> new NotFoundException("查無資料，id：" + id)));
+    }
+
+    @Override
+    public Response update(ID id, Request request) {
+        E entity = dao.findById(id)
+                .orElseThrow(() -> new NotFoundException("找不到資料，無法更新, id = " + id));
+        mapper.updateEntity(request, entity);
+        return mapper.toResponse(dao.save(entity));
+    }
+
+    @Override
+    public void deleteById(ID id) {
+        if (!dao.existsById(id)) {
+            throw new NotFoundException("找不到資料，無法刪除, id = " + id);
+        }
+        dao.deleteById(id);
+    }
+}

package/templates/base/EntityMapper.hbs

@@ -0,0 +1,12 @@
+package {{basePackage}}.mapper;
+
+import org.mapstruct.MappingTarget;
+
+public interface EntityMapper<E, Request, Response> {
+
+    E toEntity(Request request);
+
+    Response toResponse(E entity);
+
+    void updateEntity(Request request, @MappingTarget E entity);
+}

package/templates/base/README.md.hbs

@@ -0,0 +1,56 @@
+# {{projectName}}
+
+BIRC `create` 產出的 Spring Boot 4 專案。這份說明啟動與生骨架。
+給 AI coding agent 讀的規範在 `AGENTS.md`（若建立時有注入）。
+
+## 啟動
+
+{{#if hasDocker}}
+先開資料庫，再把 `.env` 載入目前的 shell，最後跑 Spring Boot。
+
+Bash / WSL / Git Bash：
+
+```bash
+docker compose up -d db
+set -a && source .env && set +a
+./gradlew bootRun
+```
+
+PowerShell：
+
+```powershell
+docker compose up -d db
+Get-Content .env | ForEach-Object {
+  if ($_ -match '^\s*([^#][^=]*)=(.*)$') {
+    Set-Item -Path "Env:$($matches[1].Trim())" -Value $matches[2].Trim().Trim('"')
+  }
+}
+.\gradlew.bat bootRun
+```
+{{else}}
+先準備 MySQL，並設定 `src/main/resources/application.yml` 的連線，再跑：
+
+```bash
+./gradlew bootRun
+```
+
+Windows 用 `.\gradlew.bat bootRun`。
+{{/if}}
+
+## 生骨架
+
+在有 `.bircrc.json` 的目錄跑即可；子目錄也可以，`birc` 會往上找。
+
+```bash
+birc make
+birc make:entity User --example --fields title:String
+birc add email
+```
+
+## 不要刪的標記
+
+`birc add` 靠這幾行插入設定。刪了會預檢查失敗、不寫任何檔。
+
+- `src/main/resources/application.yml`：`# birc-generator:config-anchor`
+- `build.gradle`：`// birc-generator:dependency-anchor`
+- 若有：`// birc-generator:plugin-anchor`、`// birc-generator:allprojects-anchor`

package/templates/base/Result.hbs

@@ -0,0 +1,48 @@
+package {{basePackage}}.web;
+
+/**
+ * API 統一外殼。成功帶 data，失敗帶 errorCode / message。
+ * 業務錯誤仍丟 ProjectException，由 ExceptionHandleController 轉成 failure。
+ */
+public class Result<T> {
+
+    private final boolean success;
+    private final T data;
+    private final String errorCode;
+    private final String message;
+
+    private Result(boolean success, T data, String errorCode, String message) {
+        this.success = success;
+        this.data = data;
+        this.errorCode = errorCode;
+        this.message = message;
+    }
+
+    public static <T> Result<T> success(T data) {
+        return new Result<>(true, data, null, null);
+    }
+
+    public static Result<Void> success() {
+        return new Result<>(true, null, null, null);
+    }
+
+    public static <T> Result<T> failure(String errorCode, String message) {
+        return new Result<>(false, null, errorCode, message);
+    }
+
+    public boolean isSuccess() {
+        return success;
+    }
+
+    public T getData() {
+        return data;
+    }
+
+    public String getErrorCode() {
+        return errorCode;
+    }
+
+    public String getMessage() {
+        return message;
+    }
+}

package/templates/base/application-test.yml.hbs

@@ -0,0 +1,27 @@
+spring:
+  datasource:
+    url: jdbc:h2:mem:{{snakeCase projectNameKebab}};MODE=MySQL;DB_CLOSE_DELAY=-1
+    driver-class-name: org.h2.Driver
+    username: sa
+    password:
+  jpa:
+    hibernate:
+      ddl-auto: none
+  flyway:
+    enabled: false
+  mail:
+    host: localhost
+    port: 3025
+    username: test
+    password: test
+
+sentry:
+  dsn:
+
+birc:
+  sso:
+    enabled: false
+
+external:
+  api:
+    base-url: https://example.com