# 📚 프로젝트 문서 구조 및 인덱스

> **프로젝트**: Next.js 15 + Laravel 하이브리드 아키텍처
> **프론트엔드**: Next.js 15 App Router + React 19
> **백엔드**: PHP Laravel
> **작성일**: 2025-11-17
> **목적**: 프로젝트 문서 아카이브 및 빠른 참조

---

## 📖 문서 분류 체계

### 1. [GUIDE] - 개발 가이드
프로젝트 개발 시 참고해야 할 표준 워크플로우 및 가이드 문서

### 2. [IMPL-YYYY-MM-DD] - 구현 기록
특정 기능 구현 과정과 결과를 시간순으로 기록한 문서

### 3. [REF] - 참고 자료
아키텍처 분석, 리서치 결과, API 요구사항 등 참고용 문서

### 4. [PLAN] - 미래 계획
향후 구현 예정이거나 검토 중인 기능에 대한 계획 문서

### 5. [LEGACY] - 레거시 문서
과거 설계안이나 폐기된 접근 방법을 기록한 문서

---

## 📂 [GUIDE] 개발 가이드 (4개)

### CSS 및 마이그레이션
| 파일명 | 목적 | 주요 내용 |
|--------|------|-----------|
| `[GUIDE] CSS-MIGRATION-WORKFLOW.md` | React → Next.js CSS 마이그레이션 표준 프로세스 | 페이지별 CSS 비교/동기화 워크플로우, 체크리스트 기반 구현 |
| `[GUIDE] LARGE-FILE-WORKFLOW.md` | 대용량 파일(>1000줄) 작업 프로토콜 | 섹션별 분해 전략, 체계적 마이그레이션 방법론 |

### 시스템 설계
| 파일명 | 목적 | 주요 내용 |
|--------|------|-----------|
| `[GUIDE] ITEM-MANAGEMENT-MIGRATION.md` | 품목관리 시스템 마이그레이션 종합 가이드 | 하이브리드 아키텍처, 데이터 구조, API 연동 전략 |

### 기술 문제 해결
| 파일명 | 목적 | 주요 내용 |
|--------|------|-----------|
| `[GUIDE] ZOD-VALIDATION-TROUBLESHOOTING.md` | Zod 검증 라이브러리 문제 해결 | 영어 에러 메시지 문제, z.preprocess 패턴, 필수 필드 처리 |

---

## 🛠️ [IMPL] 구현 기록 (25개)

### 2025-11-06 (1개)
| 파일명 | 구현 내용 |
|--------|-----------|
| `[IMPL-2025-11-06] i18n-usage-guide.md` | 다국어(i18n) 시스템 구현 |

### 2025-11-07 (7개)
| 파일명 | 구현 내용 |
|--------|-----------|
| `[IMPL-2025-11-07] api-key-management.md` | API 키 관리 시스템 |
| `[IMPL-2025-11-07] auth-guard-usage.md` | 인증 가드 사용 방법 |
| `[IMPL-2025-11-07] authentication-implementation-guide.md` | 인증 시스템 구현 가이드 |
| `[IMPL-2025-11-07] form-validation-guide.md` | 폼 검증 시스템 |
| `[IMPL-2025-11-07] jwt-cookie-authentication-final.md` | JWT 쿠키 인증 최종 구현 |
| `[IMPL-2025-11-07] middleware-issue-resolution.md` | 미들웨어 이슈 해결 |
| `[IMPL-2025-11-07] route-protection-architecture.md` | 라우트 보호 아키텍처 |
| `[IMPL-2025-11-07] seo-bot-blocking-configuration.md` | SEO 봇 차단 설정 |

### 2025-11-10 (2개)
| 파일명 | 구현 내용 |
|--------|-----------|
| `[IMPL-2025-11-10] dashboard-integration-complete.md` | 대시보드 통합 완료 |
| `[IMPL-2025-11-10] token-management-guide.md` | 토큰 관리 시스템 |

