# 라온누리 - 프로젝트 구조

> 최종 업데이트: 2025-11-12 (Writing API, 패턴 분석 확장, Content Hash 캐싱)

초등학생을 위한 창작 글쓰기 교육 플랫폼

**최신 업데이트** (2025-11-12):
- ✅ **Writing API 구현 완료**
  - POST /api/writing - 글 생성 (서버에서 wordCount/charCount 자동 계산)
  - GET /api/writing/[id] - 글 조회 (작성자만 접근)
  - PUT /api/writing/[id] - 글 수정 (작성자만 접근)
  - DELETE /api/writing/[id] - 글 삭제 (작성자만 접근)
  - POST /api/writing/user - 사용자 글 목록
  - POST /api/writing/recent - 최근 글 (limit 파라미터)
  - 서버 레이어: `src/lib/server/writing.ts` (Firestore CRUD)
  - WritingManager: 기존 클라이언트 캐싱 유지 (1분~5분)
- 📊 **글 작성 패턴 분석 - 3가지 분석 타입 지원**
  - **self**: 본인의 모든 published 글 분석 (기존)
  - **by-team**: 팀 소유자가 팀원의 팀 내 전체 글 분석 (신규)
  - **by-topic**: 팀 소유자가 특정 주제로 작성된 팀원 글 분석 (신규 - UI만)
  - 권한 체크: 팀 소유자만 팀원 분석 가능, 프라이버시 보호
  - API 파라미터 확장: `analysisType`, `targetUserId`, `topicId`, `teamId`
- 🎯 **WritingPatternDialog 개선**
  - Props 확장: 분석 타입별 파라미터 지원
  - 제목 동적 변경: "OOO 학생의 'XXX' 주제 분석" 등
  - 분석 정보 안내: "이 팀에서 작성된 N개 글 분석" 등
- 🏫 **팀 관리 페이지 UI 추가**
  - 멤버 카드 메뉴에 "팀 내 글 분석" 버튼 (by-team)
  - TopicMemberAnalysisSection 컴포넌트 (by-topic - 추후 구현)
- 🔒 **보안**: 팀 외 글(자유 주제, 다른 팀)은 분석에서 제외
- ⚡ **Content Hash 기반 스마트 캐싱**
  - L1 캐시: localStorage (영구, LRU 10개)
  - L2 캐시: Server in-memory (5분, 50개)
  - 해시 생성: `id:updatedAt` 조합 (SHA-256)
  - 변경 자동 감지: 글 추가/수정 시 해시 변경 → 재분석
  - 성능: 캐시 히트 시 1ms (localStorage) vs 5~10초 (AI 분석)
  - 유틸리티: `contentHash.ts`, `patternCacheManager.ts`

**2025-11-11 (PM) 업데이트**:
- 📊 **글 작성 패턴 분석 시스템**
  - 최근 10개 글을 분석하여 작성 스타일, 강점/약점, 발전 추이 파악
  - AI 기반 종합 평가 및 맞춤형 추천 사항 제공
  - 자주 사용하는 표현, 맞춤법 경향 분석
  - WritingPatternDialog + WritingPatternDisplay 컴포넌트
  - `/api/analyze-pattern` API 엔드포인트 (5분 캐싱)
- ✨ **실시간 하이라이트 시스템** (Tiptap Extensions)
  - SpellingHighlight: 맞춤법 오류를 빨간 물결 밑줄로 표시
  - SensoryWordHighlight: 감각 단어를 색상별 하이라이트 (초록/파랑/보라)
  - 기존 ScoreDisplay/SpellingErrorDisplay 제거 (하이라이트로 대체)
- 💬 **인터랙티브 툴팁 시스템**
  - EditorTooltip: 하이라이트된 단어 클릭 시 상세 정보 표시
  - 맞춤법 오류: 원본 → 수정, 이유 설명
  - 감각 단어: 단어 타입, 격려 메시지
  - Portal + 외부 클릭/ESC 키로 닫기
- 🔔 **Toast 알림 추가** (write 페이지)
  - 텍스트 분석 시작/완료/실패 알림 (점수 표시)
  - 맞춤법 검사 시작/완료/실패 알림 (에러 개수 표시)
  - 로딩 상태 표시 (duration: Infinity)

**2025-11-11 (AM) 업데이트**:
- 🔄 **Google AI SDK 마이그레이션**
  - `@google-cloud/vertexai` → `@google/genai` (최신 SDK)
  - Response Schema 지원 (JSON 응답 강제)
  - Vertex AI 모드 지원 (`vertexai: true`)
- 📊 **텍스트 분석 개편**
  - 평가 기준 재설계: 오감(4점) + 감정(2점) + 대화(2점) + 의성어(2점)
  - `descriptive` → `emotion` 필드 변경
  - 프롬프트 최적화 (칭찬 강화, 제안 0~1개로 제한)
- 📜 **분석 히스토리 시스템**
  - Draft에 `analysisHistory` 추가 (최대 5개)
  - AI가 수정 과정 인식하여 격려
  - 이전 버전 비교 피드백
- ✍️ **맞춤법 검사 서비스** (독립적)
  - Gemini 기반 맞춤법 검사
  - 텍스트 분석과 별도 debounce (5초)
- 🤖 **실시간 피드백 시스템** (Vertex AI 기반)
  - Delta 전송 (토큰 40% 절감)
  - 서버 캐싱 (중복 제거)
