# 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

---

## 개발 명령어

```bash
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 사용 (서비스 직접 호출 금지)**

```typescript
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 및 페이지는 다국어 지원이 필수입니다.**

```typescript
// ✅ 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"` 사용**:

```tsx
// ✅ 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` 싱글톤 사용

```typescript
// ✅ 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 응답**: 헬퍼 함수 필수

```typescript
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개 파일 업데이트 필수**:

1. `PROJECT_STRUCTURE.md` - 페이지 구조, 컴포넌트 목록
2. `ROADMAP.md` - 완료 작업, 예정 작업
3. `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`** - 개발 로드맵

---

© 2024 BlueNovaLab. All rights reserved.