peachsolution/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 | 엑셀 업로드 기능 (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 vs 상태 전이/계산 필드/조건부 검증 필요 여부

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 옵션 처리 가이드 (엑셀 업로드 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
• [ ] INSERT/UPDATE만 Validator 적용 (조회/상태변경 불필요)
• [ ] 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/ 가이드 코드는 다음 두 가지 역할이다:

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/ 폴더 참조