┌─────────────────────────────────────────────────────────────────┐
│  순차 개발 전략에서 peach-gen-store의 역할                             │
│                                                                 │
│  전제조건: Backend API 완료 (TDD 통과)                          │
│                                                                 │
│  1. Backend API 스펙 기반으로 생성                              │
│  2. TDD 검증 필수 (API 연동 테스트)                             │
│  3. 출력물 = 확정된 Store 인터페이스 (다음 단계 입력)           │
│  4. AI와 티키타카로 품질 확보                                   │
│                                                                 │
│  완료 기준:                                                     │
│  ✅ vue-tsc 타입 체크 통과 (필수)                               │
│  ⚪ TDD 테스트 통과 (복잡한 클라이언트 로직 있을 때만)          │
└─────────────────────────────────────────────────────────────────┘

입력 방식

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

옵션

옵션	기본값	설명
file	N	파일 업로드 기능 (Y/N)
storeTdd	N	Store TDD 액션 생성 (Y/N) - Backend controllerTdd=Y 필요

워크플로우

1단계: Backend API 확인 + 모듈 위치 감지

# Backend 모듈 위치 감지 (modules-* 분리 구조 대응)
ls -d api/src/modules*/[모듈명]/ 2>/dev/null

# API 스펙 확인 (Type 파일)
cat api/src/modules*/[모듈명]/type/[모듈명].type.ts 2>/dev/null

# Frontend 모듈 구조 확인
ls -d front/src/modules*/

# Frontend 상수 확인
ls front/src/modules/_common/constants/ 2>/dev/null

Backend 모듈 경로에 맞춰 Frontend 대응 경로에 생성합니다:

api/src/modules/[모듈명]/ → front/src/modules/[모듈명]/
api/src/modules-domain/[모듈명]/ → front/src/modules-domain/[모듈명]/
api/src/modules-external/[모듈명]/ → front/src/modules-domain/[모듈명]/ (프론트는 domain으로 통합)

_common/constants/ 존재 시 프론트에서도 상수 활용을 고려합니다.

Backend가 없으면:

⚠️ Backend API가 없습니다!
먼저 /peach-gen-backend [테이블명] 실행하세요.

1.5단계: 도메인 분석 (Analyze)

Backend API 타입과 test-data Store를 비교 분석합니다:

API 스펙 비교: test-data 대비 엔드포인트 수, 응답 구조, 특수 액션
상태 복잡도 판단: 단순 CRUD Store vs 다중 리스트/필터 상태/파생 상태 필요 여부
적응 결정:
- Must Follow → 그대로 (Pinia Option API, 타입 원칙, 모듈 경계)
- May Adapt → 도메인 맞춤 (추가 상태 필드, 액션 분리)
구조 제안 (May Suggest): 분석 결과 가이드코드와 다른 구조가 더 적합하면 사용자에게 제안:
- Store 파일 분리 (예: 조회 전용 Store + 관리 전용 Store)
- 파생 상태(computed) 구조 제안
- 사용자 확인 후 적용. Must Follow 침범 금지.

2단계: 코드 생성

참조 템플릿 (test-data):

front/src/modules/test-data/type/test-data.type.ts
front/src/modules/test-data/store/test-data.store.ts
front/src/modules/test-data/test/test-data.test.ts

3단계: TDD 검증 (필수)

# 타입 체크
cd front && bunx vue-tsc --noEmit

# 테스트 실행 (있는 경우)
cd front && bun test src/modules/[모듈명]/test/

4단계: 티키타카

타입 에러 또는 테스트 실패 시:
1. 에러 원인 분석
2. 코드 수정
3. 다시 검증
4. 통과할 때까지 반복

⚠️ 타입 체크 통과 없이 완료 선언 금지!

생성 파일 구조

front/src/[감지된 modules 경로]/[모듈명]/
├── type/[모듈명].type.ts    ← Entity, DTO 타입
├── store/[모듈명].store.ts  ← Pinia Store
└── test/[모듈명].test.ts    ← TDD 테스트 (선택적)

모듈 생성 경로는 1단계에서 감지된 Backend 대응 경로를 따릅니다. 기본값: front/src/modules/[모듈명]/

레이어별 체크리스트

Type 레이어

Entity Interface (백엔드와 동일)
ListItem Interface (목록용, nIndex 추가)
SearchDto Interface (검색 파라미터)
PagingDto Interface (페이징, sortData 추가)
InsertDto Interface (등록용)
UpdateDto Interface (수정용)
File Interface (file=Y인 경우)

Store 레이어

State

listData: ListItem[] (목록 데이터)
listTotalRow: number (전체 개수)
detailData: Entity | null (상세 데이터)

Actions (상세)

TDD Operations (storeTdd=Y인 경우만)

→ 하단 "Store TDD" 섹션 참조

파일 기능 (file=Y)

uploadFileLocal (로컬 파일 업로드)
uploadFileS3 (S3 파일 업로드)
getDownloadUrl (다운로드 URL)

TDD 테스트 (storeTdd=Y인 경우만)

→ 하단 "Store TDD" 섹션 참조

패턴 규칙

// ✅ Pinia Option API 스타일 (권장)
export const use[모듈명]Store = defineStore('[모듈명]', {
  state: () => ({
    listData: [] as ListItem[],
    listTotalRow: 0,
    detailData: null as Entity | null,
  }),
  actions: {
    async paging(params: PagingDto) {
      const { $api } = useNuxtApp();
      const res = await $api.get('[모듈명]/paging', { params });
      if (res.value?.data) {
        this.listData = res.value.data.list;
        this.listTotalRow = res.value.data.totalRow;
      }
      return res;
    },
    // ...
  },
});

