# claudedocs 문서 맵

> 프로젝트 기술 문서 인덱스 (Last Updated: 2025-11-28)

## 폴더 구조

```
claudedocs/
├── _index.md           # 이 파일 - 문서 맵
├── auth/               # 🔐 인증 & 토큰 관리
├── item-master/        # 📦 품목기준관리
├── dashboard/          # 📊 대시보드 & 사이드바
├── api/                # 🔌 API 통합
├── guides/             # 📚 범용 가이드
├── architecture/       # 🏗️ 아키텍처 & 시스템
└── archive/            # 📁 레거시/완료된 문서
```

---

## 🔐 auth/ - 인증 & 토큰 관리

| 파일 | 설명 |
|------|------|
| `token-management-guide.md` | ⭐ **핵심** - Access/Refresh Token 완전 가이드 |
| `jwt-cookie-authentication-final.md` | JWT + HttpOnly Cookie 구현 |
| `auth-guard-usage.md` | AuthGuard 훅 사용법 |
| `route-protection-architecture.md` | 라우트 보호 아키텍처 |
| `middleware-issue-resolution.md` | 미들웨어 이슈 해결 |
| `safari-cookie-compatibility.md` | Safari 쿠키 호환성 |
| `httponly-cookie-implementation.md` | HttpOnly 쿠키 구현 계획 |
| `httponly-cookie-security-validation.md` | 보안 검증 케이스 |
| `session-migration-*.md` | 세션 마이그레이션 관련 |
| `nextjs15-middleware-*.md` | Next.js 15 미들웨어 연구 |

---

## 📦 item-master/ - 품목기준관리

| 파일 | 설명 |
|------|------|
| `[PLAN-2025-11-28] dynamic-item-form-implementation.md` | ✅ **Phase 1-6 완료** - 품목관리 동적 렌더링 구현 (타입, 훅, 필드, 렌더러, 메인폼, Feature Flag) |
| `[API-REQUEST-2025-11-28] dynamic-page-rendering-api.md` | ⭐ **v3.1** - 동적 페이지 렌더링 API 요청서 (ID 기반 통일) |
| `[PLAN-2025-11-27] item-form-component-separation.md` | ✅ **완료** - ItemForm 컴포넌트 분리 (1607→415줄, 74% 감소) |
| `[IMPL-2025-11-27] realtime-sync-fixes.md` | 실시간 동기화 수정 (BOM, 섹션 복제, 항목 수정, **페이지 삭제 시 섹션 동기화** 2025-11-28) |
| `item-master-api-pending-tasks.md` | 진행중인 API 연동 작업 |
| `item-master-pending-integration.md` | 대기중인 통합 작업 |
| `item-master-specification.md` | API 명세 |
| `item-master-backend-requirements.md` | 백엔드 요구사항 |
| `item-management-dynamic-api-spec.md` | 동적 필드 API 스펙 |
| `item-management-dynamic-frontend.md` | 동적 필드 프론트엔드 설계 |
| `item-master-data-management.md` | 데이터 관리 분석 |
| `item-master-hooks-refactoring.md` | Hooks 리팩토링 |
| `ITEM-MANAGEMENT-MIGRATION.md` | 마이그레이션 가이드 |

---

## 📊 dashboard/ - 대시보드 & 사이드바

| 파일 | 설명 |
|------|------|
| `dashboard-integration-complete.md` | 대시보드 통합 완료 |
| `dashboard-cleanup-summary.md` | 정리 요약 |
| `dashboard-migration-summary.md` | 마이그레이션 요약 |
| `sidebar-active-menu-sync.md` | 사이드바 메뉴 동기화 |
| `sidebar-scroll-improvements.md` | 스크롤 개선 |

---

## 🔌 api/ - API 통합

| 파일 | 설명 |
|------|------|
| `api-requirements.md` | API 요구사항 |
| `api-analysis.md` | API 분석 |
| `api-route-type-safety.md` | 라우트 타입 안전성 |
| `api-key-management.md` | API 키 관리 |

---

## 📚 guides/ - 범용 가이드

| 파일 | 설명 |
|------|------|
| `i18n-usage-guide.md` | 다국어 사용 가이드 |
| `form-validation-guide.md` | 폼 유효성 검사 |
| `CSS-MIGRATION-WORKFLOW.md` | CSS 마이그레이션 워크플로우 |
| `LARGE-FILE-WORKFLOW.md` | 대용량 파일 작업 워크플로우 |
| `ZOD-VALIDATION-TROUBLESHOOTING.md` | Zod 유효성 검사 트러블슈팅 |
| `nextjs-error-handling-guide.md` | Next.js 에러 처리 |

---

## 🏗️ architecture/ - 아키텍처 & 시스템

| 파일 | 설명 |
|------|------|
| `multi-tenancy-implementation.md` | 멀티테넌시 구현 |
| `multi-tenancy-test-guide.md` | 멀티테넌시 테스트 |
| `architecture-integration-risks.md` | 통합 리스크 |
| `browser-support-policy.md` | 브라우저 지원 정책 |
| `ssr-hydration-fix.md` | SSR 하이드레이션 수정 |

---

## 📁 archive/ - 레거시/완료된 문서

완료되거나 더 이상 활성화되지 않은 문서들. 참조용으로 보관.

---

## 문서 작성 규칙

### 파일명 컨벤션
```
[TYPE-YYYY-MM-DD] description.md
```

**TYPE 종류**:
- `IMPL` - 구현 문서
- `API` - API 명세/요청
- `GUIDE` - 사용 가이드
- `REF` - 참조 문서
- `ANALYSIS` - 분석 노트
- `PLAN` - 계획 문서
- `DESIGN` - 설계 문서
- `TEST` - 테스트 가이드
- `NEXT` - 다음 작업 목록

### 폴더 배치 기준
1. **기능/도메인 우선**: 문서 주제에 맞는 폴더에 배치
2. **범용 가이드**: 여러 기능에 적용되면 `guides/`에 배치
3. **완료된 작업**: 더 이상 활성화되지 않으면 `archive/`로 이동
4. **신규 도메인**: 3개 이상 문서가 생기면 새 폴더 생성 고려

### 문서 업데이트
- 중요 변경 시 문서 상단에 날짜와 함께 변경사항 기록
- `_index.md`에 새 문서 추가 시 테이블 업데이트