@blastlabs/utils 1.13.0 → 1.15.0

package/bin/init-ai-rules.cjs

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const path = require("path");
+
+// 규칙 카테고리별 정의
+const RULE_CATEGORIES = {
+  // 기본 규칙 (항상 포함)
+  base: [
+    "typescript-standards.mdc",
+    "react-hooks.mdc",
+    "testing.mdc",
+    "documentation.mdc",
+    "git-commit.mdc",
+  ],
+  // FSD 아키텍처 규칙
+  fsd: [
+    "fsd-architecture.mdc",
+    "entities-layer.mdc",
+    "shared-layer.mdc",
+    "views-layer.mdc",
+  ],
+};
+
+function parseArgs(args) {
+  const options = {
+    fsd: false,
+    all: false,
+    list: false,
+    help: false,
+  };
+
+  for (const arg of args) {
+    if (arg === "--help" || arg === "-h") {
+      options.help = true;
+    } else if (arg === "--fsd") {
+      options.fsd = true;
+    } else if (arg === "--all") {
+      options.all = true;
+    } else if (arg === "--list" || arg === "-l") {
+      options.list = true;
+    }
+  }
+
+  return options;
+}
+
+function showHelp() {
+  console.log("@blastlabs/utils - Cursor Rules Installer\n");
+  console.log("프로젝트에 .cursor/rules/ 규칙 파일들을 설치합니다.\n");
+  console.log("사용법: npx @blastlabs/utils init-rules [options]\n");
+  console.log("Options:");
+  console.log("  --fsd         FSD 아키텍처 규칙 포함");
+  console.log("  --all         모든 규칙 설치 (base + fsd)");
+  console.log("  --list, -l    설치 가능한 규칙 목록 보기");
+  console.log("  --help, -h    도움말 보기");
+  console.log("\n예시:");
+  console.log("  npx @blastlabs/utils init-rules          # 기본 규칙만");
+  console.log("  npx @blastlabs/utils init-rules --fsd    # 기본 + FSD 규칙");
+  console.log("  npx @blastlabs/utils init-rules --all    # 모든 규칙");
+  console.log("\n⚠️  프로젝트 루트 디렉토리에서 실행해주세요!");
+}
+
+function showList() {
+  console.log("📋 설치 가능한 규칙 목록\n");
+  
+  console.log("📦 기본 규칙 (base) - 항상 포함:");
+  for (const rule of RULE_CATEGORIES.base) {
+    console.log(`   ├── ${rule}`);
+  }
+  
+  console.log("\n🏗️  FSD 아키텍처 규칙 (--fsd):");
+  for (const rule of RULE_CATEGORIES.fsd) {
+    console.log(`   ├── ${rule}`);
+  }
+  
+  console.log("\n💡 각 규칙은 globs 패턴으로 자동 적용됩니다.");
+}
+
+function getRulesSourceDir() {
+  // 패키지 내 .cursor/rules 경로
+  return path.join(__dirname, "..", ".cursor", "rules");
+}
+
+function copyRule(ruleName, sourceDir, targetDir) {
+  const sourcePath = path.join(sourceDir, ruleName);
+  const targetPath = path.join(targetDir, ruleName);
+
+  if (!fs.existsSync(sourcePath)) {
+    console.log(`   ⚠️  ${ruleName} - 소스 파일 없음, 건너뜀`);
+    return false;
+  }
+
+  if (fs.existsSync(targetPath)) {
+    console.log(`   ⏭️  ${ruleName} - 이미 존재함, 건너뜀`);
+    return false;
+  }
+
+  fs.copyFileSync(sourcePath, targetPath);
+  console.log(`   ✅ ${ruleName}`);
+  return true;
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const options = parseArgs(args);
+
+  if (options.help) {
+    showHelp();
+    process.exit(0);
+  }
+
+  if (options.list) {
+    showList();
+    process.exit(0);
+  }
+
+  const targetDir = process.cwd();
+  const rulesTargetDir = path.join(targetDir, ".cursor", "rules");
+  const rulesSourceDir = getRulesSourceDir();
+
+  // 소스 디렉토리 확인
+  if (!fs.existsSync(rulesSourceDir)) {
+    console.error("❌ 규칙 소스 디렉토리를 찾을 수 없습니다.");
+    console.error(`   경로: ${rulesSourceDir}`);
+    process.exit(1);
+  }
+
+  // .cursor/rules 디렉토리 생성
+  if (!fs.existsSync(rulesTargetDir)) {
+    fs.mkdirSync(rulesTargetDir, { recursive: true });
+    console.log("📁 .cursor/rules/ 디렉토리 생성됨\n");
+  }
+
+  // 설치할 규칙 목록 결정
+  let rulesToInstall = [...RULE_CATEGORIES.base];
+
+  if (options.all || options.fsd) {
+    rulesToInstall = [...rulesToInstall, ...RULE_CATEGORIES.fsd];
+  }
+
+  // 중복 제거
+  rulesToInstall = [...new Set(rulesToInstall)];
+
+  console.log("📥 규칙 설치 중...\n");
+
+  let installedCount = 0;
+  let skippedCount = 0;
+
+  for (const rule of rulesToInstall) {
+    const installed = copyRule(rule, rulesSourceDir, rulesTargetDir);
+    if (installed) {
+      installedCount++;
+    } else {
+      skippedCount++;
+    }
+  }
+
+  console.log("\n" + "─".repeat(40));
+  console.log(`\n✨ 완료! ${installedCount}개 설치, ${skippedCount}개 건너뜀`);
+
+  console.log("\n📦 설치된 규칙 카테고리:");
+  console.log("   ├── base (기본 규칙)");
+  if (options.all || options.fsd) {
+    console.log("   └── fsd (Feature-Sliced Design)");
+  }
+
+  console.log("\n💡 Tip:");
+  console.log("   - 각 .mdc 파일의 globs 패턴에 따라 자동 적용됩니다");
+  console.log("   - alwaysApply: true 규칙은 항상 적용됩니다");
+  console.log("   - 프로젝트에 맞게 규칙을 수정하세요!");
+}
+
+main();

