@kood/claude-code 0.1.2 → 0.1.4

package/templates/tanstack-start/docs/library/prisma/config.md

@@ -0,0 +1,377 @@
+# Prisma - Config 파일 (prisma.config.ts)
+
+> **상위 문서**: [Prisma](./index.md)
+
+Prisma v7에서 도입된 `prisma.config.ts` 설정 파일입니다.
+
+---
+
+## ⚠️ 필수: Multi-File 스키마 설정
+
+Multi-File 스키마를 사용하려면 **반드시** `prisma.config.ts`에서 스키마 폴더를 지정해야 합니다.
+
+```typescript
+// prisma.config.ts
+import path from 'node:path'
+import { defineConfig, env } from 'prisma/config'
+
+export default defineConfig({
+  // Multi-File 스키마 폴더 지정
+  schema: path.join('prisma', 'schema'),
+  datasource: {
+    url: env('DATABASE_URL'),
+  },
+})
+```
+
+---
+
+## 파일 위치 및 이름
+
+### 지원되는 파일명
+
+```
+prisma.config.ts      # 권장 (소규모 프로젝트)
+prisma.config.js
+prisma.config.mjs
+prisma.config.cjs
+prisma.config.mts
+prisma.config.cts
+
+.config/prisma.ts     # 권장 (대규모 프로젝트)
+.config/prisma.js
+```
+
+### 권장 위치
+
+```
+프로젝트/
+├── prisma.config.ts      # 프로젝트 루트
+├── prisma/
+│   ├── schema/           # Multi-File 스키마 폴더
+│   │   ├── +base.prisma
+│   │   ├── +enum.prisma
+│   │   └── user.prisma
+│   └── migrations/       # 마이그레이션 폴더
+└── package.json
+```
+
+---
+
+## 설정 옵션
+
+### 전체 옵션 목록
+
+| 옵션 | 타입 | 필수 | 설명 |
+|------|------|------|------|
+| `schema` | string | ❌ | 스키마 파일 또는 폴더 경로 |
+| `datasource.url` | string | ✅ | 데이터베이스 연결 URL |
+| `datasource.shadowDatabaseUrl` | string | ❌ | Shadow DB URL |
+| `migrations.path` | string | ❌ | 마이그레이션 폴더 경로 |
+| `migrations.seed` | string | ❌ | 시드 스크립트 명령어 |
+| `migrations.initShadowDb` | string | ❌ | Shadow DB 초기화 SQL |
+| `views.path` | string | ❌ | SQL 뷰 정의 폴더 |
+| `typedSql.path` | string | ❌ | TypedSQL 파일 폴더 |
+| `experimental` | object | ❌ | 실험적 기능 활성화 |
+
+---
+
+## 기본 설정 예시
+
+### defineConfig 사용 (권장)
+
+```typescript
+// prisma.config.ts
+import 'dotenv/config'
+import { defineConfig, env } from 'prisma/config'
+
+export default defineConfig({
+  // Multi-File 스키마 설정
+  schema: 'prisma/schema',
+
+  // 마이그레이션 설정
+  migrations: {
+    path: 'prisma/migrations',
+    seed: 'tsx prisma/seed.ts',
+  },
+
+  // 데이터베이스 연결
+  datasource: {
+    url: env('DATABASE_URL'),
+  },
+})
+```
+
+### satisfies 사용
+
+```typescript
+// prisma.config.ts
+import 'dotenv/config'
+import type { PrismaConfig } from 'prisma'
+import { env } from 'prisma/config'
+
+export default {
+  schema: 'prisma/schema',
+  migrations: {
+    path: 'prisma/migrations',
+    seed: 'tsx prisma/seed.ts',
+  },
+  datasource: {
+    url: env('DATABASE_URL'),
+  },
+} satisfies PrismaConfig
+```
+
+---
+
+## Multi-File 스키마 설정
+
+### 필수 설정
+
+```typescript
+// prisma.config.ts
+import path from 'node:path'
+import { defineConfig, env } from 'prisma/config'
+
+export default defineConfig({
+  // ⚠️ 폴더 경로 지정 (파일이 아님!)
+  schema: path.join('prisma', 'schema'),
+  datasource: {
+    url: env('DATABASE_URL'),
+  },
+})
+```
+
+### 폴더 구조
+
+```
+prisma/
+├── schema/                    # Multi-File 스키마 폴더
+│   ├── +base.prisma          # datasource, generator 설정
+│   ├── +enum.prisma          # 모든 enum 정의
+│   ├── user.prisma           # User 모델
+│   ├── post.prisma           # Post 모델
+│   └── ...
+└── migrations/               # ⚠️ datasource와 같은 레벨에 위치
+```
+
+### +base.prisma 예시
+
+```prisma
+// prisma/schema/+base.prisma
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Prisma 기본 설정 파일
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+// 데이터베이스 연결 설정
+datasource db {
+  provider = "postgresql"
+  url      = env("DATABASE_URL")
+}
+
+// Prisma Client 생성 설정
+generator client {
+  provider = "prisma-client"  // Prisma v7 필수
+  output   = "../../generated/prisma"
+}
+```
+
+---
+
+## 환경 변수 설정
+
+### dotenv 설치
+
+```bash
+npm install dotenv
+```
+
+### 환경 변수 사용
+
+```typescript
+// prisma.config.ts
+import 'dotenv/config'  // ⚠️ 반드시 최상단에 import
+import { defineConfig, env } from 'prisma/config'
+
+export default defineConfig({
+  schema: 'prisma/schema',
+  datasource: {
+    url: env('DATABASE_URL'),  // 타입 안전한 환경 변수 접근
+  },
+})
+```
+
+### .env 파일
+
+```env
+DATABASE_URL="postgresql://user:password@localhost:5432/mydb"
+```
+
+---
+
+## 마이그레이션 설정
+
+### 시드 스크립트
+
+```typescript
+// prisma.config.ts
+import { defineConfig, env } from 'prisma/config'
+
+export default defineConfig({
+  schema: 'prisma/schema',
+  migrations: {
+    path: 'prisma/migrations',
+    seed: 'tsx prisma/seed.ts',  // 시드 명령어
+  },
+  datasource: {
+    url: env('DATABASE_URL'),
+  },
+})
+```
+
+### 시드 파일 예시
+
+```typescript
+// prisma/seed.ts
+import { PrismaClient } from '../generated/prisma'
+
+const prisma = new PrismaClient()
+
+async function main() {
+  // 초기 데이터 생성
+  await prisma.user.create({
+    data: {
+      email: 'admin@example.com',
+      name: '관리자',
+      role: 'ADMIN',
+    },
+  })
+}
+
+main()
+  .catch(console.error)
+  .finally(() => prisma.$disconnect())
+```
+
+---
+
+## Shadow Database 설정
+
+마이그레이션 시 사용되는 임시 데이터베이스입니다.
+
+```typescript
+// prisma.config.ts
+import { defineConfig, env } from 'prisma/config'
+
+export default defineConfig({
+  schema: 'prisma/schema',
+  datasource: {
+    url: env('DATABASE_URL'),
+    shadowDatabaseUrl: env('SHADOW_DATABASE_URL'),
+  },
+})
+```
+
+---
+
+## 실험적 기능
+
+### External Tables
+
+외부에서 관리되는 테이블 설정:
+
+```typescript
+// prisma.config.ts
+import { defineConfig, env } from 'prisma/config'
+
+export default defineConfig({
+  schema: 'prisma/schema',
+  experimental: {
+    externalTables: true,
+  },
+  tables: {
+    external: ['public.users'],
+  },
+  enums: {
+    external: ['public.role'],
+  },
+  datasource: {
+    url: env('DATABASE_URL'),
+  },
+})
+```
+
+---
+
+## 경로 해석 규칙
+
+### 중요 사항
+
+- 모든 경로는 **config 파일 위치 기준**으로 해석됩니다
+- CLI 명령어 실행 위치가 아닙니다!
+
+### 예시
+
+```
+프로젝트/
+├── prisma.config.ts          # 여기가 기준!
+├── prisma/
+│   └── schema/
+└── src/
+```
+
+```typescript
+// prisma.config.ts
+export default defineConfig({
+  // ✅ prisma.config.ts 기준 상대 경로
+  schema: 'prisma/schema',
+
+  // ❌ 이렇게 하지 마세요
+  schema: './prisma/schema',  // ./ 불필요
+})
+```
+
+### 커스텀 경로 지정
+
+```bash
+# --config 플래그로 config 파일 위치 지정
+npx prisma validate --config ./path/to/myconfig.ts
+```
+
+---
+
+## 전체 설정 예시
+
+```typescript
+// prisma.config.ts
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Prisma v7 설정 파일
+// Multi-File 스키마 및 마이그레이션 설정
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+import 'dotenv/config'
+import path from 'node:path'
+import { defineConfig, env } from 'prisma/config'
+
+export default defineConfig({
+  // Multi-File 스키마 폴더
+  schema: path.join('prisma', 'schema'),
+
+  // 마이그레이션 설정
+  migrations: {
+    path: 'prisma/migrations',
+    seed: 'tsx prisma/seed.ts',
+  },
+
+  // 데이터베이스 연결
+  datasource: {
+    url: env('DATABASE_URL'),
+  },
+})
+```
+
+---
+
+## 관련 문서
+
+- [스키마 정의 (Multi-File)](./schema.md)
+- [설치 및 설정](./setup.md)

