sam-react-prod/claudedocs/_index.md

claudedocs 문서 맵

프로젝트 기술 문서 인덱스 (Last Updated: 2025-12-16)

⭐ 빠른 참조

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

---

폴더 구조

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

---

🔐 auth/ - 인증 & 토큰 관리

파일	설명
[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-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	마이그레이션 가이드

---

💰 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/ - 대시보드 & 사이드바

파일	설명
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/ - 범용 가이드

파일	설명
[GUIDE] large-file-handling-strategy.md	🔴 NEW - 대용량 파일 처리 전략 (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/ - 아키텍처 & 시스템

파일	설명
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 - 다음 작업 목록
• FIX - 버그 해결 문서

폴더 배치 기준

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

문서 업데이트

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