밀프레드 편식도감
개발 명세서

기술 스택

디렉토리 구조

mealfred/
├── apps/
│   ├── web/                    # Next.js 15 App Router
│   │   ├── app/
│   │   │   ├── (auth)/         # 로그인·OAuth 콜백
│   │   │   ├── (app)/          # 인증 후 — 홈·도감·기록·레시피
│   │   │   │   ├── home/
│   │   │   │   ├── dex/        # 도감
│   │   │   │   ├── record/     # 식단 기록
│   │   │   │   └── recipes/
│   │   │   ├── eval/           # daycare-eval 진입점
│   │   │   ├── api/            # API Routes
│   │   │   │   ├── eval/
│   │   │   │   ├── recommend/
│   │   │   │   ├── ocr/
│   │   │   │   └── webhook/
│   │   │   ├── layout.tsx
│   │   │   └── page.tsx
│   │   ├── components/
│   │   │   ├── ui/             # Button·Card·Modal 등 기본
│   │   │   ├── eval/           # SignalLight·GaugeBar 등
│   │   │   ├── recipe/         # RecipeCard·MealPlan
│   │   │   └── record/
│   │   ├── lib/
│   │   │   ├── supabase/       # client·server·types
│   │   │   ├── kdri/           # KDRI lookup·percentile
│   │   │   └── utils/
│   │   ├── hooks/              # useChild·useMealLogs 등
│   │   └── styles/
│   └── admin/                  # 운영자 대시보드 (Phase 2)
├── packages/
│   ├── shared/                 # 공통 타입·상수
│   │   ├── types/
│   │   ├── kdri-rni.ts         # KDRI 36 영양소 상수
│   │   └── ingredients-pool.ts # 147 식재료 풀
│   ├── eval-engine/            # 평가 엔진 (Pure functions)
│   │   ├── axes/
│   │   ├── signal.ts
│   │   └── bmi.ts
│   ├── reco-engine/            # 추천 엔진
│   │   ├── phase0-profile.ts
│   │   ├── phase1-rules.ts
│   │   ├── phase2-llm.ts
│   │   └── cache.ts
│   └── ocr-engine/             # OCR 엔진
├── supabase/
│   ├── migrations/             # SQL 마이그레이션
│   ├── functions/              # Edge Functions
│   └── seed.sql                # 초기 데이터 (KDRI·ingredients)
├── scripts/
│   ├── enrich-recipes.ts       # 4,432 레시피 메타 enrich 배치
│   └── extract-ingredients.py  # 식재료 추출
├── .github/workflows/          # CI/CD
├── pnpm-workspace.yaml
├── package.json
└── README.md

코딩 컨벤션

3-1. Naming

• 파일: kebab-case (meal-log-card.tsx), 컴포넌트는 PascalCase (MealLogCard.tsx) 선택적
• 함수: camelCase 동사 시작 (calculateBMI, fetchMealLogs)
• 훅: use 접두사 (useChild, useEvalScore)
• 상수: SCREAMING_SNAKE_CASE (KDRI_36_NUTRIENTS, MAX_LOGS_PER_DAY)
• 타입: PascalCase + 명사 (MealLog, NutrientStatus)
• enum: PascalCase (MealType, TextureLevel)
• DB 컬럼: snake_case (child_id, eaten_at) — Supabase 관례

3-2. Comment 정책

3-3. 파일 구성 패턴

// ✅ 좋은 예 — 도메인별 응집
export function calculateNutrientSignal(logs: MealLog[], ageBand: AgeBand) {
  return KDRI_36_NUTRIENTS.map(n => classifyFrequency(logs, n, ageBand))
}
function classifyFrequency(logs: MealLog[], nutrient: Nutrient, band: AgeBand): NutrientSignal {
  // 빈도 → 색상 분류
  const meals = countContributingMeals(logs, nutrient)
  const pct = (meals / WEEKLY_TARGET) * 100
  return { nutrient, pct, status: pct >= 80 ? 'green' : pct >= 50 ? 'orange' : 'red' }
}

API 엔드포인트 명세

4-1. 인증

4-2. 아이 프로필

4-3. 식단 기록

4-4. 평가

4-5. 추천

4-6. OCR

4-7. 응답 표준 형식

{
  "ok": true,
  "data": { ... },
  "meta": {
    "cached": true,
    "version": "1.0.0",
    "latency_ms": 142
  }
}
// 에러 시
{
  "ok": false,
  "error": { "code": "VALIDATION_ERROR", "message": "...", "field": "eaten_at" }
}

인증 흐름

// 1) OAuth 진입
const { data, error } = await supabase.auth.signInWithOAuth({
  provider: 'kakao',
  options: { redirectTo: '/auth/callback' }
})

// 2) 콜백 — 세션 교환
// app/auth/callback/route.ts
export async function GET(req: Request) {
  const code = new URL(req.url).searchParams.get('code')
  await supabase.auth.exchangeCodeForSession(code!)
  return Response.redirect('/home')
}