// ❌ Setup 스타일 (사용 금지)
export const use[모듈명]Store = defineStore('[모듈명]', () => {
  // ...
});

file 옵션 처리

file=N (기본)

Store: 파일 관련 함수 제외
- uploadFileLocal ❌
- uploadFileS3 ❌
- getDownloadUrl ❌

file=Y

Store: 파일 관련 함수 포함
- uploadFileLocal ✅
- uploadFileS3 ✅
- getDownloadUrl ✅
Type: File 인터페이스 추가

Bounded Autonomy (자율 적응 규칙)

가이드 코드는 기본 참고 골격이며 강제 표준이 아니다. 도메인 특성에 따라 AI가 더 나은 구조를 판단하면 자율 조정한다. Must Follow와 "단일 사용처 추상화 금지" 원칙은 그대로 지키고, 조정한 항목과 이유는 완료 보고에 기록한다. 상세 원칙은 peach-setup-ui-proto/references/04-bounded-autonomy.md (Frontend) 또는 peach-setup-harness/references/05-bounded-autonomy.md (Backend) 참조.

Must Follow (절대 준수)

Pinia Option API (Setup 스타일 금지)
타입: Entity/InsertDto/UpdateDto 같은 도메인 핵심 타입에는 불필요한 옵셔널(?), null, undefined 금지
- 검색 조건, 함수 옵션 파라미터, 프레임워크 상태 표현은 명시적으로 허용
모듈 경계: _common만 import
Store 표준 상태: listData, listTotalRow, detailData

May Adapt (분석 후 보완)

추가 상태 필드 (도메인 고유 필터, 다중 리스트)
액션 분리 방식 (복잡한 데이터 변환 로직)
에러 핸들링 세부 구현

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

Store 파일 분리 (예: 조회 전용 + 관리 전용)
파생 상태(computed) 구조 제안
복합 필터 상태 설계

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

Adapt 조건

보완 시 반드시: (1) 이유 설명 (2) Must Follow 미침범 (3) vue-tsc 통과

완료 조건

┌─────────────────────────────────────────────────────────────────┐
│  ✅ 완료 체크리스트                                              │
│                                                                 │
│  □ bunx vue-tsc --noEmit 통과 (필수)                             │
│  □ TDD 테스트 통과 (storeTdd=Y인 경우만)                        │
│                                                                 │
│  위 조건 모두 통과해야 완료!                                     │
│  실패 시 AI와 티키타카로 수정                                   │
└─────────────────────────────────────────────────────────────────┘

완료 후 안내

🎉 Frontend Store 생성 완료!

생성된 파일:
├── front/src/[감지된 modules 경로]/[모듈명]/
│   ├── type/[모듈명].type.ts
│   └── store/[모듈명].store.ts

검증 결과:
✅ 타입 체크 통과

📌 확정된 Store 인터페이스:
- use[모듈명]Store()
  - state: listData, listTotalRow, detailData
  - actions: paging, list, detail, insert, update, updateUse, softDelete

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

Store TDD (storeTdd=Y인 경우만)

→ test-pattern.md 상세 참조

전제조건: Backend controllerTdd=Y 필요 대부분의 Store는 API Wrapper이므로 TDD 불필요. Backend TDD로 충분.

TDD Actions

initTdd (TDD 데이터 생성) - useApi().post('/[모듈명]/tdd/init')
cleanupTdd (TDD 정리) - useApi().delete('/[모듈명]/tdd/cleanup/' + seq)

통합 워크플로우 테스트

beforeAll: VitestSetup.initializeTestEnvironment(), sign()
it('통합 워크플로우'): 실행기 스타일 단일 테스트
1. TDD 데이터 생성 (initTdd)
2. 상세 조회 (detail)
3. 데이터 수정 (update)
4. 사용여부 변경 (updateUse)
5. 리스트/페이징 조회
6. 커서 페이징 (cursorList)
7. 파일 업로드/수정 (file=Y)
8. 논리적 삭제 (softDelete)
9. TDD 물리 삭제 (cleanupTdd)
finally: 예외 시 cleanup

상세 가이드 참조

각 레이어별 상세 패턴은 references 폴더 참조:

store-pattern.md: Pinia Option API Store 패턴
type-pattern.md: Frontend Type 패턴 (Entity, DTO)
test-pattern.md: Frontend TDD 테스트 패턴 (실행기 스타일)
file-option.md: file 옵션 처리 가이드

⚠️ 조건부 참조 가이드 (토큰 절약)

중요: 선택된 옵션의 참조 파일만 읽으세요! 모든 references를 한 번에 로드하지 마세요.

필수 참조 (항상)

파일	용도
store-pattern.md	Pinia Store 구조
type-pattern.md	Entity, DTO 타입 정의

옵션별 추가 참조

옵션	읽어야 할 파일
file=Y	file-option.md
storeTdd=Y	test-pattern.md

참조

가이드 코드 (필수): front/src/modules/test-data/
Backend Type: api/src/modules/[모듈명]/type/

⚠️ 중요: test-data 가이드 코드를 기준 골격으로 참조하되, 도메인 특성에 맞게 Bounded Autonomy 범위 내에서 적응

peach-gen-store

Frontend Store 생성 스킬

페르소나

핵심 원칙