sam-react-prod/claudedocs/00_INDEX.md

# 프로젝트 문서 인덱스 (구현 순서 기반)

> 이 문서는 실제 프로젝트 구현 순서에 따라 문서들을 정리한 인덱스입니다.

## 📂 문서 분류

### ✅ 구현 완료 (Implementation Completed)
실제 코드로 구현되어 프로젝트에 적용된 기능

### 📋 참고 자료 (Reference)
기획/조사 단계의 문서, 또는 향후 구현 참고용 자료

### 🚧 진행 중 (In Progress)
일부 구현되었으나 완료되지 않은 기능

---

## 🎯 구현 순서별 문서 목록

### Phase 1: 프로젝트 초기 설정

#### ✅ 1. 다국어 지원 (i18n)
**파일**: `i18n-usage-guide.md`
**상태**: ✅ 구현 완료
**구현 내용**:
- next-intl 라이브러리 설정
- 한국어(ko), 영어(en), 일본어(ja) 3개 언어 지원
- `/src/i18n/config.ts` - 언어 설정
- `/src/i18n/request.ts` - 메시지 로딩
- `/src/messages/{locale}.json` - 번역 파일
- Middleware에서 로케일 자동 감지

**관련 파일**:
```
src/i18n/config.ts
src/i18n/request.ts
src/messages/ko.json, en.json, ja.json
src/middleware.ts (i18n 부분)
```

---

### Phase 2: 보안 및 Bot 차단

#### ✅ 2. SEO Bot 차단 설정
**파일**: `seo-bot-blocking-configuration.md`
**상태**: ✅ 구현 완료
**구현 내용**:
- Middleware에서 bot user-agent 감지
- 보호된 경로에 대한 bot 접근 차단
- 로봇 차단 헤더 추가 (`X-Robots-Tag`)

**관련 파일**:
```
src/middleware.ts (BOT_PATTERNS, isBot 함수)
```

---

### Phase 3: 인증 시스템

#### ✅ 3. API 분석 및 인증 방식 결정
**파일**: `api-analysis.md` ➜ `api-requirements.md`
**상태**: 📋 참고 자료
**목적**:
- Laravel API 엔드포인트 분석
- 인증 방식 비교 (Bearer Token vs Session Cookie)
- 최종 결정: **Bearer Token (JWT) + Cookie 저장 방식**

---

#### ✅ 4. 인증 시스템 설계
**파일**: `authentication-design.md`
**상태**: 📋 참고 자료 (초기 Sanctum 설계)
**목적**: Sanctum 세션 쿠키 방식 설계 (레거시)

**파일**: `jwt-cookie-authentication-final.md`
**상태**: ✅ 구현 완료 (최종 설계)
**구현 내용**:
- JWT Token을 쿠키에 저장
- Middleware에서 `user_token` 쿠키 확인
- 3가지 인증 방식 지원: Bearer Token/Sanctum/API-Key

**관련 파일**:
```
src/lib/api/auth/types.ts
src/lib/api/auth/auth-config.ts
src/lib/api/client.ts
src/middleware.ts (인증 체크 로직)
```

---

#### ✅ 5. 인증 구현 가이드
**파일**: `authentication-implementation-guide.md`
**상태**: ✅ 구현 완료
**구현 내용**:
- 3가지 인증 방식 통합 (Bearer/Sanctum/API-Key)
- API Client 구현
- Route 보호 메커니즘

**관련 파일**:
```
src/lib/api/auth/*
src/app/api/auth/* (로그인/로그아웃 API 라우트)
```

---

#### ✅ 6. API Key 관리
**파일**: `api-key-management.md`
**상태**: ✅ 구현 완료
**구현 내용**:
- 환경 변수를 통한 API Key 관리
- `.env.local`에 `API_KEY` 저장
- API 요청 시 자동으로 헤더에 추가

**관련 파일**:
```
.env.local (API_KEY)
src/lib/api/client.ts
```

---

#### ✅ 7. Middleware 인증 문제 해결
**파일**: `middleware-issue-resolution.md`
**상태**: ✅ 해결 완료
**문제**: 로그인하지 않아도 `/dashboard` 접근 가능
**원인**: `isPublicRoute()` 함수 버그 - `'/'`가 모든 경로와 매칭됨
**해결**:
- `'/'` 경로는 정확히 일치할 때만 public
- 기타 경로는 `startsWith(route + '/')` 방식
- Next.js 15 + next-intl 호환성 설정 (`turbopack: {}`)

