sam-react-prod/claudedocs/_index.md

claudedocs 문서 맵

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

빠른 참조

문서	설명
[REF] all-pages-test-urls.md	전체 페이지 테스트 URL 목록

---

프로젝트 기술 결정 사항

<img> 태그 사용 — next/image 미사용 이유 (2026-02-10)

현황: 프로젝트 전체 <img> 태그 10건, next/image 0건

결정: <img> 유지, next/image 전환 불필요

근거:

1. 폐쇄형 ERP 시스템 — SEO 불필요, LCP 점수 무의미
2. 전량 외부 동적 이미지 — 백엔드 API에서 받아오는 URL (정적 내부 이미지 0건)
3. 프린트/문서 레이아웃 — 10건 중 8건이 검사 기준서·도해 등 인쇄용. next/image의 width/height 강제 지정이 프린트 레이아웃을 깰 위험
4. blob URL 비호환 — 업로드 미리보기(blob:)는 next/image가 지원 안 함
5. 설정 부담 > 이점 — remotePatterns 설정 + 백엔드 도메인 관리 비용이 실질 이점보다 큼

모바일 헤더 backdrop-filter 깜빡임 수정 (2026-02-11)

현상: 모바일(Safari/Chrome)에서 sticky 헤더가 스크롤 시 투명↔불투명 깜빡임 발생. PC 브라우저 축소로는 재현 불가, 실제 모바일 기기에서만 발생.

원인 2가지:

1. globals.css에 * { transition: all 0.2s } — 전체 요소의 모든 CSS 속성에 전역 transition. 모바일 스크롤 리페인트 시 background/opacity가 매번 애니메이션
2. 모바일 헤더의 clean-glass 클래스: backdrop-filter: blur(8px) + background: rgba(255,255,255, 0.95) 조합이 모바일 sticky 요소에서 GPU 컴포지팅 충돌

수정:

• globals.css: * 전역 transition → button, a, input, select, textarea, [role] 인터랙티브 요소만, transition: all → color, background-color, border-color, box-shadow 속성만
• 모바일 헤더: clean-glass (반투명+blur) → bg-background border border-border (불투명 배경)

교훈:

• transition: all은 절대 *에 걸지 않기. 모바일 성능 저하 + 의도치 않은 애니메이션 발생
• backdrop-filter: blur() + sticky 조합은 모바일 브라우저 고질적 리페인트 버그. 모바일 헤더는 불투명 배경 사용
• 0.95 투명도는 육안 구분 불가 → 불투명 처리해도 시각적 차이 없음

사용처 (9개 파일):

파일	용도	이미지 소스
DocumentHeader.tsx (2건)	문서 헤더 로고	logo.imageUrl (API)
ProductInspectionInputModal.tsx	제품검사 사진 미리보기	blob URL
ProductInspectionDocument.tsx	제품검사 문서	data.productImage (API)
inspection-shared.tsx	검사 기준서 이미지	standardImage (API)
SlatInspectionContent.tsx	도해 이미지	schematicImage (API)
ScreenInspectionContent.tsx	도해 이미지	schematicImage (API)
BendingInspectionContent.tsx	도해 이미지	schematicImage (API)
SlatJointBarInspectionContent.tsx	도해 이미지	schematicImage (API)
BendingWipInspectionContent.tsx	도해 이미지	schematicImage (API)

참고: next/image가 유효한 케이스는 공개 사이트 + 정적/내부 이미지 + SEO 중요한 상황

next/dynamic 코드 스플리팅 적용 (2026-02-10)

결정: 대형 컴포넌트 + 무거운 라이브러리에 next/dynamic / 동적 import() 적용

핵심 개념 — Suspense vs dynamic():

• Suspense + 정적 import → 코드가 부모와 같은 번들 청크에 포함. 유저가 안 봐도 이미 다운로드됨. UI fallback만 제공하고 코드 분할은 안 일어남
• dynamic() → webpack이 별도 .js 청크로 분리. 컴포넌트가 실제 렌더될 때만 네트워크 요청으로 해당 청크 다운로드. 진짜 코드 분할

