docs: Sync documentation from private repository

PROJECT_STRUCTURE.md

@@ -1,10 +1,33 @@
 # 라온누리 - 프로젝트 구조
 
-> 최종 업데이트: 2025-11-14 (AI 글쓰기 도우미 시스템)
+> 최종 업데이트: 2025-11-17 (AI 이미지 생성 시스템)
 
 초등학생을 위한 창작 글쓰기 교육 플랫폼
 
-**최신 업데이트** (2025-11-14 PM):
+**최신 업데이트** (2025-11-17):
+- 🎨 **AI 이미지 생성 시스템 + 장면 분리 + 프롬프트 최적화**
+  - **Vertex AI Imagen 3.0**: 글 내용 기반 자동 이미지 생성
+  - **AI 장면 분리**: Gemini가 글에서 3~5개 주요 장면 자동 추출
+  - **AI 프롬프트 최적화**: Gemini Flash가 원문 → 핵심 키워드 추출 (string[]) → 최적화된 프롬프트 조합
+  - **4단계 플로우**: 장면 추출 → 장면 선택 → **프롬프트 최적화** → 이미지 생성 → 결과 표시
+  - **사용자 선택권**: 여러 장면 중 원하는 장면만 이미지로 생성
+  - **구조화된 프롬프트**: 피사체/행동/배경/디테일/분위기/스타일 구분하여 추출
+  - **이모지 표시**: 각 장면의 성격을 이모지로 시각화 (🏐 🎮 🍲)
+  - **원문 미리보기**: 각 장면의 원문 80자 표시
+  - **재선택 가능**: 이미지 생성 후 "다른 장면 선택"으로 여러 이미지 생성
+  - **Fallback 안전성**: 프롬프트 최적화 실패 시 기본 방식으로 자동 전환
+  - **Firebase Storage 저장**: base64 이미지 → Storage 업로드 → 공개 URL 생성
+  - **Writing 문서 업데이트**: generatedImage 필드에 이미지 정보 저장
+  - **안전 필터링**: 부적절한 콘텐츠 자동 차단
+  - **다국어 지원**: 한국어/영어/일본어 프롬프트 및 UI
+  - **Multi-region failover**: vertexAI.ts 확장 (기존 인프라 재사용)
+  - **타입**: Scene, SceneExtractionResponse
+  - **서비스**: sceneExtractionService.ts (장면 추출), imagenService.ts (프롬프트 최적화)
+  - **프롬프트**: sceneExtraction.ts (장면 분리), promptOptimization.ts (키워드 추출)
+  - **UI**: SceneSelector (장면 선택), GenerateImageDialog (4단계 플로우)
+  - **API**: POST /api/extract-scenes (장면 추출), POST /api/generate-image (프롬프트 최적화 + 이미지 생성)
+
+**이전 업데이트** (2025-11-14 PM):
 - 🤖 **AI 글쓰기 도우미 시스템**
   - **4단계 점진적 힌트**: 질문 → 방향 → 선택지 → 예시 문장
   - **작성 멈춤 감지**: 5분간 입력 없으면 자동 제안 (useWritingInactivityDetection 훅)
@@ -294,6 +317,8 @@
 | **InactivityPrompt** | `InactivityPrompt.tsx` | 🆕 **작성 멈춤 프롬프트** (5분 입력 없을 시 플로팅 버튼) | ✅ 완료 |
 | **HintDisplay** | `HintDisplay.tsx` | 🆕 **AI 힌트 표시** (4단계 힌트 Dialog, RadioCard 선택지) | ✅ 완료 |
 | **AIAssistancePanel** | `AIAssistancePanel.tsx` | 🆕 **AI 도움 패널** (레벨 선택, 남은 횟수, 쿨다운) | ✅ 완료 |
+| **GenerateImageDialog** | `GenerateImageDialog.tsx` | 🆕 **AI 이미지 생성 Dialog** (4단계 플로우: 장면 추출 → 장면 선택 → 이미지 생성 → 결과 표시) | ✅ 완료 |
+| **SceneSelector** | `SceneSelector.tsx` | 🆕 **장면 선택 컴포넌트** (RadioCard 기반, 이모지 표시, 원문 미리보기) | ✅ 완료 |
 | ~~**ScoreDisplay**~~ | ~~`ScoreDisplay.tsx`~~ | ~~실시간 피드백 점수 표시~~ | ❌ 삭제됨 (하이라이트로 대체) |
 | ~~**SpellingErrorDisplay**~~ | ~~`SpellingErrorDisplay.tsx`~~ | ~~맞춤법 오류 표시~~ | ❌ 삭제됨 (하이라이트로 대체) |
 | **CreateTopicDialog** | `CreateTopicDialog.tsx` | 개인 주제 생성 다이얼로그 (태그 입력 UI) | ✅ 완료 |
