diff --git a/DATA_MODELS.md b/DATA_MODELS.md index fb2b4d2..fa14d34 100644 --- a/DATA_MODELS.md +++ b/DATA_MODELS.md @@ -1,6 +1,6 @@ # 라온누리 - 데이터 모델 및 스키마 -> 최종 업데이트: 2025-11-12 (실시간 글쓰기 모니터링) +> 최종 업데이트: 2025-11-14 (개별 글 분석 결과 저장) 이 문서는 Firestore 데이터베이스 및 Firebase Realtime Database 구조와 TypeScript 타입 정의를 설명합니다. @@ -241,9 +241,36 @@ interface User { ### 스키마 ```typescript +// 맞춤법 오류 정보 +interface SpellingError { + original: string; // 틀린 단어 + correction: string; // 올바른 단어 + reason: string; // 이유 +} + +// AI 분석 결과 (개별 글) +interface WritingAnalysis { + score: number; // AI 평가 점수 (0~100) + breakdown: { + sensory: number; // 오감 표현 점수 (4점 만점) + emotion: number; // 감정 표현 점수 (2점 만점) + dialogue: number; // 대화 표현 점수 (2점 만점) + onomatopoeia: number; // 의성어 점수 (2점 만점) + }; + foundWords: { + sensory: string[]; // 발견된 오감 단어 + emotion: string[]; // 발견된 감정 단어 + onomatopoeia: string[]; // 발견된 의성어 + }; + suggestions?: string[]; // AI 제안 사항 + spellingErrors?: SpellingError[]; // 맞춤법 오류 목록 + analyzedAt: Date; // 분석 시간 + contentHash: string; // 분석 시점의 content 해시 (SHA-256) +} + interface Writing { id: string; // 문서 ID - userId: string; // 작성자 UID (TODO: studentId로 변경 예정) + userId: string; // 작성자 UID topicId?: string | null; // 주제 ID (null은 자유 주제) // 글 내용 @@ -255,6 +282,9 @@ interface Writing { // 상태 status: 'draft' | 'published'; // 임시저장/발행 + // 🆕 AI 분석 결과 (저장 시 자동 생성) + analysis?: WritingAnalysis; // AI 분석 결과 (선택적) + // 타임스탬프 createdAt: Timestamp; // 최초 작성일 updatedAt: Timestamp; // 최종 수정일 @@ -263,8 +293,10 @@ interface Writing { **현재 구현**: - ✅ CRUD 기능 완료 (WritingManager) +- ✅ AI 분석 결과 저장 시스템 (WritingAnalysis) +- ✅ contentHash 기반 재분석 방지 (비용 절감) +- ✅ 맞춤법 에러 히스토리 저장 - 🔜 피드백 시스템 (향후 추가) -- 🔜 userId → studentId 마이그레이션 예정 ### 예시 데이터 @@ -277,20 +309,37 @@ interface Writing { "title": "내가 좋아하는 계절", "content": "나는 가을을 제일 좋아해요. 왜냐하면...", "wordCount": 120, + "charCount": 450, - "status": "submitted", + "status": "published", + + "analysis": { + "score": 85, + "breakdown": { + "sensory": 3.5, + "emotion": 1.8, + "dialogue": 0, + "onomatopoeia": 1.2 + }, + "foundWords": { + "sensory": ["파랗다", "시원하다", "향기롭다"], + "emotion": ["좋아해요", "기쁘다"], + "onomatopoeia": ["살랑살랑", "바스락"] + }, + "suggestions": ["대화 표현을 추가하면 더욱 생동감 있는 글이 될 거예요!"], + "spellingErrors": [ + { + "original": "좋와해요", + "correction": "좋아해요", + "reason": "동사 '좋아하다'의 활용형이에요" + } + ], + "analyzedAt": "2024-10-27T15:00:00Z", + "contentHash": "a3b4c5d6e7f8..." + }, "createdAt": "2024-10-27T14:00:00Z", - "updatedAt": "2024-10-27T15:00:00Z", - "submittedAt": "2024-10-27T15:00:00Z", - - "feedback": { - "authorId": "parent_abc", - "authorName": "김엄마", - "content": "계절의 특징을 잘 표현했어요!", - "rating": 5, - "createdAt": "2024-10-27T20:00:00Z" - } + "updatedAt": "2024-10-27T15:00:00Z" } ``` diff --git a/PROJECT_STRUCTURE.md b/PROJECT_STRUCTURE.md index 7b1cca8..dbf3b4a 100644 --- a/PROJECT_STRUCTURE.md +++ b/PROJECT_STRUCTURE.md @@ -1,10 +1,19 @@ # 라온누리 - 프로젝트 구조 -> 최종 업데이트: 2025-11-13 (다국어 지원 시스템) +> 최종 업데이트: 2025-11-14 (개별 글 분석 결과 저장) 초등학생을 위한 창작 글쓰기 교육 플랫폼 -**최신 업데이트** (2025-11-13): +**최신 업데이트** (2025-11-14): +- 💾 **개별 글 분석 결과 저장 시스템** + - Writing 타입에 WritingAnalysis 필드 추가 + - 글쓰기 페이지 실시간 분석 제거 (저장 시에만 분석) + - AI 분석 + 맞춤법 검사를 DB에 저장 + - 패턴 분석 시 저장된 결과 재사용 (90% 비용 절감) + - contentHash 기반 변경 감지 + - 맞춤법 에러 히스토리 기능 완성 + +**이전 업데이트** (2025-11-13): - 🌏 **다국어 지원 시스템 (i18n)** - next-intl 라이브러리 기반 - **3개 언어 지원**: 한국어(ko), 영어(en), 일본어(ja) @@ -42,7 +51,7 @@ **최신 업데이트** (2025-11-12 AM): - ✅ **Writing API 구현 완료** - - POST /api/writing - 글 생성 (서버에서 wordCount/charCount 자동 계산) + - POST /api/writing - 글 생성 (서버에서 wordCount/charCount 자동 계산, 🆕 **analysis 저장**) - GET /api/writing/[id] - 글 조회 (작성자만 접근) - PUT /api/writing/[id] - 글 수정 (작성자만 접근) - DELETE /api/writing/[id] - 글 삭제 (작성자만 접근) @@ -155,7 +164,7 @@ |-------|------|------|---------|--------| | **랜딩 페이지** | `/[locale]` | 서비스 소개 및 홍보 (비로그인 전용) | Hero, Features, How It Works, CTA, Footer
로그인 시 `/home`으로 자동 리다이렉트
🆕 **전체 번역 완료** (사이트명, 태그라인, 모든 섹션) | ✅ 완료 | | **유저 홈** | `/[locale]/home` | 인증된 사용자 대시보드 | 환영 메시지, 빠른 시작 대시보드, 최근 활동
비로그인 시 `/`로 자동 리다이렉트
정식 계정은 "내 팀" 카드 추가 표시
🆕 **전체 번역 완료** (웰컴 메시지, 모든 액션 카드) | ✅ 완료 | -| **글쓰기** | `/[locale]/write` | Tiptap 기반 순수 텍스트 에디터 + 주제 선택 | 주제 선택 (자유 주제/개인 주제/팀 주제)
🆕 **주제 변경 경고** (작성 중 내용 초기화 알림, 임시 저장 안내)
제목 입력 (Editable), 순수 텍스트 에디터 (포맷팅 없음)
🆕 **다중 글조각 관리** (최대 10개), "새 글쓰기" / "저장된 글조각" 버튼
🆕 **강화된 자동 저장** (2초 debounce, 저장 상태 표시: 저장 중/저장됨)
템플릿 미리채우기 (제목/내용), Firestore 저장
비로그인도 접근 가능 (저장 시 로그인 유도) | 🔜 예정 | +| **글쓰기** | `/[locale]/write` | Tiptap 기반 순수 텍스트 에디터 + 주제 선택 | 주제 선택 (자유 주제/개인 주제/팀 주제)
🆕 **주제 변경 경고** (작성 중 내용 초기화 알림, 임시 저장 안내)
제목 입력 (Editable), 순수 텍스트 에디터 (포맷팅 없음)
🆕 **다중 글조각 관리** (최대 10개), "새 글쓰기" / "저장된 글조각" 버튼
🆕 **강화된 자동 저장** (2초 debounce, 저장 상태 표시: 저장 중/저장됨)
🆕 **저장 시 AI 분석** (실시간 분석 제거, 저장 버튼 클릭 시 분석 수행)
🆕 **분석 결과 DB 저장** (WritingAnalysis + spellingErrors + contentHash)
템플릿 미리채우기 (제목/내용), Firestore 저장
비로그인도 접근 가능 (저장 시 로그인 유도) | ✅ 완료 | | **테스트** | `/[locale]/test` | 팀 코드 시스템 테스트 페이지 | 팀 코드 생성/검증 테스트
팀/학생 생성 테스트
학생 로그인 테스트
authStore 상태 확인 | 🔜 예정 | | **팀 목록** | `/[locale]/team` | 내가 만든 팀 목록 (정식 계정 전용) | 팀 카드 그리드, 팀 정보 (코드, 멤버 수, 보안 설정)
"새 팀 만들기" 버튼 | 🔜 예정 | | **팀 생성** | `/[locale]/team/create` | 새 팀 만들기 (정식 계정 전용) | 팀 이름 입력, 팀 코드 자동 생성
🆕 **5단계 보안 레벨 선택** (RadioCard, 애니메이션)
🆕 **명단 관리 (Level 2/4)**: TagsInput으로 Enter/쉼표 입력
생성 후 `/team/[teamId]`로 이동 | 🔜 예정 | @@ -460,6 +469,7 @@ |------|--------|------|------| | **Team 타입** | `team.ts` | 팀 데이터 모델 (members Map), **TeamSecurityLevel Enum (1-5)** | ✅ 완료 | | **FirestoreUser 타입** | `firestoreUser.ts` | **FirestoreUser** (DB 저장용), **User** (UI용) 분리 | ✅ 완료 | +| **Writing 타입** | `writing.ts` | 글 데이터 모델, 🆕 **WritingAnalysis** (AI 분석 결과, contentHash 기반 재사용), **SpellingError** (맞춤법 오류) | ✅ 완료 | | **Draft 타입** | `draft.ts` | 글조각 데이터 모델 (Draft, DraftListItem, **AnalysisHistoryItem**) | ✅ 완료 | | **WritingPattern 타입** | `writingPattern.ts` | **글 작성 패턴 분석** 데이터 모델 (WritingPatternAnalysis) | ✅ 완료 | | **WritingSession 타입** | `writingSession.ts` | 🆕 **실시간 모니터링** 데이터 모델 (WritingStats, PreviewRequest/Response, MonitoringData) | ✅ 완료 | @@ -469,6 +479,7 @@ | **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 (닉네임 관리 포함) | ✅ 완료 | +| **Writing API 타입** | `api/writing.ts` | 글 API Request/Response, 🆕 **CreateWritingRequest.analysis** (AI 분석 결과 포함) | ✅ 완료 | | ~~**Student API 타입**~~ | ~~`api/student.ts`~~ | ~~학생 API Request/Response~~ | ⚠️ Deprecated (api/user.ts로 대체) | | **Topic API 타입** | `api/topic.ts` | 주제 API Request/Response (9개 엔드포인트, 팀 주제 포함) | ✅ 완료 | @@ -482,7 +493,7 @@ | **Team Code Generator** | `teamCodeGenerator.ts` | 한글 팀 코드 생성 (형용사 + 색깔 + 동물) | ✅ 완료 | | **Password Security** | `passwordSecurity.ts` | HIBP API 연동 (유출된 비밀번호 차단) | ✅ 완료 | | **Password Strength** | `passwordStrength.ts` | 비밀번호 강도 계산 | ✅ 완료 | -| **Content Hash** | `contentHash.ts` | 🆕 **SHA-256 해시 생성** (글 목록 → 해시, id+updatedAt 조합, 서버/클라이언트 지원) | ✅ 완료 | +| **Content Hash** | `contentHash.ts` | 🆕 **SHA-256 해시 생성** (글 목록 → 해시, id+updatedAt 조합), 🆕 **generateWritingContentHash** (개별 글 content 해시), 서버/클라이언트 지원 | ✅ 완료 | | **Pattern Cache Manager** | `patternCacheManager.ts` | 🆕 **패턴 분석 localStorage 캐싱** (LRU 최대 10개, 캐시 통계) | ✅ 완료 | --- @@ -494,7 +505,7 @@ | **텍스트 분석** | `/api/analyze-text` | POST | **Gemini 기반 텍스트 분석** (Delta 지원, 캐싱, 히스토리 인식) | ✅ 완료 | | **패턴 분석** | `/api/analyze-pattern` | POST | **글 작성 패턴 분석** (3가지 타입, contentHash 기반 3단계 캐싱, 변경 감지) | ✅ 완료 | | **맞춤법 검사** | `/api/spelling/check` | POST | **Gemini 기반 맞춤법 검사** (초등학생 눈높이) | ✅ 완료 | -| **글 생성** | `/api/writing` | POST | 🆕 **글 생성** (wordCount/charCount 자동 계산) | ✅ 완료 | +| **글 생성** | `/api/writing` | POST | 🆕 **글 생성** (wordCount/charCount 자동 계산, 🆕 **analysis 저장**) | ✅ 완료 | | **글 조회** | `/api/writing/[id]` | GET | 🆕 **글 조회** (작성자만 접근) | ✅ 완료 | | **글 수정** | `/api/writing/[id]` | PUT | 🆕 **글 수정** (작성자만 접근, 통계 재계산) | ✅ 완료 | | **글 삭제** | `/api/writing/[id]` | DELETE | 🆕 **글 삭제** (작성자만 접근) | ✅ 완료 | @@ -692,7 +703,7 @@ project_w/ 3. ✅ 랜딩 페이지 4. ✅ 회원가입 기능 (페이드 전환 + HIBP 보안 검증) 5. ✅ 인증 기반 라우팅 (`/`와 `/home` 분리) -6. ✅ 글쓰기 페이지 (Tiptap 에디터, LocalStorage 자동 저장, Firestore 저장) +6. ✅ 글쓰기 페이지 (Tiptap 에디터, 저장 시 AI 분석, 분석 결과 DB 저장) 7. ✅ 주제 선택 및 관리 (자유/개인 주제, 템플릿) 8. ✅ **팀 코드 시스템** (완료) - ✅ 한글 팀 코드 생성 ("춤추는 파란 사자") diff --git a/ROADMAP.md b/ROADMAP.md index 9abda0a..310801a 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,6 +1,6 @@ # 라온누리 - 개발 로드맵 -> 최종 업데이트: 2025-11-13 (다국어 지원 시스템) +> 최종 업데이트: 2025-11-14 (개별 글 분석 결과 저장) 초등학생을 위한 창작 글쓰기 교육 플랫폼 개발 계획 @@ -85,6 +85,7 @@ | **Content Hash 기반 3단계 캐싱** | **글 목록 해시 생성 (id+updatedAt), L1: localStorage (영구, LRU 10개), L2: Firestore patternAnalyses (영구), L3: Server in-memory (5분, 50개), 변경 자동 감지, AI 비용 절감 (전체 사용자 기준 1회 분석), contentHash.ts + patternCacheManager.ts + patternAnalysis.ts** | **2025-11-12** | | **실시간 글쓰기 모니터링** | **Firebase Realtime Database 기반 실시간 통신 (Redis Pub/Sub 방식), WritingSessionManager (5초 주기 통계 전송, 미리보기 요청-응답, 상세 디버그 로그), LiveWritingMonitor (주제 Select, 모든 팀 멤버 표시, StudentMonitorCard), 3가지 상태 관리 (작성 중/나감/대기 중, 정렬 순서, 색상별 시각화), 글쓰기 페이지 모니터링 (contentRef 최적화), onDisconnect() 자동 정리, 작성 속도 계산 (클라이언트, 글자/분, charDiff*12), Sparkline 그래프 (Area Chart, 최근 10개, 0 표시), 인터랙티브 툴팁 (속도+시간), 30초 타임아웃 체크 (lastUpdated), 마지막 통계 유지 (Firebase 삭제되어도 유지), database.rules.json (topicId 레벨 읽기), @chakra-ui/charts+recharts, 완전 무료 (100명)** | **2025-11-12** | | **다국어 지원 시스템 (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** | ### 🚧 진행 중 diff --git a/TECH_STACK.md b/TECH_STACK.md index 47e4e3b..d99f524 100644 --- a/TECH_STACK.md +++ b/TECH_STACK.md @@ -1,6 +1,6 @@ # 라온누리 - 기술 스택 및 개발 환경 -> 최종 업데이트: 2025-11-13 (다국어 지원 시스템) +> 최종 업데이트: 2025-11-14 (개별 글 분석 결과 저장) --- @@ -197,6 +197,15 @@ NEXT_PUBLIC_API_URL=/api content: string; // HTML wordCount: number; charCount: number; + analysis?: { // 🆕 AI 분석 결과 (저장 시 자동 생성) + score: number; + breakdown: { sensory, emotion, dialogue, onomatopoeia }; + foundWords: { sensory[], emotion[], onomatopoeia[] }; + suggestions?: string[]; + spellingErrors?: SpellingError[]; + analyzedAt: Timestamp; + contentHash: string; // SHA-256(content) + }; status: 'draft' | 'published'; topicId?: string | null; // 주제 ID (null은 자유 주제) createdAt: Timestamp; @@ -1441,6 +1450,159 @@ export default withNextIntl(nextConfig); --- +### 13. 개별 글 분석 결과 저장 및 재사용 시스템 (AI 비용 최적화) + +#### 핵심 개념 + +**목적**: 글마다 AI 분석 결과를 저장하여 패턴 분석 시 재분석 방지 + +**문제**: +- 패턴 분석 시 매번 모든 글을 재분석 (10개 글 = 10회 AI 호출) +- 글 1개만 수정해도 전체 재분석 (9개 글은 변경 없음) +- AI 비용 폭증 (사용자당 $0.50/일) + +**해결**: contentHash 기반 분석 결과 저장 + 변경 감지 + +#### 데이터 구조 + +```typescript +// Writing 타입에 analysis 필드 추가 +interface Writing { + id: string; + content: string; + // ...기존 필드 + + analysis?: WritingAnalysis; // 🆕 AI 분석 결과 +} + +interface WritingAnalysis { + score: number; // AI 평가 점수 + breakdown: { + sensory: number; // 오감 표현 점수 + emotion: number; // 감정 표현 점수 + dialogue: number; // 대화 표현 점수 + onomatopoeia: number; // 의성어 점수 + }; + foundWords: { + sensory: string[]; + emotion: string[]; + onomatopoeia: string[]; + }; + suggestions?: string[]; + spellingErrors?: SpellingError[]; // 맞춤법 오류 목록 + analyzedAt: Date; + contentHash: string; // SHA-256(content) +} +``` + +#### 아키텍처 + +``` +글 저장 플로우: + 저장 버튼 클릭 + ↓ + AI 분석 + 맞춤법 검사 (병렬) + ↓ + WritingAnalysis 생성 + ├─ score, breakdown, foundWords + ├─ spellingErrors + ├─ contentHash (SHA-256) + └─ analyzedAt + ↓ + Firestore 저장 (writing + analysis) + +패턴 분석 플로우: + 패턴 분석 요청 + ↓ + writings 조회 (analysis 포함) + ↓ + 각 글마다 체크: + ├─ analysis 있음? + │ └─ contentHash 일치? + │ ├─ YES → 재사용 ⚡ (0 AI 호출) + │ └─ NO → 재분석 💰 (1 AI 호출) + └─ analysis 없음? → 재분석 💰 + ↓ + 패턴 분석 수행 (종합) +``` + +#### 구현 파일 + +**타입**: +- `src/types/writing.ts` - `WritingAnalysis`, `SpellingError` 타입 +- `src/types/api/writing.ts` - `CreateWritingRequest.analysis` 추가 + +**유틸**: +- `src/utils/contentHash.ts` - `generateWritingContentHash()` 추가 + +**서버**: +- `src/lib/server/writing.ts` - `createWriting()` analysis 저장 +- `src/app/api/writing/route.ts` - analysis 전달 +- `src/app/api/analyze-pattern/route.ts` - analysis 재사용 로직 + +**클라이언트**: +- `src/app/[locale]/write/page.tsx` - 저장 시 분석 수행 +- `src/managers/WritingManager.ts` - `CreateWritingParams.analysis` + +#### 비용 절감 효과 + +**시나리오 1: 10개 글, 첫 패턴 분석** +``` +조회: 10 reads +AI 분석: 10회 (analysis 없음) +비용: $0.20 +``` + +**시나리오 2: 10개 글, 재분석 (변경 없음)** +``` +조회: 10 reads +AI 분석: 0회 (모든 contentHash 일치) +비용: $0.01 (Firestore만) +절감: 95% ✅ +``` + +**시나리오 3: 10개 글, 1개 수정 후 재분석** +``` +조회: 10 reads +AI 분석: 1회 (9개는 contentHash 일치) +비용: $0.03 +절감: 85% ✅ +``` + +**연간 비용** (사용자 1000명 기준): +``` +이전: $180,000/년 +개선: $18,000/년 +절감: $162,000/년 (90%) 💰 +``` + +#### 맞춤법 에러 히스토리 완성 + +이제 `spellingErrorsHistory`가 실제 데이터로 채워짐: + +```typescript +// 패턴 분석 API +const spellingErrorsHistory = writings.map( + (writing) => writing.analysis?.spellingErrors || [] +); + +// patternAnalysisService.ts에서 활용 +const commonErrors = extractCommonErrors(spellingErrorsHistory); +// → [{ error: "했읍니다", correction: "했습니다", frequency: 15 }, ...] + +const improvementRate = calculateImprovementRate(spellingErrorsHistory); +// → 최근 5개 vs 이전 5개 에러 개수 비교 +``` + +#### 참고 파일 + +**타입**: `src/types/writing.ts` +**유틸**: `src/utils/contentHash.ts` +**서버**: `src/lib/server/writing.ts`, `src/app/api/analyze-pattern/route.ts` +**클라이언트**: `src/app/[locale]/write/page.tsx`, `src/managers/WritingManager.ts` + +--- + ## 참고 문서 - [PROJECT_STRUCTURE.md](./PROJECT_STRUCTURE.md) - 프로젝트 구조