**관련 파일**:
```
src/middleware.ts (isPublicRoute 함수)
next.config.ts (turbopack 설정)
```

---

### Phase 4: 라우팅 및 보호

#### ✅ 8. Route 보호 아키텍처
**파일**: `route-protection-architecture.md`
**상태**: ✅ 구현 완료
**구현 내용**:
- Protected Routes: `/dashboard`, `/admin`, etc.
- Guest-only Routes: `/login`, `/register`
- Public Routes: `/`, `/about`, `/contact`
- Middleware에서 라우트 타입별 처리

**관련 파일**:
```
src/lib/api/auth/auth-config.ts (라우트 설정)
src/middleware.ts (라우트 보호 로직)
```

---

#### ✅ 9. Auth Guard 사용법
**파일**: `auth-guard-usage.md`
**상태**: 🚧 부분 구현
**구현 내용**:
- Hook 기반: `useAuthGuard()` 훅
- Layout 기반: `(protected)` 폴더

**관련 파일**:
```
src/hooks/useAuthGuard.ts
src/app/[locale]/(protected)/layout.tsx
```

---

### Phase 5: UI 및 폼 검증

#### ✅ 10. 폼 Validation
**파일**: `form-validation-guide.md`
**상태**: ✅ 구현 완료
**구현 내용**:
- react-hook-form + zod 조합
- 로그인/회원가입 폼 검증

**관련 파일**:
```
src/lib/validations/auth.ts
src/components/auth/LoginPage.tsx
src/components/auth/SignupPage.tsx
```

---

#### ✅ 11. 테마 선택 및 언어 선택
**상태**: ✅ 구현 완료
**구현 내용**:
- 다크모드/라이트모드 전환
- 테마 Context 관리
- 언어 선택 컴포넌트

**관련 파일**:
```
src/contexts/ThemeContext.tsx
src/components/ThemeSelect.tsx
src/components/LanguageSelect.tsx
```

---

### Phase 6: 대시보드 시스템

#### ✅ 12. Dashboard 마이그레이션 및 통합
**파일**: `[IMPL-2025-11-10] dashboard-integration-complete.md`
**상태**: ✅ 구현 완료 (2025-11-10)
**구현 내용**:
- Vite React → Next.js 마이그레이션
- 역할 기반 대시보드 시스템 (CEO, ProductionManager, Worker, SystemAdmin, Sales)
- Lazy loading으로 성능 최적화
- localStorage 기반 역할 관리

**관련 파일**:
```
src/components/business/Dashboard.tsx
src/components/business/CEODashboard.tsx
src/components/business/ProductionManagerDashboard.tsx
src/components/business/WorkerDashboard.tsx
src/components/business/SystemAdminDashboard.tsx
src/layouts/DashboardLayout.tsx
```

---

#### ✅ 13. Dashboard Layout 정리
**파일**: `[IMPL-2025-11-11] dashboard-cleanup-summary.md`
**상태**: ✅ 구현 완료 (2025-11-11)
**구현 내용**:
- 테스트용 역할 선택 셀렉트 제거
- 간단한 로그아웃 버튼으로 교체
- UI 단순화 및 사용자 혼란 방지

**관련 파일**:
```
src/layouts/DashboardLayout.tsx
```

---

#### ✅ 14. 차트 렌더링 경고 수정
**파일**: `[IMPL-2025-11-11] chart-warning-fix.md`
**상태**: ✅ 구현 완료 (2025-11-11)
**구현 내용**:
- recharts ResponsiveContainer 높이 명시적 설정
- "width(-1) and height(-1)" 경고 해결
- 차트 즉시 렌더링 개선

**관련 파일**:
```
src/components/business/CEODashboard.tsx
```

---

#### ✅ 15. Token 관리 가이드
**파일**: `[IMPL-2025-11-10] token-management-guide.md`
**상태**: ✅ 구현 완료 (2025-11-10)
**구현 내용**:
- JWT Token 저장 및 관리 방식
- HttpOnly Cookie 사용
- Token 갱신 로직

**관련 파일**:
```
src/app/api/auth/login/route.ts
src/app/api/auth/check/route.ts
src/middleware.ts
```

---

### Phase 7: UI/UX 개선