@@ -371,12 +396,23 @@
 | 컴포넌트 | 파일명 | 설명 | 상태 |
 |---------|--------|------|------|
 | **TeamTopicManager** | `TeamTopicManager.tsx` | 팀 주제 목록 및 생성/삭제 UI | ✅ 완료 |
+| **AIConfigDialog** | `AIConfigDialog.tsx` | 🆕 **AI 도우미 고급 설정 Dialog** (Slider, 커스텀 CheckboxCard) | ✅ 완료 |
 | **SecurityLevelSelector** | `SecurityLevelSelector.tsx` | 5단계 보안 레벨 선택 (RadioCard, framer-motion 애니메이션) | ✅ 완료 |
 | **AllowListManager** | `AllowListManager.tsx` | 명단 관리 (이름/이메일 추가/제거, TagsInput) | ✅ 완료 |
 | **TopicMemberAnalysisSection** | `TopicMemberAnalysisSection.tsx` | 주제별 학생 글쓰기 분석 (Accordion, by-topic 분석) | 🚧 UI만 (API 추후 구현) |
 | **LiveWritingMonitor** | `LiveWritingMonitor.tsx` | 🆕 **실시간 글쓰기 모니터링** (Firebase Realtime DB, 5초 주기) | ✅ 완료 |
 
 **주요 기능**:
+- ✅ **AIConfigDialog** (2025-11-17):
+  - **Slider 설정**: 멈춤 감지 시간 (1-60분), 최대 힌트 횟수 (1-20회), 쿨다운 (0-30분)
+  - **커스텀 힌트 레벨 카드** (직접 onClick 처리, CheckboxCard 미사용):
+    - 반투명 배경 레벨 번호 (opacity: 0.12, 80px 폰트)
+    - 우상단 접힌 페이지 인디케이터 (CSS border trick 삼각형)
+    - 체크 시 브랜드 컬러 삼각형 + 배경 변경
+    - 2x2 그리드 레이아웃 (SimpleGrid columns={2})
+  - **AI 제안 그대로 사용 금지** (Switch)
+  - 다국어 지원 (한국어/영어/일본어)
+  - 함수형 상태 업데이트로 클로저 문제 해결
 - ✅ **LiveWritingMonitor** (2025-11-12):
   - 주제 선택 드롭다운 (Chakra UI Select)
   - **모든 팀 멤버 표시** (getUsersByTeam)
@@ -462,7 +498,9 @@
 |-------|--------|------|------|
 | **Firebase Auth** | `firebaseAuth.ts` | 인증 서비스 (로그인, 회원가입, 소셜, Anonymous, 계정 연결) | ✅ 완료 (단순화됨) |
 | **Firestore** | `firestore.ts` | Firestore CRUD 헬퍼 함수 (WritingManager에서 사용) | ✅ 완료 |
-| **Vertex AI** | `vertexAI.ts` | **Gemini API 범용 래퍼** (`@google/genai`, Multi-region failover, Response Schema) | ✅ 완료 |
+| **Vertex AI** | `vertexAI.ts` | **Gemini API 범용 래퍼** (`@google/genai`, Multi-region failover, Response Schema, 🆕 **Imagen 이미지 생성**) | ✅ 완료 |
+| **Imagen Service** | `imagenService.ts` | 🆕 **AI 이미지 생성 서비스** (글 → 프롬프트 변환, 장면 기반 이미지 생성, 🆕 **AI 프롬프트 최적화**) | ✅ 완료 |
+| **Scene Extraction** | `sceneExtractionService.ts` | 🆕 **AI 장면 분리 서비스** (글 → 3~5개 주요 장면 추출, 장면별 프롬프트 생성) | ✅ 완료 |
 | **Text Analysis** | `textAnalysisService.ts` | **텍스트 분석 서비스** (평가 기준 개편, 히스토리 기반 분석) | ✅ 완료 |
 | **Pattern Analysis** | `patternAnalysisService.ts` | 🆕 **글 작성 패턴 분석 서비스** (10개 글 종합 분석, AI 평가) | ✅ 완료 |
 | **Spelling Check** | `spellingService.ts` | **맞춤법 검사 서비스** (Gemini 기반, 초등학생 눈높이) | ✅ 완료 |
