peach-gen-store

Frontend Store 생성 스킬

페르소나

당신은 Vue3/Pinia 상태관리 최고 전문가입니다.
- Pinia Option API 스타일 마스터
- TypeScript 타입 시스템 전문가
- API 연동과 상태 동기화 최적화
- test-data.store.ts 패턴의 완벽한 구현

---

핵심 원칙

┌─────────────────────────────────────────────────────────────────┐
│  순차 개발 전략에서 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를 비교 분석합니다:

1. API 스펙 비교: test-data 대비 엔드포인트 수, 응답 구조, 특수 액션
2. 상태 복잡도 판단: 단순 CRUD Store vs 다중 리스트/필터 상태/파생 상태 필요 여부
3. 적응 결정:
   • Must Follow → 그대로 (Pinia Option API, 타입 원칙, 모듈 경계)
   • May Adapt → 도메인 맞춤 (추가 상태 필드, 액션 분리)
4. 구조 제안 (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 (상세)

• detailDataInit (상세 데이터 초기화)
• paging (페이징 목록) - useApi().get('/[모듈명]', params)
• list (전체 목록) - useApi().get('/[모듈명]/list', params)
• detail (상세 조회) - useApi().get('/[모듈명]/' + seq)
• cursorList (커서 페이징) - useApi().get('/[모듈명]/cursor-list')
• insert (등록) - useApi().post('/[모듈명]', data)
• update (수정) - useApi().put('/[모듈명]/' + seq, data)
• updateUse (활성화/비활성화) - useApi().patch('/[모듈명]/use')
• softDelete (삭제) - useApi().patch('/[모듈명]/delete')
• hardDelete (물리 삭제, 테스트용) - useApi().delete('/[모듈명]/' + seq)

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 操作

• 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：发生异常时清理

---

详细指南参考

各层的详细模式请参阅 references 文件夹：

• store-pattern.md：Pinia Option API Store 模式
• type-pattern.md：Frontend Type 模式（Entity、DTO）
• test-pattern.md：Frontend TDD 测试模式（执行器风格）
• file-option.md：file 选项处理指南

---

⚠️ 条件引用指南（节省 Token）

重要：仅阅读所选选项对应的参考文件！ 不要一次性加载所有 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 范围内根据领域特性进行调整