201 lines
5.0 KiB
Markdown
201 lines
5.0 KiB
Markdown
# 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. |