#### ✅ 16. Sidebar 활성 메뉴 동기화
**파일**: `[IMPL-2025-11-11] sidebar-active-menu-sync.md`
**상태**: ✅ 구현 완료 (2025-11-11)
**구현 내용**:
- URL 기반 활성 메뉴 자동 감지
- 서브메뉴 우선 매칭 로직
- 메뉴 탐색 알고리즘 개선

**관련 파일**:
```
src/layouts/DashboardLayout.tsx
```

---

#### ✅ 17. Sidebar 스크롤 개선
**파일**: `[IMPL-2025-11-13] sidebar-scroll-improvements.md`
**상태**: ✅ 구현 완료 (2025-11-13)
**구현 내용**:
- 활성 메뉴 자동 스크롤 기능
- 호버 시에만 스크롤바 표시
- 부드러운 스크롤 애니메이션

**관련 파일**:
```
src/components/layout/Sidebar.tsx
src/app/globals.css (sidebar-scroll 스타일)
```

---

#### ✅ 18. 모달 Select 레이아웃 시프트 방지
**파일**: `[IMPL-2025-11-12] modal-select-layout-shift-fix.md`
**상태**: ✅ 구현 완료 (2025-11-12)
**구현 내용**:
- Shadcn UI Select 컴포넌트 레이아웃 시프트 방지
- 포털 사용으로 모달 내 Select 안정화

---

#### ✅ 19. 에러 페이지 설정
**파일**: `[IMPL-2025-11-11] error-pages-configuration.md`
**상태**: ✅ 구현 완료 (2025-11-11)
**구현 내용**:
- Next.js 15 App Router 에러 처리
- error.tsx, not-found.tsx 구성
- 다국어 지원 에러 메시지

**관련 파일**:
```
src/app/[locale]/error.tsx
src/app/[locale]/not-found.tsx
src/app/[locale]/(protected)/error.tsx
```

---

### Phase 8: 브라우저 호환성

#### ✅ 20. Safari 쿠키 호환성
**파일**: `[IMPL-2025-11-13] safari-cookie-compatibility.md`
**상태**: ✅ 구현 완료 (2025-11-13)
**구현 내용**:
- SameSite=Strict → SameSite=Lax 변경
- 개발 환경에서 Secure 속성 제외 (Safari 호환)
- 쿠키 설정/삭제 시 동일한 속성 사용

**관련 파일**:
```
src/app/api/auth/login/route.ts
src/app/api/auth/logout/route.ts
src/app/api/auth/check/route.ts
```

---

#### ✅ 21. 브라우저 지원 정책
**파일**: `[IMPL-2025-11-13] browser-support-policy.md`
**상태**: ✅ 구현 완료 (2025-11-13)
**구현 내용**:
- Internet Explorer 차단
- 안내 페이지 제공 (unsupported-browser.html)
- Middleware에서 IE User-Agent 감지

**관련 파일**:
```
src/middleware.ts (isInternetExplorer 함수)
public/unsupported-browser.html
```

---

### Phase 9: 타입 안전성

#### ✅ 22. API 라우트 타입 안전성
**파일**: `[IMPL-2025-11-11] api-route-type-safety.md`
**상태**: ✅ 구현 완료 (2025-11-11)
**구현 내용**:
- TypeScript 인터페이스 정의
- API 응답 타입 검증
- 타입 안전한 에러 처리

**관련 파일**:
```
src/app/api/auth/*/route.ts
```

---

### Phase 10: 참고 자료 및 가이드

#### 📋 23. Next.js 에러 핸들링 가이드
**파일**: `[REF] nextjs-error-handling-guide.md`
**상태**: 📋 참고 자료
**목적**: Next.js 15 App Router 에러 처리 종합 가이드

---

#### 📋 24. 컴포넌트 사용 분석
**파일**: `[REF-2025-11-12] component-usage-analysis.md`
**상태**: 📋 참고 자료
**목적**: 프로젝트 내 컴포넌트 사용 현황 분석

---

#### 📋 25. 세션 마이그레이션 가이드
**파일**:
- `[REF-2025-11-12] session-migration-backend.md`
- `[REF-2025-11-12] session-migration-frontend.md`
- `[REF-2025-11-12] session-migration-summary.md`

**상태**: 📋 참고 자료 (미구현)
**목적**: JWT → 세션 기반 인증 전환 가이드

---

#### 📋 26. Dashboard 마이그레이션 요약
**파일**: `[REF-2025-11-10] dashboard-migration-summary.md`
**상태**: 📋 참고 자료
**목적**: Vite React → Next.js 마이그레이션 과정 기록