적용 내역:

파일	대상	절감
reports/comprehensive-analysis/page.tsx	MainDashboard (2,651줄 + recharts)	~350KB
components/business/Dashboard.tsx	CEODashboard	~200KB
construction/ConstructionDashboard.tsx	ConstructionMainDashboard	~100KB
production/dashboard/page.tsx	ProductionDashboard	~100KB
lib/utils/excel-download.ts	xlsx 라이브러리 (~400KB)	~400KB
quotes/LocationListPanel.tsx	xlsx 직접 import 제거	(위와 중복)

xlsx 동적 로드 패턴:

// Before: 모든 페이지에 xlsx ~400KB 포함
import * as XLSX from 'xlsx';

// After: 엑셀 버튼 클릭 시에만 로드
async function loadXLSX() {
  return await import('xlsx');
}
export async function downloadExcel(...) {
  const XLSX = await loadXLSX();
  // ...
}

총 절감: 초기 번들에서 ~850KB 제외 (대시보드 미방문 + 엑셀 미사용 시)

테이블 가상화 (react-window) — 보류 (2026-02-10)

결정: 현시점 도입 불필요, 성능 이슈 발생 시 검토

근거:

1. 페이지네이션 사용 중 — 리스트 페이지 대부분 서버 사이드 페이지네이션 (20~50건/페이지). 50개 <tr>은 브라우저가 문제없이 처리
2. 적용 복잡도 높음 — 테이블 헤더 고정, 체크박스 선택, rowSpan/colSpan 병합 등 기존 기능과 충돌 가능. DataTable + IntegratedListTemplateV2 + UniversalListPage 전부 수정 필요
3. YAGNI — 500건 이상 한 번에 렌더링하는 페이지가 현재 없음

도입 시점: 한 페이지에 200건+ 데이터를 페이지네이션 없이 표시해야 하는 요구가 생길 때

SWR / React Query — 보류 (2026-02-10)

결정: 현시점 도입 불필요, 성능 이슈 발생 시 검토

근거:

1. 기존 패턴 안정화 완료 — useEffect + Server Action 호출 패턴이 전 페이지에 일관 적용됨
2. 캐싱 니즈 낮음 — 폐쇄형 ERP 특성상 항상 최신 데이터 필요. stale 데이터 표시는 오히려 위험
3. 마스터데이터 캐싱 구현됨 — Zustand (stores/masterDataStore)로 변경 빈도 낮은 데이터는 이미 캐싱 중
4. 도입 비용 과다 — 수십 개 페이지 useState+useEffect 패턴 전면 리팩토링 + 팀 학습 비용

도입 시점: 동일 데이터를 여러 컴포넌트에서 동시 요구하거나, 목록 ↔ 상세 이동 시 재로딩이 체감될 때

컴포넌트 레지스트리 관계도 (2026-02-12)

구현: /dev/component-registry 페이지에 관계도(카드형 플로우) 뷰 추가

구성:

• actions.ts — extractComponentImports() + buildRelationships()로 import 관계 양방향 파싱 (imports/usedBy)
• ComponentRelationshipView.tsx — 3칼럼 카드형 플로우 (사용처 → 선택 컴포넌트 → 구성요소)
• ComponentRegistryClient.tsx — 목록/관계도 뷰 토글

활용 규칙 (CLAUDE.md에 추가됨):

• 새 컴포넌트 생성 전 → 목록에서 중복 검색 + 관계도에서 조합 패턴 확인
• 기존 컴포넌트 수정 시 → usedBy로 영향 범위 파악

Action 팩토리 패턴 — 신규 CRUD 적용 규칙 (2026-02-10)

결정: 기존 84개 actions.ts 전면 전환은 하지 않음. 신규 CRUD 도메인에만 팩토리 사용

현황:

• src/lib/api/create-crud-service.ts (177줄) — CRUD 보일러플레이트 자동 생성 팩토리
• 현재 사용 중: TitleManagement, RankManagement (2개)
• 전환 가능: 15~20개 / 전환 불가 (커스텀 로직): 50+개

