baekryang/RaonNuri_Public_Documents

Fork 0

Documentation Bot 735e0ef0ba docs: Sync documentation from private repository

2025-11-12 02:07:14 +00:00

35 KiB

Raw Blame History

라온누리 - 기술 스택 및 개발 환경

최종 업데이트: 2025-11-11 (글 작성 패턴 분석, 실시간 하이라이트, 인터랙티브 툴팁)

기술 스택

Core Framework

기술	버전	용도
Next.js	16.0.0	React 프레임워크 (App Router)
React	19.2.0	UI 라이브러리
TypeScript	5.x	타입 안전성

UI & Styling

기술	버전	용도
Chakra UI	v3.28.0	컴포넌트 라이브러리
Emotion	11.14.0	CSS-in-JS
Framer Motion	12.23.24	애니메이션 라이브러리
React Icons	5.5.0	아이콘 세트
Tiptap	latest	리치 텍스트 에디터

Backend & Database

기술	버전	용도
Firebase	12.4.0	BaaS (Backend as a Service)
Firebase Auth	-	사용자 인증
Firestore	-	NoSQL 데이터베이스 (글 저장)
@google/genai	1.29.0	🆕 Google Gemini API SDK (텍스트 분석, 맞춤법 검사)
Redis	-	Cache 데이터 베이스 (예정)

AI 서비스:

Gemini 2.5 Flash-Lite: 텍스트 분석 (오감/감정/대화/의성어 평가, Delta 전송)
Gemini 2.5 Flash-Lite: 맞춤법 검사 (초등학생 눈높이)
Gemini 2.5 Flash-Lite: 글 작성 패턴 분석 (최근 10개 글 종합 분석, AI 평가 및 맞춤형 추천)
Vertex AI 모드: Multi-region failover 지원 (vertexai: true)
Response Schema: JSON 응답 강제 (Type.OBJECT, Type.ARRAY 등)

Utilities

기술	버전	용도
use-debounce	latest	🆕 React debounce hook (5초 API 호출 제한)

State Management

기술	버전	용도
Zustand	5.0.8	전역 상태 관리

Development Tools

기술	버전	용도
ESLint	9.x	코드 린팅
babel-plugin-react-compiler	1.0.0	React 컴파일러 최적화

개발 명령어

주요 명령어

# 개발 서버 시작 (포트 3001)
npm run dev

# 프로덕션 빌드
npm run build

# 프로덕션 서버 시작 (포트 3001)
npm start

# ESLint 실행
npm run lint

중요 사항

포트: 개발/프로덕션 서버 모두 포트 3001 사용 (기본 3000이 아님)
Webpack 모드: --webpack 플래그 사용 (React Compiler 요구사항)
Turbopack 미사용: React Compiler와 호환성을 위해 webpack 모드 사용

프로젝트 설정

Next.js 설정 (`next.config.ts`)

// React Compiler 활성화
const nextConfig = {
  reactCompiler: true,
  // ... 기타 설정
};

TypeScript 설정

