@kood/claude-code 0.1.2 → 0.1.4

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

@@ -0,0 +1,320 @@
+# Pino - Structured Logging
+
+> 초고속 JSON 로거 (Server Functions 전용)
+
+---
+
+## ⚠️ 중요: Server Functions에서만 사용
+
+Pino는 **Server Functions에서만** 사용해야 합니다. 클라이언트 컴포넌트에서는 사용하지 마세요.
+
+```
+✅ src/functions/*.ts          → Pino 사용 가능
+✅ routes/*/-functions/*.ts    → Pino 사용 가능
+❌ routes/*.tsx (컴포넌트)      → Pino 사용 금지 (console.log 사용)
+❌ components/*.tsx            → Pino 사용 금지
+```
+
+---
+
+## 왜 console.log 대신 Pino를 사용해야 하나요?
+
+| 항목 | console.log | Pino |
+|------|-------------|------|
+| **출력 형식** | 비정형 텍스트 | 구조화된 JSON |
+| **성능** | 느림 | 초고속 (30x 빠름) |
+| **로그 레벨** | 없음 | debug, info, warn, error, fatal |
+| **컨텍스트 추가** | 수동 문자열 연결 | 자동 객체 바인딩 |
+| **프로덕션 분석** | 어려움 | JSON 파싱으로 쉬움 |
+| **Child Logger** | 불가 | 요청별 컨텍스트 분리 |
+
+---
+
+## 설치
+
+```bash
+# pino + pino-pretty (개발용 포맷터)
+npm install pino pino-pretty
+```
+
+---
+
+## 기본 설정
+
+### lib/logger.ts
+
+```typescript
+import pino from 'pino'
+
+const isDev = process.env.NODE_ENV === 'development'
+
+export const logger = pino({
+  level: isDev ? 'debug' : 'info',
+  transport: isDev
+    ? {
+        target: 'pino-pretty',
+        options: {
+          colorize: true,
+          translateTime: 'SYS:yyyy-mm-dd HH:MM:ss',
+          ignore: 'pid,hostname',
+        },
+      }
+    : undefined,
+})
+```
+
+### 환경별 출력
+
+**개발 환경** (pino-pretty):
+```
+2024-01-15 10:30:45 INFO: User created successfully
+    userId: "user_123"
+    email: "user@example.com"
+```
+
+**프로덕션** (JSON):
+```json
+{"level":30,"time":1705312245000,"msg":"User created successfully","userId":"user_123","email":"user@example.com"}
+```
+
+---
+
+## Server Functions에서 사용
+
+### 기본 사용법
+
+```typescript
+// functions/user.ts
+import { createServerFn } from '@tanstack/react-start'
+import { logger } from '@/lib/logger'
+import { prisma } from '@/database/prisma'
+import { createUserSchema } from '@/validators/user'
+import { authMiddleware } from '@/middleware/auth'
+
+export const createUser = createServerFn({ method: 'POST' })
+  .middleware([authMiddleware])
+  .inputValidator(createUserSchema)
+  .handler(async ({ data, context }) => {
+    logger.info({ email: data.email }, 'Creating new user')
+
+    try {
+      const user = await prisma.user.create({ data })
+      logger.info({ userId: user.id }, 'User created successfully')
+      return user
+    } catch (error) {
+      logger.error({ error, email: data.email }, 'Failed to create user')
+      throw error
+    }
+  })
+```
+
+### Child Logger로 요청 컨텍스트 추가
+
+```typescript
+// functions/user.ts
+import { createServerFn } from '@tanstack/react-start'
+import { logger } from '@/lib/logger'
+import { prisma } from '@/database/prisma'
+
+export const getUser = createServerFn({ method: 'GET' })
+  .middleware([authMiddleware])
+  .handler(async ({ context }) => {
+    // 요청별 컨텍스트가 포함된 child logger 생성
+    const log = logger.child({
+      requestId: context.requestId,
+      userId: context.userId,
+    })
+
+    log.info('Fetching user profile')
+
+    const user = await prisma.user.findUnique({
+      where: { id: context.userId },
+    })
+
+    if (!user) {
+      log.warn('User not found')
+      throw new Error('User not found')
+    }
+
+    log.debug({ user }, 'User fetched successfully')
+    return user
+  })
+```
+
+**출력 예시**:
+```json
+{"level":30,"time":1705312245000,"requestId":"req_abc123","userId":"user_456","msg":"Fetching user profile"}
+{"level":20,"time":1705312245050,"requestId":"req_abc123","userId":"user_456","user":{"id":"user_456","name":"John"},"msg":"User fetched successfully"}
+```
+
+---
+
+## 로그 레벨
+
+```typescript
+logger.trace('매우 상세한 디버깅 정보')  // level: 10
+logger.debug('디버깅 정보')              // level: 20
+logger.info('일반 정보')                 // level: 30
+logger.warn('경고')                      // level: 40
+logger.error('에러')                     // level: 50
+logger.fatal('치명적 에러')              // level: 60
+```
+
+### 레벨별 사용 가이드
+
+| 레벨 | 용도 | 예시 |
+|------|------|------|
+| `trace` | 매우 상세한 흐름 추적 | 함수 진입/종료, 변수 값 |
+| `debug` | 개발 중 디버깅 | 쿼리 결과, 중간 계산값 |
+| `info` | 주요 이벤트 | 사용자 생성, 결제 완료 |
+| `warn` | 주의 필요 | 재시도 발생, 느린 쿼리 |
+| `error` | 에러 발생 | API 실패, 예외 처리 |
+| `fatal` | 시스템 중단 | 서버 시작 실패 |
+
+---
+
+## 구조화된 로깅 패턴
+
+### 객체와 메시지 함께 로깅
+
+```typescript
+// ✅ 올바른 패턴: 객체 먼저, 메시지 나중
+logger.info({ userId: '123', action: 'login' }, 'User logged in')
+
+// ❌ 잘못된 패턴: 문자열 연결
+logger.info('User ' + userId + ' logged in')  // 구조화되지 않음
+```
+
+### 에러 로깅
+
+```typescript
+try {
+  await riskyOperation()
+} catch (error) {
+  // ✅ err 키로 에러 객체 전달 (스택 트레이스 자동 포함)
+  logger.error({ err: error, context: 'riskyOperation' }, 'Operation failed')
+}
+```
+
+**출력**:
+```json
+{
+  "level": 50,
+  "time": 1705312245000,
+  "err": {
+    "type": "Error",
+    "message": "Connection refused",
+    "stack": "Error: Connection refused\n    at ..."
+  },
+  "context": "riskyOperation",
+  "msg": "Operation failed"
+}
+```
+
+---
+
+## 고급 설정
+
+### pino-pretty 전체 옵션
+
+```typescript
+// lib/logger.ts
+import pino from 'pino'
+
+export const logger = pino({
+  level: process.env.LOG_LEVEL || 'info',
+  transport:
+    process.env.NODE_ENV === 'development'
+      ? {
+          target: 'pino-pretty',
+          options: {
+            colorize: true,
+            translateTime: 'SYS:yyyy-mm-dd HH:MM:ss.l',
+            ignore: 'pid,hostname',
+            singleLine: false,
+            levelFirst: true,
+            messageFormat: '{levelLabel} - {msg}',
+            customColors: 'info:blue,warn:yellow,error:red,fatal:bgRed',
+            errorProps: 'stack,code,cause',
+          },
+        }
+      : undefined,
+})
+```
+
+### TypeScript 타입 강제
+
+```typescript
+// types/pino.d.ts
+declare module 'pino' {
+  interface LogFnFields {
+    userId?: string
+    requestId?: string
+    action?: string
+  }
+}
+```
+
+```typescript
+// 사용 시 타입 검사
+logger.info({ userId: '123' }, 'User action')  // ✅
+logger.info({ userId: 123 }, 'User action')    // ❌ 타입 에러
+```
+
+---
+
+## 프로덕션 설정
+
+### 환경 변수
+
+```bash
+# .env
+LOG_LEVEL=info  # production
+# LOG_LEVEL=debug  # staging
+```
+
+### 멀티 스트림 (파일 + stdout)
+
+```typescript
+import pino from 'pino'
+
+const streams = [
+  { level: 'info', stream: process.stdout },
+  { level: 'error', stream: pino.destination('./logs/error.log') },
+]
+
+export const logger = pino(
+  { level: 'debug' },
+  pino.multistream(streams)
+)
+```
+
+---
+
+## ❌ 하지 말아야 할 것
+
+```typescript
+// ❌ 클라이언트 컴포넌트에서 pino 사용 금지
+const MyComponent = () => {
+  logger.info('Component rendered')  // ❌ 서버에서만 동작
+  return <div>Hello</div>
+}
+
+// ❌ 민감한 정보 로깅 금지
+logger.info({ password: user.password }, 'User logged in')  // ❌
+
+// ❌ 문자열 연결 사용 금지
+logger.info('User ' + userId + ' created at ' + new Date())  // ❌
+
+// ❌ console.log와 혼용 금지 (Server Functions에서)
+console.log('Processing...')  // ❌ pino 사용하세요
+logger.info('Processing...')  // ✅
+```
+
+---
+
+## 관련 문서
+
+- [Server Functions](../tanstack-start/server-functions.md)
+- [미들웨어](../tanstack-start/middleware.md)
+- [아키텍처](../../architecture/architecture.md)