규칙:

• 신규 도메인 추가 시 단순 CRUD → createCrudService 사용 필수
• 기존 actions.ts는 잘 동작하므로 무리하게 전환하지 않음
• 커스텀 비즈니스 로직이 있는 도메인(견적, 수주, 생산 등)은 팩토리 비적합

사용 예시:

import { createCrudService } from '@/lib/api/create-crud-service';

const service = createCrudService<ApiData, FrontendType>({
  basePath: '/api/v1/resources',
  transform: (api) => ({ id: api.id, name: api.name }),
  entityName: '리소스',
});

export const getList = service.getList;
export const getById = service.getById;
export const create = service.create;
export const update = service.update;
export const remove = service.remove;

미전환 사유: 84개 중 전환 가능 1520개, 작업 24시간 대비 기능 변화 없음. 시간 대비 효율 낮음

Server Action 공통 유틸리티 — 전체 마이그레이션 완료 (2026-02-12)

결정: buildApiUrl() 전체 43개 actions.ts에 적용 완료

배경:

• 89개 actions.ts 중 43개에서 동일한 URLSearchParams 조건부 .set() 패턴 반복 (326+ 건)
• 50+ 파일에서 current_page → currentPage 수동 변환 반복
• toPaginationMeta가 src/lib/api/types.ts에 존재하나 import 0건

생성된 유틸리티:

1. src/lib/api/query-params.ts — buildQueryParams(), buildApiUrl(): URLSearchParams 보일러플레이트 제거
2. src/lib/api/execute-paginated-action.ts — executePaginatedAction(): 페이지네이션 조회 패턴 통합 (내부에서 toPaginationMeta 사용)

마이그레이션 결과 (2026-02-12):

• new URLSearchParams 사용: 326건 → 0건 (actions.ts 기준)
• const API_URL = process.env.NEXT_PUBLIC_API_URL 선언: 43개 → 0개 (마이그레이션 대상 파일)
• buildApiUrl() import: 43개 actions.ts 전체 적용
• 3가지 API_URL 패턴 통합: 표준(process.env), /api 접미사(HR), API_BASE 전체경로(품질) → 모두 buildApiUrl('/api/v1/...') 통일

executePaginatedAction 마이그레이션 (2026-02-12):

• 14개 actions.ts에서 페이지네이션 목록 조회 함수를 executePaginatedAction으로 전환
• Wave A (accounting 9개): BillManagement, DepositManagement, SalesManagement, PurchaseManagement, WithdrawalManagement, VendorLedger, CardTransactionInquiry, BankTransactionInquiry, ExpectedExpenseManagement
• Wave B (5개): PaymentHistoryManagement, StockStatus, ReceivingManagement, ShipmentManagement, quotes
• 제외 5개: AccountManagement(meta 필드명), orders(data.items 중첩), VacationManagement, EmployeeManagement, construction/order-management (별도 구조)
• 순 감소: ~220줄 (14파일 × ~20줄 제거, ~28줄 추가)
• 제거된 보일러플레이트: DEFAULT_PAGINATION, FrontendPagination/PaginationMeta 로컬 인터페이스, PaginatedApiResponse import, 수동 transform+pagination 조립
• 화면 검수 완료 (4개 페이지): Bills, StockStatus, Quotes, Shipments — 전체 PASS
• 버그 발견/수정: quotes/actions.ts에서 export type { PaginationMeta } re-export가 Turbopack 런타임 에러 유발 (tsc로 미감지) → re-export 제거, 컴포넌트에서 @/lib/api/types 직접 import로 변경

'use server' 파일 타입 export 제한 (2026-02-12)

발견 배경: executePaginatedAction 마이그레이션 화면 검수 중 견적관리 페이지 빌드 에러

제한 사항:

• 'use server' 파일에서는 async 함수만 export 가능 (Next.js Turbopack 제한)
• export type { X } from '...' (re-export) → 런타임 에러 발생
• export interface X { ... } / export type X = ... (인라인 정의) → 문제 없음 (컴파일 시 제거)
• tsc --noEmit으로는 감지 불가 — Next.js 전용 규칙이므로 실제 페이지 접속(Turbopack)에서만 발생