- 🌏 **Multi-Region Failover** (가용성 99.9%)
  - 3개 region 자동 전환 (도쿄, 싱가포르, 미국)
  - Region health tracking
  - RPM 3배 증가 (15 → 45)

**2025-11-10 업데이트**:
- ⚠️ 주제 변경 경고 Dialog (내용 초기화 알림, 임시 저장 안내)
- 📝 다중 글조각 관리 시스템 (DraftManager, SavedDraftsDialog)
- 💾 강화된 자동 저장 (2초 debounce, 저장 상태 표시)
- 🎨 테마 슬롯 레시피 추가 (Dialog, Select 자동 배경색)
- 📋 TopicSelector 그룹핑 (자유/팀/개인 주제 구분, 팀 이름 표시)
- 🔐 5단계 보안 레벨 시스템 (팀별 보안 정책 선택)
- 📦 User 타입 분리 (FirestoreUser / User)
- 🏷️ 닉네임 저장 위치 변경 (team.members[uid].nickname)
- 🗑️ memberUids optional (Object.keys(members) 사용)

---

## 페이지 구조

### ✅ 구현 완료

| 페이지 | 경로 | 설명 | 주요 기능 |
|-------|------|------|---------|
| **랜딩 페이지** | `/` | 서비스 소개 및 홍보 (비로그인 전용) | Hero, Features, How It Works, CTA, Footer<br>로그인 시 `/home`으로 자동 리다이렉트 |
| **유저 홈** | `/home` | 인증된 사용자 대시보드 | 환영 메시지, 빠른 시작 대시보드, 최근 활동<br>비로그인 시 `/`로 자동 리다이렉트<br>정식 계정은 "내 팀" 카드 추가 표시 |
| **글쓰기** | `/write` | Tiptap 기반 순수 텍스트 에디터 + 주제 선택 | 주제 선택 (자유 주제/개인 주제/팀 주제)<br>🆕 **주제 변경 경고** (작성 중 내용 초기화 알림, 임시 저장 안내)<br>제목 입력 (Editable), 순수 텍스트 에디터 (포맷팅 없음)<br>🆕 **다중 글조각 관리** (최대 10개), "새 글쓰기" / "저장된 글조각" 버튼<br>🆕 **강화된 자동 저장** (2초 debounce, 저장 상태 표시: 저장 중/저장됨)<br>템플릿 미리채우기 (제목/내용), Firestore 저장<br>비로그인도 접근 가능 (저장 시 로그인 유도) |
| **테스트** | `/test` | 팀 코드 시스템 테스트 페이지 | 팀 코드 생성/검증 테스트<br>팀/학생 생성 테스트<br>학생 로그인 테스트<br>authStore 상태 확인 |
| **팀 목록** | `/team` | 내가 만든 팀 목록 (정식 계정 전용) | 팀 카드 그리드, 팀 정보 (코드, 멤버 수, 보안 설정)<br>"새 팀 만들기" 버튼 |
| **팀 생성** | `/team/create` | 새 팀 만들기 (정식 계정 전용) | 팀 이름 입력, 팀 코드 자동 생성<br>🆕 **5단계 보안 레벨 선택** (RadioCard, 애니메이션)<br>🆕 **명단 관리 (Level 2/4)**: TagsInput으로 Enter/쉼표 입력<br>생성 후 `/team/[teamId]`로 이동 |
| **팀 멤버 페이지** | `/team/[teamId]` | 팀 멤버용 페이지 (멤버/소유자 모두 접근) | 팀 정보, 팀 코드 복사, 멤버 목록<br>소유자는 "팀 관리" 버튼 표시<br>팀 코드 로그인 후 기본 이동 페이지 |
| **팀 관리** | `/team/[teamId]/manage` | 팀 관리 페이지 (소유자 전용) | 팀 정보 및 코드, 보안 설정 표시<br>**팀 주제 관리 (생성/삭제)**<br>🆕 **주제별 학생 분석** (TopicMemberAnalysisSection)<br>멤버 목록 및 관리<br>🆕 **멤버 메뉴 - 팀 내 글 분석** (by-team)<br>"멤버 페이지 보기" 버튼 |

### 🚧 구현 예정

| 페이지 | 경로 | 설명 | 상태 |
|-------|------|------|------|
| **학습하기** | `/learn` | 레슨/코스 학습 | ❌ 미구현 (Navbar 링크만 존재) |
| **스티커** | `/stickers` | 스티커 컬렉션 | ❌ 미구현 (Navbar 링크만 존재) |
| **마이페이지** | Dialog (별도 페이지 없음) | 사용자 대시보드 다이얼로그 | 🔜 계획 중 (UserProfileButton에서 열림) |

---

## 컴포넌트 구조

### 📁 `src/components/auth/` - 인증 관련

| 컴포넌트 | 파일명 | 설명 | 상태 |
|---------|--------|------|------|
| **AuthInitializer** | `AuthInitializer.tsx` | Firebase 인증 상태 초기화 | ✅ 완료 |
| **LoginDialog** | `LoginDialog.tsx` | 로그인/회원가입 다이얼로그 (일반/팀 코드 모드 전환) | ✅ 완료 |
| **StudentLoginFlow** | `StudentLoginFlow.tsx` | 팀 코드 학생 로그인 플로우 (3단계) | ✅ 완료 |
| **LoginForm** | `LoginForm.tsx` | 로그인 폼 컴포넌트 | ✅ 완료 |
| **SignupForm** | `SignupForm.tsx` | 회원가입 폼 컴포넌트 | ✅ 완료 |
| **SocialLoginButton** | `SocialLoginButton.tsx` | 소셜 로그인 버튼 | ✅ 완료 |
| **UserProfileButton** | `UserProfileButton.tsx` | 사용자 프로필/메뉴 버튼 | ✅ 완료 |

