docs: Sync documentation from private repository

PROJECT_STRUCTURE.md

@@ -1,22 +1,34 @@
 # 라온누리 - 프로젝트 구조
 
-> 최종 업데이트: 2025-11-11 (실시간 피드백 시스템, Multi-Region Failover)
+> 최종 업데이트: 2025-11-11 (Google AI SDK 마이그레이션, 분석 히스토리, 맞춤법 검사)
 
 초등학생을 위한 창작 글쓰기 교육 플랫폼
 
 **주요 업데이트** (2025-11-11):
+- 🔄 **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 기반 맞춤법 검사
+  - SpellingErrorDisplay 컴포넌트
+  - 텍스트 분석과 별도 debounce (5초)
 - 🤖 **실시간 피드백 시스템** (Vertex AI 기반)
-  - ScoreDisplay 컴포넌트 (점수, 영역 개수, 찾은 단어, 수정 제안)
+  - ScoreDisplay 컴포넌트 (점수, 찾은 단어, 수정 제안)
   - Delta 전송 (토큰 40% 절감)
   - 서버 캐싱 (중복 제거)
 - 🌏 **Multi-Region Failover** (가용성 99.9%)
   - 3개 region 자동 전환 (도쿄, 싱가포르, 미국)
   - Region health tracking
   - RPM 3배 증가 (15 → 45)
-- 🔧 **서비스 레이어 분리**
-  - vertexAI.ts (범용 Vertex AI 래퍼)
-  - textAnalysisService.ts (텍스트 분석 로직)
-  - regionHealthManager.ts (Region 상태 관리)
 
 **2025-11-10 업데이트**:
 - ⚠️ 주제 변경 경고 Dialog (내용 초기화 알림, 임시 저장 안내)
@@ -142,7 +154,8 @@
 |---------|--------|------|------|
 | **WritingEditor** | `WritingEditor.tsx` | Tiptap 기반 순수 텍스트 에디터 | ✅ 완료 |
 | **TopicSelector** | `TopicSelector.tsx` | 🆕 주제 선택 드롭다운 (그룹핑, 팀 이름 표시) | ✅ 완료 |
-| **ScoreDisplay** | `ScoreDisplay.tsx` | 🆕 **실시간 피드백 점수 표시** (Vertex AI 기반) | ✅ 완료 |
+| **ScoreDisplay** | `ScoreDisplay.tsx` | 🆕 **실시간 피드백 점수 표시** (Gemini 기반) | ✅ 완료 |
+| **SpellingErrorDisplay** | `SpellingErrorDisplay.tsx` | 🆕 **맞춤법 오류 표시** (Gemini 기반, 별도 독립) | ✅ 완료 |
 | **CreateTopicDialog** | `CreateTopicDialog.tsx` | 개인 주제 생성 다이얼로그 (태그 입력 UI) | ✅ 완료 |
 | **CreateTeamTopicDialog** | `CreateTeamTopicDialog.tsx` | 팀 주제 생성 다이얼로그 (템플릿 지원) | ✅ 완료 |
 | **SavedDraftsDialog** | `SavedDraftsDialog.tsx` | 🆕 저장된 글조각 목록 다이얼로그 (불러오기/삭제) | ✅ 완료 |
@@ -151,13 +164,17 @@
 - ✅ 순수 텍스트 입력 (포맷팅 없음)
 - ✅ 초등학생 친화적 단순 인터페이스
 - ✅ 실시간 글자 수/단어 수 카운터
-- ✅ 🆕 **실시간 피드백 시스템** (Vertex AI 기반)
+- ✅ 🆕 **실시간 피드백 시스템** (Gemini 2.5 Flash-Lite)
-  - ✅ 점수 표시 (0~10점)
+  - ✅ 점수 표시 (0~10점, 개편된 평가 기준)
-  - ✅ 왜곡 영역 개수 (1~5개)
+  - ✅ 찾은 표현 목록 (오감, 감정, 의성어/의태어)
-  - ✅ 찾은 감각 단어 목록 (동사, 형용사, 의성어)
+  - ✅ 분석 히스토리 추적 (이전 버전 비교, 발전 과정 격려)
-  - ✅ AI 수정 제안
+  - ✅ 스마트 제안 (칭찬 강화, 제안 0~1개)
   - ✅ 5초 debounce + Delta 전송 (토큰 40% 절감)
   - ✅ Multi-region failover (가용성 99.9%)
