# claudedocs 문서 맵

> 프로젝트 기술 문서 인덱스 (Last Updated: 2026-01-29)

## ⭐ 빠른 참조

| 문서 | 설명 |
|------|------|
| **[`[REF] all-pages-test-urls.md`](./[REF]%20all-pages-test-urls.md)** | 🔗 **전체 페이지 테스트 URL 목록** - 모든 페이지 직접 접근 주소 |

---

## 폴더 구조

```
claudedocs/
├── _index.md           # 이 파일 - 문서 맵
├── auth/               # 🔐 인증 & 토큰 관리
├── hr/                 # 👥 인사관리 (부서/사원)
├── item-master/        # 📦 품목기준관리
├── production/         # 🏭 생산관리 (생산현황판/작업지시)
├── quality/            # 🔬 품질관리 (검사관리)
├── sales/              # 💰 판매관리 (견적/거래처)
├── accounting/         # 💳 회계관리 (매입/매출/출금)
├── board/              # 📝 게시판 관리
├── settings/           # ⚙️ 설정 관리
├── dashboard/          # 📊 대시보드 & 사이드바
├── api/                # 🔌 API 통합
├── guides/             # 📚 범용 가이드
├── architecture/       # 🏗️ 아키텍처 & 시스템
├── juil/               # 🏗️ 주일 공사 MES (NEW)
└── archive/            # 📁 레거시/완료된 문서
```

---

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