**주요 기능**:
- ✅ 이메일/비밀번호 로그인
- ✅ 이메일/비밀번호 회원가입
  - ✅ 이름, 이메일, 비밀번호, 비밀번호 확인 입력
  - ✅ 실시간 비밀번호 강도 게이지
  - ✅ HIBP API 연동 (유출된 비밀번호 차단)
  - ✅ 폼 검증 및 에러 애니메이션
- ✅ Google OAuth 로그인
- ✅ 팀 코드 기반 사용자 로그인 (Anonymous Auth - 단순화됨)
  - ✅ 한글 팀 코드 ("춤추는 파란 사자" 형식)
  - ✅ 사용자 이름 입력 (2단계)
  - ❌ PIN 인증 제거 (복잡도 감소)
  - ✅ UID 기반 통합 인증 (currentStudent 제거)
  - ✅ 팀별 닉네임 시스템
- ✅ 로그인/회원가입 페이드 전환 애니메이션
- ✅ Anonymous ↔ 정식 계정 연결 (UID 유지)
- 🔜 네이버 로그인 (준비 중)
- 🔜 카카오 로그인 (준비 중)

---

### 📁 `src/components/landing/` - 랜딩 페이지

| 컴포넌트 | 파일명 | 설명 | 상태 |
|---------|--------|------|------|
| **FeatureCard** | `FeatureCard.tsx` | 특징 카드 | ✅ 완료 |
| **StepCard** | `StepCard.tsx` | 단계 카드 | ✅ 완료 |
| **SectionHeader** | `SectionHeader.tsx` | 섹션 헤더 | ✅ 완료 |

---

### 📁 `src/components/navigation/` - 네비게이션

| 컴포넌트 | 파일명 | 설명 | 상태 |
|---------|--------|------|------|
| **Navbar** | `Navbar.tsx` | 상단 네비게이션 바 | ✅ 완료 |

**네비게이션 링크**:
- 홈 (`/` 또는 `/home`) - 인증 상태에 따라 동적 변경
  - 비로그인: `/` (랜딩 페이지)
  - 로그인: `/home` (유저 대시보드)
- 글쓰기 (`/write`) - 미구현
- 학습하기 (`/learn`) - 미구현
- 스티커 (`/stickers`) - 미구현

---

### 📁 `src/components/ui/` - UI 기본 컴포넌트

| 컴포넌트 | 파일명 | 설명 | 상태 |
|---------|--------|------|------|
| **Provider** | `provider.tsx` | Chakra UI Provider | ✅ 완료 |
| **ColorMode** | `color-mode.tsx` | 다크모드 토글 | ✅ 완료 |
| **Toaster** | `toaster.tsx` | 토스트 알림 | ✅ 완료 |
| **Tooltip** | `tooltip.tsx` | 툴팁 | ✅ 완료 |

---

### 📁 `src/components/seo/` - SEO

| 컴포넌트 | 파일명 | 설명 | 상태 |
|---------|--------|------|------|
| **StructuredData** | `StructuredData.tsx` | JSON-LD 구조화 데이터 | ✅ 완료 |

---

### 📁 `src/components/writing/` - 글쓰기 에디터

| 컴포넌트 | 파일명 | 설명 | 상태 |
|---------|--------|------|------|
| **WritingEditor** | `WritingEditor.tsx` | Tiptap 기반 순수 텍스트 에디터 (하이라이트 통합) | ✅ 완료 |
| **TopicSelector** | `TopicSelector.tsx` | 주제 선택 드롭다운 (그룹핑, 팀 이름 표시) | ✅ 완료 |
| **EditorTooltip** | `EditorTooltip.tsx` | 🆕 **인터랙티브 툴팁** (맞춤법/감각 단어 클릭 시 표시) | ✅ 완료 |
| **WritingPatternDialog** | `WritingPatternDialog.tsx` | 🆕 **글 작성 패턴 분석 다이얼로그** (최근 10개 글 분석) | ✅ 완료 |
| **WritingPatternDisplay** | `WritingPatternDisplay.tsx` | 🆕 **패턴 분석 결과 표시** (종합 평가, 발전 추이, 강점/약점, 추천) | ✅ 완료 |
| ~~**ScoreDisplay**~~ | ~~`ScoreDisplay.tsx`~~ | ~~실시간 피드백 점수 표시~~ | ❌ 삭제됨 (하이라이트로 대체) |
| ~~**SpellingErrorDisplay**~~ | ~~`SpellingErrorDisplay.tsx`~~ | ~~맞춤법 오류 표시~~ | ❌ 삭제됨 (하이라이트로 대체) |
| **CreateTopicDialog** | `CreateTopicDialog.tsx` | 개인 주제 생성 다이얼로그 (태그 입력 UI) | ✅ 완료 |
| **CreateTeamTopicDialog** | `CreateTeamTopicDialog.tsx` | 팀 주제 생성 다이얼로그 (템플릿 지원) | ✅ 완료 |
| **SavedDraftsDialog** | `SavedDraftsDialog.tsx` | 저장된 글조각 목록 다이얼로그 (불러오기/삭제) | ✅ 완료 |

