baekryang/RaonNuri_Public_Documents

Fork 0

Documentation Bot 4832f932e9 docs: Sync documentation from private repository

2026-06-04 23:04:17 +00:00

5.0 KiB

Raw Permalink Blame History

AGENTS.md

This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.

프로젝트 개요

라온누리 (Raonnuri) - 초등학생 대상 창작 글쓰기 교육 플랫폼

Tech Stack: Next.js 16, React 19, Chakra UI v3, Firebase Auth, TypeScript

개발 명령어

npm run dev        # 개발 서버 (포트 3001, webpack 사용)
npm run build      # 프로덕션 빌드
npm run lint       # ESLint 실행
npx tsc --noEmit   # 타입 체크 (빌드 전 필수)

주의:

Dev server는 포트 3001 사용
React Compiler 활성화
커밋 전 타입 체크 필수 (npx tsc --noEmit)

핵심 아키텍처

Manager Pattern (필수)

모든 데이터 작업은 Manager 사용 (서비스 직접 호출 금지)

import { teamManager, userManager } from "@/managers";

// ✅ Good
const teams = await teamManager.getMyTeams();
const users = await userManager.getUsersByTeam(teamId);

// ❌ Bad - 서비스 직접 호출 금지

Available Managers:

teamManager - Team CRUD, member management, security level
userManager - User CRUD
draftManager - localStorage + Realtime DB 하이브리드
writingSessionManager - Real-time monitoring
writingManager, topicManager, feedManager

상세: API_SPEC.md 참조

Data Model 핵심 원칙

Firebase Auth = Single Source of Truth (이름, 이메일, 사진)

Firestore Users 컬렉션: uid, createdAt, lastLoginAt, settings만 저장
UI User 객체: Firebase Auth + Firestore 자동 결합
팀별 닉네임: team.members[uid].nickname (User 아님)
멤버 확인: uid in team.members

상세: DATA_MODELS.md 참조

필수 개발 규칙

다국어 지원 (i18n)

모든 새로운 UI 및 페이지는 다국어 지원이 필수입니다.

// ✅ Good
import {useTranslations} from "next-intl";
import {useRouter} from "@/i18n/routing";

const t = useTranslations('newPage');
return <h1>{t('title')}</h1>;

// ❌ Bad
return <h1>새 페이지</h1>;  // 하드코딩 금지!

상세: I18N_GUIDE.md 참조

스타일 가이드

버튼에는 항상 colorPalette="brand" 사용:

// ✅ Good
<Button colorPalette="brand">클릭</Button>

// ❌ Bad
<Button>클릭</Button>  // 기본 gray 사용 금지

Semantic 토큰 우선 사용 (숫자/하드코딩 금지):

color="fg" / color="fg.muted"
bg="bg" / bg="brand.subtle"
borderColor="border.muted"

Icon 규칙: react-icons 필수 (이모티콘 금지)

✅ react-icons/lu (Lucide) - 메인 아이콘 세트
❌ 이모티콘 (🌍📝) - 사용 금지

상세: STYLE_GUIDE.md 참조

API 개발 규칙

RESTful 원칙: HTTP Method로 동작 구분

POST   /api/resource  → 생성/추가
DELETE /api/resource  → 삭제/제거
PUT    /api/resource  → 전체 수정
GET    /api/resource  → 조회

Firebase Admin SDK: adminFbClient 싱글톤 사용

// ✅ Good
import {adminFbClient} from "@/lib/firebase-admin";
const doc = await adminFbClient.collection('users').doc(uid).get();

// ❌ Bad
import {getFirestore} from "firebase-admin/firestore";
const db = getFirestore();  // 초기화 문제 발생 가능

API 응답: 헬퍼 함수 필수

import {successResponse, validationErrorResponse} from "@/lib/api-response";

// ✅ Good
return successResponse({ data });
return validationErrorResponse("에러 메시지");

// ❌ Bad
return NextResponse.json({success: false, ...});

상세: API_SPEC.md 참조

보안

초대 링크 기반 팀 참여: 디스코드 스타일 초대 시스템 사용

모든 유저는 로그인 필수 (익명 인증 삭제됨)
팀 참여는 초대 링크를 통해서만 가능
닫힌 팀 → 초대 안 만들면 됨

XSS 방지: 백엔드 자동 sanitize

src/lib/server/writing.ts에서 모든 HTML 자동 세탁
프론트엔드 별도 처리 불필요

상세: SECURITY.md 참조

Documentation Requirements

모든 새 기능/페이지는 다음 3개 파일 업데이트 필수:

PROJECT_STRUCTURE.md - 페이지 구조, 컴포넌트 목록
ROADMAP.md - 완료 작업, 예정 작업
TECH_STACK.md - 아키텍처 패턴, 플로우 다이어그램

참조 문서

개발 가이드

API_SPEC.md - API 명세서, RESTful 원칙, Firebase Admin SDK
STYLE_GUIDE.md - Color 사용법, Icon 규칙, Chakra UI 테마
FRONTEND_DESIGN_PATTERNS.md - 컴포넌트 디자인 철학, 인터랙션/시각/애니메이션 패턴
I18N_GUIDE.md - 다국어 지원 가이드 (필수)
DEVELOPMENT_GUIDE.md - AI Delta 전송, Draft 저장, Firebase Functions

프로젝트 문서

PROJECT_STRUCTURE.md - 프로젝트 구조
TECH_STACK.md - 기술 스택, 아키텍처
DATA_MODELS.md - 데이터베이스 스키마
SECURITY.md - 보안 정책, 3단계 보안 레벨
ROADMAP.md - 개발 로드맵

5.0 KiB Raw Permalink Blame History