package/templates/tanstack-start/docs/library/prisma/index.md

@@ -47,11 +47,13 @@ generator client {
 
 ## 문서 구조
 
+- [Config 파일](./config.md) - prisma.config.ts 설정 ⭐
 - [설치 및 설정](./setup.md) - Prisma Client 설정
-- [스키마 정의](./schema.md) - 모델, 관계, Enum 정의
+- [스키마 정의 (Multi-File)](./schema.md) - 모델, 관계, Enum 정의
 - [CRUD 작업](./crud.md) - Create, Read, Update, Delete
 - [관계 쿼리](./relations.md) - 중첩 생성, 관계 포함 조회
 - [트랜잭션](./transactions.md) - 배열 기반 트랜잭션, 인터랙티브 트랜잭션
+- [Cloudflare D1](./cloudflare-d1.md) - D1 서버리스 데이터베이스 연동
 
 ## 빠른 시작
 
@@ -64,10 +66,6 @@ npm install -D prisma@7
 yarn add @prisma/client@7
 yarn add -D prisma@7
 
-# pnpm
-pnpm add @prisma/client@7
-pnpm add -D prisma@7
-
 # 초기화
 npx prisma init
 ```

package/templates/tanstack-start/docs/library/prisma/schema.md

@@ -1,63 +1,161 @@
-# Prisma - 스키마 정의
+# Prisma - 스키마 정의 (Multi-File)
 
 > **상위 문서**: [Prisma](./index.md)
 
-## 기본 스키마
+## ⚠️ 필수: Multi-File 구조 사용
+
+Prisma 스키마는 **반드시 Multi-File 구조**로 작성합니다.
+
+```
+prisma/
+├── schema/
+│   ├── +base.prisma      # datasource, generator 설정
+│   ├── +enum.prisma      # 모든 enum 정의
+│   ├── user.prisma       # User 모델
+│   ├── post.prisma       # Post 모델
+│   ├── category.prisma   # Category 모델
+│   └── profile.prisma    # Profile 모델
+```
+
+## ⚠️ 필수: 한글 주석 작성
+
+**Prisma Multi-File의 모든 요소에 한글 주석을 작성해야 합니다.**
+
+```
+✅ 파일별 목적 주석
+✅ 모델별 설명 주석
+✅ 필드별 설명 주석 (용도가 명확하지 않은 경우)
+✅ 관계 설명 주석
+✅ enum 값 설명 주석
+```
+
+---
+
+## Multi-File 스키마 예시
+
+### +base.prisma (기본 설정)
 
 ```prisma
-// prisma/schema.prisma
+// prisma/schema/+base.prisma
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Prisma 기본 설정 파일
+// datasource 및 generator 설정
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+// 데이터베이스 연결 설정
 datasource db {
   provider = "postgresql"
   url      = env("DATABASE_URL")
 }
 
+// Prisma Client 생성 설정
 generator client {
-  provider = "prisma-client"
+  provider = "prisma-client"  // Prisma v7 필수
   output   = "../generated/prisma"
 }
+```
+
+### +enum.prisma (열거형 정의)
+
+```prisma
+// prisma/schema/+enum.prisma
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// 모든 열거형(enum) 정의 파일
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+// 사용자 권한 열거형
+enum Role {
+  USER   // 일반 사용자
+  ADMIN  // 관리자
+}
+
+// 게시글 상태 열거형
+enum PostStatus {
+  DRAFT      // 임시저장
+  PUBLISHED  // 공개됨
+  ARCHIVED   // 보관됨
+}
+```
+
+### user.prisma (User 모델)
+
+```prisma
+// prisma/schema/user.prisma
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// 사용자 모델
+// 시스템의 모든 사용자 정보를 저장
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 model User {
   id           Int              @id @default(autoincrement())
-  email        String           @unique
-  name         String?
-  role         Role             @default(USER)
-  posts        Post[]
-  profile      ExtendedProfile?
+  email        String           @unique  // 로그인 이메일 (중복 불가)
+  name         String?                   // 표시 이름 (선택)
+  role         Role             @default(USER)  // 사용자 권한
+  posts        Post[]                    // 작성한 게시글 목록
+  profile      ExtendedProfile?          // 확장 프로필 (1:1)
   createdAt    DateTime         @default(now())
   updatedAt    DateTime         @updatedAt
 }
+```
+
+### post.prisma (Post 모델)
+
+```prisma
+// prisma/schema/post.prisma
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// 게시글 모델
+// 사용자가 작성한 게시글 정보
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 model Post {
   id         Int        @id @default(autoincrement())
-  title      String
-  content    String?
-  published  Boolean    @default(false)
-  author     User       @relation(fields: [authorId], references: [id])
-  authorId   Int
-  categories Category[]
+  title      String                    // 게시글 제목
+  content    String?                   // 게시글 본문 (선택)
+  published  Boolean    @default(false)  // 공개 여부
+  status     PostStatus @default(DRAFT)  // 게시글 상태
+  author     User       @relation(fields: [authorId], references: [id])  // 작성자 관계
+  authorId   Int                       // 작성자 ID (외래키)
+  categories Category[]                // 소속 카테고리 목록 (M:N)
   createdAt  DateTime   @default(now())
   updatedAt  DateTime   @updatedAt
 }
+```
+
+### category.prisma (Category 모델)
+
+```prisma
+// prisma/schema/category.prisma
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// 카테고리 모델
+// 게시글 분류를 위한 카테고리
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 model Category {
   id    Int    @id @default(autoincrement())
-  name  String @unique
-  posts Post[]
+  name  String @unique  // 카테고리명 (중복 불가)
+  posts Post[]          // 소속 게시글 목록 (M:N)
 }
+```
+
+### profile.prisma (Profile 모델)
+
+```prisma
+// prisma/schema/profile.prisma
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// 확장 프로필 모델
+// 사용자의 추가 정보 (1:1 관계)
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 model ExtendedProfile {
   id        Int    @id @default(autoincrement())
-  biography String
-  user      User   @relation(fields: [userId], references: [id])
-  userId    Int    @unique
-}
-
-enum Role {
-  USER
-  ADMIN
+  biography String  // 자기소개
+  user      User   @relation(fields: [userId], references: [id])  // 사용자 관계
+  userId    Int    @unique  // 사용자 ID (외래키, 유니크)
 }
 ```
 
+---
+
 ## 선택적 관계
 
 ```prisma

package/templates/tanstack-start/docs/library/prisma/setup.md

@@ -13,10 +13,6 @@ npm install -D prisma@7
 yarn add @prisma/client@7
 yarn add -D prisma@7
 
-# pnpm
-pnpm add @prisma/client@7
-pnpm add -D prisma@7
-
 # bun
 bun add @prisma/client@7
 bun add prisma@7 --dev
@@ -34,9 +30,6 @@ npm install -D prisma@7
 
 # yarn
 yarn up prisma@7 @prisma/client@7
-
-# pnpm
-pnpm upgrade prisma@7 @prisma/client@7
 ```
 
 ### Generator 변경 (필수)

package/templates/tanstack-start/docs/library/tanstack-start/server-functions.md

@@ -4,6 +4,21 @@
 
 Server Functions는 서버에서만 실행되는 타입 안전한 함수입니다.
 
+## ⚠️ 필수: TanStack Query 사용
+
+**Server Function을 클라이언트에서 호출할 때는 반드시 TanStack Query를 사용해야 합니다.**
+
+```
+❌ 금지: Server Function 직접 호출
+✅ 필수: useQuery/useMutation과 함께 사용
+```
+
+**이유**:
+- 자동 캐싱 및 중복 요청 제거
+- 로딩/에러 상태 관리
+- 자동 재시도 및 백그라운드 갱신
+- invalidateQueries로 일관된 데이터 동기화
+
 ## 기본 Server Function
 
 ```typescript
@@ -73,9 +88,9 @@ export const submitForm = createServerFn({ method: 'POST' })
   })
 ```
 
-## 컴포넌트에서 호출
+## 컴포넌트에서 호출 (TanStack Query 필수)
 
-### useServerFn 사용
+### ✅ 올바른 패턴: useQuery 사용 (데이터 조회)
 
 ```tsx
 import { useServerFn } from '@tanstack/react-start'