현재 상태: 전체 81개 'use server' 파일 점검 완료, re-export 패턴 0건 (수정된 1건 포함)

buildApiUrl 마이그레이션 전략:

• Wave A: 1건짜리 단순 파일 20개
• Wave B: 2건짜리 파일 12개 (quotes, WorkOrders, orders 등 대형 파일 포함)
• Wave C: 3건 이상 파일 12개 (VendorLedger 5건, ReceivingManagement 5건, ProcessManagement 19건 URL 등)

효과:

• 페이지네이션 조회 코드: ~20줄 → ~5줄
• DEFAULT_PAGINATION 중앙화 (execute-paginated-action.ts 내부)
• toPaginationMeta 자동 활용 (직접 import 불필요)
• URL 빌딩 패턴 완전 일관화 (undefined/null/'' 자동 필터링, boolean/number 자동 변환)

Zod 스키마 검증 — 신규 폼 적용 규칙 (2026-02-11)

결정: 기존 폼은 건드리지 않음. 신규 폼에만 Zod + zodResolver 적용

설치 상태: zod@^4.1.12, @hookform/resolvers@^5.2.2 — 이미 설치됨

효과:

1. 스키마 하나로 타입 추론 + 런타임 검증 동시 해결 (z.infer<typeof schema>)
2. 별도 interface 중복 정의 불필요
3. 신규 코드에서 as 캐스트 자연 감소 (D-2 개선 효과)

규칙:

• 신규 폼 → zodResolver(schema) 사용 필수 (CLAUDE.md에 패턴 명시)
• 기존 rules={{ required: true }} 패턴 폼 → 마이그레이션 불필요
• 단순 1~2 필드 인라인 폼 → Zod 불필요 (오버엔지니어링)

미적용 사유: 기존 폼 수십 개를 전면 전환하는 비용 >> 이득. 신규 코드에서 점진적 확산

---

폴더 구조

claudedocs/
├── _index.md            # 이 파일 - 문서 맵
├── auth/                # 인증 & 토큰 관리
├── hr/                  # 인사관리 (부서/사원)
├── item-master/         # 품목기준관리
├── production/          # 생산관리 (생산현황판/작업자화면)
├── quality/             # 품질관리 (검사관리)
├── sales/               # 판매관리 (견적/거래처/단가)
├── accounting/          # 회계관리 (매입/매출/출금)
├── construction/        # 주일 공사 MES
├── board/               # 게시판 관리
├── settings/            # 설정 관리
├── dashboard/           # 대시보드 & 사이드바
├── security/            # 보안 & 권한
├── api/                 # API 통합
├── dev/                 # 개발도구 & 테스트
├── guides/              # 범용 가이드
├── architecture/        # 아키텍처 & 시스템
├── changes/             # 변경이력
├── vehicle/             # 차량관리
├── material/            # 자재관리
├── approval/            # 결재관리
├── customer-center/     # 고객센터
├── refactoring/         # 리팩토링 체크리스트
└── archive/             # 레거시/완료된 문서

---

인증 & 토큰 관리 — auth/