package/package.json

@@ -1,15 +1,17 @@
 {
   "name": "@blastlabs/utils",
-  "version": "1.13.0",
+  "version": "1.15.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "bin": {
-    "blastlabs-generate-entity": "./bin/generate-entity.cjs"
+    "blastlabs-generate-entity": "./bin/generate-entity.cjs",
+    "blastlabs-init-ai-rules": "./bin/init-ai-rules.cjs"
   },
   "files": [
     "dist",
-    "bin"
+    "bin",
+    "templates"
   ],
   "scripts": {
     "prepare": "npm run build:tsc",

package/templates/base.md

@@ -0,0 +1,111 @@
+# {{PROJECT_NAME}} Development Rules
+
+This file contains development guidelines for AI assistants (Cursor, Claude Code, etc.)
+
+## Project Overview
+
+{{PROJECT_DESCRIPTION}}
+
+---
+
+# 프로젝트 기본 정보
+
+- **패키지 매니저**: {{PACKAGE_MANAGER}}
+- **프레임워크**: {{FRAMEWORK}}
+
+## 기술 스택
+
+- TypeScript
+- React
+- TanStack Query
+- Tailwind CSS
+- Zod
+
+---
+
+# Common Rules (공통 규칙)
+
+## Code Style & Standards
+
+### TypeScript
+- Use strict type checking (`strict: true` in tsconfig)
+- Prefer explicit types over `any`
+- Export all public types and interfaces
+- Use generics for reusable components
+- Use `type` for unions/intersections, `interface` for object shapes
+
+### Naming Conventions
+- **Files/Folders**: kebab-case (`user-profile.tsx`, `use-auth.ts`)
+- **Components**: PascalCase (`UserProfile`, `AuthGuard`)
+- **Hooks**: camelCase with `use` prefix (`useAuth`, `useLocalStorage`)
+- **Constants**: UPPER_SNAKE_CASE (`API_BASE_URL`, `MAX_RETRY_COUNT`)
+- **Types/Interfaces**: PascalCase (`UserProfile`, `AuthState`)
+
+### Import Order
+1. React/Framework imports
+2. Third-party libraries
+3. Internal modules (absolute paths)
+4. Relative imports
+5. Types (with `type` keyword)
+
+```typescript
+import React, { useState, useEffect } from 'react';
+import { useQuery } from '@tanstack/react-query';
+import { Button } from '@/components/ui';
+import { formatDate } from '../utils';
+import type { User } from '@/types';
+```
+
+## React Best Practices
+
+### Component Patterns
+- Use functional components with hooks
+- Keep components small and focused (single responsibility)
+- Extract reusable logic into custom hooks
+- Use composition over inheritance
+
+### Hooks Rules
+- Only call hooks at the top level
+- Only call hooks from React functions
+- Use `useCallback` for event handlers passed to children
+- Use `useMemo` for expensive calculations
+
+### State Management
+- Keep state as local as possible
+- Lift state up only when necessary
+- Use TanStack Query for server state
+- Use context or Zustand for client global state
+
+## Error Handling
+
+```typescript
+try {
+  const result = await someAsyncOperation();
+  return { data: result, error: null };
+} catch (error) {
+  console.error('Operation failed:', error);
+  return { data: null, error: error instanceof Error ? error : new Error('Unknown error') };
+}
+```
+
+## Git Commit Convention
+
+Use conventional commits format:
+- `feat(scope): description` - New features
+- `fix(scope): description` - Bug fixes
+- `refactor(scope): description` - Code refactoring
+- `docs(scope): description` - Documentation changes
+- `test(scope): description` - Test changes
+- `chore(scope): description` - Build/tooling changes
+
+Examples:
+- `feat(auth): add login functionality`
+- `fix(api): resolve timeout error`
+- `docs(readme): update installation guide`
+
+## Before Committing
+
+1. Run tests: `{{PACKAGE_MANAGER}} test`
+2. Build successfully: `{{PACKAGE_MANAGER}} build`
+3. Lint check: `{{PACKAGE_MANAGER}} lint`
+4. Format code: `{{PACKAGE_MANAGER}} format`

package/templates/fsd.md

@@ -0,0 +1,150 @@
+
+---
+
+# Feature-Sliced Design (FSD)
+
+프로젝트는 [FSD 공식문서](https://feature-sliced.github.io/documentation/kr/docs/get-started/overview)를 참고하여 구조화되어 있습니다.
+
+## 폴더 구조
+
+```
+src/
+├── app/          # 앱 설정, providers, 라우팅
+├── entities/     # 도메인 모델, API
+├── features/     # 사용자 기능 단위
+├── shared/       # 공유 컴포넌트, 유틸
+├── views/        # 페이지 컴포넌트
+└── widgets/      # 복합 UI 블록
+```
+
+## Entities Layer (엔티티)
+
+엔티티는 도메인 모델과 API 로직을 관리합니다.
+
+### 구조
+
+```
+entities/
+└── (엔티티 이름)/          예: inquiry, popular-product
+    ├── api/
+    │   ├── mapper/
+    │   │   ├── map-(엔티티 이름).ts
+    │   │   └── map-(엔티티 이름)-detail.ts
+    │   ├── query/
+    │   │   ├── (엔티티 이름)-list-query.ts
+    │   │   └── (엔티티 이름)-detail-query.ts
+    │   ├── get-(엔티티 이름)-list.ts
+    │   ├── get-(엔티티 이름)-detail.ts
+    │   ├── (엔티티 이름)-queries.ts
+    │   ├── mutate.ts
+    │   └── index.ts
+    ├── model/
+    │   ├── (엔티티 이름).ts
+    │   ├── (엔티티 이름)-detail.ts
+    │   └── (엔티티 이름)-update.ts
+    ├── schema.ts
+    └── index.ts
+```
+
+### 각 파일의 역할
+
+- **mapper/**: API 응답을 도메인 모델로 변환
+- **query/**: 쿼리 파라미터 타입 정의
+- **get-\*-list.ts**: 리스트 조회 API 함수
+- **get-\*-detail.ts**: 상세 조회 API 함수
+- **\*-queries.ts**: TanStack Query queryOptions 정의 (all, lists, list, details, detail 등)
+- **mutate.ts**: mutation 함수들
+- **model/**: 도메인 모델 타입 정의
+- **schema.ts**: zod 스키마 정의 및 변환 함수
+- **index.ts**: `export * as (엔티티 이름)Api from "./api"`
+
+### 예시
+
+```
+entities/inquiry/
+├── api/
+│   ├── mapper/
+│   │   ├── map-inquiry.ts
+│   │   └── map-inquiry-detail.ts
+│   ├── query/
+│   │   ├── inquiry-list-query.ts
+│   │   └── inquiry-detail-query.ts
+│   ├── get-inquiry-list.ts
+│   ├── get-inquiry-detail.ts
+│   └── inquiry-queries.ts
+├── model/
+│   ├── inquiry.ts
+│   └── inquiry-detail.ts
+└── schema.ts
+```
+
+## Shared Layer (공유 레이어)
+
+프로젝트 전체에서 공유되는 코드를 관리합니다.
+
+### 구조
+
+```
+shared/
+├── api/                    API 인스턴스 설정
+├── constant/               공통 상수 (path.ts 등)
+├── hooks/                  공통 React 훅
+├── lib/                    라이브러리 래퍼 및 설정
+│   └── (라이브러리명)/
+│       ├── provider.tsx
+│       └── config.ts
+├── ui/
+│   ├── component/          재사용 가능한 UI 컴포넌트
+│   │   └── (컴포넌트명)/
+│   │       ├── index.tsx
+│   │       ├── types.ts
+│   │       └── (컴포넌트명).tsx
+│   ├── theme/              테마 관련 CSS 파일
+│   └── utils/              UI 관련 유틸리티 함수
+└── utils/                  일반 유틸리티 함수
+```
+
+### lib vs utils 구분 기준
+
+#### `shared/lib/`
+외부 라이브러리를 프로젝트에 맞게 감싸거나 설정하는 코드
+- 라이브러리 래퍼(wrapper) 컴포넌트
+- 라이브러리 초기 설정 및 Provider
+- 예시: `react-hook-form/form-provider.tsx`, `tanstack-query/query-client.tsx`
+
+#### `shared/utils/`
+순수 유틸리티 함수 및 비즈니스 로직 헬퍼
+- 라이브러리와 무관한 순수 함수
+- 예시: `convert-price.ts`, `export-excel.ts`, `format-date.ts`
+
+**판단 기준:**
+- 라이브러리를 감싸는가? → `lib/`
+- 순수 함수 또는 유틸인가? → `utils/`
+
+## Views Layer (페이지 레이어)
+
+페이지 단위의 UI와 로직을 관리합니다.
+
+### 구조
+
+```
+views/
+└── (페이지명)/
+    ├── page.tsx                    메인 페이지 컴포넌트 (필수)
+    ├── (페이지명)-list-page.tsx
+    ├── (페이지명)-detail-page.tsx
+    ├── detail/
+    │   ├── page.tsx
+    │   ├── ui/
+    │   ├── hooks/                  use-(페이지명)-detail-data.tsx 등
+    │   └── components/
+    ├── list/
+    │   ├── (컬럼명)-column.tsx
+    │   ├── search.tsx
+    │   └── (모달명)-modal.tsx
+    ├── hooks/
+    ├── components/
+    ├── utils/
+    ├── schema/
+    └── constants.ts
+```

package/templates/monorepo.md

@@ -0,0 +1,61 @@
+
+---
+
+# Monorepo Rules
+
+## Structure
+
+```
+root/
+├── apps/
+│   ├── web/            # 웹 앱
+│   ├── admin/          # 어드민
+│   └── mobile/         # 모바일 앱
+├── packages/
+│   ├── ui/             # 공유 UI 컴포넌트
+│   ├── utils/          # 공유 유틸리티
+│   ├── config/         # 공유 설정 (eslint, tsconfig)
+│   └── types/          # 공유 TypeScript 타입
+├── package.json
+└── pnpm-workspace.yaml
+```
+
+## Package Management
+- Use workspace protocol for internal packages (`workspace:*`)
+- Keep shared dependencies in root `package.json`
+- App-specific dependencies in app's `package.json`
+
+```json
+{
+  "dependencies": {
+    "@repo/ui": "workspace:*",
+    "@repo/utils": "workspace:*"
+  }
+}
+```
+
+## Build Order
+- Build packages before apps
+- Use Turborepo for build orchestration
+- Configure proper `dependsOn` in turbo.json
+
+## Shared Configurations
+- Extend base tsconfig in all packages
+- Share ESLint config from `packages/config`
+- Maintain consistent formatting across packages
+
+## Commands
+
+```bash
+# 전체 빌드
+pnpm build
+
+# 특정 앱만 빌드
+pnpm --filter @repo/admin build
+
+# 특정 앱 dev 서버
+pnpm --filter @repo/web dev
+
+# 전체 린트
+pnpm lint
+```

package/templates/nextjs.md

@@ -0,0 +1,67 @@
+
+---
+
+# Next.js Rules
+
+## App Router
+- Use Server Components by default
+- Add `'use client'` only when needed (hooks, browser APIs, interactivity)
+- Colocate loading.tsx, error.tsx, not-found.tsx with pages
+- Use route groups `(group)` for organization without affecting URL
+
+## File Structure
+```
+app/
+├── (auth)/
+│   ├── login/page.tsx
+│   └── register/page.tsx
+├── (main)/
+│   ├── dashboard/page.tsx
+│   └── settings/page.tsx
+├── api/
+│   └── [...route]/route.ts
+├── layout.tsx
+└── page.tsx
+```
+
+## Data Fetching
+- Prefer Server Components for data fetching
+- Use `fetch` with caching options in Server Components
+- Use React Query/SWR for client-side data fetching
+- Implement proper loading and error states
+
+## Environment Variables
+- `NEXT_PUBLIC_*` for client-side variables
+- Server-only variables without prefix
+- Use `.env.local` for local development
+
+## SSR Safety
+
+```typescript
+// ❌ Wrong - breaks SSR
+const token = localStorage.getItem('token');
+
+// ✅ Correct - SSR safe
+const token = typeof window !== 'undefined' 
+  ? localStorage.getItem('token') 
+  : null;
+```
+
+## SSR-Safe Hook Pattern
+
+```typescript
+const [value, setValue] = useState(() => {
+  if (typeof window === 'undefined') return defaultValue;
+  return window.localStorage.getItem(key);
+});
+
+useEffect(() => {
+  if (typeof window === 'undefined') return;
+  // Browser-only code
+}, []);
+```
+
+## Image Optimization
+- Always use `next/image` for images
+- Provide width and height or use `fill`
+- Use appropriate `sizes` prop for responsive images

package/templates/project-specific.md

@@ -0,0 +1,21 @@
+
+---
+
+# Project Specific Rules (프로젝트별 추가 규칙)
+
+<!-- 여기에 프로젝트 고유의 규칙을 추가하세요 -->
+
+## Custom Rules
+- Add your project-specific rules here
+- Document any exceptions to common rules
+- Include team agreements and decisions
+
+## API Conventions
+- Document API patterns used in this project
+- Specify error handling strategies
+- Define response/request formats
+
+## State Management
+- Document which state library is used
+- Define when to use local vs global state
+- Specify state structure conventions

package/templates/testing.md

@@ -0,0 +1,66 @@
+
+---
+
+# 테스트 전략
+
+## 테스트 작성 원칙
+
+### 컴포넌트 (Component) - 단위 테스트
+
+- **대상**: `shared/ui/component/`, 재사용 가능한 컴포넌트
+- **목적**: 컴포넌트의 독립적인 동작 검증
+- **방법**:
+  - Props와 사용자 상호작용에 집중
+  - 외부 의존성(API, 라우팅)은 mock 처리
+  - 렌더링, 이벤트 핸들링, 상태 변경 검증
+
+### 페이지 (Page) - 기능 테스트
+
+- **대상**: `views/*/page.tsx` 페이지 컴포넌트
+- **목적**: 사용자 시나리오와 비즈니스 로직 검증
+- **Mock 최소화 원칙**:
+  - 외부 의존성(API 호출, toast)만 mock
+  - 내부 컴포넌트는 실제로 렌더링하여 통합 테스트
+  - `data-testid` 대신 접근성 기반 쿼리 사용
+
+## Testing Library 쿼리 우선순위
+
+**1순위 (가장 권장):**
+- `getByRole` - 접근성 역할 기반 (button, textbox, checkbox 등)
+- `getByLabelText` - label과 연결된 폼 요소
+- `getByPlaceholderText` - placeholder가 있는 입력 필드
+- `getByText` - 텍스트 내용으로 찾기
+- `getByDisplayValue` - 입력 필드의 현재 값
+
+**2순위:**
+- `getByAltText` - 이미지의 alt 텍스트
+- `getByTitle` - title 속성
+
+**3순위 (최후의 수단):**
+- `getByTestId` - `data-testid` (가능한 한 피해야 함)
+
+**예시:**
+```typescript
+// ✅ 좋은 예
+screen.getByRole('button', { name: '저장' });
+screen.getByRole('checkbox');
+screen.getByText('셀러 정보를 찾을 수 없습니다.');
+screen.getByLabelText(/대표자명/);
+
+// ❌ 나쁜 예
+screen.getByTestId('save-button');
+```
+
+## 테스트 파일 위치
+
+- 컴포넌트와 같은 디렉토리에 `*.test.tsx`
+
+## 테스트 구조
+
+```typescript
+describe('ComponentName', () => {
+  it('should render correctly', () => {});
+  it('should handle user interaction', () => {});
+  it('should show error state', () => {});
+});
+```

package/templates/vite.md

@@ -0,0 +1,53 @@
+
+---
+
+# Vite + React Rules
+
+## Environment Variables
+- Use `import.meta.env.VITE_*` for environment variables
+- Only `VITE_` prefixed variables are exposed to client
+
+```typescript
+// ✅ Correct
+const apiUrl = import.meta.env.VITE_API_URL;
+
+// ❌ Wrong - won't work
+const secret = import.meta.env.SECRET_KEY;
+```
+
+## File Structure
+```
+src/
+├── assets/         # Static assets
+├── components/     # React components
+├── hooks/          # Custom hooks
+├── pages/          # Page components
+├── routes/         # Routing configuration
+├── services/       # API services
+├── stores/         # State management
+├── utils/          # Utility functions
+└── main.tsx        # Entry point
+```
+
+## Path Aliases
+- Use `@/` alias for `src/` directory
+- Configure in `vite.config.ts` and `tsconfig.json`
+
+```typescript
+// vite.config.ts
+resolve: {
+  alias: {
+    '@': path.resolve(__dirname, './src'),
+  },
+}
+```
+
+## Build Optimization
+- Use dynamic imports for code splitting
+- Lazy load routes and heavy components
+- Analyze bundle size with `rollup-plugin-visualizer`
+
+```typescript
+// Lazy loading example
+const Dashboard = lazy(() => import('./pages/Dashboard'));
+```

package/bin/entity-generator-guide.md

@@ -1,126 +0,0 @@
-# 엔티티 자동 생성 스크립트 사용법
-
-## 개요
-
-`generate-entity.cjs` 스크립트를 사용하여 새로운 엔티티의 기본 구조를 자동으로 생성할 수 있습니다.
-
-## 사용법
-
-```bash
-# entities 폴더로 이동
-cd apps/admin/src/entities
-
-# 엔티티 생성
-node generate-entity.cjs <entity-name>
-```
-
-## 예시
-
-```bash
-# user-profile 엔티티 생성
-node generate-entity.cjs user-profile
-
-# my-entity 엔티티 생성
-node generate-entity.cjs my-entity
-
-# product-review 엔티티 생성
-node generate-entity.cjs product-review
-```
-
-## 생성되는 파일 구조
-
-```
-{entity-name}/
-├── index.ts                           # 엔티티 메인 export 파일
-├── api/
-│   ├── get-{entity-name}-list.ts      # API 호출 함수
-│   ├── {entity-name}-queries.ts       # React Query 설정
-│   ├── index.ts                       # API 모듈 export
-│   ├── mapper/
-│   │   └── map-{entity-name}.ts       # 데이터 매핑 함수
-│   └── query/
-│       └── {entity-name}-list-query.ts # 쿼리 타입 정의
-└── model/
-    └── {entity-name}.ts               # Zod 스키마 및 타입
-```
-
-## 자동 생성 후 추가 작업
-
-스크립트 실행 후 다음 작업들을 수동으로 완료해야 합니다:
-
-### 1. query-keys.ts 파일 업데이트
-
-```typescript
-export const {ENTITY_NAME}_QUERY_KEYS = {
-  all: ["{entity-name}"] as const,
-  lists: () => [...{ENTITY_NAME}_QUERY_KEYS.all, "list"] as const,
-  list: (filters: {EntityName}ListParams) =>
-    [...{ENTITY_NAME}_QUERY_KEYS.lists(), filters] as const,
-  details: () => [...{ENTITY_NAME}_QUERY_KEYS.all, "detail"] as const,
-  detail: (id: number) => [...{ENTITY_NAME}_QUERY_KEYS.details(), id] as const,
-};
-```
-
-### 2. model/{entity-name}.ts 수정
-
-실제 API 응답 구조에 맞게 Zod 스키마를 수정해주세요:
-
-```typescript
-export const {EntityName}Schema = z.object({
-  id: z.number(),
-  // 실제 필드들 추가
-  name: z.string(),
-  description: z.string().nullable(),
-  createDate: z.string(),
-  updateDate: z.string(),
-});
-```
-
-### 3. api/mapper/map-{entity-name}.ts 수정
-
-API 응답 데이터를 모델에 맞게 매핑하는 로직을 수정해주세요:
-
-```typescript
-export const map{EntityName} = (item: {EntityName}) => {
-  const res = {EntityName}Schema.safeParse({
-    id: item.id,
-    name: item.name,
-    description: item.description,
-    createDate: item.createDate,
-    updateDate: item.updateDate,
-  });
-  // ...
-};
-```
-
-### 4. api/get-{entity-name}-list.ts 수정
-
-실제 API 엔드포인트 메서드명으로 변경해주세요:
-
-```typescript
-export const get{EntityName}List = (filters: {EntityName}ListQuery) => {
-  const customApi = createInstance(import.meta.env.VITE_BASE_URL);
-  // 실제 API 메서드명으로 변경
-  return customApi.default.admin{EntityName}List(filters);
-};
-```
-
-### 5. api/query/{entity-name}-list-query.ts 수정
-
-필요한 필터링 옵션을 추가해주세요:
-
-```typescript
-export type {EntityName}ListQuery = {
-  limit?: number;
-  offset?: number;
-  search?: string;
-  status?: string;
-  // 추가 필터 옵션들...
-};
-```
-
-## 참고사항
-
-- 엔티티 이름은 kebab-case로 입력해주세요 (예: `user-profile`, `product-review`)
-- 생성된 파일들은 기본 템플릿이므로 실제 API 구조에 맞게 수정이 필요합니다
-- popular-product, popular-review 폴더를 참고하여 패턴을 확인할 수 있습니다