**주요 기능**:
- ✅ 순수 텍스트 입력 (포맷팅 없음)
- ✅ 초등학생 친화적 단순 인터페이스
- ✅ 실시간 글자 수/단어 수 카운터
- ✅ 🆕 **실시간 하이라이트 시스템** (Tiptap Extensions)
  - ✅ SpellingHighlight: 맞춤법 오류를 빨간 물결 밑줄로 표시
  - ✅ SensoryWordHighlight: 감각 단어를 색상별 하이라이트 (초록/파랑/보라)
  - ✅ 클릭 시 툴팁 표시 (맞춤법: 원본→수정+이유, 감각 단어: 단어 타입+격려)
  - ✅ 브라우저 기본 맞춤법 검사 비활성화 (spellcheck="false")
- ✅ 🆕 **글 작성 패턴 분석** (AI 기반)
  - ✅ 최근 10개 글 종합 분석 (작성 스타일, 표현력, 발전 추이)
  - ✅ 강점/약점 파악, 자주 쓰는 표현 분석
  - ✅ AI 종합 평가 및 맞춤형 추천 사항 3가지
  - ✅ 5분 캐싱 (성능 최적화)
- ✅ **실시간 피드백 시스템** (Gemini 2.5 Flash-Lite)
  - ✅ 텍스트 분석 (오감/감정/대화/의성어 평가)
  - ✅ 5초 debounce + Delta 전송 (토큰 40% 절감)
  - ✅ Toast 알림 (시작/완료/실패, 점수 표시)
  - ✅ Multi-region failover (가용성 99.9%)
- ✅ **맞춤법 검사** (독립적, Gemini 기반)
  - ✅ 초등학생 눈높이 설명
  - ✅ 5초 debounce (텍스트 분석과 별도)
  - ✅ Toast 알림 (에러 개수 표시)
- ✅ **주제 변경 경고 Dialog** (작성 중 내용 초기화 알림 + 임시 저장 안내)
- ✅ **다중 글조각 관리** (최대 10개, FIFO 방식)
- ✅ **강화된 자동 저장** (2초 debounce, localStorage)
- ✅ **저장 상태 표시** (저장 중 → 저장됨 → 시간 표시)
- ✅ "새 글쓰기" 버튼 (현재 글 초기화)
- ✅ "저장된 글조각" Dialog (목록, 미리보기, 불러오기/삭제)
- ✅ **주제 선택 그룹핑** (자유/팀/개인 주제 구분, ItemGroup 사용)
- ✅ **팀 주제에 팀 이름 표시** (어느 팀의 주제인지 명확히 표시)
- ✅ 주제 선택 (자유 주제/팀 주제/개인 주제)
- ✅ 주제 정보 표시 (설명, 키워드, 예시 질문)
- ✅ 템플릿 미리채우기 (제목/내용)
- ✅ 개인 주제 생성 (카테고리, 난이도, 키워드, 템플릿 설정)
- ✅ 팀 주제 생성 (팀 소유자 전용, 팀 관리 페이지)
- ✅ 태그 입력 필드 UI (제목 템플릿: 방향키 네비게이션, Backspace/Delete 삭제)

---

### 📁 `src/extensions/` - Tiptap Extensions

| Extension | 파일명 | 설명 | 상태 |
|-----------|--------|------|------|
| **SpellingHighlight** | `spelling-highlight.ts` | 🆕 **맞춤법 오류 하이라이트** (빨간 물결 밑줄, data attributes) | ✅ 완료 |
| **SensoryWordHighlight** | `sensory-word-highlight.ts` | 🆕 **감각 단어 하이라이트** (색상별 표시: 초록/파랑/보라) | ✅ 완료 |

**주요 기능**:
- ✅ Tiptap ProseMirror Plugin 기반
- ✅ DecorationSet을 사용한 효율적인 하이라이트
- ✅ Meta를 통한 강제 업데이트 지원
- ✅ data attributes로 툴팁 정보 전달
- ✅ 실시간 텍스트 변경 추적

**하이라이트 종류**:
- **SpellingHighlight**: 맞춤법 오류 (빨간 물결 밑줄)
  - `spelling-error` 클래스
  - data-original, data-correction, data-reason 속성
- **SensoryWordHighlight**: 감각 단어 (색상별)
  - `sensory-word` (감각 동사, 초록색)
  - `emotion-word` (감각 형용사, 파란색)
  - `onomatopoeia-word` (의성어/의태어, 보라색)
  - data-word, data-type 속성

---

### 📁 `src/components/team/` - 팀 관리

| 컴포넌트 | 파일명 | 설명 | 상태 |
|---------|--------|------|------|
| **TeamTopicManager** | `TeamTopicManager.tsx` | 팀 주제 목록 및 생성/삭제 UI | ✅ 완료 |
| **SecurityLevelSelector** | `SecurityLevelSelector.tsx` | 5단계 보안 레벨 선택 (RadioCard, framer-motion 애니메이션) | ✅ 완료 |
| **AllowListManager** | `AllowListManager.tsx` | 명단 관리 (이름/이메일 추가/제거, TagsInput) | ✅ 완료 |
| **TopicMemberAnalysisSection** | `TopicMemberAnalysisSection.tsx` | 🆕 주제별 학생 글쓰기 분석 (Accordion, by-topic 분석) | 🚧 UI만 (API 추후 구현) |