파일	설명
[IMPL-2025-12-30] token-refresh-caching.md	토큰 갱신 캐싱 구현 (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	모바일 출퇴근 시스템 (카카오맵 GPS)
[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	DynamicItemForm 훅 분리 계획서
[FIX-2025-12-16] options-details-duplicate-bug.md	options vs item_details 중복 저장 버그
[IMPL-2025-12-15] backend-item-api-migration.md	백엔드 품목 API 통합
[DESIGN-2025-12-12] item-master-form-builder-roadmap.md	Low-Code Form Builder 로드맵
[PLAN-2025-12-08] dynamic-form-separation-plan.md	DynamicItemForm 품목별 분리 계획
[REF] item-code-hardcoding.md	품목관리 하드코딩 내역 종합
[REF] items-route-consolidation.md	품목 라우트 통합
[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	상태 동기화 문제 및 해결 방안
[IMPL-2025-12-02] dynamic-item-form-rebuild.md	동적 페이지 재구현
[API-REQUEST-2025-11-28] dynamic-page-rendering-api.md	동적 페이지 렌더링 API 요청서
[PLAN-2025-11-27] item-form-component-separation.md	ItemForm 컴포넌트 분리
[IMPL-2025-11-27] realtime-sync-fixes.md	실시간 동기화 수정
[IMPL-2026-01-09] item-management-api-integration.md	품목관리 API 연동
[API-REQUEST-2026-02-12] dynamic-field-type-backend-spec.md	동적 필드 타입 확장 백엔드 API 스펙
NEXT-*.md	세션 체크포인트 (다수)
API-*.md	API 명세/요청 (다수)
ANALYSIS-*.md	분석 노트 (다수)

---

생산관리 — production/

파일	설명
[IMPL-2025-12-22] production-dashboard-checklist.md	생산 현황판 구현 체크리스트 (8 Phase)
[DESIGN-2026-01-29] worker-screen-spec.md	작업자 화면 설계 스펙
[NEXT-2025-12-22] production-session-context.md	세션 체크포인트

---

품질관리 — quality/

파일	설명
[IMPL-2025-12-23] inspection-management-checklist.md	검사관리 구현 체크리스트 (7 Phase)
[PLAN-2026-02-02] document-viewer-architecture.md	문서 뷰어 아키텍처
[PLAN-2026-02-04] quality-audit-document-management.md	품질심사 문서관리

---

판매관리 — sales/

파일	설명
[API-2025-12-08] pricing-api-enhancement-request.md	단가관리 API 개선 요청서
[IMPL-2025-12-05] pricing-management-migration.md	단가관리 마이그레이션
[API-2025-12-04] quote-api-request.md	견적관리 API 요청서
[PLAN-2025-12-04] quote-management-implementation.md	견적관리 작업계획서
[IMPL-2025-12-04] client-management-api-integration.md	거래처관리 API 연동
[API-2025-12-04] client-api-analysis.md	거래처 API 분석
[PLAN-2025-12-02] sales-pages-migration.md	판매 페이지 마이그레이션
[IMPL-2025-12-22] order-management-sales.md	수주관리
[IMPL-2026-01-12] quote-v2-test-pages-checklist.md	견적 v2 테스트 페이지
[IMPL-2025-12-09] pricing-api-integration-checklist.md	단가 API 연동 체크리스트
[NEXT-2026-02-04] price-distribution-session-context.md	단가배포 세션 체크포인트
[NEXT-2025-12-09] client-session-context.md	거래처 세션 체크포인트

---

회계관리 — accounting/

파일	설명
[IMPL-2025-12-18] vendor-management-checklist.md	거래처관리 구현 체크리스트
[IMPL-2025-12-18] purchase-management.md	매입관리 페이지 구현
[IMPL-2025-12-18] bill-management.md	어음관리
[IMPL-2025-12-18] expected-expense-checklist.md	지출예정 체크리스트
[IMPL-2025-12-18] receivables-status.md	미수금 현황
[IMPL-2025-12-18] vendor-ledger.md	거래처원장
[IMPL-2025-12-18] withdrawal-management-checklist.md	출금관리 체크리스트
[IMPL-2025-12-19] bad-debt-collection-management.md	부실채권 관리
[IMPL-2025-12-19] card-transaction-inquiry.md	카드거래 조회
[PLAN-2025-12-18] sales-management.md	매출관리 계획
[PLAN-2025-12-19] bank-account-transaction-inquiry.md	은행거래 조회 계획
[PLAN-2026-01-23] vendor-credit-analysis-modal.md	거래처 여신분석 모달

---

주일 공사 MES — construction/

파일	설명
[IMPL-2026-01-05] item-management-checklist.md	품목관리 구현 체크리스트
[IMPL-2026-01-05] category-management-checklist.md	카테고리관리 구현 체크리스트
[IMPL-2026-01-05] pricing-management-checklist.md	단가관리 구현 체크리스트
[IMPL-2026-01-09] partner-management-api-integration.md	거래처관리 API 연동
[IMPL-2026-01-09] site-management-api-integration.md	현장관리 API 연동
[IMPL-2026-01-12] project-detail-checklist.md	프로젝트 상세 체크리스트
[PLAN-2026-01-05] order-management-implementation.md	발주관리 구현 계획
[PLAN-2026-01-02] estimate-detail-form-refactoring.md	견적상세 폼 리팩토링
[PLAN-2026-01-05] order-detail-form-separation.md	발주상세 폼 분리
[REF] construction-project-flow.md	프로젝트 플로우
[REF] juil-project-structure.md	프로젝트 구조 가이드
[NEXT-2025-12-30] partner-management-session-context.md	세션 체크포인트

---

대시보드 & 사이드바 — dashboard/

파일	설명
[IMPL-2026-02-11] favorites-feature.md	즐겨찾기 기능 (localStorage → 추후 API 전환)
[IMPL-2026-01-07] ceo-dashboard-checklist.md	대표님 전용 대시보드 (11개 섹션)
dashboard-integration-complete.md	대시보드 통합 완료
dashboard-cleanup-summary.md	정리 요약
dashboard-migration-summary.md	마이그레이션 요약
sidebar-active-menu-sync.md	사이드바 메뉴 동기화
sidebar-scroll-improvements.md	스크롤 개선

---

보안 & 권한 — security/

파일	설명
[PLAN-2025-01-20] permission-system-implementation.md	권한 시스템 구현 계획
[QA-2026-02-03] permission-verification-checklist.md	권한 검증 체크리스트
[PLAN-2025-12-12] tenant-data-isolation-implementation.md	테넌트 데이터 격리 구현
[SECURITY-2025-12-12] tenant-data-isolation-audit.md	테넌트 데이터 격리 감사

---

API 통합 — api/

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

---

개발도구 & 테스트 — dev/

파일	설명
[REF] all-pages-test-urls.md	전체 페이지 테스트 URL 목록
[REF] construction-pages-test-urls.md	주일 페이지 테스트 URL
[REF] page-builder-implementation.md	페이지 빌더 구현 참조
[REF] chrome-devtools-mcp-emoji-issue.md	Chrome DevTools MCP 이모지 이슈
[PLAN] detail-page-pattern-classification.md	상세페이지 패턴 분류
[PLAN-2026-02-03] claude-config-optimization.md	Claude 설정 최적화
[IMPL-2025-12-29] quality-inspection-checklist.md	품질검사 체크리스트
[IMPL-2026-01-23] full-page-inspection.md	전체 페이지 검사
[FIX-2026-01-29] typecheck-errors-checklist.md	타입체크 에러 체크리스트
[HOTFIX-2026-01-27] E2E-테스트-수정계획서.md	E2E 테스트 수정 계획서
Component Registry	/dev/component-registry — 실시간 컴포넌트 스캔 + 관계도 (목록/카드형 플로우 뷰)

---

범용 가이드 — guides/

파일	설명
UI 컴포넌트
[DESIGN-2026-01-14] universal-list-component.md	UniversalListPage 설계
[IMPL-2026-01-14] universal-list-component-checklist.md	UniversalListPage 구현 체크리스트
[PLAN] universal-detail-component.md	UniversalDetail 컴포넌트 계획
[REF] UniversalListPage-QA-patterns.md	UniversalListPage QA 패턴
UniversalListPage-검색기능-수정내역.md	검색 기능 수정 내역
UniversalListPage-검색리렌더링-해결가이드.md	검색 리렌더링 해결
[DESIGN-2026-01-02] document-modal-common-component.md	문서 모달 공통 컴포넌트
badge-commonization-guide.md	배지 공통화 가이드
공통화 & 마이그레이션
[ANALYSIS-2025-12-23] common-component-extraction-candidates.md	공통 컴포넌트 추출 후보 분석
[ANALYSIS] common-component-patterns.md	공통 컴포넌트 패턴
[PLAN-2025-12-23] common-component-extraction-plan.md	공통 컴포넌트 추출 계획
[IMPL-2025-01-26] list-page-ui-standardization-checklist.md	리스트 페이지 UI 표준화
[IMPL-2026-01-23] button-navigation-checklist.md	버튼 네비게이션 체크리스트
[IMPL-2026-01-23] mode-migration-checklist.md	모드 마이그레이션 체크리스트
[IMPL-2026-01-23] mode-navigation-full-checklist.md	모드 네비게이션 전체 체크리스트
[IMPL-2026-01-21] utility-input-migration-checklist.md	유틸리티 입력 마이그레이션
[IMPL-2026-02-06] datepicker-migration-checklist.md	DatePicker 마이그레이션
[REF-2026-01-09] server-to-client-component-migration-checklist.md	Server→Client 마이그레이션
모바일
[GUIDE] mobile-responsive-patterns.md	모바일 반응형 패턴
[IMPL-2026-01-13] mobile-filter-migration-checklist.md	모바일 필터 마이그레이션
[PLAN-2026-01-20] mobile-card-infinity-scroll.md	모바일 카드 무한스크롤
[PLAN] mobile-overflow-testing.md	모바일 오버플로우 테스트
[QA-2026-01-21] mobile-infinity-scroll-inspection.md	모바일 무한스크롤 검사
[REF] mobile-zoom-fix-guide.md	모바일 줌 수정 가이드
[REF] mobile-zoom-prevention-guide.md	모바일 줌 방지 가이드
[FIX-2026-02-04] mobile-zoom-panning.md	모바일 줌 패닝 수정
[GUIDE] foldable-device-layout-fix.md	폴더블 기기 레이아웃
프로젝트 헬스 & 문서 시스템
[PLAN-2025-12-19] project-health-improvement.md	프로젝트 헬스 개선 계획
[PLAN-2025-12-19] page-layout-standardization.md	페이지 레이아웃 표준화
[PLAN-2025-01-21] document-system-integration.md	문서 시스템 통합
[QA-2025-01-21] document-system-inspection.md	문서 시스템 검사
[QA-2026-01-15] universal-list-page-inspection.md	UniversalListPage 검사
기술 가이드
[GUIDE] print-area-utility.md	인쇄 printArea 유틸리티
[GUIDE-2025-12-29] vercel-deployment.md	Vercel 배포 가이드
[GUIDE-2025-12-16] options-vs-flattened-data.md	options vs 평탄화 데이터 패턴
[GUIDE] large-file-handling-strategy.md	대용량 파일 처리 전략
[FIX-2025-12-05] radix-ui-select-controlled-mode-bug.md	Radix UI Select 버그 해결
[GUIDE] CSS-MIGRATION-WORKFLOW.md	CSS 마이그레이션 워크플로우
[GUIDE] LARGE-FILE-WORKFLOW.md	대용량 파일 작업 워크플로우
[GUIDE] ZOD-VALIDATION-TROUBLESHOOTING.md	Zod 유효성 검사 트러블슈팅
[REF] nextjs-error-handling-guide.md	Next.js 에러 처리
[REF-2026-01-07] nextjs-security-update-and-migration-plan.md	Next.js 보안 업데이트 계획
[GUIDE] collaboration-with-claude.md	Claude 협업 가이드
[IMPL-2025-11-06] i18n-usage-guide.md	다국어 사용 가이드
[IMPL-2025-11-07] form-validation-guide.md	폼 유효성 검사
[IMPL-2026-01-05] stat-cards-grid-layout.md	스탯 카드 그리드 레이아웃
[NEXT-2026-01-14] UniversalListPage-pilot-session-context.md	세션 체크포인트

---

아키텍처 & 시스템 — architecture/

파일	설명
리팩토링 로드맵
[PLAN-2026-02-06] refactoring-roadmap.md	리팩토링 종합 로드맵 (5 Phase)
[PLAN-2026-02-06] multi-tenancy-optimization-roadmap.md	멀티테넌시 최적화 로드맵 (8 Phase)
공통화 & 마이그레이션 분석
[ANALYSIS-2026-01-20] 공통화-현황-분석.md	공통화 현황 분석
[ANALYSIS-2026-02-05] SAM-ERP-MES-정체성-분석.md	SAM ERP/MES 정체성 분석
[ANALYSIS-2026-02-05] list-page-commonization-status.md	리스트 페이지 공통화 현황
컴포넌트 아키텍처
[PLAN-2026-01-22] ui-component-abstraction.md	UI 컴포넌트 추상화
[IMPL-2026-01-21] input-form-componentization.md	입력폼 컴포넌트화
[IMPL-2026-01-21] phase4-input-migration-rollout.md	Phase 4 입력 마이그레이션
[IMPL-2026-02-05] detail-hooks-migration-plan.md	상세 훅 마이그레이션
[IMPL-2026-02-05] formatter-commonization-plan.md	formatter 공통화 계획
[IMPL] IntegratedDetailTemplate-checklist.md	통합 상세 템플릿 체크리스트
[REF] template-migration-status.md	템플릿 마이그레이션 현황
동적 필드 타입 확장
[DESIGN-2026-02-11] dynamic-field-type-extension.md	동적 필드 타입 확장 설계서 (4-Level 구조)
[IMPL-2026-02-11] dynamic-field-components.md	동적 필드 컴포넌트 구현 기획서 (Phase 1~3 완료)
시스템 설계
[PLAN-2026-01-16] layout-restructure.md	레이아웃 구조 변경
[PLAN-2025-12-29] dynamic-menu-refresh.md	동적 메뉴 갱신 시스템
[FIX-2026-01-29] masterdata-cache-tenant-isolation.md	masterData 캐시 테넌트 격리
[DESIGN-2025-12-20] item-master-zustand-refactoring.md	Zustand 리팩토링 설계
[REF-2025-11-19] multi-tenancy-implementation.md	멀티테넌시 구현
[TEST-2025-11-19] multi-tenancy-test-guide.md	멀티테넌시 테스트 가이드
[IMPL-2025-11-13] browser-support-policy.md	브라우저 지원 정책
[IMPL-2025-11-18] ssr-hydration-fix.md	SSR 하이드레이션 수정
[REF] architecture-integration-risks.md	통합 리스크
[NEXT-2025-12-20] zustand-refactoring-session-context.md	세션 체크포인트

---

게시판 관리 — board/

파일	설명
[PLAN-2025-12-19] board-management-implementation.md	게시판 구현 계획서

---

설정 관리 — settings/

파일	설명
[IMPL-2025-12-19] company-info.md	회사정보 구현
[IMPL-2025-12-19] popup-management.md	팝업관리 구현

---

리팩토링 — refactoring/

파일	설명
[IMPL-2026-02-09] phase1-common-hooks-checklist.md	Phase 1 공통 훅 추출 체크리스트 (완료) + Phase 3 프로토타입 기록

---

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

완료되거나 더 이상 활성화되지 않은 문서들. 참조용으로 보관. 테스트 스크린샷(qa-*.png)도 여기에 보관.

---

문서 작성 규칙

파일명 컨벤션

[TYPE-YYYY-MM-DD] description.md

TYPE 종류:

• IMPL - 구현 문서
• API - API 명세/요청
• GUIDE - 사용 가이드
• REF - 참조 문서
• ANALYSIS - 분석 노트
• PLAN - 계획 문서
• DESIGN - 설계 문서
• TEST - 테스트 가이드
• NEXT - 다음 작업 목록
• FIX - 버그 해결 문서
• QA - 품질 검사 문서
• HOTFIX - 긴급 수정 문서

폴더 배치 기준

1. 기능/도메인 우선: 문서 주제에 맞는 폴더에 배치
2. 범용 가이드: 여러 기능에 적용되면 guides/에 배치
3. 시스템 전체: 아키텍처/리팩토링은 architecture/에 배치
4. 개발도구: 테스트 URL, 빌드, 설정은 dev/에 배치
5. 완료된 작업: 더 이상 활성화되지 않으면 archive/로 이동