RaonNuri_Public_Documents/TECH_STACK.md

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

최종 업데이트: 2025-11-10 (주제 변경 경고 Dialog, 다중 글조각 관리)

---

기술 스택

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 데이터베이스 (글 저장)
Redis	-	Cache 데이터 베이스 (예정)

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개 엔드포인트)

---

참고 문서

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

---

© 2024 BlueNovaLab. All rights reserved.