birc-generator 0.8.0 → 0.9.0

package/PROJECT.md

@@ -48,7 +48,7 @@ anchor 就不要重寫整份設定；推測以後會用到的模組先不要做
 
 ## 慣例
 
-**make 一次整組。** `make` 串 `makeStackActions`：Entity + DAO + Mapper + DTO + Service + Controller。`--migration` 生 `create_{table}_table`（Flyway SQL）。`--seed` 生 `XxxSeeder`（Java，走 DAO；`birc seed` 才執行）。單層指令共用同一組 actions，不另寫一份。`make:entity` 產出 Entity、`XxxDAO extends BaseDAO`。`make:model` 同 Entity + DAO；`--migration` / `--seed` 同上，`--controller` 生 Controller。`make:seeder BookSeeder` 只生 Seeder（寫 `Book` 也可以，結尾 `Seeder` 會剝掉再對 Entity）。`--soft-delete` 在 Entity 加 Hibernate `@SoftDelete(columnName = "deleted_at", strategy = TIMESTAMP)`，migration 加 `deleted_at TIMESTAMP NULL`；`deleteById` 不用改。不做 restore / withTrashed。`make:entity --dto` 與 `make:entity --mapper` 一併生 Mapper 與 Request / Response DTO（同一組檔）。`make:mapper` 連 Request / Response DTO，並把 MapStruct 依賴接到 `build.gradle` 的 dependency-anchor 後面（已有則跳過）。`make:service` 的 `XxxService extends BaseService`，CRUD 在 `BaseServiceImpl`；多出來的業務方法寫在 `XxxService` / `XxxServiceImpl`。指令是 `make:entity`，不是 `make::entity`。預設只生引入與初稿；加 `--example` 或 `--fields` 才生完整範例（CRUD、欄位、`@Column`）。`--example` 的 Entity 與 `make:migration` 一樣帶 `created_at` / `updated_at`（DB 填，JPA `insertable = false`），不進 CreateRequest。多模組時 Entity / DAO 落在 `databaseconfig`。路徑以 `.bircrc.json` 的 `entityPath` / `daoPath` 為準。
+**make 一次整組。** `make` 串 `makeStackActions`：Entity + DAO + Mapper + DTO + Service + Controller。`--migration` 生 `create_{table}_table`（Flyway SQL）。`--seed` 生 `XxxSeeder`（Java，走 DAO；`birc seed` 才執行）。單層指令共用同一組 actions，不另寫一份。`make:entity` 產出 Entity、`XxxDAO extends BaseDAO`。`--migration` / `--seed` 同 `make:model`；已有 Entity 就跳過，只補 SQL / Seeder。`make:model` 同 Entity + DAO；`--migration` / `--seed` 同上，`--controller` 生 Controller。`make:seeder BookSeeder` 只生 Seeder（寫 `Book` 也可以，結尾 `Seeder` 會剝掉再對 Entity）。`--soft-delete` 在 Entity 加 Hibernate `@SoftDelete(columnName = "deleted_at", strategy = TIMESTAMP)`，migration 加 `deleted_at TIMESTAMP NULL`；`deleteById` 不用改。不做 restore / withTrashed。`make:entity --dto` 與 `make:entity --mapper` 一併生 Mapper 與 Request / Response DTO（同一組檔）。`make:mapper` 連 Request / Response DTO，並把 MapStruct 依賴接到 `build.gradle` 的 dependency-anchor 後面（已有則跳過）。`make:service` 的 `XxxService extends BaseService`，CRUD 在 `BaseServiceImpl`；多出來的業務方法寫在 `XxxService` / `XxxServiceImpl`。指令是 `make:entity`，不是 `make::entity`。預設只生引入與初稿；加 `--example` 或 `--fields` 才生完整範例（CRUD、欄位、`@Column`）。`--example` 的 Entity 與 `make:migration` 一樣帶 `created_at` / `updated_at`（DB 填，JPA `insertable = false`），不進 CreateRequest。多模組時 Entity / DAO 落在 `databaseconfig`。路徑以 `.bircrc.json` 的 `entityPath` / `daoPath` 為準。
 
 **例外走 ProjectException。** 基底是專案內的 `ProjectException`（`getErrorCode` / `getHttpStatus`），不是 starter 的 `BusinessException`。`create` 會生 `ProjectException`、`NotFoundException`、`ExceptionHandleController`、`web/Result`。`make:exception` 生的類別一律 `extends ProjectException`。Controller 回傳專案內 `Result<T>`，不引用 `tw.edu.ntub.birc.starter`。
 

