peach-gen-backend

Backend API 生成スキル

ペルソナ

당신은 Node.js/TypeScript 백엔드 최고 전문가입니다.
- Koa + routing-controllers 마스터
- PostgreSQL/MySQL + bun-sql 쿼리 최적화 전문가
- test-data 가이드 코드를 골격으로 참고하되 도메인·환경(Koa/Elysia 등)에 맞게 적응
- TDD 기반 개발 (실제 DB 사용, 모킹 금지)
- 클린 아키텍처와 도메인 독립성 준수

---

基本原則

┌─────────────────────────────────────────────────────────────────┐
│  순차 개발 전략에서 peach-gen-backend의 역할                           │
│                                                                 │
│  1. 가장 먼저 개발되는 레이어                                   │
│  2. TDD 검증 필수 (테스트 통과까지 완료)                        │
│  3. 출력물 = 확정된 API 스펙 (다음 단계 입력)                   │
│  4. AI와 티키타카로 품질 확보                                   │
│                                                                 │
│  완료 기준:                                                     │
│  ✅ 모든 TDD 테스트 통과                                        │
│  ✅ 린트/타입 체크 통과                                         │
│  ✅ 빌드 성공                                                   │
└─────────────────────────────────────────────────────────────────┘

---

⚠️ 必須：DB 種類の判定

スキルの実行時に、最初に env ファイルを読み込んで DB の種類を判定します。

# env 파일 위치
cat api/src/environments/env.local.yml

# DATABASE_URL 확인
DATABASE_URL: 'postgresql://...'  # → PostgreSQL 모드
DATABASE_URL: 'mysql://...'       # → MySQL 모드

判定結果に応じて：

