peach-gen-store

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Frontend Store 생성 스킬

Frontend Store生成技能

페르소나

角色

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

你是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的作用                             │
│                                                                 │
│  前提条件：Backend API开发完成（TDD通过）                       │
│                                                                 │
│  1. 基于Backend API规范生成代码                                │
│  2. 必须经过TDD验证（API对接测试）                             │
│  3. 输出物 = 已确认的Store接口（作为下一阶段输入）               │
│  4. 与AI迭代调优保障代码质量                                   │
│                                                                 │
│  完成标准：                                                     │
│  ✅ 必须通过vue-tsc类型检查                                     │
│  ⚪ TDD测试通过（仅存在复杂客户端逻辑时需要）                  │
└─────────────────────────────────────────────────────────────────┘

입력 방식

调用方式

bash

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

bash

/peach-gen-store [表名] [选项]

옵션

选项

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

选项	默认值	说明
file	N	文件上传功能 (Y/N)
storeTdd	N	生成Store TDD方法 (Y/N) - 需要Backend controllerTdd=Y

워크플로우

工作流

1단계: Backend API 확인

第1步：确认Backend API

bash

undefined

bash

undefined

Backend 파일 존재 확인

确认Backend文件是否存在

ls api/src/modules/[모듈명]/

ls api/src/modules/[模块名]/

API 스펙 확인 (Type 파일)

查看API规范（Type文件）

cat api/src/modules/[모듈명]/type/[모듈명].type.ts


Backend가 없으면:

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

undefined

cat api/src/modules/[模块名]/type/[模块名].type.ts


如果不存在Backend：

⚠️ 不存在Backend API！请先执行/peach-gen-backend [表名]。

undefined

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

1.5步：领域分析（Analyze）

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

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

对比分析Backend API类型与test-data Store：

API规范对比：对比test-data的端点数量、响应结构、特殊方法
判断状态复杂度：是否需要简单CRUD Store，还是需要多列表/筛选状态/派生状态
适配决策：
- 必须遵守 → 完全遵循（Pinia Option API、类型规则、模块边界）
- 可调整 → 适配领域特性（新增状态字段、拆分方法）

2단계: 코드 생성

第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

参考模板（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 검증 (필수)

第3步：TDD验证（必填）

bash

undefined

bash

undefined

타입 체크

类型检查

cd front && bunx vue-tsc --noEmit

테스트 실행 (있는 경우)

执行测试（如果有）

cd front && bun test src/modules/[모듈명]/test/

undefined

cd front && bun test src/modules/[模块名]/test/

undefined

4단계: 티키타카

第4步：迭代调优

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

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

出现类型错误或测试失败时：
1. 分析错误原因
2. 修改代码
3. 重新验证
4. 重复直到通过

⚠️ 禁止未通过类型检查就声明完成！

생성 파일 구조

生成文件结构

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

front/src/modules/[模块名]/
├── type/[模块名].type.ts    ← Entity、DTO类型
├── store/[模块名].store.ts  ← Pinia Store
└── test/[模块名].test.ts    ← TDD测试（可选）

레이어별 체크리스트

各层检查清单

Type 레이어

Type层

Store 레이어

Store层

State

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

listData: ListItem[]（列表数据）
listTotalRow: number（总条数）
detailData: Entity | null（详情数据）

Actions (상세)

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)
```

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인 경우만)

TDD方法（仅storeTdd=Y时需要）

→ 하단 "Store TDD" 섹션 참조

→ 参考下方「Store TDD」章节

파일 기능 (file=Y)

文件功能（file=Y）

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

uploadFileLocal（本地文件上传）
uploadFileS3（S3文件上传）
getDownloadUrl（获取下载地址）

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

TDD测试（仅storeTdd=Y时需要）

→ 하단 "Store TDD" 섹션 참조

→ 参考下方「Store TDD」章节

패턴 규칙

模式规则

typescript

// ✅ 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('[모듈명]', () => {
  // ...
});

typescript

// ✅ 推荐使用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选项处理

file=N (기본)

file=N（默认）

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

Store：排除文件相关函数
- uploadFileLocal ❌
- uploadFileS3 ❌
- getDownloadUrl ❌

file=Y

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

Store：包含文件相关函数

```
uploadFileLocal
```
✅
```
uploadFileS3
```
✅
```
getDownloadUrl
```
✅

Type：新增File接口

Bounded Autonomy (자율 적응 규칙)

有限自治（自适应规则）

Must Follow (절대 준수)

必须遵守

Pinia Option API (Setup 스타일 금지)
타입: 옵셔널(
```
?
```
),
```
null
```
,
```
undefined
```
금지
모듈 경계:
```
_common
```
만 import
Store 표준 상태:
```
listData
```
,
```
listTotalRow
```
,
```
detailData
```

必须使用Pinia Option API（禁止Setup风格）
类型：禁止使用可选符(
```
?
```
)、
```
null
```
、
```
undefined
```
模块边界：仅允许import
```
_common
```
模块
Store标准状态：必须包含
```
listData
```
、
```
listTotalRow
```
、
```
detailData
```

May Adapt (분석 후 보완)

可调整（分析后补充）

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

新增状态字段（领域专属筛选器、多列表）
方法拆分逻辑（复杂数据转换逻辑）
错误处理的具体实现

Adapt 조건

调整条件

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

补充调整时必须满足：(1) 说明调整原因 (2) 不违反必须遵守规则 (3) 可通过vue-tsc检查

완료 조건

完成条件

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

┌─────────────────────────────────────────────────────────────────┐
│  ✅ 完成检查清单                                                │
│                                                                 │
│  □ 必须通过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 생성

🎉 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인 경우만)

Store TDD（仅storeTdd=Y时需要）

→ test-pattern.md 상세 참조

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

→ 参考test-pattern.md获取详情

前提条件：需要Backend controllerTdd=Y 大部分Store都是API包装层，无需单独做TDD，Backend TDD即可覆盖验证需求。

TDD Actions

TDD方法

initTdd (TDD 데이터 생성) -
```
useApi().post('/[모듈명]/tdd/init')
```

cleanupTdd (TDD 정리) -

useApi().delete('/[모듈명]/tdd/cleanup/' + seq)

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

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 옵션 처리 가이드

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

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

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

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

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

重要：仅读取已选选项对应的参考文件即可！请勿一次性加载所有references文件。

필수 참조 (항상)

必看参考（所有场景）

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

文件	用途
store-pattern.md	Pinia Store结构
type-pattern.md	Entity、DTO类型定义

옵션별 추가 참조

选项对应额外参考

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

选项	需要读取的文件
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 범위 내에서 적응

示例代码（必看）：
```
front/src/modules/test-data/
```
Backend类型文件：
```
api/src/modules/[模块名]/type/
```

⚠️ 重要：以test-data示例代码为基础骨架，可在有限自治范围内适配领域特性进行调整。