diff --git a/PROJECT_STRUCTURE.md b/PROJECT_STRUCTURE.md index f2055e1..31fd2da 100644 --- a/PROJECT_STRUCTURE.md +++ b/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 기반) - - ✅ 점수 표시 (0~10점) - - ✅ 왜곡 영역 개수 (1~5개) - - ✅ 찾은 감각 단어 목록 (동사, 형용사, 의성어) - - ✅ AI 수정 제안 +- ✅ 🆕 **실시간 피드백 시스템** (Gemini 2.5 Flash-Lite) + - ✅ 점수 표시 (0~10점, 개편된 평가 기준) + - ✅ 찾은 표현 목록 (오감, 감정, 의성어/의태어) + - ✅ 분석 히스토리 추적 (이전 버전 비교, 발전 과정 격려) + - ✅ 스마트 제안 (칭찬 강화, 제안 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) | ✅ 완료 | -| **Text Analysis** | `textAnalysisService.ts` | 🆕 **텍스트 분석 서비스** (초등학생 글쓰기 평가) | ✅ 완료 | +| **Vertex AI** | `vertexAI.ts` | 🆕 **Gemini API 범용 래퍼** (`@google/genai`, Multi-region failover, Response Schema) | ✅ 완료 | +| **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 | 허용 이름 추가/제거 | ✅ 완료 | diff --git a/ROADMAP.md b/ROADMAP.md index c6b0f36..9db44d7 100644 --- a/ROADMAP.md +++ b/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** | ### 🚧 진행 중 diff --git a/TECHNICAL_IMPLEMENTATION.md b/TECHNICAL_IMPLEMENTATION.md index 39fe2a2..bf90a16 100644 --- a/TECHNICAL_IMPLEMENTATION.md +++ b/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 { const maxRetries = 3; diff --git a/TECH_STACK.md b/TECH_STACK.md index 4c1b6fc..35a46ab 100644 --- a/TECH_STACK.md +++ b/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/textAnalysisService.ts` - 텍스트 분석 비즈니스 로직 +- `src/services/vertexAI.ts` - Gemini API 범용 래퍼 (`@google/genai`) +- `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` - 감각 동사/형용사 목록