**주요 기능** (2025-11-10):
- ✅ SecurityLevelSelector: RadioCard 기반, 선택 시 추가 UI 애니메이션으로 표시
- ✅ AllowListManager: Level 2/4용 명단 관리, Enter/쉼표로 구분 입력
- ✅ 그라데이션 배경 (RadioCard와 자연스럽게 연결)
- ✅ react-icons/lu 사용 (이모티콘 제거)

---

### 📁 예정된 컴포넌트 디렉토리

| 디렉토리 | 설명 | 컴포넌트 |
|---------|------|--------------|
| `lesson/` | 학습 관련 | LessonCard, LessonContent, QuizSection, ProgressBar, LevelBadge |
| `sticker/` | 스티커 관련 | StickerGrid, StickerCard, StickerDetail, StickerStats, LockedSticker |
| `level/` | 레벨 시스템 | LevelBadge, LevelUpModal, ExperienceBar |
| `profile/` | **프로필 Dialog** | **ProfileDialog (탭: 내정보, 내글, 통계, 설정)**, ProfileCard, StatsWidget, WritingHistory |
| `notification/` | 알림 시스템 | NotificationBell, NotificationList, NotificationItem |
| `admin/` | 관리자 | TopicManager, UserManager, ContentEditor |

**Notes**:
- `profile/` 디렉토리는 Dialog 기반으로 구현됩니다. UserProfileButton 클릭 시 ProfileDialog가 열립니다.

---

## 비즈니스 로직 레이어

### 📁 `src/managers/` - Manager 패턴 (API 호출 + 클라이언트 캐싱)

| Manager | 파일명 | 설명 | 상태 |
|---------|--------|------|------|
| **ManagerBase** | `ManagerBase.ts` | 공통 기능 (authenticatedFetch, API 호출, 캐싱) | ✅ 완료 |
| **TeamManager** | `TeamManager.ts` | 팀 관련 API 호출 (생성, 조회, 수정, 삭제, 멤버 관리) | ✅ 완료 |
| **UserManager** | `UserManager.ts` | 사용자 관련 API 호출 (생성, 조회, 수정, 닉네임 관리) **[NEW]** | ✅ 완료 |
| **DraftManager** | `DraftManager.ts` | 🆕 글조각 관리 (localStorage 기반, 최대 10개, CRUD) | ✅ 완료 |
| ~~**StudentManager**~~ | ~~`StudentManager.ts`~~ | ~~학생 관련 API 호출~~ | ⚠️ Deprecated (UserManager로 대체) |
| **WritingManager** | `WritingManager.ts` | 글쓰기 관련 비즈니스 로직 (CRUD, 통계) | ✅ 완료 |
| **TopicManager** | `TopicManager.ts` | 주제 관련 비즈니스 로직 (CRUD, 템플릿 처리) | ✅ 완료 |
| **index.ts** | `index.ts` | 모든 매니저 export | ✅ 완료 |
| **LevelManager** | `LevelManager.ts` | 레벨/경험치 관리 | ❌ 미구현 |
| **StickerManager** | `StickerManager.ts` | 스티커 획득/관리 | ❌ 미구현 |

**주요 기능**:
- ✅ **싱글톤 패턴**으로 전역 인스턴스 관리
- ✅ **HTTP API 호출**: Next.js API Routes로 서버 로직 분리
- ✅ **클라이언트 사이드 캐싱**: in-memory 캐싱 (TTL 기반)
- ✅ **자동 캐시 무효화**: 변경 작업 시 관련 캐시 삭제
- ✅ **인증 자동 처리**: ID Token 자동 헤더 추가
- ✅ **타입 안전성**: Request/Response 타입 완전 정의
- ✅ **비즈니스 로직과 UI 레이어 분리**

### 📁 `src/services/` - 데이터 레이어 (일부 deprecated)

| 서비스 | 파일명 | 설명 | 상태 |
|-------|--------|------|------|
| **Firebase Auth** | `firebaseAuth.ts` | 인증 서비스 (로그인, 회원가입, 소셜, Anonymous, 계정 연결) | ✅ 완료 (단순화됨) |
| **Firestore** | `firestore.ts` | Firestore CRUD 헬퍼 함수 (WritingManager에서 사용) | ✅ 완료 |
| **Vertex AI** | `vertexAI.ts` | **Gemini API 범용 래퍼** (`@google/genai`, Multi-region failover, Response Schema) | ✅ 완료 |
| **Text Analysis** | `textAnalysisService.ts` | **텍스트 분석 서비스** (평가 기준 개편, 히스토리 기반 분석) | ✅ 완료 |
| **Pattern Analysis** | `patternAnalysisService.ts` | 🆕 **글 작성 패턴 분석 서비스** (10개 글 종합 분석, AI 평가) | ✅ 완료 |
| **Spelling Check** | `spellingService.ts` | **맞춤법 검사 서비스** (Gemini 기반, 초등학생 눈높이) | ✅ 완료 |
| **Region Health** | `regionHealthManager.ts` | **Region 과부하 상태 추적** (자동 복구, 1분 TTL) | ✅ 완료 |
| ~~**Team Service**~~ | ~~`teamService.ts`~~ | ~~팀 CRUD, 팀 코드 생성~~ | ⚠️ Deprecated (TeamManager로 이동) |
| ~~**Student Service**~~ | ~~`studentService.ts`~~ | ~~학생 CRUD, PIN 해시/검증~~ | ⚠️ Deprecated (UserManager로 대체) |
| **Level System** | `levelSystem.ts` | 레벨/경험치 계산 로직 | ❌ 미구현 |
| **Sticker System** | `stickerSystem.ts` | 스티커 획득 조건 엔진 | ❌ 미구현 |