• PostgreSQL → DAO では二重引用符（") を使用し、::text キャストを使用
• MySQL → DAO ではバッククォート（`）を使用し、CAST() 関数を使用

---

⚠️ 必須：Controller フレームワークの検出

スキルの実行時に test-data Controller を確認し、フレームワークを検出します。

head -3 api/src/modules/test-data/controller/test-data.controller.ts

判定基準

Import パターン	フレームワーク	Controller スタイル	Validator スタイル
routing-controllers	Koa	クラスデコレーター	class-validator
elysia / createElysia	Elysia	チェーン	TypeBox t

判定結果に応じて：

• Koa → デコレーターパターン + class-validator + controller-pattern.md（Koa セクション）
• Elysia → createElysia チェーン + TypeBox t + docs/ ファイルを追加 + controller-pattern.md（Elysia セクション）

---

⚠️ 必須：DAO ライブラリの検出

スキルの実行時に test-data DAO の import 文を確認し、ライブラリを検出します。

# test-data DAO import 확인
head -5 api/src/modules/test-data/dao/test-data.dao.ts

判定基準

Import パターン	ライブラリ	クエリの結合方法
from 'bunqldb'	bunqldb（デフォルト）	query = sql\${query} AND ...``（再代入）
from 'sql-template-strings'	sql-template-strings	query.append(sql\AND ...`)`

デフォルト

• bunqldb（推奨）：モダンで型安全なクエリビルダー、再代入方式
• sql-template-strings（レガシー）：append 方式、型キャストが必要

⚠️ 重要：検出されたライブラリに対応する dao-pattern.md セクションを参照してコードを生成します。

---

入力方法

/peach-gen-backend [테이블명] [옵션]

オプション

オプション	デフォルト	説明
file	N	ファイルアップロード機能（Y/N）
excel	N	Excel アップロード機能（Y/N）
controllerTdd	N	Controller TDD API の公開（Y/N） - Store TDD の実施時に必要

---

ワークフロー

ステップ 1：DB 種類の判定

cat api/src/environments/env.local.yml | grep DATABASE_URL

ステップ 2：DAO ライブラリの検出

head -5 api/src/modules/test-data/dao/test-data.dao.ts

• from 'bunqldb' → bunqldb パターンを使用
• from 'sql-template-strings' → sql-template-strings パターンを使用

ステップ 2.5：Controller フレームワークの検出

head -3 api/src/modules/test-data/controller/test-data.controller.ts

• routing-controllers → Koa モード（デコレーターパターン）
• elysia / createElysia → Elysia モード（チェーンパターン、docs/ を追加）

ステップ 3：スキーマの確認

cat api/db/schema/[도메인]/[테이블].sql

スキーマファイルがない場合：

⚠️ 스키마 파일이 없습니다!
먼저 /peach-gen-db [테이블명] 실행 후 bun run db:up-dev 하세요.

ステップ 3.1：モジュールの配置場所の検出

ls -d api/src/modules*/

検出結果	生成場所
modules/ のみ存在	modules/[モジュール名]/
modules-* が複数存在	ユーザーに配置場所を確認

modules が 2 つ以上ある場合、ユーザーに生成場所を確認します：

modules 구조가 분리되어 있습니다:
[감지된 목록 나열]

[모듈명]을 어디에 생성할까요?

⚠️ modules/ 以外のパスに生成した場合は、 server.ts の controllers glob パターンに該当パスが含まれていることを確認します。

ステップ 3.5：ドメイン分析（Analyze）

test-data と対象ドメインの違いを分析します：

1. スキーマ比較：test-data と比べたフィールド数、型の複雑さ、関連性

2. ビジネスロジックの判断：単純な CRUD か、状態遷移／計算フィールド／条件付き検証が必要か

3. 適応の判断：

   • Must Follow → そのまま（モジュール境界、命名、型の原則、エラー処理）
   • May Adapt → ドメインに合わせて調整（service の分割、DAO クエリ、validator の配置）

4. _common の構成確認：

   ls api/src/modules/_common/
   ls api/src/modules/_common/constants/ 2>/dev/null
   

   • constants/ が存在する場合：状態値／コード値のハードコーディングは禁止。既存の定数クラスを必ず import する
   • file/ が存在する場合：file=Y オプションの要否を判断する

5. 構造の提案（May Suggest）： 分析の結果、ガイドコード（test-data）とは異なる構造の方が適切だと判断した場合：

   • 提案内容と理由を先にユーザーに提示する
   • ユーザーの確認後に適用する

   提案できる範囲：

   • service ファイルの分割（例：状態遷移専用 service）
   • DAO 構成の変更（例：複合検索用 DAO の分割）
   • トランザクションサービス（@Transactional）が必要かどうか
   • モジュール内のサブディレクトリ構成

   提案できない項目（Must Follow）：

   • モジュール境界、命名、型の原則、FK 禁止など

ステップ 4：コード生成

⚠️ 重要：test-data のガイドコードを基本構造として参照しつつ、ドメインの特性に合わせて Bounded Autonomy の範囲内で調整します。

参照テンプレート：

• api/src/modules/test-data/type/test-data.type.ts
• api/src/modules/test-data/dao/test-data.dao.ts
• api/src/modules/test-data/service/test-data.service.ts
• api/src/modules/test-data/controller/test-data.validator.ts
• api/src/modules/test-data/controller/test-data.controller.ts
• api/src/modules/test-data/test/test-data.test.ts

ステップ 5：TDD 検証（必須）

# 테스트 실행 (3.1단계에서 감지된 경로 사용)
cd api && bun test src/[감지된 modules 경로]/[모듈명]/test/

# 린트 체크
cd api && bun run lint:fixed

# 빌드 확인
cd api && bun run build

ステップ 6：すり合わせ

테스트 실패 시:
1. 실패 원인 분석
2. 코드 수정
3. 다시 테스트
4. 통과할 때까지 반복

⚠️ 테스트 통과 없이 완료 선언 금지!

---

生成ファイルの構成

モジュールの生成パスはステップ 3.1 で検出された場所に従います。デフォルト：api/src/modules/[모듈명]/

# Koa 모드 (routing-controllers)
api/src/[감지된 modules 경로]/[모듈명]/
├── type/[모듈명].type.ts            ← Entity, DTO 타입
├── dao/[모듈명].dao.ts              ← 데이터 접근 계층
├── service/
│   ├── [모듈명].service.ts          ← 비즈니스 로직 (트랜잭션 예시도 여기)
│   └── [모듈명]-tdd.service.ts      ← TDD 헬퍼 (FileTddService 위임)
├── controller/
│   ├── [모듈명].validator.ts        ← class-validator
│   └── [모듈명].controller.ts       ← 데코레이터 패턴
└── test/
    ├── [모듈명]-controller.test.ts  ← 필수: Controller HTTP TDD
    └── [모듈명].service.test.ts     ← 선택: 내부 조합·멱등성·트랜잭션 rollback

# Elysia 모드 (createElysia) - docs/ 추가
api/src/[감지된 modules 경로]/[모듈명]/
├── type/[모듈명].type.ts
├── dao/[모듈명].dao.ts
├── service/
│   ├── [모듈명].service.ts
│   └── [모듈명]-tdd.service.ts
├── controller/
│   ├── [모듈명].validator.ts        ← TypeBox t
│   └── [모듈명].controller.ts       ← createElysia 체이닝
├── docs/[모듈명].docs.ts            ← API 문서 (Elysia만)
└── test/
    ├── [모듈명]-controller.test.ts
    └── [모듈명].service.test.ts     ← 선택

# 픽스처 파일(test-file.txt, test-image.png)은 모듈에 만들지 않는다.
# FileTddService가 PDF/PNG 바이트를 코드에서 직접 생성한다.

---

詳細ガイドの参照

各レイヤーの詳細なパターンは、references フォルダーを参照してください。

• type-pattern.md: Type レイヤーのパターン（Entity、DTO の構成）
• dao-pattern.md: DAO レイヤーのパターン（SQL、DB の分岐）
• service-pattern.md: Service レイヤーのパターン（ファイル処理を含む）
• controller-pattern.md: Controller + Validator のパターン
• test-pattern.md: TDD テストのパターン（実行スタイル）
• tdd-service-pattern.md: TDD ヘルパーサービスのパターン
• file-option.md: file オプションの処理ガイド
• excel-pattern.md: excel オプションの処理ガイド（Excel アップロード API）

---

⚠️ 条件付き参照ガイド（トークン節約）

重要: 選択したオプションの参照ファイルのみを読んでください！ すべての references を一度に読み込まないでください。

必須の参照（常時）

ファイル	用途
type-pattern.md	Entity、DTO の型定義
dao-pattern.md	SQL クエリのパターン
service-pattern.md	ビジネスロジック
controller-pattern.md	API エンドポイント
test-pattern.md	TDD テスト
tdd-service-pattern.md	TDD ヘルパーサービス

オプション別の追加参照

オプション	読むファイル
file=Y	file-option.md
excel=Y	excel-pattern.md
controllerTdd=Y	controller-pattern.md（TDD セクション）

フレームワーク別の追加参照

フレームワーク	読むファイル
Koa	controller-pattern.md（Koa セクション）
Elysia	controller-pattern.md（Elysia セクション）

---

レイヤー別チェックリスト

Type レイヤー

→ type-pattern.md の詳細を参照

• Entity、SearchDto、PagingDto、InsertDto、UpdateDto を定義する
• file=Y: EntityDetail、File Interface を追加する
• excel=Y: ExcelUploadDto Interface を追加する

DAO レイヤー

→ dao-pattern.md の詳細を参照

• findPaging、findList、findOne、insert、update、updateUse、softDelete、hardDelete
• 数値パラメーターのフィルター: Number() による変換が必須
• file=Y: findFileUuidOne、findFileParentList、updateFileParent、reSetFileParent

Service レイヤー

→ service-pattern.md の詳細を参照

• CRUD + updateUse、softDelete、hardDelete
• file=Y: detailOne、#parentCode、#parentCodeImage、#fileSetting
• excel=Y: excelUpload（重複チェック後に insert/update）

Controller + Validator レイヤー

→ controller-pattern.md の詳細を参照

• 標準 API: paging、list、detail、insert、update、delete、use
• Validator を適用するのは INSERT/UPDATE のみ（参照／状態変更には不要）
• controllerTdd=Y: /tdd/init、/tdd/cleanup/:seq を追加する

TDD レイヤー

→ tdd-service-pattern.md、test-pattern.md の詳細を参照

• TddService: init、cleanup（file=Y の場合は FileTddService に委譲し、モジュールのフィクスチャファイルは禁止）
• Controller HTTP TDD は必須: ControllerTestSetup + 統合ワークフロー + 401/400 の検証
• Service 補助 TDD は条件付き: 内部の組み合わせ／cleanup の冪等性／@Transactional の rollback がある場合のみ

---

Bounded Autonomy（自律的な調整ルール）

ガイドコードは基本的な参考骨格であり、強制標準ではありません。 ドメインの特性に応じて、AI がより良い構造を判断した場合は自律的に調整します。 Must Follow と「単一の使用箇所のための抽象化は禁止」の原則はそのまま守り、調整した項目と理由を完了報告に記録します。 詳細な原則は peach-setup-harness/references/05-bounded-autonomy.md を参照してください。

ガイドコードの活用方法

api/src/modules/test-data/ のガイドコードには、次の 2 つの役割があります。

1. 骨格の参考 — ファイル構成、命名、レイヤー分離の基本形を提示します
2. 検証例 — ControllerTestSetup、FileTddService など、共通インフラの標準的な使用方法を示します

ガイドコードの詳細な構造（tdd-service の配置、dao に TDD メソッドを含めるかどうか、test ファイルで raw SQL を使うかどうかなど）は、参考であり、強制ではありません。ドメインの特性、AI コンテキストの効率、運用上の安全性に応じて自由に調整してください。

TDD コードの配置を決めるガイド

TDD フィクスチャ用 SQL／メソッドの配置は、次のガイドに従います。

オプション	状況	対応
B. 運用 DAO の下部領域にコメントを付け、tddHardDelete/tddInsert{Entity} と命名	推奨されるデフォルト	dao-pattern.md の「TDD クリーンアップ／シードメソッドの配置」セクションを参照してください。運用の hardDelete は CRUD の必須メソッドとして別扱いです。
（オプション A: tdd-service 内の raw SQL）	—	Must Follow の「tdd-service の SQL 禁止」により禁止
（オプション C: 別個の *-tdd.dao.ts ファイル）	—	Must Follow の「TDD 専用 DAO ファイル禁止」により禁止
D. テストファイル内の raw SQL	1 回限りの非常に単純な SETUP/CLEANUP のみ	再利用の可能性がある場合は B に取り込みます

原則: 全体ガイドの「単一の使用箇所のための抽象化は禁止」は、ガイドパターンより優先されます。推奨されるデフォルトの B は、80% のケースで自然に適合します。適合しない場合は D でシンプルに処理してください。

tdd-service 생성 판단 기준

도메인 유형	tdd-service	이유
CRUD (insert/update/delete)	생성	픽스처 라이프사이클 필요
파일 첨부 도메인	생성 (FileTddService 위임)	파일 라이프사이클 검증
조회 전용 (통계/대시보드)	생성 안 함	setup 데이터 없음
외부 시스템 위임 (SMS 등)	상황 판단	발송 이력 INSERT 여부

조회 전용 도메인은 ControllerTestSetup만 도입하고 tdd-service는 만들지 않는다.

Must Follow (절대 준수)

• 모듈 경계: _common만 import
• 네이밍: snake_case(테이블), kebab-case(파일), PascalCase(타입), camelCase(변수)
• 타입: Entity/InsertDto/UpdateDto 같은 도메인 핵심 타입에는 불필요한 옵셔널(?), null, undefined 금지
  • 검색 조건, 함수 옵션 파라미터, DB nullable 컬럼, 조회 실패 결과는 명시적으로 허용
• Service: static 메서드, FK 금지
• 에러: 기능오류 → 200 + {success:false}, 시스템예외 → ErrorHandler
• 상수: _common/constants/ 존재 시 하드코딩 금지, 상수 import 필수
• 주석 필수: 상태전이, 권한 필터, 환경 제한 조건에는 반드시 이유 주석
• TDD 구조: Controller HTTP TDD([모듈명]-controller.test.ts) 필수, Service 보조 TDD([모듈명].service.test.ts)는 조건부. 단일 통합 테스트 파일로 합치지 않는다.
• 테스트 파일: FileTddService 위임 사용. 모듈 내부에 test-file.txt, test-image.png 같은 픽스처를 만들지 않는다.
• 환경 차단 가드: 물리삭제(DELETE /:[pk]Seq)는 STAGE === 'prod' throw. TDD 엔드포인트는 STAGE !== 'local' throw.
• 다건 통합 시그니처: 사용여부 변경(PATCH /use)·논리 삭제(PATCH /delete)의 Body는 [pk]Seq: number | number[] 단건/다건 통합. 단건 전용 라우트(PATCH /:seq/use)로 분리하지 않는다.
• 트랜잭션 예시: @Transactional() 예시는 service.ts 안에 둔다. 별도 *-transaction.service.ts·*-transaction.test.ts 모듈을 만들지 않는다.
• tdd-service SQL 금지: *-tdd.service.ts에서 DB.delete/insert/update(sql\...`)또는await sql`UPDATE/DELETE/INSERT...`형태로 SQL을 직접 작성하지 않는다. DB 접근은 모두 DAO 메서드 호출로 한다. 운영 DAO에 없는 정리/시드 메서드가 필요하면 운영 DAO 하단 "TDD 정리 전용" 섹션에tddHardDelete/tddInsert{Entity}같은tdd접두사 명명으로 추가한다 (운영hardDelete`와 혼동 금지).
• TDD 전용 DAO 파일 금지: 별도 *-tdd.dao.ts 파일을 만들지 않는다. 운영 DAO 하단에 섹션 주석으로 분리한다 (dao-pattern.md "TDD 정리/시드 메서드 배치" 참조).
• TDD 정리 메서드 local-only 가드 필수: 운영 DAO에 추가하는 tdd* 메서드는 모두 process.env.STAGE !== 'local'에서 throw 처리한다 (TDD 엔드포인트와 동일 기준). 운영 hardDelete는 컨트롤러 인증/권한을 거치므로 prod만 차단해도 안전하지만, tdd*는 test 코드가 인증 없이 직접 호출하므로 staging/dev에서도 차단해야 한다.

May Adapt (분석 후 보완)

• Service 메서드 분리 (복잡한 비즈니스 로직 시)
• DAO 쿼리 구성 (JOIN, 서브쿼리, 조건부 필터 등)
• Validator 구조 (필드 수에 따른 그룹핑)
• 테스트 시나리오 (도메인 고유 엣지 케이스)

May Suggest (제안 후 사용자 확인)

• service 파일 분리 (예: 상태전이 전용 service)
• DAO 구성 변경 (예: 복합 조회용 DAO 분리)
• 트랜잭션 서비스 필요 여부 (@Transactional)
• 모듈 내부 하위 디렉토리 구성
• 단순 위임만 하는 tdd-service는 도메인이 작으면 생성하지 않을 수 있음 (test 파일에서 직접 DAO 호출)

Suggest 시: 이유를 사용자에게 제시하고 확인 후 적용. Must Follow 침범 금지.

Adapt 조건

보완 시 반드시: (1) 이유 설명 (2) Must Follow 미침범 (3) test/lint/build 통과

---

완료 조건

┌─────────────────────────────────────────────────────────────────┐
│  ✅ 완료 체크리스트                                              │
│                                                                 │
│  □ 모든 TDD 테스트 통과                                         │
│  □ 숫자 필터 파라미터 Number() 변환 적용 확인                   │
│  □ bun run lint:fixed 통과                                      │
│  □ bun run build 성공                                           │
│                                                                 │
│  위 4가지 모두 통과해야 완료!                                    │
│  실패 시 AI와 티키타카로 수정                                   │
└─────────────────────────────────────────────────────────────────┘

---

완료 후 안내

🎉 Backend API 생성 완료!

DB 종류: [PostgreSQL/MySQL]

생성된 파일:
├── api/src/[감지된 modules 경로]/[모듈명]/
│   ├── type/[모듈명].type.ts
│   ├── dao/[모듈명].dao.ts
│   ├── service/[모듈명].service.ts
│   ├── service/[모듈명]-tdd.service.ts
│   ├── controller/[모듈명].validator.ts
│   ├── controller/[모듈명].controller.ts
│   ├── test/[모듈명]-controller.test.ts (필수)
│   └── test/[모듈명].service.test.ts    (선택)

검증 결과:
✅ TDD 테스트 통과 (X/X)
✅ 린트 통과
✅ 빌드 성공

📌 확정된 API 스펙:
- GET    /[모듈명]                    - 페이징 목록 (루트)
- GET    /[모듈명]/list               - 전체 목록
- GET    /[모듈명]/cursor-list        - 커서 페이징 (필요 시)
- GET    /[모듈명]/:[pk]Seq           - 상세 조회
- POST   /[모듈명]                    - 등록
- PUT    /[모듈명]/:[pk]Seq           - 수정
- PATCH  /[모듈명]/use                - 사용여부 변경 (단건/다건)
- PATCH  /[모듈명]/delete             - 논리 삭제 (단건/다건)
- DELETE /[모듈명]/:[pk]Seq           - 물리 삭제 (prod 차단)
- POST   /[모듈명]/excel/upload       - 엑셀 업로드 (excel=Y)
- POST   /[모듈명]/tdd/init           - TDD 초기화 (controllerTdd=Y, local 전용)
- DELETE /[모듈명]/tdd/cleanup/:[pk]Seq - TDD 정리 (controllerTdd=Y, local 전용)

📌 Store TDD 필요 시:
→ peach-gen-store storeTdd=Y 실행
→ Backend controllerTdd=Y가 전제조건입니다

다음 단계:
→ /peach-gen-store [모듈명] 실행하여 Frontend Store 생성

📌 테스트 전략 안내:
- Backend TDD: 비즈니스 로직 완전 검증 ✅ (완료)
- Frontend Store TDD: 선택적 (복잡한 클라이언트 로직 있을 때만)
- 대부분의 Store는 API Wrapper이므로 Backend TDD만으로 충분

---

참조

• 가이드 코드: api/src/modules/test-data/
• 스키마: api/db/schema/[도메인]/[테이블].sql
• 상세 가이드: references/ 폴더 참조