@@ -486,7 +524,8 @@
 |------|--------|------|------|
 | **Team 타입** | `team.ts` | 팀 데이터 모델 (members Map), **TeamSecurityLevel Enum (1-5)**, 🆕 **AIAssistanceConfig** (AI 도우미 설정) | ✅ 완료 |
 | **FirestoreUser 타입** | `firestoreUser.ts` | **FirestoreUser** (DB 저장용), **User** (UI용) 분리 | ✅ 완료 |
-| **Writing 타입** | `writing.ts` | 글 데이터 모델, 🆕 **WritingAnalysis** (AI 분석 결과, contentHash 기반 재사용), **SpellingError** (맞춤법 오류), 🆕 **AIAssistanceRecord** (AI 도움 이력) | ✅ 완료 |
+| **Writing 타입** | `writing.ts` | 글 데이터 모델, 🆕 **WritingAnalysis** (AI 분석 결과, contentHash 기반 재사용), **SpellingError** (맞춤법 오류), 🆕 **AIAssistanceRecord** (AI 도움 이력), 🆕 **GeneratedImage** (AI 생성 이미지) | ✅ 완료 |
+| **Scene 타입** | `scene.ts` | 🆕 **장면 데이터 모델** (Scene, SceneExtractionResponse) | ✅ 완료 |
 | **Draft 타입** | `draft.ts` | 글조각 데이터 모델 (Draft, DraftListItem, **AnalysisHistoryItem**) | ✅ 완료 |
 | **WritingPattern 타입** | `writingPattern.ts` | **글 작성 패턴 분석** 데이터 모델 (WritingPatternAnalysis) | ✅ 완료 |
 | **WritingSession 타입** | `writingSession.ts` | 🆕 **실시간 모니터링** 데이터 모델 (WritingStats, PreviewRequest/Response, MonitoringData) | ✅ 완료 |
@@ -512,6 +551,7 @@
 | **Password Strength** | `passwordStrength.ts` | 비밀번호 강도 계산 | ✅ 완료 |
 | **Content Hash** | `contentHash.ts` | 🆕 **SHA-256 해시 생성** (글 목록 → 해시, id+updatedAt 조합), 🆕 **generateWritingContentHash** (개별 글 content 해시), 서버/클라이언트 지원 | ✅ 완료 |
 | **Pattern Cache Manager** | `patternCacheManager.ts` | 🆕 **패턴 분석 localStorage 캐싱** (LRU 최대 10개, 캐시 통계) | ✅ 완료 |
+| **Image Storage** | `imageStorage.ts` | 🆕 **Firebase Storage 이미지 업로드** (base64 → Storage, 공개 URL 반환) | ✅ 완료 |
 
 ---
 
@@ -530,6 +570,8 @@
 | **Text Analysis** | `textAnalysis.ts` | 텍스트 분석 프롬프트 (다국어, 히스토리 기반) | ✅ 완료 |
 | **Pattern Analysis** | `patternAnalysis.ts` | 패턴 분석 프롬프트 (10개 글 종합 평가) | ✅ 완료 |
 | **Writing Assistance** | `writingAssistance.ts` | 🆕 **AI 글쓰기 도우미 프롬프트** (4단계 × 3개 언어, 주제 맥락 활용) | ✅ 완료 |
+| **Scene Extraction** | `sceneExtraction.ts` | 🆕 **AI 장면 추출 프롬프트** (3~5개 장면 분리, Response Schema, ko/en/ja) | ✅ 완료 |
+| **Prompt Optimization** | `promptOptimization.ts` | 🆕 **프롬프트 최적화 프롬프트** (원문 → 핵심 키워드 배열 추출, Imagen 최적화) | ✅ 완료 |
 
 ---
 
@@ -552,6 +594,8 @@
 | **명단 관리** | `/api/team/[teamId]/allowed-names` | POST, DELETE | 허용 이름 추가/제거 | ✅ 완료 |
 | **이메일 관리** | `/api/team/[teamId]/allowed-emails` | POST, DELETE | 허용 이메일 추가/제거 | ✅ 완료 |
 | **팀 AI 설정** | `/api/team/[teamId]/ai-config` | GET, PUT | 🆕 **AI 도우미 설정 조회/업데이트** | ✅ 완료 |