**마이그레이션 완료**:
- ✅ **teamService.ts** → **TeamManager** (API 호출 방식)
- ✅ **studentService.ts** → **UserManager** (UID 기반 단순화)
- ✅ **students 컬렉션** → **users 컬렉션** (UID 기반)
- ✅ Firestore 직접 접근 → HTTP API 호출로 전환
- ✅ PIN 기능 제거, 팀별 닉네임 시스템 추가

### 📁 `src/types/` - 타입 정의

| 타입 | 파일명 | 설명 | 상태 |
|------|--------|------|------|
| **Team 타입** | `team.ts` | 팀 데이터 모델 (members Map), **TeamSecurityLevel Enum (1-5)** | ✅ 완료 |
| **FirestoreUser 타입** | `firestoreUser.ts` | **FirestoreUser** (DB 저장용), **User** (UI용) 분리 | ✅ 완료 |
| **Draft 타입** | `draft.ts` | 글조각 데이터 모델 (Draft, DraftListItem, **AnalysisHistoryItem**) | ✅ 완료 |
| **WritingPattern 타입** | `writingPattern.ts` | 🆕 **글 작성 패턴 분석** 데이터 모델 (WritingPatternAnalysis) | ✅ 완료 |
| ~~**User 타입**~~ | ~~`user.ts`~~ | ~~사용자 데이터 모델~~ | ⚠️ Deprecated (firestoreUser.ts로 변경) |
| ~~**Student 타입**~~ | ~~`student.ts`~~ | ~~학생 데이터 모델~~ | ⚠️ Deprecated (user.ts로 대체) |
| **Topic 타입** | `topic.ts` | 주제 데이터 모델, TopicCategory/Difficulty/OwnerType Enum, 팀 주제 유틸 함수 | ✅ 완료 |
| **API 공통 타입** | `api.ts` | ApiResponse, ApiError, HttpMethod Enum | ✅ 완료 |
| **Team API 타입** | `api/team.ts` | 팀 API Request/Response (add/removeMember 추가, requirePin 제거) | ✅ 완료 |
| **User API 타입** | `api/user.ts` | 사용자 API Request/Response (닉네임 관리 포함) | ✅ 완료 |
| ~~**Student API 타입**~~ | ~~`api/student.ts`~~ | ~~학생 API Request/Response~~ | ⚠️ Deprecated (api/user.ts로 대체) |
| **Topic API 타입** | `api/topic.ts` | 주제 API Request/Response (9개 엔드포인트, 팀 주제 포함) | ✅ 완료 |

---

### 📁 `src/utils/` - 유틸리티 함수

| 유틸리티 | 파일명 | 설명 | 상태 |
|---------|--------|------|------|
| **Korean Word List** | `koreanWordList.ts` | 한글 감각 동사/형용사 목록 (점수 가중치, 영역 변환 함수) | ✅ 완료 |
| **Team Code Generator** | `teamCodeGenerator.ts` | 한글 팀 코드 생성 (형용사 + 색깔 + 동물) | ✅ 완료 |
| **Password Security** | `passwordSecurity.ts` | HIBP API 연동 (유출된 비밀번호 차단) | ✅ 완료 |
| **Password Strength** | `passwordStrength.ts` | 비밀번호 강도 계산 | ✅ 완료 |
| **Content Hash** | `contentHash.ts` | 🆕 **SHA-256 해시 생성** (글 목록 → 해시, id+updatedAt 조합, 서버/클라이언트 지원) | ✅ 완료 |
| **Pattern Cache Manager** | `patternCacheManager.ts` | 🆕 **패턴 분석 localStorage 캐싱** (LRU 최대 10개, 캐시 통계) | ✅ 완료 |

---

### 📁 `src/app/api/` - API Routes

| API | 경로 | 메서드 | 설명 | 상태 |
|-----|------|--------|------|------|
| **텍스트 분석** | `/api/analyze-text` | POST | **Gemini 기반 텍스트 분석** (Delta 지원, 캐싱, 히스토리 인식) | ✅ 완료 |
| **패턴 분석** | `/api/analyze-pattern` | POST | **글 작성 패턴 분석** (3가지 타입, contentHash 기반 2단계 캐싱, 변경 감지) | ✅ 완료 |
| **맞춤법 검사** | `/api/spelling/check` | POST | **Gemini 기반 맞춤법 검사** (초등학생 눈높이) | ✅ 완료 |
| **글 생성** | `/api/writing` | POST | 🆕 **글 생성** (wordCount/charCount 자동 계산) | ✅ 완료 |
| **글 조회** | `/api/writing/[id]` | GET | 🆕 **글 조회** (작성자만 접근) | ✅ 완료 |
| **글 수정** | `/api/writing/[id]` | PUT | 🆕 **글 수정** (작성자만 접근, 통계 재계산) | ✅ 완료 |
| **글 삭제** | `/api/writing/[id]` | DELETE | 🆕 **글 삭제** (작성자만 접근) | ✅ 완료 |
| **사용자 글 목록** | `/api/writing/user` | POST | 🆕 **사용자 글 목록** (userId 선택적, 본인 글만) | ✅ 완료 |
| **최근 글** | `/api/writing/recent` | POST | 🆕 **최근 글** (limit 파라미터, 기본 5개) | ✅ 완료 |
| **팀 CRUD** | `/api/team` | GET, POST, PUT, DELETE | 팀 생성/조회/수정/삭제 | ✅ 완료 |
| **팀 보안 레벨** | `/api/team/[teamId]/security-level` | POST | 보안 레벨 변경 | ✅ 완료 |
| **명단 관리** | `/api/team/[teamId]/allowed-names` | POST, DELETE | 허용 이름 추가/제거 | ✅ 완료 |
| **이메일 관리** | `/api/team/[teamId]/allowed-emails` | POST, DELETE | 허용 이메일 추가/제거 | ✅ 완료 |
| **주제 CRUD** | `/api/topic` | GET, POST, PUT, DELETE | 주제 생성/조회/수정/삭제 (9개 엔드포인트) | ✅ 완료 |
| **사용자 관리** | `/api/user` | GET, POST, PUT | 사용자 조회/생성/업데이트 | ✅ 완료 |