| 파일 | 설명 |
|------|------|
| `[IMPL-2025-12-30] token-refresh-caching.md` | 🔴 **NEW** - 토큰 갱신 캐싱 구현 (동시 요청 충돌 해결, Request Coalescing 패턴) |
| `[IMPL-2025-12-04] signup-page-blocking.md` | ✅ **완료** - MVP 회원가입 페이지 차단 (운영 페이지 이동 예정) |
| `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 미들웨어 연구 |

---

## 👥 hr/ - 인사관리 (부서/사원/근태/휴가)

| 파일 | 설명 |
|------|------|
| `[IMPL-2025-12-16] mobile-attendance.md` | 🔴 **NEW** - 모바일 출퇴근 시스템 (카카오맵 GPS 기반, MVP) |
| `[IMPL-2025-12-05] department-management-checklist.md` | ✅ **완료** - 부서관리 구현 체크리스트 (무제한 트리구조) |
| `[IMPL-2025-12-05] employee-management-checklist.md` | ✅ **완료** - 사원관리 구현 체크리스트 |
| `[IMPL-2025-12-06] vacation-management-checklist.md` | ✅ **완료** - 휴가관리 구현 체크리스트 |

---

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

| 파일 | 설명 |
|------|------|
| `[PLAN-2025-12-16] dynamicitemform-hook-extraction.md` | 🔴 **NEW** - DynamicItemForm 훅 분리 계획서 (2161줄 → 900줄 목표, 6 Phase) |
| `[FIX-2025-12-16] options-details-duplicate-bug.md` | options vs item_details 중복 저장 버그 (bending_details 값 덮어쓰기 문제 해결) |
| `[IMPL-2025-12-15] backend-item-api-migration.md` | 백엔드 품목 API 통합 (product/material → items), group_id 파라미터, **향후 동적 변경 예정** |
| `[NEXT-2025-12-13] item-file-upload-session-context.md` | ⭐ **세션 체크포인트** - 파일 업로드 UI 개선 완료, 백엔드 대기 중, DynamicItemForm 분리 예정 |
| `[NEXT-2025-12-12] item-crud-session-context.md` | 📁 이전 세션 - BOM/파일 연동 완료, 파일 업로드 동적화 작업 추가 |
| `[DESIGN-2025-12-12] item-master-form-builder-roadmap.md` | 🆕 **로드맵** - Low-Code Form Builder 확장 설계 (노션 스타일 블록 시스템) |
| `[PLAN-2025-12-08] dynamic-form-separation-plan.md` | 📋 DynamicItemForm 품목별 분리 계획 (Phase 2: 컴포넌트 구조 설계) |
| `[REF] item-code-hardcoding.md` | ⭐ **핵심** - 품목관리 하드코딩 내역 종합 (품목유형/코드자동생성/전개도/BOM) |
| `[IMPL-2025-12-02] item-code-auto-generation.md` | 품목코드 자동생성 구현 상세 |
| `[PLAN-2025-12-01] service-layer-refactoring.md` | ✅ **완료** - 서비스 레이어 리팩토링 계획 (도메인 로직 중앙화) |
| `[REF-2025-12-01] state-sync-solutions.md` | 📋 **참조** - 상태 동기화 문제 및 해결 방안 (정규화, React Query 등) |
| `[PLAN-2025-11-28] dynamic-item-form-implementation.md` | ⚠️ **롤백됨** - 이전 구현 계획 (참조용) |
| `[IMPL-2025-12-02] dynamic-item-form-rebuild.md` | 🔄 **진행중** - 품목관리 동적 페이지 재구현 (디자인 100% 동일 유지) |
| `[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` | 마이그레이션 가이드 |

---

## 🏭 production/ - 생산관리 (생산현황판/작업지시)

| 파일 | 설명 |
|------|------|
| `[IMPL-2025-12-22] production-dashboard-checklist.md` | 🔴 **NEW** - 생산 현황판 구현 체크리스트 (메인/작업자화면, 8 Phase) |

---

## 🔬 quality/ - 품질관리 (검사관리)

| 파일 | 설명 |
|------|------|
| `[IMPL-2025-12-23] inspection-management-checklist.md` | 🔴 **NEW** - 검사관리 구현 체크리스트 (리스트/등록/상세/수정, 7 Phase) |

---

## 💰 sales/ - 판매관리 (견적/거래처/단가)

| 파일 | 설명 |
|------|------|
| `[API-2025-12-08] pricing-api-enhancement-request.md` | 🔴 **NEW** - 단가관리 백엔드 API 개선 요청서 (스키마 변경, 신규 엔드포인트) |
| `[IMPL-2025-12-05] pricing-management-migration.md` | 🔄 **진행중** - 단가관리 마이그레이션 계획 (7 Phase, 체크리스트, 원가/마진 계산 로직) |
| `[API-2025-12-04] quote-api-request.md` | ⭐ **NEW** - 견적관리 API 요청서 (데이터 모델, 엔드포인트, 수식 계산) |
| `[PLAN-2025-12-04] quote-management-implementation.md` | 📋 **NEW** - 견적관리 작업계획서 (6 Phase, 체크리스트) |
| `[NEXT-2025-12-09] client-session-context.md` | ⭐ **세션 체크포인트** - 다음 세션 이어하기용 (완료/숨긴 섹션/다음 작업) |
| `[IMPL-2025-12-04] client-management-api-integration.md` | ✅ **완료** - 거래처관리 API 연동 체크리스트 (CRUD, 그룹 훅) |
| `[API-2025-12-04] client-api-analysis.md` | ✅ **완료** - 거래처 API 분석 (2차 필드 완료, is_active Boolean) |
| `[PLAN-2025-12-02] sales-pages-migration.md` | 📋 견적관리/거래처관리 마이그레이션 계획 |

---

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

| 파일 | 설명 |
|------|------|
| `[IMPL-2026-01-07] ceo-dashboard-checklist.md` | 🔴 **NEW** - 대표님 전용 대시보드 구현 체크리스트 (11개 섹션, 달력 포함) |
| `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/ - 범용 가이드

| 파일 | 설명 |
|------|------|
| `[REF-2026-01-07] nextjs-security-update-and-migration-plan.md` | 🔴 **NEW** - Next.js 보안 업데이트 (15.5.9) 및 16 마이그레이션 계획 |
| `[DESIGN-2026-01-02] document-modal-common-component.md` | 문서 모달 공통 컴포넌트 설계 요구사항 (6개 모달 분석, 헤더/결재라인/테이블 조합형) |
| `[GUIDE] print-area-utility.md` | 인쇄 모달 printArea 유틸리티 가이드 (8개 모달 적용, print-utils.ts) |
| `[GUIDE-2025-12-29] vercel-deployment.md` | Vercel 배포 가이드 (환경변수, CORS, 테스트 체크리스트) |
| `[PLAN-2025-12-23] common-component-extraction-plan.md` | 공통 컴포넌트 추출 계획서 (Phase 1-4, 체크리스트 포함, ~1,900줄 절감) |
| `[ANALYSIS-2025-12-23] common-component-extraction-candidates.md` | 📋 공통 컴포넌트 추출 후보 분석 (다이얼로그 102개 중복, ~2,370줄 절감 예상) |
| `[PLAN-2025-12-19] project-health-improvement.md` | ✅ **Phase 1 완료** - 프로젝트 헬스 개선 계획서 (타입에러 0개, API키 보안, SSR 수정) |
| `[PLAN-2025-12-19] page-layout-standardization.md` | 🔴 **NEW** - 페이지 레이아웃 표준화 계획 |
| `[GUIDE-2025-12-16] options-vs-flattened-data.md` | options vs 평탄화 데이터 패턴 (API 응답 매핑 시 options 직접 파싱 금지) |
| `[GUIDE] large-file-handling-strategy.md` | 대용량 파일 처리 전략 (100MB+ CAD 도면, 청크 업로드, 스트리밍 다운로드) |
| `[FIX-2025-12-05] radix-ui-select-controlled-mode-bug.md` | ⭐ **핵심** - Radix UI Select 버그 해결 (Edit 모드 값 표시 안됨 → key prop 강제 리마운트) |
| `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/ - 아키텍처 & 시스템

| 파일 | 설명 |
|------|------|
| `[PLAN-2026-02-06] refactoring-roadmap.md` | 🔴 **NEW** - 리팩토링 종합 로드맵 (5 Phase, 공통훅~성능최적화, **전부 프론트 단독**) |
| `[PLAN-2026-02-06] multi-tenancy-optimization-roadmap.md` | 🔴 **NEW** - 멀티테넌시 공통화/최적화 종합 로드맵 (8 Phase, API 테넌트 주입~라우팅) |
| `[FIX-2026-01-29] masterdata-cache-tenant-isolation.md` | masterDataStore 캐시 테넌트 격리 수정 (page_config 키에 tenantId 추가, dead code 해소) |
| `[PLAN-2025-12-29] dynamic-menu-refresh.md` | 동적 메뉴 갱신 시스템 (1단계: 폴링, 2단계: SSE) |
| `multi-tenancy-implementation.md` | ✅ **Phase 1-2 완료** - 초기 멀티테넌시 구현 (AuthContext, TenantAwareCache) |
| `multi-tenancy-test-guide.md` | 멀티테넌시 캐시 격리 테스트 가이드 |
| `architecture-integration-risks.md` | 통합 리스크 |
| `browser-support-policy.md` | 브라우저 지원 정책 |
| `ssr-hydration-fix.md` | SSR 하이드레이션 수정 |

---

## 💳 accounting/ - 회계관리 (거래처/매입/매출/출금)

| 파일 | 설명 |
|------|------|
| `[IMPL-2025-12-18] vendor-management-checklist.md` | 🔴 **NEW** - 거래처관리 구현 체크리스트 (리스트 + 상세 페이지) |
| `[IMPL-2025-12-18] purchase-management.md` | 매입관리 페이지 구현 (리스트 + 상세 모달) |

---

## 📝 board/ - 게시판 관리

| 파일 | 설명 |
|------|------|
| `[PLAN-2025-12-19] board-management-implementation.md` | 🔴 **NEW** - 게시판 구현 계획서 (리스트/등록/상세/댓글, TipTap 에디터) |

---

## ⚙️ settings/ - 설정 관리

| 파일 | 설명 |
|------|------|
| `[IMPL-2025-12-19] company-info.md` | 🔴 **NEW** - 회사정보 구현 (폼 기반, 회사 추가 팝업) |
| `[IMPL-2025-12-19] popup-management.md` | 팝업관리 구현 (리스트/등록/상세/수정, RichTextEditor) |

---

## 🏗️ juil/ - 주일 공사 MES (NEW)

| 파일 | 설명 |
|------|------|
| `[IMPL-2026-01-05] item-management-checklist.md` | 🔴 **NEW** - 품목관리 구현 체크리스트 (발주관리 > 기준정보 > 품목관리) |
| `[IMPL-2026-01-05] category-management-checklist.md` | 🔴 **NEW** - 카테고리관리 구현 체크리스트 (발주관리 > 기준정보) |
| `[PLAN-2026-01-05] order-management-implementation.md` | 발주관리 페이지 구현 계획서 (달력+리스트, ScheduleCalendar 공통 컴포넌트) |
| `[NEXT-2025-12-30] partner-management-session-context.md` | ⭐ **세션 체크포인트** - 거래처 관리 리스트 완료, 등록/상세/수정 예정 |
| `[REF] juil-project-structure.md` | 주일 프로젝트 구조 가이드 (경로, 컴포넌트, 테스트 URL) |

**프로젝트 정보**:
- 업체: 주일 (공사/건설)
- 페이지 경로: `src/app/[locale]/(protected)/juil/`
- 컴포넌트: `src/components/business/juil/`
- 테스트 URL: http://localhost:3000/dev/juil-test-urls

---

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

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

---

## 문서 작성 규칙

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

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

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

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