+- ✅ 🆕 **맞춤법 검사** (독립적, Gemini 기반)
+  - ✅ 초등학생 눈높이 설명
+  - ✅ 5초 debounce (텍스트 분석과 별도)
+  - ✅ 오류 목록 표시 (원본 → 수정, 이유)
 - ✅ 🆕 **주제 변경 경고 Dialog** (작성 중 내용 초기화 알림 + 임시 저장 안내)
 - ✅ 🆕 **다중 글조각 관리** (최대 10개, FIFO 방식)
 - ✅ 🆕 **강화된 자동 저장** (2초 debounce, localStorage)
@@ -239,8 +256,9 @@
 |-------|--------|------|------|
 | **Firebase Auth** | `firebaseAuth.ts` | 인증 서비스 (로그인, 회원가입, 소셜, Anonymous, 계정 연결) | ✅ 완료 (단순화됨) |
 | **Firestore** | `firestore.ts` | Firestore CRUD 헬퍼 함수 (WritingManager에서 사용) | ✅ 완료 |
-| **Vertex AI** | `vertexAI.ts` | 🆕 **Vertex AI 범용 래퍼** (Multi-region failover, Retry) | ✅ 완료 |
+| **Vertex AI** | `vertexAI.ts` | 🆕 **Gemini API 범용 래퍼** (`@google/genai`, Multi-region failover, Response Schema) | ✅ 완료 |
-| **Text Analysis** | `textAnalysisService.ts` | 🆕 **텍스트 분석 서비스** (초등학생 글쓰기 평가) | ✅ 완료 |
+| **Text Analysis** | `textAnalysisService.ts` | 🆕 **텍스트 분석 서비스** (평가 기준 개편, 히스토리 기반 분석) | ✅ 완료 |
+| **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로 대체) |
@@ -260,7 +278,7 @@
 |------|--------|------|------|
 | **Team 타입** | `team.ts` | 🆕 팀 데이터 모델 (members Map), **TeamSecurityLevel Enum (1-5)** | ✅ 완료 |
 | **FirestoreUser 타입** | `firestoreUser.ts` | 🆕 **FirestoreUser** (DB 저장용), **User** (UI용) 분리 | ✅ 완료 |
-| **Draft 타입** | `draft.ts` | 🆕 글조각 데이터 모델 (Draft, DraftListItem) | ✅ 완료 |
+| **Draft 타입** | `draft.ts` | 🆕 글조각 데이터 모델 (Draft, DraftListItem, **AnalysisHistoryItem**) | ✅ 완료 |
 | ~~**User 타입**~~ | ~~`user.ts`~~ | ~~사용자 데이터 모델~~ | ⚠️ Deprecated (firestoreUser.ts로 변경) |
 | ~~**Student 타입**~~ | ~~`student.ts`~~ | ~~학생 데이터 모델~~ | ⚠️ Deprecated (user.ts로 대체) |
 | **Topic 타입** | `topic.ts` | 주제 데이터 모델, TopicCategory/Difficulty/OwnerType Enum, 팀 주제 유틸 함수 | ✅ 완료 |
@@ -287,7 +305,8 @@
 
 | API | 경로 | 메서드 | 설명 | 상태 |
 |-----|------|--------|------|------|
-| **텍스트 분석** | `/api/analyze-text` | POST | 🆕 **Vertex AI 기반 텍스트 분석** (Delta 지원, 캐싱) | ✅ 완료 |
+| **텍스트 분석** | `/api/analyze-text` | POST | 🆕 **Gemini 기반 텍스트 분석** (Delta 지원, 캐싱, 히스토리 인식) | ✅ 완료 |
+| **맞춤법 검사** | `/api/spelling/check` | POST | 🆕 **Gemini 기반 맞춤법 검사** (초등학생 눈높이) | ✅ 완료 |
 | **팀 CRUD** | `/api/team` | GET, POST, PUT, DELETE | 팀 생성/조회/수정/삭제 | ✅ 완료 |
 | **팀 보안 레벨** | `/api/team/[teamId]/security-level` | POST | 보안 레벨 변경 | ✅ 완료 |
 | **명단 관리** | `/api/team/[teamId]/allowed-names` | POST, DELETE | 허용 이름 추가/제거 | ✅ 완료 |

ROADMAP.md

@@ -72,6 +72,10 @@
 | **Multi-Region Failover** | **3개 region 자동 전환 (도쿄/싱가포르/미국), Region health tracking, Exponential backoff, RPM 3배 증가 (15→45)** | **2025-11-11** |
 | **서비스 레이어 분리** | **vertexAI.ts (범용 래퍼), textAnalysisService.ts (분석 로직), regionHealthManager.ts (상태 관리)** | **2025-11-11** |
 | **문서화 완료** | **TECHNICAL_IMPLEMENTATION.md, SERVICE_DIRECTION.md 전면 개편 (Vertex AI 기반)** | **2025-11-11** |