+| **AI 장면 추출** | `/api/extract-scenes` | POST | 🆕 **글에서 주요 장면 추출** (Gemini Flash, 3~5개 장면, 각 장면별 이미지 프롬프트 자동 생성) | ✅ 완료 |
+| **AI 이미지 생성** | `/api/generate-image` | POST | 🆕 **장면 기반 이미지 생성** (🆕 **AI 프롬프트 최적화**, Imagen 3.0, Firebase Storage 저장, Writing 업데이트) | ✅ 완료 |
 | **주제 CRUD** | `/api/topic` | GET, POST, PUT, DELETE | 주제 생성/조회/수정/삭제 (9개 엔드포인트) | ✅ 완료 |
 | **사용자 관리** | `/api/user` | GET, POST, PUT | 사용자 조회/생성/업데이트 | ✅ 완료 |
 
@@ -594,10 +638,11 @@
 | `firebase.ts` | Firebase 초기화 및 설정 (Auth, Firestore, **Realtime DB**) | ✅ 완료 |
 | `site.ts` | 사이트 메타데이터 및 설정 | ✅ 완료 |
 
-**Firebase 서비스** (2025-11-12):
+**Firebase 서비스** (2025-11-17):
 - ✅ Firebase Authentication (Email/Password, Google OAuth, Anonymous)
 - ✅ Cloud Firestore (데이터베이스)
 - ✅ Firebase Realtime Database (실시간 모니터링)
+- ✅ Firebase Storage (이미지 저장)
 - ✅ Firebase Analytics (분석)
 
 **Firebase Config**:

ROADMAP.md

@@ -1,6 +1,6 @@
 # 라온누리 - 개발 로드맵
 
-> 최종 업데이트: 2025-11-14 (AI 글쓰기 도우미 시스템)
+> 최종 업데이트: 2025-11-17 (AI 이미지 생성 시스템)
 
 초등학생을 위한 창작 글쓰기 교육 플랫폼 개발 계획
 
