docs: Sync documentation from private repository

PROJECT_STRUCTURE.md

@@ -1,10 +1,17 @@
 # 라온누리 - 프로젝트 구조
 
-> 최종 업데이트: 2025-11-21 (수정 모드 UX 개선 + 주제 변경 차단)
+> 최종 업데이트: 2025-11-21 (홈 페이지 모듈화)
 
 초등학생을 위한 창작 글쓰기 교육 플랫폼
 
 **최신 업데이트** (2025-11-21):
+- 📦 **홈 페이지 모듈화**
+  - **6개 컴포넌트 분리**: HeroSection, QuickActionCard, QuickActionsGrid, ViewAllWritingsCard, EmptyStateCard, RecentActivitySection
+  - **코드 감소**: 580줄 → 223줄 (62% 감소)
+  - **Semantic token 적극 활용**: `bg`, `fg`, `border` 등 우선 사용
+  - **재사용성 향상**: 각 컴포넌트 단일 책임 원칙 준수
+  - **UI 일관성**: 글래스모피즘, framer-motion 애니메이션, 브랜드 컬러 통일
+  - **JSX 주석 한글화**: 모든 주석을 한글로 통일
 - 🎨 **수정 모드 UX 대폭 개선**
   - **Sticky 헤더바**: 오렌지/앰버 그라데이션 배경, 상단 고정 (z-index: 100)
   - **강조된 테두리**: 주제 선택 + 글쓰기 영역에 오렌지 테두리 (2px solid)
@@ -23,7 +30,7 @@
   - 상단 버튼 영역 단순화 ("저장된 글조각" 버튼만 유지)
   - 미사용 i18n 키 정리 (`newWriting`, `discardConfirm`)
 
-**이전 업데이트** (2025-11-20):
+**업데이트** (2025-11-20):
 - 🎨 **AI 이미지 생성 스타일 일관성 개선**
   - **Vertex AI Imagen 4.0 Fast**: 글 내용 기반 자동 이미지 생성 (모델 업그레이드)
   - **일관된 스타일 가이드**: 모든 이미지에 동일한 화풍 적용
@@ -35,7 +42,7 @@
   - **AI 프롬프트 최적화**: Gemini Flash가 원문 → 핵심 키워드 추출 (6-12개) → 스타일 키워드 자동 추가
   - **폴백 안전성**: AI 최적화 실패 시에도 일관된 스타일 적용
 
-**이전 업데이트** (2025-11-17):
+**업데이트** (2025-11-17):
 - 🎨 **AI 이미지 생성 시스템 + 장면 분리 + 프롬프트 최적화**
   - **AI 장면 분리**: Gemini가 글에서 3~5개 주요 장면 자동 추출
   - **4단계 플로우**: 장면 추출 → 장면 선택 → 프롬프트 최적화 → 이미지 생성 → 결과 표시
@@ -52,7 +59,7 @@
   - **UI**: SceneSelector (장면 선택), GenerateImageDialog (4단계 플로우)
   - **API**: POST /api/extract-scenes (장면 추출), POST /api/generate-image (프롬프트 최적화 + 이미지 생성)
 
-**이전 업데이트** (2025-11-14 PM):
+**업데이트** (2025-11-14 PM):
 - 🤖 **AI 글쓰기 도우미 시스템**
   - **4단계 점진적 힌트**: 질문 → 방향 → 선택지 → 예시 문장
   - **작성 멈춤 감지**: 5분간 입력 없으면 자동 제안 (useWritingInactivityDetection 훅)
@@ -65,7 +72,7 @@
   - **API**: POST /api/writing-assistance, GET/PUT /api/team/[teamId]/ai-config
   - **Firestore**: Team.aiAssistanceConfig 필드 추가
 
-**최신 업데이트** (2025-11-14 AM):
+**업데이트** (2025-11-14 AM):
 - 💾 **개별 글 분석 결과 저장 시스템**
   - Writing 타입에 WritingAnalysis 필드 추가
   - 글쓰기 페이지 실시간 분석 제거 (저장 시에만 분석)
@@ -74,7 +81,7 @@
   - contentHash 기반 변경 감지
   - 맞춤법 에러 히스토리 기능 완성
 
-**이전 업데이트** (2025-11-13):
+**업데이트** (2025-11-13):
 - 🌏 **다국어 지원 시스템 (i18n)**
   - next-intl 라이브러리 기반
   - **3개 언어 지원**: 한국어(ko), 영어(en), 일본어(ja)
@@ -89,7 +96,7 @@
   - **쿠키 저장**: 사용자가 선택한 언어 기억 (`NEXT_LOCALE`)
   - **site.ts 텍스트 이동**: 사이트 메타데이터도 번역 파일로 관리
 
-**최신 업데이트** (2025-11-12 PM):
+**업데이트** (2025-11-12 PM):
 - 📡 **실시간 글쓰기 모니터링 시스템**
   - Firebase Realtime Database 기반 실시간 통신 (Redis Pub/Sub 방식)
   - **모든 팀 멤버 표시** (getUsersByTeam)