**서버 레이어** (`src/lib/server/`):
- `team.ts` - 팀 Firestore CRUD
- `user.ts` - 사용자 Firestore CRUD
- `topic.ts` - 주제 Firestore CRUD
- 🆕 `writing.ts` - 글 Firestore CRUD (createWriting, getWriting, updateWriting, deleteWriting, getUserWritings, getRecentWritings, isWritingOwner)

---

## 상태 관리 (Zustand)

### 📁 `src/store/`

| 스토어 | 파일명 | 설명 | 상태 |
|-------|--------|------|------|
| **Auth Store** | `authStore.ts` | 인증 상태 및 로그인 다이얼로그 (단순화됨) | ✅ 완료 |
| **User Progress Store** | `userProgressStore.ts` | 사용자 진행 상황 (레벨, XP) | ❌ 미구현 |
| **Notification Store** | `notificationStore.ts` | 알림 상태 | ❌ 미구현 |

**Auth Store 아키텍처 (2025-11-07 단순화)**:
- ✅ **user** - Firebase Auth 기반 통합 사용자 (익명 + 정식 계정)
- ✅ **isAuthenticated** - 로그인 여부 (익명 포함)
- ✅ **user.isAnonymous** - 익명/정식 계정 구분
- ✅ **loginAsUser()** - 팀 코드 로그인 (PIN 제거)
- ✅ **linkWithEmail()** - 이메일 계정 연결
- ✅ **linkWithGoogle()** - Google 계정 연결
- ❌ ~~currentStudent~~, ~~ownedStudents~~, ~~switchStudent()~~ 제거 (복잡도 감소)

---

## 설정 파일

### 📁 `src/config/`

| 파일 | 설명 | 상태 |
|------|------|------|
| `firebase.ts` | Firebase 초기화 및 설정 | ✅ 완료 |
| `site.ts` | 사이트 메타데이터 및 설정 | ✅ 완료 |

---

## 디렉토리 구조 요약