+| **Google AI SDK 마이그레이션** | **`@google-cloud/vertexai` → `@google/genai` (v1.29.0), Response Schema 지원, Gemini 2.0+ 기능** | **2025-11-11** |
+| **텍스트 분석 평가 기준 개편** | **오감(4점) + 감정(2점) + 대화(2점) + 의성어(2점), `descriptive` → `emotion`, 프롬프트 최적화 (칭찬 강화, 제안 0~1개)** | **2025-11-11** |
+| **분석 히스토리 시스템** | **Draft.analysisHistory 추가 (최대 5개), AI가 수정 과정 인식, 이전 버전 비교 피드백** | **2025-11-11** |
+| **맞춤법 검사 서비스** | **spellingService.ts (Gemini 기반), SpellingErrorDisplay 컴포넌트, 독립적 debounce (5초)** | **2025-11-11** |
 
 ### 🚧 진행 중
 

TECHNICAL_IMPLEMENTATION.md

@@ -119,7 +119,7 @@ export async function POST(req: NextRequest) {
   }
 
   // Vertex AI 분석
-  const model = vertex.getGenerativeModel({ model: "gemini-2.5-flash" });
+  const model = vertex.getGenerativeModel({ model: "gemini-2.5-flash-lite" });
   const prompt = `초등학생 글을 분석하여 감각 동사, 형용사, 대화, 의성어를 평가하세요.
 
 평가 기준:
@@ -406,7 +406,7 @@ const AVAILABLE_REGIONS = [
 
 export async function generateContent(
   prompt: string,
-  modelName: string = "gemini-2.5-flash"
+  modelName: string = "gemini-2.5-flash-lite"
 ): Promise<string> {
   const maxRetries = 3;
 

TECH_STACK.md

@@ -1,6 +1,6 @@
 # 라온누리 - 기술 스택 및 개발 환경
 
-> 최종 업데이트: 2025-11-11 (실시간 피드백 시스템, Multi-Region Failover)
+> 최종 업데이트: 2025-11-11 (Google AI SDK 마이그레이션, 분석 히스토리, 맞춤법 검사)
 
 ---
 
@@ -31,9 +31,15 @@
 | **Firebase** | 12.4.0 | BaaS (Backend as a Service) |
 | **Firebase Auth** | - | 사용자 인증 |
 | **Firestore** | - | NoSQL 데이터베이스 (글 저장) |
-| **Vertex AI** | latest | 🆕 **AI 텍스트 분석** (Gemini 2.5 Flash) |
+| **@google/genai** | 1.29.0 | 🆕 **Google Gemini API SDK** (텍스트 분석, 맞춤법 검사) |
 | **Redis** | - | Cache 데이터 베이스 (예정) |
 
+**AI 서비스**:
+- **Gemini 2.5 Flash-Lite**: 텍스트 분석 (오감/감정/대화/의성어 평가)
+- **Gemini 2.5 Flash-Lite**: 맞춤법 검사 (초등학생 눈높이)
+- **Vertex AI 모드**: Multi-region failover 지원 (`vertexai: true`)
+- **Response Schema**: JSON 응답 강제 (`Type.OBJECT`, `Type.ARRAY` 등)
+
 ### Utilities
 
 | 기술 | 버전 | 용도 |
@@ -649,17 +655,17 @@ writings/{writingId}
 
 ---
 
-### 7. 실시간 피드백 시스템 (3-Layer 아키텍처)
+### 7. 실시간 피드백 시스템 (3-Layer 아키텍처) + 맞춤법 검사
 
 #### 핵심 개념
 
-**목적**: Vertex AI로 초등학생 글쓰기를 실시간 평가하면서 비용 최적화
+**목적**: Gemini API로 초등학생 글쓰기를 실시간 평가하면서 비용 최적화
 
 **문제**:
 - 매번 전체 텍스트 전송 = 비용 폭증
 - Rate Limit (15 RPM) = 사용자 2명만 접속해도 초과
 
-**해결**: Delta 전송 + 캐싱 + Multi-Region Failover
+**해결**: Delta 전송 + 캐싱 + Multi-Region Failover + 분석 히스토리
 
 #### 아키텍처
 
@@ -679,7 +685,8 @@ writings/{writingId}
 │ src/services/textAnalysisService.ts    │
 │                                         │
 │ 역할:                                   │
-│ - 프롬프트 생성 (평가 기준 정의)         │
+│ - 프롬프트 생성 (히스토리 포함)          │
+│ - Response Schema 정의 (Type.OBJECT)    │
 │ - JSON 파싱 (AI 응답 처리)              │
 │ - 점수 제한 (최대 10점)                 │
 │ - vertexAI 호출                         │
@@ -690,13 +697,25 @@ writings/{writingId}
 │ src/services/vertexAI.ts                │
 │                                         │
 │ 역할:                                   │
-│ - Vertex AI 클라이언트 관리              │
+│ - GoogleGenAI 클라이언트 관리 (SDK)     │
+│ - Response Schema 전달 (JSON 강제)      │
 │ - Multi-region failover                 │
 │ - Retry with exponential backoff        │
 │ - regionHealthManager 연동              │
 └─────────────────────────────────────────┘
               ↓
 ┌─────────────────────────────────────────┐
+│ 맞춤법 검사 (독립적)                    │
+│ src/services/spellingService.ts         │
+│                                         │
+│ 역할:                                   │
+│ - Gemini 기반 맞춤법 검사               │
+│ - Response Schema (SpellingError[])     │
+│ - 초등학생 눈높이 설명 생성              │
+│ - 별도 debounce (5초)                   │
+└─────────────────────────────────────────┘
+              ↓
+┌─────────────────────────────────────────┐
 │ Region Health Manager                   │
 │ src/services/regionHealthManager.ts    │
 │                                         │
@@ -776,17 +795,67 @@ Single: 95%
 Multi-Region: 99.9% (자동 failover)
 ```
 