package/README.md

@@ -21,17 +21,9 @@ CRUD 用 `birc make`。多模組目錄、`BaseDAO`、`ProjectException` 會先
 
 ## 安裝
 
-需要 Node 18 以上。一般只要裝全域的 `birc`，不必 clone。三種擇一：
-npm、`curl | bash`、PowerShell 的 `irm | iex`。同一台不要混裝，PATH 會搶
-同一個 `birc`。改產生器、或要跑還沒發到 npm 的 commit，才 clone。
-
-`birc update` 會自己判斷來源。npm 裝的等同
-`npm install -g birc-generator@latest`；`curl` / PowerShell 裝的都拉
-GitLab 到 `~/.birc-generator`。
-
-### npm
-
-Win11、WSL、macOS、Linux 都可以。
+需要 Node 18 以上。只走 npm。Win11、WSL、macOS、Linux 都可以。一般只要
+裝全域的 `birc`，不必 clone。改產生器、或要跑還沒發到 npm 的 commit，才
+clone。
 
 ```bash
 npm install -g birc-generator
@@ -44,47 +36,12 @@ npm update -g birc-generator
 npm uninstall -g birc-generator
 ```
 
-使用時若偵測到新版本，會問要不要更新。說不要的話，同一版本 24 小時內
-不會再問。不想檢查就設 `BIRC_SKIP_UPDATE_CHECK=1`。CI 或不是互動終端
-也不會問。
-
-### curl | bash
-
-給 macOS、Linux、WSL、Git Bash。程式放到 `~/.birc-generator`，並把
-`birc` 寫進使用者自己的 bin。不需要 sudo。PowerShell 不要貼這條：內建
-`curl` 是 `Invoke-WebRequest`，會報找不到參數 `-fsSL`。改用下面的
-PowerShell 安裝。
-
-```bash
-curl -fsSL https://gitlab.ntubimdbirc.tw/lucashsu95/birc-generator/-/raw/main/install.sh | bash
-```
-
-關掉終端再開一次，跑 `birc --help`。之後更新用 `birc update`。還沒有
-這個指令的舊安裝，再跑一次上面的 `install.sh`。
-
-解除安裝：
-
-```bash
-curl -fsSL https://gitlab.ntubimdbirc.tw/lucashsu95/birc-generator/-/raw/main/uninstall.sh | bash
-```
-
-### PowerShell
+`birc update` 等同 `npm install -g birc-generator@latest`。使用時若偵測到
+新版本，會問要不要更新。說不要的話，同一版本 24 小時內不會再問。不想檢查
+就設 `BIRC_SKIP_UPDATE_CHECK=1`。CI 或不是互動終端也不會問。
 
-給 Windows 原生 PowerShell 5.1 或 7。落地目錄跟 `curl | bash` 相同
-（`%USERPROFILE%\.birc-generator`），所以之後的 `birc update` 是同一條路。
-`irm | iex` 在記憶體執行，通常不必改 ExecutionPolicy。
-
-```powershell
-irm https://gitlab.ntubimdbirc.tw/lucashsu95/birc-generator/-/raw/main/install.ps1 | iex
-```
-
-關掉終端再開一次，跑 `birc --help`。之後更新用 `birc update`。
-
-解除安裝：
-
-```powershell
-irm https://gitlab.ntubimdbirc.tw/lucashsu95/birc-generator/-/raw/main/uninstall.ps1 | iex
-```
+以前用 `curl | bash` 或 PowerShell 裝到 `~/.birc-generator` 的，改裝 npm
+全域套件，並自行刪掉那個目錄。
 
 ## 第一次用
 
@@ -162,11 +119,11 @@ ValidGroup、Spotless、注入 agent 文件），不再問。
 | 指令 | 做什麼 |
 | --- | --- |
 | `birc create` | 開一個多模組 Spring Boot 4 專案。`--yes` 其餘用預設、不要問 |
-| `birc update` | 更新本機 `birc`。npm 裝的跑 `npm install -g`；curl / PowerShell / clone 拉 GitLab `main` |
+| `birc update` | 更新本機 `birc`（`npm install -g birc-generator@latest`） |
 | `birc add` | 往既有專案加模組。沒帶名稱會互動勾選；`birc add email sentry` 直接加。`--force` 覆寫已選的已安裝 feature 檔 |
 | `birc sync` | 用目前 template 覆寫全部已安裝 feature 的檔（不動 yml / gradle） |
 | `birc make` | 一次生 Entity + DAO + Mapper + DTO + Service + Controller；加 `--migration` / `--seed` |
