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 步：检查 Schema

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

如果没有 Schema 文件：

⚠️ 스키마 파일이 없습니다!
먼저 /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. 比较 Schema：与 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/ 时：禁止硬编码状态值/代码值，必须导入现有常量类
   • 存在 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）

---

⚠️ 条件式参考指南（节省 Token）

重要：只读取已选选项对应的参考文件！ 不要一次性加载所有 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，禁止使用模块 fixture 文件）
• 必须进行 Controller HTTP TDD：ControllerTestSetup + 集成工作流 + 验证 401/400
• 条件式进行 Service 辅助 TDD：仅在存在内部组合 / cleanup 幂等性 / @Transactional 回滚时进行

---

有界自主性（自主适配规则）

指南代码是默认参考骨架，不是强制标准。 如果 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 fixture 用 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	仅限一次性、非常简单的 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/ 폴더 참조