```
src/
├── app/                          # Next.js App Router
│   ├── layout.tsx               # 루트 레이아웃
│   ├── page.tsx                 # 랜딩 페이지 (/) - 로그인 시 /home 리다이렉트
│   ├── home/
│   │   └── page.tsx            # ✅ 유저 홈 페이지 (/home)
│   ├── write/
│   │   └── page.tsx            # ✅ 글쓰기 페이지 (/write)
│   ├── test/
│   │   └── page.tsx            # ✅ 테스트 페이지 (/test) - 팀 코드 시스템 테스트
│   ├── globals.css
│   ├── favicon.ico
│   ├── team/                   # ✅ 팀 관리 페이지들
│   │   ├── page.tsx            # ✅ 팀 목록 (/team)
│   │   ├── create/
│   │   │   └── page.tsx        # ✅ 팀 생성 (/team/create)
│   │   └── [teamId]/
│   │       ├── page.tsx        # ✅ 팀 멤버 페이지 (/team/[teamId])
│   │       └── manage/
│   │           └── page.tsx    # ✅ 팀 관리 페이지 (/team/[teamId]/manage)
│   └── [미구현 페이지들]
│       ├── learn/               # 학습 페이지
│       ├── stickers/            # 스티커 페이지
│       └── admin/               # 관리자
│
├── components/                  # React 컴포넌트
│   ├── auth/                   # ✅ 인증 (로그인, 프로필, 팀 코드)
│   ├── landing/                # ✅ 랜딩 페이지 카드들
│   ├── navigation/             # ✅ 네비게이션 바
│   ├── seo/                    # ✅ SEO 컴포넌트
│   ├── ui/                     # ✅ Chakra UI 기본
│   ├── writing/                # ✅ 글쓰기 에디터
│   │   ├── WritingEditor.tsx   # 순수 텍스트 에디터 (포맷팅 없음)
│   │   ├── TopicSelector.tsx   # ✅ 주제 선택 컴포넌트 (팀/개인 배지)
│   │   ├── CreateTopicDialog.tsx      # ✅ 개인 주제 생성
│   │   └── CreateTeamTopicDialog.tsx  # ✅ 팀 주제 생성
│   ├── team/                   # ✅ 팀 관련
│   │   ├── TeamTopicManager.tsx       # ✅ 팀 주제 관리
│   │   ├── SecurityLevelSelector.tsx  # 🆕 보안 레벨 선택 (RadioCard, 애니메이션)
│   │   └── AllowListManager.tsx       # 🆕 명단 관리 (TagsInput)
│   └── [미구현]
│       ├── lesson/             # 학습 컴포넌트
│       ├── sticker/            # 스티커 컴포넌트
│       ├── level/              # 레벨 시스템
│       ├── profile/            # 프로필 컴포넌트
│       ├── notification/       # 알림 컴포넌트
│       └── admin/              # 관리자 컴포넌트
│
├── config/                     # ✅ 설정
│   ├── firebase.ts
│   └── site.ts
│
├── managers/                   # ✅ 비즈니스 로직 (Manager 패턴)
│   ├── ManagerBase.ts          # 기본 Manager 클래스
│   ├── WritingManager.ts       # 글쓰기 관리
│   ├── TopicManager.ts         # ✅ 주제 관리
│   └── [미구현]
│       ├── LevelManager.ts
│       └── StickerManager.ts
│
├── data/                       # ✅ 정적 데이터
│   └── classCodeWords.ts       # ✅ 한글 팀 코드 단어 (형용사, 색상, 동물)
│
├── services/                   # 데이터 레이어 (Firestore/API 호출)
│   ├── firebaseAuth.ts         # ✅ 인증 (이메일, Google, Anonymous)
│   ├── classroomService.ts     # ✅ 클래스룸 CRUD
│   ├── studentService.ts       # ✅ 학생 CRUD, PIN 관리
│   ├── firestore.ts            # ✅ Firestore CRUD
│   └── [미구현]
│       ├── levelSystem.ts
│       └── stickerSystem.ts
│
├── store/                      # Zustand 상태 관리
│   ├── authStore.ts            # ✅ 인증 상태 (currentStudent 중심)
│   └── [미구현]
│       ├── userProgressStore.ts
│       └── notificationStore.ts
│
├── theme/                      # ✅ Chakra UI 테마
│   └── system.ts
│
├── types/                      # TypeScript 타입
│   ├── topic.ts                # ✅ 주제 관련 타입 (Enum + 유틸 함수)
│   ├── team.ts                 # ✅ 팀 관련 타입 (Enum)
│   ├── student.ts              # ✅ 학생 타입
│   ├── api/                    # ✅ API Request/Response 타입
│   │   ├── topic.ts            # ✅ 주제 API (팀/개인 주제)
│   │   ├── team.ts             # ✅ 팀 API
│   │   └── student.ts          # ✅ 학생 API
│   └── [미구현]
│
└── utils/                      # 유틸리티 함수
    ├── passwordStrength.ts     # ✅ 비밀번호 강도 계산
    ├── passwordSecurity.ts     # ✅ HIBP API 연동
    └── classCodeGenerator.ts   # ✅ 팀 코드 생성/검증/정규화
```

---

## 다음 구현 단계

### Phase 1: 핵심 기능 (현재)
1. ✅ 프로젝트 설정 및 인프라
2. ✅ 인증 시스템 (로그인)
3. ✅ 랜딩 페이지
4. ✅ 회원가입 기능 (페이드 전환 + HIBP 보안 검증)
5. ✅ 인증 기반 라우팅 (`/`와 `/home` 분리)
6. ✅ 글쓰기 페이지 (Tiptap 에디터, LocalStorage 자동 저장, Firestore 저장)
7. ✅ 주제 선택 및 관리 (자유/개인 주제, 템플릿)
8. ✅ **팀 코드 시스템** (완료)
   - ✅ 한글 팀 코드 생성 ("춤추는 파란 사자")
   - ✅ Anonymous Auth 학생 로그인
   - ✅ 팀/학생 관리 서비스 (ownerId 기반)
   - ✅ PIN 인증 (SHA-256)
   - ✅ 정식 계정 연결 (linkWithCredential)
   - ✅ currentStudent 중심 authStore 재설계
   - ✅ 학생 로그인 UI (3단계 플로우, 이름 입력, 완료 화면)
   - ✅ 팀 관리 UI (목록/생성/멤버 페이지/관리 페이지)
   - ✅ 용어 변경: "클래스" → "팀", "교사" → "소유자"
9. 🚧 **다음**: 내가 쓴 글 목록

### Phase 2: 팀 코드 UI 완성
- 학생 로그인 UI (팀 코드 입력 → 이름 선택 → PIN)
- 팀 관리 (팀 생성, 멤버 관리)
- LoginDialog에 학생 탭 추가

### Phase 3: 학습 시스템
- `/learn` 학습 페이지
- 레슨 콘텐츠 및 진행 상황

### Phase 4: 게임화
- 레벨업 시스템
- `/stickers` 스티커 페이지

### Phase 5: 사용자 경험
- ProfileDialog 마이페이지 (Dialog 형식)
- 검색 및 알림

### Phase 6: 고급 기능
- 부모님 모드 (계정 연결)
- 관리자 패널

---

## 관련 문서

- [TECH_STACK.md](./TECH_STACK.md) - 기술 스택 및 개발 환경 설정
- [DATA_MODELS.md](./DATA_MODELS.md) - 데이터베이스 스키마 및 타입 정의
- [ROADMAP.md](./ROADMAP.md) - 개발 우선순위 및 로드맵
- [CLAUDE.md](./CLAUDE.md) - Claude Code 작업 가이드

---

© 2024 BlueNovaLab. All rights reserved.