Path Alias: @/* → ./src/*
모든 import는 @/ 경로 사용

// 예시
import { useAuthStore } from "@/store/authStore";
import { Navbar } from "@/components/navigation/Navbar";

ESLint 설정

Next.js 공식 ESLint 설정 사용
React 19 및 Next.js 16 규칙 적용

환경 변수

`.env.local` 파일 구조

# Firebase 설정 (필수)
NEXT_PUBLIC_FIREBASE_API_KEY=your_api_key
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your_project.firebaseapp.com
NEXT_PUBLIC_FIREBASE_PROJECT_ID=your_project_id
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your_project.appspot.com
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=your_sender_id
NEXT_PUBLIC_FIREBASE_APP_ID=your_app_id

# 사이트 URL (프로덕션)
NEXT_PUBLIC_URL=https://raonnuri.com

# API Base URL (선택적, 기본값: /api)
NEXT_PUBLIC_API_URL=/api

환경 변수 사용 예시

// src/config/firebase.ts
const firebaseConfig = {
  apiKey: process.env.NEXT_PUBLIC_FIREBASE_API_KEY,
  authDomain: process.env.NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN,
  // ...
};

Firebase 설정

인증 제공자

제공자	상태	설정 위치	용도
이메일/비밀번호	✅ 활성화	Firebase Console > Authentication	정식 계정 (학부모/고학년)
Google OAuth	✅ 활성화	Firebase Console > Authentication	정식 계정 (소셜 로그인)
Anonymous	✅ 활성화	Firebase Console > Authentication	학생 팀 코드 로그인
네이버	🔜 준비 중	-	정식 계정 (소셜 로그인)
카카오	🔜 준비 중	-	정식 계정 (소셜 로그인)

Firestore 데이터베이스

프로젝트 루트
└── firestore.rules        # Firestore 보안 규칙 (예정)

컬렉션 구조:

writings/ ✅ - 작성한 글

{
  userId: string;
  title: string;
  content: string; // HTML
  wordCount: number;
  charCount: number;
  status: 'draft' | 'published';
  topicId?: string | null; // 주제 ID (null은 자유 주제)
  createdAt: Timestamp;
  updatedAt: Timestamp;
}

topics/ ✅ - 글쓰기 주제 (팀 주제 + 개인 주제)

{
  title: string;
  description: string;
  category: TopicCategory; // Enum: daily | imagination | emotion | experience
  difficulty: TopicDifficulty; // Enum: easy | medium | hard
  ownerType: TopicOwnerType; // Enum: system | team | personal
  ownerId?: string; // 팀 주제: teamId, 개인 주제: userId
  keywords: string[];
  examplePrompts: string[];
  titleTemplate?: string; // 제목 템플릿
  contentTemplate?: string; // 내용 템플릿
  usageCount: number;
  createdAt: Timestamp;
  updatedAt: Timestamp;
  createdBy: string;
  isActive: boolean;
}
// 팀 주제: ownerId = teamId 직접 사용 (예: abc123)
// 유틸 함수: getTeamOwnerId(teamId), extractTeamId(ownerId) - 단순 반환

classrooms/ ✅ - 팀 (팀 코드 시스템)

{
  code: string;                    // "춤추는 파란 사자" (한글 팀 코드)
  name: string;                    // "2학년 1반"
  ownerId: string;                 // 팀 소유자 UID
  securityMode: 'simple' | 'normal' | 'open';
  requirePin: boolean;
  allowAnonymousJoin: boolean;
  studentIds: string[];            // students 컬렉션 참조
  createdAt: Timestamp;
  updatedAt: Timestamp;
  isActive: boolean;
}

students/ ✅ - 학생 계정 (독립적, Anonymous Auth 기반)

{
  firebaseUid: string;             // Anonymous Auth UID
  linkedUserId?: string;           // 연결된 정식 계정 (선택적, 1:1)
  name: string;
  pinHash?: string;                // SHA-256 해시
  classroomIds: string[];          // 다중 팀 지원
  isAnonymous: true;
  createdAt: Timestamp;
  lastLoginAt: Timestamp;
}

users/ 🔜 - 사용자 프로필 및 진행 상황 (정식 계정)

{
  uid: string;
  email: string;
  ownedStudentIds: string[];       // students 컬렉션 ID 배열
  role: 'student' | 'parent' | 'teacher';
  // ...
}

lessons/ 🔜 - 학습 레슨
stickers/ 🔜 - 스티커 마스터 데이터
userStickers/ 🔜 - 사용자별 스티커 획득 기록

Chakra UI v3 커스텀 테마

파일: src/theme/system.ts
브랜드 컬러: 핑크(#FF6B9D), 오렌지(#FFA07A), 청록(#4ECDC4)
다크모드: 시맨틱 토큰으로 자동 전환
반응형 타이포그래피: hero, heading, body 등 텍스트 스타일 정의
🆕 슬롯 레시피 (2025-11-10):
- menu: 커스텀 메뉴 스타일 (애니메이션, hover 효과)
- dialog: Dialog 자동 배경색, border, shadow
- select: Select 드롭다운 자동 배경색, hover 효과
시맨틱 토큰:
- bg, fg, border: 전역 배경/전경/테두리 색상
- brand.*: 브랜드 컬러 시맨틱 토큰
- navbar.*, menu.*: 컴포넌트별 시맨틱 토큰
- landing.*: 랜딩 페이지 전용 토큰

아키텍처 패턴

1. Manager 패턴 + API 아키텍처 (3계층 구조)

UI Layer (Components/Pages)
    ↓ 매니저 호출
Manager Layer (비즈니스 로직 + 클라이언트 캐싱)
    ├─> TeamManager (싱글톤)
    │   ├─> createTeam() → POST /team
    │   ├─> getTeam() → GET /team/:id (5분 캐싱)
    │   ├─> getMyTeams() → GET /team/list (소유+참여 팀, 1분 캐싱)
    │   ├─> updateTeam() → PUT /team/:id
    │   ├─> deleteTeam() → DELETE /team/:id
    │   └─> generateUniqueTeamCode() → POST /team/generate-code
    │
    ├─> UserManager (싱글톤)
    │   ├─> createUser() → POST /user
    │   ├─> getUser() → GET /user/:id (Firebase Auth + Firestore 자동 결합, 5분 캐싱)
    │   ├─> getUsersByTeam() → GET /user/by-team/:teamId (30초 캐싱)
    │   ├─> updateLastLogin() → POST /user/:uid/update-last-login
    │   ├─> findUserByNickname() → POST /user/find-by-nickname (Level 1용)
    │   └─> setUserNickname() → POST /user/:uid/nickname (DEPRECATED - 팀에서 관리)
    │
    ├─> WritingManager (싱글톤)
    │   ├─> createWriting()
    │   ├─> getWriting()
    │   └─> getUserWritings()
    │
    └─> TopicManager (싱글톤)
        ├─> getAvailableTopics()
        └─> createPersonalTopic()
    ↓ HTTP API 호출
API Layer (Next.js API Routes / Server Actions) - 구현 대기
    ├─> /api/team/* (팀 관련 엔드포인트)
    ├─> /api/student/* (학생 관련 엔드포인트)
    └─> ID Token 검증, 권한 체크, Firestore 접근
    ↓
Database Layer
    ├─> Firestore (영구 데이터)
    └─> Redis (캐싱, Rate Limiting) - 예정

Manager 패턴의 장점:

✅ UI와 비즈니스 로직 완전 분리
✅ 싱글톤 패턴으로 전역 인스턴스 관리
✅ 클라이언트 사이드 캐싱: GET 요청 자동 캐싱 (TTL 기반)
✅ 캐시 무효화: 변경 작업 시 관련 캐시 자동 삭제
✅ API 추상화: HTTP 호출 로직을 BaseManager에서 처리
✅ 타입 안전성: Request/Response 타입 완전 정의
✅ 테스트 용이성: API 모킹으로 단위 테스트 가능
✅ 유연성: Firestore 직접 접근 → API 호출로 전환 완료

BaseManager 기능:

// src/managers/ManagerBase.ts

abstract class BaseManager {
  // 인증
  protected async getIdToken(): Promise<string | null>
  protected getCurrentUserId(): string | null
  protected isAuthenticated(): boolean

  // API 호출
  protected async authenticatedFetch<T>(endpoint, options)
  protected async ApiCall<Req, Res>(method, endpoint, data)
}

abstract class SingletonManager extends BaseManager {
  // 캐싱
  protected getCached<T>(key, ttl?): T | null
  protected setCached<T>(key, data): void
  protected invalidateCache(key): void
  protected invalidateCachePattern(pattern): void
  protected clearCache(): void

  // API + 캐싱 통합
  protected async callApiWithCache<Req, Res>(cacheKey, method, endpoint, data, ttl)
}

사용 예시:

// team/page.tsx
import { teamManager } from "@/managers";

// 팀 목록 조회 - 소유한 팀 + 참여한 팀 (1분간 캐싱됨)
const teams = await teamManager.getMyTeams();

// 🆕 팀 생성 (5단계 보안 레벨)
const teamId = await teamManager.createTeam({
  name: "우리반",
  code: "춤추는파란사자",
  securityLevel: 2,  // 1-5 (명단 기반)
  allowedNames: ["홍길동", "김철수"]
});

// 🆕 보안 레벨 변경
await teamManager.updateSecurityLevel(teamId, 4, true); // Level 4, 자동 명단 생성

// 🆕 닉네임 조회
const nickname = teamManager.getMemberNickname(team, uid, user?.name);

참고 문서:

API_SPEC.md - 전체 API 명세서

2. 인증 플로우 및 라우팅 (currentStudent 중심 아키텍처)

1. AuthInitializer (클라이언트)
   └─> initializeAuth() 호출 (마운트 시)
       └─> onAuthStateChanged 리스너 등록
           ├─> firebaseUser.isAnonymous ?
           │   └─> getStudentByFirebaseUid() → authStore.currentStudent 설정
           └─> else ?
               └─> getStudentsByUserId() → authStore.ownedStudents 설정

2. authStore (Zustand) - 재설계됨
   ├─> **currentStudent** (Student | null) - 현재 활동 중인 학생 (필수)
   ├─> user (User | null) - 정식 계정 (선택적)
   ├─> ownedStudents (Student[]) - 정식 계정이 소유한 학생들
   ├─> isAnonymous (boolean) - Anonymous Auth 여부
   ├─> isAuthenticated - 정식 계정 로그인 여부
   ├─> isLoading
   └─> 액션:
       ├─> login/signup/loginWithGoogle (기존)
       ├─> **loginAsStudent(classCode, name, pin?)** - 팀 코드 로그인
       ├─> **switchStudent(student)** - 학생 전환
       ├─> **linkCurrentStudentWithEmail()** - 계정 연결
       └─> **linkCurrentStudentWithGoogle()** - Google 계정 연결

3. 인증 기반 라우팅
   ├─> 랜딩 페이지 (/)
   │   └─> 로그인 상태 확인
   │       └─> isAuthenticated || currentStudent ? redirect(/home) : 랜딩 표시
   │
   └─> 유저 홈 (/home)
       └─> 인증 상태 확인
           └─> !currentStudent ? redirect(/) : 대시보드 표시

4. 보호된 페이지 패턴
   └─> useAuthStore()로 currentStudent 확인
       └─> 미인증 시 redirect(/) 또는 openLoginDialog()

3. 글쓰기 및 저장 로직 (Manager 패턴 적용)

1. 사용자가 /write 페이지 접근
   ├─> LocalStorage에서 임시 저장된 글 불러오기 (DraftManager)
   └─> 에디터에 복원

2. 주제 선택
   ├─> 작성 중인 내용 없음: 바로 주제 변경 + 템플릿 적용
   └─> 작성 중인 내용 있음:
       ├─> 🆕 **경고 Dialog 표시**
       │   ├─> "제목과 내용이 모두 초기화됩니다"
       │   └─> "임시 저장된 내용은 저장된 글조각에서 복구 가능"
       ├─> 사용자 선택:
       │   ├─> "취소": 주제 변경 취소
       │   └─> "확인하고 초기화": 주제 변경 + 내용 초기화
       └─> 확인 시 템플릿 미리채우기 (제목/내용)

3. 글 작성 중
   ├─> 제목: Editable 컴포넌트 (인라인 편집)
   ├─> 본문: Tiptap 순수 텍스트 에디터 (포맷팅 비활성화)
   │   └─> 초등학생을 위한 단순한 텍스트 입력에 집중
   ├─> 2초마다 LocalStorage에 자동 저장 (DraftManager, FIFO)
   ├─> 저장 상태 표시 (저장 중 → 저장됨 → 시간)
   └─> 하단 고정 버튼 (취소, 저장)

4. 저장 버튼 클릭
   ├─> 미인증 시: 로그인 다이얼로그 표시
   └─> 인증 시:
       └─> writingManager.createWriting() 호출
           ├─> 유효성 검사 (제목, 내용)
           ├─> 텍스트 통계 계산 (글자 수, 단어 수)
           ├─> Firestore에 저장
           └─> LocalStorage draft 삭제 후 /home 이동

5. WritingManager API
   ├─> createWriting() - 새 글 작성
   ├─> getWriting() - 글 조회
   ├─> getUserWritings() - 사용자 글 목록
   ├─> getRecentWritings() - 최근 글 목록
   ├─> updateWriting() - 글 수정
   └─> deleteWriting() - 글 삭제

6. DraftManager (클라이언트 전용)
   ├─> saveDraft() - 글조각 저장 (최대 10개, FIFO)
   ├─> getDraft() - 글조각 조회
   ├─> getAllDrafts() - 전체 글조각 목록
   ├─> deleteDraft() - 글조각 삭제
   ├─> setCurrentDraftId() - 현재 편집 중인 draft 설정
   └─> migrateLegacyDraft() - 기존 단일 draft 마이그레이션

4. 상태 관리 원칙

전역 상태: Zustand 사용 (인증, 사용자 진행 상황, 알림)
로컬 상태: useState 사용 (폼 입력, UI 토글, 에디터 내용)
로컬 저장소: LocalStorage (임시 저장 글)
서버 상태: Firestore 직접 호출 (React Query는 나중에 고려)

5. 태그 입력 필드 패턴 (Tag Input Field)

CreateTopicDialog의 제목 템플릿 입력에 사용되는 고급 UI 패턴입니다.

구현 방식:

// 상태 구조
type TemplatePart = {
  id: string;
  type: "text" | "placeholder";
  value: string;  // "{date}" 또는 일반 텍스트
  label?: string; // "날짜" (placeholder인 경우)
};

const [templateParts, setTemplateParts] = useState<TemplatePart[]>([]);
const [currentInput, setCurrentInput] = useState("");
const [selectedPartIndex, setSelectedPartIndex] = useState<number | null>(null);

주요 기능:

✅ 자동 플레이스홀더 감지: {date}, {time} 등 입력 시 자동으로 태그 변환
✅ 키보드 네비게이션:
- ← (왼쪽 화살표): 이전 part 선택
- → (오른쪽 화살표): 다음 part 선택 또는 입력 필드로 복귀
- Backspace: 선택된 part 삭제 (입력이 비어있으면 마지막 part 선택)
- Delete: 선택된 part 삭제 (다음 part로 이동)
- Enter: 현재 입력 확정
✅ 마우스 인터랙션:
- part 클릭: 해당 part 선택
- × 버튼: 즉시 삭제
✅ 시각적 피드백:
- 선택된 텍스트: 파란 배경 + 파란 테두리
- 선택된 태그: 진한 파란 테두리 + 투명도 감소

사용 사례:

템플릿 입력 (제목/내용 템플릿)
이메일 받는 사람 입력 (Gmail 스타일)
태그 입력 (해시태그, 키워드)
멘션 입력 (Slack, Discord 스타일)

참고 파일: src/components/writing/CreateTopicDialog.tsx:61-321

6. 팀 코드 시스템 아키텍처 (초등 저학년 로그인 간소화)

핵심 개념

문제: 초등 저학년은 이메일/비밀번호 로그인이 어려움 해결: 팀 소유자가 팀 코드를 발급하고, 학생은 간단히 로그인 아키텍처: currentStudent 중심, 정식 계정은 선택사항

계정 구조

정식 계정 (User) - 선택적
├─ Firebase Auth: user456 (Email/Google)
├─ Firestore: users/user456
└─ ownedStudentIds: ["studentDoc1", "studentDoc2"]
    │
    ├─> 학생 계정 1 (Student) - 독립적, 필수
    │   ├─ Firebase Auth: anon123 (Anonymous)
    │   ├─ Firestore: students/studentDoc1
    │   ├─ linkedUserId: user456 (1:1 관계)
    │   ├─ teamIds: ["team1", "team2"]
    │   └─ 모든 활동 데이터(writings, topics)는 studentId로 기록
    │
    └─> 학생 계정 2 (Student)
        └─ ... (동일 구조)

팀 코드 생성

한글 3단어 조합: [형용사/동사] + [색상] + [동물]

예시: "춤추는 파란 사자"

조합 수:
- 형용사/동사: 100개
- 색상: 20개
- 동물: 50개
→ 총 100,000가지 조합 (10만 개)

특징:
✅ 기억하기 쉬움 (이미지 연상)
✅ 구두 전달 가능 (말로 쉽게 전달)
✅ 타이핑 오타 최소화 (자동완성 가능)
✅ 초등 저학년도 이해 가능
✅ 재미있고 친근함 (팀 정체성 형성)

파일: src/data/classCodeWords.ts, src/utils/classCodeGenerator.ts

학생 로그인 플로우 (개선됨 - 2025-11-06)

1. 학생 로그인 (팀 코드 3단계)
   Step 1: 팀 코드 입력
   ├─> "춤추는 파란 사자" 입력
   ├─> Firestore teams 조회
   ├─> 소유자 체크 (본인 팀이면 /manage로 리다이렉트)
   └─> Step 2로 진행

   Step 2: 이름 입력 (선택 → 입력으로 개선)
   ├─> 이름 직접 입력 (예: "김민지")
   ├─> PIN 필요하면 Step 3 (PIN)
   └─> PIN 불필요하면 Step 3 (완료 화면)

   Step 3: PIN 입력 또는 완료 화면
   ├─> [PIN 필요] 숫자 패드로 PIN 입력 → 검증 → 완료 화면
   └─> [완료 화면] 참여/로그인 구분
       ├─> 신규: 🎉 "환영합니다! {이름}님, {팀명}에 참여했어요"
       └─> 재로그인: 👋 "반가워요! {이름}님, 다시 돌아왔군요!"

2. 로그인 완료
   ├─> Anonymous Auth 유지/생성
   ├─> authStore.currentStudent 설정
   └─> /team/[teamId] 멤버 페이지로 이동

2. 정식 계정 연결 (선택적, 학부모/고학년)
   ├─> 설정 → "내 계정 만들기"
   ├─> 이메일 회원가입 또는 Google 로그인
   ├─> linkWithCredential() 호출
   │   └─ Anonymous(anon123) → Email(user456) 전환
   ├─> Firestore 연결:
   │   ├─ students/studentDoc.linkedUserId = user456
   │   └─ users/user456.ownedStudentIds = [studentDoc]
   └─> 이후 user456으로 로그인 가능 (currentStudent 자동 설정)

3. 정식 계정 로그인 (학생 자동 선택)
   ├─> user456으로 로그인
   ├─> Firestore users/user456 조회
   ├─> ownedStudentIds로 students 조회
   ├─> 학생이 1명: 자동 선택
   ├─> 학생이 2명+: StudentPicker 표시 (누구로 활동할까요?)
   └─> authStore.currentStudent 설정

보안 모드

모드	인증 단계	사용 사례
simple	팀 코드 + 이름	교실 전용, 저학년 (1-2학년)
normal	팀 코드 + 이름 + PIN	가정 학습 포함, 고학년 (3-4학년)
open	팀 코드 + 자유 가입	전학생, 체험 학생 허용

Rate Limiting (학생 친화적)

5회 실패: 💡 "어려우면 팀을 만든 사람에게 물어보세요!"
10회 실패: ⚠️ "입력을 확인해주세요. 띄어쓰기는 안 해도 괜찮아요!"
15회 실패: 🔒 "2분 후에 다시 시도해주세요. 팀 관리자에게 도움을 요청하세요."

데이터 흐름

모든 활동 데이터는 studentId로 기록:

writings/{writingId}
├─ studentId: "studentDoc1"  ← 핵심! (userId 아님)
├─ title: "나의 하루"
└─ content: "..."

조회 시:
- 팀 코드 계정: getUserWritings(currentStudent.id)
- 정식 계정: ownedStudents.map(s => getUserWritings(s.id))

참고 파일:

src/managers/TeamManager.ts - 팀 관련 API 호출 + 캐싱
src/managers/StudentManager.ts - 학생 관련 API 호출 + 캐싱
src/managers/ManagerBase.ts - API 호출 및 캐싱 공통 로직
src/services/firebaseAuth.ts:125-316 - 학생 로그인 로직
src/store/authStore.ts - currentStudent 중심 상태 관리
src/types/api/team.ts - 팀 API 타입 정의
src/types/api/student.ts - 학생 API 타입 정의
API_SPEC.md - 전체 API 명세서 (23개 엔드포인트)

7. 실시간 피드백 시스템 (3-Layer 아키텍처) + 맞춤법 검사

핵심 개념

목적: Gemini API로 초등학생 글쓰기를 실시간 평가하면서 비용 최적화

문제:

매번 전체 텍스트 전송 = 비용 폭증
Rate Limit (15 RPM) = 사용자 2명만 접속해도 초과

해결: Delta 전송 + 캐싱 + Multi-Region Failover + 분석 히스토리

아키텍처

┌─────────────────────────────────────────┐
│ Layer 1: API Route                      │
│ src/app/api/analyze-text/route.ts      │
│                                         │
│ 역할:                                   │
│ - Delta 계산 (변경된 부분만 추출)        │
│ - 서버 캐싱 (In-Memory LRU, TTL 1분)    │
│ - textAnalysisService 호출              │
└─────────────────────────────────────────┘
              ↓
┌─────────────────────────────────────────┐
│ Layer 2: Business Logic                │
│ src/services/textAnalysisService.ts    │
│                                         │
│ 역할:                                   │
│ - 프롬프트 생성 (히스토리 포함)          │
│ - Response Schema 정의 (Type.OBJECT)    │
│ - JSON 파싱 (AI 응답 처리)              │
│ - 점수 제한 (최대 10점)                 │
│ - vertexAI 호출                         │
└─────────────────────────────────────────┘
              ↓
┌─────────────────────────────────────────┐
│ Layer 3: Infrastructure                │
│ src/services/vertexAI.ts                │
│                                         │
│ 역할:                                   │
│ - 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    │
│                                         │
│ 역할:                                   │
│ - Region별 과부하 상태 추적              │
│ - 429 에러 시 1분간 region 제외          │
│ - 자동 복구 (1분 경과 시)               │
└─────────────────────────────────────────┘

Multi-Region Strategy

사용 가능한 Regions (우선순위 순):

1. asia-northeast1 (도쿄) - 한국 최근접, ~50ms 🥇
2. asia-southeast1 (싱가포르) - 백업, ~100ms 🥈
3. us-central1 (미국) - 최종 대체, ~200ms 🥉

장애 시나리오:

요청 → 도쿄 region
      ↓ 429 Rate Limit
     도쿄를 1분간 "과부하" 마킹
      ↓
다음 요청 → 싱가포르 (자동 전환)
      ↓ 성공 ✅
계속 싱가포르 사용
      ↓ 1분 후
     도쿄 자동 복구
      ↓
다시 도쿄 우선 사용 (빠름)

Delta 전송 메커니즘

문제: 500자 전체 전송 = 토큰 낭비

해결: 변경분만 전송

// 클라이언트
const previousText = "오늘 날씨가 좋다."; // 15자
const currentText = "오늘 날씨가 좋다. 하늘이 맑다."; // 24자

fetch('/api/analyze-text', {
  body: JSON.stringify({
    text: currentText,
    previousText: previousText  // Delta 계산용
  })
});

// 서버
const delta = text.slice(previousText.length); // " 하늘이 맑다." (9자)
// → 9자만 Vertex AI로 전송 (60% 절감)

성능 최적화

비용 절감:

순수 AI: $0.18/글
Debounce: $0.036/글 (80% 절감)
Delta: $0.014/글 (92% 절감)
Delta + Cache: $0.009/글 (95% 절감) ⭐

처리량 증가:

Single Region: 15 RPM
Multi-Region (3개): 45 RPM (3배)
동시 사용자: 1~2명 → 3~5명

가용성 향상:

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 타입 확장:

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 - 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~~ - ❌ 삭제됨 (하이라이트로 대체)
~~src/components/writing/SpellingErrorDisplay.tsx~~ - ❌ 삭제됨 (하이라이트로 대체)
src/app/write/page.tsx - Delta 추적 + 통합 + Toast 알림

타입 정의:

src/types/draft.ts - Draft, AnalysisHistoryItem

유틸리티:

src/utils/koreanWordList.ts - 감각 동사/형용사 목록

문서:

TECHNICAL_IMPLEMENTATION.md - 상세 기술 구현 가이드
SERVICE_DIRECTION.md - 서비스 방향성 논의 (8차)

8. 글 작성 패턴 분석 시스템

핵심 개념

목적: 사용자의 여러 글을 분석하여 작성 패턴, 강점, 약점을 파악하고 맞춤형 피드백 제공

분석 항목:

작성 스타일: 평균 글자/단어 수, 선호하는 글 길이, 문장 구조 (단문/복문/혼합)
표현력 분석: 평균 점수, 강점/약점, 카테고리별 점수, 자주 쓰는 표현
맞춤법 경향: 자주 하는 실수, 개선율
발전 추이: 최근 5개 vs 이전 5개 비교, 개선 영역, 주의 필요 영역
AI 종합 평가: 전반적 평가, 격려 메시지, 맞춤형 추천 3가지

서비스 레이어:

patternAnalysisService.ts - 10개 글 종합 분석, Gemini 기반 AI 평가, Response Schema 사용

API:

POST /api/analyze-pattern - 최근 10개 글 분석 (5분 캐싱)
- 인증 필요 (ID Token)
- Firestore에서 글 조회 → 각 글 AI 분석 (병렬) → 패턴 분석 → 캐싱

컴포넌트:

WritingPatternDialog - 패턴 분석 다이얼로그 (로딩/에러/성공 상태)
WritingPatternDisplay - 분석 결과 표시 (종합 평가, 발전 추이, 작성 스타일, 표현력, 강점/약점, 자주 쓰는 표현, 추천)

타입:

src/types/writingPattern.ts - WritingPatternAnalysis, AnalyzePatternRequest/Response

참고 파일:

src/services/patternAnalysisService.ts - 패턴 분석 로직
src/app/api/analyze-pattern/route.ts - 패턴 분석 API
src/components/writing/WritingPatternDialog.tsx - 다이얼로그
src/components/writing/WritingPatternDisplay.tsx - 표시 컴포넌트
src/app/home/page.tsx - "작성 패턴 분석" 카드 추가

9. 실시간 하이라이트 시스템 (Tiptap Extensions)

핵심 개념

목적: 에디터에서 맞춤법 오류와 감각 단어를 실시간으로 시각적으로 표시

하이라이트 종류:

맞춤법 오류: 빨간 물결 밑줄 (spelling-error 클래스)
감각 동사: 초록색 하이라이트 (sensory-word 클래스)
감각 형용사: 파란색 하이라이트 (emotion-word 클래스)
의성어/의태어: 보라색 하이라이트 (onomatopoeia-word 클래스)

Tiptap Extensions:

SpellingHighlight - 맞춤법 오류 하이라이트
- data-original, data-correction, data-reason 속성
- Meta를 통한 강제 업데이트
SensoryWordHighlight - 감각 단어 하이라이트
- data-word, data-type 속성
- 색상별 구분 (초록/파랑/보라)

DecorationSet 기반:

ProseMirror Decoration을 사용한 효율적인 하이라이트
문서 변경 시 자동 업데이트
하이라이트 위치를 정확하게 추적

WritingEditor 통합:

spellingErrors, foundWords props 추가
Extension 옵션 실시간 업데이트
브라우저 기본 맞춤법 검사 비활성화 (spellcheck="false")

참고 파일:

src/extensions/spelling-highlight.ts - 맞춤법 하이라이트 Extension
src/extensions/sensory-word-highlight.ts - 감각 단어 하이라이트 Extension
src/components/writing/WritingEditor.tsx - Extensions 통합

10. 인터랙티브 툴팁 시스템

핵심 개념

목적: 하이라이트된 단어를 클릭하면 상세 정보를 툴팁으로 표시

툴팁 종류:

맞춤법 오류 툴팁:
- 원본 → 수정 (취소선 → 굵은 글씨)
- 이유 설명 (초등학생 눈높이)
- 빨간색 테두리
감각 단어 툴팁:
- 단어 표시
- 단어 타입 (감각 동사/형용사/의성어)
- 격려 메시지 ("이렇게 구체적으로 표현하면 글이 더 생생해져요!")
- 색상별 테두리 (초록/파랑/보라)

기술 구현:

Portal 사용 (z-index 문제 해결)
클릭한 요소의 data attributes 읽기
외부 클릭/ESC 키로 닫기
Fade-in 애니메이션

WritingEditor 통합:

DOM 클릭 이벤트 리스너 등록
하이라이트 클래스 확인 (spelling-error, sensory-word 등)
툴팁 위치 계산 (getBoundingClientRect)
여러 개 툴팁 동시 표시 가능 (배열 관리)

참고 파일:

src/components/writing/EditorTooltip.tsx - 툴팁 컴포넌트
src/components/writing/WritingEditor.tsx - 클릭 이벤트 처리

11. Toast 알림 시스템

핵심 개념

목적: 텍스트 분석 및 맞춤법 검사 진행 상태를 사용자에게 알림

알림 종류:

텍스트 분석:
- 시작: "글을 분석하고 있어요..." (loading, duration: Infinity)
- 완료: "분석 완료! 점수: X.X점" (success, 3초)
- 실패: "분석 실패, 다시 시도해주세요." (error, 3초)
맞춤법 검사:
- 시작: "맞춤법을 검사하고 있어요..." (loading, duration: Infinity)
- 완료: "맞춤법 검사 완료! X개의 오류 발견" 또는 "맞춤법 오류 없음!" (success, 3초)
- 실패: "맞춤법 검사 실패" (error, 3초)

기술 구현:

Chakra UI Toaster 사용
Toast ID 관리 (ref로 저장, dismiss 호출)
로딩 상태 toast는 수동으로 dismiss
성공/실패 시 기존 loading toast 제거 후 새 toast 표시

참고 파일:

src/app/write/page.tsx - Toast 알림 통합

참고 문서

PROJECT_STRUCTURE.md - 프로젝트 구조
ROADMAP.md - 개발 로드맵
CLAUDE.md - Claude Code 가이드

35 KiB Raw Blame History Unescape Escape

라온누리 - 기술 스택 및 개발 환경

기술 스택

Core Framework

UI & Styling

Backend & Database

Utilities

State Management

Development Tools

개발 명령어

주요 명령어

중요 사항

프로젝트 설정

Next.js 설정 (next.config.ts)

TypeScript 설정

ESLint 설정

환경 변수

.env.local 파일 구조

환경 변수 사용 예시

Firebase 설정

인증 제공자

Firestore 데이터베이스

Chakra UI v3 커스텀 테마

아키텍처 패턴

1. Manager 패턴 + API 아키텍처 (3계층 구조)

2. 인증 플로우 및 라우팅 (currentStudent 중심 아키텍처)

3. 글쓰기 및 저장 로직 (Manager 패턴 적용)

4. 상태 관리 원칙

5. 태그 입력 필드 패턴 (Tag Input Field)

6. 팀 코드 시스템 아키텍처 (초등 저학년 로그인 간소화)

핵심 개념

계정 구조

팀 코드 생성

학생 로그인 플로우 (개선됨 - 2025-11-06)

보안 모드

Rate Limiting (학생 친화적)

데이터 흐름

7. 실시간 피드백 시스템 (3-Layer 아키텍처) + 맞춤법 검사

핵심 개념

아키텍처

Multi-Region Strategy

Delta 전송 메커니즘

성능 최적화

새로운 평가 기준 (2025-11-11 개편)

분석 히스토리 시스템

참고 파일

8. 글 작성 패턴 분석 시스템

핵심 개념

9. 실시간 하이라이트 시스템 (Tiptap Extensions)

핵심 개념

10. 인터랙티브 툴팁 시스템

핵심 개념

11. Toast 알림 시스템

핵심 개념

참고 문서

35 KiB

Raw Blame History

Next.js 설정 (`next.config.ts`)

`.env.local` 파일 구조