---

#### 📋 27. Production 배포 체크리스트
**파일**: `[REF] production-deployment-checklist.md`
**상태**: 📋 참고 자료
**목적**: 배포 전 확인 사항 체크리스트

---

#### 📋 28. 코드 품질 리포트
**파일**: `[REF] code-quality-report.md`
**상태**: 📋 참고 자료
**목적**: 코드 품질 분석 결과

---

#### 📋 29. 아키텍처 통합 리스크
**파일**: `[REF] architecture-integration-risks.md`
**상태**: 📋 참고 자료
**목적**: 인증/i18n/bot 차단 통합 시 리스크 분석

---

### Phase 11: 보안 연구 및 개선

#### 📋 30. Token 보안 연구 (Next.js 15)
**파일**: `[REF-2025-11-07] research_token_security_nextjs15.md`
**상태**: 📋 참고 자료
**목적**: JWT Token 보안 연구

---

#### 📋 31. Middleware 인증 연구
**파일**: `[REF-2025-11-07] research_nextjs15_middleware_authentication.md`
**상태**: 📋 참고 자료
**목적**: Next.js 15 Middleware 인증 방식 조사

---

#### 📋 32. HttpOnly Cookie 구현
**파일**: `[REF-Future] httponly-cookie-implementation.md`
**상태**: 📋 참고 자료 (미구현)
**목적**: HttpOnly Cookie 방식 설계 (보안 강화 옵션)

---

#### 📋 33. 커뮤니케이션 개선 가이드
**파일**: `[REF] communication_improvement_guide.md`
**상태**: 📋 참고 자료
**목적**: 프로젝트 커뮤니케이션 개선 방안

---

#### 📋 34. 프로젝트 컨텍스트
**파일**: `[REF] project-context.md`
**상태**: 📋 참고 자료
**목적**: 프로젝트 전체 개요 및 빠른 시작 가이드

---

## 🔍 빠른 검색

### 주제별 문서 찾기

| 주제 | 문서 |
|------|------|
| **프로젝트 개요** | `[REF] project-context.md` |
| **다국어** | `[IMPL-2025-11-06] i18n-usage-guide.md` |
| **인증 설계** | `[IMPL-2025-11-07] jwt-cookie-authentication-final.md` |
| **인증 구현** | `[IMPL-2025-11-07] authentication-implementation-guide.md` |
| **Bot 차단** | `[IMPL-2025-11-07] seo-bot-blocking-configuration.md` |
| **Route 보호** | `[IMPL-2025-11-07] route-protection-architecture.md` |
| **Middleware** | `[IMPL-2025-11-07] middleware-issue-resolution.md` |
| **폼 검증** | `[IMPL-2025-11-07] form-validation-guide.md` |
| **API 분석** | `[REF] api-analysis.md`, `[REF] api-requirements.md` |
| **Dashboard** | `[IMPL-2025-11-10] dashboard-integration-complete.md` |
| **Sidebar** | `[IMPL-2025-11-13] sidebar-scroll-improvements.md` |
| **Safari 호환성** | `[IMPL-2025-11-13] safari-cookie-compatibility.md` |
| **IE 차단** | `[IMPL-2025-11-13] browser-support-policy.md` |
| **에러 처리** | `[REF] nextjs-error-handling-guide.md` |
| **세션 마이그레이션** | `[REF-2025-11-12] session-migration-summary.md` |
| **배포** | `[REF] production-deployment-checklist.md` |

---

## 📝 업데이트 이력

| 날짜 | 변경 내용 |
|------|----------|
| 2025-11-13 | Phase 6-11 추가 (대시보드, UI/UX, 브라우저 호환성, 타입 안전성, 참고 자료) |
| 2025-11-10 | 인덱스 파일 생성, 구현 순서 기반 분류 |

---

## 📊 문서 통계

- **총 문서 수**: 38개
- **구현 완료 (IMPL)**: 21개
- **참고 자료 (REF)**: 16개
- **부분 구현 (PARTIAL)**: 1개

---

## 💡 사용 가이드

1. **새 세션 시작 시**: `project-context.md` 먼저 읽기
2. **특정 기능 작업 시**: 위 인덱스에서 관련 문서 찾기
3. **새 기능 추가 시**: 이 인덱스에 문서 추가 및 상태 업데이트