+#### 새로운 평가 기준 (2025-11-11 개편)
+
+**총 10점 = 오감(4) + 감정(2) + 대화(2) + 의성어(2)**
+
+| 항목 | 배점 | 설명 |
+|------|------|------|
+| **오감 표현** | 0~4점 | 시각/청각/후각/미각/촉각, 1개당 +1점 |
+| **감정 표현** | 0~2점 | 기쁨/슬픔/놀람 등, 1개당 +1점 |
+| **대화 표현** | 0~2점 | 큰따옴표(" ") 사용 시 +2점 |
+| **의성어/의태어** | 0~2점 | 쿵쿵, 반짝반짝 등, 1개당 +1점 |
+
+**변경사항**:
+- ❌ `descriptive` (감각/감정 형용사, 0~3점)
+- ✅ `emotion` (감정 표현, 0~2점)
+- ✅ 오감과 감정 분리로 평가 명확화
+
+#### 분석 히스토리 시스템
+
+**Draft 타입 확장**:
+```typescript
+interface AnalysisHistoryItem {
+  version: number;        // 1, 2, 3, ...
+  content: string;        // 해당 버전의 텍스트
+  timestamp: string;      // ISO string
+  analysis: {             // 분석 결과 전체
+    score: number;
+    breakdown: {...};
+    foundWords: {...};
+    suggestions: string[];
+  };
+}
+
+interface Draft {
+  // ... 기존 필드
+  analysisHistory?: AnalysisHistoryItem[];  // 최대 5개
+}
+```
+
+**AI 피드백 개선**:
+- ✅ 이전 버전과 비교하여 개선점 칭찬
+- ✅ 학생의 발전 과정 인정
+- ✅ 제안 최소화 (0~1개, 정말 부족한 것만)
+- ✅ 7점 이상이면 칭찬만
+
 #### 참고 파일
 
 **서비스 레이어**:
-- `src/services/vertexAI.ts` - Vertex AI 범용 래퍼
+- `src/services/vertexAI.ts` - Gemini API 범용 래퍼 (`@google/genai`)
-- `src/services/textAnalysisService.ts` - 텍스트 분석 비즈니스 로직
+- `src/services/textAnalysisService.ts` - 텍스트 분석 (히스토리 기반)
+- `src/services/spellingService.ts` - 🆕 맞춤법 검사 (독립적)
 - `src/services/regionHealthManager.ts` - Region 상태 관리
 
 **API & 컴포넌트**:
 - `src/app/api/analyze-text/route.ts` - 텍스트 분석 API
+- `src/app/api/spelling/check/route.ts` - 🆕 맞춤법 검사 API
 - `src/components/writing/ScoreDisplay.tsx` - 점수 표시 UI
-- `src/app/write/page.tsx` - Delta 추적 + 통합
+- `src/components/writing/SpellingErrorDisplay.tsx` - 🆕 맞춤법 오류 표시
+- `src/app/write/page.tsx` - Delta 추적 + 통합 + 맞춤법 검사
+
+**타입 정의**:
+- `src/types/draft.ts` - Draft, AnalysisHistoryItem
 
 **유틸리티**:
 - `src/utils/koreanWordList.ts` - 감각 동사/형용사 목록