-| `birc make:entity` | Entity、`XxxDAO`；加 `--dto`、`--mapper`、`--soft-delete`。已有檔要覆寫加 `--force` |
+| `birc make:entity` | Entity、`XxxDAO`；加 `--migration` / `--seed` / `--dto`、`--mapper`、`--soft-delete`。已有檔要覆寫加 `--force`；只要表或 Seeder 可 `--migration` / `--seed`，不會覆寫 Entity |
 | `birc make:model` | 同 `make:entity`；加 `--migration` / `--seed` / `--controller` / `--soft-delete` |
 | `birc make:mapper` | Mapper 和 CreateRequest / Response |
 | `birc make:service` | `XxxService extends BaseService`，CRUD 在 `BaseServiceImpl` |
@@ -295,8 +252,7 @@ npm run test:mutation
 
 發版順序：先把改動推進 GitLab `main`，再改 `package.json` 的 `version`，
 最後 `npm publish`。只推 GitLab、不 publish 的話，`npm install -g` 的人
-拿不到新版；只 publish、不合進 `main` 的話，`curl | bash` /
-`irm | iex` / `birc update` 會跟 npm 版本對不上。
+拿不到新版。
 
 ## 接下來
 

package/bin/birc.js

@@ -28,7 +28,7 @@ const HELP_SECTIONS = [
     note: '寫法是 make:種類 [名稱]。預設只生引入與初稿；加 --example 或 --fields 才有完整範例',
     commands: [
       ['make', '一次生 Entity + DAO + Mapper + DTO + Service + Controller；--migration / --seed'],
-      ['make:entity', 'Entity、XxxDAO（--dto / --mapper / --soft-delete）'],
+      ['make:entity', 'Entity、XxxDAO（--migration / --seed / --dto / --mapper / --soft-delete）'],
       ['make:model', '同 make:entity；--migration / --seed / --controller / --soft-delete'],
       ['make:mapper', 'Mapper、CreateRequest、Response'],
       ['make:service', 'XxxService extends BaseService'],
@@ -174,8 +174,8 @@ function printHelp() {
       `  ${'--example'.padEnd(nameWidth + 2)}make:* 產出完整範例`,
       `  ${'--dto'.padEnd(nameWidth + 2)}make:entity 順便生 Mapper 與 DTO`,
       `  ${'--mapper'.padEnd(nameWidth + 2)}同 --dto`,
-      `  ${'--migration'.padEnd(nameWidth + 2)}make / make:model 順便生 create_{table}_table`,
-      `  ${'--seed'.padEnd(nameWidth + 2)}make / make:model 順便生 Java Seeder`,
+      `  ${'--migration'.padEnd(nameWidth + 2)}make / make:entity / make:model 順便生 create_{table}_table`,
+      `  ${'--seed'.padEnd(nameWidth + 2)}make / make:entity / make:model 順便生 Java Seeder`,
       `  ${'--controller'.padEnd(nameWidth + 2)}make:model 順便生 Controller`,
       `  ${'--soft-delete'.padEnd(nameWidth + 2)}make:entity / make:model 加 deleted_at 軟刪`,
       `  ${'--fields'.padEnd(nameWidth + 2)}make 的欄位，例如 title:String,startTime:LocalDateTime（有帶就當完整產出）`,
@@ -198,6 +198,8 @@ function printHelp() {
       '  birc make:entity User --mapper',
       '  birc make:entity User --example',
       '  birc make:entity User --fields title:String,startTime:LocalDateTime',
+      '  birc make:entity Book --migration',
+      '  birc make:entity Book --seed',
       '  birc make Book --fields title:String,author:String --migration --seed',
       '  birc make:entity User --force',
       '  birc make:model Flight --migration',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "birc-generator",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Spring Boot 4 CRUD scaffold generator built on Plop.js",
   "license": "MIT",
   "author": "lucashsu95",

package/plopfile.js

@@ -1212,13 +1212,15 @@ module.exports = function (plop) {
   });
 
   plop.setGenerator('make:entity', {
-    description: '產生 Entity 與 DAO；--dto / --mapper 加 DTO，--soft-delete 加軟刪',
+    description: '產生 Entity 與 DAO；--migration / --seed / --dto / --mapper / --soft-delete',
     prompts: [entityNamePrompt, fieldsPrompt],
     actions(data) {
-      const actions = makeEntityActions(data);
+      const extras = includeModelMigration(data) || includeModelSeed(data);
+      const actions = makeEntityActions(data, { skipIfExists: extras });
       if (includeMapperWithEntity(data)) {
-        return actions.concat(makeMapperActions(data));
+        actions.push(...makeMapperActions(data));
       }
+      appendMakeSqlActions(actions, data);
       return actions;
     }
   });

package/project-docs/PROJECT.md.hbs

@@ -58,7 +58,7 @@ DB → Entity → Mapper → XxxResponse → Result<T>
 ## 統一規範
 
 - 例外丟 `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`。`make` 也可加 `--migration` / `--seed`。`make:seeder BookSeeder` 生 Java Seeder。`--soft-delete` 用 Hibernate `@SoftDelete` 的 `deleted_at`，查詢自動排除已刪；不要自寫 `@SQLDelete`。預設是初稿，完整範例加 `--example` 或 `--fields`。`make:migration create_{table}_table` 讀對應 Entity 欄位寫進 SQL。`--seed` 生 Java Seeder，用 DAO 塞資料；`birc seed` 才執行。清空資料庫用 `birc db:wipe`。不要複製其他 Entity 的程式碼來改名。
+- 整組骨架用 `birc make`；單層用 `birc make:entity` / `make:model` / `make:mapper` / `make:service` / `make:controller` / `make:exception`。`make:entity` 只生 Entity 與 DAO；`--migration` / `--seed` 同 `make:model`（已有 Entity 就跳過，只補 SQL / Seeder）。`--dto` 與 `--mapper` 一併生 Mapper 與 DTO。`make:model` 可加 `--migration` / `--seed` / `--controller`。`make` 也可加 `--migration` / `--seed`。`make:seeder BookSeeder` 生 Java Seeder。`--soft-delete` 用 Hibernate `@SoftDelete` 的 `deleted_at`，查詢自動排除已刪；不要自寫 `@SQLDelete`。預設是初稿，完整範例加 `--example` 或 `--fields`。`make:migration create_{table}_table` 讀對應 Entity 欄位寫進 SQL。`--seed` 生 Java Seeder，用 DAO 塞資料；`birc seed` 才執行。清空資料庫用 `birc db:wipe`。不要複製其他 Entity 的程式碼來改名。
 - 欄位驗證用專案內 `validation/ValidGroup`。CRUD 用 `Create` / `Update`。`Delete` 給「刪除還要帶原因、確認碼、樂觀鎖 version」的 body。`Submit` 給草稿可少填、送審要全填（活動送審就是這組）。Controller 的 `@Validated` 與欄位 `groups` 對同一組。
 - email / sso / oauth / validGroup 用 `birc add`，不要從別的專案抄設定。
 - 格式化走 Spotless（`./gradlew spotlessApply`），不要另裝 Checkstyle。

package/test.md

@@ -35,7 +35,7 @@
 - CLI dest：檔落在呼叫者目錄，不是 generator repo。
 - 產出 Java 沒有 `tw.edu.ntub.birc.starter` / `birc-spring-boot-starter`。
 - `make:entity --dto` / `--mapper` 與 `make:mapper` 同一組 Mapper + DTO；預設 `make:entity` 不生它們。
-- `make --fields --migration --seed` 寫 CREATE TABLE 與 Java `XxxSeeder`，不生 seed SQL；`make:model --migration` 的表名跟 Entity `@Table` 一致。
+- `make --fields --migration --seed` 寫 CREATE TABLE 與 Java `XxxSeeder`，不生 seed SQL；`make:model --migration` 的表名跟 Entity `@Table` 一致。已有 Entity 時 `make:entity --migration` / `--seed` 跳過 Java，只補 CREATE TABLE / `XxxSeeder`。
 - `make:seeder` / `--seed` 讀既有 Entity 欄位寫進 `setXxx`；沒有欄位時 `run()` 是空的。`make:seeder BookSeeder` 生 `BookSeeder.java`，不是 `BookSeederSeeder`。
 - `make:migration create_{table}_table` 讀既有 Entity 欄位寫進 SQL；找不到 Entity 時仍只有 `id`。
 - `--soft-delete` 的 Entity 用 `deleted_at` + `SoftDeleteType.TIMESTAMP`；沒加 flag 的 Entity / migration 沒有這欄。