@@ -110,7 +117,7 @@
   - 완전 무료 (동시 접속 100명까지, 1GB/day)
   - Security Rules (본인 쓰기, 인증된 사용자 읽기)
 
-**최신 업데이트** (2025-11-12 AM):
+**업데이트** (2025-11-12 AM):
 - ✅ **Writing API 구현 완료**
   - POST /api/writing - 글 생성 (서버에서 wordCount/charCount 자동 계산, 🆕 **analysis 저장**)
   - GET /api/writing/[id] - 글 조회 (작성자만 접근)
@@ -348,8 +355,7 @@
 | **WritingCard** | `WritingCard.tsx` | 🆕 **글 카드 컴포넌트** (제목, 날짜, 미리보기, 주제/점수/이미지 배지, 메뉴, 삭제) | ✅ 완료 |
 | ~~**ScoreDisplay**~~ | ~~`ScoreDisplay.tsx`~~ | ~~실시간 피드백 점수 표시~~ | ❌ 삭제됨 (하이라이트로 대체) |
 | ~~**SpellingErrorDisplay**~~ | ~~`SpellingErrorDisplay.tsx`~~ | ~~맞춤법 오류 표시~~ | ❌ 삭제됨 (하이라이트로 대체) |
-| **CreateTopicDialog** | `CreateTopicDialog.tsx` | 개인 주제 생성 다이얼로그 (태그 입력 UI) | ✅ 완료 |
+| **CreateTopicDialog** | `CreateTopicDialog.tsx` | 🆕 **통합 주제 생성 다이얼로그** (개인/팀 공용, 태그 입력 UI, 템플릿 지원, TopicFormData 반환) | ✅ 완료 |
-| **CreateTeamTopicDialog** | `CreateTeamTopicDialog.tsx` | 팀 주제 생성 다이얼로그 (템플릿 지원) | ✅ 완료 |
 | **SavedDraftsDialog** | `SavedDraftsDialog.tsx` | 저장된 글조각 목록 다이얼로그 (불러오기/삭제, **동기화 상태 배지** 🟢synced/🟡syncing/⚪local) | ✅ 완료 |
 
 **주요 기능**:
@@ -469,6 +475,35 @@
 
 ---
 
+### 📁 `src/components/home/` - 홈 페이지
+
+| 컴포넌트 | 파일명 | 설명 | 상태 |
+|---------|--------|------|------|
+| **HeroSection** | `HeroSection.tsx` | 환영 메시지 섹션 (그라데이션 강조 라인, 사용자 이름) | ✅ 완료 |
+| **QuickActionCard** | `QuickActionCard.tsx` | 개별 빠른 실행 액션 카드 (아이콘, 제목, 설명, 글래스모피즘, 미구현 오버레이) | ✅ 완료 |
+| **QuickActionsGrid** | `QuickActionsGrid.tsx` | 액션 카드 그리드 레이아웃 (12컬럼 그리드, framer-motion) | ✅ 완료 |
+| **ViewAllWritingsCard** | `ViewAllWritingsCard.tsx` | "모든 글 보기" 액션 카드 (화살표 아이콘, 클릭 가능) | ✅ 완료 |
+| **EmptyStateCard** | `EmptyStateCard.tsx` | 글이 없을 때 빈 상태 표시 (이모티콘, CTA 버튼, 패턴 배경) | ✅ 완료 |
+| **RecentActivitySection** | `RecentActivitySection.tsx` | 최근 활동 섹션 전체 (글 목록, 로딩, 빈 상태 처리) | ✅ 완료 |
+
+**주요 기능**:
+- ✅ **모듈화** (2025-11-21):
+  - 홈 페이지 580줄 → 223줄 (62% 코드 감소)
+  - 6개 재사용 가능한 컴포넌트로 분리
+  - 각 컴포넌트 단일 책임 원칙 준수
+- ✅ **Semantic Token 적극 활용**:
+  - `bg`, `fg`, `border` 등 semantic token 우선 사용
+  - Conditional style 객체 최소화 (특수한 경우만)
+  - Landing 페이지 전용 토큰 활용 (`landing.feature.*.bg`, `landing.text`)
+- ✅ **UI 일관성**:
+  - 글래스모피즘 효과 (backdrop-filter, 반투명 배경)
+  - framer-motion 애니메이션 (fade-in, scale, stagger)
+  - 브랜드 컬러 시스템 통일
+- ✅ **다국어 지원**: 한국어/영어/일본어 번역
+- ✅ **JSX 주석 한글화**: 모든 주석을 한글로 통일
+
+---
+
 ### 📁 예정된 컴포넌트 디렉토리
 
 | 디렉토리 | 설명 | 컴포넌트 |
@@ -779,8 +814,7 @@ project_w/
 │   ├── writing/                # ✅ 글쓰기 에디터
 │   │   ├── WritingEditor.tsx   # 순수 텍스트 에디터 (포맷팅 없음)
 │   │   ├── TopicSelector.tsx   # ✅ 주제 선택 컴포넌트 (팀/개인 배지)