// 3) API 보호 — middleware
export async function middleware(req: NextRequest) {
  const session = await getSession(req)
  if (!session) return NextResponse.redirect('/login')
}

// 4) RLS 자동 적용 (Supabase가 auth.uid()를 컨텍스트로)
// children 테이블의 RLS 정책이 user_id = auth.uid() 자동 필터링

데이터 페칭 + 상태

• 서버 상태: @tanstack/react-query v5 — 캐싱·revalidation·optimistic updates
• 클라이언트 상태: zustand (전역 UI 상태) + useState (지역)
• 폼: react-hook-form + zod 검증
• URL 상태: Next.js searchParams (필터·날짜 등)

// 예: useChild hook
export function useChild(childId: string) {
  return useQuery({
    queryKey: ['child', childId],
    queryFn: () => fetchChild(childId),
    staleTime: 5 * 60 * 1000,  // 5분
  })
}

테스트 전략

GitHub Actions + Vercel

# .github/workflows/ci.yml
on: [pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v3
      - run: pnpm install
      - run: pnpm typecheck
      - run: pnpm test:unit
      - run: pnpm test:integration
      - run: pnpm test:e2e
      - run: pnpm build
      - uses: codecov/codecov-action@v4

# Vercel PR Preview 자동 (브랜치 push 시)
# main 머지 시 → 프로덕션 자동 배포 (icn1 region)

# 배치 작업 cron
# .github/workflows/cron-enrich.yml — 매일 03:00 KST
# - 신규 식재료 운영 큐 검토 알림
# - 캐시 정리
# - LLM 사용량 리포트

환경변수 관리

# .env.local (개발)
NEXT_PUBLIC_SUPABASE_URL=https://xxx.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ...
SUPABASE_SERVICE_ROLE_KEY=eyJ...    # server only
ANTHROPIC_API_KEY=sk-ant-...
UPSTASH_REDIS_REST_URL=...
UPSTASH_REDIS_REST_TOKEN=...
SENTRY_DSN=https://...
NEXT_PUBLIC_POSTHOG_KEY=phc_...

# 환경별 분리
.env.development  → 개발
.env.preview      → Vercel PR preview
.env.production   → 프로덕션

# Vercel에서 관리:
# - SUPABASE_SERVICE_ROLE_KEY, ANTHROPIC_API_KEY 등 secret
# - dev/preview/production 환경별 다른 값 가능

에러 처리 + 로깅

• 전역 에러 바운더리: app/error.tsx + Sentry 자동 캡쳐
• API 에러: 표준 코드 (VALIDATION_ERROR·UNAUTHORIZED·RATE_LIMIT·LLM_ERROR·OCR_FAILED)
• 재시도: LLM/OCR 호출은 exponential backoff (1s, 2s, 4s, max 3회)
• fallback: LLM 실패 시 Phase 1 룰 결과만 반환 (자연어 이유 제외)
• 사용자 메시지: 기술 용어 X → "이런, 한 번 더 시도해볼까요?"

성능 최적화

• 이미지: Next/Image + AVIF/WebP · lazy loading · responsive sizes
• 코드 분할: route-based + dynamic import (모달·차트)
• SSR/SSG: 정적 페이지(blog·proposal) SSG, 앱은 SSR + Streaming
• 캐싱: API 응답 Cache-Control + Redis hot data + React Query
• LLM 비용: Anthropic Prompt Caching (system prompt) → -50%
• DB 인덱스: 핵심 쿼리에 covering index (architecture-detailed §1-3)
• 모니터링 지표: LCP < 2.5s · FID < 100ms · CLS < 0.1

보안

• RLS: 모든 사용자 데이터 테이블에 적용 — 자기 데이터만 접근
• CSP: Content-Security-Policy 헤더 — 외부 스크립트 화이트리스트
• CORS: API 라우트는 same-origin only (앱 도메인에서만)
• Rate Limiting: Upstash Ratelimit — IP당 60 req/min
• SQL Injection: Supabase 클라이언트 (parameterized)
• XSS: React 자동 escape + dangerouslySetInnerHTML 금지
• 비밀: service_role_key는 서버 only, 클라이언트 노출 절대 X
• OAuth: PKCE flow · state 검증
• 이미지 검증: 업로드 시 magic byte 체크 + 크기 제한 10MB
• LLM 입력: prompt injection 방지 — user input은 항상 user role로 전달

모니터링 + 알람

13-1. 추적 지표

13-2. 알람 채널

• Slack #alerts: 모든 에러 · 비용 임계 · 성능 저하
• 이메일 (긴급): 서비스 다운 · 보안 이슈
• 대시보드: Grafana (월 단위 + 실시간)

13-3. 운영자 대시보드 (Phase 2)

• 신규 식재료 검수 큐 (영양사 일 1회)
• OCR 실패 케이스 검토
• 사용자 피드백 모니터링
• 비용·사용량 트렌드