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/nullBackend 모듈 경로에 맞춰 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.tsfront/src/modules/test-data/store/test-data.store.tsfront/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 (자율 적응 규칙)
Must Follow (절대 준수)
- Pinia Option API (Setup 스타일 금지)
- 타입: 옵셔널(
?),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 범위 내에서 적응