### 2025-11-11 (5개)
| 파일명 | 구현 내용 |
|--------|-----------|
| `[IMPL-2025-11-11] api-route-type-safety.md` | API 라우트 타입 안전성 |
| `[IMPL-2025-11-11] chart-warning-fix.md` | 차트 경고 수정 |
| `[IMPL-2025-11-11] dashboard-cleanup-summary.md` | 대시보드 정리 요약 |
| `[IMPL-2025-11-11] error-pages-configuration.md` | 에러 페이지 설정 |
| `[IMPL-2025-11-11] sidebar-active-menu-sync.md` | 사이드바 활성 메뉴 동기화 |

### 2025-11-12 (1개)
| 파일명 | 구현 내용 |
|--------|-----------|
| `[IMPL-2025-11-12] modal-select-layout-shift-fix.md` | 모달 Select 레이아웃 시프트 수정 |

### 2025-11-13 (3개)
| 파일명 | 구현 내용 |
|--------|-----------|
| `[IMPL-2025-11-13] browser-support-policy.md` | 브라우저 지원 정책 |
| `[IMPL-2025-11-13] safari-cookie-compatibility.md` | Safari 쿠키 호환성 |
| `[IMPL-2025-11-13] sidebar-scroll-improvements.md` | 사이드바 스크롤 개선 |

### 2025-11-17 (1개)
| 파일명 | 구현 내용 |
|--------|-----------|
| `[IMPL-2025-11-17] item-list-css-sync.md` | 품목 리스트 CSS 동기화 |

---

## 📋 [REF] 참고 자료 (14개)

### 프로젝트 컨텍스트
| 파일명 | 내용 |
|--------|------|
| `[REF] project-context.md` | 프로젝트 전체 컨텍스트 및 아키텍처 개요 |
| `[REF] architecture-integration-risks.md` | 아키텍처 통합 리스크 분석 |
| `[REF] code-quality-report.md` | 코드 품질 리포트 |
| `[REF] communication_improvement_guide.md` | 커뮤니케이션 개선 가이드 |

### API 및 백엔드
| 파일명 | 내용 |
|--------|------|
| `[REF] api-requirements.md` | API 요구사항 (일반) |
| `[REF] api-requirements-items.md` | 품목관리 API 요구사항 |
| `[REF] api-analysis.md` | API 분석 |

### 인증 및 보안 리서치
| 파일명 | 내용 |
|--------|------|
| `[REF] nextjs15-middleware-authentication-research.md` | Next.js 15 미들웨어 인증 리서치 |
| `[REF] token-security-nextjs15-research.md` | 토큰 보안 리서치 |

### 마이그레이션 및 세션 관리
| 파일명 | 내용 |
|--------|------|
| `[REF] dashboard-migration-summary.md` | 대시보드 마이그레이션 요약 |
| `[REF] session-migration-backend.md` | 세션 마이그레이션 (백엔드) |
| `[REF] session-migration-frontend.md` | 세션 마이그레이션 (프론트엔드) |
| `[REF] session-migration-summary.md` | 세션 마이그레이션 요약 |

### 컴포넌트 및 배포
| 파일명 | 내용 |
|--------|------|
| `[REF] component-usage-analysis.md` | 컴포넌트 사용 분석 |
| `[REF] nextjs-error-handling-guide.md` | Next.js 에러 핸들링 가이드 |
| `[REF] production-deployment-checklist.md` | 프로덕션 배포 체크리스트 |

---

## 🚀 [PLAN] 미래 계획 (1개)

| 파일명 | 계획 내용 |
|--------|-----------|
| `[PLAN] httponly-cookie-implementation.md` | HttpOnly 쿠키 구현 계획 |

---

## 📜 [LEGACY] 레거시 문서 (1개)

| 파일명 | 내용 |
|--------|------|
| `[LEGACY] authentication-design.md` | 초기 인증 시스템 설계안 (폐기) |

---