@@ -103,6 +118,69 @@ function PostList() {
 }
 ```
 
+### ✅ 올바른 패턴: useMutation 사용 (데이터 변경)
+
+```tsx
+import { useServerFn } from '@tanstack/react-start'
+import { useMutation, useQueryClient } from '@tanstack/react-query'
+import { createPost, deletePost } from '~/lib/server-functions'
+
+function PostForm() {
+  const queryClient = useQueryClient()
+  const createPostFn = useServerFn(createPost)
+
+  const mutation = useMutation({
+    mutationFn: (data: { title: string; content: string }) => createPostFn({ data }),
+    onSuccess: () => {
+      // 관련 쿼리 무효화로 데이터 동기화
+      queryClient.invalidateQueries({ queryKey: ['posts'] })
+    },
+  })
+
+  const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
+    e.preventDefault()
+    const formData = new FormData(e.currentTarget)
+    mutation.mutate({
+      title: formData.get('title') as string,
+      content: formData.get('content') as string,
+    })
+  }
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <input name="title" required />
+      <textarea name="content" required />
+      <button type="submit" disabled={mutation.isPending}>
+        {mutation.isPending ? '저장 중...' : '저장'}
+      </button>
+    </form>
+  )
+}
+```
+
+### ❌ 금지: Server Function 직접 호출
+
+```tsx
+// ❌ 이렇게 하지 마세요!
+function BadExample() {
+  const [posts, setPosts] = useState([])
+  const [loading, setLoading] = useState(false)
+
+  useEffect(() => {
+    setLoading(true)
+    getPosts()
+      .then(setPosts)
+      .finally(() => setLoading(false))
+  }, [])
+
+  // 문제점:
+  // - 중복 요청 발생 가능
+  // - 캐싱 없음
+  // - 에러 처리 수동
+  // - 다른 컴포넌트와 데이터 동기화 안됨
+}
+```
+
 ## 보안 패턴
 
 ### 서버 전용 데이터 보호