@@ -87,6 +87,8 @@
 | **다국어 지원 시스템 (i18n)** | **next-intl 라이브러리 설치 및 설정, [locale] 라우팅 구조 변경 (/ko/*, /en/*, /ja/*), middleware.ts 생성 (브라우저 언어 자동 감지, Accept-Language 헤더), 3개 언어 번역 파일 생성 (messages/ko.json, messages/en.json, messages/ja.json - 각 407줄, 220+ 키), Navbar 번역 (4개 링크), LocaleSwitcher 드롭다운 메뉴 개선 (국기 이모지 🇰🇷 🇺🇸 🇯🇵, 현재 언어 체크 표시, Portal 사용), Landing 페이지 전체 번역 (Hero, Features, Steps, CTA, Footer - 20+ 항목), Home 페이지 전체 번역 (Welcome, QuickStart 9개 액션 카드, RecentActivity), 인증 컴포넌트 전체 번역 (LoginDialog, LoginForm, SignupForm, UserProfileButton, StudentLoginFlow, SavedDraftsDialog - 70+ 항목), Team 페이지 전체 번역 (List, Create, Detail, Manage + SecurityLevelSelector - 60+ 항목), Write 페이지 번역 (분석/저장 메시지, 버튼), 일본어 어린이 친화적 표현 (한자 최소화, ひらがな 우선), site.ts 텍스트를 번역 파일로 이동 (사이트명, 태그라인, 저작권), localeDetection: true 설정, NEXT_LOCALE 쿠키 저장, next.config.ts에 next-intl 플러그인 추가, i18n/routing.ts + i18n/request.ts 설정, 타입 체크 통과, CLAUDE.md에 다국어 필수 규칙 추가** | **2025-11-13** |
 | **개별 글 분석 결과 저장** | **Writing 타입에 WritingAnalysis 필드 추가, SpellingError 타입 정의, generateWritingContentHash 유틸 추가, 글쓰기 페이지 실시간 분석 제거, 저장 버튼 클릭 시 AI 분석 + 맞춤법 검사 병렬 수행, 분석 결과를 DB에 저장, 패턴 분석 시 저장된 분석 재사용 (contentHash 비교), 변경된 글만 재분석 (90% 비용 절감), 맞춤법 에러 히스토리 기능 완성, API 타입/서버 함수/WritingManager 전체 수정, getTranslations()로 서버 사이드 다국어 지원** | **2025-11-14** |
 | **AI 글쓰기 도우미 시스템** | **4단계 점진적 힌트 시스템 (질문 → 방향 → 선택지 → 예시 문장), useWritingInactivityDetection 훅 (5분 작성 멈춤 감지, 타이머 리셋, 남은 시간), UI 컴포넌트 3개 (InactivityPrompt 플로팅 버튼, HintDisplay Dialog, AIAssistancePanel), writingAssistanceService.ts (Vertex AI, 주제 맥락 활용, 서버 캐싱), writingAssistance.ts 프롬프트 (4단계 × 3개 언어 ko/en/ja), 글쓰기 페이지 통합 (AI 도움 요청, 서버 에러 처리), POST /api/writing-assistance (주제 정보 전달, 팀 설정 검증), GET/PUT /api/team/[teamId]/ai-config (AI 설정 조회/업데이트), Team.aiAssistanceConfig 필드 (enabled, detectionTimeMinutes, maxHintsPerWriting, cooldownMinutes, allowedHintLevels, requireSelfEdit), DEFAULT_AI_ASSISTANCE_CONFIG 상수, 팀 관리 페이지 AI On/Off 토글 (Switch.Root v3), TeamManager AI 메서드 (getAIConfig, updateAIConfig), lib/server/team.ts AI 함수 (getTeamAIConfig, updateTeamAIConfig), 서버 검증 (enabled=false → 403, allowedHintLevels 체크), 사용 제한 (글당 5회, 3분 쿨다운), 다국어 번역 추가 (messages/*.json, aiAssist namespace 19개 키), successResponse() 헬퍼 사용, AIAssistanceRecord 타입 (timestamp, hintLevel, topicId, topicTitle, context, hintProvided, wasUsed)** | **2025-11-14** |
+| **AI 설정 고급 UI 완성** | **AIConfigDialog 컴포넌트 (팀 관리 페이지), Slider 3개 (멈춤 감지/최대 힌트/쿨다운), 커스텀 힌트 레벨 카드 (반투명 배경 번호, 우상단 접힌 페이지 삼각형 인디케이터, CSS border trick, 직접 onClick 처리), SimpleGrid 2x2 레이아웃, 브랜드 컬러 상태 변화, Switch (AI 제안 그대로 사용 금지), 함수형 상태 업데이트 (클로저 해결), 다국어 지원 (ko/en/ja, team.manage.aiConfig namespace 28개 키)** | **2025-11-17** |
+| **AI 이미지 생성 + 장면 분리 + 프롬프트 최적화** | **Vertex AI Imagen 3.0 통합, AI 장면 분리 기능 (Gemini Flash), AI 프롬프트 최적화 (Gemini Flash-Lite, 원문 → 핵심 키워드 배열 추출 → 쉼표 연결, Fallback 안전성), 4단계 플로우 (장면 추출 → 장면 선택 → 프롬프트 최적화 → 이미지 생성 → 결과 표시), Scene/SceneExtractionResponse 타입 추가, sceneExtractionService.ts (글 → 3~5개 장면 자동 추출, 장면별 프롬프트 생성), sceneExtraction.ts 프롬프트 (ko/en/ja, Response Schema), promptOptimization.ts 프롬프트 (키워드 추출, ko/en/ja), POST /api/extract-scenes (장면 추출 API), SceneSelector 컴포넌트 (RadioCard, 이모지, 원문 미리보기 80자, ItemHiddenInput 추가), GeneratedImage 타입 (url, prompt, generatedAt, modelName), imagenService.ts (글 → 어린이 친화적 프롬프트 자동 변환, optimizePromptForImage 함수, 안전 필터링), vertexAI.ts 확장 (generateImage 함수, multi-region failover 재사용), imageStorage.ts (Firebase Storage 업로드, base64 → 공개 URL 변환, toDataURL 헬퍼), POST /api/generate-image (권한 체크, AI 프롬프트 최적화, Imagen API 호출, Storage 저장, Writing.generatedImage 필드 업데이트), GenerateImageDialog 개선 (4단계 플로우, 장면 선택 UI, "다른 장면 선택" 버튼), 글쓰기 페이지 통합 ("구체화하기" 버튼, 저장 완료 후 표시, 홈 이동 제거), Firebase Storage 초기화 (fbStorage), 다국어 번역 (write.generateImage + write.extractScenes namespace, ko/en/ja 22개 키), 타입 체크 통과** | **2025-11-17** |
 
 ### 🚧 진행 중
 

TECH_STACK.md

@@ -1,6 +1,6 @@
 # 라온누리 - 기술 스택 및 개발 환경
 
-> 최종 업데이트: 2025-11-14 (개별 글 분석 결과 저장)
+> 최종 업데이트: 2025-11-17 (AI 설정 고급 UI 완성)
 
 ---