package/templates/tanstack-start/docs/library/prisma/cloudflare-d1.md

@@ -0,0 +1,404 @@
+# Prisma - Cloudflare D1
+
+> **상위 문서**: [Prisma](./index.md)
+
+---
+
+## ⚠️ 주의사항
+
+Cloudflare D1은 **SQLite 기반 서버리스 데이터베이스**입니다. 일반 Prisma 마이그레이션과 **다른 워크플로우**를 사용합니다.
+
+```
+⚠️ D1은 트랜잭션을 지원하지 않음 (ACID 보장 X)
+⚠️ prisma migrate dev 사용 불가 - wrangler CLI 사용
+⚠️ Prisma ORM D1 지원은 Preview 상태
+```
+
+---
+
+## 🚀 Quick Reference
+
+```typescript
+// D1 Adapter 설정
+import { PrismaClient } from './generated/prisma'
+import { PrismaD1 } from '@prisma/adapter-d1'
+
+export interface Env {
+  DB: D1Database
+}
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const adapter = new PrismaD1(env.DB)
+    const prisma = new PrismaClient({ adapter })
+
+    const users = await prisma.user.findMany()
+    return new Response(JSON.stringify(users))
+  },
+}
+```
+
+### schema.prisma (D1용)
+
+```prisma
+generator client {
+  provider = "prisma-client"
+  output   = "../src/generated/prisma"
+  runtime  = "cloudflare"  // D1 필수!
+}
+
+datasource db {
+  provider = "sqlite"  // D1은 SQLite 기반
+}
+
+model User {
+  id    Int     @id @default(autoincrement())
+  email String  @unique
+  name  String?
+}
+```
+
+---
+
+## 설치
+
+```bash
+# 필수 패키지
+npm install @prisma/client @prisma/adapter-d1
+npm install -D prisma wrangler
+
+# Prisma 초기화
+npx prisma init --datasource-provider sqlite
+```
+
+---
+
+## D1 데이터베이스 생성
+
+```bash
+# Cloudflare D1 데이터베이스 생성
+npx wrangler d1 create my-database
+
+# 출력 예시:
+# ✅ Successfully created DB 'my-database'
+# database_id = "xxxx-xxxx-xxxx-xxxx"
+```
+
+---
+
+## wrangler.jsonc 설정
+
+```jsonc
+{
+  "$schema": "node_modules/wrangler/config-schema.json",
+  "name": "my-worker",
+  "main": "src/index.ts",
+  "compatibility_date": "2025-01-01",
+  "d1_databases": [
+    {
+      "binding": "DB",
+      "database_name": "my-database",
+      "database_id": "YOUR_DATABASE_ID"
+    }
+  ]
+}
+```
+
+---
+
+## Schema 설정
+
+### schema.prisma
+
+```prisma
+generator client {
+  provider = "prisma-client"
+  output   = "../src/generated/prisma"
+  runtime  = "cloudflare"
+}
+
+datasource db {
+  provider = "sqlite"
+}
+
+model User {
+  id    Int     @id @default(autoincrement())
+  email String  @unique
+  name  String?
+  posts Post[]
+}
+
+model Post {
+  id        Int     @id @default(autoincrement())
+  title     String
+  content   String?
+  published Boolean @default(false)
+  author    User    @relation(fields: [authorId], references: [id])
+  authorId  Int
+}
+```
+
+---
+
+## 마이그레이션 워크플로우
+
+D1은 일반 Prisma 마이그레이션(`prisma migrate dev`)을 사용하지 않습니다.
+
+### 1단계: 마이그레이션 디렉토리 생성
+
+```bash
+mkdir -p prisma/migrations
+```
+
+### 2단계: 마이그레이션 파일 생성 (wrangler)
+
+```bash
+npx wrangler d1 migrations create my-database create_user_table
+```
+
+### 3단계: SQL 생성 (prisma migrate diff)
+
+```bash
+# 초기 마이그레이션 (빈 스키마에서)
+npx prisma migrate diff \
+  --from-empty \
+  --to-schema-datamodel prisma/schema.prisma \
+  --script \
+  --output prisma/migrations/0001_create_user_table.sql
+
+# 후속 마이그레이션 (로컬 D1에서)
+npx prisma migrate diff \
+  --from-local-d1 \
+  --to-schema-datamodel prisma/schema.prisma \
+  --script \
+  --output prisma/migrations/0002_add_post_table.sql
+```
+
+### 4단계: 마이그레이션 적용
+
+```bash
+# 로컬 데이터베이스에 적용
+npx wrangler d1 migrations apply my-database --local
+
+# 원격(프로덕션) 데이터베이스에 적용
+npx wrangler d1 migrations apply my-database --remote
+```
+
+### 생성된 SQL 예시
+
+```sql
+-- 0001_create_user_table.sql
+-- CreateTable
+CREATE TABLE "User" (
+    "id" INTEGER NOT NULL PRIMARY KEY AUTOINCREMENT,
+    "email" TEXT NOT NULL,
+    "name" TEXT
+);
+
+-- CreateIndex
+CREATE UNIQUE INDEX "User_email_key" ON "User"("email");
+```
+
+---
+
+## Prisma Client 설정
+
+### Cloudflare Worker에서 사용
+
+```typescript
+// src/index.ts
+import { PrismaClient } from './generated/prisma'
+import { PrismaD1 } from '@prisma/adapter-d1'
+
+export interface Env {
+  DB: D1Database
+}
+
+export default {
+  async fetch(
+    request: Request,
+    env: Env,
+    ctx: ExecutionContext
+  ): Promise<Response> {
+    const adapter = new PrismaD1(env.DB)
+    const prisma = new PrismaClient({ adapter })
+
+    const url = new URL(request.url)
+
+    if (url.pathname === '/users' && request.method === 'GET') {
+      const users = await prisma.user.findMany()
+      return new Response(JSON.stringify(users), {
+        headers: { 'Content-Type': 'application/json' },
+      })
+    }
+
+    if (url.pathname === '/users' && request.method === 'POST') {
+      const body = await request.json()
+      const user = await prisma.user.create({
+        data: body,
+      })
+      return new Response(JSON.stringify(user), {
+        status: 201,
+        headers: { 'Content-Type': 'application/json' },
+      })
+    }
+
+    return new Response('Not Found', { status: 404 })
+  },
+}
+```
+
+---
+
+## TanStack Start + D1 통합
+
+D1은 Cloudflare Workers 환경에서 실행되므로, TanStack Start의 Cloudflare 배포와 함께 사용합니다.
+
+### Server Function에서 사용
+
+```typescript
+// lib/prisma.ts
+import { PrismaClient } from './generated/prisma'
+import { PrismaD1 } from '@prisma/adapter-d1'
+
+export const createPrismaClient = (db: D1Database) => {
+  const adapter = new PrismaD1(db)
+  return new PrismaClient({ adapter })
+}
+
+// Server Function
+import { createServerFn } from '@tanstack/react-start'
+
+export const getUsers = createServerFn({ method: 'GET' })
+  .handler(async ({ context }) => {
+    // context에서 D1 바인딩 접근 필요
+    const prisma = createPrismaClient(context.env.DB)
+    return prisma.user.findMany()
+  })
+```
+
+---
+
+## 로컬 개발
+
+### 로컬 D1로 개발
+
+```bash
+# 로컬 Worker 실행 (D1 포함)
+npx wrangler dev
+
+# 로컬 D1에 데이터 삽입
+npx wrangler d1 execute my-database --local \
+  --command "INSERT INTO User (email, name) VALUES ('test@example.com', 'Test User');"
+
+# 로컬 D1 조회
+npx wrangler d1 execute my-database --local \
+  --command "SELECT * FROM User;"
+```
+
+---
+
+## 배포
+
+```bash
+# Prisma Client 생성
+npx prisma generate
+
+# 원격 D1에 마이그레이션 적용
+npx wrangler d1 migrations apply my-database --remote
+
+# Worker 배포
+npx wrangler deploy
+```
+
+---
+
+## ⚠️ 제한사항
+
+### 트랜잭션 미지원
+
+```typescript
+// ❌ 트랜잭션이 무시됨 - ACID 보장 안됨
+await prisma.$transaction([
+  prisma.user.create({ data: { email: 'user1@example.com' } }),
+  prisma.post.create({ data: { title: 'Post', authorId: 1 } }),
+])
+
+// ❌ Interactive 트랜잭션도 미지원
+await prisma.$transaction(async (tx) => {
+  // 각 쿼리가 독립적으로 실행됨
+})
+```
+
+### D1 vs 일반 SQLite 차이점
+
+| 항목 | 일반 SQLite | Cloudflare D1 |
+|------|-------------|---------------|
+| 마이그레이션 | `prisma migrate dev` | `wrangler d1 migrations` |
+| 트랜잭션 | ✅ 지원 | ❌ 미지원 |
+| 데이터베이스 위치 | 로컬 파일 | Cloudflare Edge |
+| 접속 방식 | 직접 연결 | HTTP (어댑터) |
+| 환경 | 로컬 `.wrangler/state` | 원격 Cloudflare |
+
+---
+
+## prisma.config.ts (선택사항)
+
+Prisma CLI에서 D1에 직접 접근이 필요한 경우:
+
+```typescript
+// prisma.config.ts
+import path from 'node:path'
+import type { PrismaConfig } from 'prisma'
+import { PrismaD1 } from '@prisma/adapter-d1'
+
+export default {
+  experimental: {
+    adapter: true,
+  },
+  engine: 'js',
+  schema: path.join('prisma', 'schema.prisma'),
+  async adapter() {
+    return new PrismaD1({
+      CLOUDFLARE_D1_TOKEN: process.env.CLOUDFLARE_D1_TOKEN,
+      CLOUDFLARE_ACCOUNT_ID: process.env.CLOUDFLARE_ACCOUNT_ID,
+      CLOUDFLARE_DATABASE_ID: process.env.CLOUDFLARE_DATABASE_ID,
+    })
+  },
+} satisfies PrismaConfig
+```
+
+---
+
+## 마이그레이션 명령어 요약
+
+```bash
+# D1 데이터베이스 생성
+npx wrangler d1 create my-database
+
+# 마이그레이션 파일 생성
+npx wrangler d1 migrations create my-database migration_name
+
+# SQL 생성 (초기)
+npx prisma migrate diff --from-empty --to-schema-datamodel prisma/schema.prisma --script
+
+# SQL 생성 (후속)
+npx prisma migrate diff --from-local-d1 --to-schema-datamodel prisma/schema.prisma --script
+
+# 로컬 적용
+npx wrangler d1 migrations apply my-database --local
+
+# 원격 적용
+npx wrangler d1 migrations apply my-database --remote
+
+# Prisma Client 생성
+npx prisma generate
+```
+
+---
+
+## 참고 자료
+
+- [Prisma D1 공식 문서](https://www.prisma.io/docs/orm/overview/databases/cloudflare-d1)
+- [Cloudflare D1 문서](https://developers.cloudflare.com/d1/)
+- [Prisma D1 가이드](https://www.prisma.io/guides/cloudflare-d1)