-│   │   ├── CreateTopicDialog.tsx      # ✅ 개인 주제 생성
+│   │   └── CreateTopicDialog.tsx      # ✅ 통합 주제 생성 (개인/팀 공용)
-│   │   └── CreateTeamTopicDialog.tsx  # ✅ 팀 주제 생성
 │   ├── team/                   # ✅ 팀 관련
 │   │   ├── TeamTopicManager.tsx       # ✅ 팀 주제 관리
 │   │   ├── SecurityLevelSelector.tsx  # 보안 레벨 선택 (RadioCard, 애니메이션)

ROADMAP.md

@@ -1,6 +1,6 @@
 # 라온누리 - 개발 로드맵
 
-> 최종 업데이트: 2025-11-21 (수정 모드 UX 개선 + 주제 변경 차단)
+> 최종 업데이트: 2025-11-21 (홈 페이지 모듈화)
 
 초등학생을 위한 창작 글쓰기 교육 플랫폼 개발 계획
 
@@ -104,6 +104,8 @@
 | **Draft 클라우드 동기화** | **localStorage + Realtime DB 하이브리드 저장, syncStatus 필드 추가 ('local'\|'synced'\|'syncing'), DraftManager 확장 (syncToCloud, loadDraftsFromCloud, mergeDrafts, deleteDraftFromCloud), SavedDraftsDialog 배지 표시 (🟢동기화됨/🟡동기화 중/⚪기기만), write/page.tsx mergeDrafts 호출 (로그인 시), database.rules.json drafts 규칙 추가 (본인만 읽기/쓰기), 기기 간 동기화 (학교 ↔ 집), updatedAt 비교로 최신 버전 선택** | **2025-11-19** |
 | **팀 코드 예약 반환 로직** | **generate-code API 수정 (previousCode 파라미터 추가), 새 코드 받기 시 이전 예약 자동 해제, team/create page 중복 호출 방지 (isGeneratingCode 체크), 팀 생성 실패 시에도 예약 해제 (catch 블록), GenerateTeamCodeRequest 타입 확장, TeamManager.generateUniqueTeamCode previousCode 파라미터** | **2025-11-19** |
 | **Firebase Cloud Functions Phase 1** | **functions/ 프로젝트 초기화 (Node.js 22, v2 API), 파일 분리 구조 (index.ts export만, 로직 별도 파일), cleanupExpiredReservations (매 시간, 팀 코드 예약 정리), cleanupExpiredDrafts (매일 새벽 3시, 180일 이상 drafts 정리), onTeamDeleted (Firestore Trigger, cascade 삭제), onWritingCreated (Firestore Trigger, 추후 자동 분석), 한글 로그, asia-northeast1 리전, firebase.json predeploy 수정 (lint 제거), 4개 함수 배포 완료** | **2025-11-19** |
+| **주제 생성 Dialog 통합** | **CreateTeamTopicDialog 삭제 (674줄), CreateTopicDialog로 통합 (개인/팀 공용), TopicFormData export (데이터 반환 방식), onSubmit 콜백 패턴 (부모가 topicManager 호출), team.manage.teamTopics.dialog 번역 키 제거 (30개), topicSelector.createSuccess 추가, 652줄 코드 감소, 관심사 분리 (Dialog는 UI만, 비즈니스 로직은 부모)** | **2025-11-21** |
+| **홈 페이지 모듈화** | **HeroSection/QuickActionCard/QuickActionsGrid/ViewAllWritingsCard/EmptyStateCard/RecentActivitySection 컴포넌트 분리 (src/components/home/), 580줄 → 223줄 (62% 감소), Semantic token 적극 활용 (bg/fg/border), Conditional style 객체 최소화, 재사용성 및 유지보수성 향상, JSX 주석 한글화** | **2025-11-21** |
 
 ### 🚧 진행 중
 

TECH_STACK.md

@@ -1,6 +1,6 @@
 # 라온누리 - 기술 스택 및 개발 환경
 
-> 최종 업데이트: 2025-11-20 (AI 이미지 생성 스타일 개선)
+> 최종 업데이트: 2025-11-21 (홈 페이지 모듈화)
 
 ---
 
@@ -653,7 +653,12 @@ if (speedHistory.length > 10) speedHistory.shift();
 
 ### 6. 태그 입력 필드 패턴 (Tag Input Field)
 
-CreateTopicDialog의 제목 템플릿 입력에 사용되는 고급 UI 패턴입니다.
+CreateTopicDialog (개인/팀 공용)의 제목 템플릿 입력에 사용되는 고급 UI 패턴입니다.
+
+**통합 Dialog 설계**:
+- `TopicFormData` export: 입력 데이터만 수집하여 반환
+- `onSubmit` 콜백 패턴: 부모 컴포넌트가 팀/개인 주제 생성 결정
+- **관심사 분리**: Dialog는 UI만 담당, 비즈니스 로직은 부모에게 위임
 
 **구현 방식**:
 ```typescript