## 🔍 빠른 검색 가이드

### 상황별 문서 찾기

#### 1. React → Next.js 마이그레이션 작업 시
```
[GUIDE] CSS-MIGRATION-WORKFLOW.md         # CSS 마이그레이션 표준 프로세스
[GUIDE] LARGE-FILE-WORKFLOW.md             # 대용량 파일 작업 방법
[GUIDE] ITEM-MANAGEMENT-MIGRATION.md       # 품목관리 시스템 전체 설계
```

#### 2. 품목관리 기능 개발 시
```
[REF] api-requirements-items.md            # 백엔드 API 요구사항
[GUIDE] ITEM-MANAGEMENT-MIGRATION.md       # 시스템 아키텍처 및 데이터 구조
[IMPL-2025-11-17] item-list-css-sync.md    # 품목 리스트 CSS 동기화 구현
```

#### 3. 인증/보안 관련 작업 시
```
[IMPL-2025-11-07] jwt-cookie-authentication-final.md  # JWT 쿠키 인증 구현
[IMPL-2025-11-07] route-protection-architecture.md    # 라우트 보호
[REF] token-security-nextjs15-research.md             # 토큰 보안 리서치
```

#### 4. 폼 검증 문제 해결 시
```
[GUIDE] ZOD-VALIDATION-TROUBLESHOOTING.md  # Zod 검증 문제 해결
[IMPL-2025-11-07] form-validation-guide.md # 폼 검증 구현 가이드
```

#### 5. UI/UX 이슈 해결 시
```
[IMPL-2025-11-12] modal-select-layout-shift-fix.md    # 모달 레이아웃 시프트
[IMPL-2025-11-13] safari-cookie-compatibility.md      # Safari 호환성
[IMPL-2025-11-13] sidebar-scroll-improvements.md      # 사이드바 스크롤
```

#### 6. 배포 준비 시
```
[REF] production-deployment-checklist.md   # 배포 체크리스트
[IMPL-2025-11-13] browser-support-policy.md # 브라우저 지원 정책
[REF] code-quality-report.md               # 코드 품질 리포트
```

---

## 📊 문서 통계

| 카테고리 | 문서 수 | 비율 |
|----------|---------|------|
| [GUIDE] | 4 | 8.7% |
| [IMPL] | 25 | 54.3% |
| [REF] | 14 | 30.4% |
| [PLAN] | 1 | 2.2% |
| [LEGACY] | 1 | 2.2% |
| [INDEX] | 1 | 2.2% |
| **합계** | **46** | **100%** |

---

## 🎯 문서 작성 원칙

### 1. 명명 규칙
- **[GUIDE]**: 대문자, 하이픈으로 단어 구분
- **[IMPL-YYYY-MM-DD]**: 구현 날짜 포함, 소문자, 하이픈 구분
- **[REF]**: 소문자, 하이픈 구분

### 2. 문서 구조
- 명확한 목차
- 코드 예제 포함
- 실행 가능한 명령어
- 트러블슈팅 섹션

### 3. 유지보수
- 구현 완료 시 즉시 [IMPL] 문서 작성
- 워크플로우 개선 시 [GUIDE] 업데이트
- 레거시 문서는 [LEGACY]로 이동, 삭제 금지

---

## 📝 문서 업데이트 이력

| 날짜 | 변경 내용 |
|------|-----------|
| 2025-11-17 | 초기 인덱스 문서 작성 |
| 2025-11-17 | 모든 문서 명명 규칙 통일 |

---

## 🔗 관련 리소스

- **프로젝트 루트**: `/Users/byeongcheolryu/codebridgex/sam_project/sam-next/sma-next-project/sam-react-prod`
- **문서 디렉토리**: `claudedocs/`
- **React 소스**: `sma-react-v2.0/`
- **Next.js 소스**: `src/`

---

**마지막 업데이트**: 2025-11-17
**문서 버전**: 1.0.0
**관리자**: Claude + Development Team