merge: main의 검사문서/생산/결재 커밋을 develop으로 이동

- 결재함에서 work_order 연결 문서 클릭 시 InspectionReportModal(readOnly)로 표시
  - 기존 LinkedDocumentContent(key-value)가 아닌 템플릿 기반 검사성적서 형태로 표시
  - getDocumentApprovalById에서 document.linkable_type/linkable_id로 workOrderId 추출
  - field_value 컬럼명 매칭 수정 (d.value → d.field_value ?? d.value)
- InspectionReportModal에 결재 상신 버튼 추가 (DRAFT 상태에서만 표시)
- submitDocumentForApproval 서버 액션 추가
- LinkedDocumentContent 컴포넌트 신규 (일반 문서용 폴백)
- DocumentType에 'document' 타입 추가, LinkedDocumentData 인터페이스 신규

.claude/hooks/block-build.sh

@@ -0,0 +1,16 @@
+#!/bin/bash
+# PreToolUse Hook: 빌드 명령 차단
+# CLAUDE.md 규칙: "Claude가 직접 npm run build 실행 금지"
+
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
+
+# 빌드 명령 패턴 체크
+if echo "$COMMAND" | grep -qE '(npm run build|next build|yarn build|pnpm build)(\s|$|;|&&|\|)'; then
+  echo "🚫 빌드 명령이 차단되었습니다." >&2
+  echo "  CLAUDE.md 규칙: Claude가 직접 빌드 실행 금지" >&2
+  echo "  빌드가 필요하면 사용자에게 요청하세요." >&2
+  exit 2
+fi
+
+exit 0

.claude/hooks/check-file-size.sh

@@ -0,0 +1,31 @@
+#!/bin/bash
+# PreToolUse Hook: Write 전 파일 크기 급감 경고
+# 기존 파일 대비 50% 이상 줄어들면 경고 (최소 50줄 이상 파일만)
+
+INPUT=$(cat)
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+NEW_CONTENT=$(echo "$INPUT" | jq -r '.tool_input.content // empty')
+
+# 파일이 없으면 (신규 생성) 통과
+if [ ! -f "$FILE_PATH" ]; then
+  exit 0
+fi
+
+EXISTING_LINES=$(wc -l < "$FILE_PATH" 2>/dev/null | tr -d ' ')
+NEW_LINES=$(echo "$NEW_CONTENT" | wc -l | tr -d ' ')
+
+# 기존 파일이 50줄 미만이면 체크 스킵
+if [ "$EXISTING_LINES" -lt 50 ] 2>/dev/null; then
+  exit 0
+fi
+
+# 새 내용이 기존의 50% 미만이면 경고
+THRESHOLD=$((EXISTING_LINES / 2))
+if [ "$NEW_LINES" -lt "$THRESHOLD" ] 2>/dev/null; then
+  echo "⚠️ File size drop: $FILE_PATH" >&2
+  echo "  기존: ${EXISTING_LINES}줄 → 새 내용: ${NEW_LINES}줄 (${THRESHOLD}줄 미만)" >&2
+  echo "  파일 내용이 절반 이상 줄었습니다. 의도한 변경인지 확인하세요." >&2
+  exit 2
+fi
+
+exit 0

.claude/hooks/check-unused-imports.sh

@@ -0,0 +1,29 @@
+#!/bin/bash
+# PostToolUse Hook: Edit/Write 후 미사용 import 체크
+# 단일 파일 eslint로 빠르게 체크 (전체 tsc보다 빠름)
+
+INPUT=$(cat)
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+
+# TypeScript 파일만 체크
+if [[ "$FILE_PATH" != *.ts && "$FILE_PATH" != *.tsx ]]; then
+  exit 0
+fi
+
+# 파일 존재 확인
+if [ ! -f "$FILE_PATH" ]; then
+  exit 0
+fi
+
+cd "$CLAUDE_PROJECT_DIR" 2>/dev/null || exit 0
+
+# eslint로 미사용 변수/import 체크 (단일 파일 → 빠름)
+RESULT=$(npx eslint --no-eslintrc --rule '{"@typescript-eslint/no-unused-vars": "error"}' --parser @typescript-eslint/parser --plugin @typescript-eslint "$FILE_PATH" 2>&1 | grep "no-unused-vars" | head -10)
+
+if [ -n "$RESULT" ]; then
+  echo "Unused imports/variables in $FILE_PATH:" >&2
+  echo "$RESULT" >&2
+  exit 2
+fi
+
+exit 0

.claude/hooks/typecheck-after-edit.sh

@@ -0,0 +1,25 @@
+#!/bin/bash
+# PostToolUse Hook: Write/Edit 후 TypeScript 타입체크
+# exit 0 = 성공, exit 2 = 에러 (Claude에 피드백)
+
+INPUT=$(cat)
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+
+# TypeScript 파일만 체크
+if [[ "$FILE_PATH" != *.ts && "$FILE_PATH" != *.tsx ]]; then
+  exit 0
+fi
+
+# 프로젝트 디렉토리로 이동
+cd "$CLAUDE_PROJECT_DIR" 2>/dev/null || exit 0
+
+# tsc 실행 (에러만 출력, 최대 20줄)
+RESULT=$(npx tsc --noEmit 2>&1 | head -20)
+
+if [ -n "$RESULT" ] && echo "$RESULT" | grep -q "error TS"; then
+  echo "TypeScript errors after editing $FILE_PATH:" >&2
+  echo "$RESULT" >&2
+  exit 2
+fi
+
+exit 0

.env.example

@@ -1,48 +0,0 @@
-# ==============================================
-# API Configuration
-# ==============================================
-API_URL=https://api.5130.co.kr
-
-# Frontend URL (for CORS)
-NEXT_PUBLIC_FRONTEND_URL=http://localhost:3000
-
-# ==============================================
-# Authentication Mode
-# ==============================================
-# 인증 모드 선택: sanctum | bearer
-# - sanctum: 웹 브라우저 사용자 (HTTP-only 쿠키)
-# - bearer: 모바일/SPA (토큰 기반)
-NEXT_PUBLIC_AUTH_MODE=sanctum
-
-# ==============================================
-# API Key (⚠️ 서버 사이드 전용 - 절대 공개 금지!)
-# ==============================================
-# 개발팀 공유: 팀 내부 문서에서 키 값 확인
-# 주기적 갱신: PHP 백엔드 팀에서 새 키 발급 시 업데이트 필요
-#
-# ⚠️ 주의사항:
-# 1. 절대 NEXT_PUBLIC_ 접두사 붙이지 말 것!
-# 2. Git에 커밋하지 말 것! (.gitignore에 포함됨)
-# 3. 브라우저에서 접근 불가 (서버 사이드 전용)
-#
-# 사용처:
-# - 서버 간 통신 (Next.js API Routes)
-# - 백그라운드 작업 (Cron, Scripts)
-# - 외부 시스템 연동
-API_KEY=your-secret-api-key-here
-
-# ==============================================
-# Development Tools
-# ==============================================
-# DevToolbar: 개발/테스트용 폼 자동 채우기 도구
-# - true: 활성화 (화면 하단에 플로팅 툴바 표시)
-# - false 또는 미설정: 비활성화
-# 주의: 운영 환경에서는 반드시 false로 설정!
-NEXT_PUBLIC_DEV_TOOLBAR_ENABLED=false
-
-# ==============================================
-# Development Notes
-# ==============================================
-# 1. .env.example을 복사하여 .env.local 생성
-# 2. .env.local에 실제 키 값 입력
-# 3. .env.local은 Git에 커밋되지 않음

.env.production

@@ -1,33 +0,0 @@
-# ==============================================
-# API Configuration
-# ==============================================
-NEXT_PUBLIC_API_URL=https://api.codebridge-x.com
-
-# Frontend URL (for CORS)
-NEXT_PUBLIC_FRONTEND_URL=https://dev.codebridge-x.com
-
-# ==============================================
-# Authentication Mode
-# ==============================================
-# 인증 모드: sanctum (웹 브라우저 쿠키 기반)
-NEXT_PUBLIC_AUTH_MODE=sanctum
-
-# ==============================================
-# API Key (⚠️ 절대 Git에 커밋하지 말 것!)
-# ==============================================
-# 개발용 고정 키 (주기적 갱신 예정)
-# 발급일: 2025-11-07
-# 갱신 필요 시: PHP 백엔드 팀에 새 키 요청
-# ✅ 서버 전용 (클라이언트에 노출되지 않음)
-API_KEY=42Jfwc6EaRQ04GNRmLR5kzJp5UudSOzGGqjmdk1a
-
-# ==============================================
-# Google Maps API Key
-# ==============================================
-NEXT_PUBLIC_GOOGLE_MAPS_API_KEY=AIzaSyAS3bAzmXlhhZHgO3buFiTGzavXZ6ubYq8
-
-# ==============================================
-# Development Tools
-# ==============================================
-# DevToolbar: 개발/테스트용 폼 자동 채우기 도구
-NEXT_PUBLIC_DEV_TOOLBAR_ENABLED=true

.gitignore

@@ -95,9 +95,10 @@ build/
 .idea/
 *.iml
 
-# ---> Claude
-.env.local
-.env*.local
+# ---> Environment
+.env
+.env.*
+.env*
 
 # ---> Unused components and contexts (archived)
 src/components/_unused/
@@ -119,3 +120,9 @@ src/app/**/dev/page-builder/
 
 # ---> Dev Dashboard Prototypes (디자인 프로토타입 - 로컬 전용)
 src/app/**/dev/dashboard/
+
+# ---> Serena MCP memories
+.serena/
+
+# ---> Deploy script (로컬 전용)
+deploy.sh

.serena/project.yml

@@ -103,3 +103,14 @@ default_modes:
 # fixed set of tools to use as the base tool set (if non-empty), replacing Serena's default set of tools.
 # This cannot be combined with non-empty excluded_tools or included_optional_tools.
 fixed_tools: []
+
+# override of the corresponding setting in serena_config.yml, see the documentation there.
+# If null or missing, the value from the global config is used.
+symbol_info_budget:
+
+# The language backend to use for this project.
+# If not set, the global setting from serena_config.yml is used.
+# Valid values: LSP, JetBrains
+# Note: the backend is fixed at startup. If a project with a different backend
+# is activated post-init, an error will be returned.
+language_backend:

CLAUDE.md

@@ -0,0 +1,512 @@
+# SAM ERP 프로젝트 규칙
+
+SAM 프로젝트(Next.js 프론트엔드) 전용 규칙. 범용 규칙은 `~/.claude/RULES.md` 참조.
+
+---
+
+## 프로젝트 개요
+
+```yaml
+sam_project:
+  frontend: sam_project/sam-next/sma-next-project/sam-react-prod  # Next.js (현재)
+  backend_api: sam_project/sam-api/sam-api                         # PHP Laravel
+  design: sam_project/sam-design/sam-design                        # React 디자인 시스템
+  hotfix: sam_project/sam-hotfix/sam-hotfix                        # E2E 테스트 결과/핫픽스 관리
+  특성: 인증 필수 폐쇄형 ERP 시스템 (SEO 불필요)
+```
+
+---
+
+## Git Workflow
+**Priority**: 🔴
+
+### 브랜치 구조
+| 브랜치 | 역할 | 커밋 상태 |
+|--------|------|-----------|
+| `develop` | 평소 작업 브랜치 (자유롭게) | 지저분해도 OK |
+| `stage` | QA/테스트 환경 | 기능별 squash 정리 |
+| `main` | 배포용 (기본 브랜치) | 검증된 것만 |
+| `feature/*` | 큰 기능/실험적 작업 시 | 선택적 사용 |
+
+### "git 올려줘" 단축 명령어
+`git 올려줘` 입력 시 **develop에 push**:
+1. `git status` → 2. `git diff --stat` → 3. `git add -A` → 4. `git commit` (자동 메시지) → 5. `git push origin develop`
+
+- `snapshot.txt`, `.DS_Store` 파일은 항상 제외
+- develop에서 자유롭게 커밋 (커밋 메시지 정리 불필요)
+
+### main에 올리기 (기능별 squash merge) — 필수 규칙
+사용자가 "main에 올려줘" 또는 특정 기능을 main에 올리라고 지시할 때만 실행.
+**절대 자동으로 main에 push하지 않음.**
+
+**🔴 반드시 기능별로 나눠서 올릴 것. 통째로 squash 금지.**
+
+```bash
+# 실행 순서
+git checkout main
+git pull origin main
+
+# 1. develop 커밋 이력 분석 → 기능별 그룹 분류
+git log --oneline main..develop
+
+# 2. 기능별로 cherry-pick + squash commit (기능 수만큼 반복)
+git cherry-pick --no-commit <기능A커밋1> <기능A커밋2> ...
+git commit -m "feat: [기능A 설명]"
+
+git cherry-pick --no-commit <기능B커밋1> <기능B커밋2> ...
+git commit -m "feat: [기능B 설명]"
+
+# 3. push 후 develop으로 복귀
+git push origin main
+git checkout develop
+```
+
+**기능 분류 기준**:
+- 같은 도메인/모듈 수정은 하나로 묶기 (예: CEO 대시보드 관련 커밋들)
+- CI/CD, 문서 등 인프라 변경은 별도 커밋 (예: chore: Jenkinsfile 정비)
+- 커밋 메시지 타입: feat(기능), fix(버그), refactor(리팩토링), chore(설정/문서)
+
+**핵심: main에는 기능 단위 커밋만 → 문제 시 `git revert`로 해당 기능만 롤백 가능**
+
+### feature 브랜치 사용 기준
+| 상황 | 방법 |
+|------|------|
+| 일반 작업 | develop에서 바로 |
+| 1주일+ 걸리는 큰 기능 | feature/* 따서 작업 |
+| 실험적 시도 | feature/* 따서 작업 |
+| 백엔드와 동시 수정 건 | 각자 feature/* 권장 |
+
+### 금지 사항
+- ❌ main에 직접 커밋/push
+- ❌ `git push --force` (main/develop)
+- ❌ 사용자 지시 없이 main에 merge
+
+---
+
+## Client Component 사용 원칙
+**Priority**: 🔴
+
+### 배경
+- 폐쇄형 사이트 → SEO 불필요, 오히려 노출되면 안 됨
+- Server Component에서는 쿠키 수정(토큰 갱신) 불가
+
+### 규칙
+- **Server Component 사용 금지**: `export default async function Page()` 패턴 금지
+- **Client Component 사용**: 모든 페이지는 `'use client'` 선언 필수
+- **데이터 로딩**: useEffect에서 Server Action 호출
+
+```typescript
+// ✅ 올바른 패턴
+'use client';
+import { useEffect, useState } from 'react';
+import { getData } from '@/components/.../actions';
+
+export default function Page() {
+  const [data, setData] = useState(null);
+  const [isLoading, setIsLoading] = useState(true);
+
+  useEffect(() => {
+    getData()
+      .then(result => setData(result.data))
+      .finally(() => setIsLoading(false));
+  }, []);
+
+  if (isLoading) return <div>로딩 중...</div>;
+  return <Component initialData={data} />;
+}
+```
+
+```typescript
+// ❌ 잘못된 패턴
+export default async function Page() {
+  const result = await getData();
+  return <Component initialData={result.data} />;
+}
+```
+
+---
+
+## HttpOnly Cookie API Communication
+**Priority**: 🔴
+
+- HttpOnly 쿠키는 JavaScript로 읽을 수 없음
+- **모든 인증 API 호출은 Next.js API route 프록시 필수**
+
+```typescript
+// ✅ Next.js API Proxy
+// /src/app/api/proxy/[...path]/route.ts
+export async function GET(request: NextRequest, { params }: { params: { path: string[] } }) {
+  const token = request.cookies.get('access_token')?.value;
+  const response = await fetch(`${BACKEND_URL}/${params.path.join('/')}`, {
+    headers: { 'Authorization': `Bearer ${token}` },
+  });
+  return response;
+}
+
+// 프론트엔드에서는 프록시 호출
+const response = await fetch('/api/proxy/item-master/init');
+```
+
+---
+
+## 기획서/스크린샷 기반 UI 구현 프로세스
+**Priority**: 🔴
+
+### 기획서 Description 영역 처리
+기획서 스크린샷의 Description 영역(보통 오른쪽 검은 배경)은 **설명용**이며 UI에 구현하지 않음.
+빨간 원 번호, 설명 텍스트, 메타 정보 → 절대 UI에 추가 금지.
+
+### 필수 5단계 프로세스
+
+**1단계: Description 정독 및 요소 추출**
+- 각 번호(①②③...) 항목별 정확히 파악
+- 필터 조건, 테이블 헤더, 버튼/액션, 특수 기능 추출
+
+**2단계: 구성 계획 작성 및 사용자 확인**
+🔴 구현 전 반드시 계획 제시 후 사용자 확인 필수. 확인 없이 구현 진행 절대 금지.
+
+```markdown
+## [페이지명] 구성 계획
+### 필터 조건
+| 필터명 | 타입 | 옵션 | 기본값 |
+### 테이블 컬럼
+| 순서 | 컬럼명 | 설명 |
+### 특수 기능
+- [기능1]: [설명]
+```
+
+**3단계: 기존 패턴 검색**
+```
+1순위: 동일 기능 컴포넌트 (예: "*Dashboard*.tsx")
+2순위: 유사 도메인 컴포넌트
+3순위: 공통 UI 컴포넌트 (src/components/ui/)
+```
+
+**4단계: 구현** - 기획서 요소만, 임의 추가 절대 금지
+
+**5단계: 검증 체크리스트**
+```markdown
+| 기획서 요소 | 구현 여부 | 비고 |
+```
+
+---
+
+## Component Pattern Reuse
+**Priority**: 🔴
+
+- 새 컴포넌트 만들기 전 프로젝트 내 유사 컴포넌트 검색 필수
+- 스크린샷만으로 추측 금지, 프로젝트 표준 우선
+
+| 요소 | 확인 사항 |
+|------|----------|
+| 모달/다이얼로그 | 너비, 배경색, 헤더 구조, 버튼 배치 |
+| 문서/프린트 | 용지 스타일, 헤더/푸터, 결재라인 |
+| 폼 | 레이아웃, 필드 배치, 버튼 위치 |
+| 테이블/리스트 | 컬럼 구조, 체크박스, 페이지네이션 |
+
+### 컴포넌트 레지스트리 활용 (dev/component-registry)
+실시간 스캔 기반 컴포넌트 목록 + 관계도 페이지가 존재함. 새로고침 시 최신 상태 반영.
+
+**새 컴포넌트 생성 전 필수 확인**:
+1. **목록 뷰**: 동일/유사 컴포넌트가 이미 있는지 검색
+2. **관계도 뷰**: 유사 컴포넌트의 구성요소(imports)를 확인하여 동일한 공통 컴포넌트 조합 패턴 따르기
+
+**기존 컴포넌트 수정 시 필수 확인**:
+- 관계도의 **사용처(usedBy)** 확인 → 수정 시 영향받는 범위 파악
+- usedBy가 많은 공통 컴포넌트일수록 수정 시 주의
+
+---
+
+## Common Table Standards
+**Priority**: 🔴
+
+### 필수 컬럼 구조
+- **체크박스** → **번호(1부터)** → **데이터 컬럼** → **작업 컬럼**
+- 작업 버튼: 체크박스 선택 시만 표시
+- 번호: `globalIndex` 사용 또는 `(currentPage - 1) * pageSize + index + 1`
+
+---
+
+## Document Table Merging (rowSpan/colSpan)
+**Priority**: 🔴
+
+### 핵심: 구조 분석 → 코딩 (절대 순서 바꾸지 않음)
+
+**1단계: 플랫 인덱스 맵** - 논리적 No가 아닌 실제 렌더링 행 수 기준
+```
+flatIdx 0: No.1 겉모양
+flatIdx 1: No.2 치수-두께  ← No.2 시작 (methodSpan: 3)
+flatIdx 2: No.2 치수-너비
+flatIdx 3: No.2 치수-길이  ← No.2 끝
+```
+
+**2단계: 병합 범위 표기** - span은 병합 그룹의 첫 행에만
+
+**3단계: Coverage Map 패턴**
+```typescript
+function buildCoverageMap(items, spanKey) {
+  const map = {}; const covered = new Set();
+  items.forEach((item, idx) => {
+    const span = item[spanKey];
+    if (span && span > 1) {
+      map[idx] = span;
+      for (let i = idx + 1; i < idx + span; i++) covered.add(i);
+    }
+  });
+  return { map, covered };
+}
+// map에 있으면 → <td rowSpan={span}>
+// covered에 있으면 → skip
+// 둘 다 아니면 → 일반 <td>
+```
+
+---
+
+## Page Layout Standards
+**Priority**: 🟡
+
+- **AuthenticatedLayout**: `<main>`에 패딩 없음
+- **PageLayout**: `p-3 md:p-6` 패딩 담당
+- **page.tsx**: 패딩 wrapper 금지 (이중 패딩 방지)
+
+---
+
+## Design Popup Policy
+**Priority**: 🟡
+
+- `alert()`, `confirm()`, `prompt()` 사용 금지
+- Radix UI Dialog/AlertDialog 또는 `toast from 'sonner'` 사용
+
+---
+
+## Radix UI Select Controlled Mode Bug
+**Priority**: 🟡
+
+빈 값('')으로 마운트 후 value 변경이 반영 안 되는 버그:
+```tsx
+// ✅ key prop으로 강제 리마운트
+<Select key={`${fieldKey}-${stringValue}`} value={stringValue} onValueChange={onChange}>
+```
+
+---
+
+## Build Policy
+**Priority**: 🔴
+
+- Claude가 직접 `npm run build` 실행 금지
+- 빌드 필요 시 사용자에게 "빌드 확인해주세요" 요청
+
+---
+
+## React → Next.js Migration Rules
+**Priority**: 🔴
+
+### localStorage Access
+```typescript
+// ✅ Next.js Pattern
+const [data, setData] = useState(() => {
+  if (typeof window === 'undefined') return defaultValue;
+  const saved = localStorage.getItem('key');
+  return saved ? JSON.parse(saved) : defaultValue;
+});
+```
+
+### App Router Rules
+- Client Components: 'use client' for interactivity, state, browser APIs
+- Dynamic Import: `next/dynamic` with `ssr: false` for client-only components
+
+---
+
+## Large File Migration Workflow
+**Priority**: 🟡
+
+**섹션당 6단계**: 구조 파악 → 기능 구현 → 기능 검증 → 스타일 파악 → 스타일 구현 → 스타일 검증
+
+분할 전략: <1000줄 전체 | 1000-3000줄 3-4섹션 | >3000줄 1000줄 단위
+
+---
+
+## Backend API Analysis Policy
+**Priority**: 🟡
+
+- Backend API 코드는 **분석만**, 직접 수정 안 함
+- 수정 필요 시 백엔드 요청 문서로 정리:
+```markdown
+## 백엔드 API 수정 요청
+### 파일 위치: `/path/to/file.php` - 메서드명 (Line XX-XX)
+### 현재 문제: [설명]
+### 수정 요청: [내용]
+```
+
+---
+
+## Test URL Documentation Rules
+**Priority**: 🟡
+
+- 메인 페이지만 등록, 세부 페이지(상세/수정/등록) 제외
+- 간결한 목록 유지
+
+---
+
+## Zod 스키마 검증 (신규 코드 적용)
+**Priority**: 🟡
+
+### 적용 범위
+- **신규 폼**: Zod 스키마 필수 적용
+- **기존 폼**: 건드리지 않음 (정상 작동 중이면 마이그레이션 불필요)
+- **API 응답**: 신규 서버 액션에서 선택적 적용
+
+### 신규 폼 작성 패턴
+```typescript
+import { z } from 'zod';
+import { useForm } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+
+// 1. 스키마 정의 (타입 + 검증 한 번에)
+const formSchema = z.object({
+  itemName: z.string().min(1, '품목명을 입력하세요'),
+  quantity: z.number().min(1, '1 이상 입력하세요'),
+  status: z.enum(['active', 'inactive']),
+  memo: z.string().optional(),
+});
+
+// 2. 스키마에서 타입 추출 (별도 interface 정의 불필요)
+type FormData = z.infer<typeof formSchema>;
+
+// 3. useForm에 zodResolver 연결
+const form = useForm<FormData>({
+  resolver: zodResolver(formSchema),
+  defaultValues: { itemName: '', quantity: 1, status: 'active' },
+});
+```
+
+### 규칙
+- **스키마 위치**: 컴포넌트 파일 상단 또는 같은 디렉토리의 `schema.ts`
+- **타입 추출**: `z.infer<typeof schema>` 사용, 별도 `interface` 중복 정의 금지
+- **에러 메시지**: 한글로 작성 (사용자에게 직접 표시됨)
+- **`as` 캐스트 지양**: Zod 스키마로 타입이 보장되므로 `as` 캐스트 불필요
+
+### 사용하지 않는 경우
+- 기존 `rules={{ required: true }}` 패턴으로 작동 중인 폼
+- 단순 필드 1~2개짜리 인라인 폼 (오버엔지니어링)
+
+---
+
+## Server Action 공통 유틸리티
+**Priority**: 🔴
+
+### 규칙:
+- `buildApiUrl()` 사용 필수 (직접 `new URLSearchParams` 또는 `${API_URL}` 조립 금지)
+- 페이지네이션 조회 → `executePaginatedAction()` 사용
+- 단건/목록 조회 → `executeServerAction()` 유지
+- `toPaginationMeta()` 직접 사용도 허용
+- **`'use server'` 파일에서 타입 re-export 금지** — `export type { X } from '...'` 사용 불가 (Next.js Turbopack 제한: async 함수만 export 허용). 인라인 `export interface` / `export type X = ...`는 허용. 컴포넌트에서 타입이 필요하면 원본 파일에서 직접 import할 것
+
+### 현황:
+- **전체 43개 actions.ts 마이그레이션 완료** (2026-02-12)
+- `new URLSearchParams` 사용 0건 (actions.ts 기준)
+- 모든 URL 빌딩은 `buildApiUrl(path, params)` 사용
+
+```typescript
+// ✅ 필수 패턴
+import { buildApiUrl } from '@/lib/api/query-params';
+
+// 쿼리 파라미터 있는 경우
+url: buildApiUrl('/api/v1/items', {
+  search: params.search,
+  status: params.status !== 'all' ? params.status : undefined,
+  page: params.page,
+}),
+
+// 동적 경로 + 파라미터
+url: buildApiUrl(`/api/v1/items/${id}`, { with_details: true }),
+
+// 파라미터 없는 단순 경로
+url: buildApiUrl('/api/v1/items'),
+```
+
+```typescript
+// ❌ 금지 패턴
+const API_URL = process.env.NEXT_PUBLIC_API_URL;
+const params = new URLSearchParams();
+params.set('search', value);
+url: `${API_URL}/api/v1/items?${params.toString()}`
+```
+
+---
+
+## Common Component Usage Rules
+**Priority**: 🔴
+
+신규 페이지/모달 작업 시 **반드시** 공통 패턴 가이드를 먼저 읽고 기존 구조를 따를 것.
+
+**트리거 → 가이드 읽기:**
+| 작업 유형 | 읽을 파일 |
+|-----------|----------|
+| 검색 모달/선택 팝업 | `claudedocs/guides/[GUIDE] common-page-patterns.md` → "검색 모달" 섹션 |
+| 리스트/목록 페이지 | `claudedocs/guides/[GUIDE] common-page-patterns.md` → "리스트 페이지" 섹션 |
+| 상세/수정/등록 페이지 | `claudedocs/guides/[GUIDE] common-page-patterns.md` → "상세/폼 페이지" 섹션 |
+| 새 organisms 필요 | `src/components/organisms/index.ts` 먼저 확인 → 없으면 생성 |
+
+**핵심 원칙:**
+- 새 파일 만들기 전 `organisms/`, `molecules/` export 목록 확인
+- 검색+선택 모달 → `SearchableSelectionModal<T>` 사용 (직접 Dialog 조합 금지)
+- 리스트 페이지 → `UniversalListPage` 또는 organisms 조합
+- 상세/폼 → Card + 기존 패턴 따르기
+
+---
+
+## FormField 사용 규칙 (신규 폼 필수)
+**Priority**: 🟡
+
+### 적용 범위
+- **신규 폼**: `Label + Input` 수동 조합 대신 `FormField` molecule 필수 사용
+- **기존 폼**: 건드리지 않음 (해당 파일 수정 시에만 선택적 전환)
+
+### 사용 패턴
+```typescript
+import { FormField } from '@/components/molecules/FormField';
+
+// ✅ 올바른 패턴 - FormField 사용
+<FormField
+  label="회사명"
+  value={formData.companyName}
+  onChange={(value) => handleChange('companyName', value)}
+  placeholder="회사명"
+  disabled={!isEditMode}
+/>
+
+// ❌ 잘못된 패턴 - Label + Input 수동 조합
+<div className="space-y-2">
+  <Label>회사명</Label>
+  <Input
+    value={formData.companyName}
+    onChange={(e) => handleChange('companyName', e.target.value)}
+    placeholder="회사명"
+    disabled={!isEditMode}
+  />
+</div>
+```
+
+### FormField 지원 타입
+| type | 설명 | 대체 컴포넌트 |
+|------|------|---------------|
+| `text` (기본값) | 일반 텍스트 입력 | Label + Input |
+| `number` | 숫자 입력 | Label + Input[type=number] |
+| `email` | 이메일 입력 | Label + Input[type=email] |
+| `tel` | 전화번호 (자동 포맷) | Label + PhoneInput |
+| `businessNumber` | 사업자등록번호 (자동 포맷) | Label + BusinessNumberInput |
+| `textarea` | 여러 줄 텍스트 | Label + Textarea |
+
+### FormField로 대체하지 않는 경우
+- **특수 컴포넌트 필드**: Select, DatePicker, ImageUpload, FileInput, AccountNumberInput 등
+- **복합 레이아웃 필드**: 주소 검색(버튼+입력), 다중 입력 조합
+- **커스텀 인터랙션**: 편집/읽기 모드가 다른 컴포넌트(예: 결제일 Select↔Input 전환)
+
+---
+
+## User Environment
+**Priority**: 🟢
+
+- 스크린샷: 항상 바탕화면 `/Users/byeongcheolryu/Desktop/`
+- 파일명 패턴: `스크린샷 YYYY-MM-DD 오전/오후 HH.MM.SS.png`

CURRENT_WORKS.md

@@ -1,37 +1,24 @@
 # SAM React 작업 현황
 
-## 2026-01-09 (목) - Phase L 건설관리 Mock → API 연동 (3개 모듈) ✅
+## 🔄 진행 중 - 절곡 작업일지 실 데이터 테스트
 
-### 작업 목표
-- Backend API가 이미 존재하는 3개 모듈의 Mock → API 연동
-- pricing-management, estimates, category-management
+- ✅ 절곡 작업일지 PHP 기준 완전 재구현 (4개 카테고리 섹션)
+- ✅ 슬랫 작업일지 입고 LOT NO 개소별 표시 수정
+- ⬜ 절곡 실 데이터 테스트 (bending_info 채워진 작업지시로 확인)
 
-### 완료된 작업
+### 최근 커밋
+- `59b9b1b` (2026-02-19) feat(WEB): 절곡 작업일지 완전 재구현 + 슬랫 입고 LOT NO 개소별 표시 수정
 
-| 모듈 | 변경 내용 | 상태 |
-|------|----------|------|
-| pricing-management | Mock → apiClient 변환 (378줄), types.ts 타입 추가 | ✅ |
-| estimates | Mock → apiClient 변환, 복잡한 중첩 타입 처리 | ✅ |
-| category-management | Mock → apiClient 변환, 에러 타입 처리 (IN_USE/DEFAULT/GENERAL) | ✅ |
+---
 
-### 수정된 파일
-| 파일명 | 설명 |
-|--------|------|
-| `src/components/business/construction/pricing-management/actions.ts` | Mock → apiClient 표준화 |
-| `src/components/business/construction/pricing-management/types.ts` | PricingListResponse, PricingFilter, PricingFormData 추가 |
-| `src/components/business/construction/estimates/actions.ts` | Mock → apiClient 표준화 (중첩 타입) |
-| `src/components/business/construction/category-management/actions.ts` | Mock → apiClient 표준화 |
+## TODO - 미커밋 변경사항
 
-### 적용된 패턴
-- `'use server'` + `apiClient from '@/lib/api'`
-- Snake_case API 타입 (ApiXxx) → camelCase Frontend 타입 변환
-- 표준 응답: `{ success, data?, error? }`
-- 페이지네이션: `{ items, total, page, size, totalPages }`
+- `src/components/quotes/types.ts` - `formula_source?: string` 추가 (TypeScript 빌드 에러 수정)
 
-### 빌드 검증
-✅ Next.js 빌드 성공 (349 페이지)
+---
+
+## TODO - 건설관리 Mock 모듈 (Backend API 개발 후 연동)
 
-### 남은 Mock 모듈 (Backend API 개발 필요)
 | 모듈 | Backend API | 비고 |
 |------|-------------|------|
 | bidding | ❌ 없음 | Backend 필요 |
@@ -39,807 +26,4 @@
 | structure-review | ❌ 없음 | Backend 필요 |
 | labor-management | ❌ 없음 | Backend 필요 |
 
----
-
-## 2026-01-09 (목) - Phase 1.3-1.5 건설관리 apiClient 표준화
-
-### 작업 목표
-- 건설관리 모듈의 커스텀 `apiRequest` 함수를 표준 `apiClient` 패턴으로 변환
-- Phase 1.3: 계약관리(contract), Phase 1.4: 거래처관리(partners), Phase 1.5: 현장관리(site-management)
-
-### 수정된 파일
-| 파일명 | 설명 |
-|--------|------|
-| `src/components/business/construction/contract/actions.ts` | 커스텀 apiRequest → apiClient 표준화 |
-| `src/components/business/construction/partners/actions.ts` | 커스텀 apiRequest → apiClient 표준화 |
-| `src/components/business/construction/site-management/actions.ts` | 커스텀 apiRequest → apiClient 표준화 |
-
-### 주요 변경 내용
-
-#### 1. 제거된 코드 (각 파일에서)
-- 커스텀 `apiRequest()` 함수 전체
-- `import { cookies } from 'next/headers'`
-- `const API_BASE_URL = process.env.NEXT_PUBLIC_API_URL`
-- `const API_KEY = process.env.API_KEY`
-
-#### 2. 추가된 코드
-- `import { apiClient } from '@/lib/api'`
-- 명시적 API 타입 정의:
-  - **contract**: `ApiContract`, `ApiContractFile`, `ApiAttachment`, `ApiContractStats`, `ApiContractStageCount`
-  - **partners**: `ApiPartner`, `ApiPartnerStats`
-  - **site-management**: `ApiSite`, `ApiSiteStats`
-
-#### 3. API 엔드포인트 (변경 없음)
-**계약관리 (contract)**
-- `GET /construction/contracts` - 목록
-- `GET /construction/contracts/stats` - 통계
-- `GET /construction/contracts/stage-counts` - 단계별 건수
-- `GET /construction/contracts/{id}` - 상세
-- `POST /construction/contracts` - 등록
-- `PUT /construction/contracts/{id}` - 수정
-- `DELETE /construction/contracts/{id}` - 삭제
-- `DELETE /construction/contracts/bulk` - 일괄 삭제
-
-**거래처관리 (partners)**
-- `GET /clients` - 목록
-- `GET /clients/stats` - 통계
-- `GET /clients/{id}` - 상세
-- `POST /clients` - 등록
-- `PUT /clients/{id}` - 수정
-- `DELETE /clients/{id}` - 삭제
-- `DELETE /clients/bulk` - 일괄 삭제
-
-**현장관리 (site-management)**
-- `GET /sites` - 목록
-- `GET /sites/stats` - 통계
-- `DELETE /sites/{id}` - 삭제
-- `DELETE /sites/bulk` - 일괄 삭제
-
-### 빌드 검증
-✅ Next.js 빌드 성공 (349 페이지)
-
-### Git 커밋
-- React: `5db6e59` refactor(construction): 건설관리 3개 모듈 apiClient 표준화
-
----
-
-## 2026-01-09 (목) - Phase 1.2 인수인계보고서 API 표준화
-
-### 작업 목표
-- `handover-report/actions.ts` 커스텀 fetch → 표준 apiClient 변환
-- 기존 API 연동 코드를 프로젝트 표준 패턴으로 통일
-
-### 수정된 파일
-| 파일명 | 설명 |
-|--------|------|
-| `src/components/business/construction/handover-report/actions.ts` | 커스텀 apiRequest → apiClient 표준화 |
-
-### 주요 변경 내용
-
-#### 1. 제거된 코드
-- 커스텀 `apiRequest()` 함수 (52줄)
-- `cookies()` 직접 import
-- `API_BASE_URL`, `API_KEY` 직접 정의
-
-#### 2. 추가된 코드
-- `import { apiClient } from '@/lib/api'`
-- 명시적 API 타입 정의: `ApiHandoverReport`, `ApiManager`, `ApiContractItem`, `ApiExternalEquipmentCost`
-
-#### 3. API 엔드포인트 (변경 없음)
-- `GET /construction/handover-reports` - 목록
-- `GET /construction/handover-reports/stats` - 통계
-- `GET /construction/handover-reports/{id}` - 상세
-- `POST /construction/handover-reports` - 등록
-- `PUT /construction/handover-reports/{id}` - 수정
-- `DELETE /construction/handover-reports/{id}` - 삭제
-- `DELETE /construction/handover-reports/bulk` - 일괄 삭제
-
-### 빌드 검증
-✅ Next.js 빌드 성공 (349 페이지)
-
-### Git 커밋
-- React: `b7b8b90` refactor(handover-report): 커스텀 fetch → apiClient 표준화
-
----
-
-## 2026-01-09 (목) - Phase 2.4 수주관리 API 연동
-
-### 작업 목표
-- 시공사 페이지 API 연동 계획 Phase 2.4: 수주관리
-- `order-management/actions.ts` Mock 데이터 → 실제 API 연동
-- common_codes 테이블 기반 공용 코드 시스템 도입
-
-### 수정된 파일
-| 저장소 | 파일명 | 설명 |
-|--------|--------|------|
-| api | `database/migrations/2026_01_09_171700_add_order_codes_to_common_codes.php` | order_status/order_type 코드 추가 |
-| api | `app/Http/Controllers/Api/V1/CommonController.php` | index 메서드 구현 |
-| react | `src/lib/api/common-codes.ts` | 공용 코드 조회 유틸리티 (신규) |
-| react | `src/lib/api/index.ts` | common-codes 모듈 export 추가 |
-| react | `src/components/business/construction/order-management/actions.ts` | Mock → API 완전 재작성 |
-
-### 주요 변경 내용
-
-#### 1. common_codes 공용 코드 시스템
-- `order_status` 코드 그룹: DRAFT, CONFIRMED, IN_PROGRESS, COMPLETED, CANCELLED
-- `order_type` 코드 그룹: ORDER, PURCHASE
-- API 엔드포인트: `GET /api/v1/settings/common/{group}`
-
-#### 2. 상태 매핑 함수
-| Frontend | Backend |
-|----------|---------|
-| waiting | DRAFT |
-| order_complete | CONFIRMED |
-| delivery_scheduled | IN_PROGRESS |
-| delivery_complete | COMPLETED |
-
-#### 3. API 함수 구현 (10개)
-- `getOrderList()` - GET /api/v1/orders
-- `getOrderStats()` - GET /api/v1/orders/stats
-- `getOrderDetail()` - GET /api/v1/orders/{id}
-- `getOrderDetailFull()` - GET /api/v1/orders/{id} (전체 정보)
-- `createOrder()` - POST /api/v1/orders
-- `updateOrder()` - PUT /api/v1/orders/{id}
-- `deleteOrder()` - DELETE /api/v1/orders/{id}
-- `deleteOrders()` - 개별 삭제 반복 (batch API 미존재)
-- `duplicateOrder()` - 조회 후 새로 생성
-- `updateOrderStatus()` - PATCH /api/v1/orders/{id}/status
-
-### Git 커밋
-- API: `9f8bff2` feat(common-codes): order_status/order_type 공용 코드 추가
-- React: `6615f39` feat(order-management): Mock → API 연동 및 common-codes 유틸리티 추가
-
-### 빌드 검증
-✅ Next.js 빌드 성공 (349 페이지)
-
----
-
-## 2026-01-09 (목) - TODO-1 결재선/참조 Select 버그 수정
-
-### 작업 목표
-- 결재선/참조 Select 컴포넌트에서 선택한 직원 정보가 표시되지 않는 버그 수정
-- @/lib/api barrel export 추가 (빌드 오류 해결)
-
-### 수정된 파일
-| 파일명 | 설명 |
-|--------|------|
-| `src/components/approval/DocumentCreate/ApprovalLineSection.tsx` | SelectValue 버그 수정 |
-| `src/components/approval/DocumentCreate/ReferenceSection.tsx` | SelectValue 버그 수정 |
-| `src/lib/api/index.ts` | 신규 생성 - barrel export |
-
-### 주요 변경 내용
-
-#### 1. SelectValue 버그 수정
-**문제**: Radix UI SelectValue의 children prop에 조건부 렌더링 사용 시 Select 상태 관리가 깨짐
-
-**해결**: children 제거, placeholder prop으로 이동
-```tsx
-// Before (버그)
-<SelectValue placeholder="부서명 / 직책명 / 이름 ▼">
-  {person.name ? `${person.department} / ${person.position} / ${person.name}` : null}
-</SelectValue>
-
-// After (수정)
-<SelectValue
-  placeholder={
-    person.name && !person.id.startsWith('temp-')
-      ? `${person.department || ''} / ${person.position || ''} / ${person.name}`
-      : "부서명 / 직책명 / 이름 ▼"
-  }
-/>
-```
-
-#### 2. @/lib/api barrel export
-Phase 2.3 자재관리 작업에서 사용하는 import 경로 지원:
-```typescript
-// src/lib/api/index.ts
-export { ApiClient, withTokenRefresh } from './client';
-export { serverFetch } from './fetch-wrapper';
-export { AUTH_CONFIG } from './auth/auth-config';
-
-export const apiClient = new ApiClient({
-  mode: 'api-key',
-  apiKey: process.env.API_KEY,
-});
-```
-
-### 빌드 검증
-✅ Next.js 빌드 성공 (349 페이지)
-
----
-
-## 2026-01-09 (목) - Phase 2.3 자재관리(품목관리) API 연동
-
-### 작업 목표
-- 시공사 페이지 API 연동 계획 Phase 2.3: 자재관리
-- `item-management/actions.ts` Mock 데이터 → 실제 API 연동
-
-### 수정된 파일
-| 파일명 | 설명 |
-|--------|------|
-| `src/components/business/construction/item-management/actions.ts` | Mock → API 완전 재작성 |
-| `claudedocs/[IMPL-2026-01-09] item-management-api-integration.md` | 구현 문서 |
-
-### 주요 변경 내용
-
-#### 1. 타입 변환 함수 추가
-- `transformItemType()` - Backend item_type → Frontend itemType
-- `transformToBackendItemType()` - Frontend itemType → Backend item_type
-- `transformSpecification()` - Backend options → Frontend specification
-- `transformOrderType()` - Backend options → Frontend orderType
-- `transformStatus()` - Backend is_active + options → Frontend status
-- `transformOrderItems()` - Backend options → Frontend orderItems
-- `transformItem()` - API 응답 → Item 타입
-- `transformItemDetail()` - API 응답 → ItemDetail 타입
-- `transformItemToApi()` - ItemFormData → API 요청 데이터
-
-#### 2. 품목유형 매핑
-| Frontend | Backend |
-|----------|---------|
-| 제품 | FG |
-| 부품 | PT |
-| 소모품 | CS |
-| 공과 | RM |
-
-#### 3. API 함수 구현 (8개)
-- `getItemList()` - GET /api/v1/items
-- `getItemStats()` - GET /api/v1/items/stats
-- `getItem()` - GET /api/v1/items/{id}
-- `createItem()` - POST /api/v1/items
-- `updateItem()` - PUT /api/v1/items/{id}
-- `deleteItem()` - DELETE /api/v1/items/{id}
-- `deleteItems()` - DELETE /api/v1/items/batch
-- `getCategoryOptions()` - GET /api/v1/categories
-
-#### 4. Frontend 전용 필터링
-Backend에서 미지원 필터는 Frontend에서 처리:
-- 규격 (specification)
-- 구분 (orderType)
-- 날짜 범위 (startDate, endDate)
-- 정렬 (sortBy)
-
-### 관련 API 변경 (api 저장소)
-- `routes/api.php` - `/items/stats` 라우트 추가
-
-### 관련 문서
-- 구현 문서: `claudedocs/[IMPL-2026-01-09] item-management-api-integration.md`
-
----
-
-## 2025-01-09 (목) - 작업지시 process_type → process_id FK 변환
-
-### 작업 목표
-- 작업지시의 `process_type` (varchar enum: 'screen'/'slat'/'bending')를 `process_id` (FK → processes.id)로 변환
-- API와 Frontend 전체 스택 마이그레이션
-
-### 수정된 파일
-| 파일명 | 설명 |
-|--------|------|
-| `src/components/production/WorkOrders/types.ts` | processId, processName, processCode 필드 추가, transformApiToFrontend에서 processType 하위 호환 유지 |
-| `src/components/production/WorkOrders/actions.ts` | getProcessOptions() 추가, createWorkOrder에서 processId 사용 |
-| `src/components/production/WorkOrders/WorkOrderCreate.tsx` | processType enum → processId FK 변경, 동적 공정 옵션 로딩 |
-| `src/components/production/WorkOrders/WorkOrderList.tsx` | PROCESS_TYPE_LABELS 제거, order.processName 사용 |
-| `src/components/production/WorkOrders/WorkOrderDetail.tsx` | PROCESS_TYPE_LABELS 제거, order.processName 사용 (비즈니스 로직은 processType 유지) |
-
-### 주요 변경 내용
-
-#### 1. types.ts - 타입 및 변환 함수
-- `WorkOrder` 인터페이스에 `processId`, `processName`, `processCode` 추가
-- `processType`은 `@deprecated` 마킹, 하위 호환용 유지
-- `transformApiToFrontend`에서 `processName` → `processType` 자동 매핑
-
-#### 2. actions.ts - 서버 액션
-- `getProcessOptions()`: 공정 목록 API 조회 (GET /api/v1/processes)
-- `createWorkOrder()`: `processId` 필드 사용 (기존 processType 제거)
-
-#### 3. WorkOrderCreate.tsx - 등록 폼
-- `processType: ProcessType` → `processId: number | null`
-- `useEffect`로 공정 옵션 동적 로딩
-- 첫 번째 공정 자동 선택 (기본값)
-- Select 컴포넌트 동적 옵션 렌더링
-
-#### 4. WorkOrderList.tsx / WorkOrderDetail.tsx - 목록/상세
-- `PROCESS_TYPE_LABELS[order.processType]` → `order.processName`
-- 비즈니스 로직(ProcessSteps, 절곡 확인)은 `processType` 유지
-
-### 빌드 검증
-✅ Next.js 빌드 성공 (TypeScript 오류 없음)
-
-### 관련 API 변경 (api 저장소)
-- `WorkOrder` 모델: `process_id` FK 추가, `process()` 관계 정의
-- `WorkOrderService`: `process_id` 사용
-- `WorkOrderStoreRequest/UpdateRequest`: `process_id` 검증 규칙
-
----
-
-## 2025-01-09 (목) - 작업지시 코드 리뷰 기반 프론트엔드 개선
-
-### 작업 목표
-- 작업지시 기능 코드 리뷰 결과 기반 프론트엔드 개선
-- Critical, High, Medium 우선순위 항목 전체 수정
-
-### 수정된 파일
-| 파일명 | 설명 |
-|--------|------|
-| `src/components/production/WorkOrders/WorkOrderList.tsx` | useCallback 의존성 순환 수정 |
-| `src/components/production/WorkOrders/WorkOrderDetail.tsx` | 작업 버튼 핸들러 구현 |
-| `src/components/production/WorkOrders/types.ts` | scheduledDate 매핑, 다중 담당자 타입 추가 |
-| `src/components/production/WorkOrders/actions.ts` | API 경로 수정 (/sales-orders → /orders) |
-| `src/components/production/WorkOrders/SalesOrderSelectModal.tsx` | debounce 적용 |
-| `src/components/production/WorkOrders/hooks/useDebounce.ts` | 신규 생성 - 커스텀 debounce 훅 |
-
-### 주요 변경 내용
-1. **useCallback 의존성 수정**: 무한 루프 방지를 위한 의존성 배열 수정
-2. **scheduledDate 매핑**: transformFrontendToApi에 scheduled_date 필드 추가
-3. **작업 버튼 구현**: "시작"/"완료" 버튼 핸들러 추가
-4. **API 경로 수정**: `/api/v1/sales-orders` → `/api/v1/orders` 변경
-5. **debounce 적용**: 커스텀 useDebounce 훅 (300ms) 적용
-6. **다중 담당자 타입**: WorkOrderAssigneeApi 인터페이스 및 assignees 필드 추가
-
-### Git 커밋
-- `12b4259 refactor(work-orders): 코드 리뷰 기반 프론트엔드 개선`
-
-### 관련 문서
-- 계획: `~/.claude/plans/purring-sparking-pinwheel.md`
-
----
-
-## 2025-01-02 (목) - 견적 등록 자동산출 기능 구현
-
-### 작업 목표
-- 견적 등록 화면에서 BOM 기반 자동산출 기능 구현
-- MNG 시뮬레이터와 동일하게 동작하도록 API 연동
-
-### 수정된 파일
-| 파일명 | 설명 |
-|--------|------|
-| `src/components/quotes/QuoteRegistration.tsx` | FormField type="custom" 추가, API 요청 구조 변경, 응답 파싱 수정 |
-| `src/components/quotes/actions.ts` | Item 모델 필드 매핑 수정, BomCalculateItem 인터페이스 변경 |
-
-### 주요 변경 내용
-1. **FormField 렌더링 수정**:
-   - Input 자식 컴포넌트도 `type="custom"` 필요
-   - openWidth, openHeight 필드에 적용
-
-2. **API 필드 매핑 수정** (actions.ts):
-   - `item.item_code` → `item.code` (Laravel Item 모델 필드명)
-   - `item.item_name` → `item.name`
-
-3. **API 요청 구조 변경** (QuoteRegistration.tsx):
-   - 중첩 구조 제거: `{ input_variables: { W0, H0 } }` → `{ openWidth, openHeight }`
-   - flat 구조로 API FormRequest와 일치
-
-4. **API Enum 값 변경**:
-   - 가이드레일: "벽면형" → "wall", "측면형" → "floor"
-   - 모터전원: "220V" → "single", "380V" → "three"
-   - 제어기: "단독" → "basic", "연동" → "smart"
-
-5. **API 응답 파싱 수정**:
-   - `result.data.items` 배열 접근
-   - `result.data.summary.grand_total` 총합계 접근
-
-### Git 커밋
-- `5a3e534` feat(WEB): 견적 등록 자동산출 기능 구현
-- `5f062d5` chore(WEB): 견적 등록 디버깅 로그 제거
-
-### 관련 API
-- `POST /api/v1/quotes/calculate/bom/bulk` - 다건 BOM 자동산출 API
-
----
-
-## 2025-01-02 (목) - 채권현황 동적월 지원 및 버그 수정
-
-### 작업 목표
-- "최근 1년" 필터 선택 시 동적 월 기간(최근 12개월) 지원
-- year=0 파라미터 처리 버그 수정
-- 거래처별 연체 상태 및 메모 관리 기능 추가
-
-### 수정된 파일
-| 파일명 | 설명 |
-|--------|------|
-| `src/components/accounting/ReceivablesStatus/types.ts` | MonthlyAmount 동적 배열로 변경, 새 필드 추가 |
-| `src/components/accounting/ReceivablesStatus/actions.ts` | year=0 처리 버그 수정, updateMemos 액션 추가 |
-| `src/components/accounting/ReceivablesStatus/index.tsx` | 동적 월 헤더 및 메모 입력 행 추가 |
-
-### 주요 변경 내용
-1. **types.ts 변경**:
-   - `MonthlyAmount`: 고정 월 키 → `values: number[]` 동적 배열
-   - `VendorReceivables`: `monthLabels`, `carryForwardBalance`, `memo` 필드 추가
-   - 정적 `MONTH_LABELS`, `MONTH_KEYS` 상수 제거
-
-2. **actions.ts 버그 수정**:
-   - `typeof yearValue === 'number'` 명시적 타입 체크 추가
-   - `year=0`일 때 `recent_year=true` 파라미터 올바르게 전송
-   - `updateMemos` 액션 추가
-
-3. **index.tsx UI 개선**:
-   - API에서 받은 `monthLabels` 사용하여 동적 헤더 렌더링
-   - 메모 입력 행 추가 (거래처 단위)
-   - 연체/메모 변경사항 추적 및 저장
-
-### Git 커밋
-- `672b1b4` feat(WEB): 채권현황 동적월 지원 및 year=0 파라미터 버그 수정
-
-### 남은 작업
-- [ ] 디버깅 console.log 제거 (테스트 완료 후)
-- [ ] 추가 UI 개선사항 확인
-
----
-
-## 2025-12-28 (토) - 고객센터 시스템 게시판 API 연동 수정
-
-### 작업 목표
-- 고객센터 컴포넌트에서 시스템 게시판 API 엔드포인트 사용
-- 날짜 범위 필터 초기값 수정 (전체 조회)
-
-### 수정된 파일 (4개)
-
-| 파일명 | 변경 내용 |
-|--------|----------|
-| `src/components/customer-center/shared/actions.ts` | `/boards/` → `/system-boards/` API 엔드포인트 변경 |
-| `src/components/customer-center/EventManagement/EventList.tsx` | 날짜 범위 초기값 빈 문자열로 변경 (전체 조회) |
-| `src/components/customer-center/InquiryManagement/InquiryList.tsx` | 날짜 범위 초기값 빈 문자열로 변경 (전체 조회) |
-| `src/components/customer-center/NoticeManagement/NoticeList.tsx` | 날짜 범위 초기값 빈 문자열로 변경 (전체 조회) |
-
-### 상세 변경사항
-
-#### 1. shared/actions.ts API 엔드포인트 변경
-```typescript
-// 변경 전
-const url = `${process.env.NEXT_PUBLIC_API_URL}/api/v1/boards/${boardCode}/posts`;
-
-// 변경 후
-const url = `${process.env.NEXT_PUBLIC_API_URL}/api/v1/system-boards/${boardCode}/posts`;
-```
-
-영향받는 함수:
-- `getPosts()` - 게시글 목록 조회
-- `getPost()` - 게시글 상세 조회
-- `createPost()` - 게시글 생성
-- `updatePost()` - 게시글 수정
-- `deletePost()` - 게시글 삭제
-
-#### 2. 날짜 범위 필터 초기값 변경
-```typescript
-// 변경 전
-const [startDate, setStartDate] = useState(format(new Date(), 'yyyy-MM-dd'));
-const [endDate, setEndDate] = useState(format(new Date(), 'yyyy-MM-dd'));
-
-// 변경 후
-const [startDate, setStartDate] = useState('');
-const [endDate, setEndDate] = useState('');
-```
-
-- 초기 로드 시 모든 데이터 조회 가능
-- 날짜 필터 미선택 시 전체 기간 조회
-
-### 연관 API 수정 (api 저장소)
-- `PostService.php` - 시스템 게시판 tenant_id 처리 개선
-- custom_fields field_key → field_id 매핑 지원
-- 댓글 생성 시 tenant_id 추가
-
----
-
-## 2025-12-27 (금) - 결재 문서 작성 버그 수정
-
-### 수정된 파일 (2개)
-
-| 파일명 | 변경 내용 |
-|--------|----------|
-| `src/components/approval/DocumentCreate/actions.ts` | transformApiToFormData에서 `form.code` 처리 추가 |
-| `src/components/approval/DocumentCreate/index.tsx` | useRef로 toast 중복 호출 방지 |
-
-### 완료된 수정
-
-#### 1. 복제 모드 documentType 매핑 오류 수정
-- **문제**: 복제로 들어왔을 때 문서유형이 선택되지 않아 추가 폼이 안 보임
-- **원인**: API는 `form.code`로 반환하는데 프론트엔드는 `form_code`를 기대
-- **수정파일**: `src/components/approval/DocumentCreate/actions.ts`
-- **수정내용**: `transformApiToFormData`에서 `apiData.form?.code || apiData.form_code` 처리
-
-#### 2. 복제 모드 toast 중복 호출 수정
-- **문제**: "문서가 복제되었습니다" 메시지가 두 번 표시됨
-- **원인**: React.StrictMode에서 useEffect 두 번 실행
-- **수정파일**: `src/components/approval/DocumentCreate/index.tsx`
-- **수정내용**: `useRef`로 toast 호출 중복 방지
-
-### 미해결 React Todo 🚧
-
-#### TODO-1: 결재선/참조 Select 변경 불가 문제
-- **증상**: 한번 결재자/참조자를 선택하면 다른 사람으로 변경 불가
-- **원인 후보**:
-  1. `SelectTrigger` 내부 조건부 렌더링(`span` vs `SelectValue`)이 Radix Select 상태 관리에 영향
-  2. `employees` 배열에 선택된 person이 없어서 Select value가 유효하지 않음
-- **해결 방향**:
-  - A. `employees` 배열에 현재 선택된 사람들 포함 (useMemo)
-  - B. `SelectTrigger` 내부를 항상 `SelectValue`만 렌더링하고 표시 내용만 변경
-  - C. Shadcn/ui Select 컴포넌트 디버깅 필요
-- **파일**: `ApprovalLineSection.tsx`, `ReferenceSection.tsx`
-
----
-
-## 2025-12-26 (목) - 급여관리 직책/직급 매핑 수정
-
-### 문제
-- 급여관리 페이지에서 직책과 직급이 사원관리와 다르게 표시됨
-- `position_label` → 직책으로 잘못 매핑 (실제로는 직위)
-- `job_title_label` → 직급으로 잘못 매핑 (실제로는 직책)
-
-### 수정된 파일 (1개)
-
-| 파일명 | 변경 내용 |
-|--------|----------|
-| `src/components/hr/SalaryManagement/actions.ts` | 직책/직급 매핑 수정 |
-
-### 상세 변경사항
-- `transformApiToFrontend` (목록용):
-  - `position: profile?.position_label` → `profile?.job_title_label` (직책)
-  - `rank: profile?.job_title_label` → `profile?.rank` (직급)
-- `transformApiToDetail` (상세용):
-  - 동일하게 수정
-
-### 매핑 기준 (사원관리 기준 통일)
-| 필드 | API 필드 | 설명 | 예시 |
-|------|----------|------|------|
-| 직책 (position) | `job_title_label` | 직무상 책임 | 팀장, 팀원 |
-| 직급 (rank) | `rank` | 호봉 등급 | 부장, 과장, 대리 |
-
----
-
-## 2025-12-26 (목) - 휴가관리 사용현황 동기화 수정
-
-### 작업 목표
-- 휴가 승인 후 사용현황 즉시 반영
-- 부여일수 계산 수정 (기본 15일 + 부여분)
-
-### 수정된 파일 (1개)
-
-| 파일명 | 변경 내용 |
-|--------|----------|
-| `src/components/hr/VacationManagement/index.tsx` | 승인 후 `fetchUsageData()` 호출 추가, baseVacation 고정 '15일', grantedVacation 계산식 수정 |
-
-### 상세 변경사항
-- `handleApproveConfirm`: 승인 후 `fetchUsageData()` 호출 추가
-- `baseVacation`: 동적 `${totalDays}일` → 고정 `'15일'`
-- `grantedVacation`: 하드코딩 `'0일'` → `Math.max(0, totalDays - 15)일`
-- `useCallback` dependencies에 `fetchUsageData` 추가
-
-### Git 커밋
-```
-909005c fix(vacation): 휴가 사용현황 동기화 및 부여일수 계산 수정
-```
-
----
-
-## 2025-12-23 (월) - React Mock Data to API 마이그레이션 Phase B
-
-### 프로젝트 개요
-React 컴포넌트에서 Mock 데이터를 실제 API 호출로 교체하는 작업
-
-**참고 문서:** `docs/plans/react-mock-to-api-migration-plan.md`
-
-### 진행 상황
-
-#### Phase A (완료 - 이전 세션)
-- [x] A-1 악성채권 관리 API 연동
-- [x] A-2 거래처 관리 API 연동
-- [x] A-3 어음 관리 API 연동
-- [x] A-4 대출 관리 API 연동
-- [x] A-5 알림 설정 API 연동
-- [x] A-6 거래처 원장 (API 미존재로 스킵)
-
-#### Phase B (✅ 완료)
-- [x] B-1 매출관리 (SalesManagement) API 연동 ✅
-- [x] B-2 매입관리 (PurchaseManagement) API 연동 ✅
-- [x] B-2.1 매입 세금계산서 토글 기능 수정 ✅
-- [x] B-3 입금관리 (DepositManagement) API 연동 ✅
-- [x] B-4 출금관리 (WithdrawalManagement) API 연동 ✅
-- [x] B-5 거래처관리 (VendorManagement) API 연동 ✅
-- [x] B-6 어음관리 (BillManagement) API 연동 ✅
-
-> **참고**: 원본 계획 문서(`docs/plans/react-mock-to-api-migration-plan.md`)의 Phase B 정의와 일치하도록 수정함
-
----
-
-### B-1 매출관리 API 연동 (완료)
-
-#### 수정된 파일
-- `src/components/accounting/SalesManagement/types.ts`
-  - API 응답 타입 추가 (ApiSaleData, ApiSalesListResponse 등)
-  - transformApiSaleToRecord() 변환 함수 추가
-  - formatDate() 날짜 포맷 함수 추가
-
-- `src/components/accounting/SalesManagement/index.tsx`
-  - generateMockData() 제거
-  - fetchSales(), deleteSale() API 함수 추가
-  - useEffect로 API 데이터 로딩
-  - 삭제 핸들러 API 연동
-
-#### 테스트 결과
-- API 연동 성공 (80개 레코드)
-- 페이지네이션 정상 동작 (4페이지)
-- 통계 카드 정상 표시 (총 매출: 679,876,062원)
-- 날짜 포맷 정상 (YYYY-MM-DD)
-
----
-
-### B-2 매입관리 API 연동 (완료)
-
-#### 수정된 파일
-- `src/components/accounting/PurchaseManagement/types.ts`
-  - API 응답 타입 추가 (ApiPurchaseData, ApiPurchasesListResponse 등)
-  - transformApiPurchaseToRecord() 변환 함수 추가
-  - formatDate() 날짜 포맷 함수 추가
-
-- `src/components/accounting/PurchaseManagement/index.tsx`
-  - generateMockData() 제거
-  - fetchPurchases(), deletePurchase() API 함수 추가
-  - useEffect로 API 데이터 로딩
-  - 삭제 핸들러 API 연동
-  - toast 알림 추가
-
-#### 테스트 결과
-- API 연동 성공 (70개 레코드)
-- 페이지네이션 정상 동작 (4페이지)
-- 통계 카드 정상 표시:
-  - 총 매입: 577,881,642원
-  - 당월 매입: 164,988,080원
-  - 매입유형 미설정: 20건
-  - 세금계산서 수취 미확인: 8건
-- 날짜 포맷 정상 (YYYY-MM-DD)
-
----
-
-### B-2.1 매입 세금계산서 토글 기능 수정 (2025-12-24)
-
-#### 문제
-- 매입 관리 페이지에서 세금계산서 수취 토글이 작동하지 않음
-- 원인 1: API 마이그레이션 미실행 (tax_invoice_received 컬럼 미존재)
-- 원인 2: index.tsx에서 Mock 데이터 사용 중 (API 미연동)
-
-#### 수정된 파일
-- `src/components/accounting/PurchaseManagement/index.tsx`
-  - Mock 데이터(generateMockData) → API 데이터로 전환
-  - useEffect 추가로 API 데이터 로딩
-  - isLoading 상태 추가
-  - vendorOptions에서 빈 문자열 필터링 (Select.Item 에러 수정)
-  - format import 제거 (미사용)
-  - PurchaseType import 제거 (미사용)
-
-- `src/components/accounting/PurchaseManagement/actions.ts` (신규)
-  - getPurchases(): 매입 목록 조회 서버 액션
-  - togglePurchaseTaxInvoice(): 세금계산서 수취 토글 서버 액션
-  - API 응답 변환 함수 포함
-
-#### API 변경사항 (api 저장소)
-- 마이그레이션 실행: `2025_12_24_160000_add_tax_invoice_received_to_purchases_table`
-- Purchase 모델: tax_invoice_received 필드 추가
-- PurchaseService: toggleTaxInvoice() 메서드 추가
-
-#### 버그 수정
-- **Console Error**: `A <Select.Item /> must have a value prop that is not an empty string`
-  - 원인: API 응답에 vendorName이 빈 문자열인 매입 레코드 존재
-  - 해결: vendorOptions 생성 시 빈 문자열 필터링 추가
-  ```typescript
-  const uniqueVendors = [...new Set(data.map(d => d.vendorName).filter(v => v && v.trim() !== ''))];
-  ```
-
-#### 테스트 결과
-- 세금계산서 수취 토글 정상 동작 ✅
-- API 호출 및 UI 업데이트 정상 ✅
-- Console 에러 해결 ✅
-
----
-
-### API 연동 패턴 (공통)
-
-```typescript
-// 1. types.ts에 API 타입 추가
-export interface ApiXxxData {
-  id: number;
-  // snake_case 필드들
-}
-
-export interface ApiXxxListResponse {
-  success: boolean;
-  message: string;
-  data: {
-    data: ApiXxxData[];
-    current_page: number;
-    last_page: number;
-    per_page: number;
-    total: number;
-  };
-}
-
-// 2. 변환 함수 추가
-export function transformApiXxxToRecord(apiData: ApiXxxData): XxxRecord {
-  // snake_case → camelCase 변환
-  // 날짜 포맷 변환
-  // 상태 매핑
-}
-
-// 3. index.tsx에서 API 함수 추가
-async function fetchXxx(params): Promise<ApiXxxListResponse> {
-  const url = `/api/proxy/xxx?${searchParams.toString()}`;
-  const response = await fetch(url);
-  return response.json();
-}
-
-// 4. useEffect로 데이터 로딩
-useEffect(() => {
-  loadData();
-}, [loadData]);
-```
-
----
-
-#### Phase C (✅ 완료)
-- [x] C-1 직원관리 (EmployeeManagement) API 연동 ✅
-- [x] C-2 근태관리 (AttendanceManagement) API 연동 ✅
-- [x] C-3 휴가관리 (VacationManagement) API 연동 ✅
-
-#### Phase D (✅ 완료) - 설정/시스템
-- [x] D-1 부서관리 (DepartmentManagement) API 연동 ✅
-- [x] D-2 직급관리 (RankManagement) API 연동 ✅
-- [x] D-3 직책관리 (TitleManagement) API 연동 ✅
-- [x] D-4 근무시간설정 (WorkScheduleManagement) API 연동 ✅
-
-#### Phase E (✅ 완료) - 인사/급여
-- [x] E-1 급여관리 (SalaryManagement) API 연동 ✅
-- [x] E-2 카드관리 (CardManagement) API 연동 ✅
-
-#### Phase F (✅ 완료) - 결재시스템
-- [x] F-1 기안함 (DraftBox) API 연동 ✅
-- [x] F-2 결재함 (ApprovalBox) API 연동 ✅
-- [x] F-3 참조함 (ReferenceBox) API 연동 ✅
-- [x] F-4 문서작성 (DocumentCreate) API 연동 ✅
-
-#### Phase G (✅ 완료) - 생산관리
-- [x] G-1 작업지시 (WorkOrders) API 연동 ✅
-- [x] G-2 작업실적 (WorkResults) API 연동 ✅
-- [x] G-3 작업자화면 (WorkerScreen) API 연동 ✅
-- [x] G-4 생산현황 (ProductionDashboard) API 연동 ✅
-
-#### Phase H (✅ 완료) - 자재/출하
-- [x] H-1 재고현황 (StockStatus) API 연동 ✅
-- [x] H-2 입고관리 (ReceivingManagement) API 연동 ✅
-- [x] H-3 출하관리 (ShipmentManagement) API 연동 ✅
-
-#### Phase I (✅ 완료) - 판매/견적
-- [x] I-1 수주관리 (Orders) API 연동 ✅
-- [x] I-2 단가관리 (Pricing) API 연동 ✅
-- [x] I-3 견적관리 (Quotes) API 연동 ✅
-
-#### Phase J (✅ 완료) - 회계관리
-- [x] 악성채권, 계좌조회, 어음관리, 카드거래 등 13개 모듈 API 연동 ✅
-
-#### Phase K (✅ 완료) - 보고서
-- [x] K-1 종합분석 (Reports) API 연동 ✅
-
-#### Phase L (🔄 진행중 ~80%) - 건설관리
-**✅ apiClient 표준화 완료:**
-- [x] handover-report (b7b8b90)
-- [x] contract (5db6e59)
-- [x] partners (5db6e59)
-- [x] site-management (5db6e59)
-- [x] order-management (6615f39)
-- [x] item-management (Phase 2.3)
-- [x] pricing-management (Phase L) ✅ 2026-01-09
-- [x] estimates (Phase L) ✅ 2026-01-09
-- [x] category-management (Phase L) ✅ 2026-01-09
-
-**⏳ Mock → API 변환 필요 (Backend API 개발 필요):**
-- [ ] bidding - 입찰관리
-- [ ] site-briefings - 현장설명회
-- [ ] structure-review - 구조검토
-- [ ] labor-management - 노무관리
-
-> **마이그레이션 진행률**: 97% 완료 (41/43 모듈) - 건설관리 4개 모듈 Backend API 개발 필요
-> **점검일**: 2026-01-09
-
-### 다음 작업
-- Phase L 건설관리 모듈 마이그레이션 완료 (Backend API 개발 필요: bidding, site-briefings, structure-review, labor-management)
-- ~~TODO-1: 결재선/참조 Select 변경 불가 문제~~ ✅ 2026-01-09 수정 완료
-
----
+> Mock → API 마이그레이션 진행률: 97% 완료 (41/43 모듈)

Jenkinsfile

@@ -0,0 +1,139 @@
+pipeline {
+    agent any
+
+    options {
+        disableConcurrentBuilds()
+    }
+
+    environment {
+        DEPLOY_USER = 'hskwon'
+        RELEASE_ID  = new Date().format('yyyyMMdd_HHmmss')
+    }
+
+    stages {
+        stage('Checkout') {
+            steps {
+                checkout scm
+                script {
+                    env.GIT_COMMIT_MSG = sh(script: "git log -1 --pretty=format:'%s'", returnStdout: true).trim()
+                }
+                slackSend channel: '#product_infra', color: '#439FE0', tokenCredentialId: 'slack-token',
+                    message: "🚀 *react* 빌드 시작 (`${env.BRANCH_NAME}`)\n${env.GIT_COMMIT_MSG}\n<${env.BUILD_URL}|빌드 #${env.BUILD_NUMBER}>"
+            }
+        }
+
+        stage('Prepare Env') {
+            steps {
+                script {
+                    if (env.BRANCH_NAME == 'main') {
+                        // main: Stage 빌드 먼저 → Production 재빌드
+                        sh "cp /var/lib/jenkins/env-files/react/.env.stage .env.production"
+                    } else {
+                        def envFile = "/var/lib/jenkins/env-files/react/.env.${env.BRANCH_NAME}"
+                        sh "cp ${envFile} .env.production"
+                    }
+                }
+            }
+        }
+
+        stage('Install') {
+            steps { sh 'npm install --prefer-offline' }
+        }
+
+        stage('Build') {
+            steps { sh 'npm run build' }
+        }
+
+        // ── develop → 개발서버 배포 ──
+        stage('Deploy Development') {
+            when { branch 'develop' }
+            steps {
+                sshagent(credentials: ['deploy-ssh-key']) {
+                    sh """
+                        rsync -az --delete \
+                            --exclude='.git' --exclude='.env*' --exclude='ecosystem.config.*' \
+                            .next package.json next.config.ts public node_modules \
+                            ${DEPLOY_USER}@114.203.209.83:/home/webservice/react/
+                        scp .env.production ${DEPLOY_USER}@114.203.209.83:/home/webservice/react/.env.production
+                        ssh ${DEPLOY_USER}@114.203.209.83 'cd /home/webservice/react && pm2 restart sam-react'
+                    """
+                }
+            }
+        }
+
+        // ── main → 운영서버 Stage 배포 ──
+        stage('Deploy Stage') {
+            when { branch 'main' }
+            steps {
+                sshagent(credentials: ['deploy-ssh-key']) {
+                    sh """
+                        ssh ${DEPLOY_USER}@211.117.60.189 'mkdir -p /home/webservice/react-stage/releases/${RELEASE_ID}'
+                        rsync -az --delete \
+                            .next package.json next.config.ts public node_modules \
+                            ${DEPLOY_USER}@211.117.60.189:/home/webservice/react-stage/releases/${RELEASE_ID}/
+                        scp .env.production ${DEPLOY_USER}@211.117.60.189:/home/webservice/react-stage/releases/${RELEASE_ID}/.env.production
+                        ssh ${DEPLOY_USER}@211.117.60.189 '
+                            ln -sfn /home/webservice/react-stage/releases/${RELEASE_ID} /home/webservice/react-stage/current &&
+                            cd /home/webservice && pm2 reload sam-front-stage 2>/dev/null || pm2 start react-stage/current/node_modules/.bin/next --name sam-front-stage -- start -p 3100 &&
+                            cd /home/webservice/react-stage/releases && ls -1dt */ | tail -n +4 | xargs rm -rf 2>/dev/null || true
+                        '
+                    """
+                }
+            }
+        }
+
+        // ── 운영 배포 승인 (런칭 후 활성화) ──
+        // stage('Production Approval') {
+        //     when { branch 'main' }
+        //     steps {
+        //         slackSend channel: '#product_deploy', color: '#FF9800', tokenCredentialId: 'slack-token',
+        //             message: "🔔 *react* 운영 배포 승인 대기 중\n${env.GIT_COMMIT_MSG}\nStage: https://stage.sam.it.kr\n<${env.BUILD_URL}input|승인하러 가기>"
+        //         timeout(time: 24, unit: 'HOURS') {
+        //             input message: 'Stage 확인 후 운영 배포를 진행하시겠습니까?\nStage: https://stage.sam.it.kr',
+        //                   ok: '운영 배포 진행'
+        //         }
+        //     }
+        // }
+
+        // ── main → Production 재빌드 (운영 환경변수) ──
+        stage('Rebuild for Production') {
+            when { branch 'main' }
+            steps {
+                sh "cp /var/lib/jenkins/env-files/react/.env.main .env.production"
+                sh 'npm run build'
+            }
+        }
+
+        // ── main → 운영서버 Production 배포 ──
+        stage('Deploy Production') {
+            when { branch 'main' }
+            steps {
+                sshagent(credentials: ['deploy-ssh-key']) {
+                    sh """
+                        ssh ${DEPLOY_USER}@211.117.60.189 'mkdir -p /home/webservice/react/releases/${RELEASE_ID}'
+                        rsync -az --delete \
+                            .next package.json next.config.ts public node_modules \
+                            ${DEPLOY_USER}@211.117.60.189:/home/webservice/react/releases/${RELEASE_ID}/
+                        scp .env.production ${DEPLOY_USER}@211.117.60.189:/home/webservice/react/releases/${RELEASE_ID}/.env.production
+                        ssh ${DEPLOY_USER}@211.117.60.189 '
+                            ln -sfn /home/webservice/react/releases/${RELEASE_ID} /home/webservice/react/current &&
+                            cd /home/webservice && pm2 reload sam-front &&
+                            cd /home/webservice/react/releases && ls -1dt */ | tail -n +6 | xargs rm -rf 2>/dev/null || true
+                        '
+                    """
+                }
+            }
+        }
+    }
+
+    post {
+        success {
+            slackSend channel: '#product_infra', color: 'good', tokenCredentialId: 'slack-token',
+                message: "✅ *react* 배포 성공 (`${env.BRANCH_NAME}`)\n${env.GIT_COMMIT_MSG}\n<${env.BUILD_URL}|빌드 #${env.BUILD_NUMBER}>"
+        }
+        failure {
+            slackSend channel: '#product_infra', color: 'danger', tokenCredentialId: 'slack-token',
+                message: "❌ *react* 배포 실패 (`${env.BRANCH_NAME}`)\n${env.GIT_COMMIT_MSG}\n<${env.BUILD_URL}|빌드 #${env.BUILD_NUMBER}>"
+        }
+    }
+}

claudedocs/[FIX-2026-02-26] windows-compatibility-checklist.md

@@ -0,0 +1,109 @@
+# Windows 호환성 개선 계획서
+
+> 작성일: 2026-02-26
+> 배경: macOS 개발환경 → Windows 공장 PC 사용자 환경 차이로 인한 이슈
+> 상태: 계획 단계
+
+---
+
+## 완료된 작업
+
+- [x] Popover 계열 컴포넌트 Windows 포커스 이슈 수정 (6개 파일)
+  - `ui/date-picker.tsx` — onPointerDownOutside/onInteractOutside 방어
+  - `ui/time-picker.tsx` — 동일
+  - `ui/date-range-picker.tsx` — 동일
+  - `ui/multi-select-combobox.tsx` — 동일
+  - `ui/searchable-select.tsx` — 동일
+  - `molecules/ColumnSettingsPopover.tsx` — 동일
+- [x] 삭제 버튼 아이콘 X → Trash2 통일 (23개 파일)
+
+---
+
+## Phase 1: IMPORTANT — 사용자 체감 영향 큰 항목
+
+### 1-1. backdrop-filter 성능 최적화
+- **파일**: `src/app/globals.css` (line 269-280)
+- **문제**: `backdrop-filter: blur()` 가 Windows GPU에서 비효율적 → 공장 PC에서 스크롤 버벅거림
+- **영향 범위**: `.clean-glass` 클래스 사용하는 전체 레이아웃 (Sidebar, Login 등)
+- **수정 방향**:
+  - `prefers-reduced-motion` / `prefers-reduced-transparency` 미디어쿼리로 분기
+  - 성능 낮은 환경에서는 `backdrop-filter: none` + 불투명 배경 대체
+- [ ] globals.css `.clean-glass` 수정
+- [ ] 적용된 컴포넌트에서 시각적 변화 확인
+
+### 1-2. 폰트 굵기 렌더링 차이 보정
+- **파일**: `src/app/globals.css` (line 219-235), `src/app/[locale]/layout.tsx` (line 14-19)
+- **문제**: Windows 폰트 렌더링이 macOS보다 ~0.5-1.5 weight 더 굵게 표시 (Pretendard 변수 폰트)
+- **영향 범위**: 전체 UI 텍스트
+- **수정 방향**:
+  - `-webkit-font-smoothing: antialiased` 확인 (이미 적용됨)
+  - `font-weight: 400` 명시적 지정
+  - 필요 시 Windows에서 `font-weight: 350` 적용 검토 (변수 폰트이므로 가능)
+- [ ] 현재 폰트 설정 확인
+- [ ] Windows에서 시각 비교 테스트 후 보정값 결정
+- [ ] globals.css 수정
+
+### 1-3. 스크롤바 동작 차이
+- **파일**: `src/app/globals.css` (line 332-412), `src/layouts/AuthenticatedLayout.tsx` (line 173-197)
+- **문제**: macOS는 스크롤바 자동 숨김, Windows는 항상 표시 → 투명→페이드인 방식이 어색
+- **영향 범위**: 모든 스크롤 가능한 영역
+- **수정 방향**:
+  - 스크롤바 thumb을 기본 살짝 보이게 (`rgba(0,0,0,0.1)`)
+  - `.is-scrolling` 시 진하게 (`rgba(0,0,0,0.2)`) 유지
+  - 너비 8px → 10-12px 로 Windows 기대치에 맞게 조정 검토
+- [ ] globals.css 스크롤바 스타일 수정
+- [ ] Windows에서 시각 확인
+
+### 1-4. 숫자 포맷 locale 명시
+- **파일**: `src/app/[locale]/(protected)/sales/order-management-sales/[id]/edit/page.tsx` (line 65-68)
+- **문제**: `toLocaleString(undefined, ...)` → Windows 지역 설정에 따라 포맷 달라짐
+- **영향 범위**: 해당 페이지 숫자 표시 (다른 곳에도 동일 패턴 있는지 추가 검색 필요)
+- **수정 방향**:
+  - `undefined` → `'ko-KR'` 명시적 locale 지정
+  - 프로젝트 전체에서 동일 패턴 일괄 검색 후 수정
+- [ ] `toLocaleString(undefined` 패턴 전체 검색
+- [ ] locale을 `'ko-KR'`로 일괄 변경
+
+---
+
+## Phase 2: MINOR — 안정성/효율성 개선
+
+### 2-1. number input 스피너 버튼 숨김
+- **파일**: 품질관리 문서 등 `input[type="number"]` 사용처
+- **문제**: Windows에서 ↑↓ 스피너 버튼 표시 → 터치스크린에서 실수 클릭
+- **수정 방향**: 전역 CSS로 스피너 숨김 처리
+- [ ] globals.css에 `input[type="number"]` 스피너 숨김 CSS 추가
+
+### 2-2. 클립보드 API 에러 핸들링
+- **파일**: `src/app/[locale]/(protected)/dev/component-registry/ComponentRegistryClient.tsx` (line 44-48)
+- **문제**: `navigator.clipboard.writeText()` 가 Windows 보안 정책으로 실패 가능
+- **수정 방향**: try-catch + `document.execCommand('copy')` fallback
+- [ ] 클립보드 사용 코드 에러 핸들링 추가
+
+### 2-3. 출퇴근 시계 갱신 주기 최적화
+- **파일**: `src/app/[locale]/(protected)/hr/attendance/page.tsx` (line ~170-180)
+- **문제**: `setInterval(1000)` 매초 갱신 → 공장 PC CPU 부하
+- **수정 방향**: 날짜만 표시하므로 60초 간격으로 변경
+- [ ] setInterval 주기 1초 → 60초로 변경
+
+---
+
+## 테스트 체크리스트
+
+모든 수정 후 Windows 환경에서 확인:
+
+- [ ] DatePicker: Dialog 안에서 날짜 선택 → 값 정상 입력
+- [ ] DatePicker: 이전/다음달 날짜 클릭 → 팝업 유지, 월 이동
+- [ ] TimePicker: Dialog 안에서 시간 선택 → 정상 동작
+- [ ] 스크롤: 메인 레이아웃 + 테이블 스크롤 부드러움 확인
+- [ ] 폰트: 텍스트 두께가 macOS와 비슷한 수준인지 확인
+- [ ] 숫자 포맷: 천단위 구분자, 소수점 정상 표시
+- [ ] number input: 스피너 버튼 안 보이는지 확인
+
+---
+
+## 참고
+
+- Windows 공장 PC 사양: 보통 중저사양 (Intel i3-i5, 8GB RAM, 내장 GPU)
+- 브라우저: Chrome 또는 Edge (Chromium 기반)
+- 터치스크린 사용 가능성 있음

claudedocs/[PLAN-2025-01-20] permission-system-implementation.md

@@ -1,979 +0,0 @@
-# 권한 시스템 구현 계획서
-
-> 작성일: 2025-01-20
-> 최종 수정: 2026-01-21
-> 상태: 계획 완료 (구현 대기)
-
----
-
-## 📊 전체 페이지 분석 결과 (2026-01-21 추가)
-
-### 핵심 통계
-
-| 구분 | 수량 | 비고 |
-|------|------|------|
-| **전체 Protected 페이지** | 206개 | src/app/[locale]/(protected) |
-| **템플릿 자동 적용 가능** | 165개+ | 템플릿 2개 수정으로 해결 |
-| **개별 작업 필요 페이지** | 41개 | 수동 권한 적용 |
-| **Config 파일** | 46개 | menuCode 추가 필요 |
-
-### 템플릿 사용 현황
-
-| 템플릿 | 사용 컴포넌트 수 | 적용 방식 |
-|--------|-----------------|----------|
-| **UniversalListPage** (리스트) | 64개 | 자동 (템플릿 수정) |
-| **IntegratedDetailTemplate** (상세/폼) | 101개+ | 자동 (템플릿 수정) |
-| **직접 구현** | 41개 | 수동 (usePermission 적용) |
-
-### 효율성 분석
-
-```
-✅ 템플릿 2개 수정 = 165개+ 페이지 자동 권한 적용 (80%)
-⚠️ 개별 41개 페이지 = 수동 작업 필요 (20%)
-🎯 ROI: 템플릿 2개 → 165개 페이지 = 82.5배 효율
-```
-
----
-
-## 📈 공통화/추상화 효율 분석 (2026-01-23 추가)
-
-### 측정 관점 차이 설명
-
-| 구분 | page.tsx 레벨 | 컴포넌트 레벨 | 설명 |
-|------|--------------|--------------|------|
-| **측정 대상** | page.tsx 파일 | 도메인 컴포넌트 | 관점 차이 |
-| **UniversalListPage** | 4개 페이지 | 64개 컴포넌트 | 컴포넌트가 템플릿 사용 |
-| **IntegratedDetailTemplate** | 18개 페이지 | 101개 컴포넌트 | 컴포넌트가 템플릿 사용 |
-| **직접 사용률** | 12.1% | 80% | 컴포넌트 레벨이 실제 효율 |
-
-**구조:**
-```
-page.tsx (207개) → 도메인 컴포넌트 (165개+) → 템플릿 (2개)
-                   ↑                         ↑
-                 여기서 렌더링            여기서 권한 적용
-```
-
-### 공통화 수준 평가
-
-| 단계 | 항목 | 달성도 | 상태 |
-|------|------|--------|------|
-| Level 1 | 공통 UI 컴포넌트 (52개) | 80% | ✅ 양호 |
-| Level 2 | 계층 구조 (Atomic Design) | 40% | 🟡 부분 |
-| Level 3 | 템플릿/레이아웃 | 30% | 🟡 부분 |
-| Level 4 | Config 기반 구현 | 25% | 🟡 미흡 |
-| Level 5 | 권한 자동화 | 10% | 🔴 미흡 |
-
-**종합 공통화 수준: 약 35-40%**
-
-### 권한 적용 전략 비교
-
-| 전략 | 자동 적용 | 수동 적용 | 효율 |
-|------|----------|----------|------|
-| page.tsx 레벨 분석 | 22개 (10.6%) | 185개 (89.4%) | 🔴 낮음 |
-| **컴포넌트 레벨 분석** | **165개+ (80%)** | **41개 (20%)** | ✅ 높음 |
-
-### 권한 적용 구조도
-
-```
-┌─────────────────────────────────────────────────────┐
-│                 전체 207개 페이지                    │
-├─────────────────────────────────────────────────────┤
-│  ┌─────────────────────────────────────────────┐   │
-│  │     템플릿 사용 컴포넌트 경유 (165개+)        │   │
-│  │  ┌───────────────┐ ┌───────────────────┐   │   │
-│  │  │ UniversalList │ │ IntegratedDetail  │   │   │
-│  │  │   Page (64)   │ │   Template (101)  │   │   │
-│  │  └───────────────┘ └───────────────────┘   │   │
-│  │              ↓                              │   │
-│  │      Config에 menuCode 추가                 │   │
-│  │              ↓                              │   │
-│  │      ✅ 자동 권한 적용 (80%)                 │   │
-│  └─────────────────────────────────────────────┘   │
-│                                                     │
-│  ┌─────────────────────────────────────────────┐   │
-│  │      특수 페이지 (41개)                       │   │
-│  │  대시보드, 설정, 전자결재, QMS 등             │   │
-│  │              ↓                              │   │
-│  │      usePermission 훅 직접 적용              │   │
-│  │              ↓                              │   │
-│  │      ⚠️ 수동 권한 적용 (20%)                 │   │
-│  └─────────────────────────────────────────────┘   │
-└─────────────────────────────────────────────────────┘
-```
-
-### 최종 결론
-
-| 항목 | 수치 | 비고 |
-|------|------|------|
-| 공통화 수준 | 35-40% | 잠재력 높음 |
-| 권한 자동 적용 | 80% (165개+ 컴포넌트) | Config + 템플릿 |
-| 권한 수동 적용 | 20% (41개 특수 페이지) | usePermission |
-| Config 수정 | 47개 파일 | menuCode 추가 |
-| 템플릿 수정 | 2개 파일 | 권한 체크 로직 |
-
-**권한 시스템은 계획서대로 진행 가능:**
-- 템플릿 2개 수정 → 165개+ 컴포넌트 자동 적용
-- 41개 특수 페이지만 개별 작업
-
----
-
-## 0. 확정 사항 (2025-01-21)
-
-| 항목 | 결정 |
-|------|------|
-| 백엔드 API | ✅ 기존 `/api/v1/permissions/users/{userId}/menu-matrix` 활용 |
-| 추가 API 필요 | ❌ 불필요 |
-| 캐싱 전략 | 로그인 시 1회 로드 |
-| 권한 반영 시점 | 재로그인 시 적용 |
-| 선행 조건 | 페이지 통합 작업 완료 후 진행 |
-
----
-
-## 1. 현재 상태 분석
-
-### 1.1 구현 완료 항목
-
-| 구분 | 상태 | 위치 |
-|------|------|------|
-| 역할(Role) CRUD | ✅ | `/settings/permissions` |
-| 권한 매트릭스 UI | ✅ | `PermissionDetailClient.tsx` |
-| 권한 타입 정의 | ✅ | `types.ts` |
-| 메뉴 트리 API | ✅ | `GET /api/v1/role-permissions/menus` |
-| 권한 토글 API | ✅ | `POST /api/v1/roles/{id}/permissions/toggle` |
-
-### 1.2 미구현 항목
-
-| 구분 | 필요성 | 우선순위 | 비고 |
-|------|--------|----------|------|
-| ~~현재 사용자 권한 조회 API~~ | ~~필수~~ | ~~🔴 높음~~ | ✅ 기존 API 활용 |
-| PermissionContext/Provider | 필수 | 🔴 높음 | |
-| usePermission 훅 | 필수 | 🔴 높음 | |
-| PermissionGuard 컴포넌트 | 필수 | 🟡 중간 | |
-| Config에 권한 정보 추가 | 필수 | 🟡 중간 | |
-| AccessDenied 페이지 | 권장 | 🟢 낮음 | |
-
----
-
-## 2. 권한 데이터 구조
-
-### 2.1 권한 타입 (7가지)
-
-```typescript
-type PermissionType = 'view' | 'create' | 'update' | 'delete' | 'approve' | 'export' | 'manage';
-
-const PERMISSION_LABELS: Record<PermissionType, string> = {
-  view: '조회',
-  create: '생성',
-  update: '수정',
-  delete: '삭제',
-  approve: '승인',
-  export: '내보내기',
-  manage: '관리',
-};
-```
-
-### 2.2 권한 매트릭스 구조
-
-```typescript
-interface UserPermissions {
-  role: {
-    id: number;
-    name: string;
-  };
-  permissions: {
-    [menuCode: string]: {
-      view?: boolean;
-      create?: boolean;
-      update?: boolean;
-      delete?: boolean;
-      approve?: boolean;
-      export?: boolean;
-      manage?: boolean;
-    };
-  };
-}
-```
-
-### 2.3 메뉴 트리 구조
-
-```typescript
-interface MenuTreeItem {
-  id: number;
-  name: string;
-  code: string;           // 권한 체크 시 사용되는 키
-  parent_id: number | null;
-  depth: number;
-  sort_order: number;
-  children?: MenuTreeItem[];
-}
-```
-
----
-
-## 3. 구현 계획
-
-### Phase 1: 기반 구조 (✅ 백엔드 준비 완료)
-
-#### 3.1.1 사용할 API
-
-**기존 API 활용:**
-```
-GET /api/v1/permissions/users/{userId}/menu-matrix
-
-Response:
-{
-  "success": true,
-  "data": {
-    "actions": ["view", "create", "update", "delete", "approve"],
-    "tree": [
-      {
-        "menu_id": 1,
-        "parent_id": null,
-        "name": "수주관리",
-        "url": "/sales/order-management",
-        "type": "system",
-        "children": [...],
-        "actions": {
-          "view": { "permission_id": 123, "state": "allow", "is_allowed": 1 },
-          "create": { "permission_id": 124, "state": "allow", "is_allowed": 1 },
-          "update": { "permission_id": 125, "state": "deny", "is_allowed": 0 },
-          "delete": { "permission_id": 126, "state": "none", "is_allowed": 0 },
-          "approve": { "permission_id": 127, "state": "allow", "is_allowed": 1 }
-        }
-      }
-    ]
-  }
-}
-```
-
-**프론트엔드 변환 필요:**
-- 트리 구조 → flat 권한 객체로 변환
-- url 기반으로 menuCode 추출 (예: `/sales/order-management` → `order-management`)
-
-#### 3.1.2 파일 구조
-
-```
-src/
-├── contexts/
-│   └── PermissionContext.tsx    # 권한 Context + Provider
-├── hooks/
-│   └── usePermission.ts         # 권한 체크 훅
-└── lib/
-    └── permissions/
-        ├── types.ts             # 권한 관련 타입
-        └── actions.ts           # 권한 조회 Server Action
-```
-
-#### 3.1.3 PermissionContext 설계
-
-```typescript
-// src/contexts/PermissionContext.tsx
-
-interface PermissionContextType {
-  permissions: UserPermissions | null;
-  isLoading: boolean;
-  error: string | null;
-  can: (menuCode: string, action: PermissionType) => boolean;
-  canAny: (menuCode: string, actions: PermissionType[]) => boolean;
-  canAll: (menuCode: string, actions: PermissionType[]) => boolean;
-  refresh: () => Promise<void>;
-}
-```
-
-#### 3.1.4 usePermission 훅 설계
-
-```typescript
-// src/hooks/usePermission.ts
-
-interface UsePermissionReturn {
-  canView: boolean;
-  canCreate: boolean;
-  canUpdate: boolean;
-  canDelete: boolean;
-  canApprove: boolean;
-  canExport: boolean;
-  canManage: boolean;
-  isLoading: boolean;
-}
-
-function usePermission(menuCode: string): UsePermissionReturn;
-
-// 사용 예시
-const { canView, canCreate, canUpdate, canDelete } = usePermission('order-management');
-```
-
----
-
-### Phase 2: Config 확장
-
-#### 3.2.1 DetailConfig 타입 확장
-
-```typescript
-// src/components/templates/IntegratedDetailTemplate/types.ts
-
-interface PermissionConfig {
-  menuCode: string;              // 메뉴 코드 (API와 매핑)
-  requiredAction?: PermissionType; // 페이지 접근에 필요한 최소 권한 (기본: 'view')
-}
-
-interface DetailConfig {
-  title: string;
-  description: string;
-  icon: LucideIcon;
-  basePath: string;
-  fields: FieldConfig[];
-  actions: ActionConfig;
-  permission?: PermissionConfig;  // 🆕 추가
-}
-```
-
-#### 3.2.2 Config 파일 업데이트 예시
-
-**수정 전:**
-```typescript
-export const orderCreateConfig: DetailConfig = {
-  title: '수주 등록',
-  basePath: '/sales/order-management',
-  // ...
-};
-```
-
-**수정 후:**
-```typescript
-export const orderCreateConfig: DetailConfig = {
-  title: '수주 등록',
-  basePath: '/sales/order-management',
-  permission: {
-    menuCode: 'order-management',
-    requiredAction: 'create',
-  },
-  // ...
-};
-```
-
-#### 3.2.3 업데이트 대상 Config 파일 (46개)
-
-| 카테고리 | 수량 | Config 파일 |
-|---------|------|-------------|
-| **회계 (Accounting)** | 8개 | badDebtConfig, billConfig, depositDetailConfig, purchaseConfig, salesConfig, vendorConfig, vendorLedgerConfig, withdrawalDetailConfig |
-| **건설 (Construction)** | 15개 | biddingConfig, contractConfig, estimateConfig, handoverReportConfig, issueConfig, itemConfig, laborDetailConfig, constructionConfig, orderConfig, partnerConfig, pricingDetailConfig, progressBillingConfig, siteBriefingConfig, siteConfig, structureReviewConfig |
-| **고객/클라이언트** | 2개 | clientConfig, clientDetailConfig |
-| **고객센터** | 3개 | eventConfig, inquiryConfig, noticeConfig |
-| **HR** | 2개 | cardConfig, employeeConfig |
-| **자재** | 2개 | receivingConfig, stockStatusConfig |
-| **주문** | 2개 | orderConfig, orderSalesConfig |
-| **생산** | 1개 | workOrderConfig |
-| **프로세스** | 1개 | processConfig |
-| **품질** | 1개 | inspectionConfig |
-| **견적** | 2개 | quoteConfig, quoteRegistrationConfig |
-| **설정** | 3개 | accountConfig, permissionConfig, popupDetailConfig |
-| **유통** | 1개 | shipmentConfig |
-| **게시판** | 1개 | boardFormConfig |
-| **전자결재** | 1개 | documentCreateConfig |
-| **기타** | 1개 | importInspectionConfig |
-
-**Config 파일 전체 경로:**
-```
-src/components/
-├── accounting/
-│   ├── BadDebtCollection/badDebtConfig.ts
-│   ├── BillManagement/billConfig.ts
-│   ├── DepositManagement/depositDetailConfig.ts
-│   ├── PurchaseManagement/purchaseConfig.ts
-│   ├── SalesManagement/salesConfig.ts
-│   ├── VendorLedger/vendorLedgerConfig.ts
-│   ├── VendorManagement/vendorConfig.ts
-│   └── WithdrawalManagement/withdrawalDetailConfig.ts
-├── approval/
-│   └── DocumentCreate/documentCreateConfig.ts
-├── board/
-│   └── BoardForm/boardFormConfig.ts
-├── business/construction/
-│   ├── bidding/biddingConfig.ts
-│   ├── contract/contractConfig.ts
-│   ├── estimates/estimateConfig.ts
-│   ├── handover-report/handoverReportConfig.ts
-│   ├── issue-management/issueConfig.ts
-│   ├── item-management/itemConfig.ts
-│   ├── labor-management/laborDetailConfig.ts
-│   ├── management/constructionConfig.ts
-│   ├── order-management/orderConfig.ts
-│   ├── partners/partnerConfig.ts
-│   ├── pricing-management/pricingDetailConfig.ts
-│   ├── progress-billing/progressBillingConfig.ts
-│   ├── site-briefings/siteBriefingConfig.ts
-│   ├── site-management/siteConfig.ts
-│   └── structure-review/structureReviewConfig.ts
-├── clients/
-│   ├── clientConfig.ts
-│   └── clientDetailConfig.ts
-├── customer-center/
-│   ├── EventManagement/eventConfig.ts
-│   ├── InquiryManagement/inquiryConfig.ts
-│   └── NoticeManagement/noticeConfig.ts
-├── hr/
-│   ├── CardManagement/cardConfig.ts
-│   └── EmployeeManagement/employeeConfig.ts
-├── material/
-│   ├── ReceivingManagement/receivingConfig.ts
-│   ├── ReceivingManagement/inspectionConfig.ts (importInspectionConfig)
-│   └── StockStatus/stockStatusConfig.ts
-├── orders/
-│   ├── orderConfig.ts
-│   └── orderSalesConfig.ts
-├── outbound/
-│   └── ShipmentManagement/shipmentConfig.ts
-├── process-management/
-│   └── processConfig.ts
-├── production/
-│   └── WorkOrders/workOrderConfig.ts
-├── quality/
-│   └── InspectionManagement/inspectionConfig.ts
-├── quotes/
-│   ├── quoteConfig.ts
-│   └── quoteRegistrationConfig.ts
-└── settings/
-    ├── AccountManagement/accountConfig.ts
-    ├── PermissionManagement/permissionConfig.ts
-    └── PopupManagement/popupDetailConfig.ts
-```
-
----
-
-### Phase 3: 공통 컴포넌트
-
-#### 3.3.1 PermissionGuard 컴포넌트
-
-```typescript
-// src/components/common/PermissionGuard.tsx
-
-interface PermissionGuardProps {
-  menuCode: string;
-  action: PermissionType;
-  fallback?: React.ReactNode;  // 권한 없을 때 대체 UI
-  children: React.ReactNode;
-}
-
-// 사용 예시
-<PermissionGuard menuCode="order-management" action="delete">
-  <Button variant="destructive">삭제</Button>
-</PermissionGuard>
-
-<PermissionGuard
-  menuCode="order-management"
-  action="update"
-  fallback={<ReadOnlyView />}
->
-  <EditForm />
-</PermissionGuard>
-```
-
-#### 3.3.2 AccessDenied 페이지
-
-```typescript
-// src/components/common/AccessDenied.tsx
-
-interface AccessDeniedProps {
-  title?: string;
-  description?: string;
-  showBackButton?: boolean;
-}
-
-// 기본 메시지: "접근 권한이 없습니다"
-```
-
-#### 3.3.3 파일 구조
-
-```
-src/components/common/
-├── PermissionGuard.tsx      # 권한 기반 조건부 렌더링
-├── AccessDenied.tsx         # 접근 거부 페이지
-└── index.ts                 # export
-```
-
----
-
-### Phase 4: 페이지별 적용
-
-#### 3.4.1 IntegratedDetailTemplate 수정
-
-```typescript
-// 템플릿 내부에서 자동 권한 체크
-function IntegratedDetailTemplate({ config, ...props }) {
-  const menuCode = config.permission?.menuCode;
-  const { canView, canCreate, canUpdate, canDelete } = usePermission(menuCode || '');
-
-  // 페이지 접근 권한 체크
-  if (menuCode && !canView) {
-    return <AccessDenied />;
-  }
-
-  // 버튼 자동 숨김
-  const effectiveActions = {
-    ...config.actions,
-    showSave: config.actions.showSave && (mode === 'create' ? canCreate : canUpdate),
-    showDelete: config.actions.showDelete && canDelete,
-  };
-
-  return (
-    // ... 기존 렌더링
-  );
-}
-```
-
-#### 3.4.2 UniversalListPage 수정
-
-```typescript
-// 리스트 템플릿 내부에서 자동 권한 체크
-function UniversalListPage({ config, ...props }) {
-  const menuCode = config.permission?.menuCode;
-  const { canView, canCreate, canUpdate, canDelete } = usePermission(menuCode || '');
-
-  // 페이지 접근 권한 체크
-  if (menuCode && !canView) {
-    return <AccessDenied />;
-  }
-
-  // 버튼 자동 숨김
-  const showCreateButton = config.showCreateButton && canCreate;
-  const showDeleteButton = config.showDeleteButton && canDelete;
-  const showEditAction = canUpdate;
-
-  return (
-    // ... 기존 렌더링
-  );
-}
-```
-
-#### 3.4.3 적용 방식
-
-| 방식 | 적용 위치 | 제어 수준 | 비율 |
-|------|----------|----------|------|
-| **자동** | IntegratedDetailTemplate | Config 기반 | ~49% (101개) |
-| **자동** | UniversalListPage | Config 기반 | ~31% (64개) |
-| **수동** | 개별 컴포넌트 | usePermission 훅 | ~20% (41개) |
-
-#### 3.4.4 개별 작업 필요 페이지 목록 (41개)
-
-##### 우선순위 1 - HIGH (8개)
-
-| 페이지 | 경로 | 복잡도 | 작업 내용 |
-|--------|------|--------|----------|
-| 대시보드 | `/dashboard` | 🟡 중간 | 역할별 위젯 필터링 |
-| 생산 대시보드 | `/production/dashboard` | 🟡 중간 | 생산 권한 기반 위젯 |
-| 계정정보 | `/settings/account-info` | 🟢 낮음 | 사용자 정보 접근 권한 |
-| 출퇴근설정 | `/settings/attendance-settings` | 🟢 낮음 | 관리자 권한 체크 |
-| 휴가정책 | `/settings/leave-policy` | 🟢 낮음 | HR 권한 체크 |
-| 직급관리 | `/settings/ranks` | 🟢 낮음 | 관리자 권한 체크 |
-| 직책관리 | `/settings/titles` | 🟢 낮음 | 관리자 권한 체크 |
-| 근무일정 | `/settings/work-schedule` | 🟢 낮음 | 관리자 권한 체크 |
-
-##### 우선순위 2 - MEDIUM (15개)
-
-| 페이지 | 경로 | 복잡도 | 작업 내용 |
-|--------|------|--------|----------|
-| 기안작성 | `/approval/draft/new` | 🟡 중간 | 결재 권한 |
-| 결재함 | `/approval/inbox` | 🟡 중간 | 결재자 권한 |
-| 참조함 | `/approval/reference` | 🟢 낮음 | 참조 권한 |
-| 게시글 작성 | `/board/create` | 🟢 낮음 | 게시판 권한 |
-| 게시글 상세 | `/boards/[boardCode]/[postId]` | 🟡 중간 | 작성자/관리자 권한 |
-| 부서관리 | `/hr/department-management` | 🟡 중간 | HR 권한 (트리 구조) |
-| 품목기준관리 | `/master-data/item-master-data-management` | 🟢 낮음 | 데이터 조회 권한 |
-| 공정관리 | `/master-data/process-management` | 🟢 낮음 | 데이터 조회 권한 |
-| FAQ | `/customer-center/faq` | 🟢 낮음 | 조회 권한 (아코디언) |
-| 1:1 문의 | `/customer-center/qna` | 🟢 낮음 | 문의 권한 |
-| 회사정보 | `/company-info` | 🟢 낮음 | 테넌트 마스터 권한 |
-| 구독관리 | `/subscription` | 🟢 낮음 | 테넌트 마스터 권한 |
-| 결제내역 | `/payment-history` | 🟢 낮음 | 결제 조회 권한 |
-| 알림설정 | `/settings/notification-settings` | 🟢 낮음 | 사용자 설정 |
-| 공과관리 | `/construction/project/utility-management` | 🟢 낮음 | 건설 권한 |
-
-##### 우선순위 3 - LOW (18개)
-
-| 페이지 | 경로 | 복잡도 | 작업 내용 |
-|--------|------|--------|----------|
-| QMS | `/quality/qms` | 🔴 높음 | 복잡한 상태 관리 |
-| 종합경영분석 | `/reports/comprehensive-analysis` | 🟡 중간 | 보고서 조회 권한 |
-| 보고서 메인 | `/reports` | 🟢 낮음 | 보고서 접근 권한 |
-| 모바일 출퇴근 | `/hr/attendance` | 🟢 낮음 | 사용자 본인 권한 |
-| 일일 일보 | `/accounting/daily-report` | 🟢 낮음 | 조회 권한 |
-| 미수금 현황 | `/accounting/receivables-status` | 🟢 낮음 | 조회 권한 |
-| 작업인력현황 | `/construction/project/worker-status` | 🟢 낮음 | 건설 권한 |
-| 카테고리관리 | `/construction/order/base-info/categories` | 🟢 낮음 | 건설 기준정보 |
-| 건설 대시보드 | `/construction/dashboard` | 🟡 중간 | 건설 권한 |
-| dev 페이지들 | `/dev/*` | 🟢 낮음 | 개발용 (권한 제외 가능) |
-| Catch-all | `/[...slug]` | 🟢 낮음 | 동적 라우트 |
-| 동적 게시판들 | `/boards/[boardCode]/*` | 🟡 중간 | 동적 권한 |
-| 기타 | 나머지 | 🟢 낮음 | 단순 권한 체크 |
-
-#### 3.4.5 수동 적용 코드 패턴
-
-```typescript
-'use client';
-import { usePermission } from '@/hooks/usePermission';
-import { AccessDenied } from '@/components/common/AccessDenied';
-
-export default function MyPage() {
-  const { canView, canCreate, canUpdate, canDelete, isLoading } = usePermission('MENU_CODE');
-
-  if (isLoading) {
-    return <div>로딩 중...</div>;
-  }
-
-  if (!canView) {
-    return <AccessDenied />;
-  }
-
-  return (
-    <div>
-      {canCreate && <CreateButton />}
-      {canUpdate && <EditButton />}
-      {canDelete && <DeleteButton />}
-    </div>
-  );
-}
-```
-
-#### 3.4.6 수동 적용이 필요한 이유
-
-- 특수 권한 로직 (승인 워크플로우 등)
-- 조건부 필드 표시/숨김
-- 복합 권한 체크 (여러 메뉴 권한 조합)
-- 목록 페이지의 행 단위 권한
-- 템플릿을 사용하지 않는 특수 UI (트리, 아코디언, 대시보드)
-
----
-
-## 4. 메뉴 코드 매핑 규칙
-
-### 4.1 URL → 메뉴 코드 매핑
-
-| URL 패턴 | 메뉴 코드 (예상) |
-|----------|-----------------|
-| `/sales/order-management` | `order-management` |
-| `/sales/client-management` | `client-management` |
-| `/sales/quote-management` | `quote-management` |
-| `/hr/employee-management` | `employee-management` |
-| `/settings/permissions` | `permission-management` |
-
-### 4.2 확인 필요 사항
-
-- [ ] 백엔드 메뉴 트리의 `code` 값 목록 확인
-- [ ] URL과 메뉴 코드 매핑 규칙 확정
-- [ ] 하위 메뉴 권한 상속 규칙 확인
-
----
-
-## 5. 권한 캐싱 전략 (✅ 확정)
-
-### 5.1 확정된 전략: 로그인 시 1회 로드
-
-| 항목 | 내용 |
-|------|------|
-| 전략 | 로그인 시 1회 로드 |
-| 권한 반영 시점 | 재로그인 시 적용 |
-| API 호출 | 최소 (로그인 시 1회) |
-| 성능 | 좋음 |
-
-**선택 이유:**
-- 권한 부여 전까지는 아무것도 할 수 없음
-- 권한 변경은 자주 발생하지 않음
-- 재로그인으로 변경된 권한 적용 (사용자 혼란 없음)
-
-### 5.2 구현 코드
-
-```typescript
-// 로그인 성공 시 권한 로드
-const PermissionProvider = ({ children }) => {
-  const { user, isAuthenticated } = useAuth();
-  const [permissions, setPermissions] = useState(null);
-  const [isLoading, setIsLoading] = useState(true);
-
-  useEffect(() => {
-    if (isAuthenticated && user?.id) {
-      loadPermissions(user.id);
-    }
-  }, [isAuthenticated, user?.id]);
-
-  const loadPermissions = async (userId: number) => {
-    setIsLoading(true);
-    const result = await getMyPermissions(userId);
-    if (result.success) {
-      setPermissions(transformToFlatPermissions(result.data));
-    }
-    setIsLoading(false);
-  };
-
-  return (
-    <PermissionContext.Provider value={{ permissions, isLoading }}>
-      {children}
-    </PermissionContext.Provider>
-  );
-};
-```
-
----
-
-## 6. 구현 체크리스트
-
-### Phase 1: 기반 구조 (파일 6개)
-- [x] ~~백엔드에 `/api/v1/my-permissions` API 요청~~ → 기존 API 활용 (2025-01-21 확인)
-- [ ] `src/lib/permissions/types.ts` 생성
-- [ ] `src/lib/permissions/actions.ts` 생성 (Server Action)
-- [ ] `src/lib/permissions/utils.ts` 생성 (트리→flat 변환 유틸)
-- [ ] `src/contexts/PermissionContext.tsx` 생성
-- [ ] `src/hooks/usePermission.ts` 생성
-- [ ] RootProvider에 PermissionProvider 추가
-
-### Phase 2: Config 확장 (파일 48개)
-- [ ] `DetailConfig` 타입에 `permission` 필드 추가
-- [ ] `ListConfig` 타입에 `permission` 필드 추가 (UniversalListPage용)
-- [ ] **46개 Config 파일**에 `menuCode` 추가
-  - [ ] 회계 (8개): badDebtConfig, billConfig, depositDetailConfig, purchaseConfig, salesConfig, vendorConfig, vendorLedgerConfig, withdrawalDetailConfig
-  - [ ] 건설 (15개): biddingConfig, contractConfig, estimateConfig, handoverReportConfig, issueConfig, itemConfig, laborDetailConfig, constructionConfig, orderConfig, partnerConfig, pricingDetailConfig, progressBillingConfig, siteBriefingConfig, siteConfig, structureReviewConfig
-  - [ ] 기타 (23개): 나머지 Config 파일
-
-### Phase 3: 공통 컴포넌트 (파일 2개)
-- [ ] `PermissionGuard` 컴포넌트 생성
-- [ ] `AccessDenied` 페이지 생성
-
-### Phase 4-A: 템플릿 수정 (파일 2개 → 165개+ 페이지 자동 적용)
-- [ ] `IntegratedDetailTemplate`에 자동 권한 체크 추가 (101개+ 페이지)
-- [ ] `UniversalListPage`에 자동 권한 체크 추가 (64개 페이지)
-
-### Phase 4-B: 개별 페이지 수동 적용 (41개 페이지)
-- [ ] **우선순위 1 - HIGH (8개)**: 대시보드, 설정 페이지
-- [ ] **우선순위 2 - MEDIUM (15개)**: 전자결재, 게시판, 마스터데이터
-- [ ] **우선순위 3 - LOW (18개)**: QMS, 보고서, 기타
-
----
-
-## 7. 예상 작업량
-
-### 7.1 Phase별 작업량
-
-| Phase | 작업 | 파일 수 | 영향 페이지 | 난이도 |
-|-------|------|--------|-----------|--------|
-| **1** | 기반 구조 | 6개 신규 | 전체 | 🟡 중간 |
-| **2** | Config 확장 | 48개 수정 | 템플릿 사용 페이지 | 🟢 낮음 (반복 작업) |
-| **3** | 공통 컴포넌트 | 2개 신규 | 전체 | 🟢 낮음 |
-| **4-A** | 템플릿 수정 | 2개 수정 | **165개+ 자동** | 🟡 중간 |
-| **4-B** | 개별 페이지 | 41개 수정 | 41개 | 🟡~🔴 |
-
-### 7.2 개별 페이지 작업량 상세
-
-| 우선순위 | 페이지 수 | 복잡도 | 작업 내용 |
-|---------|----------|--------|----------|
-| **HIGH** | 8개 | 🟢~🟡 | 대시보드 위젯 필터링, 설정 권한 체크 |
-| **MEDIUM** | 15개 | 🟢~🟡 | 전자결재, 게시판, 마스터데이터 권한 |
-| **LOW** | 18개 | 🟢~🔴 | QMS(복잡), 보고서, 기타 페이지 |
-
-### 7.3 총 작업량 요약
-
-```
-📁 신규 파일: 8개 (Phase 1: 6개, Phase 3: 2개)
-✏️ 수정 파일: 91개 (Config 48개 + 템플릿 2개 + 개별 41개)
-📄 영향 페이지: 206개 전체
-
-🎯 효율성:
-- 템플릿 2개 수정 → 165개+ 페이지 자동 적용 (82.5배 효율)
-- 총 99개 파일 수정 → 206개 페이지 보호 (2.1배 효율)
-```
-
----
-
-## 8. 의존성 및 선행 조건
-
-### 8.1 백엔드 의존성
-- [x] ~~`/api/v1/my-permissions` API 구현 필요~~ → 기존 API 활용 (✅ 해결)
-- 사용 API: `GET /api/v1/permissions/users/{userId}/menu-matrix`
-
-### 8.2 프론트엔드 의존성
-- Phase 1 → Phase 2 → Phase 3 → Phase 4 순서 준수
-- **선행 조건**: 페이지 통합 작업 완료 후 진행
-
----
-
-## 9. 참고 파일 위치
-
-| 구분 | 파일 경로 |
-|------|----------|
-| 권한 타입 | `src/components/settings/PermissionManagement/types.ts` |
-| 권한 API | `src/components/settings/PermissionManagement/actions.ts` |
-| 권한 매트릭스 UI | `src/components/settings/PermissionManagement/PermissionDetailClient.tsx` |
-| AuthContext | `src/contexts/AuthContext.tsx` |
-| 메뉴 스토어 | `src/store/menuStore.ts` |
-| DetailConfig 타입 | `src/components/templates/IntegratedDetailTemplate/types.ts` |
-| UniversalListPage | `src/components/templates/UniversalListPage/index.tsx` |
-
----
-
-## 10. 템플릿 사용 컴포넌트 상세 목록 (2026-01-21 추가)
-
-### 10.1 UniversalListPage 사용 컴포넌트 (64개)
-
-#### 회계 (Accounting) - 13개
-```
-- BadDebtCollection/index.tsx
-- BillManagement/index.tsx, BillManagementClient.tsx
-- DepositManagement/index.tsx
-- ExpectedExpenseManagement/index.tsx
-- PurchaseManagement/index.tsx
-- SalesManagement/index.tsx
-- VendorLedger/index.tsx
-- VendorManagement/index.tsx, VendorManagementClient.tsx
-- WithdrawalManagement/index.tsx
-- BankTransactionInquiry/index.tsx
-- CardTransactionInquiry/index.tsx
-```
-
-#### HR - 5개
-```
-- AttendanceManagement/index.tsx
-- CardManagement/index.tsx, CardManagementUnified.tsx
-- EmployeeManagement/index.tsx
-- SalaryManagement/index.tsx
-- VacationManagement/index.tsx
-```
-
-#### 건설 (Construction) - 17개
-```
-- bidding/BiddingListClient.tsx
-- contract/ContractListClient.tsx
-- estimates/EstimateListClient.tsx
-- handover-report/HandoverReportListClient.tsx
-- issue-management/IssueManagementListClient.tsx
-- item-management/ItemManagementClient.tsx
-- labor-management/LaborManagementClient.tsx
-- management/ConstructionManagementListClient.tsx
-- order-management/OrderManagementListClient.tsx, OrderManagementUnified.tsx
-- partners/PartnerListClient.tsx
-- pricing-management/PricingListClient.tsx
-- progress-billing/ProgressBillingManagementListClient.tsx
-- site-briefings/SiteBriefingListClient.tsx
-- site-management/SiteManagementListClient.tsx
-- structure-review/StructureReviewListClient.tsx
-- utility-management/UtilityManagementListClient.tsx
-- worker-status/WorkerStatusListClient.tsx
-```
-
-#### 자재/생산/품질/유통 - 7개
-```
-- material/StockStatus/StockStatusList.tsx
-- material/ReceivingManagement/ReceivingList.tsx
-- production/WorkOrders/WorkOrderList.tsx
-- production/WorkResults/WorkResultList.tsx
-- quality/InspectionManagement/InspectionList.tsx
-- outbound/ShipmentManagement/ShipmentList.tsx
-```
-
-#### 기타 - 22개
-```
-- pricing/PricingListClient.tsx
-- process-management/ProcessListClient.tsx
-- items/ItemListClient.tsx
-- quotes/QuoteManagementClient.tsx
-- settings/PermissionManagement/index.tsx
-- settings/AccountManagement/index.tsx
-- settings/PaymentHistoryManagement/index.tsx, PaymentHistoryClient.tsx
-- settings/PopupManagement/PopupList.tsx
-- board/BoardList/index.tsx, BoardListUnified.tsx
-- board/BoardManagement/index.tsx
-- customer-center/NoticeManagement/NoticeList.tsx
-- customer-center/EventManagement/EventList.tsx
-- customer-center/InquiryManagement/InquiryList.tsx
-- approval/ApprovalBox/index.tsx
-- approval/DraftBox/index.tsx
-- approval/ReferenceBox/index.tsx
-```
-
-### 10.2 IntegratedDetailTemplate 사용 컴포넌트 (101개+)
-
-#### 회계 (Accounting) - 19개
-```
-- BadDebtCollection/BadDebtDetail.tsx
-- BillManagement/BillDetail.tsx
-- DepositManagement/DepositDetailClientV2.tsx
-- PurchaseManagement/PurchaseDetail.tsx
-- SalesManagement/SalesDetail.tsx
-- VendorLedger/VendorLedgerDetail.tsx
-- VendorManagement/VendorDetail.tsx, VendorDetailClient.tsx
-- WithdrawalManagement/WithdrawalDetailClientV2.tsx
-```
-
-#### 건설 (Construction) - 40개+
-```
-- bidding/BiddingDetailForm.tsx
-- contract/ContractDetailForm.tsx
-- estimates/EstimateDetailForm.tsx
-- handover-report/HandoverReportDetailForm.tsx
-- issue-management/IssueDetailForm.tsx
-- item-management/ItemDetailClient.tsx
-- labor-management/LaborDetailClient.tsx
-- management/ConstructionDetailClient.tsx
-- order-management/OrderDetailForm.tsx
-- partners/PartnerForm.tsx
-- pricing-management/PricingDetailClient.tsx
-- progress-billing/ProgressBillingDetailForm.tsx
-- site-briefings/SiteBriefingForm.tsx
-- site-management/SiteDetailForm.tsx
-- structure-review/StructureReviewDetailForm.tsx
-```
-
-#### HR/클라이언트/고객센터 - 15개+
-```
-- hr/EmployeeManagement/EmployeeDetail.tsx, EmployeeForm.tsx
-- hr/CardManagement/CardDetail.tsx
-- clients/ClientDetailClientV2.tsx, ClientRegistration.tsx
-- customer-center/NoticeManagement/NoticeDetail.tsx
-- customer-center/EventManagement/EventDetail.tsx
-- customer-center/InquiryManagement/InquiryDetail.tsx, InquiryForm.tsx
-```
-
-#### 자재/생산/품질/유통 - 12개+
-```
-- material/ReceivingManagement/ReceivingDetail.tsx, InspectionCreate.tsx
-- material/StockStatus/StockStatusDetail.tsx
-- production/WorkOrders/WorkOrderCreate.tsx, WorkOrderDetail.tsx, WorkOrderEdit.tsx
-- quality/InspectionManagement/InspectionCreate.tsx, InspectionDetail.tsx
-- outbound/ShipmentManagement/ShipmentCreate.tsx, ShipmentDetail.tsx, ShipmentEdit.tsx
-```
-
-#### 기타 - 15개+
-```
-- orders/OrderRegistration.tsx, OrderSalesDetailEdit.tsx, OrderSalesDetailView.tsx
-- quotes/QuoteRegistration.tsx
-- process-management/ProcessForm.tsx
-- settings/PermissionManagement/PermissionDetail.tsx
-- settings/PopupManagement/PopupDetailClientV2.tsx
-- board/BoardForm/index.tsx
-- approval/DocumentCreate/index.tsx
-```
-
----
-
-## 11. 검증 체크리스트
-
-### Phase 1 완료 후 검증
-- [ ] PermissionContext가 로그인 시 권한 로드
-- [ ] usePermission 훅이 올바른 권한 반환
-- [ ] 권한 없는 사용자에게 false 반환
-
-### Phase 2 완료 후 검증
-- [ ] 모든 46개 Config에 menuCode 추가됨
-- [ ] TypeScript 타입 에러 없음
-- [ ] 기존 기능 영향 없음 (backward compatible)
-
-### Phase 4 완료 후 검증
-- [ ] 템플릿 사용 페이지 165개+ 권한 체크 작동
-- [ ] 개별 페이지 41개 권한 체크 작동
-- [ ] 권한 없는 사용자 AccessDenied 표시
-- [ ] 권한 있는 사용자 모든 기능 정상
-
----
-
-**문서 업데이트 이력:**
-- 2025-01-20: 최초 작성
-- 2025-01-21: 백엔드 API 확정, 캐싱 전략 확정
-- 2026-01-21: 전체 페이지 분석 추가 (206개), Config 파일 46개 확인, 개별 작업 필요 페이지 41개 목록화
-- 2026-01-23: 공통화/추상화 효율 분석 추가, page.tsx vs 컴포넌트 레벨 관점 차이 설명, 권한 적용 구조도 추가

claudedocs/_index.md

@@ -1,12 +1,14 @@
 # claudedocs 문서 맵
 
-> 프로젝트 기술 문서 인덱스 (Last Updated: 2026-01-29)
+> 프로젝트 기술 문서 인덱스 (Last Updated: 2026-02-23)
 
-## ⭐ 빠른 참조
+## 빠른 참조
 
 | 문서 | 설명 |
 |------|------|
-| **[`[REF] all-pages-test-urls.md`](./[REF]%20all-pages-test-urls.md)** | 🔗 **전체 페이지 테스트 URL 목록** - 모든 페이지 직접 접근 주소 |
+| **[`[REF] all-pages-test-urls.md`](./dev/[REF]%20all-pages-test-urls.md)** | 전체 페이지 테스트 URL 목록 |
+| **[`[REF] technical-decisions.md`](./architecture/[REF]%20technical-decisions.md)** | 프로젝트 기술 결정 사항 (13개 항목) |
+| **[`[GUIDE] common-page-patterns.md`](./guides/[GUIDE]%20common-page-patterns.md)** | 공통 페이지 패턴 가이드 |
 
 ---
 
@@ -14,231 +16,40 @@
 
 ```
 claudedocs/
-├── _index.md           # 이 파일 - 문서 맵
-├── auth/               # 🔐 인증 & 토큰 관리
-├── hr/                 # 👥 인사관리 (부서/사원)
-├── item-master/        # 📦 품목기준관리
-├── production/         # 🏭 생산관리 (생산현황판/작업지시)
-├── quality/            # 🔬 품질관리 (검사관리)
-├── sales/              # 💰 판매관리 (견적/거래처)
-├── accounting/         # 💳 회계관리 (매입/매출/출금)
-├── board/              # 📝 게시판 관리
-├── settings/           # ⚙️ 설정 관리
-├── dashboard/          # 📊 대시보드 & 사이드바
-├── api/                # 🔌 API 통합
-├── guides/             # 📚 범용 가이드
-├── architecture/       # 🏗️ 아키텍처 & 시스템
-├── juil/               # 🏗️ 주일 공사 MES (NEW)
-└── archive/            # 📁 레거시/완료된 문서
+├── _index.md              # 이 파일 - 문서 맵
+├── auth/                  # 인증 & 토큰 관리
+├── hr/                    # 인사관리 (부서/사원)
+├── item-master/           # 품목기준관리
+├── production/            # 생산관리 (생산현황판/작업자화면)
+├── quality/               # 품질관리 (검사관리)
+├── sales/                 # 판매관리 (견적/거래처/단가)
+├── accounting/            # 회계관리 (매입/매출/출금)
+├── construction/          # 주일 공사 MES
+├── board/                 # 게시판 관리
+├── settings/              # 설정 관리
+├── dashboard/             # 대시보드 & 사이드바
+├── security/              # 보안 & 권한
+├── api/                   # API 통합
+├── dev/                   # 개발도구 & 테스트
+├── guides/                # 범용 가이드
+│   ├── mobile/            # 모바일 반응형
+│   ├── universal-list/    # UniversalListPage 관련
+│   └── migration/         # 마이그레이션 체크리스트
+├── architecture/          # 아키텍처 & 시스템 & 기술 결정
+├── changes/               # 변경이력
+├── refactoring/           # 리팩토링 체크리스트
+├── vehicle/               # 차량관리
+├── material/              # 자재관리
+├── approval/              # 결재관리
+├── customer-center/       # 고객센터
+├── components/            # 컴포넌트 문서
+├── vercel/                # Vercel 배포
+└── archive/               # 레거시/완료된 문서
+    └── sessions/          # 만료된 세션 체크포인트
 ```
 
 ---
 
-## 🔐 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/ - 아키텍처 & 시스템
-
-| 파일 | 설명 |
-|------|------|
-| `[FIX-2026-01-29] masterdata-cache-tenant-isolation.md` | 🔴 **NEW** - masterDataStore 캐시 테넌트 격리 수정 (page_config 키에 tenantId 추가, dead code 해소) |
-| `[PLAN-2025-12-29] dynamic-menu-refresh.md` | 동적 메뉴 갱신 시스템 (1단계: 폴링, 2단계: SSE) |
-| `multi-tenancy-implementation.md` | 멀티테넌시 구현 |
-| `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/ - 레거시/완료된 문서
-
-완료되거나 더 이상 활성화되지 않은 문서들. 참조용으로 보관.
-
----
-
 ## 문서 작성 규칙
 
 ### 파일명 컨벤션
@@ -255,15 +66,25 @@ claudedocs/
 - `PLAN` - 계획 문서
 - `DESIGN` - 설계 문서
 - `TEST` - 테스트 가이드
-- `NEXT` - 다음 작업 목록
+- `NEXT` - 다음 작업 목록 (세션 체크포인트)
 - `FIX` - 버그 해결 문서
+- `QA` - 품질 검사 문서
+- `HOTFIX` - 긴급 수정 문서
+- `REPORT` - 보고서/전달 문서
 
 ### 폴더 배치 기준
 1. **기능/도메인 우선**: 문서 주제에 맞는 폴더에 배치
 2. **범용 가이드**: 여러 기능에 적용되면 `guides/`에 배치
-3. **완료된 작업**: 더 이상 활성화되지 않으면 `archive/`로 이동
-4. **신규 도메인**: 3개 이상 문서가 생기면 새 폴더 생성 고려
+3. **시스템 전체**: 아키텍처/리팩토링/기술결정은 `architecture/`에 배치
+4. **개발도구**: 테스트 URL, 빌드, E2E, 설정은 `dev/`에 배치
+5. **완료된 작업**: 더 이상 활성화되지 않으면 `archive/`로 이동
+6. **만료 세션**: 2개월 이상 경과한 NEXT-* 파일은 `archive/sessions/`로 이동
 
-### 문서 업데이트
-- 중요 변경 시 문서 상단에 날짜와 함께 변경사항 기록
-- `_index.md`에 새 문서 추가 시 테이블 업데이트
+### 파일 목록 확인
+```bash
+# 특정 도메인 파일 확인
+ls claudedocs/<domain>/
+
+# 전체 파일 검색
+find claudedocs/ -name "*.md" | sort
+```

claudedocs/architecture/[ANALYSIS-2026-02-05] SAM-ERP-MES-정체성-분석.md

@@ -0,0 +1,256 @@
+# SAM 프로젝트 정체성 및 현장 효용성 분석
+
+> 작성일: 2026-02-05
+> 목적: ERP/MES 관점에서 SAM 시스템의 포지션, 강점/약점, 현장 효용성 분석
+
+---
+
+## 1. SAM의 정체성: "제조+설치 통합형 ERP/MES"
+
+### 포지셔닝
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    SAM 시스템 포지션                         │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│   Pure MES ◄────────── SAM ──────────► Pure ERP            │
+│   (공장 실행)          │              (경영 관리)            │
+│                       │                                     │
+│              ┌────────┴────────┐                           │
+│              │  70% ERP        │                           │
+│              │  30% MES        │                           │
+│              │  + 건설 프로젝트 │                           │
+│              └─────────────────┘                           │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+SAM은 **순수 MES도 아니고 순수 ERP도 아닌**, 제조업체가 실제로 필요로 하는 기능들을 통합한 시스템이다.
+
+### 타겟 산업: 블라인드/셔터 제조 + 설치
+
+| 특징 | SAM의 대응 |
+|------|-----------|
+| 주문생산(Make-to-Order) | 수주 → 생산지시 → 작업실적 흐름 |
+| 다품종 소량생산 | 동적 품목 마스터 (빌더 시스템) |
+| 설치 서비스 병행 | 건설/시공 프로젝트 모듈 |
+| 품질 인증 필요 | QMS 검사성적서 시스템 |
+| 중소기업 규모 | SaaS 멀티테넌트 구조 |
+
+---
+
+## 2. ERP 관점 분석
+
+### 커버리지
+
+| ERP 영역 | SAM 구현 수준 | 비고 |
+|----------|-------------|------|
+| **재무회계** | ⭐⭐⭐⭐ (80%) | 매입/매출/입출금/어음/카드/채권 |
+| **영업관리** | ⭐⭐⭐⭐ (85%) | 견적→수주→생산지시 연동 |
+| **구매관리** | ⭐⭐⭐ (70%) | 입고 중심, 발주 모듈 약함 |
+| **재고관리** | ⭐⭐⭐ (65%) | 재고현황 중심, 창고이동 미흡 |
+| **인사관리** | ⭐⭐⭐⭐ (80%) | 근태/급여/휴가/문서 |
+| **전자결재** | ⭐⭐⭐ (70%) | 기안/결재/참조 기본 구조 |
+| **프로젝트** | ⭐⭐⭐⭐⭐ (90%) | 건설 모듈이 매우 정교함 |
+
+### ERP로서의 강점
+
+1. **영업-생산 연동**: 수주가 바로 생산지시로 연결되는 구조
+2. **프로젝트 관리**: 입찰→계약→시공→정산까지 풀 사이클
+3. **회계 통합**: 매출/매입이 거래처원장과 연동
+4. **멀티테넌트**: 신규 고객사 온보딩이 빠름
+
+### ERP로서의 약점
+
+1. **구매/발주**: 입고 위주, 구매요청→발주→입고 흐름 미흡
+2. **원가계산**: 제조원가 계산 로직이 명시적이지 않음
+3. **창고관리**: 다창고, 로케이션 관리 부재
+4. **BI/분석**: 대시보드는 있으나 심층 분석 약함
+
+---
+
+## 3. MES 관점 분석
+
+### 커버리지
+
+| MES 영역 | SAM 구현 수준 | 비고 |
+|----------|-------------|------|
+| **작업지시** | ⭐⭐⭐⭐ (80%) | 생산지시 생성/관리 |
+| **작업실적** | ⭐⭐⭐⭐ (80%) | 실적 입력/조회 |
+| **품질관리** | ⭐⭐⭐⭐⭐ (90%) | 다양한 검사성적서 |
+| **설비관리** | ⭐ (20%) | 거의 없음 |
+| **실시간 모니터링** | ⭐⭐⭐ (60%) | 대시보드 있음, PLC 연동 없음 |
+| **작업자 화면** | ⭐⭐⭐⭐ (75%) | 현장 터치 인터페이스 |
+| **추적성(Traceability)** | ⭐⭐⭐ (65%) | 로트 추적 기본 구조 |
+
+### MES로서의 강점
+
+1. **품질 시스템**: QMS가 상당히 정교함 (6종 검사성적서)
+2. **작업자 친화적**: 현장용 작업자 화면 별도 존재
+3. **생산-영업 연결**: 수주 기반 생산이라 주문 추적 용이
+
+### MES로서의 약점
+
+1. **설비 연동 없음**: PLC, 바코드 스캐너 등 현장 장비 연동 부재
+2. **실시간성 부족**: 폴링 기반, 실시간 푸시 아님
+3. **공정 스케줄링**: 단순 작업지시, APS(고급계획) 없음
+4. **설비 모니터링**: OEE, 설비 가동률 등 없음
+
+---
+
+## 4. 현장 효용성 평가
+
+### 실제로 잘 맞는 업종
+
+```
+✅ 주문생산 제조업 (블라인드, 가구, 인테리어 자재)
+✅ 설치 서비스 병행 업체
+✅ 다품종 소량생산
+✅ 품질 인증 필요 업종 (ISO, KS 등)
+✅ 직원 50명 이하 중소기업
+✅ IT 인력이 부족한 회사 (SaaS로 운영부담 최소화)
+```
+
+### 맞지 않는 업종
+
+```
+❌ 대량생산 (자동차, 반도체) - MES 깊이 부족
+❌ 연속공정 (화학, 식품) - 배치/레시피 관리 없음
+❌ 설비 집약 산업 - 설비 연동/모니터링 없음
+❌ 복잡한 원가계산 필요 업종 - 원가 모듈 약함
+❌ 대기업 (100명+) - 워크플로우 복잡도 한계
+```
+
+### 현장에서의 실제 가치
+
+| 관점 | 효용 |
+|------|------|
+| **경영진** | 수주~매출까지 한눈에, 프로젝트별 손익 파악 |
+| **영업팀** | 견적→수주→생산현황 실시간 확인 |
+| **생산팀** | 작업지시 받고 실적 입력, 품질 기록 |
+| **품질팀** | 검사성적서 발행, 인증심사 대응 |
+| **경리팀** | 매입/매출/입출금 통합 관리 |
+| **현장 작업자** | 터치 화면으로 작업 확인/실적 입력 |
+
+---
+
+## 5. 경쟁 포지션
+
+### vs 범용 ERP (더존, 영림원)
+
+| 항목 | SAM | 범용 ERP |
+|------|-----|---------|
+| 제조 특화 | ⭐⭐⭐⭐ | ⭐⭐ |
+| 건설/시공 | ⭐⭐⭐⭐⭐ | ⭐ |
+| 회계 깊이 | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
+| 커스터마이징 | ⭐⭐⭐⭐ (빌더) | ⭐⭐ |
+| 도입 비용 | 낮음 (SaaS) | 높음 |
+
+### vs 전문 MES (포스코ICT, 미라콤)
+
+| 항목 | SAM | 전문 MES |
+|------|-----|---------|
+| 설비 연동 | ❌ | ⭐⭐⭐⭐⭐ |
+| 실시간성 | ⭐⭐ | ⭐⭐⭐⭐⭐ |
+| 품질 관리 | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ |
+| ERP 통합 | ⭐⭐⭐⭐⭐ | ⭐⭐ (별도 연동) |
+| 도입 기간 | 짧음 | 길음 |
+
+### SAM의 틈새 (Niche)
+
+```
+"전문 MES는 과하고, 범용 ERP는 제조 기능이 부족한"
+중소 제조+설치 업체를 위한 통합 솔루션
+```
+
+---
+
+## 6. 빌더 확장 시 기대효과
+
+현재 품목기준관리 빌더를 다른 영역으로 확장하면:
+
+| 확장 영역 | 예상 효과 |
+|----------|----------|
+| **폼 빌더** (등록/수정) | 신규 업종 대응 시 개발 50% 절감 |
+| **리스트 빌더** (조회) | 화면 추가/변경 무코딩 가능 |
+| **문서 빌더** (성적서) | 업종별 양식 빠른 대응 |
+| **워크플로우 빌더** | 결재/승인 프로세스 설정화 |
+
+**신규 업체 온보딩 시나리오**:
+```
+현재: 요구분석 → 개발 → 테스트 → 배포 (4-8주)
+목표: 요구분석 → 빌더 설정 → 배포 (1-2주)
+```
+
+---
+
+## 7. 종합 평가
+
+### SAM의 정체성 한 문장
+
+> **"주문생산 중소 제조업을 위한 ERP+MES 통합 SaaS로, 생산-품질-영업-회계를 하나로 연결하고, 설치 프로젝트까지 관리하는 올인원 솔루션"**
+
+### 핵심 차별점
+
+1. **제조+설치 통합** - 대부분의 시스템이 둘 중 하나만 함
+2. **품질 시스템 내장** - QMS가 기본 탑재
+3. **빌더 기반 확장성** - 업종별 커스터마이징 용이
+4. **SaaS 멀티테넌트** - 도입 부담 최소화
+
+### 발전 방향 제안
+
+| 단기 | 중기 | 장기 |
+|------|------|------|
+| 빌더 → 리스트까지 확장 | 바코드/QR 스캐닝 | 설비 연동 (IoT) |
+| 발주 모듈 보강 | 모바일 앱 강화 | AI 수요 예측 |
+| 원가계산 기본 기능 | 실시간 알림 (WebSocket) | APS 스케줄링 |
+
+---
+
+## 8. 시스템 규모 현황
+
+### 프로젝트 스케일
+
+- **24개** 주요 기능 모듈
+- **250+** 페이지
+- **900+** 컴포넌트 파일
+- 멀티테넌트 아키텍처
+- 다국어 지원 (한국어, 영어, 일본어)
+
+### 모듈별 복잡도
+
+| 모듈 | 복잡도 | 페이지 수 | 핵심 기능 |
+|------|--------|----------|----------|
+| Construction | ⭐⭐⭐⭐⭐ | 57 | 프로젝트 풀 라이프사이클 |
+| Accounting | ⭐⭐⭐⭐ | 31 | 재무 관리 전체 |
+| Production | ⭐⭐⭐⭐ | 12 | 실시간 MES 코어 |
+| Quality | ⭐⭐⭐⭐ | 24 | 다중 검사 QMS |
+| Master Data | ⭐⭐⭐⭐⭐ | 12 | 동적 폼 템플릿 |
+| Sales | ⭐⭐⭐ | 20 | 견적→수주 흐름 |
+| HR | ⭐⭐⭐ | 17 | 직원 라이프사이클 |
+| Material | ⭐⭐ | 6 | 재고 & 입고 |
+| Outbound | ⭐⭐ | 7 | 출고 & 배차 |
+
+---
+
+## 부록: 기술 스택
+
+**Frontend:**
+- Next.js 15 (App Router)
+- React 18
+- TypeScript
+- Tailwind CSS
+- Radix UI
+- Zustand
+
+**Backend:**
+- PHP Laravel API (별도 코드베이스)
+- MySQL/MariaDB
+- JWT 인증
+- 멀티테넌트 아키텍처
+
+**인프라:**
+- HttpOnly 쿠키 보안
+- 멀티테넌트 데이터 격리
+- RESTful API 설계

claudedocs/architecture/[ANALYSIS-2026-02-05] list-page-commonization-status.md

@@ -0,0 +1,505 @@
+# 리스트 페이지 공통화 현황 분석
+
+> 작성일: 2026-02-05
+> 목적: 리스트 페이지 반복 패턴 식별 및 공통화 가능성 분석
+
+---
+
+## 📊 전체 현황
+
+| 구분 | 수량 |
+|------|------|
+| 총 리스트 페이지 | 37개 |
+| UniversalListPage 사용 | 15개+ |
+| IntegratedListTemplateV2 직접 사용 | 5개+ |
+| 레거시 패턴 | 10개+ |
+
+---
+
+## 🏗️ 템플릿 계층 구조
+
+```
+UniversalListPage (최상위 - config 기반)
+    └── IntegratedListTemplateV2 (하위 - props 기반)
+            └── 공통 UI 컴포넌트
+                ├── PageLayout
+                ├── PageHeader
+                ├── StatCards
+                ├── DateRangeSelector
+                ├── MobileFilter
+                ├── ListMobileCard
+                └── Table, Pagination 등
+```
+
+---
+
+## 📁 리스트 페이지 목록 및 사용 템플릿
+
+### UniversalListPage 사용 (최신 패턴)
+
+| 파일 | 도메인 | 특징 |
+|------|--------|------|
+| `items/ItemListClient.tsx` | 품목관리 | 외부 훅(useItemList) 사용, 엑셀 업로드/다운로드 |
+| `pricing/PricingListClient.tsx` | 가격관리 | 외부 훅 사용 |
+| `production/WorkOrders/WorkOrderList.tsx` | 생산 | 공정 기반 탭, 외부 통계 API |
+| `outbound/ShipmentManagement/ShipmentList.tsx` | 출고 | 캘린더 통합, 날짜범위 필터 |
+| `outbound/VehicleDispatchManagement/VehicleDispatchList.tsx` | 배차 | - |
+| `material/ReceivingManagement/ReceivingList.tsx` | 입고 | - |
+| `material/StockStatus/StockStatusList.tsx` | 재고 | - |
+| `customer-center/NoticeManagement/NoticeList.tsx` | 공지사항 | 클라이언트 사이드 필터링 |
+| `customer-center/EventManagement/EventList.tsx` | 이벤트 | 클라이언트 사이드 필터링 |
+| `customer-center/InquiryManagement/InquiryList.tsx` | 문의 | - |
+| `customer-center/FAQManagement/FAQList.tsx` | FAQ | - |
+| `quality/InspectionManagement/InspectionList.tsx` | 품질검사 | - |
+| `process-management/ProcessListClient.tsx` | 공정관리 | - |
+| `pricing-table-management/PricingTableListClient.tsx` | 단가표 | - |
+| `pricing-distribution/PriceDistributionList.tsx` | 가격배포 | - |
+
+### 건설 도메인 (UniversalListPage 사용)
+
+| 파일 | 기능 |
+|------|------|
+| `construction/management/ProjectListClient.tsx` | 프로젝트 목록 |
+| `construction/management/ConstructionManagementListClient.tsx` | 공사관리 목록 |
+| `construction/contract/ContractListClient.tsx` | 계약 목록 |
+| `construction/estimates/EstimateListClient.tsx` | 견적 목록 |
+| `construction/bidding/BiddingListClient.tsx` | 입찰 목록 |
+| `construction/pricing-management/PricingListClient.tsx` | 단가관리 목록 |
+| `construction/partners/PartnerListClient.tsx` | 협력사 목록 |
+| `construction/order-management/OrderManagementListClient.tsx` | 발주관리 목록 |
+| `construction/site-management/SiteManagementListClient.tsx` | 현장관리 목록 |
+| `construction/site-briefings/SiteBriefingListClient.tsx` | 현장브리핑 목록 |
+| `construction/handover-report/HandoverReportListClient.tsx` | 인수인계 목록 |
+| `construction/issue-management/IssueManagementListClient.tsx` | 이슈관리 목록 |
+| `construction/structure-review/StructureReviewListClient.tsx` | 구조검토 목록 |
+| `construction/utility-management/UtilityManagementListClient.tsx` | 유틸리티 목록 |
+| `construction/worker-status/WorkerStatusListClient.tsx` | 작업자 현황 |
+| `construction/progress-billing/ProgressBillingManagementListClient.tsx` | 기성관리 목록 |
+
+### 기타/레거시
+
+| 파일 | 비고 |
+|------|------|
+| `settings/PopupManagement/PopupList.tsx` | 팝업관리 |
+| `production/WorkResults/WorkResultList.tsx` | 작업실적 |
+| `quality/PerformanceReportManagement/PerformanceReportList.tsx` | 성과보고서 |
+| `board/BoardList/BoardListUnified.tsx` | 통합 게시판 |
+
+---
+
+## 🔄 반복 패턴 분석
+
+### 1. Badge 색상 매핑 (매우 반복적)
+
+각 페이지마다 개별 정의되어 있는 패턴:
+
+```typescript
+// ItemListClient.tsx
+const badges: Record<string, { variant: string; className: string }> = {
+  FG: { variant: 'default', className: 'bg-purple-100 text-purple-700 border-purple-200' },
+  PT: { variant: 'default', className: 'bg-orange-100 text-orange-700 border-orange-200' },
+  // ...
+};
+
+// WorkOrderList.tsx
+const PRIORITY_COLORS: Record<string, string> = {
+  '긴급': 'bg-red-100 text-red-700',
+  '우선': 'bg-orange-100 text-orange-700',
+  '일반': 'bg-gray-100 text-gray-700',
+};
+
+// ShipmentList.tsx - types.ts에서 import
+export const SHIPMENT_STATUS_STYLES: Record<ShipmentStatus, string> = { ... };
+```
+
+**현황**:
+- `src/lib/utils/status-config.ts`에 `createStatusConfig` 유틸 존재
+- 일부 페이지만 사용 중 (대부분 개별 정의)
+
+### 2. 상태 라벨 정의 (반복적)
+
+```typescript
+// WorkOrderList.tsx - types.ts에서 import
+export const WORK_ORDER_STATUS_LABELS: Record<WorkOrderStatus, string> = {
+  pending: '대기',
+  in_progress: '진행중',
+  completed: '완료',
+};
+
+// ShipmentList.tsx - types.ts에서 import
+export const SHIPMENT_STATUS_LABELS: Record<ShipmentStatus, string> = { ... };
+```
+
+**현황**: 각 도메인 types.ts에서 개별 정의
+
+### 3. 필터 설정 (filterConfig)
+
+```typescript
+// WorkOrderList.tsx
+const filterConfig: FilterFieldConfig[] = [
+  {
+    key: 'status',
+    label: '상태',
+    type: 'single',
+    options: [
+      { value: 'waiting', label: '작업대기' },
+      { value: 'in_progress', label: '진행중' },
+      { value: 'completed', label: '작업완료' },
+    ],
+  },
+  {
+    key: 'priority',
+    label: '우선순위',
+    type: 'single',
+    options: [
+      { value: 'urgent', label: '긴급' },
+      { value: 'priority', label: '우선' },
+      { value: 'normal', label: '일반' },
+    ],
+  },
+];
+```
+
+**공통 필터 패턴**:
+- 상태 필터 (대기/진행/완료)
+- 우선순위 필터 (긴급/우선/일반)
+- 유형 필터 (전체/유형1/유형2...)
+
+### 4. 행 클릭 핸들러 패턴
+
+```typescript
+// 모든 페이지에서 동일한 패턴
+const handleRowClick = useCallback(
+  (item: SomeType) => {
+    router.push(`/ko/${basePath}/${item.id}?mode=view`);
+  },
+  [router]
+);
+```
+
+### 5. 테이블 행 렌더링 (renderTableRow)
+
+```typescript
+// 공통 구조
+<TableRow onClick={() => handleRowClick(item)}>
+  <TableCell onClick={(e) => e.stopPropagation()}>
+    <Checkbox checked={isSelected} onCheckedChange={onToggle} />
+  </TableCell>
+  <TableCell className="text-center">{globalIndex}</TableCell>
+  {/* 데이터 컬럼들 */}
+  <TableCell>
+    <Badge className={getStatusStyle(item.status)}>
+      {getStatusLabel(item.status)}
+    </Badge>
+  </TableCell>
+</TableRow>
+```
+
+---
+
+## ✅ 이미 공통화된 것
+
+| 유틸/컴포넌트 | 위치 | 사용률 |
+|--------------|------|--------|
+| `UniversalListPage` | templates/ | 높음 (15개+) |
+| `IntegratedListTemplateV2` | templates/ | 높음 |
+| `ListMobileCard`, `InfoField` | organisms/ | 높음 |
+| `MobileFilter` | molecules/ | 높음 |
+| `DateRangeSelector` | molecules/ | 높음 |
+| `StatCards` | organisms/ | 높음 |
+| `createStatusConfig` | lib/utils/ | **낮음** (일부만 사용) |
+
+---
+
+## ❌ 공통화 필요한 것
+
+### 높은 우선순위 (ROI 높음)
+
+| 패턴 | 현황 | 공통화 방안 |
+|------|------|-------------|
+| **Badge 색상 매핑** | 각 페이지 개별 정의 | `src/lib/utils/badge-styles.ts` 생성 |
+| **공통 필터 프리셋** | 각 페이지 개별 정의 | `src/lib/constants/filter-presets.ts` 생성 |
+| **우선순위 색상** | 각 페이지 개별 정의 | 공통 상수로 추출 |
+
+### 중간 우선순위
+
+| 패턴 | 현황 | 공통화 방안 |
+|------|------|-------------|
+| 상태 라벨 | 도메인별 types.ts | 도메인별 유지 (비즈니스 로직) |
+| 행 클릭 핸들러 | 각 페이지 개별 | UniversalListPage에서 처리 중 |
+
+---
+
+## 📋 공통화 대상 상세
+
+### 1. Badge 스타일 공통화
+
+**현재 분산된 위치**:
+- `items/ItemListClient.tsx` - getItemTypeBadge()
+- `production/WorkOrders/types.ts` - WORK_ORDER_STATUS_COLORS
+- `outbound/ShipmentManagement/types.ts` - SHIPMENT_STATUS_STYLES
+- 기타 각 도메인별 개별 정의
+
+**이미 존재하는 공통 유틸** (`src/lib/utils/status-config.ts`):
+```typescript
+export const BADGE_STYLE_PRESETS: Record<StatusStylePreset, string> = {
+  default: 'bg-gray-100 text-gray-800',
+  success: 'bg-green-100 text-green-800',
+  warning: 'bg-yellow-100 text-yellow-800',
+  destructive: 'bg-red-100 text-red-800',
+  info: 'bg-blue-100 text-blue-800',
+  muted: 'bg-gray-100 text-gray-500',
+  orange: 'bg-orange-100 text-orange-800',
+  purple: 'bg-purple-100 text-purple-800',
+};
+```
+
+**문제**: 존재하지만 대부분의 페이지에서 사용하지 않음
+
+### 2. 공통 필터 프리셋
+
+**추출 가능한 공통 필터**:
+```typescript
+// 상태 필터 (거의 모든 페이지)
+export const COMMON_STATUS_FILTER: FilterFieldConfig = {
+  key: 'status',
+  label: '상태',
+  type: 'single',
+  options: [
+    { value: 'pending', label: '대기' },
+    { value: 'in_progress', label: '진행중' },
+    { value: 'completed', label: '완료' },
+  ],
+};
+
+// 우선순위 필터 (생산, 출고 등)
+export const COMMON_PRIORITY_FILTER: FilterFieldConfig = {
+  key: 'priority',
+  label: '우선순위',
+  type: 'single',
+  options: [
+    { value: 'urgent', label: '긴급' },
+    { value: 'priority', label: '우선' },
+    { value: 'normal', label: '일반' },
+  ],
+};
+```
+
+### 3. 우선순위 색상 통합
+
+**현재 상태**: 여러 파일에서 동일한 색상 반복
+```typescript
+// 긴급: bg-red-100 text-red-700
+// 우선: bg-orange-100 text-orange-700
+// 일반: bg-gray-100 text-gray-700
+```
+
+---
+
+## 🎯 권장 액션
+
+### Phase 1: 즉시 실행 가능
+
+1. **`createStatusConfig` 사용률 높이기**
+   - 기존 유틸 활용도 확인
+   - 새 페이지 작성 시 필수 사용 권장
+
+2. **공통 필터 프리셋 파일 생성**
+   - 위치: `src/lib/constants/filter-presets.ts`
+   - 상태/우선순위/유형 필터 템플릿
+
+3. **우선순위 색상 상수 통합**
+   - 위치: `src/lib/utils/status-config.ts`에 추가
+
+### Phase 2: 점진적 적용
+
+1. 신규 페이지는 공통 유틸 필수 사용
+2. 기존 페이지는 수정 시 점진적 마이그레이션
+3. 기능 변경 없이 import만 변경
+
+---
+
+## 📊 공통화 효과 예측
+
+| 항목 | Before | After |
+|------|--------|-------|
+| Badge 정의 위치 | 37개 파일에 분산 | 1개 파일 (+ import) |
+| 필터 프리셋 | 각 페이지 개별 | 공통 상수 재사용 |
+| 색상 변경 시 수정 범위 | 37개 파일 | 1개 파일 |
+| 신규 페이지 개발 시간 | 기존 페이지 참고 필요 | 공통 유틸 import만 |
+
+---
+
+## 📝 결론
+
+1. **UniversalListPage는 이미 잘 구축됨** - 대부분 리스트가 사용 중
+2. **Badge/필터 공통화가 주요 개선점** - 반복 코드 제거 가능
+3. **기존 유틸(`createStatusConfig`) 활용도 낮음** - 홍보/가이드 필요
+4. **기능 변경 없이 공통화 가능** - 리팩토링 리스크 낮음
+
+---
+
+## ✅ 공통화 작업 완료 현황 (2026-02-05)
+
+### 생성된 파일
+
+| 파일 | 설명 |
+|------|------|
+| `src/lib/constants/filter-presets.ts` | 공통 필터 프리셋 (상태/우선순위/품목유형 등) |
+| `claudedocs/guides/badge-commonization-guide.md` | Badge 공통화 사용 가이드 |
+
+### 수정된 파일
+
+| 파일 | 변경 내용 |
+|------|----------|
+| `src/lib/utils/status-config.ts` | 우선순위/품목유형 설정 추가, 한글 라벨 지원 |
+| `src/components/production/WorkOrders/WorkOrderList.tsx` | 공통 유틸 적용 (샘플 마이그레이션) |
+
+### 추가된 공통 유틸
+
+**filter-presets.ts**:
+- `COMMON_STATUS_FILTER` - 대기/진행/완료
+- `WORK_STATUS_FILTER` - 작업대기/진행중/작업완료
+- `COMMON_PRIORITY_FILTER` - 긴급/우선/일반
+- `ITEM_TYPE_FILTER` - 품목유형
+- `createSingleFilter()`, `createMultiFilter()` - 커스텀 필터 생성
+
+**status-config.ts**:
+- `getPriorityLabel()`, `getPriorityStyle()` - 우선순위 (한글/영문 모두 지원)
+- `getItemTypeLabel()`, `getItemTypeStyle()` - 품목유형
+- `COMMON_STATUS_CONFIG`, `WORK_STATUS_CONFIG` 등 - 미리 정의된 상태 설정
+
+### 샘플 마이그레이션 결과 (WorkOrderList.tsx)
+
+**Before**:
+```tsx
+// 개별 정의
+const PRIORITY_COLORS: Record<string, string> = {
+  '긴급': 'bg-red-100 text-red-700',
+  '우선': 'bg-orange-100 text-orange-700',
+  '일반': 'bg-gray-100 text-gray-700',
+};
+
+const filterConfig: FilterFieldConfig[] = [
+  { key: 'status', label: '상태', type: 'single', options: [...] },
+  { key: 'priority', label: '우선순위', type: 'single', options: [...] },
+];
+
+<Badge className={`${PRIORITY_COLORS[item.priorityLabel]} border-0`}>
+```
+
+**After**:
+```tsx
+// 공통 유틸 사용
+import { WORK_STATUS_FILTER, COMMON_PRIORITY_FILTER } from '@/lib/constants/filter-presets';
+import { getPriorityStyle } from '@/lib/utils/status-config';
+
+const filterConfig = [WORK_STATUS_FILTER, COMMON_PRIORITY_FILTER];
+
+<Badge className={`${getPriorityStyle(item.priorityLabel)} border-0`}>
+```
+
+**효과**:
+- 코드 라인 20줄 → 3줄
+- 필터 옵션 중복 정의 제거
+- 색상 일관성 보장
+
+---
+
+## 🔄 추가 마이그레이션 (2026-02-05 업데이트)
+
+### 완료된 마이그레이션
+
+| 파일 | 적용 내용 | 효과 |
+|------|----------|------|
+| `WorkOrderList.tsx` | WORK_STATUS_FILTER + COMMON_PRIORITY_FILTER + getPriorityStyle | 20줄 → 3줄 |
+| `ItemListClient.tsx` | getItemTypeStyle (품목유형 Badge) | 17줄 → 4줄 |
+| `ItemDetailClient.tsx` | getItemTypeStyle (품목유형 Badge) | 17줄 → 4줄 |
+
+### 마이그레이션 제외 대상 (도메인 특화 설정)
+
+| 파일 | 제외 사유 |
+|------|----------|
+| `PricingListClient.tsx` | 다른 색상 체계 (SM=cyan, BENDING 추가 타입) |
+| `StockStatus/types.ts` | 레거시 타입 지원 (raw_material, bent_part 등) |
+| `ShipmentManagement/types.ts` | 다른 우선순위 라벨 (보통/낮음) |
+| `issue-management/types.ts` | 2단계 우선순위 (긴급/일반만) |
+| `WipProductionModal.tsx` | 버튼 스타일 우선순위 (Badge 아님) |
+| `ReceivingList.tsx` | 도메인 특화 상태 (입고대기/입고완료/검사완료) |
+| HR 페이지들 | 도메인 특화 상태 설정 |
+| 건설 도메인 페이지들 | 도메인 특화 상태 설정 |
+
+### 분석 결과 요약
+
+1. **공통 유틸 적용 완료 페이지**: 3개 (WorkOrderList, ItemListClient, ItemDetailClient)
+2. **도메인 특화 설정 페이지**: 34개 (개별 유지가 적절)
+3. **결론**: 대부분의 페이지는 도메인별 특화된 상태/라벨/색상을 사용하며, 이는 비즈니스 로직을 명확히 반영하기 위해 의도된 설계
+
+### 공통 유틸 권장 사용 시나리오
+
+1. **신규 리스트 페이지 생성 시**: 표준 패턴(대기/진행/완료, 긴급/우선/일반) 사용
+2. **품목유형 Badge**: 일관된 색상 적용 필요 시 `getItemTypeStyle` 사용
+3. **우선순위 Badge**: 표준 3단계(긴급/우선/일반) 사용 시 `getPriorityStyle` 사용
+
+---
+
+## 🎨 getPresetStyle 마이그레이션 완료 (2026-02-05 최종)
+
+### 마이그레이션 완료 파일 (22개)
+
+| 파일 | 적용 내용 |
+|------|----------|
+| `orders/OrderRegistration.tsx` | success, info preset |
+| `pricing-distribution/PriceDistributionDetail.tsx` | success preset |
+| `pricing/PricingFormClient.tsx` | purple, info, success preset |
+| `quality/InspectionManagement/InspectionList.tsx` | success, destructive preset |
+| `quality/InspectionManagement/InspectionCreate.tsx` | success, destructive preset |
+| `quality/InspectionManagement/InspectionDetail.tsx` | success, destructive preset |
+| `accounting/PurchaseManagement/index.tsx` | info preset |
+| `accounting/PurchaseManagement/PurchaseDetail.tsx` | orange preset (기존) |
+| `accounting/PurchaseManagement/PurchaseDetailModal.tsx` | orange preset (기존) |
+| `accounting/VendorManagement/CreditAnalysisModal/CreditAnalysisDocument.tsx` | info preset |
+| `quotes/QuoteRegistration.tsx` | success preset |
+| `pricing/PricingHistoryDialog.tsx` | info preset |
+| `business/construction/management/KanbanColumn.tsx` | info preset |
+| `business/construction/management/DetailCard.tsx` | warning preset |
+| `business/construction/management/StageCard.tsx` | warning preset |
+| `business/construction/management/ProjectCard.tsx` | info preset |
+| `production/WorkerScreen/WorkCard.tsx` | success, destructive preset |
+| `production/WorkerScreen/ProcessDetailSection.tsx` | warning preset |
+| `production/ProductionDashboard/index.tsx` | orange, success preset (기존) |
+| `items/ItemForm/BOMSection.tsx` | info preset (기존) |
+| `items/DynamicItemForm/sections/DynamicBOMSection.tsx` | info preset (기존) |
+| `items/ItemMasterDataManagement/tabs/MasterFieldTab/index.tsx` | info preset |
+| `customer-center/InquiryManagement/InquiryList.tsx` | warning, success preset (기존) |
+| `hr/EmployeeManagement/CSVUploadDialog.tsx` | success, destructive preset (기존) |
+
+### 마이그레이션 제외 파일 (유지)
+
+| 파일 | 제외 사유 |
+|------|----------|
+| `business/MainDashboard.tsx` | CEO 대시보드 - 다양한 데이터 시각화용 고유 색상 (achievement %, overdue days 등) |
+| `pricing/PricingListClient.tsx` | 도메인 특화 색상 체계 (SM=cyan, BENDING type 등) |
+| `business/CEODashboard/sections/TodayIssueSection.tsx` | 알림 유형별 고유 색상+아이콘 (notification_type 기반) |
+| `dev/DevToolbar.tsx` | 개발 도구 (운영 무관) |
+| `ui/status-badge.tsx` | 이미 status-config.ts 사용 중 |
+| `items/ItemDetailClient.tsx` | getItemTypeStyle 사용 (도메인 특화) |
+| `items/ItemListClient.tsx` | getItemTypeStyle 사용 (도메인 특화) |
+
+### 사용된 Preset 유형 통계
+
+| Preset | 사용 횟수 | 용도 |
+|--------|----------|------|
+| `success` | 15+ | 완료, 일치, 활성, 긍정적 상태 |
+| `info` | 10+ | 정보성 라벨, 진행 상태, 문서 타입 |
+| `warning` | 6+ | 진행중, 주의 필요, 선행 생산 |
+| `destructive` | 5+ | 오류, 불일치, 긴급 |
+| `orange` | 3+ | 품의서/지출결의서, 지연 |
+| `purple` | 2+ | 최종 확정, 특수 상태 |
+
+### 마이그레이션 효과
+
+1. **코드 일관성**: 22개 파일에서 동일한 유틸리티 함수 사용
+2. **유지보수성**: 색상 변경 시 `status-config.ts` 한 곳만 수정
+3. **가독성 향상**: `getPresetStyle('success')` vs `bg-green-100 text-green-700 border-green-200`
+4. **타입 안전성**: TypeScript로 프리셋 이름 자동완성

claudedocs/architecture/[ANALYSIS-2026-02-19] frontend-comprehensive-review.md

@@ -0,0 +1,165 @@
+# SAM ERP 프론트엔드 종합 검수 보고서
+
+> 작성일: 2026-02-19
+> 분석 범위: src/ 전체 (1,438개 TS/TSX 파일, ~314K줄)
+> 분석 방법: 5개 에이전트 병렬 분석 (코드품질, 번들/성능, 에러/UX, 아키텍처, 모바일/보안)
+
+---
+
+## 종합 스코어카드
+
+| 영역 | 점수 | 등급 | 핵심 이슈 |
+|------|------|------|-----------|
+| **코드 품질** | 7.5/10 | 🟢 양호 | TS 규율 우수, any 133건/TODO 121건 잔존 |
+| **번들/성능** | 8.5/10 | 🟢 우수 | 동적 로드 적용, tree-shaking 양호 |
+| **에러/UX 일관성** | 5.5/10 | 🟡 보통 | 에러바운더리 우수, 로딩UI/접근성 미흡 |
+| **아키텍처** | 6.5/10 | 🟡 보통 | 순환의존 없음, 상태관리 중복 |
+| **모바일 대응** | 6/10 | 🟡 보통 | 57% 반응형, 터치영역 미달 |
+| **보안** | 7/10 | 🟢 양호 | 인증 강함, CSP unsafe 허용 |
+
+**전체: 6.8/10** — 기능적으로 안정적이나, UX 일관성과 아키텍처 정리에 개선 여지
+
+---
+
+## 우선순위별 개선 항목
+
+### P0: 보안 이슈 (즉시 조치)
+
+| # | 항목 | 심각도 | 현황 | 조치 |
+|---|------|--------|------|------|
+| S-1 | CSP `unsafe-inline`/`unsafe-eval` | 🔴 높음 | middleware.ts에서 허용 중 | nonce 기반으로 전환 |
+| S-2 | `new Function()` 코드 주입 | 🔴 높음 | ComputedField.tsx에서 사용 | 사용자 입력 검증 추가 또는 safe-eval 대체 |
+| S-3 | sanitizeHTML 함수 강도 | 🟡 중간 | 5개 파일에서 사용 중 | DOMPurify 사용 여부 확인 |
+
+### P1: 아키텍처 정리 (1~2주)
+
+| # | 항목 | 현황 | 개선안 |
+|---|------|------|--------|
+| A-1 | **상태관리 중복** | ItemMasterContext + itemStore + useItemMasterStore 3중 | Zustand 하나로 통합 |
+| A-2 | **테마 중복** | ThemeContext + themeStore 병존 | Zustand로 완전 마이그레이션 |
+| A-3 | **utils 폴더 중복** | `src/utils/` (2개) + `src/lib/utils/` (11개) 병존 | `src/utils/` → `src/lib/utils/`로 통합 |
+| A-4 | **상수 산재** | constants/ 1개 파일만, 나머지 각 컴포넌트 내부 하드코딩 | 도메인별 `constants/` 정리 |
+
+### P2: 코드 품질 (2~3주)
+
+| # | 항목 | 건수 | 현황 | 조치 |
+|---|------|------|------|------|
+| Q-1 | `as any` 타입 캐스트 | 64건 | 주로 form errors 처리 | 제네릭 타입 정의 |
+| Q-2 | `: any` 타입 선언 | 48건 | API 응답/props 타입 | 인터페이스 정의 |
+| Q-3 | TODO/FIXME 누적 | 121건 (68파일) | useItemMasterStore 15건 등 | 이슈화 → 점진적 해소 |
+| Q-4 | God 컴포넌트 | 5개 | ItemMasterContext 2,200줄, MainDashboard 1,400줄 | 단계적 분리 |
+| Q-5 | 거대 훅 | 1개 | useCEODashboard 37.9KB | stats/charts/timeline 분리 |
+| Q-6 | `alert()`/`confirm()` 잔존 | 32건 | 15개 alert + 17개 confirm | ConfirmDialog/toast로 교체 |
+
+### P3: UX 일관성 (3~4주)
+
+| # | 항목 | 현황 | 목표 |
+|---|------|------|------|
+| U-1 | **로딩 UI** | 40+ 페이지에서 `"로딩 중..."` 텍스트만 사용, Skeleton 2개만 | Skeleton 기반 로딩으로 통일 |
+| U-2 | **접근성 (a11y)** | aria-label 3건, role 9건 | 주요 폼/테이블에 ARIA 추가 |
+| U-3 | **i18n 사용률** | 인프라 완성(ko/en/ja), 실제 사용 ~5% | 점진적 적용 확대 |
+| U-4 | **Zod 검증** | 2개 폼만 적용 | 신규 폼 필수, 기존은 유지 |
+| U-5 | **EmptyState 활용** | 컴포넌트 존재하나 하드코딩 "데이터 없음" 다수 | EmptyState 컴포넌트 통일 |
+
+### P4: 모바일/성능 (선택)
+
+| # | 항목 | 현황 | 조치 |
+|---|------|------|------|
+| M-1 | **반응형 커버리지** | 57% 페이지 적용 | HR/대시보드 등 미적용 페이지 보강 |
+| M-2 | **터치 영역** | Checkbox 20x20px (권장 44x44px) | 모바일 터치 타겟 확대 |
+| M-3 | **html2canvas + dom-to-image** 중복 | 2개 라이브러리 공존 | 하나로 통합 (~50-80KB 절감) |
+| M-4 | **Tiptap 동적 로딩** | 보드/팝업에서만 사용하나 번들 포함 | next/dynamic 적용 (~80-100KB 절감) |
+| M-5 | **도메인별 actions.ts 표준화** | accounting만 page-level actions, 나머지는 컴포넌트 내부 | accounting 패턴으로 통일 |
+
+---
+
+## 잘 되어있는 점 (유지 사항)
+
+### 코드 품질
+- ✅ **TypeScript 규율**: @ts-ignore 0건, @ts-nocheck 1건(레거시)
+- ✅ **console.log 관리**: 23건만 (16건은 logger 유틸리티)
+- ✅ **에러 바운더리**: 글로벌 + Protected 레벨 4개, Slack 연동
+- ✅ **Toast 시스템**: sonner 기반 1,277개 인스턴스 일관 사용
+
+### 번들/성능
+- ✅ **XLSX 동적 로드**: 버튼 클릭 시에만 ~400KB 로드
+- ✅ **대시보드 코드 스플리팅**: ~850KB 초기 번들에서 제외
+- ✅ **tree-shaking**: `import *` 0건, lodash/moment 미사용
+- ✅ **Zustand 정규화**: 체계적 상태 + Immer + selector hooks
+- ✅ **Tailwind v4**: 최신 버전, 효율적 트리셰이킹
+
+### 아키텍처
+- ✅ **순환 의존성 없음**: pages→components→ui 단방향
+- ✅ **API 계층**: buildApiUrl 43개 actions.ts 전면 적용
+- ✅ **executePaginatedAction**: 14개 파일 표준화
+
+### 보안
+- ✅ **Bot 차단**: 25개 패턴 필터링
+- ✅ **다층 인증**: Bearer Token + Authorization 헤더 + Sanctum + API Key
+- ✅ **Open Redirect 방지**: 내부 경로 검증
+- ✅ **환경변수 분리**: NEXT_PUBLIC_ 적절히 사용
+- ✅ **민감 정보 노출 없음**: console.log에 토큰/비밀번호 출력 0건
+
+---
+
+## 주요 파일 참조
+
+### God 컴포넌트 (분리 대상)
+- `src/contexts/ItemMasterContext.tsx` (2,200줄)
+- `src/components/business/MainDashboard.tsx` (1,400줄)
+- `src/hooks/useCEODashboard.ts` (37.9KB)
+
+### any 타입 집중 지역
+- `src/components/items/ItemForm/forms/parts/` (22건)
+- `src/components/items/ItemMasterDataManagement/` (18건)
+- `src/components/quotes/LocationDetailPanel.tsx` (10건)
+
+### 보안 확인 대상
+- `src/middleware.ts` (CSP 설정)
+- `src/components/**/ComputedField.tsx` (new Function)
+- sanitizeHTML 사용 파일 5개 (게시판, 팝업, 고객센터)
+
+### 상태관리 중복
+- `src/contexts/ItemMasterContext.tsx` vs `src/stores/itemStore.ts` vs `src/stores/item-master/useItemMasterStore.ts`
+- `src/contexts/ThemeContext.tsx` vs `src/stores/themeStore.ts`
+
+---
+
+## 기존 로드맵과의 관계
+
+| 기존 항목 | 상태 | 이번 분석 결과 |
+|-----------|------|---------------|
+| D-1 God 컴포넌트 분리 | ⏳ 대기 | → P2-Q4로 재확인, 여전히 필요 |
+| D-2 `as` 타입 캐스트 | 보류 | → P2-Q1/Q2로 133건 확인 (기존 ~200건에서 감소) |
+| D-6 TODO 102건 | ⏳ 대기 | → P2-Q3으로 121건 확인 (소폭 증가) |
+| A-2 DataTable 최적화 | ⏳ 대기 | → 에이전트 분석 결과 re-render 위험 낮음 (우선순위 하향) |
+
+### 신규 발견 항목 (기존 로드맵에 없었던 것)
+- **S-1~S-3**: 보안 이슈 (CSP, code injection, sanitization)
+- **A-1~A-2**: 상태관리 3중 중복
+- **U-1~U-5**: UX 일관성 전반 (로딩/접근성/i18n/빈상태)
+- **M-3~M-4**: 라이브러리 중복/동적 로딩 기회
+
+---
+
+## 실행 로드맵 요약
+
+```
+Week 1-2: P0 보안 + P1 아키텍처 정리
+  ├── CSP nonce 전환
+  ├── ComputedField 보안 패치
+  ├── 상태관리 중복 정리 (Context → Zustand)
+  └── utils 폴더 통합
+
+Week 3-4: P2 코드 품질
+  ├── any 타입 정리 (form errors 제네릭)
+  ├── alert/confirm → ConfirmDialog 교체
+  └── TODO/FIXME 이슈 정리
+
+Week 5-6: P3 UX 일관성 (선택)
+  ├── Skeleton 로딩 UI 통일
+  ├── EmptyState 활용 확대
+  └── 접근성 기본 적용
+
+이후: P4 모바일/성능 (필요 시)
+```

claudedocs/architecture/[ANALYSIS-2026-02-23] deep-analysis-util-component-zustand.md

@@ -0,0 +1,396 @@
+# SAM ERP 프로젝트 심층분석 종합 보고서
+> 분석일: 2026-02-23 | 분석 영역: Util 분리 / 컴포넌트 공통화 / Zustand 통합
+
+---
+
+## 목차
+1. [Executive Summary](#1-executive-summary)
+2. [Util 함수 분리 분석](#2-util-함수-분리-분석)
+3. [컴포넌트 공통화 분석](#3-컴포넌트-공통화-분석)
+4. [Zustand 스토어 통합 분석](#4-zustand-스토어-통합-분석)
+5. [통합 리팩토링 로드맵](#5-통합-리팩토링-로드맵)
+
+---
+
+## 1. Executive Summary
+
+### 전체 현황 스코어카드
+
+| 영역 | 현재 수준 | 주요 이슈 | 예상 절감 |
+|------|----------|----------|----------|
+| **Util 분리** | 🟡 보통 | 중복 함수 6건, 과대 파일 4개, 인라인 유틸 6패턴 | ~800줄 |
+| **컴포넌트 공통화** | 🟡 보통 | 중복 다이얼로그 5건, Detail 버전 혼재, 패턴 비일관 | ~1,500줄 |
+| **Zustand 통합** | 🟢 양호 | Context→Zustand 미전환 3건, 셀렉터 훅 미비 | 리렌더 최적화 |
+
+### Top 5 우선 조치 항목
+
+1. 🔴 **AuthContext → Zustand 마이그레이션** (전역 리렌더 제거)
+2. 🔴 **GenericCRUDDialog 추출** (5개 중복 다이얼로그 통합)
+3. 🔴 **파일 다운로드 로직 통합** (3곳 중복 → 1곳)
+4. 🟡 **dashboard/transformers.ts 분할** (1,700줄 → 도메인별 분리)
+5. 🟡 **Detail/DetailClient/DetailClientV2 정리** (버전 혼재 제거)
+
+---
+
+## 2. Util 함수 분리 분석
+
+### 2.1 현재 유틸 파일 인벤토리
+
+```
+src/lib/
+├── utils.ts                  (cn, safeJsonParse - 최소)
+├── formatters.ts             (phone, businessNumber, card, account 포맷터)
+├── print-utils.ts            (인쇄 유틸)
+├── sanitize.ts               (데이터 정제)
+├── error-reporting.ts        (에러 리포팅)
+├── utils/                    (13개 파일, ~82KB)
+│   ├── amount.ts             (금액 포맷: 원/만원)
+│   ├── date.ts               (날짜 유틸)
+│   ├── validation.ts         (Zod 스키마 - 725줄 ⚠️)
+│   ├── excel-download.ts     (엑셀 다운로드 - 528줄 ⚠️)
+│   ├── fileDownload.ts       (파일 다운로드)
+│   ├── export.ts             (엑셀 내보내기 - 중복 ⚠️)
+│   ├── search.ts             (검색/필터 파이프라인)
+│   ├── materialTransform.ts  (자재 데이터 변환)
+│   ├── menuTransform.ts      (메뉴 구조 변환)
+│   ├── menuRefresh.ts        (메뉴 새로고침)
+│   ├── status-config.ts      (상태 스타일 설정)
+│   ├── redirect-error.ts     (Next.js 리다이렉트 에러)
+│   └── locale.ts             (로케일 유틸)
+├── api/                      (25개 파일)
+│   ├── error-handler.ts      (API 에러 처리)
+│   ├── toast-utils.ts        (토스트 유틸 - 중복 ⚠️)
+│   ├── transformers.ts       (변환기 - 454줄 ⚠️)
+│   ├── dashboard/transformers.ts  (대시보드 변환 - 1,700줄 🔴)
+│   ├── execute-server-action.ts
+│   ├── execute-paginated-action.ts
+│   └── query-params.ts       (buildApiUrl - 표준화 완료)
+├── permissions/              (3개 파일)
+├── auth/                     (2개 파일)
+└── cache/                    (2개 파일)
+```
+
+### 2.2 중복 로직 탐지 (6건)
+
+#### 🔴 HIGH PRIORITY
+
+| # | 중복 항목 | 위치 | 상세 |
+|---|----------|------|------|
+| 1 | **Blob 다운로드** | `export.ts`, `excel-download.ts`, `fileDownload.ts` | 동일한 `URL.createObjectURL → link.click → revokeObjectURL` 패턴이 3곳에 존재 |
+| 2 | **날짜 문자열 생성** | `export.ts:58`, `excel-download.ts:78` | `toISOString().slice(0,10).replace(/-/g,'')` 동일 패턴, 시간 정밀도만 다름(초 vs 분) |
+| 3 | **에러 메시지 포맷** | `error-handler.ts:122`, `toast-utils.ts:106` | `getErrorMessage()` vs `formatApiError()` - 동일 로직 |
+| 4 | **숫자 포맷팅** | `amount.ts:15`, `formatters.ts:178` | `Intl.NumberFormat` vs regex 기반 - 3가지 접근법 혼재 |
+
+#### 🟡 MEDIUM PRIORITY
+
+| # | 중복 항목 | 위치 |
+|---|----------|------|
+| 5 | 엑셀 파일명 생성 | `export.ts:54` vs `excel-download.ts:78` |
+| 6 | 쿼리 파라미터 빌드 | 레거시 `URLSearchParams` 패턴 (마이그레이션 완료 상태) |
+
+### 2.3 인라인 유틸 추출 후보 (6패턴)
+
+컴포넌트 내부에 반복적으로 등장하지만 util로 분리되지 않은 패턴:
+
+| 패턴 | 발견 위치 | 영향 파일 | 추천 위치 |
+|------|----------|----------|----------|
+| 월/분기 날짜 범위 계산 | TaxInvoice, HR 페이지들 | 5+ | `lib/utils/dateRange.ts` |
+| 시간 문자열 포맷팅 | TransactionFormModal, time-picker | 4+ | `lib/utils/timeFormatter.ts` |
+| 포맷된 숫자 파싱 | VendorManagement, Withdrawal 등 | 8+ | `lib/formatters.ts` 확장 |
+| 에러 객체→메시지 변환 | attendance/page, employee/page | 3+ | `lib/utils/errorFormatter.ts` |
+| 배열 합계/카운트 reduce | 대시보드, 주문관리 등 | 6+ | `lib/utils/aggregation.ts` |
+| 파일 크기 포맷팅 | file-input.tsx | 2 | `lib/utils/fileSizeFormatter.ts` |
+
+### 2.4 과대 파일 (분할 필요)
+
+| 파일 | 줄 수 | 문제 | 분할 방안 |
+|------|-------|------|----------|
+| 🔴 `api/dashboard/transformers.ts` | **1,700+** | 10+ 도메인 변환 혼재 | `dashboard/transformers/{sales,production,quality,accounting,hr,common}.ts` |
+| 🟡 `utils/validation.ts` | 725 | 5개 아이템 타입 스키마 혼재 | `validations/{item-master-base,product,part,material,filters}.ts` |
+| 🟡 `utils/excel-download.ts` | 528 | 다운로드/내보내기/템플릿 혼재 | `{blob-download,excel-export,excel-template}.ts` |
+| 🟡 `api/transformers.ts` | 454 | 27개 export 함수 | `transformers/{pages,sections,fields,bom,templates,options}.ts` |
+
+### 2.5 미사용 유틸 (후보)
+
+| 함수 | 파일 | 상태 |
+|------|------|------|
+| `parsePhoneNumber()` | `formatters.ts:36` | import 0건 |
+| `extractNumbers()` | `formatters.ts:220` | import 0건 |
+| `formatPersonalNumber()` | `formatters.ts:84` | 실제 사용은 `formatPersonalNumberMasked` |
+
+---
+
+## 3. 컴포넌트 공통화 분석
+
+### 3.1 현재 컴포넌트 계층 구조
+
+```
+src/components/
+├── ui/          (49개 - Radix UI 래퍼)
+├── atoms/       (3개 - 최소 단위)
+├── molecules/   (9개 - 복합 폼/표시)
+├── organisms/   (11개 - 비즈니스 컴포넌트)
+├── templates/   (2+1개 - UniversalListPage, IntegratedDetailTemplate, IntegratedListTemplateV2)
+├── accounting/  (18개 도메인 폴더, 100+ 컴포넌트)
+├── settings/    (12개 도메인 폴더)
+└── [기타 도메인] (15+ 폴더)
+```
+
+### 3.2 중복 컴포넌트 패턴 (핵심 발견)
+
+#### 🔴 CRITICAL: 단순 CRUD 다이얼로그 중복 (5건)
+
+거의 동일한 구조: Dialog 래퍼 → 폼 필드 → 유효성 검증 → 제출/취소 버튼
+
+| 컴포넌트 | 줄 수 | 차이점 |
+|----------|-------|--------|
+| `settings/RankManagement/RankDialog.tsx` | 89 | 라벨명만 다름 |
+| `settings/TitleManagement/TitleDialog.tsx` | 90 | 라벨명만 다름 |
+| `settings/PermissionManagement/PermissionDialog.tsx` | ~90 | 라벨명만 다름 |
+| `settings/NotificationSettings/ItemSettingsDialog.tsx` | ~90 | 라벨명만 다름 |
+| `accounting/VendorManagement/CreditAnalysisModal/` | ~100 | 약간 복잡 |
+
+**해결안**: `GenericCRUDDialog<T>` 제네릭 컴포넌트 생성
+```typescript
+// src/components/molecules/GenericCRUDDialog.tsx
+interface GenericCRUDDialogProps<T> {
+  isOpen: boolean;
+  onOpenChange: (open: boolean) => void;
+  mode: 'add' | 'edit';
+  title: string;
+  fields: FormFieldDefinition[];
+  data?: T;
+  onSubmit: (data: T) => Promise<void>;
+}
+```
+→ **~400줄 절감**
+
+#### 🔴 CRITICAL: Detail 파일 버전 혼재
+
+한 엔티티에 대해 여러 버전의 Detail 파일이 공존:
+
+| 엔티티 | 파일들 | 문제 |
+|--------|--------|------|
+| BadDebt | `BadDebtDetail.tsx`, `BadDebtDetailClientV2.tsx` | V2 마이그레이션 미완 |
+| Withdrawal | `WithdrawalDetailClientV2.tsx` | ClientV2 접미사 |
+| Deposit | `DepositDetailClientV2.tsx` | ClientV2 접미사 |
+| Vendor | `VendorDetail.tsx`, `VendorDetailClient.tsx` | 두 파일 공존 |
+
+→ **단일 소스로 통합 필요, ~300줄 절감**
+
+#### 🟡 HIGH: 리스트 페이지 설정 중복
+
+`UniversalListPage`로 통합은 잘 되어있으나, 설정(config) 코드가 각 페이지에 반복:
+
+| 반복 요소 | 발견 위치 | 해결안 |
+|-----------|----------|--------|
+| 상태 관리 (data, filters, pagination) | Sales, Purchase, Vendor 등 | 설정 파일 분리 |
+| DateRange 선택기 | 8+ 회계 페이지 | `useDateRange()` 훅 표준화 |
+| Stats 계산 useMemo | 대부분의 리스트 페이지 | `DataStatsCard<T>` 추출 |
+
+→ **~500줄 절감**
+
+### 3.3 재사용률 분석
+
+#### 높은 재사용 (Good)
+- **UniversalListPage**: 40+ 페이지 (우수)
+- **IntegratedDetailTemplate**: 20+ 상세 페이지
+- **FormField**: 50+ 폼
+
+#### 활용 부족 (Should Use More)
+- **SearchableSelectionModal**: 실제 3곳만 사용 → 더 광범위 적용 가능
+- **StandardDialog**: 존재하지만 단순 다이얼로그들이 미사용
+- **MobileCard**: 정의되었지만 비일관적 사용
+
+### 3.4 패턴 비일관성
+
+| 패턴 | 현재 상태 | 표준화 방향 |
+|------|----------|------------|
+| 날짜 범위 선택 | 3가지 방식 혼재 (컴포넌트/훅/인라인) | `useDateRange()` + `<DateRangeSelector />` |
+| 검색/필터 | 3가지 경쟁 패턴 (A: UniversalListPage, B: 커스텀 useState, C: IntegratedListTemplateV2) | Pattern A로 통일 |
+| 모달 vs 페이지 | VendorDetail→풀페이지, PurchaseDetail→모달 혼재 | 도메인별 기준 확립 |
+
+### 3.5 추출 필요 공유 컴포넌트
+
+| 컴포넌트 | 사용처 | 설명 |
+|----------|--------|------|
+| `LineItemsTable<T>` | SalesDetail, PurchaseDetail | 품목 추가/삭제/계산 테이블 (~150줄×2 절감) |
+| `DataStatsCard<T>` | 회계 리스트 페이지들 | 유연한 통계 표시 카드 |
+| `DocumentTemplate` | CreditAnalysis, InspectionReport | 인쇄용 문서 래퍼 (헤더/푸터/워터마크) |
+| `DataTableWithActions` | 대부분의 리스트 | 페이지네이션+선택+액션 통합 |
+
+---
+
+## 4. Zustand 스토어 통합 분석
+
+### 4.1 현재 스토어 인벤토리 (7개)
+
+| 스토어 | 파일 | 줄 수 | 미들웨어 | 용도 |
+|--------|------|-------|---------|------|
+| `useItemMasterStore` | `stores/item-master/useItemMasterStore.ts` | 1,150 | devtools, immer | 품목기준관리 정규화 상태 |
+| `useMasterDataStore` | `stores/masterDataStore.ts` | 450 | devtools | 동적 폼 설정 캐싱 |
+| `useMenuStore` | `stores/menuStore.ts` | ~100 | persist | 사이드바/메뉴 상태 |
+| `useFavoritesStore` | `stores/favoritesStore.ts` | ~100 | persist + custom storage | 즐겨찾기 (최대 10개) |
+| `useThemeStore` | `stores/themeStore.ts` | ~50 | persist | 테마 (light/dark/senior) |
+| `useTableColumnStore` | `stores/useTableColumnStore.ts` | ~100 | persist + custom storage | 테이블 컬럼 가시성/너비 |
+| `useCalendarScheduleStore` | `stores/useCalendarScheduleStore.ts` | ~100 | devtools | 캘린더 일정 연도별 캐싱 |
+
+### 4.2 핵심 발견: Context → Zustand 미전환 (3건)
+
+#### 🔴 #1: AuthContext (최우선)
+
+| 항목 | 현재 | 문제 |
+|------|------|------|
+| **위치** | `/src/contexts/AuthContext.tsx` (278줄) | React Context + useState |
+| **상태** | users[], currentUser, roles, tenants | Provider 리렌더 전파 |
+| **localStorage** | 수동 동기화 (line 162-190) | Zustand persist가 자동 처리 가능 |
+| **영향** | 사이드바, 대시보드, 모든 인증 페이지 | 상태 변경 시 전체 앱 리렌더 |
+
+**전환 방안**:
+```typescript
+// /src/stores/authStore.ts
+export const useAuthStore = create<AuthState>()(
+  persist(
+    devtools((set) => ({
+      currentUser: null,
+      setCurrentUser: (user) => set({ currentUser: user }),
+      // ... 기타 액션
+    })),
+    { name: 'mes-currentUser' }
+  )
+);
+```
+
+#### 🟡 #2: ItemMasterContext (중복 제거)
+
+| 항목 | 현재 | 문제 |
+|------|------|------|
+| **Context** | `contexts/ItemMasterContext.tsx` (27,922 토큰) | useState 13개+ 상태 |
+| **Zustand** | `stores/item-master/useItemMasterStore.ts` (1,150줄) | 유사 데이터 관리 |
+| **중복** | 양쪽에서 품목 마스터 데이터 관리 | 캐싱/API 레이어 분리 |
+
+→ **Context를 Zustand 스토어로 통합, Context는 얇은 래퍼로만 유지**
+
+#### 🟡 #3: PermissionContext
+
+| 항목 | 현재 | 문제 |
+|------|------|------|
+| **위치** | `contexts/PermissionContext.tsx` | 순수 데이터/셀렉터 패턴 |
+| **적합도** | Zustand 셀렉터 패턴에 완벽 부합 | Provider 불필요 |
+
+### 4.3 셀렉터 훅 미비 (성능 이슈)
+
+| 스토어 | 셀렉터 훅 | 문제 |
+|--------|----------|------|
+| ✅ `masterDataStore` | `usePageConfig()`, `usePageConfigLoading()` 등 | 양호 |
+| ❌ `useTableColumnStore` | 없음 - 전체 스토어 구독 | 불필요한 리렌더 |
+| ❌ `useMenuStore` | 없음 - 전체 스토어 구독 | 사이드바 토글이 모든 구독자 리렌더 |
+| ❌ `useThemeStore` | 없음 | 경미 |
+
+**해결 패턴**:
+```typescript
+// ✅ 추가 필요
+export const useTableSettings = (pageId: string) =>
+  useTableColumnStore((state) => state.pageSettings[pageId]);
+
+export const useMenuActiveId = () =>
+  useMenuStore((state) => state.activeMenu);
+
+export const useSidebarCollapsed = () =>
+  useMenuStore((state) => state.sidebarCollapsed);
+```
+
+### 4.4 Custom Storage 중복
+
+`favoritesStore`와 `tableColumnStore`에서 동일한 사용자별 localStorage 래퍼가 반복:
+
+```typescript
+// 두 파일 모두 동일 패턴 반복:
+const customStorage = {
+  getItem: (name) => { /* userId 기반 키 생성 */ },
+  setItem: (name, value) => { /* userId 기반 키로 저장 */ },
+  removeItem: (name) => { /* userId 기반 키로 삭제 */ },
+};
+```
+
+**해결안**: `/src/lib/storage/user-scoped-storage.ts` 추출
+```typescript
+export function createUserScopedStorage(prefix: string): StateStorage {
+  return { getItem, setItem, removeItem };
+}
+```
+
+### 4.5 누락된 스토어 기회
+
+| 스토어 | 용도 | 현재 상태 |
+|--------|------|----------|
+| 🔴 `useUIStore` | 전역 모달/노티/로딩 | 각 컴포넌트에서 로컬 관리 |
+| 🟡 글로벌 필터 상태 | 리스트 페이지 공통 필터 | useState로 산재 |
+
+---
+
+## 5. 통합 리팩토링 로드맵
+
+### Phase 1: 즉시 (1주)
+
+| 작업 | 영역 | 영향도 | 난이도 |
+|------|------|--------|--------|
+| AuthContext → Zustand 마이그레이션 | Zustand | 🔴 전역 리렌더 제거 | 중 |
+| GenericCRUDDialog 추출 (5개 다이얼로그 통합) | 컴포넌트 | 🔴 ~400줄 절감 | 저 |
+| Blob 다운로드 로직 통합 (3곳→1곳) | Util | 🔴 중복 제거 | 저 |
+| 에러 메시지 포맷 통합 (`formatApiError` 제거) | Util | 🟡 API 레이어 정리 | 저 |
+| Zustand 셀렉터 훅 추가 (3개 스토어) | Zustand | 🟡 리렌더 최적화 | 저 |
+
+### Phase 2: 단기 (2~3주)
+
+| 작업 | 영역 | 영향도 | 난이도 |
+|------|------|--------|--------|
+| `dashboard/transformers.ts` 분할 (1,700줄) | Util | 🟡 유지보수성 | 중 |
+| Detail 파일 버전 정리 (V2 통합) | 컴포넌트 | 🟡 ~300줄 절감 | 중 |
+| `LineItemsTable<T>` organism 추출 | 컴포넌트 | 🟡 Sales/Purchase 공통화 | 중 |
+| Custom Storage 유틸 추출 | Zustand | 🟡 DRY | 저 |
+| 날짜 범위 선택 표준화 | 컴포넌트 | 🟡 패턴 통일 | 중 |
+
+### Phase 3: 중기 (3~4주)
+
+| 작업 | 영역 | 영향도 | 난이도 |
+|------|------|--------|--------|
+| `validation.ts` 분할 (725줄) | Util | 🟢 유지보수성 | 저 |
+| ItemMasterContext → Zustand 통합 | Zustand | 🟡 중복 제거 | 고 |
+| IntegratedListTemplateV2 폐기 | 컴포넌트 | 🟢 레거시 제거 | 중 |
+| 인라인 유틸 추출 (6패턴) | Util | 🟢 코드 품질 | 저 |
+| 미사용 유틸 함수 정리 | Util | 🟢 코드 청결 | 저 |
+
+### Phase 4: 장기 (4주+)
+
+| 작업 | 영역 | 영향도 | 난이도 |
+|------|------|--------|--------|
+| PermissionContext → Zustand | Zustand | 🟢 아키텍처 통일 | 중 |
+| DocumentTemplate organism 추출 | 컴포넌트 | 🟢 인쇄 공통화 | 중 |
+| useUIStore 생성 (전역 UI 상태) | Zustand | 🟢 모달/노티 통합 | 중 |
+| 숫자 포맷팅 API 표준화 | Util | 🟢 일관성 | 저 |
+
+---
+
+## 부록: 핵심 파일 참조
+
+### 리팩토링 대상 (Util)
+- `/src/lib/utils/export.ts` - 중복 제거 대상
+- `/src/lib/utils/excel-download.ts` - 분할 대상 (528줄)
+- `/src/lib/utils/validation.ts` - 분할 대상 (725줄)
+- `/src/lib/api/dashboard/transformers.ts` - 분할 대상 (1,700줄)
+- `/src/lib/api/toast-utils.ts` - `formatApiError` 제거 대상
+
+### 리팩토링 대상 (컴포넌트)
+- `/src/components/settings/RankManagement/RankDialog.tsx` - GenericCRUDDialog로 대체
+- `/src/components/settings/TitleManagement/TitleDialog.tsx` - GenericCRUDDialog로 대체
+- `/src/components/accounting/BadDebtCollection/BadDebtDetailClientV2.tsx` - 버전 통합
+- `/src/components/accounting/WithdrawalManagement/WithdrawalDetailClientV2.tsx` - 버전 통합
+- `/src/components/accounting/DepositManagement/DepositDetailClientV2.tsx` - 버전 통합
+
+### 리팩토링 대상 (Zustand)
+- `/src/contexts/AuthContext.tsx` → `/src/stores/authStore.ts`
+- `/src/contexts/ItemMasterContext.tsx` → `/src/stores/item-master/` 통합
+- `/src/stores/useTableColumnStore.ts` - 셀렉터 훅 추가
+- `/src/stores/menuStore.ts` - 셀렉터 훅 추가
+- `/src/stores/favoritesStore.ts` - custom storage 유틸 추출

claudedocs/architecture/[GUIDE] component-tier-definition.md

@@ -0,0 +1,153 @@
+# Component Tier 정의
+
+> SAM 프로젝트의 컴포넌트 계층(tier) 기준 정의.
+> 새 컴포넌트 작성 시 어디에 배치할지 판단하는 기준 문서.
+
+## Tier 구조 요약
+
+```
+ui          원시 빌딩블록 (HTML 래퍼, 단일 기능)
+  ↓ 조합
+atoms       최소 단위 UI 조각 (ui 1~2개 조합)
+  ↓ 조합
+molecules   의미 있는 UI 패턴 (atoms/ui 여러 개 조합)
+  ↓ 조합
+organisms   페이지 섹션 단위 (molecules/atoms 조합, 레이아웃 포함)
+  ↓ 사용
+domain      도메인별 비즈니스 컴포넌트 (organisms/molecules 사용)
+```
+
+## Tier별 정의
+
+### ui (원시 빌딩블록)
+| 항목 | 기준 |
+|------|------|
+| 위치 | `src/components/ui/` |
+| 역할 | HTML 요소를 감싼 최소 단위. 스타일링 + 접근성만 담당 |
+| 특징 | 비즈니스 로직 없음, 범용적, Radix UI 래퍼 포함 |
+| 예시 | Button, Input, Select, Badge, Dialog, DatePicker, EmptyState |
+| 판단 기준 | "이 컴포넌트가 다른 프로젝트에 그대로 복사해도 동작하는가?" → Yes면 ui |
+
+### atoms (최소 UI 조각)
+| 항목 | 기준 |
+|------|------|
+| 위치 | `src/components/atoms/` |
+| 역할 | ui 1~2개를 조합한 작은 패턴. 단일 목적 |
+| 특징 | props 2~5개, 상태 관리 최소 |
+| 예시 | BadgeSm, TabChip, ScrollableButtonGroup |
+| 판단 기준 | "ui 하나로는 부족하지만, 독립적인 의미 단위인가?" → Yes면 atoms |
+
+### molecules (의미 있는 UI 패턴)
+| 항목 | 기준 |
+|------|------|
+| 위치 | `src/components/molecules/` |
+| 역할 | atoms/ui 여러 개를 조합하여 하나의 기능 패턴을 구성 |
+| 특징 | Label + Input + Error 같은 조합, 내부 상태 가능 |
+| 예시 | FormField, StatusBadge, DateRangeSelector, StandardDialog, TableActions |
+| 판단 기준 | "여러 ui/atoms의 조합이고, 재사용 가능한 패턴인가?" → Yes면 molecules |
+
+### organisms (페이지 섹션)
+| 항목 | 기준 |
+|------|------|
+| 위치 | `src/components/organisms/` |
+| 역할 | 페이지의 독립적인 섹션. molecules/atoms를 조합하여 레이아웃 포함 |
+| 특징 | 데이터 테이블, 검색 필터, 폼 섹션 등 페이지 구성 단위 |
+| 예시 | DataTable, PageHeader, StatCards, FormSection, SearchableSelectionModal |
+| 판단 기준 | "페이지에서 하나의 영역으로 독립 가능한가?" → Yes면 organisms |
+
+### common (공용 페이지/레이아웃)
+| 항목 | 기준 |
+|------|------|
+| 위치 | `src/components/common/` |
+| 역할 | 에러 페이지, 권한 없음 페이지 등 전역 공통 화면 |
+| 특징 | 라우터 사용, 전체 페이지 레이아웃 |
+| 예시 | AccessDenied, EmptyPage, ServerErrorPage |
+| 판단 기준 | "전체 화면을 차지하는 공통 페이지인가?" → Yes면 common |
+
+### layout (레이아웃 구조)
+| 항목 | 기준 |
+|------|------|
+| 위치 | `src/components/layout/` |
+| 역할 | 앱 전체 레이아웃 골격 (사이드바, 헤더, 네비게이션) |
+| 예시 | AuthenticatedLayout, Sidebar, TopNav |
+
+### dev (개발 도구)
+| 항목 | 기준 |
+|------|------|
+| 위치 | `src/components/dev/` |
+| 역할 | 개발 환경 전용 도구 (프로덕션 미포함) |
+| 예시 | DevToolbar |
+
+### domain (도메인 비즈니스)
+| 항목 | 기준 |
+|------|------|
+| 위치 | `src/components/{도메인명}/` (hr, sales, accounting 등) |
+| 역할 | 특정 도메인의 비즈니스 로직이 포함된 컴포넌트 |
+| 특징 | API 호출, 도메인 타입, 비즈니스 규칙 포함 |
+| 예시 | EmployeeManagement, OrderRegistration, BillDetail |
+| 판단 기준 | "특정 도메인에서만 사용되는가?" → Yes면 domain |
+
+## 자주 혼동되는 케이스
+
+| 상황 | 올바른 tier | 이유 |
+|------|-------------|------|
+| EmptyState (프리셋/variant 있음) | **ui** | 범용 빌딩블록, 비즈니스 로직 없음 |
+| StatusBadge (icon/dot/색상 커스텀) | **molecules** | Badge + BadgeSm 조합, DataTable 연동 |
+| ConfirmDialog (삭제/저장 확인) | **ui** | AlertDialog 래퍼, 범용적 |
+| StandardDialog (범용 컨테이너) | **molecules** | Dialog + Header + Footer 조합 패턴 |
+| DataTable (정렬/페이지네이션/선택) | **organisms** | 페이지 섹션 단위, 다수 하위 컴포넌트 |
+| SearchableSelectionModal | **organisms** | 검색+선택 완결 기능, 독립 섹션 |
+
+## 중복 방지 규칙
+
+1. **새 컴포넌트 작성 전**: 같은 이름/기능이 다른 tier에 이미 있는지 확인
+2. **ui에 이미 있으면**: molecules/organisms에 동일 컴포넌트 만들지 않음. 필요하면 ui를 확장
+3. **re-export 허용**: organisms/index.ts에서 ui 컴포넌트를 re-export 가능 (편의성)
+4. **확인(Confirm) 다이얼로그**: `ui/confirm-dialog.tsx` 하나만 사용 (52개 파일 사용 중)
+
+## StatusBadge 역할 구분
+
+이름이 같지만 tier와 용도가 다른 두 컴포넌트. **둘 다 유지**.
+
+### `ui/status-badge.tsx` — 범용 상태 배지
+
+| 항목 | 내용 |
+|------|------|
+| import | `import { StatusBadge } from '@/components/ui/status-badge'` |
+| 용도 | `createStatusConfig`와 연동하는 **config 기반** 상태 표시 |
+| API | `children` 또는 `status + config` 자동 라벨/스타일 |
+| 특화 기능 | `mode` (badge/text), `ConfiguredStatusBadge` 제네릭 |
+| 사용 예시 | 템플릿/유틸과 연동하는 범용 상태 표시 |
+
+```tsx
+// config 기반 사용
+<StatusBadge status="pending" config={APPROVAL_STATUS_CONFIG} />
+
+// children 기반 사용
+<StatusBadge variant="success">완료</StatusBadge>
+```
+
+### `molecules/StatusBadge.tsx` — DataTable 특화 배지
+
+| 항목 | 내용 |
+|------|------|
+| import | `import { StatusBadge } from '@/components/molecules/StatusBadge'` |
+| 용도 | DataTable 셀에서 상태를 **아이콘/도트와 함께** 표시 |
+| API | `label` 필수, `variant`로 색상 지정 |
+| 특화 기능 | `icon` (LucideIcon), `showDot`, 커스텀 `bgColor/textColor/borderColor` |
+| 기반 | Badge + BadgeSm 조합 (size="sm"일 때 BadgeSm으로 자동 전환) |
+
+```tsx
+// DataTable 셀 렌더링
+<StatusBadge label="승인완료" variant="success" showDot />
+<StatusBadge label="긴급" variant="danger" icon={AlertCircle} />
+```
+
+### 선택 기준
+
+| 상황 | 사용할 컴포넌트 |
+|------|----------------|
+| `createStatusConfig` 결과와 연동 | **ui** StatusBadge |
+| DataTable 컬럼 셀 렌더링 | **molecules** StatusBadge |
+| 아이콘이나 도트가 필요한 배지 | **molecules** StatusBadge |
+| 단순 텍스트 상태 표시 (badge/text 모드) | **ui** StatusBadge |

claudedocs/architecture/[IMPL-2026-02-05] detail-hooks-migration-plan.md

@@ -0,0 +1,304 @@
+# 상세 페이지 훅 마이그레이션 계획서
+
+> 작성일: 2026-02-05
+> 상태: 계획 수립
+
+---
+
+## 1. 개요
+
+### 1.1 목적
+- 상세/등록/수정 페이지의 반복 코드를 공통 훅으로 통합
+- 코드 일관성 확보 및 유지보수성 향상
+- 서비스 런칭 전 기술 부채 최소화
+
+### 1.2 생성된 공통 훅
+| 훅 | 위치 | 역할 |
+|----|------|------|
+| `useDetailPageState` | `src/hooks/useDetailPageState.ts` | 페이지 상태 관리 (mode, id, navigation) |
+| `useDetailData` | `src/hooks/useDetailData.ts` | 데이터 로딩 + 로딩/에러 상태 |
+| `useCRUDHandlers` | `src/hooks/useCRUDHandlers.ts` | 등록/수정/삭제 + toast/redirect |
+| `useDetailPermissions` | `src/hooks/useDetailPermissions.ts` | 권한 체크 |
+
+### 1.3 테스트 완료
+- [x] `BillDetail.tsx` → `BillDetailV2.tsx` 마이그레이션 성공
+- [x] 조회/수정/등록 모드 정상 작동 확인
+- [x] 유효성 검사 정상 작동 확인
+
+---
+
+## 2. 마이그레이션 대상
+
+### 2.1 전체 현황
+| 구분 | 개수 | 비고 |
+|------|------|------|
+| IntegratedDetailTemplate 사용 | 47개 | 훅 마이그레이션 대상 |
+| 레거시/커스텀 패턴 | 36개 | 별도 검토 (이번 범위 외) |
+| **총계** | 83개 | |
+
+### 2.2 복잡도별 분류
+| 복잡도 | 기준 | 개수 |
+|--------|------|------|
+| 단순 | < 200줄, useState 3~4개 | 12개 |
+| 보통 | 200~500줄, useState 5~7개 | 18개 |
+| 복잡 | > 500줄, useState 8~11개 | 17개 |
+
+---
+
+## 3. 도메인별 대상 목록
+
+### 3.1 회계관리 (10개)
+
+| # | 파일 | 라인 | 복잡도 | 상태 |
+|---|------|------|--------|------|
+| 1 | `accounting/BadDebtCollection/BadDebtDetail.tsx` | 966 | 복잡 | ⬜ |
+| 2 | `accounting/BillManagement/BillDetail.tsx` | 474 | 보통 | ✅ 완료 |
+| 3 | `accounting/CardTransactionInquiry/CardTransactionDetailClient.tsx` | 138 | 단순 | ⬜ |
+| 4 | `accounting/DepositManagement/DepositDetailClientV2.tsx` | 143 | 단순 | ⬜ |
+| 5 | `accounting/PurchaseManagement/PurchaseDetail.tsx` | 698 | 복잡 | ⬜ |
+| 6 | `accounting/SalesManagement/SalesDetail.tsx` | 581 | 복잡 | ⬜ |
+| 7 | `accounting/VendorLedger/VendorLedgerDetail.tsx` | 385 | 보통 | ⬜ |
+| 8 | `accounting/VendorManagement/VendorDetail.tsx` | 683 | 복잡 | ⬜ |
+| 9 | `accounting/VendorManagement/VendorDetailClient.tsx` | 585 | 복잡 | ⬜ |
+| 10 | `accounting/WithdrawalManagement/WithdrawalDetail.tsx` | 327 | 보통 | ⬜ |
+
+### 3.2 건설관리 (13개)
+
+| # | 파일 | 라인 | 복잡도 | 상태 |
+|---|------|------|--------|------|
+| 1 | `construction/bidding/BiddingDetailForm.tsx` | 544 | 복잡 | ⬜ |
+| 2 | `construction/contract/ContractDetailForm.tsx` | 546 | 복잡 | ⬜ |
+| 3 | `construction/estimates/EstimateDetailForm.tsx` | 763 | 복잡 | ⬜ |
+| 4 | `construction/handover-report/HandoverReportDetailForm.tsx` | 699 | 복잡 | ⬜ |
+| 5 | `construction/issue-management/IssueDetailForm.tsx` | 627 | 복잡 | ⬜ |
+| 6 | `construction/item-management/ItemDetailClient.tsx` | 486 | 보통 | ⬜ |
+| 7 | `construction/labor-management/LaborDetailClientV2.tsx` | 120 | 단순 | ⬜ |
+| 8 | `construction/management/ConstructionDetailClient.tsx` | 739 | 복잡 | ⬜ |
+| 9 | `construction/order-management/OrderDetailForm.tsx` | 275 | 보통 | ⬜ |
+| 10 | `construction/pricing-management/PricingDetailClientV2.tsx` | 134 | 단순 | ⬜ |
+| 11 | `construction/progress-billing/ProgressBillingDetailForm.tsx` | 193 | 단순 | ⬜ |
+| 12 | `construction/site-management/SiteDetailForm.tsx` | 385 | 보통 | ⬜ |
+| 13 | `construction/structure-review/StructureReviewDetailForm.tsx` | 392 | 보통 | ⬜ |
+
+### 3.3 기타 도메인 (24개)
+
+#### 고객센터 (3개)
+| # | 파일 | 라인 | 복잡도 | 상태 |
+|---|------|------|--------|------|
+| 1 | `customer-center/EventManagement/EventDetail.tsx` | 101 | 단순 | ⬜ |
+| 2 | `customer-center/InquiryManagement/InquiryDetail.tsx` | 357 | 보통 | ⬜ |
+| 3 | `customer-center/NoticeManagement/NoticeDetail.tsx` | 101 | 단순 | ⬜ |
+
+#### 인사관리 (1개)
+| # | 파일 | 라인 | 복잡도 | 상태 |
+|---|------|------|--------|------|
+| 1 | `hr/EmployeeManagement/EmployeeDetail.tsx` | 221 | 단순 | ⬜ |
+
+#### 자재관리 (2개)
+| # | 파일 | 라인 | 복잡도 | 상태 |
+|---|------|------|--------|------|
+| 1 | `material/ReceivingManagement/ReceivingDetail.tsx` | ~350 | 보통 | ⬜ |
+| 2 | `material/StockStatus/StockStatusDetail.tsx` | ~300 | 보통 | ⬜ |
+
+#### 주문관리 (2개)
+| # | 파일 | 라인 | 복잡도 | 상태 |
+|---|------|------|--------|------|
+| 1 | `orders/OrderSalesDetailEdit.tsx` | 735 | 복잡 | ⬜ |
+| 2 | `orders/OrderSalesDetailView.tsx` | 668 | 복잡 | ⬜ |
+
+#### 출고관리 (2개)
+| # | 파일 | 라인 | 복잡도 | 상태 |
+|---|------|------|--------|------|
+| 1 | `outbound/ShipmentManagement/ShipmentDetail.tsx` | 670 | 복잡 | ⬜ |
+| 2 | `outbound/VehicleDispatchManagement/VehicleDispatchDetail.tsx` | 180 | 단순 | ⬜ |
+
+#### 생산관리 (1개)
+| # | 파일 | 라인 | 복잡도 | 상태 |
+|---|------|------|--------|------|
+| 1 | `production/WorkOrders/WorkOrderDetail.tsx` | 531 | 복잡 | ⬜ |
+
+#### 품질관리 (1개)
+| # | 파일 | 라인 | 복잡도 | 상태 |
+|---|------|------|--------|------|
+| 1 | `quality/InspectionManagement/InspectionDetail.tsx` | 949 | 복잡 | ⬜ |
+
+#### 설정 (2개)
+| # | 파일 | 라인 | 복잡도 | 상태 |
+|---|------|------|--------|------|
+| 1 | `settings/PermissionManagement/PermissionDetail.tsx` | 455 | 보통 | ⬜ |
+| 2 | `settings/PopupManagement/PopupDetailClientV2.tsx` | 198 | 단순 | ⬜ |
+
+#### 거래처 (1개)
+| # | 파일 | 라인 | 복잡도 | 상태 |
+|---|------|------|--------|------|
+| 1 | `clients/ClientDetailClientV2.tsx` | 252 | 단순 | ⬜ |
+
+#### 기타 (9개)
+| # | 파일 | 라인 | 복잡도 | 상태 |
+|---|------|------|--------|------|
+| 1 | `board/BoardManagement/BoardDetail.tsx` | 119 | 단순 | ⬜ |
+| 2 | `process-management/ProcessDetail.tsx` | 346 | 보통 | ⬜ |
+| 3 | `process-management/StepDetail.tsx` | 143 | 단순 | ⬜ |
+| 4 | `settings/AccountManagement/AccountDetail.tsx` | 355 | 보통 | ⬜ |
+| 5 | `accounting/DepositManagement/DepositDetail.tsx` | 327 | 보통 | ⬜ |
+| 6 | `clients/ClientDetail.tsx` | 253 | 보통 | ⬜ |
+| 7 | `construction/labor-management/LaborDetailClient.tsx` | 471 | 보통 | ⬜ |
+| 8 | `construction/pricing-management/PricingDetailClient.tsx` | 464 | 보통 | ⬜ |
+| 9 | `quotes/LocationDetailPanel.tsx` | 826 | 복잡 | ⬜ |
+
+---
+
+## 4. 작업 방식
+
+### 4.1 Git 브랜치 전략
+```
+main
+  └── feature/detail-hooks-migration
+        ├── 회계관리 커밋
+        ├── 건설관리 커밋
+        └── 기타 도메인 커밋
+```
+
+### 4.2 파일별 작업 순서
+1. 파일 읽기 및 현재 패턴 파악
+2. `useDetailData` 적용 (데이터 로딩 부분)
+3. `useCRUDHandlers` 적용 (CRUD 핸들러 부분)
+4. 개별 useState → 통합 formData 객체로 변환 (선택)
+5. 기능 테스트
+6. 커밋
+
+### 4.3 적용할 변경 패턴
+
+#### Before (기존)
+```tsx
+const [data, setData] = useState(null);
+const [isLoading, setIsLoading] = useState(true);
+const [error, setError] = useState(null);
+
+useEffect(() => {
+  fetchData(id).then(result => {
+    if (result.success) setData(result.data);
+    else setError(result.error);
+  }).finally(() => setIsLoading(false));
+}, [id]);
+
+const handleSubmit = async () => {
+  const result = await updateData(id, formData);
+  if (result.success) {
+    toast.success('저장되었습니다.');
+    router.push('/list');
+  } else {
+    toast.error(result.error);
+  }
+};
+```
+
+#### After (신규)
+```tsx
+const { data, isLoading, error } = useDetailData(id, fetchData);
+
+const { handleUpdate, isSubmitting } = useCRUDHandlers({
+  onUpdate: updateData,
+  successRedirect: '/list',
+  successMessages: { update: '저장되었습니다.' },
+});
+```
+
+---
+
+## 5. 일정 계획
+
+| Phase | 대상 | 파일 수 | 예상 기간 |
+|-------|------|---------|----------|
+| Phase 1 | 회계관리 | 10개 | 1일 |
+| Phase 2 | 건설관리 | 13개 | 1.5일 |
+| Phase 3 | 기타 도메인 | 24개 | 2일 |
+| Phase 4 | 통합 테스트 | - | 1일 |
+| **총계** | | **47개** | **약 5~6일** |
+
+---
+
+## 6. 체크리스트
+
+### 6.1 사전 준비
+- [x] 공통 훅 4개 생성 완료
+- [x] 테스트 마이그레이션 (BillDetail) 완료
+- [x] 계획서 작성
+- [ ] 브랜치 생성
+
+### 6.2 Phase 1: 회계관리 (0/10)
+- [ ] BadDebtDetail.tsx
+- [x] BillDetail.tsx ✅
+- [ ] CardTransactionDetailClient.tsx
+- [ ] DepositDetailClientV2.tsx
+- [ ] PurchaseDetail.tsx
+- [ ] SalesDetail.tsx
+- [ ] VendorLedgerDetail.tsx
+- [ ] VendorDetail.tsx
+- [ ] VendorDetailClient.tsx
+- [ ] WithdrawalDetail.tsx
+
+### 6.3 Phase 2: 건설관리 (0/13)
+- [ ] BiddingDetailForm.tsx
+- [ ] ContractDetailForm.tsx
+- [ ] EstimateDetailForm.tsx
+- [ ] HandoverReportDetailForm.tsx
+- [ ] IssueDetailForm.tsx
+- [ ] ItemDetailClient.tsx
+- [ ] LaborDetailClientV2.tsx
+- [ ] ConstructionDetailClient.tsx
+- [ ] OrderDetailForm.tsx
+- [ ] PricingDetailClientV2.tsx
+- [ ] ProgressBillingDetailForm.tsx
+- [ ] SiteDetailForm.tsx
+- [ ] StructureReviewDetailForm.tsx
+
+### 6.4 Phase 3: 기타 도메인 (0/24)
+- [ ] EventDetail.tsx
+- [ ] InquiryDetail.tsx
+- [ ] NoticeDetail.tsx
+- [ ] EmployeeDetail.tsx
+- [ ] ReceivingDetail.tsx
+- [ ] StockStatusDetail.tsx
+- [ ] OrderSalesDetailEdit.tsx
+- [ ] OrderSalesDetailView.tsx
+- [ ] ShipmentDetail.tsx
+- [ ] VehicleDispatchDetail.tsx
+- [ ] WorkOrderDetail.tsx
+- [ ] InspectionDetail.tsx
+- [ ] PermissionDetail.tsx
+- [ ] PopupDetailClientV2.tsx
+- [ ] ClientDetailClientV2.tsx
+- [ ] BoardDetail.tsx
+- [ ] ProcessDetail.tsx
+- [ ] StepDetail.tsx
+- [ ] AccountDetail.tsx
+- [ ] DepositDetail.tsx
+- [ ] ClientDetail.tsx
+- [ ] LaborDetailClient.tsx
+- [ ] PricingDetailClient.tsx
+- [ ] LocationDetailPanel.tsx
+
+### 6.5 완료 후
+- [ ] 전체 기능 테스트
+- [ ] 코드 리뷰
+- [ ] PR 머지
+- [ ] BillDetailV2.tsx 정리 (원본으로 교체)
+
+---
+
+## 7. 위험 요소 및 대응
+
+| 위험 | 가능성 | 대응 |
+|------|--------|------|
+| 기존 기능 손상 | 중 | 파일별 테스트, Git 롤백 준비 |
+| 예상보다 복잡한 파일 | 중 | 복잡한 파일은 부분 적용 허용 |
+| 타입 에러 | 높 | 래퍼 함수로 타입 호환성 확보 |
+
+---
+
+## 8. 참고 자료
+
+- 공통 훅 소스: `src/hooks/index.ts`
+- 테스트 케이스: `BillDetailV2.tsx`
+- 기존 템플릿: `IntegratedDetailTemplate.tsx`

claudedocs/architecture/[IMPL-2026-02-05] formatter-commonization-plan.md

@@ -0,0 +1,88 @@
+# 금액/날짜 포맷터 공통화 계획
+
+> 작성일: 2026-02-05
+> 상태: ✅ 완료
+> 목적: 중복 정의된 formatAmount, formatDate 함수를 공통 유틸로 통합
+
+---
+
+## 📊 현황 분석
+
+### 이미 존재하는 유틸
+
+| 파일 | 함수 | 설명 |
+|------|------|------|
+| `src/utils/formatAmount.ts` | `formatAmount()` | 자동 만원 변환 (1만 이상 → "N만원") |
+| | `formatAmountWon()` | 항상 원 단위 ("N원") |
+| | `formatAmountManwon()` | 항상 만원 단위 ("N만원") |
+| | `formatKoreanAmount()` | 억/만 축약 ("1억 5,000만") |
+| | `formatNumber()` | **신규** 단순 천단위 콤마 |
+| `src/utils/date.ts` | `getLocalDateString()` | YYYY-MM-DD 반환 |
+| | `getTodayString()` | 오늘 날짜 YYYY-MM-DD |
+| | `formatDateForInput()` | input용 날짜 변환 |
+| | `formatDate()` | **신규** YYYY-MM-DD 표시용 |
+| | `formatDateRange()` | **신규** "시작 ~ 종료" 형식 |
+
+---
+
+## 📊 결과 요약
+
+### 마이그레이션 완료 파일
+
+#### formatAmount → formatNumber (12개 파일) ✅
+| 파일 | 상태 |
+|------|------|
+| `construction/contract/ContractListClient.tsx` | ✅ 완료 |
+| `construction/contract/ContractDetailForm.tsx` | ✅ 완료 |
+| `construction/bidding/BiddingListClient.tsx` | ✅ 완료 |
+| `construction/bidding/BiddingDetailForm.tsx` | ✅ 완료 |
+| `construction/estimates/EstimateListClient.tsx` | ✅ 완료 |
+| `construction/estimates/modals/EstimateDocumentContent.tsx` | ✅ 완료 |
+| `construction/handover-report/HandoverReportListClient.tsx` | ✅ 완료 |
+| `construction/handover-report/HandoverReportDetailForm.tsx` | ✅ 완료 |
+| `construction/handover-report/modals/HandoverReportDocumentModal.tsx` | ✅ 완료 |
+| `construction/utility-management/UtilityManagementListClient.tsx` | ✅ 완료 |
+| `construction/estimates/utils/formatters.ts` | ✅ re-export로 변경 |
+
+#### formatDate 공통화 (7개 파일) ✅
+| 파일 | 상태 |
+|------|------|
+| `construction/contract/ContractListClient.tsx` | ✅ 완료 (formatDateRange) |
+| `construction/bidding/BiddingListClient.tsx` | ✅ 완료 |
+| `construction/handover-report/HandoverReportListClient.tsx` | ✅ 완료 (formatDateRange) |
+| `construction/utility-management/UtilityManagementListClient.tsx` | ✅ 완료 |
+| `construction/issue-management/IssueManagementListClient.tsx` | ✅ 완료 |
+| `construction/structure-review/StructureReviewListClient.tsx` | ✅ 완료 |
+| `construction/management/ConstructionDetailClient.tsx` | ✅ 완료 |
+
+#### 마이그레이션 제외 (한글 형식 유지)
+| 파일 | 사유 |
+|------|------|
+| `handover-report/modals/HandoverReportDocumentModal.tsx` | 한글 형식 ("년 월 일") |
+| `order-management/modals/OrderDocumentModal.tsx` | 한글 형식 ("년 월 일") |
+
+---
+
+## 📋 효과
+
+| 항목 | Before | After |
+|------|--------|-------|
+| formatAmount 정의 | 12개 파일 | 1개 파일 (`formatNumber`) |
+| formatDate 정의 | 8개 파일 | 1개 파일 |
+| 중복 코드 라인 | ~150줄 | 0줄 |
+| 포맷 변경 시 수정 | 20개 파일 | 1개 파일 |
+
+---
+
+## ⚠️ 주의사항
+
+1. **기존 formatAmount()와 formatNumber() 차이**
+   - 기존 `formatAmount()`: 자동 만원 변환 (유지됨)
+   - 신규 `formatNumber()`: 단순 천단위 콤마만
+
+2. **한글 날짜 형식은 별도 유지**
+   - 문서 모달에서 사용하는 "년 월 일" 형식은 로컬 유지
+   - 공통 `formatDate()`는 YYYY-MM-DD 형식만 처리
+
+3. **backward compatibility**
+   - `estimates/utils/formatters.ts`는 `formatNumber`를 `formatAmount`로 re-export

claudedocs/architecture/[IMPL-2026-02-11] dynamic-field-components.md

@@ -0,0 +1,343 @@
+# 동적 필드 타입 컴포넌트 — 프론트엔드 구현 기획서
+
+> 작성일: 2026-02-11
+> 설계 근거: `[DESIGN-2026-02-11] dynamic-field-type-extension.md`
+> 상태: ✅ 프론트 구현 완료 — 백엔드 작업 대기
+> 백엔드 스펙: `item-master/[API-REQUEST-2026-02-12] dynamic-field-type-backend-spec.md`
+
+---
+
+## 목적
+
+현재 DynamicItemForm의 필드 타입이 6종(textbox, number, dropdown, checkbox, date, textarea)으로 제한되어 있어 제조/공사/유통/물류 등 다양한 산업의 품목관리 요구를 충족하지 못함.
+
+**이 작업의 목표**:
+- 8종의 신규 필드 컴포넌트를 미리 만들어둔다
+- 범용 테이블 섹션(DynamicTableSection)을 만든다
+- 백엔드가 `field_type` + `properties` config를 보내면 자동 렌더링되는 구조를 완성한다
+- 백엔드 작업 전에도 mock props로 독립 테스트 가능하게 한다
+
+**API 연동 시 동작 흐름**:
+```
+백엔드 DB:  field_type = "reference", properties = { "source": "vendors" }
+     ↓
+API 응답:   GET /v1/item-master/pages/{id}/structure
+     ↓
+프론트:     DynamicFieldRenderer → switch("reference") → <ReferenceField />
+            ReferenceField가 properties.source 읽어서 /api/proxy/vendors 검색 API 호출
+```
+
+---
+
+## 컴포넌트 구현 목록
+
+### Phase 1: 핵심 컴포넌트
+
+| # | 컴포넌트 | field_type | 상태 | 비고 |
+|---|---------|-----------|------|------|
+| 1-1 | ReferenceField | `reference` | ✅ 완료 | 다른 테이블 검색/선택 |
+| 1-2 | MultiSelectField | `multi-select` | ✅ 완료 | 복수 선택 태그 |
+| 1-3 | FileField | `file` | ✅ 완료 | 파일/이미지 업로드 |
+| 1-4 | DynamicTableSection | (섹션) | ✅ 완료 | 범용 테이블 섹션 |
+| 1-5 | TableCellRenderer | (내부) | ✅ 완료 | 테이블 셀 렌더러 |
+| 1-6 | reference-sources.ts | (config) | ✅ 완료 | 참조 소스 프리셋 정의 |
+| 1-7 | DynamicFieldRenderer 확장 | (수정) | ✅ 완료 | switch문 + 신규 import |
+| 1-8 | 타입 정의 확장 | (수정) | ✅ 완료 | ItemFieldType 통합 + config 인터페이스 |
+
+### Phase 2: 편의 컴포넌트
+
+| # | 컴포넌트 | field_type | 상태 | 비고 |
+|---|---------|-----------|------|------|
+| 2-1 | CurrencyField | `currency` | ✅ 완료 | 통화 금액 (천단위 포맷) |
+| 2-2 | UnitValueField | `unit-value` | ✅ 완료 | 값+단위 조합 (100mm) |
+| 2-3 | RadioField | `radio` | ✅ 완료 | 라디오 버튼 그룹 |
+| 2-4 | section-presets.ts | (config) | ✅ 완료 | 산업별 섹션 프리셋 JSON |
+
+### Phase 3: 고급 컴포넌트
+
+| # | 컴포넌트 | field_type | 상태 | 비고 |
+|---|---------|-----------|------|------|
+| 3-1 | ToggleField | `toggle` | ✅ 완료 | On/Off 스위치 |
+| 3-2 | ComputedField | `computed` | ✅ 완료 | 계산 필드 (읽기전용) |
+| 3-3 | 조건부 표시 연산자 확장 | (수정) | ✅ 완료 | in/not_in/greater_than 등 9종 |
+
+---
+
+## 각 컴포넌트 스펙
+
+### 1-1. ReferenceField
+
+**파일**: `DynamicItemForm/fields/ReferenceField.tsx`
+
+**역할**: 다른 테이블의 데이터를 검색하여 선택 (거래처, 품목, 고객, 현장, 차량 등)
+
+**UI 구성**:
+- 읽기전용 Input + 검색 버튼(돋보기 아이콘)
+- 클릭 시 SearchableSelectionModal 열림
+- 선택 후 displayField 값 표시
+- X 버튼으로 선택 해제
+
+**properties에서 읽는 값**:
+```typescript
+interface ReferenceConfig {
+  source: string;              // "vendors" | "items" | "custom" 등
+  displayField?: string;       // 기본 "name"
+  valueField?: string;         // 기본 "id"
+  searchFields?: string[];     // 기본 ["name"]
+  searchApiUrl?: string;       // source="custom"일 때 필수
+  columns?: Array<{ key: string; label: string; width?: string }>;
+  displayFormat?: string;      // "{code} - {name}"
+  returnFields?: string[];     // ["id", "code", "name"]
+}
+```
+
+**API 연동 시**:
+- `REFERENCE_SOURCES[source]`에서 apiUrl 조회
+- `GET {apiUrl}?search={query}&size=20` 호출
+- 결과를 SearchableSelectionModal에 표시
+
+**API 연동 전 (mock)**:
+- props로 전달된 options 사용 또는
+- 빈 상태에서 UI/UX만 확인
+
+---
+
+### 1-2. MultiSelectField
+
+**파일**: `DynamicItemForm/fields/MultiSelectField.tsx`
+
+**역할**: 여러 항목을 동시에 선택 (태그 칩 형태로 표시)
+
+**UI 구성**:
+- Combobox (검색 가능한 드롭다운)
+- 선택된 항목은 칩(Chip/Badge)으로 표시
+- 칩의 X 버튼으로 개별 해제
+
+**properties에서 읽는 값**:
+```typescript
+interface MultiSelectConfig {
+  maxSelections?: number;      // 최대 선택 수 (기본: 무제한)
+  allowCustom?: boolean;       // 직접 입력 허용 (기본: false)
+  layout?: 'chips' | 'list';  // 기본: "chips"
+}
+```
+
+**options**: 기존 dropdown과 동일 `[{label, value}]`
+
+**저장값**: `string[]` (예: `["CUT", "BEND", "WELD"]`)
+
+---
+
+### 1-3. FileField
+
+**파일**: `DynamicItemForm/fields/FileField.tsx`
+
+**역할**: 파일/이미지 첨부
+
+**UI 구성**:
+- 파일 선택 버튼 ("파일 선택" 또는 드래그 앤 드롭 영역)
+- 선택된 파일 목록 표시 (이름, 크기, 삭제 버튼)
+- 이미지 파일일 경우 미리보기 썸네일
+
+**properties에서 읽는 값**:
+```typescript
+interface FileConfig {
+  accept?: string;             // ".pdf,.doc" (기본: "*")
+  maxSize?: number;            // bytes (기본: 10MB = 10485760)
+  maxFiles?: number;           // 기본: 1
+  preview?: boolean;           // 이미지 미리보기 (기본: true)
+  category?: string;           // 파일 카테고리 태그
+}
+```
+
+**API 연동 시**: `POST /v1/files/upload` (multipart)
+**API 연동 전**: File 객체를 로컬 상태로 관리, URL.createObjectURL로 미리보기
+
+---
+
+### 1-4. DynamicTableSection
+
+**파일**: `DynamicItemForm/sections/DynamicTableSection.tsx`
+
+**역할**: config 기반 범용 테이블 (공정, 품질검사, 구매처, 공정표, 배차 등)
+
+**UI 구성**:
+- 테이블 헤더 (columns config 기반)
+- 행 추가/삭제 버튼
+- 각 셀은 TableCellRenderer (= DynamicFieldRenderer 재사용)
+- 요약행 (선택, summaryRow config)
+- 빈 상태 메시지
+
+**props**:
+```typescript
+interface DynamicTableSectionProps {
+  section: ItemSectionResponse;
+  tableConfig: TableConfig;
+  rows: Record<string, any>[];
+  onRowsChange: (rows: Record<string, any>[]) => void;
+  disabled?: boolean;
+}
+```
+
+**tableConfig 구조**: 설계서 섹션 4.3 참조
+
+**API 연동 시**: `GET/PUT /v1/items/{itemId}/section-data/{sectionId}`
+**API 연동 전**: rows를 폼 상태(formData)에 로컬 관리
+
+---
+
+### 1-5. TableCellRenderer
+
+**파일**: `DynamicItemForm/sections/TableCellRenderer.tsx`
+
+**역할**: 테이블 셀 = DynamicFieldRenderer를 테이블 셀용 축소 모드로 래핑
+
+**핵심**: column config → ItemFieldResponse 호환 객체로 변환 → DynamicFieldRenderer 호출
+
+```typescript
+function TableCellRenderer({ column, value, onChange, compact }) {
+  const fieldLike = columnToFieldResponse(column);
+  return <DynamicFieldRenderer field={fieldLike} value={value} onChange={onChange} />;
+}
+```
+
+---
+
+### 1-6. reference-sources.ts
+
+**파일**: `DynamicItemForm/config/reference-sources.ts`
+
+**역할**: reference 필드의 소스별 기본 설정 (API URL, 표시 필드, 검색 컬럼)
+
+**내용**: 공통(vendors, items, customers, employees, warehouses) + 산업별(processes, sites, vehicles, stores 등)
+
+**확장 방법**: 새 소스 추가 = 이 파일에 객체 1개 추가
+
+---
+
+### 2-1. CurrencyField
+
+**파일**: `DynamicItemForm/fields/CurrencyField.tsx`
+
+**역할**: 통화 금액 입력 (천단위 콤마, 통화 기호)
+
+**UI**: Input + 통화기호(₩) prefix + 천단위 포맷
+- 입력 중: 숫자만
+- 포커스 아웃: "₩15,000" 포맷
+
+**properties**: `{ currency, precision, showSymbol, allowNegative }`
+
+**저장값**: `number` (포맷 없이)
+
+---
+
+### 2-2. UnitValueField
+
+**파일**: `DynamicItemForm/fields/UnitValueField.tsx`
+
+**역할**: 값 + 단위 조합 입력 (100mm, 50kg)
+
+**UI**: Input(숫자) + Select(단위) 가로 배치
+
+**properties**: `{ units, defaultUnit, precision }`
+
+**저장값**: `{ value: number, unit: string }`
+
+---
+
+### 2-3. RadioField
+
+**파일**: `DynamicItemForm/fields/RadioField.tsx`
+
+**역할**: 라디오 버튼 그룹
+
+**UI**: RadioGroup (수평/수직)
+
+**properties**: `{ layout: "horizontal" | "vertical" }`
+
+**options**: `[{label, value}]`
+
+---
+
+### 3-1. ToggleField
+
+**파일**: `DynamicItemForm/fields/ToggleField.tsx`
+
+**역할**: On/Off 토글 스위치
+
+**UI**: Switch + 라벨
+
+**properties**: `{ onLabel, offLabel, onValue, offValue }`
+
+---
+
+### 3-2. ComputedField
+
+**파일**: `DynamicItemForm/fields/ComputedField.tsx`
+
+**역할**: 다른 필드 기반 자동 계산 (읽기 전용)
+
+**UI**: 읽기전용 표시 (배경색 구분, muted)
+
+**properties**: `{ formula, dependsOn, format, precision }`
+
+**동작**: `dependsOn` 필드 값이 변경될 때마다 formula 재계산
+
+---
+
+## 파일 구조
+
+```
+DynamicItemForm/
+├── fields/
+│   ├── DynamicFieldRenderer.tsx     ← switch 확장
+│   ├── TextField.tsx                  (기존)
+│   ├── NumberField.tsx                (기존)
+│   ├── DropdownField.tsx              (기존)
+│   ├── CheckboxField.tsx              (기존)
+│   ├── DateField.tsx                  (기존)
+│   ├── TextareaField.tsx              (기존)
+│   ├── ReferenceField.tsx           ★ Phase 1
+│   ├── MultiSelectField.tsx         ★ Phase 1
+│   ├── FileField.tsx                ★ Phase 1
+│   ├── CurrencyField.tsx            ★ Phase 2
+│   ├── UnitValueField.tsx           ★ Phase 2
+│   ├── RadioField.tsx               ★ Phase 2
+│   ├── ToggleField.tsx              ★ Phase 3
+│   └── ComputedField.tsx            ★ Phase 3
+├── sections/
+│   ├── DynamicBOMSection.tsx          (기존)
+│   ├── DynamicTableSection.tsx      ★ Phase 1
+│   └── TableCellRenderer.tsx        ★ Phase 1
+├── config/
+│   └── reference-sources.ts         ★ Phase 1
+├── presets/
+│   └── section-presets.ts           ★ Phase 2
+├── hooks/                             (기존, 변경 없음)
+├── types.ts                         ← 타입 확장
+└── index.tsx                        ← table 섹션 렌더링 추가
+```
+
+## 기존 코드 수정 범위
+
+| 파일 | 수정 내용 | 줄 수 |
+|------|----------|-------|
+| `DynamicFieldRenderer.tsx` | switch case 8개 추가 + import | +20줄 |
+| `types.ts` | ExtendedFieldType union + config 인터페이스 | +80줄 |
+| `index.tsx` | 섹션 렌더링에 `case 'table'` 추가 | +15줄 |
+| `item-master-api.ts` | field_type union 확장 | +3줄 |
+
+**기존 컴포넌트 6개 + BOM + hooks 7개 = 변경 없음**
+
+---
+
+## 상태 범례
+
+- ⬜ 대기
+- 🔄 진행 중
+- ✅ 완료
+- ⏸️ 보류
+
+---
+
+**마지막 업데이트**: 2026-02-12 — Phase 1+2+3 전체 완료 (15/15 항목)

claudedocs/architecture/[IMPL-2026-02-23] phase1-item4-error-format.md

@@ -0,0 +1,112 @@
+# Phase 1-4: 에러 메시지 포맷 통합 (`formatApiError` 제거)
+
+> 난이도: 저 | 영향도: 🟡 API 레이어 정리 | 예상 변경: 1파일 삭제
+
+---
+
+## 현황 요약
+
+에러 메시지 포맷팅 함수가 2곳에 중복:
+
+| 파일 | 함수 | 외부 사용처 |
+|------|------|------------|
+| `src/lib/api/error-handler.ts:122` | `getErrorMessage()` | **5+ 파일** (활발히 사용) |
+| `src/lib/api/toast-utils.ts:106` | `formatApiError()` | **0건** (dead code) |
+
+또한 `SHOW_ERROR_CODE` 상수도 양쪽에 중복 정의됨.
+
+---
+
+## 핵심 발견: toast-utils.ts 전체가 dead code
+
+`from '@/lib/api/toast-utils'` 를 import하는 파일이 **0건**.
+
+```
+toast-utils.ts 내보내는 함수 전부 미사용:
+- toastApiError()    → 0 import
+- toastSuccess()     → 0 import
+- toastWarning()     → 0 import
+- toastInfo()        → 0 import
+- formatApiError()   → 0 import
+```
+
+현재 프로젝트에서 에러 토스트 표시는 직접 `toast.error(getErrorMessage(err))` 패턴으로 처리 중.
+
+---
+
+## 작업 내역
+
+### Step 1: `src/lib/api/toast-utils.ts` 삭제
+
+파일 전체가 dead code이므로 삭제.
+
+### Step 2: (선택) 유용한 헬퍼를 error-handler.ts로 이동
+
+`toastApiError()` 함수는 validation 에러의 첫 번째 필드를 표시하는 로직이 있어,
+향후 유용할 수 있으면 error-handler.ts 하단에 통합 가능.
+
+```typescript
+// src/lib/api/error-handler.ts 하단에 추가 (선택)
+import { toast } from 'sonner';
+
+export function toastApiError(error: unknown, fallbackMessage = '오류가 발생했습니다.'): void {
+  if (error instanceof ApiError && error.errors && SHOW_ERROR_CODE) {
+    const firstField = Object.keys(error.errors)[0];
+    if (firstField) {
+      toast.error(`${getErrorMessage(error)}\n${firstField}: ${error.errors[firstField][0]}`);
+      return;
+    }
+  }
+  toast.error(getErrorMessage(error) || fallbackMessage);
+}
+```
+
+이 step은 **선택**. 현재 사용처가 없으므로 당장은 삭제만으로 충분.
+
+### Step 3: 검증
+
+```bash
+npx tsc --noEmit
+```
+
+toast-utils.ts를 삭제해도 외부 import가 없으므로 타입 에러 없음.
+
+---
+
+## 관련 파일 참조
+
+### 활발히 사용 중인 함수 (변경 없음)
+
+`getErrorMessage()` 사용처 (error-handler.ts에서 export):
+- `src/contexts/ItemMasterContext.tsx` (line 7, 589, 682)
+- `src/components/items/ItemMasterDataManagement/hooks/usePageManagement.ts` (line 7, 122, 159, 198, 219)
+- `src/components/items/ItemMasterDataManagement/hooks/useImportManagement.ts` (line 5, 58, 80, 92)
+- `src/components/items/ItemMasterDataManagement/hooks/useInitialDataLoading.ts` (line 7, 130)
+- `src/app/[locale]/(protected)/sales/client-management-sales-admin/page.tsx` (line 40, 301, 347)
+
+### 삭제 대상
+
+- `src/lib/api/toast-utils.ts` (전체 116줄)
+
+---
+
+## 중복 구조 비교
+
+```
+error-handler.ts                    toast-utils.ts (삭제 대상)
+─────────────────                   ──────────────────────────
+const SHOW_ERROR_CODE = true;       const SHOW_ERROR_CODE = true;  ← 중복
+
+getErrorMessage(error):             formatApiError(error):
+  DuplicateCodeError → [status]       ApiError → [status] msg
+  ApiError → [status] msg             else → getErrorMessage()   ← 결국 위임
+  Error → .message
+  unknown → 기본 메시지
+                                    toastApiError(error):
+                                      DuplicateCodeError → toast  ← getErrorMessage와 동일 로직
+                                      ApiError → toast
+                                      Error → toast
+                                      unknown → toast
+```
+
+`formatApiError`는 결국 `getErrorMessage`를 호출하는 래퍼에 불과. 삭제해도 기능 손실 없음.

claudedocs/architecture/[IMPL-2026-02-23] phase1-item5-zustand-selectors.md

@@ -0,0 +1,229 @@
+# Phase 1-5: Zustand 셀렉터 훅 추가 (3개 스토어)
+
+> 난이도: 저 | 영향도: 🟡 리렌더 최적화 | 예상 변경: 3 스토어 + 4 컨슈머
+
+---
+
+## 현황 요약
+
+셀렉터 없이 전체 스토어를 구독하면, 무관한 상태 변경에도 컴포넌트가 리렌더됩니다.
+
+| 스토어 | 셀렉터 훅 | 사용처 | 문제 |
+|--------|----------|--------|------|
+| ✅ `masterDataStore` | `usePageConfig()` 등 | 다수 | 양호 |
+| ✅ `authStore` | `useCurrentUser()` 등 | 4곳 | 양호 (방금 추가) |
+| ❌ `useTableColumnStore` | 없음 | 1곳 | 전체 스토어 구독 |
+| ❌ `useMenuStore` | 없음 | 15곳 | 일부 전체 구독 |
+| ❌ `useThemeStore` | 없음 | 2곳 | 전체 구독 |
+
+---
+
+## 작업 내역
+
+### Step 1: `src/stores/useTableColumnStore.ts` — 셀렉터 훅 추가
+
+파일 끝에 추가:
+
+```typescript
+// ===== 셀렉터 훅 =====
+
+/** 특정 페이지의 컬럼 설정만 구독 */
+export const usePageColumnSettings = (pageId: string) =>
+  useTableColumnStore((state) => state.pageSettings[pageId] ?? DEFAULT_PAGE_SETTINGS);
+
+/** 특정 페이지의 숨김 컬럼만 구독 */
+export const useHiddenColumns = (pageId: string) =>
+  useTableColumnStore((state) => state.pageSettings[pageId]?.hiddenColumns ?? []);
+
+/** 특정 페이지의 컬럼 너비만 구독 */
+export const useColumnWidths = (pageId: string) =>
+  useTableColumnStore((state) => state.pageSettings[pageId]?.columnWidths ?? {});
+```
+
+**주의**: `DEFAULT_PAGE_SETTINGS` 객체는 파일 내에 이미 정의되어 있음 (line 30-33).
+
+**컨슈머 변경** — `src/hooks/useColumnSettings.ts`:
+
+```typescript
+// Before (line 17)
+const store = useTableColumnStore();        // 전체 스토어 구독
+const settings = store.getPageSettings(pageId);
+
+// After
+const settings = usePageColumnSettings(pageId);  // 해당 페이지 설정만 구독
+const { setColumnWidth: storeSetWidth, toggleColumnVisibility: storeToggle, resetPageSettings } = useTableColumnStore.getState();
+// 또는 액션만 별도 구독 (액션은 참조 안정적이라 리렌더 유발 안 함):
+const setColumnWidth = useTableColumnStore((s) => s.setColumnWidth);
+const toggleColumnVisibility = useTableColumnStore((s) => s.toggleColumnVisibility);
+const resetPageSettings = useTableColumnStore((s) => s.resetPageSettings);
+```
+
+---
+
+### Step 2: `src/stores/menuStore.ts` — 셀렉터 훅 추가
+
+파일 끝에 추가:
+
+```typescript
+// ===== 셀렉터 훅 =====
+
+/** 사이드바 접힘 상태만 구독 */
+export const useSidebarCollapsed = () =>
+  useMenuStore((state) => state.sidebarCollapsed);
+
+/** 활성 메뉴 ID만 구독 */
+export const useActiveMenu = () =>
+  useMenuStore((state) => state.activeMenu);
+
+/** 메뉴 아이템 목록만 구독 */
+export const useMenuItems = () =>
+  useMenuStore((state) => state.menuItems);
+
+/** 하이드레이션 완료 여부만 구독 */
+export const useMenuHydrated = () =>
+  useMenuStore((state) => state._hasHydrated);
+```
+
+**컨슈머 변경 대상**:
+
+#### 2-A. `src/layouts/AuthenticatedLayout.tsx` (line 99) — 🔴 핵심
+
+현재: 전체 스토어 디스트럭처링
+```typescript
+const { menuItems, activeMenu, setActiveMenu, setMenuItems, sidebarCollapsed, toggleSidebar, _hasHydrated } = useMenuStore();
+```
+
+변경:
+```typescript
+const menuItems = useMenuItems();
+const activeMenu = useActiveMenu();
+const sidebarCollapsed = useSidebarCollapsed();
+const _hasHydrated = useMenuHydrated();
+// 액션은 참조 안정적이므로 별도 셀렉터:
+const setActiveMenu = useMenuStore((s) => s.setActiveMenu);
+const setMenuItems = useMenuStore((s) => s.setMenuItems);
+const toggleSidebar = useMenuStore((s) => s.toggleSidebar);
+```
+
+#### 2-B. `src/components/production/WorkerScreen/index.tsx` (line 327)
+
+현재:
+```typescript
+const { sidebarCollapsed } = useMenuStore();  // 전체 구독
+```
+
+변경:
+```typescript
+const sidebarCollapsed = useSidebarCollapsed();
+```
+
+#### 2-C. `src/components/layout/CommandMenuSearch.tsx` (line 68)
+
+현재:
+```typescript
+const { menuItems } = useMenuStore();  // 전체 구독
+```
+
+변경:
+```typescript
+const menuItems = useMenuItems();
+```
+
+#### 2-D. 나머지 sidebarCollapsed 사용 파일 (이미 셀렉터 패턴)
+
+아래 파일들은 이미 `useMenuStore((state) => state.sidebarCollapsed)` 패턴을 사용 중이므로 **변경 불필요**:
+- `ItemDetail.tsx`, `ChecklistDetail.tsx`, `PriceDistributionDetail.tsx`
+- `StepDetail.tsx`, `PermissionDetailClient.tsx`, `BoardDetail/index.tsx`
+- `ProcessDetail.tsx`, `PricingTableForm.tsx`, `DynamicItemForm/index.tsx`
+- `ItemDetailClient.tsx`, `ClientDetail.tsx`, `DetailActions.tsx`
+
+단, 셀렉터 훅이 추가되면 이 파일들도 향후 `useSidebarCollapsed()`로 전환 가능 (선택).
+
+---
+
+### Step 3: `src/stores/themeStore.ts` — 셀렉터 훅 추가
+
+파일 끝에 추가:
+
+```typescript
+// ===== 셀렉터 훅 =====
+
+/** 현재 테마만 구독 */
+export const useTheme = () =>
+  useThemeStore((state) => state.theme);
+
+/** setTheme 액션만 구독 */
+export const useSetTheme = () =>
+  useThemeStore((state) => state.setTheme);
+```
+
+**컨슈머 변경 대상**:
+
+#### 3-A. `src/layouts/AuthenticatedLayout.tsx` (line 100)
+
+현재:
+```typescript
+const { theme, setTheme } = useThemeStore();
+```
+
+변경:
+```typescript
+const theme = useTheme();
+const setTheme = useSetTheme();
+```
+
+#### 3-B. `src/components/ThemeSelect.tsx` (line 24)
+
+현재:
+```typescript
+const { theme, setTheme } = useThemeStore();
+```
+
+변경:
+```typescript
+const theme = useTheme();
+const setTheme = useSetTheme();
+```
+
+---
+
+## 검증
+
+```bash
+npx tsc --noEmit
+```
+
+셀렉터 훅은 기존 API에 추가만 하는 것이므로 기존 코드에 영향 없음.
+컨슈머 변경은 import 경로와 호출 패턴만 바뀌므로 타입 에러 가능성 낮음.
+
+---
+
+## 변경 파일 총 정리
+
+| # | 파일 | 작업 | 내용 |
+|---|------|------|------|
+| 1 | `src/stores/useTableColumnStore.ts` | 추가 | 셀렉터 훅 3개 (`usePageColumnSettings`, `useHiddenColumns`, `useColumnWidths`) |
+| 2 | `src/stores/menuStore.ts` | 추가 | 셀렉터 훅 4개 (`useSidebarCollapsed`, `useActiveMenu`, `useMenuItems`, `useMenuHydrated`) |
+| 3 | `src/stores/themeStore.ts` | 추가 | 셀렉터 훅 2개 (`useTheme`, `useSetTheme`) |
+| 4 | `src/hooks/useColumnSettings.ts` | 수정 | `useTableColumnStore()` → 셀렉터 패턴 |
+| 5 | `src/layouts/AuthenticatedLayout.tsx` | 수정 | menuStore/themeStore 전체 구독 → 셀렉터 |
+| 6 | `src/components/production/WorkerScreen/index.tsx` | 수정 | `useMenuStore()` → `useSidebarCollapsed()` |
+| 7 | `src/components/layout/CommandMenuSearch.tsx` | 수정 | `useMenuStore()` → `useMenuItems()` |
+| 8 | `src/components/ThemeSelect.tsx` | 수정 | `useThemeStore()` → `useTheme()` + `useSetTheme()` |
+
+---
+
+## 참고: Zustand 셀렉터가 중요한 이유
+
+```
+// ❌ 전체 구독 — menuItems 변경 시 sidebarCollapsed만 쓰는 컴포넌트도 리렌더
+const { sidebarCollapsed } = useMenuStore();
+
+// ✅ 셀렉터 — sidebarCollapsed 변경 시에만 리렌더
+const sidebarCollapsed = useMenuStore((state) => state.sidebarCollapsed);
+// 또는
+const sidebarCollapsed = useSidebarCollapsed();
+```
+
+Zustand는 `Object.is`로 반환값을 비교. 셀렉터가 원시값(string, boolean, number)을 반환하면 참조 비교로 정확히 변경 감지.
+객체를 반환하는 셀렉터(예: `usePageColumnSettings`)는 같은 참조를 반환하므로 해당 pageId의 설정이 변경될 때만 리렌더.

claudedocs/architecture/[PLAN-2025-02-10] frontend-improvement-roadmap.md

@@ -0,0 +1,74 @@
+# SAM ERP 프론트엔드 개선 로드맵
+
+> 작성일: 2025-02-10
+> 분석 기준: src/ 전체 (500+ 파일, ~163K줄)
+
+---
+
+## Phase A: 즉시 개선 — ✅ 완료
+
+| # | 항목 | 상태 | 비고 |
+|---|------|------|------|
+| A-1 | `<img>` → `next/image` 전환 | ✅ **전환 불필요 결정** | 폐쇄형 ERP, 전량 외부 동적 이미지, blob URL 비호환 (`_index.md` 참조) |
+| A-2 | DataTable 렌더링 최적화 | ⏳ 대기 | TableRow memo + useCallback |
+
+---
+
+## Phase B: 단기 개선 — ✅ 완료
+
+| # | 항목 | 상태 | 비고 |
+|---|------|------|------|
+| B-1 | `next/dynamic` 코드 스플리팅 | ✅ **완료** | 대시보드 4개 + xlsx 동적 로드, ~850KB 절감 (`_index.md` 참조) |
+| B-2 | API 병렬 호출 (`Promise.all`) | ✅ **완료** | |
+| B-3 | `store/` vs `stores/` 통합 | ✅ **완료** | |
+
+---
+
+## Phase C: 중기 개선 — ✅ 완료
+
+| # | 항목 | 상태 | 비고 |
+|---|------|------|------|
+| C-1 | 테이블 가상화 (react-window) | ✅ **보류 결정** | 페이지네이션 사용 중, YAGNI (`_index.md` 참조) |
+| C-2 | SWR / React Query | ✅ **보류 결정** | Zustand 캐싱 충족 (`_index.md` 참조) |
+| C-3 | Action 팩토리 패턴 확대 | ✅ **규칙 확정** | 신규 CRUD만 팩토리 사용 (`_index.md` 참조) |
+| C-4 | V1/V2 컴포넌트 정리 | ✅ **완료** | V2 최종본 확정, V1 삭제, 접미사 제거 |
+
+---
+
+## Phase D: 장기 개선 (필요 시)
+
+| # | 항목 | 상태 |
+|---|------|------|
+| D-1 | God 컴포넌트 분리 (5개, 1200~2700줄) | ⏳ 대기 |
+| D-2 | `as` 타입 캐스트 점진적 제거 (926건) | ✅ **보류 결정** | 실제 ~200건만 actionable, 신규 코드에서 제네릭 활용 (2026-02-11) |
+| D-3 | `@deprecated` 함수 정리 (13파일) | ✅ **즉시 삭제분 완료** | uploadFile/deleteFile/getSiteNames/deprecated props 삭제 (2026-02-11) |
+| D-4 | Molecules 레이어 활성화 | ✅ **보류 결정** | 사용률 ~0%, organisms/templates로 충분 (2026-02-11) |
+| D-5 | 모달 컴포넌트 통합 | ✅ **완료** | InspectionPreviewModal → DocumentViewer 전환 (2026-02-11) |
+| D-6 | 기타 (TODO 102건, strictMode 등) | ⏳ 대기 |
+
+---
+
+## 이전 리팩토링 완료 항목 (참고)
+
+| 항목 | 상태 | 날짜 |
+|------|------|------|
+| Phase 1: 공통 훅 추출 (executeServerAction 등) | ✅ 완료 | 이전 세션 |
+| 중복 코드 공통화 (buildApiUrl 전체 43개 actions.ts 마이그레이션) | ✅ 완료 | 2026-02-12 |
+| executePaginatedAction 전체 마이그레이션 (14개 actions.ts, ~220줄 감소) | ✅ 완료 | 2026-02-12 |
+| Phase 3: 공용 유틸 추출 (PaginatedApiResponse 등) | ✅ 완료 | 이전 세션 |
+| Phase 4: SearchableSelectionModal 공통화 | ✅ 완료 | 이전 세션 |
+| Phase 5: any 21건 + memo 3개 정리 | ✅ 완료 | 이전 세션 |
+| console.log 524건 → 22건 정리 | ✅ 완료 | 2025-02-10 |
+| TODO 주석 정리 (login route) | ✅ 완료 | 2025-02-10 |
+| SSR 가드 추가 (ThemeContext, ApiErrorContext, useDetailPageState) | ✅ 완료 | 2025-02-10 |
+| 커스텀 훅 불필요 'use client' 15개 제거 | ✅ 완료 | 2025-02-10 |
+| formatDate 이름 충돌 해소 → formatCalendarDate | ✅ 완료 | 2025-02-10 |
+
+---
+
+## 우선순위 요약
+
+```
+Phase A~C: ✅ 전체 완료/결정 완료 (A-2 DataTable 최적화만 대기)
+Phase D:   남은 작업 → A-2, D-1, D-6
+```

claudedocs/architecture/[PLAN-2025-12-29] dynamic-menu-refresh.md

@@ -52,6 +52,8 @@
 |------|------|
 | `src/store/menuStore.ts` | Zustand 메뉴 상태 관리 |
 | `src/lib/utils/menuTransform.ts` | API 메뉴 → UI 메뉴 변환 |
+| `src/lib/utils/menuRefresh.ts` | 메뉴 갱신 유틸리티 (해시 비교, localStorage/Zustand 동시 업데이트) |
+| `src/hooks/useMenuPolling.ts` | 메뉴 폴링 훅 (30초 간격, 탭 가시성, 세션 만료 처리) |
 | `src/layouts/AuthenticatedLayout.tsx` | 메뉴 로드 및 스토어 설정 |
 | `src/components/layout/Sidebar.tsx` | 메뉴 렌더링 |
 | `src/contexts/AuthContext.tsx` | 사용자 인증 컨텍스트 |
@@ -229,28 +231,30 @@ export async function refreshMenus(): Promise<boolean> {
 
 ```typescript
 // src/hooks/useMenuPolling.ts
-import { useEffect, useRef } from 'react';
-import { refreshMenus } from '@/lib/utils/menuRefresh';
+// 주요 기능: 30초 폴링, 탭 가시성 처리, 세션 만료 감지(3회 연속 401), 토큰 갱신 쿠키 감지
 
-const POLLING_INTERVAL = 30000; // 30초
-
-export function useMenuPolling(enabled: boolean = true) {
-  const intervalRef = useRef<NodeJS.Timeout | null>(null);
+export function useMenuPolling(options: UseMenuPollingOptions = {}): UseMenuPollingReturn {
+  // ⚠️ 콜백 안정화 패턴 (2026-02-03 버그 수정)
+  // 부모 컴포넌트에서 인라인 콜백을 전달하면 매 렌더마다 새 참조가 생성되어
+  // executeRefresh → useEffect 의존성이 변경 → setInterval이 매 렌더마다 리셋되는 버그 발생.
+  // 해결: 콜백을 ref로 저장하여 executeRefresh 의존성에서 제거.
+  const onMenuUpdatedRef = useRef(onMenuUpdated);
+  const onErrorRef = useRef(onError);
+  const onSessionExpiredRef = useRef(onSessionExpired);
 
   useEffect(() => {
-    if (!enabled) return;
+    onMenuUpdatedRef.current = onMenuUpdated;
+    onErrorRef.current = onError;
+    onSessionExpiredRef.current = onSessionExpired;
+  });
 
-    // 초기 실행은 하지 않음 (로그인 시 이미 받아옴)
-    intervalRef.current = setInterval(() => {
-      refreshMenus();
-    }, POLLING_INTERVAL);
-
-    return () => {
-      if (intervalRef.current) {
-        clearInterval(intervalRef.current);
-      }
-    };
-  }, [enabled]);
+  // executeRefresh 의존성: [stopPolling] 만 — 안정적
+  const executeRefresh = useCallback(async () => {
+    // ref를 통해 최신 콜백 호출
+    onMenuUpdatedRef.current?.();
+    onSessionExpiredRef.current?.();
+    onErrorRef.current?.(result.error);
+  }, [stopPolling]);
 }
 ```
 
@@ -303,6 +307,40 @@ menuStore.setMenuItems(newMenus);       // UI 즉시 반영
 ## 작성 정보
 
 - **작성일**: 2025-12-29
-- **상태**: ✅ 1단계 구현 완료 (테스트 대기)
+- **최종 수정**: 2026-02-03
+- **상태**: ✅ 1단계 구현 완료 + 폴링 버그 수정
 - **담당**: 프론트엔드 팀
-- **백엔드**: `GET /api/v1/menus` API 이미 존재 ✅
+- **백엔드**: `GET /api/v1/menus` API 이미 존재 ✅
+
+---
+
+## 변경 이력
+
+### 2026-02-03: 폴링 인터벌 리셋 버그 수정
+
+**문제**: 메뉴 폴링이 실제로 실행되지 않아 백엔드에서 메뉴를 추가해도 재로그인 전까지 반영되지 않음.
+
+**원인**: `useMenuPolling` 훅의 `executeRefresh` 콜백이 매 렌더마다 새 참조를 생성하여 `setInterval`이 리셋됨.
+
+```
+AuthenticatedLayout에서 인라인 콜백 전달:
+  onMenuUpdated: () => { ... }     ← 매 렌더마다 새 함수
+  onSessionExpired: () => { ... }  ← 매 렌더마다 새 함수
+       ↓
+  executeRefresh deps: [onMenuUpdated, onError, onSessionExpired, stopPolling]
+       ↓ 매 렌더마다 변경
+  useEffect deps: [executeRefresh] → clearInterval → setInterval 재설정
+       ↓
+  알림 폴링이 30초마다 state 업데이트 → 리렌더 → 메뉴 인터벌 리셋
+       ↓
+  메뉴 폴링이 30초에 도달하지 못하고 영원히 미실행
+```
+
+**수정**: 콜백을 `useRef`로 안정화하여 `executeRefresh` 의존성에서 제거.
+
+```
+수정 전: executeRefresh deps = [onMenuUpdated, onError, onSessionExpired, stopPolling]
+수정 후: executeRefresh deps = [stopPolling]  ← 안정적, 인터벌 리셋 없음
+```
+
+**수정 파일**: `src/hooks/useMenuPolling.ts`

claudedocs/architecture/[PLAN-2026-02-06] multi-tenancy-optimization-roadmap.md

@@ -0,0 +1,666 @@
+# 멀티테넌시 공통화 및 최적화 로드맵
+
+**작성일**: 2026-02-06
+**목적**: 전체 프로젝트 멀티테넌시 준비 상태 점검 및 공통화/최적화 계획 수립
+**이전 문서**: `[REF-2025-11-19] multi-tenancy-implementation.md` (Phase 1-2 완료)
+
+---
+
+## 현재 상태 요약 (2026-02-06 기준)
+
+### 완료된 항목 (이전 로드맵 Phase 1-2)
+
+| 항목 | 상태 | 파일 |
+|------|------|------|
+| User 타입에 Tenant 객체 포함 | ✅ 완료 | `src/contexts/AuthContext.tsx` |
+| Tenant 인터페이스 정의 (id, company_name 등) | ✅ 완료 | `src/contexts/AuthContext.tsx` |
+| TenantAwareCache 유틸리티 | ✅ 완료 | `src/lib/cache/TenantAwareCache.ts` |
+| 테넌트 전환 감지 + 캐시 클리어 | ✅ 완료 | `src/contexts/AuthContext.tsx` |
+| masterDataStore 테넌트 스코프 캐시 키 | ✅ 완료 | `src/stores/masterDataStore.ts` |
+| sessionStorage/localStorage 테넌트 격리 | ✅ 완료 | `mes-{tenantId}-{key}` 패턴 |
+
+### 미완료 / 개선 필요 항목
+
+| 영역 | 우선순위 | 현재 상태 |
+|------|----------|-----------|
+| API 프록시에 테넌트 컨텍스트 전달 | 🔴 | X-Tenant-ID 헤더 없음 |
+| Server Actions 테넌트 인식 | 🔴 | 70+ actions.ts에 테넌트 미포함 |
+| 포매터/유틸리티 다국어/다통화 | 🔴 | 한국어 하드코딩 |
+| 브랜딩 동적화 (로고, 앱이름) | 🟡 | "SAM", sam-logo.png 하드코딩 |
+| 상수/공휴일 외부화 | 🟡 | 한국 공휴일 하드코딩 |
+| localStorage 직접 사용 잔재 | 🟡 | TenantAwareCache 미사용 곳 존재 |
+| tenantId 타입 불일치 | 🟡 | string vs number 혼재 |
+| 테넌트 라우팅 | 🟢 | 현재 없음 (필요 시 추가) |
+| TenantContext Provider | 🟢 | 테넌트 설정 전용 Context 없음 |
+
+---
+
+## 작업 영역 구분: 프론트 단독 vs 백엔드 협의
+
+### 선행 확인 사항
+
+> **핵심 질문**: "백엔드가 이미 JWT 토큰 안의 tenant_id로 데이터를 필터링하고 있는가?"
+>
+> - **Yes** → 프론트에서 별도 X-Tenant-ID 안 보내도 됨. Phase 1은 불필요하고 프론트 단독 Phase부터 진행
+> - **No** → 백엔드도 같이 수정 필요. Phase 1이 최우선
+
+### 프론트 단독 가능 (백엔드 수정 불필요)
+
+| Phase | 작업 | 이유 |
+|-------|------|------|
+| **3** | 포매터 다국어/다통화 전환 | `formatAmount()`, `formatDate()` 등 프론트 유틸리티 내부 수정. 기본값을 한국어로 유지하면 하위 호환 |
+| **6** | localStorage 잔재 정리 + tenantId 타입 통일 | 프론트 코드 정리. TenantAwareCache 미사용 곳 마이그레이션, `string` → `number` 통일 |
+| **8** | 테넌트 라우팅 (필요 시) | Next.js App Router 구조 변경. 순수 프론트 라우팅 |
+
+> **즉시 착수 가능**: 백엔드 협의 결과를 기다리지 않고 바로 시작할 수 있음
+
+### 백엔드 협의 필요 (프론트 + 백엔드 동시 수정)
+
+| Phase | 작업 | 백엔드 필요 이유 |
+|-------|------|-----------------|
+| **1** | API 테넌트 컨텍스트 주입 | 프론트에서 `X-Tenant-ID` 헤더를 보내도, **백엔드가 읽고 필터링**해줘야 의미 있음. 안 읽으면 보내봤자 무용지물 |
+| **2** | Server Actions 마이그레이션 | Phase 1에 종속. 백엔드가 헤더 or URL로 테넌트를 구분 안 하면 프론트만 바꿔도 소용없음 |
+| **4** | 브랜딩 동적화 | 테넌트별 로고/앱이름을 **어디서 가져오나?** → 백엔드 API 필요 (`GET /api/v1/tenant/config`) |
+| **5** | 상수/공휴일 외부화 | 공휴일 데이터를 **DB에서 서빙**해야 함 → 백엔드 API 필요 (`GET /api/v1/holidays?year=2026`) |
+| **7** | TenantConfigService | 테넌트 설정 통합 API 필요 → branding + regional + features를 한 번에 가져오는 엔드포인트 |
+
+### 추천 진행 순서
+
+```
+[즉시 시작 - 프론트 단독]
+  Phase 3 (포매터) + Phase 6 (localStorage/타입) 병렬 진행
+
+[백엔드 협의 후 시작]
+  Phase 1 (API 헤더) → Phase 2 (Actions)
+
+[백엔드 API 준비 후 시작]
+  Phase 7 (TenantConfigService) → Phase 4 (브랜딩) + Phase 5 (상수)
+```
+
+---
+
+## Phase 1: API 레이어 테넌트 컨텍스트 주입 🔴 `백엔드 협의 필요`
+
+> **목표**: 모든 백엔드 API 호출에 테넌트 식별 정보가 전달되도록 함
+> **예상**: 3-5일
+
+### 1-1. 로그인 시 tenant_id 쿠키 추가
+
+**파일**: `src/app/api/auth/login/route.ts`
+
+**현재**: access_token, refresh_token 쿠키만 설정
+**변경**: tenant_id 쿠키 추가 (HttpOnly, API 프록시에서 읽기용)
+
+```typescript
+// 로그인 성공 후 추가
+const tenantCookie = [
+  `tenant_id=${data.tenant.id}`,
+  'HttpOnly',
+  ...(isProduction ? ['Secure'] : []),
+  'SameSite=Lax',
+  'Path=/',
+  `Max-Age=${data.expires_in || 7200}`,
+].join('; ');
+response.headers.append('Set-Cookie', tenantCookie);
+```
+
+### 1-2. API 프록시에 X-Tenant-ID 헤더 추가
+
+**파일**: `src/app/api/proxy/[...path]/route.ts`
+
+**현재**:
+```typescript
+const headers = {
+  'Accept': 'application/json',
+  'X-API-KEY': process.env.API_KEY || '',
+  'Authorization': `Bearer ${token}`,
+};
+```
+
+**변경**:
+```typescript
+const tenantId = request.cookies.get('tenant_id')?.value;
+const headers = {
+  'Accept': 'application/json',
+  'X-API-KEY': process.env.API_KEY || '',
+  'Authorization': `Bearer ${token}`,
+  ...(tenantId && { 'X-Tenant-ID': tenantId }),
+};
+```
+
+### 1-3. serverFetch 래퍼에 테넌트 헤더 추가
+
+**파일**: `src/lib/api/fetch-wrapper.ts`
+
+**현재**: Authorization 헤더만 전달
+**변경**: tenant_id 쿠키 읽어서 X-Tenant-ID 헤더 자동 추가
+
+```typescript
+export async function serverFetch(url: string, options?: RequestInit) {
+  const cookieStore = await cookies();
+  const token = cookieStore.get('access_token')?.value;
+  const tenantId = cookieStore.get('tenant_id')?.value;
+
+  const headers = {
+    ...options?.headers,
+    'Authorization': `Bearer ${token}`,
+    ...(tenantId && { 'X-Tenant-ID': tenantId }),
+  };
+  // ...
+}
+```
+
+### 1-4. ApiClient 클래스에 테넌트 지원
+
+**파일**: `src/lib/api/client.ts`
+
+**변경**: `getAuthHeaders()`에 X-Tenant-ID 포함
+
+### 체크리스트
+
+```
+- [ ] login/route.ts에 tenant_id 쿠키 Set-Cookie 추가
+- [ ] proxy/[...path]/route.ts에서 tenant_id 쿠키 읽기 + X-Tenant-ID 헤더 전달
+- [ ] fetch-wrapper.ts serverFetch에 X-Tenant-ID 자동 추가
+- [ ] client.ts ApiClient에 tenantId 옵션 추가
+- [ ] authenticated-fetch.ts에도 테넌트 헤더 전파 확인
+- [ ] 로그아웃 시 tenant_id 쿠키 삭제 확인
+- [ ] 토큰 갱신 시 tenant_id 쿠키 유지 확인
+- [ ] 백엔드와 X-Tenant-ID 헤더 수신 방식 협의
+```
+
+---
+
+## Phase 2: Server Actions 점진적 마이그레이션 🔴 `백엔드 협의 필요`
+
+> **목표**: 70+ actions.ts에서 테넌트 컨텍스트가 자동 전달되도록 함
+> **예상**: 1-2주 (Phase 1 완료 후 자동 적용되는 부분 다수)
+
+### 2-1. 현재 패턴 분석
+
+대부분의 actions.ts가 이 패턴을 따름:
+```typescript
+const url = `${process.env.NEXT_PUBLIC_API_URL}/api/v1/endpoint`;
+const { response, error } = await serverFetch(url, { method: 'GET' });
+```
+
+### 2-2. 자동 적용 범위 (Phase 1 완료 시)
+
+Phase 1에서 `serverFetch`에 X-Tenant-ID를 자동 추가하면, **기존 actions.ts 대부분은 수정 없이** 테넌트 헤더가 전달됨.
+
+### 2-3. 수동 확인 필요 케이스
+
+`serverFetch`를 사용하지 않고 직접 `fetch()`를 호출하는 곳:
+```bash
+# 검색 대상
+grep -r "fetch(" src/components/*/actions.ts --include="*.ts" | grep -v serverFetch
+```
+
+### 2-4. 선택적 URL 테넌트 프리픽스
+
+백엔드가 URL 경로에 테넌트를 요구하는 경우만:
+```typescript
+// 필요한 경우에만 적용
+function buildTenantUrl(endpoint: string, tenantId?: string): string {
+  if (endpoint.startsWith('http')) return endpoint; // 레거시 호환
+  const base = process.env.NEXT_PUBLIC_API_URL;
+  return tenantId
+    ? `${base}/api/v1/tenant/${tenantId}/${endpoint}`
+    : `${base}/api/v1/${endpoint}`;
+}
+```
+
+### 체크리스트
+
+```
+- [ ] serverFetch 사용하지 않는 actions.ts 목록 확인
+- [ ] 직접 fetch() 호출하는 곳 serverFetch로 마이그레이션
+- [ ] 백엔드와 URL 패턴 vs 헤더 패턴 최종 협의
+- [ ] 고빈도 도메인 우선 검증: clients, items, production, sales
+- [ ] 에러 시 테넌트 컨텍스트 누락 로그 추가
+```
+
+---
+
+## Phase 3: 포매터 & 유틸리티 테넌트 설정 기반 전환 🔴 `프론트 단독 가능`
+
+> **목표**: 한국어 하드코딩된 포매터를 테넌트 설정 기반으로 변경
+> **예상**: 3-5일
+
+### 3-1. 영향받는 파일 목록
+
+| 파일 | 함수 | 하드코딩 내용 |
+|------|------|---------------|
+| `src/utils/formatAmount.ts` | `formatAmount()` | "원", "만원" |
+| `src/utils/formatAmount.ts` | `formatKoreanAmount()` | "억", "만" |
+| `src/lib/formatters.ts` | `formatBusinessNumber()` | 한국 사업자번호 (XXX-XX-XXXXX) |
+| `src/lib/formatters.ts` | `formatPhoneNumber()` | 한국 전화 (02-, 010-) |
+| `src/utils/date.ts` | `formatDate()` | `'ko-KR'` 로케일 |
+
+### 3-2. TenantRegionalConfig 인터페이스
+
+```typescript
+// src/types/tenant-config.ts (신규)
+export interface TenantRegionalConfig {
+  locale: string;           // 'ko-KR' | 'en-US' | 'ja-JP'
+  timezone: string;         // 'Asia/Seoul' | 'America/New_York'
+  currency: {
+    code: string;           // 'KRW' | 'USD' | 'JPY'
+    symbol: string;         // '원' | '$' | '¥'
+    locale: string;         // Intl.NumberFormat 로케일
+    largeUnitName?: string; // '만' (한국 전용)
+    largeUnitValue?: number; // 10000
+  };
+  phone: {
+    countryCode: string;    // '+82' | '+1' | '+81'
+    format: string;         // 'XXX-XXXX-XXXX'
+  };
+  businessNumber: {
+    format: string;         // 'XXX-XX-XXXXX'
+    label: string;          // '사업자번호' | 'Business No.' | '法人番号'
+  };
+}
+```
+
+### 3-3. 마이그레이션 접근 (하위 호환)
+
+기존 함수를 바로 변경하지 않고, 오버로드 + 기본값 패턴 적용:
+
+```typescript
+// 기존 호출 코드를 깨지 않는 방식
+export function formatAmount(amount: number, config?: TenantCurrencyConfig): string {
+  const cfg = config ?? DEFAULT_KR_CURRENCY_CONFIG; // 기본값: 한국
+  // ... 테넌트 설정 기반 포매팅
+}
+```
+
+### 3-4. 기존 공통화 작업 참조
+
+**이미 작성된 관련 문서**:
+- `claudedocs/[IMPL-2026-02-05] formatter-commonization-plan.md`
+- `claudedocs/[ANALYSIS-2026-01-20] 공통화-현황-분석.md`
+
+이 문서들의 포매터 공통화 계획과 병합하여 진행.
+
+### 체크리스트
+
+```
+- [ ] TenantRegionalConfig 인터페이스 정의
+- [ ] DEFAULT_KR_CONFIG 기본값 생성 (하위 호환)
+- [ ] formatAmount() 테넌트 설정 지원 추가
+- [ ] formatDate() 테넌트 로케일 지원 추가
+- [ ] formatBusinessNumber() 포맷 설정 지원 추가
+- [ ] formatPhoneNumber() 국가 코드 지원 추가
+- [ ] 기존 호출 코드 깨지지 않는지 검증
+- [ ] formatter-commonization-plan.md와 통합
+```
+
+---
+
+## Phase 4: 브랜딩 동적화 🟡 `백엔드 API 필요`
+
+> **목표**: 하드코딩된 회사명/로고를 테넌트 설정 기반으로 변경
+> **예상**: 2-3일
+
+### 4-1. 영향받는 파일 목록
+
+| 파일 | 하드코딩 | 변경 방향 |
+|------|----------|-----------|
+| `src/layouts/AuthenticatedLayout.tsx` | `APP_NAME = 'SAM'` | `tenant.company_name` 또는 테넌트 설정 |
+| `src/layouts/AuthenticatedLayout.tsx` | `<Image src="/sam-logo.png">` | 테넌트별 로고 URL |
+| `src/layouts/AuthenticatedLayout.tsx` | `MOCK_COMPANIES` 배열 | `user.tenant.other_tenants` 연동 |
+| `src/app/[locale]/layout.tsx` | `APP_TITLE = 'SAM - 내 손안의 대시보드'` | 테넌트 설정 기반 |
+| `src/app/[locale]/layout.tsx` | SEO 메타데이터 | 테넌트별 (단, 폐쇄형이므로 낮은 우선순위) |
+
+### 4-2. 테넌트 브랜딩 설정 구조
+
+```typescript
+// src/types/tenant-config.ts에 추가
+export interface TenantBrandingConfig {
+  appName: string;            // 'SAM' | '주일 MES' | 커스텀
+  appSubtitle?: string;       // 'Smart Automation Management'
+  logoUrl: string;            // '/sam-logo.png' | '/tenants/282/logo.png'
+  faviconUrl?: string;
+  primaryColor?: string;      // 테마 주색상
+  loginBackground?: string;   // 로그인 페이지 배경
+}
+```
+
+### 4-3. 적용 방식
+
+```typescript
+// AuthenticatedLayout.tsx 내부
+const { currentUser } = useAuth();
+const branding = currentUser?.tenant?.branding ?? DEFAULT_BRANDING;
+
+// 로고
+<Image src={branding.logoUrl} alt={branding.appName} />
+
+// 앱 이름
+<h1>{branding.appName}</h1>
+```
+
+### 4-4. MOCK_COMPANIES → other_tenants 연동
+
+**현재**: 하드코딩 목업
+```typescript
+const MOCK_COMPANIES = [
+  { id: 'all', name: '전체' },
+  { id: 'company1', name: '(주)삼성건설' },
+  ...
+];
+```
+
+**변경**: 실제 테넌트 데이터 연동
+```typescript
+const tenantOptions = useMemo(() => {
+  const current = currentUser?.tenant;
+  const others = current?.other_tenants ?? [];
+  return [current, ...others].filter(Boolean);
+}, [currentUser]);
+```
+
+### 체크리스트
+
+```
+- [ ] TenantBrandingConfig 인터페이스 정의
+- [ ] DEFAULT_BRANDING 기본값 (현재 SAM 설정)
+- [ ] AuthenticatedLayout 로고/앱이름 동적화
+- [ ] MOCK_COMPANIES를 other_tenants 기반으로 교체
+- [ ] 로그인 페이지 브랜딩 동적화
+- [ ] favicon 동적 변경 (선택)
+- [ ] 테넌트별 로고 파일 서빙 방식 결정 (public/ vs API)
+```
+
+---
+
+## Phase 5: 상수 & 비즈니스 로직 외부화 🟡 `백엔드 API 필요`
+
+> **목표**: 한국 특화 상수를 테넌트/국가별 설정으로 외부화
+> **예상**: 3-5일
+
+### 5-1. 영향받는 항목
+
+| 항목 | 파일 | 현재 | 변경 |
+|------|------|------|------|
+| 공휴일 | `src/constants/calendarEvents.ts` | 한국 공휴일 하드코딩 | DB/API 기반 |
+| 프로세스 타입 | `src/types/process.ts` | "생산", "검사" 등 | i18n 라벨 |
+| 상태 라벨 | `src/lib/utils/status-config.ts` | "대기", "완료" 등 | i18n 라벨 |
+| 품목 타입 | `src/types/item.ts` | "제품", "부품" 등 | i18n 라벨 |
+| 근무일 | 관련 컴포넌트 | 월-금 하드코딩 | 테넌트 설정 |
+
+### 5-2. 외부화 전략
+
+**공휴일**: 백엔드 API로 이동 (테넌트별 국가 설정에 따라 반환)
+```typescript
+// AS-IS: 하드코딩
+const HOLIDAYS_2026 = [
+  { date: '2026-01-01', name: '신정', type: 'holiday' },
+  ...
+];
+
+// TO-BE: API 호출
+const holidays = await getHolidays(tenantId, year);
+```
+
+**라벨/상태**: next-intl 다국어 시스템 활용 (이미 ko/en/ja 구조 있음)
+```typescript
+// AS-IS
+const statusLabels = { pending: '대기', completed: '완료' };
+
+// TO-BE
+const t = useTranslations('status');
+const label = t('pending'); // 로케일에 따라 자동 변환
+```
+
+### 체크리스트
+
+```
+- [ ] calendarEvents.ts 공휴일 데이터 → API 엔드포인트로 이동
+- [ ] 프로세스 타입 라벨 → messages/ko.json, en.json, ja.json으로 이동
+- [ ] 상태 라벨 → i18n 키로 변환
+- [ ] 품목 타입 라벨 → i18n 키로 변환
+- [ ] 근무일 설정 → 테넌트 config로 이동
+- [ ] 백엔드에 공휴일 API 요청
+```
+
+---
+
+## Phase 6: localStorage 잔재 정리 & 타입 통일 🟡 `프론트 단독 가능`
+
+> **목표**: TenantAwareCache 미사용 곳 정리 + tenantId 타입 통일
+> **예상**: 2-3일
+
+### 6-1. localStorage 직접 사용 감사
+
+```bash
+# 검색 대상
+grep -r "localStorage\.\(setItem\|getItem\)" src/ --include="*.ts" --include="*.tsx"
+```
+
+**알려진 비-테넌트-스코프 키**:
+- `mes-users` → 사용자 목록 (테넌트 스코프 필요 여부 검토)
+- `mes-currentUser` → 현재 사용자 (로그인 상태이므로 테넌트 무관)
+- 기타 직접 사용 곳 → TenantAwareCache 또는 테넌트 프리픽스 적용
+
+### 6-2. tenantId 타입 통일
+
+**현재 상황**:
+- `User.tenant.id` → `number` (AuthContext)
+- `PageConfig.tenantId` → `string` (masterDataStore)
+- TenantAwareCache → `number`
+
+**통일**: `number`로 표준화 (백엔드 응답 기준)
+
+```typescript
+// 수정 대상 찾기
+grep -r "tenantId.*string" src/ --include="*.ts"
+```
+
+### 체크리스트
+
+```
+- [ ] localStorage 직접 사용 전수 조사
+- [ ] TenantAwareCache로 마이그레이션 가능한 곳 목록화
+- [ ] 테넌트 스코프 불필요한 곳 명시 (mes-currentUser 등)
+- [ ] tenantId: string → number 통일
+- [ ] PageConfig 타입 수정
+- [ ] 관련 타입 참조 전부 업데이트
+```
+
+---
+
+## Phase 7: TenantConfigService & TenantContext (선택) 🟢 `백엔드 API 필요`
+
+> **목표**: 테넌트 설정을 한곳에서 관리하는 서비스 레이어
+> **예상**: 3-5일 (Phase 3-5 진행 중 필요에 따라)
+
+### 7-1. TenantConfigService
+
+```typescript
+// src/services/TenantConfigService.ts (신규)
+export interface TenantConfiguration {
+  tenantId: number;
+  branding: TenantBrandingConfig;
+  regional: TenantRegionalConfig;
+  features: {
+    enabledModules: string[];
+    customFields?: Record<string, unknown>;
+  };
+  calendar: {
+    workingDays: number[];   // [1,2,3,4,5] = 월-금
+    holidays: HolidayEntry[];
+  };
+}
+
+class TenantConfigService {
+  private cache: Map<number, TenantConfiguration> = new Map();
+
+  async getConfig(tenantId: number): Promise<TenantConfiguration> {
+    if (this.cache.has(tenantId)) return this.cache.get(tenantId)!;
+    const config = await this.fetchFromApi(tenantId);
+    this.cache.set(tenantId, config);
+    return config;
+  }
+}
+```
+
+### 7-2. TenantContext Provider
+
+```typescript
+// src/contexts/TenantContext.tsx (신규)
+export function TenantProvider({ children }: { children: ReactNode }) {
+  const { currentUser } = useAuth();
+  const [config, setConfig] = useState<TenantConfiguration>();
+
+  useEffect(() => {
+    if (currentUser?.tenant?.id) {
+      tenantConfigService.getConfig(currentUser.tenant.id)
+        .then(setConfig);
+    }
+  }, [currentUser?.tenant?.id]);
+
+  return (
+    <TenantContext.Provider value={config}>
+      {children}
+    </TenantContext.Provider>
+  );
+}
+
+// 사용
+const tenantConfig = useTenantConfig();
+const currencySymbol = tenantConfig.regional.currency.symbol;
+```
+
+### 체크리스트
+
+```
+- [ ] TenantConfiguration 통합 인터페이스 설계
+- [ ] TenantConfigService 구현 (캐시 + API 호출)
+- [ ] TenantContext Provider 구현
+- [ ] useTenantConfig() 훅 구현
+- [ ] Protected Layout에 TenantProvider 추가
+- [ ] 기존 코드에서 점진적 마이그레이션
+```
+
+---
+
+## Phase 8: 테넌트 라우팅 (필요 시) 🟢 `프론트 단독 가능`
+
+> **목표**: URL에 테넌트 식별자 포함 (필요한 경우에만)
+> **예상**: 1주+
+
+### 현재 라우팅
+```
+/[locale]/(protected)/dashboard
+```
+
+### 옵션 A: 경로 기반 (권장 - 필요 시)
+```
+/[tenant]/[locale]/(protected)/dashboard
+/acme/ko/dashboard
+```
+
+### 옵션 B: 서브도메인 기반
+```
+acme.sam.com/ko/dashboard
+```
+
+### 옵션 C: 현재 유지 (인증 기반만)
+```
+/[locale]/(protected)/dashboard  ← 테넌트는 JWT/쿠키로만 식별
+```
+
+**결정**: 현재는 **옵션 C 유지**. 다중 테넌트 URL 분리가 필요해지면 옵션 A 도입.
+
+---
+
+## 백엔드 협의 사항
+
+### 필수 협의 (Phase 1 시작 전)
+
+| 항목 | 질문 | 결정 사항 |
+|------|------|-----------|
+| 테넌트 식별 방식 | `X-Tenant-ID` 헤더 vs URL 경로 vs JWT만? | TBD |
+| X-Tenant-ID 수신 | 백엔드가 이 헤더를 읽고 필터링하는지? | TBD |
+| JWT 내 tenant_id | 토큰에 tenant_id가 포함되어 있는지? | TBD |
+| 공휴일 API | `GET /api/v1/holidays?year=2026` 지원? | TBD |
+| 테넌트 설정 API | `GET /api/v1/tenant/config` 지원? | TBD |
+
+### 선택 협의 (Phase 4-5 시작 전)
+
+| 항목 | 질문 | 결정 사항 |
+|------|------|-----------|
+| 테넌트 로고 | 로고 URL을 어디서 제공? (API vs 파일서버) | TBD |
+| 브랜딩 설정 | 테넌트별 앱이름/테마 API 제공 가능? | TBD |
+| 다국어 라벨 | 백엔드 코드 라벨이 다국어 지원? | TBD |
+
+---
+
+## 실행 우선순위 요약
+
+```
+[프론트 단독]  Phase 3: 포매터 테넌트 설정 기반      🔴 3-5일   ← 즉시 시작 가능
+[프론트 단독]  Phase 6: localStorage 정리/타입 통일  🟡 2-3일   ← 즉시 시작 가능
+[프론트 단독]  Phase 8: 테넌트 라우팅               🟢 필요시   ← 당분간 불필요
+
+[백엔드 협의]  Phase 1: API 테넌트 컨텍스트 주입    🔴 3-5일   ← 백엔드 확인 후
+[백엔드 협의]  Phase 2: Server Actions 마이그레이션  🔴 1-2주   ← Phase 1 후 자동 적용 범위 큼
+
+[백엔드 API]   Phase 4: 브랜딩 동적화               🟡 2-3일   ← 테넌트 설정 API 필요
+[백엔드 API]   Phase 5: 상수/공휴일 외부화           🟡 3-5일   ← 공휴일 API 필요
+[백엔드 API]   Phase 7: TenantConfigService         🟢 3-5일   ← 통합 설정 API 필요
+```
+
+### 병렬 진행 가능 조합
+
+```
+[즉시 시작 - 프론트 단독]
+├─ Phase 3 (포매터) ─────────→ 독립 완료
+└─ Phase 6 (localStorage) ──→ 독립 완료
+
+[백엔드 협의 후 - 프론트+백엔드]
+└─ Phase 1 (API 헤더) ──────→ Phase 2 (Actions 자동 적용)
+
+[백엔드 API 준비 후 - 프론트+백엔드]
+└─ Phase 7 (TenantConfig) ──→ Phase 4 (브랜딩) + Phase 5 (상수)
+```
+
+---
+
+## 위험 요소 & 대응
+
+| 위험 | 확률 | 영향 | 대응 |
+|------|------|------|------|
+| 70+ actions.ts 수동 마이그레이션 | 높음 | 중간 | serverFetch 자동 주입으로 대부분 해결 |
+| 백엔드 X-Tenant-ID 미지원 | 중간 | 높음 | Phase 1 시작 전 백엔드 팀 협의 필수 |
+| 포매터 변경 시 기존 UI 깨짐 | 낮음 | 중간 | 기본값 패턴으로 하위 호환 유지 |
+| 캐시 무효화 누락 | 낮음 | 높음 | TenantAwareCache 이미 검증됨 |
+| 다국어 번역 리소스 부족 | 중간 | 낮음 | 한국어 기본값 유지, 점진 추가 |
+
+---
+
+## 관련 문서
+
+| 문서 | 설명 |
+|------|------|
+| `architecture/[REF-2025-11-19] multi-tenancy-implementation.md` | 이전 멀티테넌시 구현 (Phase 1-2 → 완료됨) |
+| `architecture/[TEST-2025-11-19] multi-tenancy-test-guide.md` | 캐시 격리 테스트 가이드 |
+| `architecture/[FIX-2026-01-29] masterdata-cache-tenant-isolation.md` | masterDataStore 캐시 테넌트 격리 수정 |
+| `[IMPL-2026-02-05] formatter-commonization-plan.md` | 포매터 공통화 계획 (Phase 3과 병합) |
+| `[ANALYSIS-2026-01-20] 공통화-현황-분석.md` | 공통화 현황 분석 |
+| `[ANALYSIS-2026-02-05] list-page-commonization-status.md` | 리스트 페이지 공통화 현황 |
+| `auth/[IMPL-2025-11-07] jwt-cookie-authentication-final.md` | JWT 쿠키 인증 구현 |
+| `api/[REF] api-requirements.md` | API 요구사항 |
+
+---
+
+## 변경 이력
+
+| 날짜 | 변경 내용 |
+|------|-----------|
+| 2026-02-06 | 초기 작성 - 전체 코드베이스 분석 기반 8 Phase 로드맵 |
+
+---
+
+**다음 액션**: Phase 1 시작 전 백엔드 팀과 `X-Tenant-ID` 헤더 수신 방식 협의

claudedocs/architecture/[PLAN-2026-02-06] refactoring-roadmap.md

@@ -0,0 +1,446 @@
+# 리팩토링 로드맵
+
+**작성일**: 2026-02-06
+**목적**: 전체 코드베이스 리팩토링 포인트 점검 및 실행 계획
+**상태**: Phase 1 완료, Phase 3 완료 (공용 유틸 추출), Phase 4 SearchableSelectionModal 완료
+
+---
+
+## 현재 코드베이스 수치 (2026-02-06 기준)
+
+| 지표 | 수치 | 비고 |
+|------|------|------|
+| 전체 코드 | ~301,000줄 | TS/TSX |
+| 컴포넌트 파일 | ~551개 | |
+| 페이지 파일 | ~253개 | |
+| action.ts 파일 | 80개 | 거의 동일 CRUD 패턴 |
+| types.ts 파일 | 94개 | 중복 타입 다수 |
+| 모달 컴포넌트 | 42개 | 유사 패턴 반복 |
+| 2000줄+ 파일 | 4개 | God 컴포넌트 |
+| 1000~2000줄 파일 | 25+개 | 분리 대상 |
+| 500~1000줄 파일 | 50+개 | 검토 대상 |
+
+---
+
+## God 컴포넌트 / 대형 파일 목록
+
+### 🔴 2000줄 이상 (즉시 분리 필요)
+
+| 파일 | 줄수 | 핵심 문제 | 분리 방향 |
+|------|------|-----------|-----------|
+| `components/business/MainDashboard.tsx` | 2,651 | CEO/영업/생산/품질 대시보드 한 파일 | 역할별 섹션 컴포넌트 분리 |
+| `contexts/ItemMasterContext.tsx` | 2,406 | useState 17개, useEffect 15개, 함수 50+개 | 도메인별 5개 Context 분리 |
+| `lib/api/item-master.ts` | 2,232 | 모든 품목 API 한 파일 | 도메인별 API 모듈 분리 |
+| `lib/api/dashboard/transformers.ts` | 1,576 | 전체 대시보드 변환 로직 | 섹션별 transformer 분리 |
+
+### 🟡 1000~2000줄 (우선 검토)
+
+| 파일 | 줄수 | 도메인 | 분리 방향 |
+|------|------|--------|-----------|
+| `components/orders/actions.ts` | 1,394 | 수주 | 서비스 레이어 분리 |
+| `components/accounting/ExpectedExpenseManagement/index.tsx` | 1,299 | 회계 | 서브 컴포넌트 추출 |
+| `layouts/AuthenticatedLayout.tsx` | 1,289 | 레이아웃 | 훅 24개 → 섹션별 분리 |
+| `components/quotes/QuoteRegistration.tsx` | 1,268 | 견적 | 폼 섹션 추출, useState 13개 |
+| `components/quotes/actions.ts` | 1,266 | 견적 | API 레이어 분리 |
+| `components/business/construction/management/actions.ts` | 1,222 | 건설 | 도메인 서비스 추출 |
+| `components/business/construction/estimates/actions.ts` | 1,222 | 건설 | 도메인 서비스 추출 |
+| `components/production/WorkerScreen/index.tsx` | 1,198 | 생산 | 화면 섹션 분리 |
+| `hooks/useCEODashboard.ts` | 1,172 | 대시보드 | useState 18개 → 섹션별 훅 분리 |
+| `components/material/ReceivingManagement/actions.ts` | 1,152 | 자재 | API 서비스 레이어 |
+| `components/quotes/types.ts` | 1,149 | 견적 | 타입 조직화 |
+| `components/quality/InspectionManagement/InspectionDetail.tsx` | 1,125 | 품질 | 컴포넌트 추출 |
+| `components/hr/VacationManagement/actions.ts` | 1,125 | HR | 서비스 레이어 분리 |
+| `components/orders/OrderRegistration.tsx` | 1,123 | 수주 | 폼 섹션 추출, useState 12개 |
+| `components/items/DynamicItemForm/index.tsx` | 1,073 | 품목 | 복합 폼 로직 추출 |
+| `components/templates/IntegratedListTemplateV2.tsx` | 1,066 | 템플릿 | 템플릿 특화 |
+| `components/hr/EmployeeManagement/EmployeeForm.tsx` | 1,051 | HR | 폼 섹션 분리 |
+| `components/quotes/QuoteRegistrationV2.tsx` | 1,020 | 견적 | 폼 리팩토링 |
+| `components/templates/UniversalListPage/index.tsx` | 1,007 | 템플릿 | 템플릿 최적화 |
+| `components/items/ItemMasterDataManagement.tsx` | 1,005 | 품목 | 도메인 로직 추출 |
+
+---
+
+## 중복 패턴 분석
+
+### 1. 액션 파일 80개 동일 패턴 (~24,000줄 중복)
+
+**현재**: 모든 도메인이 이 구조를 복붙
+```typescript
+'use server';
+import { serverFetch } from '@/lib/api/fetch-wrapper';
+
+interface Api[Domain]Data { ... }         // 타입 정의 100~300줄
+function transform(data) { ... }          // API→프론트 변환 50~100줄
+
+export async function getList(params) {   // 목록 조회
+  const url = `${API_URL}/api/v1/endpoint`;
+  const { response } = await serverFetch(url, { method: 'GET' });
+  return transform(response);
+}
+export async function getById(id) { ... } // 상세 조회
+export async function create(data) { ... } // 생성
+export async function update(id, data) { ... } // 수정
+export async function delete(id) { ... }  // 삭제
+export async function bulkDelete(ids) { ... } // 일괄 삭제
+```
+
+**해당 도메인**: orders, quotes, clients, accounting(13모듈), hr(6모듈), production(4모듈), material(2모듈), quality(2모듈), construction(17모듈), settings(14모듈)
+
+**해결 방향**: 제네릭 API 서비스 팩토리
+```typescript
+// lib/api/createCrudService.ts
+function createCrudService<TApi, TFront>(config: {
+  endpoint: string;
+  transform: (api: TApi) => TFront;
+  reverseTransform: (front: TFront) => Partial<TApi>;
+}) {
+  return {
+    getList: async (params) => { ... },
+    getById: async (id) => { ... },
+    create: async (data) => { ... },
+    update: async (id, data) => { ... },
+    delete: async (id) => { ... },
+    bulkDelete: async (ids) => { ... },
+  };
+}
+
+// 사용: 10줄로 끝
+const orderService = createCrudService<ApiOrder, Order>({
+  endpoint: 'orders',
+  transform: transformOrder,
+  reverseTransform: reverseTransformOrder,
+});
+```
+
+### 2. 데이터 페칭 패턴 3가지 혼재
+
+| 패턴 | 사용 비율 | 위치 |
+|------|-----------|------|
+| useEffect + .then() 직접 호출 | ~75% (99+ 컴포넌트) | 대부분의 도메인 |
+| 커스텀 훅 (useDetailData 등) | ~15% (~15 컴포넌트) | 신규 구현 |
+| ApiClient 클래스 | ~10% (15 컴포넌트) | 건설 도메인만 |
+
+**수동 로딩 상태 관리**: 262곳에서 반복
+```typescript
+// 이 패턴이 262번 반복됨
+const [data, setData] = useState([]);
+const [isLoading, setIsLoading] = useState(true);
+const [error, setError] = useState(null);
+
+useEffect(() => {
+  setIsLoading(true);
+  fetchData()
+    .then(result => setData(result))
+    .catch(err => setError(err))
+    .finally(() => setIsLoading(false));
+}, []);
+```
+
+### 3. 폼 검증 3가지 방식 혼재
+
+| 방식 | 사용 파일 수 | 비율 |
+|------|-------------|------|
+| Zod 스키마 (정석) | 3개 (로그인, 회원가입, 품목) | 5% |
+| 수동 if문 검증 | 50+개 | 60% |
+| 검증 없음 | ~30개 | 35% |
+
+### 4. 리스트 페이지 템플릿 이중화
+
+| 방식 | 사용 | 비율 |
+|------|------|------|
+| `UniversalListPage` (신규 표준) | 20개 페이지 | 25% |
+| 수동 구현 (레거시) | 60+ 페이지 | 75% |
+
+### 5. 모달/다이얼로그 42개 유사 패턴
+
+**검색/선택 모달 5개+ 거의 동일**:
+- `quotes/ItemSearchModal.tsx`
+- `production/WorkOrders/AssigneeSelectModal.tsx`
+- `material/ReceivingManagement/SupplierSearchModal.tsx`
+- `quality/InspectionManagement/OrderSelectModal.tsx`
+- `production/WorkOrders/SalesOrderSelectModal.tsx`
+
+전부 "검색 입력 → API 호출 → 목록 표시 → 체크박스 선택 → 확인" 동일 구조
+→ `SearchableSelectionModal<T>` 하나로 통합 가능
+
+---
+
+## 성능 최적화 포인트
+
+| 항목 | 현재 상태 | 영향도 | 해결 방향 |
+|------|-----------|--------|-----------|
+| React.memo | 551개 컴포넌트 중 **1개만** 사용 | 🔴 높음 | 리스트 아이템/카드 컴포넌트에 적용 |
+| 인라인 화살표 함수 | **746곳** `onClick={() => ...}` | 🟡 중간 | 대형 컴포넌트에서 useCallback 적용 |
+| useMemo 미사용 | 대용량 배열 필터링/정렬 곳곳 | 🟡 중간 | 비용 높은 계산에 적용 |
+
+**React.memo 우선 적용 대상** (리스트 내 반복 렌더링 컴포넌트):
+- `production/WorkerScreen/WorkItemCard.tsx`
+- `board/CommentSection/CommentItem.tsx`
+- `business/construction/management/ProjectCard.tsx`
+- 기타 *Row, *Item, *Card 컴포넌트 30+개
+
+---
+
+## 타입 시스템 문제
+
+| 항목 | 수치 | 영향 |
+|------|------|------|
+| `any` 타입 사용 | 102곳 (29개 파일) | 타입 안전성 저하 |
+| 동일 엔티티 다중 타입 정의 | Vendor, Item, Order 등 | 변환 코드 ~800줄 중복 |
+| types.ts 파일 | 94개 | 정규 타입 찾기 어려움 |
+| @ts-ignore/eslint-disable | 25개 파일 | 숨겨진 타입 에러 |
+
+---
+
+## 추출 가능한 공통 훅 목록
+
+### 즉시 생성 가능 (프론트 단독)
+
+| 훅 이름 | 대체 범위 | 예상 절감 | 기존 참고 |
+|---------|-----------|-----------|-----------|
+| `useListData` | 60+ 리스트 페이지 | ~4,000줄 | hooks/useDetailData.ts 패턴 확장 |
+| `useFormSubmit` | 80+ 폼 | ~3,000줄 | 신규 |
+| `usePagination` | 60+ 컴포넌트 | ~1,000줄 | 신규 |
+| `useModal<T>` | 42 모달 | ~500줄 | 신규 |
+| `useClientSideFiltering` | 55+ 컴포넌트 | ~800줄 | 신규 |
+
+### 기존 훅 (활용 확대 필요)
+
+| 훅 | 현재 사용 | 전체 적용 시 |
+|----|-----------|-------------|
+| `useDetailData` | ~15 컴포넌트 | 100+ 상세 페이지 |
+| `useDetailPageState` | ~10 컴포넌트 | 100+ 상세 페이지 |
+| `useCRUDHandlers` | ~10 컴포넌트 | 80+ CRUD 페이지 |
+
+---
+
+## 실행 계획
+
+### Phase 1: 공통 훅 추출 ✅ 완료 (2026-02-09)
+
+> 실제 코드 분석 결과 계획 수정 → 실증 기반 리팩토링 실행
+
+**실행 결과** (계획 vs 실제):
+```
+기존 계획의 useListData, usePagination, useClientSideFiltering, useModal은
+UniversalListPage 템플릿이 이미 내부 처리 → 불필요 판정.
+
+실제 실행:
+- [x] Step 1: executeServerAction (82개 action.ts 에러처리 래퍼) → ~3,000줄 절감
+- [x] Step 2: useDeleteDialog (6개 파일 삭제 다이얼로그 통합) → ~150줄 절감
+- [x] Step 3: useStatsLoader (7개 파일 stats 로딩 통합) → ~100줄 절감
+- [x] Step 4: React.memo 3개 + any→unknown 7건 + @ts-ignore 0건
+```
+
+**실제 효과**: ~3,750줄 절감, 82개 action.ts 패턴 통일, 타입 안전성 향상
+**상세**: `refactoring/[IMPL-2026-02-09] phase1-common-hooks-checklist.md`
+
+---
+
+### Phase 2: God 컴포넌트 분리 (2-3주) `프론트 단독`
+
+> 2000줄+ 파일 4개 + 핵심 1000줄+ 파일 우선 분리
+
+**작업 항목**:
+```
+- [ ] MainDashboard.tsx (2,651줄) 분리
+      → sections/CEOSection, SalesSection, ProductionSection, QualitySection
+      → hooks/useDashboardData
+      → utils/calculations
+- [ ] ItemMasterContext.tsx (2,406줄) 분리
+      → ItemContext, SpecificationContext, MaterialContext
+      → TemplateContext, AttributeContext
+- [ ] useCEODashboard.ts (1,172줄) 분리
+      → useDailyReport, useReceivables, useMonthlyExpense 등 개별 훅
+      → 훅 팩토리 패턴 적용
+- [ ] lib/api/item-master.ts (2,232줄) 분리
+      → 도메인별 API 모듈 (items, specifications, materials, templates)
+- [ ] AuthenticatedLayout.tsx (1,289줄)
+      → useLayoutState, useNavigation, useTenantBranding 훅 추출
+```
+
+**예상 효과**: 유지보수성 +50%, 단위 테스트 가능성 확보
+
+---
+
+### Phase 3: 액션 파일 공용 유틸 추출 ✅ 완료 (2026-02-10)
+
+> 전수 분석 → 팩토리 ROI 재평가 → 공용 유틸 추출로 전략 변경
+
+**전수 분석 결과** (82개 action 파일):
+```
+- 35개: executeServerAction 패턴 (Phase 1에서 통일)
+- 15개: 모의 데이터 (mock, API 미연동)
+- 13개: ApiClient 클래스 패턴 (건설 도메인)
+- 나머지: 특수 도메인 로직 (견적, 수주, 품목 등)
+```
+
+**팩토리 마이그레이션 ROI 재평가**:
+```
+- createCrudService 팩토리: 2개(Rank, Title)만 적합 → ROI ~6% (너무 낮음)
+- 대부분 파일: 페이지네이션, 커스텀 쿼리 파라미터, 도메인 특화 로직으로 팩토리 패턴 부적합
+- 결론: 팩토리 대량 마이그레이션 대신 공용 유틸 추출로 전략 전환
+```
+
+**실행 결과** (2026-02-10):
+```
+Step 1: 공용 타입 추출 (src/lib/api/types.ts)
+  - [x] PaginatedApiResponse<T> — 25+ 파일에서 중복 정의 제거
+  - [x] PaginationMeta, PaginatedResult<T> — 프론트엔드 표준 페이지네이션 타입
+  - [x] toPaginationMeta() — snake_case → camelCase 변환 헬퍼
+  - [x] SelectOption — 공용 선택 옵션 타입
+
+Step 2: 공용 룩업 헬퍼 추출 (src/lib/api/shared-lookups.ts)
+  - [x] fetchVendorOptions() — 거래처 목록 조회 (4개 파일 중복 제거)
+  - [x] fetchBankAccountOptions() — 계좌 목록 조회 (심플)
+  - [x] fetchBankAccountDetailOptions() — 계좌 상세 조회 (bankName, accountNumber 포함)
+  - [x] BankAccountOption 타입
+
+Step 3: PaginatedResponse 타입 마이그레이션 (~20개 파일)
+  - [x] 제네릭 패턴 (interface PaginatedResponse<T>) → import PaginatedApiResponse
+  - [x] 도메인 패턴 (interface XxxPaginatedResponse) → type alias
+  - 스킵: VendorManagement/types.ts (page?/size? 비표준), PermissionManagement/types.ts (meta 래퍼)
+
+Step 4: 공용 룩업 헬퍼 마이그레이션 (4개 파일)
+  - [x] DepositManagement/actions.ts — getVendors + getBankAccounts 교체
+  - [x] WithdrawalManagement/actions.ts — getVendors + getBankAccounts 교체
+  - [x] PurchaseManagement/actions.ts — getVendors + getBankAccounts(상세) 교체
+  - [x] ExpectedExpenseManagement/actions.ts — getBankAccounts(상세) 교체
+
+Step 5: TypeScript 검증 통과 ✅
+```
+
+**실측 효과**:
+- PaginatedResponse 중복 제거: ~20개 파일, 파일당 ~7줄 = ~140줄 절감
+- 공용 룩업 헬퍼: 4개 파일, 파일당 ~20줄 = ~80줄 절감
+- 총 ~220줄 직접 절감 + 향후 새 파일에서 중복 방지
+- createCrudService + TitleManagement 마이그레이션: ~36줄 절감 (프로토타입 포함)
+
+**생성된 공용 파일**:
+- `src/lib/api/types.ts` — 공용 API 타입 (PaginatedApiResponse, PaginationMeta 등)
+- `src/lib/api/shared-lookups.ts` — 공용 룩업 헬퍼 (fetchVendorOptions 등)
+- `src/lib/api/create-crud-service.ts` — CRUD 팩토리 (Rank, Title 2개 사용)
+
+---
+
+### Phase 4: 템플릿/패턴 통일 (2-3주) `프론트 단독` `SearchableSelectionModal 완료`
+
+> UniversalListPage 확대 + 검증 표준화 + 모달 통합
+
+**SearchableSelectionModal 완료** (2026-02-10):
+```
+- [x] SearchableSelectionModal<T> 공통 컴포넌트 생성
+      - types.ts, useSearchableData.ts, SearchableSelectionModal.tsx, index.ts
+      - 단일선택(single) + 다중선택(multiple) + listWrapper(테이블용) 지원
+- [x] ItemSearchModal 교체 (212→113줄, -47%)
+- [x] SupplierSearchModal 교체 (268→161줄, -40%)
+- [x] SalesOrderSelectModal 교체 (163→101줄, -38%)
+- [x] QuotationSelectDialog 교체 (196→113줄, -42%)
+- [x] OrderSelectModal 교체 (220→107줄, -51%)
+- [x] organisms/index.ts export 추가
+- [x] CLAUDE.md 공통 컴포넌트 사용 규칙 + claudedocs 가이드 문서 작성
+```
+**실측 효과**: 1,059줄 → 595줄 (464줄 절감, -44%) + 공통 컴포넌트 ~430줄
+
+**남은 작업**:
+```
+- [ ] UniversalListPage 기능 보강
+      - 고급 필터 UI
+      - 컬럼 커스터마이징
+      - 내보내기 기능
+- [ ] 레거시 리스트 페이지 → UniversalListPage 마이그레이션 (우선 20개)
+- [ ] Zod 검증 스키마 라이브러리 구축
+      - lib/validations/common.ts (이메일, 전화, 사업자번호)
+      - lib/validations/vendor.ts, order.ts, item.ts 등
+- [ ] 수동 검증 50+ 폼 → Zod 마이그레이션 (우선 10개)
+```
+
+**예상 효과**: ~5,000줄 절감 (SearchableSelectionModal ~464줄 달성), UX 일관성 +80%
+
+---
+
+### Phase 5: 성능 + 타입 정리 (1-2주) `프론트 단독` `일부 Phase 1에서 선처리`
+
+> React.memo 적용 + any 제거 + 타입 통합
+
+**Phase 1에서 선처리된 항목** (2026-02-09):
+```
+- [x] React.memo 3개 적용 (InfoField, CommentItem, WorkItemCard)
+- [x] any→unknown 7건 (logger.ts)
+- [x] action error handler any 50+곳 (executeServerAction으로 자동 해결)
+- [x] @ts-ignore 0건 (이미 제거 완료)
+```
+
+**남은 작업**:
+```
+- [ ] React.memo 추가 적용 (나머지 리스트 아이템 컴포넌트)
+- [ ] 대형 컴포넌트 useCallback 적용
+- [ ] any 타입 잔여 92건
+      - items/ 도메인 60건 (복잡도 높음, 별도 작업)
+      - Form 에러 캐스팅 26건 (RHF 타입 시스템 변경 필요)
+      - dev/ 프로토타입 6건 (비프로덕션)
+- [ ] 공통 타입 라이브러리 정리
+      - types/shared/ 폴더 생성
+      - PaginatedApiResponse<T> ✅ Phase 3에서 완료 (src/lib/api/types.ts)
+      - FormState<T>, SelectOption 등 추가 타입
+```
+
+**예상 효과**: 리스트 렌더링 30-50% 개선, 타입 안전성 +60%
+
+---
+
+## 전체 예상 효과 요약
+
+| 지표 | Phase 1 ✅ | Phase 2 | Phase 3 ✅ | Phase 4 | Phase 5 | 합계 |
+|------|-----------|---------|---------|---------|---------|------|
+| 코드 절감 | ~3,750줄 (실측) | (구조 개선) | ~256줄 (실측) | ~5,000줄 | (품질 개선) | **~9,000줄+** |
+| 중복 제거 | 82개 action 통일 | - | 25+ 타입 + 4 룩업 통합 | 5 모달 통합 | - | 종합 개선 |
+| 패턴 일관성 | +60% | +50% | +30% (타입 표준화) | +80% | +60% | 종합 개선 |
+| 유지보수성 | 높음 | 매우 높음 | 중간 (공용 유틸) | 중간 | 중간 | 종합 개선 |
+| 위험도 | 낮음 | 중간 | 낮음 (완료) | 낮음 | 낮음 | - |
+
+---
+
+## 병렬 진행 가능 조합
+
+```
+[완료]
+├─ Phase 1 (공통 훅) ──────→ ✅ 완료 (2026-02-09)
+├─ Phase 3 (공용 유틸 추출) ──→ ✅ 완료 (2026-02-10)
+├─ Phase 4 (SearchableSelectionModal) → ✅ 완료 (2026-02-10)
+│
+[즉시 시작 가능]
+├─ Phase 2 (God 컴포넌트 분리) ──→ Phase 1 훅 + Phase 3 공용 타입 활용
+├─ Phase 4 남은 작업 (UniversalListPage 확대, Zod 검증)
+├─ Phase 5 (성능/타입) ─────→ 일부 Phase 1/3에서 선처리됨
+```
+
+---
+
+## 관련 문서
+
+| 문서 | 설명 |
+|------|------|
+| `[PLAN-2026-02-06] multi-tenancy-optimization-roadmap.md` | 멀티테넌시 공통화 로드맵 (별도 트랙) |
+| `[ANALYSIS-2026-01-20] 공통화-현황-분석.md` | 공통화 현황 분석 |
+| `[ANALYSIS-2026-02-05] list-page-commonization-status.md` | 리스트 페이지 공통화 현황 |
+| `[IMPL-2026-02-05] detail-hooks-migration-plan.md` | 상세 페이지 훅 마이그레이션 계획 |
+| `[IMPL-2026-02-05] formatter-commonization-plan.md` | 포매터 공통화 계획 |
+| `[PLAN-2026-01-22] ui-component-abstraction.md` | UI 컴포넌트 추상화 계획 |
+| `guides/[PLAN-2025-12-23] common-component-extraction-plan.md` | 공통 컴포넌트 추출 계획 |
+
+---
+
+## 변경 이력
+
+| 날짜 | 변경 내용 |
+|------|-----------|
+| 2026-02-06 | 초기 작성 - 전체 코드베이스 분석 기반 5 Phase 로드맵 |
+| 2026-02-09 | Phase 1 완료 반영 - 실측 기반 효과 수치 보정 (8,500줄→3,750줄), executeServerAction/useDeleteDialog/useStatsLoader 3개 훅 생성 완료 |
+| 2026-02-09 | Phase 3 프로토타입 검증 완료 - createCrudService 팩토리 생성, RankManagement 5/5 CRUD 정상, Server Action 호환성 확인 |
+| 2026-02-10 | Phase 4 SearchableSelectionModal 완료 - 5개 모달 통합, 464줄 절감(-44%), 가이드 문서 작성 |
+| 2026-02-10 | Phase 3 완료 - 전수 분석 후 팩토리 ROI 재평가(~6%), 공용 유틸 추출로 전략 전환. PaginatedApiResponse 25+파일 타입 통합, 공용 룩업 헬퍼 4파일 중복 제거, ~256줄 절감 |
+
+---
+
+**모든 Phase 프론트 단독 가능** - 백엔드 의존성 없음

claudedocs/architecture/[REF] technical-decisions.md

@@ -0,0 +1,316 @@
+# 프로젝트 기술 결정 사항
+
+> `_index.md`에서 분리됨 (2026-02-23). 프로젝트 전반의 기술 선택 배경과 근거를 기록.
+
+---
+
+### `<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 동적 로드 패턴**:
+```typescript
+// 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는 잘 동작하므로 무리하게 전환하지 않음
+- 커스텀 비즈니스 로직이 있는 도메인(견적, 수주, 생산 등)은 팩토리 비적합
+
+**사용 예시**:
+```typescript
+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개 중 전환 가능 15~20개, 작업 2~4시간 대비 기능 변화 없음. 시간 대비 효율 낮음
+
+### 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 자동 변환)
+
+### KST 안전 날짜 유틸리티 — `toISOString` 사용 금지 (2026-02-19)
+
+**현황**: `new Date().toISOString().split('T')[0]` — 15개 파일 26곳에서 사용 중이었음
+
+**문제**: `toISOString()`은 **UTC 기준**으로 변환. 한국(KST, UTC+9)에서 오전 9시 이전에 실행하면 **전날 날짜** 반환
+```
+// 2026-02-19 08:30 KST → UTC는 2026-02-18 23:30
+new Date().toISOString().split('T')[0]  // "2026-02-18" ← 잘못됨
+```
+
+**결정**: KST 안전 유틸리티 함수로 전량 교체, 직접 `toISOString` 사용 금지
+
+**유틸리티** (`src/lib/utils/date.ts`):
+| 함수 | 용도 | 대체 대상 |
+|------|------|-----------|
+| `getTodayString()` | 오늘 날짜 문자열 | `new Date().toISOString().split('T')[0]` |
+| `getLocalDateString(date)` | 임의 Date 객체 문자열 | `someDate.toISOString().split('T')[0]` |
+
+**사용 규칙**:
+```typescript
+// 올바른 패턴
+import { getTodayString, getLocalDateString } from '@/lib/utils/date';
+const today = getTodayString();                    // "2026-02-19"
+const thirtyDaysAgo = getLocalDateString(pastDate); // "2026-01-20"
+
+// 금지 패턴
+const today = new Date().toISOString().split('T')[0];
+```
+
+**현재 상태**: `src/` 내 `toISOString().split` 사용 0건 (date.ts 내 구현부 제외)
+
+### 달력/스케줄 공통 리소스 — 작업 전 필수 확인 (2026-02-23)
+
+달력·일정·날짜 관련 작업 시 아래 공통 리소스를 **반드시 확인**하고 사용할 것.
+
+**날짜 유틸리티** (`src/lib/utils/date.ts`):
+| 함수 | 용도 |
+|------|------|
+| `getLocalDateString(date)` | Date → `'YYYY-MM-DD'` (KST 안전) |
+| `getTodayString()` | 오늘 날짜 문자열 |
+| `formatDate(dateStr)` | 표시용 날짜 포맷 (null → `'-'`) |
+| `formatDateForInput(dateStr)` | input용 `YYYY-MM-DD` 변환 |
+| `formatDateRange(start, end)` | `'시작 ~ 종료'` 포맷 |
+| `getDateAfterDays(n)` | N일 후 날짜 |
+
+**달력 일정 스토어** (`src/stores/useCalendarScheduleStore.ts`):
+- 달력관리(CalendarManagement)에서 등록한 공휴일/세무일정/회사일정을 프로젝트 전체에 공유
+- `fetchSchedules(year)` — 연도별 캐시 조회 (API 호출)
+- `setSchedulesForYear(year, data)` — 이미 가져온 데이터 직접 설정
+- `invalidateYear(year)` — 캐시 무효화 (등록/수정/삭제 후)
+- **현재 상태**: 백엔드 API 미구현 → 호출부 주석 처리 (TODO 검색)
+
+**달력 이벤트 유틸** (`src/constants/calendarEvents.ts`):
+- `isHoliday(date)`, `isTaxDeadline(date)`, `getHolidayName(date)` 등
+- 스토어 우선 → 하드코딩 폴백(2026년) 패턴
+- 새 연도 폴백 데이터 필요 시 이 파일에 `HOLIDAYS_YYYY`, `TAX_DEADLINES_YYYY` 추가
+
+**ScheduleCalendar 공통 컴포넌트** (`src/components/common/ScheduleCalendar/`):
+- `hideNavigation` prop으로 헤더 숨김 가능 (연간 달력 등 상위 네비게이션 사용 시)
+- `availableViews={[]}` 으로 뷰 전환 버튼 숨김
+
+**규칙**:
+- `Date → string` 변환 시 `getLocalDateString()` 필수 (`toISOString().split('T')[0]` 금지)
+- 공휴일/세무일 판별 시 `calendarEvents.ts` 유틸 함수 사용
+- 달력 데이터 공유 시 zustand 스토어 경유 (컴포넌트 간 직접 전달 금지)
+
+### `useDateRange` 훅 — 날짜 필터 보일러플레이트 제거 (2026-02-19)
+
+**현황**: 20+ 리스트 페이지에서 `useState('2025-01-01')` / `useState('2025-12-31')` 하드코딩
+
+**문제**: 연도가 바뀌면 수동으로 모든 파일 수정 필요 (2025→2026 전환 시 데이터 미표시 버그 발생)
+
+**결정**: `useDateRange` 훅으로 동적 날짜 범위 자동 계산
+
+**훅** (`src/hooks/useDateRange.ts`):
+```typescript
+import { useDateRange } from '@/hooks';
+
+// 프리셋
+const { startDate, endDate, setStartDate, setEndDate } = useDateRange('currentYear');  // 2026-01-01 ~ 2026-12-31
+const { startDate, endDate, setStartDate, setEndDate } = useDateRange('currentMonth'); // 2026-02-01 ~ 2026-02-28
+const { startDate, endDate, setStartDate, setEndDate } = useDateRange('today');        // 2026-02-19 ~ 2026-02-19
+```
+
+**적용 규칙**:
+- 리스트 페이지 날짜 필터 → `useDateRange` 필수 사용
+- 연간 조회 → `'currentYear'`, 월간 조회 → `'currentMonth'`
+- `useState('YYYY-MM-DD')` 하드코딩 금지
+
+**현재 상태**: `useState('2025` 패턴 0건 (전량 `useDateRange`로 전환 완료)
+
+### 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/architecture/[RESEARCH-2026-02-11] ERP-admin-panel-architecture-patterns.md

@@ -0,0 +1,606 @@
+# Research: Next.js / React ERP & Admin Panel Architecture Patterns (2025-2026)
+
+**Date**: 2026-02-11
+**Purpose**: Compare SAM ERP's current architecture against proven open-source patterns
+**Confidence**: High (0.85) - Based on 6 major open-source projects and established methodologies
+
+---
+
+## Executive Summary
+
+After investigating 6 major open-source admin/ERP frameworks and 3 architectural methodologies, the dominant pattern emerging in 2025-2026 is a **hybrid approach**: domain/feature-based folder organization combined with headless CRUD hooks and a provider-based API abstraction layer. Pure Atomic Design is losing ground to Feature-Sliced Design (FSD) for application-level organization, though Atomic Design remains useful for the shared UI component layer.
+
+### Key Findings
+
+1. **Resource-based CRUD abstraction** (react-admin, Refine) is the most proven pattern for 50+ page admin apps
+2. **Feature/domain-based folder structure** is winning over layer-based (atoms/molecules/organisms) for application code
+3. **Provider pattern** (dataProvider, authProvider) decouples UI from API more effectively than scattered Server Actions
+4. **Config-driven UI generation** (Payload CMS) reduces code duplication for similar pages
+5. **Headless hooks** (useListController, useTable, useForm) separate business logic from UI completely
+
+---
+
+## 1. Project-by-Project Architecture Analysis
+
+### 1.1 React-Admin (marmelab) -- 25K+ GitHub Stars
+
+**Architecture**: Resource-based SPA with Provider pattern
+
+**Key Concepts**:
+- **Resources**: The core abstraction. Each entity (posts, users, orders) is a "resource" with CRUD views
+- **Providers**: Adapter layer between UI and backend
+  - `dataProvider` - abstracts all API calls (getList, getOne, create, update, delete)
+  - `authProvider` - handles authentication flow
+  - `i18nProvider` - internationalization
+- **Headless Core**: `ra-core` package contains all hooks, zero UI dependency
+- **Controller Hooks**: `useListController`, `useEditController`, `useCreateController`, `useShowController`
+
+**Folder Pattern**:
+```
+src/
+  resources/
+    posts/
+      PostList.tsx        # <List> view
+      PostEdit.tsx         # <Edit> view
+      PostCreate.tsx       # <Create> view
+      PostShow.tsx         # <Show> view
+    users/
+      UserList.tsx
+      UserEdit.tsx
+  providers/
+    dataProvider.ts        # API abstraction
+    authProvider.ts        # Auth abstraction
+  App.tsx                  # Resource registration
+```
+
+**CRUD Registration Pattern**:
+```tsx
+<Admin dataProvider={dataProvider} authProvider={authProvider}>
+  <Resource name="posts" list={PostList} edit={PostEdit} create={PostCreate} />
+  <Resource name="users" list={UserList} edit={UserEdit} />
+</Admin>
+```
+
+**SAM Comparison**:
+| Aspect | react-admin | SAM ERP |
+|--------|-------------|---------|
+| API Layer | Centralized dataProvider | 89 scattered actions.ts files |
+| CRUD Views | Resource-based registration | Manual page creation per domain |
+| State | React Query (built-in) | Zustand + manual fetching |
+| Form | react-hook-form (built-in) | Mixed (migrating to RHF+Zod) |
+
+**Sources**:
+- [Architecture Docs](https://marmelab.com/react-admin/Architecture.html)
+- [Resource Component](https://marmelab.com/react-admin/Resource.html)
+- [CRUD Pages](https://marmelab.com/react-admin/CRUD.html)
+- [GitHub](https://github.com/marmelab/react-admin)
+
+---
+
+### 1.2 Refine -- 30K+ GitHub Stars
+
+**Architecture**: Headless meta-framework with resource-based CRUD
+
+**Key Concepts**:
+- **Headless by design**: Zero UI opinion, works with Ant Design, Material UI, Shadcn, or custom
+- **Data Provider Interface**: Standardized CRUD methods (getList, getOne, create, update, deleteOne)
+- **Resource Hooks**: `useTable`, `useForm`, `useShow`, `useSelect` -- all headless
+- **Inferencer**: Auto-generates CRUD pages from API schema
+
+**Data Provider Interface**:
+```typescript
+const dataProvider = {
+  getList:    ({ resource, pagination, sorters, filters }) => Promise,
+  getOne:     ({ resource, id }) => Promise,
+  create:     ({ resource, variables }) => Promise,
+  update:     ({ resource, id, variables }) => Promise,
+  deleteOne:  ({ resource, id }) => Promise,
+  getMany:    ({ resource, ids }) => Promise,
+  custom:     ({ url, method, payload }) => Promise,
+};
+```
+
+**Headless Hook Pattern**:
+```tsx
+// useTable returns data + controls, you handle UI
+const { tableProps, sorters, filters } = useTable({ resource: "products" });
+
+// useForm returns form state + submit, you handle UI
+const { formProps, saveButtonProps } = useForm({ resource: "products", action: "create" });
+```
+
+**SAM Comparison**:
+| Aspect | Refine | SAM ERP |
+|--------|--------|---------|
+| API Abstraction | Single dataProvider | Per-domain actions.ts |
+| List Page | useTable hook | UniversalListPage template |
+| Form | useForm hook (headless) | Manual per-page forms |
+| Code Generation | Inferencer auto-gen | Manual creation |
+
+**Sources**:
+- [Data Provider Docs](https://refine.dev/docs/data/data-provider/)
+- [useTable Hook](https://refine.dev/docs/data/hooks/use-table/)
+- [GitHub](https://github.com/refinedev/refine)
+
+---
+
+### 1.3 Payload CMS 3.0 -- 30K+ GitHub Stars
+
+**Architecture**: Config-driven, Next.js-native with auto-generated admin UI
+
+**Key Concepts**:
+- **Collection Config**: Define schema once, get admin UI + API + types automatically
+- **Field System**: Rich field types auto-generate corresponding UI components
+- **Hooks**: beforeChange, afterRead, beforeValidate at collection and field level
+- **Access Control**: Document-level and field-level permissions in config
+- **Next.js Native**: Installs directly into /app folder, uses Server Components
+
+**Config-Driven Pattern**:
+```typescript
+// collections/Products.ts
+export const Products: CollectionConfig = {
+  slug: 'products',
+  admin: {
+    useAsTitle: 'name',
+    defaultColumns: ['name', 'price', 'status'],
+  },
+  access: {
+    read: () => true,
+    create: isAdmin,
+    update: isAdminOrSelf,
+  },
+  hooks: {
+    beforeChange: [calculateTotal],
+    afterRead: [formatCurrency],
+  },
+  fields: [
+    { name: 'name', type: 'text', required: true },
+    { name: 'price', type: 'number', min: 0 },
+    { name: 'status', type: 'select', options: ['draft', 'published'] },
+    { name: 'category', type: 'relationship', relationTo: 'categories' },
+  ],
+};
+```
+
+**SAM Comparison**:
+| Aspect | Payload CMS | SAM ERP |
+|--------|-------------|---------|
+| Page Generation | Auto from config | Manual per page |
+| Field Definitions | Centralized schema | Inline JSX per form |
+| Access Control | Config-based per field | Manual per component |
+| Type Safety | Auto-generated from schema | Manual interface definitions |
+
+**Sources**:
+- [Collection Configs](https://payloadcms.com/docs/configuration/collections)
+- [Fields Overview](https://payloadcms.com/docs/fields/overview)
+- [Collection Hooks](https://payloadcms.com/docs/hooks/collections)
+- [GitHub](https://github.com/payloadcms/payload)
+
+---
+
+### 1.4 Medusa Admin v2 -- 26K+ GitHub Stars
+
+**Architecture**: Domain-based routes with widget injection system
+
+**Key Concepts**:
+- **Domain Routes**: Routes organized by business domain (products, orders, customers)
+- **Widget System**: Inject custom React components into predetermined zones
+- **UI Routes**: File-based routing under src/admin/routes/
+- **Hook-based data fetching**: Domain-specific hooks for API integration
+- **Monorepo**: UI library (@medusajs/ui) separate from admin logic
+
+**Folder Structure**:
+```
+packages/admin/dashboard/src/
+  routes/
+    products/
+      product-list/
+        components/
+        hooks/
+        page.tsx
+      product-detail/
+        components/
+        hooks/
+        page.tsx
+    orders/
+      order-list/
+      order-detail/
+    customers/
+  hooks/              # Shared hooks
+  components/         # Shared components
+  lib/                # Utilities
+```
+
+**SAM Comparison**:
+| Aspect | Medusa Admin | SAM ERP |
+|--------|-------------|---------|
+| Route Organization | Domain > Action > Components | Domain > page.tsx + actions.ts |
+| Shared Components | Separate UI package | organisms/molecules/atoms |
+| Hooks | Per-route + shared | Global + inline |
+| Extensibility | Widget injection zones | N/A |
+
+**Sources**:
+- [Admin UI Routes](https://docs.medusajs.com/learn/fundamentals/admin/ui-routes)
+- [Admin Development](https://docs.medusajs.com/learn/fundamentals/admin)
+- [GitHub](https://github.com/medusajs/medusa)
+
+---
+
+### 1.5 AdminJS
+
+**Architecture**: Auto-generated admin from resource configuration
+
+**Key Concepts**:
+- **Resource Registration**: Register database models, get admin UI automatically
+- **Component Customization**: Override via ComponentLoader
+- **Dashboard Customization**: Custom React components for dashboard
+
+**SAM Relevance**: Lower -- AdminJS is more backend-driven (Node.js ORM-based) and less applicable to a frontend-heavy ERP.
+
+**Sources**:
+- [AdminJS Documentation](https://adminjs.co/)
+- [GitHub](https://github.com/SoftwareBrothers/adminjs)
+
+---
+
+### 1.6 Hoppscotch
+
+**Architecture**: Monorepo with shared-library pattern
+
+**Key Concepts**:
+- **@hoppscotch/common**: 90% of UI and business logic in shared package
+- **@hoppscotch/data**: Type safety across all layers
+- **Platform-specific code**: Thin wrapper handling native capabilities
+
+**SAM Relevance**: The shared-library-as-core pattern is interesting for large codebases where most logic is platform-agnostic.
+
+**Sources**:
+- [DeepWiki Analysis](https://deepwiki.com/hoppscotch/hoppscotch)
+
+---
+
+## 2. Architectural Methodologies Comparison
+
+### 2.1 Feature-Sliced Design (FSD) -- Rising Standard
+
+**7-Layer Architecture**:
+```
+app/        # App initialization, providers, routing
+processes/  # Complex cross-page business flows (deprecated in latest)
+pages/      # Full page compositions
+widgets/    # Self-contained UI blocks with business logic
+features/   # User-facing actions (login, add-to-cart)
+entities/   # Business entities (user, product, order)
+shared/     # Reusable utilities, UI kit, configs
+```
+
+**Key Rules**:
+- Layers can ONLY import from layers below them
+- Each layer divided into **slices** (domain groupings)
+- Each slice divided into **segments** (ui/, model/, api/, lib/, config/)
+
+**FSD Applied to ERP**:
+```
+src/
+  app/                          # App shell, providers
+  pages/
+    quality-qms/                # QMS page composition
+    sales-quote/                # Quote page composition
+  widgets/
+    inspection-report/          # Self-contained inspection UI
+      ui/
+      model/
+      api/
+    quote-calculator/
+  features/
+    add-inspection-item/
+    approve-quote/
+  entities/
+    inspection/
+      ui/    (InspectionCard, InspectionRow)
+      model/ (types, store)
+      api/   (getInspection, updateInspection)
+    quote/
+      ui/
+      model/
+      api/
+  shared/
+    ui/     (Button, Table, Modal -- your atoms)
+    lib/    (formatDate, exportUtils)
+    api/    (httpClient, apiProxy)
+    config/ (constants)
+```
+
+**Sources**:
+- [Feature-Sliced Design](https://feature-sliced.design/)
+- [Layers Reference](https://feature-sliced.design/docs/reference/layers)
+- [Slices and Segments](https://feature-sliced.design/docs/reference/slices-segments)
+
+---
+
+### 2.2 Atomic Design -- Aging for App-Level Organization
+
+**SAM's Current Approach**:
+```
+components/
+  atoms/       # Basic UI elements
+  molecules/   # (unused)
+  organisms/   # Complex composed components
+  templates/   # Page layout templates
+```
+
+**Industry Assessment (2025-2026)**:
+- Atomic Design excels for **UI component libraries** (shared/ layer)
+- Struggles with **domain complexity** -- "UserCard" and "ProductCard" are both organisms but semantically distinct
+- Grouping by visual complexity (atom/molecule/organism) dilutes domain boundaries
+- Most large-scale projects have moved to **feature/domain organization** for application code
+- Atomic Design remains valuable for the **shared UI kit layer only**
+
+**Sources**:
+- [Atomic Design Meets Feature-Based Architecture](https://medium.com/@buwanekasumanasekara/atomic-design-meets-feature-based-architecture-in-next-js-a-practical-guide-c06ea56cf5cc)
+- [From Components to Systems](https://www.codewithseb.com/blog/from-components-to-systems-scalable-frontend-with-atomiec-design)
+
+---
+
+### 2.3 Modular Monolith (Frontend)
+
+**Key Principles for ERP**:
+- Single deployment, but internally organized as independent modules
+- Each module = bounded context with clear API boundaries
+- Modules communicate through well-defined interfaces, not direct imports
+- Common concerns (auth, logging) handled at application level
+
+**Applied to Next.js ERP**:
+```
+src/
+  modules/
+    quality/
+      components/
+      hooks/
+      actions/
+      types/
+      index.ts          # Public API -- only exports from here
+    sales/
+      components/
+      hooks/
+      actions/
+      types/
+      index.ts
+    accounting/
+      ...
+  shared/               # Cross-module utilities
+  app/                  # Next.js routing (thin layer)
+```
+
+**Sources**:
+- [Modular Monolith Revolution](https://medium.com/@bhargavkoya56/the-modular-monolith-revolution-enterprise-grade-architecture-part-i-theory-b3705ca70a5f)
+- [Frontend at Scale](https://frontendatscale.com/issues/45/)
+
+---
+
+## 3. Server Actions Organization Patterns
+
+### Pattern A: Colocated (SAM's Current -- 89 files)
+```
+app/[locale]/(protected)/quality/qms/
+  page.tsx
+  actions.ts        # Server actions for this route
+```
+**Pros**: Easy to find, clear ownership
+**Cons**: Duplication across similar pages, no reuse
+
+### Pattern B: Domain-Centralized (react-admin / Refine style)
+```
+src/
+  actions/
+    quality/
+      inspection.ts     # All inspection-related server actions
+      qms.ts
+    sales/
+      quote.ts
+      order.ts
+  lib/
+    api-client.ts       # Shared fetch logic with auth
+```
+**Pros**: Reusable across pages, easier to maintain
+**Cons**: Indirection, harder to find for route-specific logic
+
+### Pattern C: Hybrid (Recommended for large apps)
+```
+app/[locale]/(protected)/quality/qms/
+  page.tsx
+  _actions.ts          # Route-specific actions only
+
+src/
+  domains/
+    quality/
+      actions/          # Shared domain actions
+        inspection.ts
+        qms.ts
+      hooks/
+      types/
+```
+**Pros**: Route-specific stays colocated, shared logic centralized
+**Cons**: Need clear rules on what goes where
+
+### Industry Consensus
+For 100+ page apps, the **hybrid approach** (Pattern C) dominates. Route-specific logic stays colocated; shared domain logic is centralized. The key is having a clear **data provider / API client** layer that all server actions delegate to.
+
+**Sources**:
+- [Next.js Colocation Template](https://next-colocation-template.vercel.app/)
+- [Inside the App Router (2025)](https://medium.com/better-dev-nextjs-react/inside-the-app-router-best-practices-for-next-js-file-and-directory-structure-2025-edition-ed6bc14a8da3)
+
+---
+
+## 4. CRUD Abstraction Patterns for 50+ Similar Pages
+
+### Pattern 1: Resource Hooks (react-admin / Refine approach)
+```typescript
+// hooks/useResourceList.ts
+function useResourceList<T>(resource: string, options?: ListOptions) {
+  const [data, setData] = useState<T[]>([]);
+  const [pagination, setPagination] = useState({ page: 1, pageSize: 20 });
+  const [filters, setFilters] = useState({});
+  const [sorters, setSorters] = useState({});
+
+  useEffect(() => {
+    fetchList(resource, { pagination, filters, sorters })
+      .then(result => setData(result.data));
+  }, [resource, pagination, filters, sorters]);
+
+  return { data, pagination, setPagination, filters, setFilters, sorters, setSorters };
+}
+
+// Usage in any list page
+function QualityInspectionList() {
+  const { data, pagination, filters } = useResourceList<Inspection>('quality/inspections');
+  return <UniversalListPage data={data} columns={inspectionColumns} />;
+}
+```
+
+### Pattern 2: Config-Driven Pages (Payload CMS approach)
+```typescript
+// configs/quality-inspection.config.ts
+export const inspectionConfig: ResourceConfig = {
+  resource: 'quality/inspections',
+  list: {
+    columns: [
+      { key: 'id', label: '번호' },
+      { key: 'name', label: '검사명' },
+      { key: 'status', label: '상태', render: StatusBadge },
+    ],
+    filters: [
+      { key: 'status', type: 'select', options: statusOptions },
+      { key: 'dateRange', type: 'daterange' },
+    ],
+    defaultSort: { key: 'createdAt', direction: 'desc' },
+  },
+  form: {
+    fields: [
+      { name: 'name', type: 'text', required: true, label: '검사명' },
+      { name: 'type', type: 'select', options: typeOptions, label: '검사유형' },
+    ],
+  },
+};
+
+// Generic page component
+function ResourceListPage({ config }: { config: ResourceConfig }) {
+  const list = useResourceList(config.resource);
+  return <UniversalListPage {...list} columns={config.list.columns} />;
+}
+```
+
+### Pattern 3: Template Composition (SAM's current direction, improved)
+```typescript
+// templates/UniversalCRUDPage.tsx -- enhanced version
+function UniversalCRUDPage<T>({
+  resource,
+  listConfig,
+  detailConfig,
+  formConfig,
+}: CRUDPageProps<T>) {
+  // Handles list/detail/form modes based on URL
+  // Integrates data fetching, pagination, filtering
+  // Renders appropriate template based on mode
+}
+```
+
+### Industry Assessment
+- **Pattern 1** (Resource Hooks) is the most widely adopted -- used by react-admin (25K stars) and Refine (30K stars)
+- **Pattern 2** (Config-Driven) reduces code the most but requires upfront investment in the config system
+- **Pattern 3** (Template Composition) is the middle ground -- SAM's `UniversalListPage` is already this direction
+
+**Recommendation**: Evolve toward a **Provider + Resource Hooks** layer. Keep `UniversalListPage` and `IntegratedDetailTemplate` but back them with a standardized data provider.
+
+---
+
+## 5. Comparison Matrix: SAM ERP vs Industry Patterns
+
+| Dimension | SAM ERP (Current) | react-admin | Refine | Payload CMS | FSD | Recommendation |
+|-----------|-------------------|-------------|--------|-------------|-----|----------------|
+| **Folder Structure** | Domain-based (app router) | Resource-based | Resource-based | Collection-based | Layer > Slice > Segment | Hybrid Domain + FSD shared layer |
+| **Component Org** | Atomic Design (partial) | Flat per resource | Flat per resource | Config-driven | Layer-based (entities/features) | FSD for app code, Atomic for shared UI |
+| **API Layer** | 89 colocated actions.ts | Centralized dataProvider | Centralized dataProvider | Built-in Local API | api/ segment per slice | Centralized API client + domain actions |
+| **CRUD Abstraction** | UniversalListPage template | Resource + Controller hooks | useTable/useForm hooks | Auto-generated from config | Manual per feature | Add resource hooks on top of templates |
+| **Form Handling** | Mixed (migrating to RHF+Zod) | react-hook-form (built-in) | react-hook-form (headless) | Auto from field config | Manual per feature | Complete RHF+Zod migration |
+| **State Management** | Zustand stores | React Query (built-in) | React Query (built-in) | Server-side | Per-slice model/ | Keep Zustand for UI state, add React Query for server state |
+| **Type Safety** | Manual interfaces | Built-in types | TypeScript throughout | Auto-generated from schema | Manual per segment | Consider schema-driven type generation |
+| **50+ Page Scale** | Manual duplication | Resource registration | Inferencer + hooks | Collection config | Slice per entity | Resource hooks + config-driven columns |
+
+---
+
+## 6. Actionable Recommendations for SAM ERP
+
+### Priority 1: Introduce a Data Provider / API Client Layer
+**Why**: The biggest gap vs. industry standard. 89 scattered actions.ts files means duplicated fetch logic, inconsistent error handling, and no centralized caching.
+
+**Action**: Create a `dataProvider` abstraction inspired by react-admin/Refine:
+```typescript
+// src/lib/data-provider.ts
+export const dataProvider = {
+  getList: (resource, params) => proxyFetch(`/api/proxy/${resource}`, params),
+  getOne: (resource, id) => proxyFetch(`/api/proxy/${resource}/${id}`),
+  create: (resource, data) => proxyFetch(`/api/proxy/${resource}`, { method: 'POST', body: data }),
+  update: (resource, id, data) => proxyFetch(`/api/proxy/${resource}/${id}`, { method: 'PUT', body: data }),
+  delete: (resource, id) => proxyFetch(`/api/proxy/${resource}/${id}`, { method: 'DELETE' }),
+};
+```
+
+### Priority 2: Create Resource Hooks
+**Why**: Reduce per-page boilerplate for list/detail/form patterns.
+
+**Action**: Build `useResourceList`, `useResourceDetail`, `useResourceForm` hooks that wrap the data provider.
+
+### Priority 3: Evolve Folder Structure Toward Hybrid FSD
+**Why**: Atomic Design for app-level code leads to unclear domain boundaries.
+
+**Action**:
+- Keep `shared/ui/` (atoms/organisms) for reusable UI components
+- Add `domains/` or `entities/` for business-logic grouping
+- Keep `app/` routes thin -- delegate to domain components
+
+### Priority 4: Complete Form Standardization
+**Why**: Mixed form patterns make maintenance harder and prevent reusable form configs.
+
+**Action**: Complete the react-hook-form + Zod migration. Consider field-config-driven forms (Payload pattern) for highly repetitive forms.
+
+### Priority 5: Consider Server State Management (React Query / TanStack Query)
+**Why**: react-admin and Refine both use React Query internally for caching, optimistic updates, and background refetching. Zustand is better suited for client UI state.
+
+**Action**: Evaluate adding TanStack Query for server state alongside Zustand for UI state.
+
+---
+
+## 7. What SAM ERP Is Already Doing Well
+
+1. **Domain-based routing** (`app/[locale]/(protected)/quality/...`) aligns with industry best practice
+2. **UniversalListPage + IntegratedDetailTemplate** is the right abstraction direction (similar to react-admin's List/Edit components)
+3. **SearchableSelectionModal** as a reusable pattern is good (similar to react-admin's ReferenceInput)
+4. **Server Actions in colocated files** follows Next.js official recommendation for route-specific logic
+5. **Zustand for global state** is a solid choice for UI state (sidebar state, theme, etc.)
+
+---
+
+## Sources
+
+### Open-Source Projects
+- [react-admin - Architecture](https://marmelab.com/react-admin/Architecture.html)
+- [react-admin - GitHub](https://github.com/marmelab/react-admin)
+- [Refine - Data Provider](https://refine.dev/docs/data/data-provider/)
+- [Refine - GitHub](https://github.com/refinedev/refine)
+- [Payload CMS - Collections](https://payloadcms.com/docs/configuration/collections)
+- [Payload CMS - GitHub](https://github.com/payloadcms/payload)
+- [Medusa - Admin Development](https://docs.medusajs.com/learn/fundamentals/admin)
+- [Medusa - GitHub](https://github.com/medusajs/medusa)
+
+### Architectural Methodologies
+- [Feature-Sliced Design](https://feature-sliced.design/)
+- [FSD - Layers Reference](https://feature-sliced.design/docs/reference/layers)
+- [Atomic Design + FSD Hybrid](https://medium.com/@buwanekasumanasekara/atomic-design-meets-feature-based-architecture-in-next-js-a-practical-guide-c06ea56cf5cc)
+- [Clean Architecture vs FSD in Next.js](https://medium.com/@metastability/clean-architecture-vs-feature-sliced-design-in-next-js-applications-04df25e62690)
+
+### Folder Structure & Patterns
+- [Next.js App Router Best Practices (2025)](https://medium.com/better-dev-nextjs-react/inside-the-app-router-best-practices-for-next-js-file-and-directory-structure-2025-edition-ed6bc14a8da3)
+- [Scalable Next.js Folder Structure](https://techtales.vercel.app/read/thedon/building-a-scalable-folder-structure-for-large-next-js-projects)
+- [SaaS Architecture Patterns with Next.js](https://vladimirsiedykh.com/blog/saas-architecture-patterns-nextjs)
+- [Modular Monolith for Frontend](https://frontendatscale.com/issues/45/)

claudedocs/architecture/[VISION-2026-02-19] dynamic-rendering-platform-strategy.md

@@ -0,0 +1,224 @@
+# 동적 렌더링 플랫폼 전략 — 기준관리 기반 화면 자동 구성
+
+> 작성일: 2026-02-19
+> 상태: 비전 정리 (논의 기반)
+> 관련 기술 설계: `[DESIGN-2026-02-11] dynamic-field-type-extension.md`
+> 관련 구현 현황: `[IMPL-2026-02-11] dynamic-field-components.md`
+> 관련 로드맵: `item-master/[DESIGN-2025-12-12] item-master-form-builder-roadmap.md`
+
+---
+
+## 1. 핵심 비전
+
+```
+기준관리 페이지에서 설정 → API로 메타데이터 전달 → 프론트가 자동 렌더링
+```
+
+**목표**: 개발자가 매번 화면을 코딩하는 것이 아니라, 기준관리 페이지에서 등록한 설정값에 따라 프론트엔드가 동적으로 화면을 구성하는 **ERP 커스터마이징 플랫폼**.
+
+---
+
+## 2. 운영 워크플로우 비전
+
+### 2.1 전체 흐름
+
+```
+현장 방문 (영업자/매니저)
+  ├─ 녹음, 체크리스트, 문서 수집
+  └─ → MD 파일 정리 (요구사항)
+        │
+        ↓
+기준관리 페이지 (관리자/컨설턴트)
+  ├─ MD 보고 속성, 칼럼, 옵션 등록
+  └─ → 메타데이터 저장 (DB)
+        │
+        ↓ API
+        │
+프론트엔드 (자동 렌더링)
+  └─ 메타데이터 기반으로 동적 화면 구성
+```
+
+### 2.2 역할 변화
+
+| 역할 | 현재 | 비전 |
+|------|------|------|
+| 영업자/매니저 | 요구사항 전달 → 개발 대기 | 현장에서 MD 파일 작성 |
+| 관리자/컨설턴트 | — | MD 보고 기준관리에 설정 입력 |
+| **개발자** | **요구사항마다 화면 코딩** | **플랫폼 유지보수 + 새 블록 타입 추가 시에만 개입** |
+
+### 2.3 개발자 개입이 필요한 시점
+
+- 기존 블록(Input, Select, DatePicker 등)으로 조합 가능 → **개발자 불필요**
+- 새로운 입력 타입/계산 로직 필요 → **블록 1개 추가** → 이후 재사용
+- 기준관리 UI 자체 개선 → **설계/검증**
+- page-builder 고도화 → **설계/구현**
+
+---
+
+## 3. 현재 자산 현황
+
+### 3.1 이미 있는 것
+
+#### UI 블록 (공통 컴포넌트)
+```
+src/components/ui/
+  ├─ Input, NumberInput, QuantityInput, CurrencyInput
+  ├─ Select, Checkbox, DatePicker, Textarea
+  ├─ Button, Badge, Card, Dialog
+  └─ ...
+```
+모든 도메인별 테이블이 이 공통 블록을 사용 중.
+
+#### 동적 필드 시스템 (14종 완성)
+```
+DynamicItemForm/fields/
+  ├─ 기존 6종: textbox, number, dropdown, checkbox, date, textarea
+  └─ 신규 8종: reference, multi-select, file, currency, unit-value, radio, toggle, computed
+```
+Phase 1~3 프론트 구현 완료 (백엔드 작업 대기).
+
+#### 범용 테이블 섹션
+```
+DynamicTableSection — config 기반 칼럼 정의, 행 CRUD, 요약행
+TableCellRenderer — 테이블 셀 = DynamicFieldRenderer 재사용
+```
+
+#### 속성 관리 시스템 (품목기준관리)
+```
+useAttributeManagement — 속성 옵션 상태 관리
+AttributeTabContent — 동적 탭 렌더링
+OptionColumn[] + MasterOption[] — 메타데이터 구조
+```
+
+#### page-builder 프로토타입
+```
+/dev/page-builder — 드래그앤드롭, 섹션/필드 구성, Undo/Redo, 반응형 뷰포트
+```
+
+### 3.2 현재 구조: "기준관리 → 동적 렌더링" 패턴
+
+```
+품목기준관리 (Admin)                    품목 등록 (User)
+ItemMasterDataManagement.tsx           DynamicItemForm/index.tsx
+  ↓ 설정 (pages/sections/fields)        ↓ 읽어서 렌더링
+  DB에 메타데이터 저장                    DynamicFieldRenderer (14종 switch)
+                                        DynamicTableSection (config 기반)
+```
+
+**이 패턴이 핵심이고, 다른 도메인에도 동일하게 확장하는 것이 비전.**
+
+---
+
+## 4. 확장 대상 분석
+
+### 4.1 도메인별 동적 렌더링 적합성
+
+| 도메인 | 적합도 | 이유 |
+|--------|:---:|------|
+| 품목기준관리 | ✅ 이미 적용 | 테넌트/업종별 관리 항목이 다름 |
+| 설비/자산 관리 | ✅ 높음 | 설비 종류별 관리 속성이 다름 |
+| 거래처 관리 | ✅ 높음 | 업종별 추가 정보 다름 |
+| 공정/라우팅 관리 | ✅ 높음 | 제조 방식별 공정 구성 다름 |
+| 검사 항목 관리 | ✅ 높음 | 품목별 검사 항목/기준 다름 |
+| 견적서/발주서 | 🟡 부분 | 테이블은 동적 가능, 비즈니스 로직은 고정 |
+| 세금계산서 | ❌ 낮음 | 법정 양식, 테넌트별 차이 없음 |
+| 대시보드 | ❌ 낮음 | 위젯 기반이 더 적합 |
+
+### 4.2 편집 가능 테이블 현황
+
+| 컴포넌트 | 공통 컴포넌트 사용 | 자동 계산 | 합계 행 |
+|---------|:---:|:---:|:---:|
+| EditableTable (공통) | 본인이 공통 | ❌ | ❌ |
+| TaxInvoiceItemTable | ❌ 개별 | ✅ | ✅ |
+| OrderDetailItemTable | ❌ 개별 | ❌ | ✅ |
+| EstimateDetailTableSection | ❌ 개별 | ✅ (복잡) | ✅ |
+| DynamicTableSection | ❌ 개별 (config 기반) | ✅ (요약) | ✅ |
+
+**테이블 안의 부품(Input, Select 등)은 전부 공통 ui 컴포넌트 사용.**
+껍데기(테이블 구조, 계산 로직)만 각자 구현.
+
+---
+
+## 5. page-builder 갭 분석
+
+### 5.1 현재 page-builder 상태
+
+```
+/dev/page-builder (프로토타입)
+  ✅ 드래그앤드롭 (섹션/필드 → 캔버스)
+  ✅ 섹션 타입 (BASIC, BOM, CUSTOM)
+  ✅ 필드 타입 (기본 6종)
+  ✅ 조건부 표시 (DisplayCondition)
+  ✅ 검증 규칙 (ValidationRule)
+  ✅ BOM 테이블
+  ✅ 마스터 필드 연동
+  ✅ Undo/Redo 히스토리
+  ✅ 반응형 뷰포트 (desktop/tablet/mobile)
+  ✅ API 변환 타입 정의
+```
+
+### 5.2 비전 대비 부족한 점
+
+| 항목 | 현재 | 필요 |
+|------|------|------|
+| 대상 도메인 | 품목 전용 (ItemType: FG/PT/SM/RM/CS) | 모든 기준관리 |
+| 사용자 | 개발자용 프로토타입 | 비개발자(영업/매니저/관리자) |
+| 테이블 섹션 | BOM만 (고정 칼럼) | 동적 칼럼 + 행 CRUD (DynamicTableSection 연결) |
+| 신규 필드 타입 | 기본 6종만 | 14종 전체 반영 |
+| API 연동 | 타입만 정의 | 실제 저장/조회 |
+| 프리셋 | 하드코딩 | 산업별 섹션 프리셋 선택 |
+
+### 5.3 고도화 방향
+
+```
+1단계: 도메인 범용화
+  - ItemType 종속 제거
+  - "기준관리 도메인" 선택 → 해당 도메인의 페이지 구성
+
+2단계: 14종 필드 타입 반영
+  - ComponentPalette에 신규 8종 필드 추가
+  - PropertyPanel에 각 필드별 config 편집 UI
+
+3단계: DynamicTableSection 연결
+  - BOM 외 범용 테이블 섹션 지원
+  - 칼럼 정의 UI (타입/너비/필수 설정)
+
+4단계: 비개발자 UX
+  - 용어 단순화 (field_type → "입력 형태")
+  - 미리보기 강화
+  - 저장/불러오기
+```
+
+---
+
+## 6. 4-Level 아키텍처 요약
+
+기존 기술 설계서(`[DESIGN-2026-02-11]`)의 핵심:
+
+```
+Level 1: 필드 타입 컴포넌트 (14종) — 코드 레벨, 거의 안 바뀜
+Level 2: properties config (JSON) — 설정 레벨, 코드 변경 없음
+Level 3: 섹션 프리셋 (JSON) — 템플릿 레벨, 코드 변경 없음
+Level 4: reference sources (API URL) — 연결 레벨, 코드 변경 없음
+```
+
+**새 산업 진출 시에도 프론트엔드 코드 변경 = 0줄.**
+백엔드 API + config JSON만 추가.
+
+---
+
+## 7. 관련 문서
+
+| 문서 | 위치 | 내용 |
+|------|------|------|
+| 동적 필드 타입 확장 설계 | `architecture/[DESIGN-2026-02-11]` | 4-Level 구조, 14종 필드, 범용 테이블, 산업별 확장 |
+| 동적 필드 컴포넌트 구현 | `architecture/[IMPL-2026-02-11]` | Phase 1~3 프론트 구현 완료 상태 |
+| Form Builder 로드맵 | `item-master/[DESIGN-2025-12-12]` | Low-Code Form Builder 초기 로드맵 |
+| 백엔드 API 스펙 | `item-master/[API-REQUEST-2026-02-12]` | 동적 필드 타입 백엔드 API 요청서 |
+| page-builder 참조 | `dev/[REF] page-builder-implementation.md` | 페이지 빌더 구현 참조 |
+| 멀티테넌시 최적화 | `architecture/[PLAN-2026-02-06] multi-tenancy-optimization-roadmap.md` | 테넌트별 격리/최적화 |
+
+---
+
+**문서 버전**: 1.0
+**마지막 업데이트**: 2026-02-19

claudedocs/components/_registry.md

@@ -0,0 +1,691 @@
+# Component Registry
+
+> Auto-generated: 2026-02-12T01:56:50.520Z  
+> Total: **501** components
+
+## UI (53)
+
+### ui (53)
+
+| Component | File | Export | Props | Client | Lines |
+|-----------|------|--------|-------|--------|-------|
+| Accordion | accordion.tsx | none |  | Y | 66 |
+| AccountNumberInput | account-number-input.tsx | none | AccountNumberInputProps | Y | 95 |
+| Alert | alert.tsx | none | VariantProps |  | 59 |
+| AlertDialog | alert-dialog.tsx | none |  | Y | 158 |
+| Badge | badge.tsx | none | VariantProps |  | 47 |
+| BusinessNumberInput | business-number-input.tsx | none | BusinessNumberInputProps | Y | 114 |
+| Button | button.tsx | none | VariantProps |  | 62 |
+| Calendar | calendar.tsx | none |  | Y | 138 |
+| Card | card.tsx | none |  |  | 93 |
+| CardNumberInput | card-number-input.tsx | none | CardNumberInputProps | Y | 95 |
+| ChartWrapper | chart-wrapper.tsx | named | ChartWrapperProps |  | 66 |
+| Checkbox | checkbox.tsx | none |  | Y | 33 |
+| Collapsible | collapsible.tsx | none |  | Y | 33 |
+| Command | command.tsx | none |  | Y | 177 |
+| ConfirmDialog | confirm-dialog.tsx | both | ConfirmDialogProps | Y | 226 |
+| CurrencyInput | currency-input.tsx | none | CurrencyInputProps | Y | 220 |
+| DatePicker | date-picker.tsx | none | DatePickerProps | Y | 279 |
+| Dialog | dialog.tsx | none |  | Y | 137 |
+| Drawer | drawer.tsx | none |  | Y | 133 |
+| DropdownMenu | dropdown-menu.tsx | none |  | Y | 258 |
+| EmptyState | empty-state.tsx | both | ButtonProps | Y | 227 |
+| ErrorCard | error-card.tsx | named | ErrorCardProps | Y | 196 |
+| ErrorMessage | error-message.tsx | named | ErrorMessageProps |  | 38 |
+| FileDropzone | file-dropzone.tsx | both | FileDropzoneProps | Y | 227 |
+| FileInput | file-input.tsx | both | FileInputProps | Y | 226 |
+| FileList | file-list.tsx | both | FileListProps | Y | 276 |
+| ImageUpload | image-upload.tsx | both | ImageUploadProps | Y | 309 |
+| Input | input.tsx | none |  |  | 22 |
+| Label | label.tsx | none |  | Y | 25 |
+| LoadingSpinner | loading-spinner.tsx | named | LoadingSpinnerProps |  | 114 |
+| MultiSelectCombobox | multi-select-combobox.tsx | named | MultiSelectComboboxProps | Y | 128 |
+| NumberInput | number-input.tsx | none | NumberInputProps | Y | 280 |
+| PersonalNumberInput | personal-number-input.tsx | none | PersonalNumberInputProps | Y | 101 |
+| PhoneInput | phone-input.tsx | none | PhoneInputProps | Y | 95 |
+| Popover | popover.tsx | none |  | Y | 53 |
+| Progress | progress.tsx | none |  | Y | 32 |
+| QuantityInput | quantity-input.tsx | none | QuantityInputProps | Y | 271 |
+| RadioGroup | radio-group.tsx | none |  | Y | 46 |
+| ScrollArea | scroll-area.tsx | none |  | Y | 53 |
+| SearchableSelect | searchable-select.tsx | named | SearchableSelectProps | Y | 219 |
+| Select | select.tsx | none |  | Y | 192 |
+| Separator | separator.tsx | none | SeparatorProps | Y | 32 |
+| Sheet | sheet.tsx | none |  | Y | 146 |
+| Skeleton | skeleton.tsx | none | SkeletonProps | Y | 679 |
+| Slider | slider.tsx | none |  |  | 26 |
+| StatusBadge | status-badge.tsx | both | StatusBadgeProps | Y | 123 |
+| Switch | switch.tsx | none |  | Y | 32 |
+| Table | table.tsx | none |  |  | 117 |
+| Tabs | tabs.tsx | none |  | Y | 66 |
+| Textarea | textarea.tsx | none |  |  | 25 |
+| TimePicker | time-picker.tsx | none | TimePickerProps | Y | 191 |
+| Tooltip | tooltip.tsx | none |  | Y | 48 |
+| VisuallyHidden | visually-hidden.tsx | none |  | Y | 14 |
+
+## ATOMS (3)
+
+### atoms (3)
+
+| Component | File | Export | Props | Client | Lines |
+|-----------|------|--------|-------|--------|-------|
+| BadgeSm | BadgeSm.tsx | named | BadgeSmProps | Y | 117 |
+| ScrollableButtonGroup | ScrollableButtonGroup.tsx | named | ScrollableButtonGroupProps |  | 53 |
+| TabChip | TabChip.tsx | named | TabChipProps | Y | 72 |
+
+## MOLECULES (8)
+
+### molecules (8)
+
+| Component | File | Export | Props | Client | Lines |
+|-----------|------|--------|-------|--------|-------|
+| DateRangeSelector | DateRangeSelector.tsx | named | DateRangeSelectorProps | Y | 217 |
+| FormField | FormField.tsx | named | FormFieldProps |  | 296 |
+| IconWithBadge | IconWithBadge.tsx | named | IconWithBadgeProps | Y | 51 |
+| MobileFilter | MobileFilter.tsx | named | MobileFilterProps | Y | 335 |
+| StandardDialog | StandardDialog.tsx | named | StandardDialogProps | Y | 219 |
+| StatusBadge | StatusBadge.tsx | named | StatusBadgeProps | Y | 111 |
+| TableActions | TableActions.tsx | named | TableActionsProps | Y | 89 |
+| YearQuarterFilter | YearQuarterFilter.tsx | named | YearQuarterFilterProps | Y | 98 |
+
+## ORGANISMS (12)
+
+### organisms (12)
+
+| Component | File | Export | Props | Client | Lines |
+|-----------|------|--------|-------|--------|-------|
+| DataTable | DataTable.tsx | named | DataTableProps | Y | 363 |
+| EmptyState | EmptyState.tsx | named | EmptyStateProps | Y | 38 |
+| FormActions | FormActions.tsx | named | FormActionsProps |  | 74 |
+| FormFieldGrid | FormFieldGrid.tsx | named | FormFieldGridProps |  | 35 |
+| FormSection | FormSection.tsx | named | FormSectionProps |  | 62 |
+| MobileCard | MobileCard.tsx | named | InfoFieldProps | Y | 347 |
+| PageHeader | PageHeader.tsx | named | PageHeaderProps | Y | 42 |
+| PageLayout | PageLayout.tsx | named | PageLayoutProps | Y | 32 |
+| ScreenVersionHistory | ScreenVersionHistory.tsx | named | ScreenVersionHistoryProps | Y | 75 |
+| SearchableSelectionModal | SearchableSelectionModal.tsx | named |  | Y | 253 |
+| SearchFilter | SearchFilter.tsx | named | SearchFilterProps | Y | 58 |
+| StatCards | StatCards.tsx | named | StatCardsProps | Y | 67 |
+
+## COMMON (16)
+
+### common (16)
+
+| Component | File | Export | Props | Client | Lines |
+|-----------|------|--------|-------|--------|-------|
+| AccessDenied | AccessDenied.tsx | named | AccessDeniedProps | Y | 68 |
+| CalendarHeader | CalendarHeader.tsx | named |  | Y | 148 |
+| DayCell | DayCell.tsx | named | DayCellProps | Y | 93 |
+| DayTimeView | DayTimeView.tsx | named |  | Y | 167 |
+| EditableTable | EditableTable.tsx | both | EditableTableProps | Y | 333 |
+| EmptyPage | EmptyPage.tsx | named | EmptyPageProps | Y | 150 |
+| MonthView | MonthView.tsx | named | WeekRowProps | Y | 264 |
+| MorePopover | MorePopover.tsx | named | MorePopoverProps | Y | 45 |
+| NoticePopupModal | NoticePopupModal.tsx | named | NoticePopupModalProps | Y | 171 |
+| ParentMenuRedirect | ParentMenuRedirect.tsx | named | ParentMenuRedirectProps | Y | 82 |
+| PermissionGuard | PermissionGuard.tsx | named | PermissionGuardProps | Y | 44 |
+| ScheduleBar | ScheduleBar.tsx | named | ScheduleBarProps | Y | 96 |
+| ScheduleCalendar | ScheduleCalendar.tsx | named |  | Y | 194 |
+| ServerErrorPage | ServerErrorPage.tsx | named | ServerErrorPageProps | Y | 140 |
+| WeekTimeView | WeekTimeView.tsx | named |  | Y | 217 |
+| WeekView | WeekView.tsx | named |  | Y | 211 |
+
+## LAYOUT (3)
+
+### layout (3)
+
+| Component | File | Export | Props | Client | Lines |
+|-----------|------|--------|-------|--------|-------|
+| CommandMenuSearch | CommandMenuSearch.tsx | default |  | Y | 199 |
+| HeaderFavoritesBar | HeaderFavoritesBar.tsx | default | HeaderFavoritesBarProps | Y | 156 |
+| Sidebar | Sidebar.tsx | default | SidebarProps |  | 390 |
+
+## DEV (2)
+
+### dev (2)
+
+| Component | File | Export | Props | Client | Lines |
+|-----------|------|--------|-------|--------|-------|
+| DevFillProvider | DevFillContext.tsx | named | DevFillProviderProps | Y | 179 |
+| DevToolbar | DevToolbar.tsx | both |  | Y | 499 |
+
+## DOMAIN (404)
+
+### LanguageSelect.tsx (1)
+
+| Component | File | Export | Props | Client | Lines |
+|-----------|------|--------|-------|--------|-------|
+| LanguageSelect | LanguageSelect.tsx | named | LanguageSelectProps | Y | 90 |
+
+### ThemeSelect.tsx (1)
+
+| Component | File | Export | Props | Client | Lines |
+|-----------|------|--------|-------|--------|-------|
+| ThemeSelect | ThemeSelect.tsx | named | ThemeSelectProps | Y | 82 |
+
+### accounting (19)
+
+| Component | File | Export | Props | Client | Lines |
+|-----------|------|--------|-------|--------|-------|
+| BadDebtDetail | BadDebtDetail.tsx | named | BadDebtDetailProps | Y | 963 |
+| BadDebtDetailClientV2 | BadDebtDetailClientV2.tsx | named | BadDebtDetailClientV2Props | Y | 136 |
+| BillDetail | BillDetail.tsx | named | BillDetailProps | Y | 540 |
+| BillManagementClient | BillManagementClient.tsx | named | BillManagementClientProps | Y | 522 |
+| CardTransactionDetailClient | CardTransactionDetailClient.tsx | default | CardTransactionDetailClientProps | Y | 139 |
+| CreditAnalysisDocument | CreditAnalysisDocument.tsx | named | CreditAnalysisDocumentProps | Y | 210 |
+| CreditSignal | CreditSignal.tsx | named | CreditSignalProps | Y | 58 |
+| DepositDetail | DepositDetail.tsx | named | DepositDetailProps | Y | 327 |
+| DepositDetailClientV2 | DepositDetailClientV2.tsx | default | DepositDetailClientV2Props | Y | 144 |
+| PurchaseDetail | PurchaseDetail.tsx | named | PurchaseDetailProps | Y | 697 |
+| PurchaseDetailModal | PurchaseDetailModal.tsx | named | PurchaseDetailModalProps | Y | 402 |
+| RiskRadarChart | RiskRadarChart.tsx | named | RiskRadarChartProps | Y | 95 |
+| SalesDetail | SalesDetail.tsx | named | SalesDetailProps | Y | 579 |
+| VendorDetail | VendorDetail.tsx | named | VendorDetailProps | Y | 684 |
+| VendorDetailClient | VendorDetailClient.tsx | named | VendorDetailClientProps | Y | 586 |
+| VendorLedgerDetail | VendorLedgerDetail.tsx | named | VendorLedgerDetailProps | Y | 386 |
+| VendorManagementClient | VendorManagementClient.tsx | named | VendorManagementClientProps | Y | 574 |
+| WithdrawalDetail | WithdrawalDetail.tsx | named | WithdrawalDetailProps | Y | 327 |
+| WithdrawalDetailClientV2 | WithdrawalDetailClientV2.tsx | default | WithdrawalDetailClientV2Props | Y | 144 |
+
+### approval (11)
+
+| Component | File | Export | Props | Client | Lines |
+|-----------|------|--------|-------|--------|-------|
+| ApprovalLineBox | ApprovalLineBox.tsx | named | ApprovalLineBoxProps | Y | 85 |
+| ApprovalLineSection | ApprovalLineSection.tsx | named | ApprovalLineSectionProps | Y | 108 |
+| BasicInfoSection | BasicInfoSection.tsx | named | BasicInfoSectionProps | Y | 81 |
+| DocumentDetailModalV2 | DocumentDetailModalV2.tsx | named |  | Y | 94 |
+| ExpenseEstimateDocument | ExpenseEstimateDocument.tsx | named | ExpenseEstimateDocumentProps | Y | 130 |
+| ExpenseEstimateForm | ExpenseEstimateForm.tsx | named | ExpenseEstimateFormProps | Y | 167 |
+| ExpenseReportDocument | ExpenseReportDocument.tsx | named | ExpenseReportDocumentProps | Y | 138 |
+| ExpenseReportForm | ExpenseReportForm.tsx | named | ExpenseReportFormProps | Y | 243 |
+| ProposalDocument | ProposalDocument.tsx | named | ProposalDocumentProps | Y | 117 |
+| ProposalForm | ProposalForm.tsx | named | ProposalFormProps | Y | 234 |
+| ReferenceSection | ReferenceSection.tsx | named | ReferenceSectionProps | Y | 109 |
+
+### attendance (2)
+
+| Component | File | Export | Props | Client | Lines |
+|-----------|------|--------|-------|--------|-------|
+| AttendanceComplete | AttendanceComplete.tsx | default | AttendanceCompleteProps | Y | 83 |
+| GoogleMap | GoogleMap.tsx | default | GoogleMapProps | Y | 309 |
+
+### auth (2)
+
+| Component | File | Export | Props | Client | Lines |
+|-----------|------|--------|-------|--------|-------|
+| LoginPage | LoginPage.tsx | named |  | Y | 301 |
+| SignupPage | SignupPage.tsx | named |  | Y | 763 |
+
+### board (8)
+
+| Component | File | Export | Props | Client | Lines |
+|-----------|------|--------|-------|--------|-------|
+| BoardDetail | BoardDetail.tsx | named | BoardDetailProps | Y | 120 |
+| BoardDetailClientV2 | BoardDetailClientV2.tsx | named | BoardDetailClientV2Props | Y | 308 |
+| BoardForm | BoardForm.tsx | named | BoardFormProps | Y | 271 |
+| BoardListUnified | BoardListUnified.tsx | both |  | Y | 372 |
+| CommentItem | CommentItem.tsx | both | CommentItemProps | Y | 161 |
+| DynamicBoardCreateForm | DynamicBoardCreateForm.tsx | named | DynamicBoardCreateFormProps | Y | 166 |
+| DynamicBoardEditForm | DynamicBoardEditForm.tsx | named | DynamicBoardEditFormProps | Y | 253 |
+| MenuBar | MenuBar.tsx | named | MenuBarProps | Y | 289 |
+
+### business (97)
+
+| Component | File | Export | Props | Client | Lines |
+|-----------|------|--------|-------|--------|-------|
+| BiddingDetailForm | BiddingDetailForm.tsx | default | BiddingDetailFormProps | Y | 533 |
+| BiddingListClient | BiddingListClient.tsx | default | BiddingListClientProps | Y | 385 |
+| CalendarSection | CalendarSection.tsx | named | CalendarSectionProps | Y | 421 |
+| CardManagementSection | CardManagementSection.tsx | named | CardManagementSectionProps | Y | 71 |
+| CategoryDialog | CategoryDialog.tsx | named |  | Y | 89 |
+| CEODashboard | CEODashboard.tsx | named |  | Y | 407 |
+| ConstructionDashboard | ConstructionDashboard.tsx | named |  | Y | 19 |
+| ConstructionDetailCard | ConstructionDetailCard.tsx | named | ConstructionDetailCardProps | Y | 83 |
+| ConstructionDetailClient | ConstructionDetailClient.tsx | default | ConstructionDetailClientProps | Y | 732 |
+| ConstructionMainDashboard | ConstructionMainDashboard.tsx | named |  | Y | 196 |
+| ConstructionManagementListClient | ConstructionManagementListClient.tsx | default | ConstructionManagementListClientProps | Y | 540 |
+| ContractDetailForm | ContractDetailForm.tsx | default | ContractDetailFormProps | Y | 541 |
+| ContractDocumentModal | ContractDocumentModal.tsx | named | ContractDocumentModalProps | Y | 64 |
+| ContractInfoCard | ContractInfoCard.tsx | named | ContractInfoCardProps | Y | 169 |
+| ContractInfoCard | ContractInfoCard.tsx | named | ContractInfoCardProps | Y | 58 |
+| ContractListClient | ContractListClient.tsx | default | ContractListClientProps | Y | 399 |
+| DailyReportSection | DailyReportSection.tsx | named | DailyReportSectionProps | Y | 37 |
+| Dashboard | Dashboard.tsx | named |  | Y | 33 |
+| DashboardSettingsDialog | DashboardSettingsDialog.tsx | named | DashboardSettingsDialogProps | Y | 744 |
+| DashboardSwitcher | DashboardSwitcher.tsx | named |  | Y | 89 |
+| DebtCollectionSection | DebtCollectionSection.tsx | named | DebtCollectionSectionProps | Y | 62 |
+| DetailAccordion | DetailAccordion.tsx | default | DetailAccordionProps | Y | 199 |
+| DetailCard | DetailCard.tsx | default | DetailCardProps | Y | 69 |
+| DetailModal | DetailModal.tsx | named | DetailModalProps | Y | 763 |
+| DirectConstructionContent | DirectConstructionContent.tsx | named | DirectConstructionContentProps | Y | 157 |
+| DirectConstructionModal | DirectConstructionModal.tsx | named | DirectConstructionModalProps | Y | 60 |
+| ElectronicApprovalModal | ElectronicApprovalModal.tsx | named | ElectronicApprovalModalProps | Y | 299 |
+| ElectronicApprovalModal | ElectronicApprovalModal.tsx | none |  |  | 2 |
+| EnhancedDailyReportSection | EnhancedSections.tsx | named | EnhancedDailyReportSectionProps | Y | 534 |
+| EntertainmentSection | EntertainmentSection.tsx | named | EntertainmentSectionProps | Y | 53 |
+| EstimateDetailForm | EstimateDetailForm.tsx | default | EstimateDetailFormProps | Y | 761 |
+| EstimateDetailTableSection | EstimateDetailTableSection.tsx | named | EstimateDetailTableSectionProps | Y | 657 |
+| EstimateDocumentContent | EstimateDocumentContent.tsx | named | EstimateDocumentContentProps | Y | 286 |
+| EstimateDocumentModal | EstimateDocumentModal.tsx | named | EstimateDocumentModalProps | Y | 88 |
+| EstimateInfoSection | EstimateInfoSection.tsx | named | EstimateInfoSectionProps | Y | 262 |
+| EstimateListClient | EstimateListClient.tsx | default | EstimateListClientProps | Y | 376 |
+| EstimateSummarySection | EstimateSummarySection.tsx | named | EstimateSummarySectionProps | Y | 182 |
+| ExpenseDetailSection | ExpenseDetailSection.tsx | named | ExpenseDetailSectionProps | Y | 197 |
+| HandoverReportDetailForm | HandoverReportDetailForm.tsx | default | HandoverReportDetailFormProps | Y | 694 |
+| HandoverReportDocumentModal | HandoverReportDocumentModal.tsx | named | HandoverReportDocumentModalProps | Y | 236 |
+| HandoverReportListClient | HandoverReportListClient.tsx | default | HandoverReportListClientProps | Y | 387 |
+| IndirectConstructionContent | IndirectConstructionContent.tsx | named | IndirectConstructionContentProps | Y | 143 |
+| IndirectConstructionModal | IndirectConstructionModal.tsx | named | IndirectConstructionModalProps | Y | 60 |
+| IssueDetailForm | IssueDetailForm.tsx | default | IssueDetailFormProps | Y | 625 |
+| IssueManagementListClient | IssueManagementListClient.tsx | default | IssueManagementListClientProps | Y | 514 |
+| ItemDetailClient | ItemDetailClient.tsx | default | ItemDetailClientProps | Y | 487 |
+| ItemManagementClient | ItemManagementClient.tsx | default | ItemManagementClientProps | Y | 618 |
+| KanbanColumn | KanbanColumn.tsx | default | KanbanColumnProps | Y | 53 |
+| LaborDetailClient | LaborDetailClient.tsx | default | LaborDetailClientProps | Y | 121 |
+| LaborManagementClient | LaborManagementClient.tsx | default | LaborManagementClientProps | Y | 372 |
+| MainDashboard | MainDashboard.tsx | named |  |  | 2652 |
+| MonthlyExpenseSection | MonthlyExpenseSection.tsx | named | MonthlyExpenseSectionProps | Y | 38 |
+| OrderDetailForm | OrderDetailForm.tsx | default | OrderDetailFormProps | Y | 276 |
+| OrderDetailItemTable | OrderDetailItemTable.tsx | named | OrderDetailItemTableProps | Y | 445 |
+| OrderDialogs | OrderDialogs.tsx | named | OrderDialogsProps | Y | 66 |
+| OrderDocumentModal | OrderDocumentModal.tsx | named | OrderDocumentModalProps | Y | 311 |
+| OrderInfoCard | OrderInfoCard.tsx | named | OrderInfoCardProps | Y | 143 |
+| OrderManagementListClient | OrderManagementListClient.tsx | default | OrderManagementListClientProps | Y | 608 |
+| OrderManagementUnified | OrderManagementUnified.tsx | both | OrderManagementUnifiedProps | Y | 641 |
+| OrderMemoCard | OrderMemoCard.tsx | named | OrderMemoCardProps | Y | 29 |
+| OrderScheduleCard | OrderScheduleCard.tsx | named | OrderScheduleCardProps | Y | 42 |
+| PartnerForm | PartnerForm.tsx | default | PartnerFormProps | Y | 642 |
+| PartnerListClient | PartnerListClient.tsx | default | PartnerListClientProps | Y | 335 |
+| PhotoDocumentContent | PhotoDocumentContent.tsx | named | PhotoDocumentContentProps | Y | 130 |
+| PhotoDocumentModal | PhotoDocumentModal.tsx | named | PhotoDocumentModalProps | Y | 60 |
+| PhotoTable | PhotoTable.tsx | named | PhotoTableProps | Y | 153 |
+| PriceAdjustmentSection | PriceAdjustmentSection.tsx | named | PriceAdjustmentSectionProps | Y | 150 |
+| PricingDetailClient | PricingDetailClient.tsx | default | PricingDetailClientProps | Y | 135 |
+| PricingListClient | PricingListClient.tsx | default | PricingListClientProps | Y | 477 |
+| ProgressBillingDetailForm | ProgressBillingDetailForm.tsx | default | ProgressBillingDetailFormProps | Y | 193 |
+| ProgressBillingInfoCard | ProgressBillingInfoCard.tsx | named | ProgressBillingInfoCardProps | Y | 78 |
+| ProgressBillingItemTable | ProgressBillingItemTable.tsx | named | ProgressBillingItemTableProps | Y | 193 |
+| ProgressBillingManagementListClient | ProgressBillingManagementListClient.tsx | default | ProgressBillingManagementListClientProps | Y | 343 |
+| ProjectCard | ProjectCard.tsx | default | ProjectCardProps | Y | 89 |
+| ProjectDetailClient | ProjectDetailClient.tsx | default | ProjectDetailClientProps | Y | 197 |
+| ProjectEndDialog | ProjectEndDialog.tsx | default | ProjectEndDialogProps | Y | 192 |
+| ProjectGanttChart | ProjectGanttChart.tsx | default | ProjectGanttChartProps | Y | 367 |
+| ProjectKanbanBoard | ProjectKanbanBoard.tsx | default | ProjectKanbanBoardProps | Y | 244 |
+| ProjectListClient | ProjectListClient.tsx | default | ProjectListClientProps | Y | 629 |
+| ReceivableSection | ReceivableSection.tsx | named | ReceivableSectionProps | Y | 69 |
+| ScheduleDetailModal | ScheduleDetailModal.tsx | named | ScheduleDetailModalProps | Y | 290 |
+| SECTION_THEME_STYLES | components.tsx | named |  | Y | 434 |
+| SiteBriefingForm | SiteBriefingForm.tsx | default | SiteBriefingFormProps | Y | 957 |
+| SiteBriefingListClient | SiteBriefingListClient.tsx | default | SiteBriefingListClientProps | Y | 362 |
+| SiteDetailClientV2 | SiteDetailClientV2.tsx | both | SiteDetailClientV2Props | Y | 141 |
+| SiteDetailForm | SiteDetailForm.tsx | default | SiteDetailFormProps | Y | 386 |
+| SiteManagementListClient | SiteManagementListClient.tsx | default | SiteManagementListClientProps | Y | 338 |
+| StageCard | StageCard.tsx | default | StageCardProps | Y | 89 |
+| StatusBoardSection | StatusBoardSection.tsx | named | StatusBoardSectionProps | Y | 72 |
+| StructureReviewDetailClientV2 | StructureReviewDetailClientV2.tsx | both | StructureReviewDetailClientV2Props | Y | 149 |
+| StructureReviewDetailForm | StructureReviewDetailForm.tsx | default | StructureReviewDetailFormProps | Y | 390 |
+| StructureReviewListClient | StructureReviewListClient.tsx | default | StructureReviewListClientProps | Y | 375 |
+| TodayIssueSection | TodayIssueSection.tsx | named | TodayIssueSectionProps | Y | 453 |
+| UtilityManagementListClient | UtilityManagementListClient.tsx | default | UtilityManagementListClientProps | Y | 395 |
+| VatSection | VatSection.tsx | named | VatSectionProps | Y | 38 |
+| WelfareSection | WelfareSection.tsx | named | WelfareSectionProps | Y | 53 |
+| WorkerStatusListClient | WorkerStatusListClient.tsx | default | WorkerStatusListClientProps | Y | 416 |
+
+### checklist-management (7)
+
+| Component | File | Export | Props | Client | Lines |
+|-----------|------|--------|-------|--------|-------|
+| ChecklistDetail | ChecklistDetail.tsx | named | ChecklistDetailProps | Y | 316 |
+| ChecklistDetailClient | ChecklistDetailClient.tsx | named | ChecklistDetailClientProps | Y | 123 |
+| ChecklistForm | ChecklistForm.tsx | named | ChecklistFormProps | Y | 173 |
+| ChecklistListClient | ChecklistListClient.tsx | default |  | Y | 520 |
+| ItemDetail | ItemDetail.tsx | named | ItemDetailProps | Y | 224 |
+| ItemDetailClient | ItemDetailClient.tsx | named | ItemDetailClientProps | Y | 111 |
+| ItemForm | ItemForm.tsx | named | ItemFormProps | Y | 351 |
+
+### clients (3)
+
+| Component | File | Export | Props | Client | Lines |
+|-----------|------|--------|-------|--------|-------|
+| ClientDetail | ClientDetail.tsx | named | ClientDetailProps | Y | 254 |
+| ClientDetailClientV2 | ClientDetailClientV2.tsx | named | ClientDetailClientV2Props | Y | 253 |
+| ClientRegistration | ClientRegistration.tsx | named | ClientRegistrationProps | Y | 468 |
+
+### customer-center (9)
+
+| Component | File | Export | Props | Client | Lines |
+|-----------|------|--------|-------|--------|-------|
+| EventDetail | EventDetail.tsx | both | EventDetailProps | Y | 102 |
+| EventList | EventList.tsx | both |  | Y | 261 |
+| FAQList | FAQList.tsx | both |  | Y | 172 |
+| InquiryDetail | InquiryDetail.tsx | both | InquiryDetailProps | Y | 359 |
+| InquiryDetailClientV2 | InquiryDetailClientV2.tsx | both | InquiryDetailClientV2Props | Y | 224 |
+| InquiryForm | InquiryForm.tsx | both | InquiryFormProps | Y | 237 |
+| InquiryList | InquiryList.tsx | both |  | Y | 292 |
+| NoticeDetail | NoticeDetail.tsx | both | NoticeDetailProps | Y | 102 |
+| NoticeList | NoticeList.tsx | both |  | Y | 227 |
+
+### document-system (11)
+
+| Component | File | Export | Props | Client | Lines |
+|-----------|------|--------|-------|--------|-------|
+| ApprovalLine | ApprovalLine.tsx | named | ApprovalLineProps | Y | 170 |
+| ConstructionApprovalTable | ConstructionApprovalTable.tsx | named | ConstructionApprovalTableProps | Y | 116 |
+| DocumentContent | DocumentContent.tsx | named | DocumentContentProps | Y | 59 |
+| DocumentHeader | DocumentHeader.tsx | named | DocumentHeaderProps | Y | 248 |
+| DocumentToolbar | DocumentToolbar.tsx | named | DocumentToolbarProps | Y | 327 |
+| DocumentViewer | DocumentViewer.tsx | named |  | Y | 378 |
+| InfoTable | InfoTable.tsx | named | InfoTableProps | Y | 95 |
+| LotApprovalTable | LotApprovalTable.tsx | named | LotApprovalTableProps | Y | 122 |
+| QualityApprovalTable | QualityApprovalTable.tsx | named | QualityApprovalTableProps | Y | 123 |
+| SectionHeader | SectionHeader.tsx | named | SectionHeaderProps | Y | 46 |
+| SignatureSection | SignatureSection.tsx | named | SignatureSectionProps | Y | 107 |
+
+### hr (24)
+
+| Component | File | Export | Props | Client | Lines |
+|-----------|------|--------|-------|--------|-------|
+| AttendanceInfoDialog | AttendanceInfoDialog.tsx | named |  | Y | 301 |
+| CardDetail | CardDetail.tsx | named | CardDetailProps | Y | 132 |
+| CardForm | CardForm.tsx | named | CardFormProps | Y | 246 |
+| CardManagementUnified | CardManagementUnified.tsx | named | CardManagementUnifiedProps | Y | 267 |
+| CSVUploadDialog | CSVUploadDialog.tsx | named | CSVUploadDialogProps | Y | 252 |
+| CSVUploadPage | CSVUploadPage.tsx | named | CSVUploadPageProps | Y | 355 |
+| DepartmentDialog | DepartmentDialog.tsx | named |  | Y | 92 |
+| DepartmentStats | DepartmentStats.tsx | named |  | Y | 18 |
+| DepartmentToolbar | DepartmentToolbar.tsx | named |  | Y | 60 |
+| DepartmentTree | DepartmentTree.tsx | named |  | Y | 70 |
+| DepartmentTreeItem | DepartmentTreeItem.tsx | named |  | Y | 118 |
+| EmployeeDetail | EmployeeDetail.tsx | named | EmployeeDetailProps | Y | 222 |
+| EmployeeDialog | EmployeeDialog.tsx | named |  | Y | 582 |
+| EmployeeForm | EmployeeForm.tsx | named | EmployeeFormProps | Y | 1052 |
+| EmployeeToolbar | EmployeeToolbar.tsx | named | EmployeeToolbarProps | Y | 82 |
+| FieldSettingsDialog | FieldSettingsDialog.tsx | named | FieldSettingsDialogProps | Y | 259 |
+| ReasonInfoDialog | ReasonInfoDialog.tsx | named |  | Y | 140 |
+| SalaryDetailDialog | SalaryDetailDialog.tsx | named | SalaryDetailDialogProps | Y | 420 |
+| UserInviteDialog | UserInviteDialog.tsx | named | UserInviteDialogProps | Y | 116 |
+| VacationAdjustDialog | VacationAdjustDialog.tsx | named | VacationAdjustDialogProps | Y | 225 |
+| VacationGrantDialog | VacationGrantDialog.tsx | named | VacationGrantDialogProps | Y | 202 |
+| VacationRegisterDialog | VacationRegisterDialog.tsx | named | VacationRegisterDialogProps | Y | 201 |
+| VacationRequestDialog | VacationRequestDialog.tsx | named | VacationRequestDialogProps | Y | 208 |
+| VacationTypeSettingsDialog | VacationTypeSettingsDialog.tsx | named | VacationTypeSettingsDialogProps | Y | 192 |
+
+### items (65)
+
+| Component | File | Export | Props | Client | Lines |
+|-----------|------|--------|-------|--------|-------|
+| AssemblyPartForm | AssemblyPartForm.tsx | default | AssemblyPartFormProps |  | 337 |
+| AttributeTabContent | AttributeTabContent.tsx | named | AttributeTabContentProps | Y | 453 |
+| BendingDiagramSection | BendingDiagramSection.tsx | default | BendingDiagramSectionProps |  | 477 |
+| BendingPartForm | BendingPartForm.tsx | default | BendingPartFormProps |  | 304 |
+| BOMManagementSection | BOMManagementSection.tsx | named | BOMManagementSectionProps | Y | 293 |
+| BOMSection | BOMSection.tsx | default | BOMSectionProps |  | 366 |
+| CheckboxField | CheckboxField.tsx | named |  | Y | 47 |
+| ColumnDialog | ColumnDialog.tsx | named | ColumnDialogProps | Y | 124 |
+| ColumnManageDialog | ColumnManageDialog.tsx | named | ColumnManageDialogProps | Y | 210 |
+| ComputedField | ComputedField.tsx | named |  | Y | 136 |
+| ConditionalDisplayUI | ConditionalDisplayUI.tsx | named | ConditionalDisplayUIProps |  | 349 |
+| CurrencyField | CurrencyField.tsx | named |  | Y | 127 |
+| DateField | DateField.tsx | named |  | Y | 45 |
+| DraggableField | DraggableField.tsx | named | DraggableFieldProps |  | 130 |
+| DraggableSection | DraggableSection.tsx | named | DraggableSectionProps |  | 140 |
+| DrawingCanvas | DrawingCanvas.tsx | named | DrawingCanvasProps | Y | 404 |
+| DropdownField | DropdownField.tsx | named |  | Y | 141 |
+| DuplicateCodeDialog | DuplicateCodeDialog.tsx | named | DuplicateCodeDialogProps | Y | 49 |
+| DynamicBOMSection | DynamicBOMSection.tsx | default | DynamicBOMSectionProps | Y | 515 |
+| DynamicFieldRenderer | DynamicFieldRenderer.tsx | named |  | Y | 86 |
+| DynamicTableSection | DynamicTableSection.tsx | default | DynamicTableSectionProps | Y | 200 |
+| ErrorAlertDialog | ErrorAlertDialog.tsx | named | ErrorAlertDialogProps | Y | 51 |
+| ErrorAlertProvider | ErrorAlertContext.tsx | named | ErrorAlertProviderProps | Y | 94 |
+| FieldDialog | FieldDialog.tsx | named | FieldDialogProps | Y | 478 |
+| FieldDrawer | FieldDrawer.tsx | named | FieldDrawerProps | Y | 682 |
+| FileField | FileField.tsx | named |  | Y | 200 |
+| FileUpload | FileUpload.tsx | default | FileUploadProps | Y | 233 |
+| FileUploadFields | FileUploadFields.tsx | named | FileUploadFieldsProps | Y | 240 |
+| FormHeader | FormHeader.tsx | named | FormHeaderProps | Y | 31 |
+| FormHeader | FormHeader.tsx | default | FormHeaderProps |  | 62 |
+| ImportFieldDialog | ImportFieldDialog.tsx | named | ImportFieldDialogProps | Y | 279 |
+| ImportSectionDialog | ImportSectionDialog.tsx | named | ImportSectionDialogProps | Y | 221 |
+| ItemDetailClient | ItemDetailClient.tsx | default | ItemDetailClientProps | Y | 638 |
+| ItemDetailEdit | ItemDetailEdit.tsx | named | ItemDetailEditProps | Y | 390 |
+| ItemDetailView | ItemDetailView.tsx | named | ItemDetailViewProps | Y | 275 |
+| ItemFormContext | ItemFormContext.tsx | both | ItemFormProviderProps | Y | 77 |
+| ItemListClient | ItemListClient.tsx | default |  | Y | 607 |
+| ItemMasterDataManagement | ItemMasterDataManagement.tsx | named |  | Y | 1006 |
+| ItemMasterDialogs | ItemMasterDialogs.tsx | named | ItemMasterDialogsProps | Y | 968 |
+| ItemTypeSelect | ItemTypeSelect.tsx | default | ItemTypeSelectProps | Y | 76 |
+| LoadTemplateDialog | LoadTemplateDialog.tsx | named | LoadTemplateDialogProps | Y | 103 |
+| MasterFieldDialog | MasterFieldDialog.tsx | named | MasterFieldDialogProps | Y | 306 |
+| MaterialForm | MaterialForm.tsx | default | MaterialFormProps |  | 354 |
+| MultiSelectField | MultiSelectField.tsx | named |  | Y | 192 |
+| NumberField | NumberField.tsx | named |  | Y | 58 |
+| OptionDialog | OptionDialog.tsx | named | OptionDialogProps | Y | 262 |
+| PageDialog | PageDialog.tsx | named | PageDialogProps | Y | 107 |
+| PartForm | PartForm.tsx | default | PartFormProps |  | 273 |
+| PathEditDialog | PathEditDialog.tsx | named | PathEditDialogProps | Y | 86 |
+| ProductForm | ProductForm.tsx | both | ProductFormProps |  | 307 |
+| PurchasedPartForm | PurchasedPartForm.tsx | default | PurchasedPartFormProps |  | 336 |
+| RadioField | RadioField.tsx | named |  | Y | 92 |
+| ReferenceField | ReferenceField.tsx | named |  | Y | 168 |
+| SectionDialog | SectionDialog.tsx | named | SectionDialogProps | Y | 335 |
+| SectionsTab | SectionsTab.tsx | named | SectionsTabProps | Y | 363 |
+| SectionTemplateDialog | SectionTemplateDialog.tsx | named | SectionTemplateDialogProps | Y | 180 |
+| TableCellRenderer | TableCellRenderer.tsx | named | TableCellRendererProps | Y | 85 |
+| TabManagementDialogs | TabManagementDialogs.tsx | named | TabManagementDialogsProps | Y | 409 |
+| TemplateFieldDialog | TemplateFieldDialog.tsx | named | TemplateFieldDialogProps | Y | 392 |
+| TextareaField | TextareaField.tsx | named |  | Y | 51 |
+| TextField | TextField.tsx | named |  | Y | 48 |
+| ToggleField | ToggleField.tsx | named |  | Y | 62 |
+| UnitValueField | UnitValueField.tsx | named |  | Y | 129 |
+| ValidationAlert | ValidationAlert.tsx | named | ValidationAlertProps | Y | 42 |
+| ValidationAlert | ValidationAlert.tsx | default | ValidationAlertProps |  | 50 |
+
+### material (13)
+
+| Component | File | Export | Props | Client | Lines |
+|-----------|------|--------|-------|--------|-------|
+| ImportInspectionInputModal | ImportInspectionInputModal.tsx | named | ImportInspectionInputModalProps | Y | 798 |
+| InspectionCreate | InspectionCreate.tsx | named | Props | Y | 364 |
+| InventoryAdjustmentDialog | InventoryAdjustmentDialog.tsx | named | Props | Y | 236 |
+| ReceivingDetail | ReceivingDetail.tsx | named | Props | Y | 921 |
+| ReceivingList | ReceivingList.tsx | named |  | Y | 467 |
+| ReceivingProcessDialog | ReceivingProcessDialog.tsx | named | Props | Y | 238 |
+| ReceivingReceiptContent | ReceivingReceiptContent.tsx | named | ReceivingReceiptContentProps | Y | 132 |
+| ReceivingReceiptDialog | ReceivingReceiptDialog.tsx | named | Props | Y | 46 |
+| StockAuditModal | StockAuditModal.tsx | named | StockAuditModalProps | Y | 237 |
+| StockStatusDetail | StockStatusDetail.tsx | named | StockStatusDetailProps | Y | 313 |
+| StockStatusList | StockStatusList.tsx | named |  | Y | 473 |
+| SuccessDialog | SuccessDialog.tsx | named | Props | Y | 49 |
+| SupplierSearchModal | SupplierSearchModal.tsx | named | SupplierSearchModalProps | Y | 161 |
+
+### orders (10)
+
+| Component | File | Export | Props | Client | Lines |
+|-----------|------|--------|-------|--------|-------|
+| ContractDocument | ContractDocument.tsx | named | ContractDocumentProps | Y | 246 |
+| ItemAddDialog | ItemAddDialog.tsx | named | ItemAddDialogProps | Y | 317 |
+| OrderDocumentModal | OrderDocumentModal.tsx | named | OrderDocumentModalProps | Y | 207 |
+| OrderRegistration | OrderRegistration.tsx | named | OrderRegistrationProps | Y | 1087 |
+| OrderSalesDetailEdit | OrderSalesDetailEdit.tsx | named | OrderSalesDetailEditProps | Y | 735 |
+| OrderSalesDetailView | OrderSalesDetailView.tsx | named | OrderSalesDetailViewProps | Y | 824 |
+| PurchaseOrderDocument | PurchaseOrderDocument.tsx | named | PurchaseOrderDocumentProps | Y | 223 |
+| QuotationSelectDialog | QuotationSelectDialog.tsx | named | QuotationSelectDialogProps | Y | 114 |
+| SalesOrderDocument | SalesOrderDocument.tsx | named | SalesOrderDocumentProps | Y | 638 |
+| TransactionDocument | TransactionDocument.tsx | named | TransactionDocumentProps | Y | 226 |
+
+### outbound (11)
+
+| Component | File | Export | Props | Client | Lines |
+|-----------|------|--------|-------|--------|-------|
+| DeliveryConfirmation | DeliveryConfirmation.tsx | named | DeliveryConfirmationProps | Y | 18 |
+| ShipmentCreate | ShipmentCreate.tsx | named |  | Y | 772 |
+| ShipmentDetail | ShipmentDetail.tsx | named | ShipmentDetailProps | Y | 671 |
+| ShipmentEdit | ShipmentEdit.tsx | named | ShipmentEditProps | Y | 791 |
+| ShipmentList | ShipmentList.tsx | named |  | Y | 399 |
+| ShipmentOrderDocument | ShipmentOrderDocument.tsx | named | ShipmentOrderDocumentProps | Y | 647 |
+| ShippingSlip | ShippingSlip.tsx | named | ShippingSlipProps | Y | 18 |
+| TransactionStatement | TransactionStatement.tsx | named | TransactionStatementProps | Y | 154 |
+| VehicleDispatchDetail | VehicleDispatchDetail.tsx | named | VehicleDispatchDetailProps | Y | 181 |
+| VehicleDispatchEdit | VehicleDispatchEdit.tsx | named | VehicleDispatchEditProps | Y | 399 |
+| VehicleDispatchList | VehicleDispatchList.tsx | named |  | Y | 331 |
+
+### pricing (5)
+
+| Component | File | Export | Props | Client | Lines |
+|-----------|------|--------|-------|--------|-------|
+| PricingFinalizeDialog | PricingFinalizeDialog.tsx | both | PricingFinalizeDialogProps | Y | 95 |
+| PricingFormClient | PricingFormClient.tsx | both | PricingFormClientProps | Y | 780 |
+| PricingHistoryDialog | PricingHistoryDialog.tsx | both | PricingHistoryDialogProps | Y | 170 |
+| PricingListClient | PricingListClient.tsx | both | PricingListClientProps | Y | 387 |
+| PricingRevisionDialog | PricingRevisionDialog.tsx | both | PricingRevisionDialogProps | Y | 95 |
+
+### pricing-distribution (3)
+
+| Component | File | Export | Props | Client | Lines |
+|-----------|------|--------|-------|--------|-------|
+| PriceDistributionDetail | PriceDistributionDetail.tsx | both | Props | Y | 539 |
+| PriceDistributionDocumentModal | PriceDistributionDocumentModal.tsx | both | Props | Y | 158 |
+| PriceDistributionList | PriceDistributionList.tsx | both |  | Y | 328 |
+
+### pricing-table-management (3)
+
+| Component | File | Export | Props | Client | Lines |
+|-----------|------|--------|-------|--------|-------|
+| PricingTableDetailClient | PricingTableDetailClient.tsx | named | PricingTableDetailClientProps | Y | 93 |
+| PricingTableForm | PricingTableForm.tsx | named | PricingTableFormProps | Y | 486 |
+| PricingTableListClient | PricingTableListClient.tsx | default |  | Y | 381 |
+
+### process-management (12)
+
+| Component | File | Export | Props | Client | Lines |
+|-----------|------|--------|-------|--------|-------|
+| InspectionPreviewModal | InspectionPreviewModal.tsx | named | InspectionPreviewModalProps | Y | 265 |
+| InspectionSettingModal | InspectionSettingModal.tsx | named | InspectionSettingModalProps | Y | 294 |
+| ProcessDetail | ProcessDetail.tsx | named | ProcessDetailProps | Y | 451 |
+| ProcessDetailClientV2 | ProcessDetailClientV2.tsx | named | ProcessDetailClientV2Props | Y | 137 |
+| ProcessForm | ProcessForm.tsx | named | ProcessFormProps | Y | 829 |
+| ProcessListClient | ProcessListClient.tsx | default | ProcessListClientProps | Y | 546 |
+| ProcessWorkLogContent | ProcessWorkLogContent.tsx | named | ProcessWorkLogContentProps | Y | 136 |
+| ProcessWorkLogPreviewModal | ProcessWorkLogPreviewModal.tsx | named | ProcessWorkLogPreviewModalProps | Y | 45 |
+| RuleModal | RuleModal.tsx | named | RuleModalProps | Y | 352 |
+| StepDetail | StepDetail.tsx | named | StepDetailProps | Y | 212 |
+| StepDetailClient | StepDetailClient.tsx | named | StepDetailClientProps | Y | 115 |
+| StepForm | StepForm.tsx | named | StepFormProps | Y | 397 |
+
+### production (31)
+
+| Component | File | Export | Props | Client | Lines |
+|-----------|------|--------|-------|--------|-------|
+| AssigneeSelectModal | AssigneeSelectModal.tsx | named | AssigneeSelectModalProps | Y | 317 |
+| BendingInspectionContent | BendingInspectionContent.tsx | named | BendingInspectionContentProps | Y | 490 |
+| BendingWipInspectionContent | BendingWipInspectionContent.tsx | named | BendingWipInspectionContentProps | Y | 304 |
+| BendingWorkLogContent | BendingWorkLogContent.tsx | named | BendingWorkLogContentProps | Y | 194 |
+| CompletionConfirmDialog | CompletionConfirmDialog.tsx | named | CompletionConfirmDialogProps | Y | 64 |
+| CompletionToast | CompletionToast.tsx | named | CompletionToastProps | Y | 28 |
+| InspectionCheckbox | inspection-shared.tsx | named |  | Y | 282 |
+| InspectionInputModal | InspectionInputModal.tsx | named | InspectionInputModalProps | Y | 978 |
+| InspectionReportModal | InspectionReportModal.tsx | named | InspectionReportModalProps | Y | 409 |
+| IssueReportModal | IssueReportModal.tsx | named | IssueReportModalProps | Y | 178 |
+| MaterialInputModal | MaterialInputModal.tsx | named | MaterialInputModalProps | Y | 333 |
+| ProcessDetailSection | ProcessDetailSection.tsx | named | ProcessDetailSectionProps | Y | 392 |
+| SalesOrderSelectModal | SalesOrderSelectModal.tsx | named | SalesOrderSelectModalProps | Y | 102 |
+| ScreenInspectionContent | ScreenInspectionContent.tsx | named | ScreenInspectionContentProps | Y | 310 |
+| ScreenWorkLogContent | ScreenWorkLogContent.tsx | named | ScreenWorkLogContentProps | Y | 201 |
+| SlatInspectionContent | SlatInspectionContent.tsx | named | SlatInspectionContentProps | Y | 297 |
+| SlatJointBarInspectionContent | SlatJointBarInspectionContent.tsx | named | SlatJointBarInspectionContentProps | Y | 311 |
+| SlatWorkLogContent | SlatWorkLogContent.tsx | named | SlatWorkLogContentProps | Y | 198 |
+| TemplateInspectionContent | TemplateInspectionContent.tsx | named | TemplateInspectionContentProps | Y | 719 |
+| WipProductionModal | WipProductionModal.tsx | named | WipProductionModalProps | Y | 272 |
+| WorkCard | WorkCard.tsx | named | WorkCardProps | Y | 188 |
+| WorkCompletionResultDialog | WorkCompletionResultDialog.tsx | named | WorkCompletionResultDialogProps | Y | 85 |
+| WorkItemCard | WorkItemCard.tsx | named | WorkItemCardProps | Y | 382 |
+| WorkLogContent | WorkLogContent.tsx | named | WorkLogContentProps | Y | 195 |
+| WorkLogModal | WorkLogModal.tsx | named | WorkLogModalProps | Y | 152 |
+| WorkOrderCreate | WorkOrderCreate.tsx | named |  | Y | 545 |
+| WorkOrderDetail | WorkOrderDetail.tsx | named | WorkOrderDetailProps | Y | 656 |
+| WorkOrderEdit | WorkOrderEdit.tsx | named | WorkOrderEditProps | Y | 656 |
+| WorkOrderList | WorkOrderList.tsx | named |  | Y | 460 |
+| WorkOrderListPanel | WorkOrderListPanel.tsx | named | WorkOrderListPanelProps | Y | 132 |
+| WorkResultList | WorkResultList.tsx | named |  | Y | 374 |
+
+### quality (11)
+
+| Component | File | Export | Props | Client | Lines |
+|-----------|------|--------|-------|--------|-------|
+| InspectionCreate | InspectionCreate.tsx | named |  | Y | 695 |
+| InspectionDetail | InspectionDetail.tsx | named | InspectionDetailProps | Y | 1126 |
+| InspectionList | InspectionList.tsx | named |  | Y | 388 |
+| InspectionReportDocument | InspectionReportDocument.tsx | named | InspectionReportDocumentProps | Y | 416 |
+| InspectionReportModal | InspectionReportModal.tsx | named | InspectionReportModalProps | Y | 170 |
+| InspectionRequestDocument | InspectionRequestDocument.tsx | named | InspectionRequestDocumentProps | Y | 258 |
+| InspectionRequestModal | InspectionRequestModal.tsx | named | InspectionRequestModalProps | Y | 40 |
+| MemoModal | MemoModal.tsx | named | MemoModalProps | Y | 92 |
+| OrderSelectModal | OrderSelectModal.tsx | named | OrderSelectModalProps | Y | 111 |
+| PerformanceReportList | PerformanceReportList.tsx | named |  | Y | 604 |
+| ProductInspectionInputModal | ProductInspectionInputModal.tsx | named | ProductInspectionInputModalProps | Y | 486 |
+
+### quotes (15)
+
+| Component | File | Export | Props | Client | Lines |
+|-----------|------|--------|-------|--------|-------|
+| DiscountModal | DiscountModal.tsx | named | DiscountModalProps | Y | 232 |
+| FormulaViewModal | FormulaViewModal.tsx | named | FormulaViewModalProps | Y | 316 |
+| ItemSearchModal | ItemSearchModal.tsx | named | ItemSearchModalProps | Y | 114 |
+| LocationDetailPanel | LocationDetailPanel.tsx | named | LocationDetailPanelProps | Y | 827 |
+| LocationEditModal | LocationEditModal.tsx | named | LocationEditModalProps | Y | 283 |
+| LocationListPanel | LocationListPanel.tsx | named | LocationListPanelProps | Y | 575 |
+| PurchaseOrderDocument | PurchaseOrderDocument.tsx | named | PurchaseOrderDocumentProps |  | 265 |
+| QuoteDocument | QuoteDocument.tsx | named | QuoteDocumentProps |  | 409 |
+| QuoteFooterBar | QuoteFooterBar.tsx | named | QuoteFooterBarProps | Y | 236 |
+| QuoteManagementClient | QuoteManagementClient.tsx | named | QuoteManagementClientProps | Y | 713 |
+| QuotePreviewContent | QuotePreviewContent.tsx | named | QuotePreviewContentProps | Y | 434 |
+| QuotePreviewModal | QuotePreviewModal.tsx | named | QuotePreviewModalProps | Y | 132 |
+| QuoteRegistration | QuoteRegistration.tsx | named | QuoteRegistrationProps | Y | 1023 |
+| QuoteSummaryPanel | QuoteSummaryPanel.tsx | named | QuoteSummaryPanelProps | Y | 277 |
+| QuoteTransactionModal | QuoteTransactionModal.tsx | named | QuoteTransactionModalProps | Y | 324 |
+
+### settings (16)
+
+| Component | File | Export | Props | Client | Lines |
+|-----------|------|--------|-------|--------|-------|
+| AccountDetail | AccountDetail.tsx | named | AccountDetailProps | Y | 356 |
+| AccountDetail | AccountDetail.tsx | named | AccountDetailProps | Y | 369 |
+| AddCompanyDialog | AddCompanyDialog.tsx | named | AddCompanyDialogProps | Y | 149 |
+| ItemSettingsDialog | ItemSettingsDialog.tsx | named | ItemSettingsDialogProps | Y | 336 |
+| PaymentHistoryClient | PaymentHistoryClient.tsx | named | PaymentHistoryClientProps | Y | 255 |
+| PermissionDetail | PermissionDetail.tsx | named | PermissionDetailProps | Y | 456 |
+| PermissionDetailClient | PermissionDetailClient.tsx | named | PermissionDetailClientProps | Y | 700 |
+| PermissionDialog | PermissionDialog.tsx | named |  | Y | 109 |
+| PopupDetail | PopupDetail.tsx | both | PopupDetailProps | Y | 125 |
+| PopupDetailClientV2 | PopupDetailClientV2.tsx | named | PopupDetailClientV2Props | Y | 199 |
+| PopupForm | PopupForm.tsx | both | PopupFormProps | Y | 319 |
+| PopupList | PopupList.tsx | both | PopupListProps | Y | 198 |
+| RankDialog | RankDialog.tsx | named |  | Y | 89 |
+| SubscriptionClient | SubscriptionClient.tsx | named | SubscriptionClientProps | Y | 242 |
+| SubscriptionManagement | SubscriptionManagement.tsx | named | SubscriptionManagementProps | Y | 250 |
+| TitleDialog | TitleDialog.tsx | named |  | Y | 90 |
+
+### templates (11)
+
+| Component | File | Export | Props | Client | Lines |
+|-----------|------|--------|-------|--------|-------|
+| DetailActions | DetailActions.tsx | both | DetailActionsProps | Y | 172 |
+| DetailField | DetailField.tsx | both | DetailFieldProps | Y | 91 |
+| DetailFieldSkeleton | DetailFieldSkeleton.tsx | both | DetailFieldSkeletonProps | Y | 48 |
+| DetailGrid | DetailGrid.tsx | both | DetailGridProps | Y | 63 |
+| DetailGridSkeleton | DetailGridSkeleton.tsx | both | DetailGridSkeletonProps | Y | 61 |
+| DetailSection | DetailSection.tsx | both | DetailSectionProps | Y | 97 |
+| DetailSectionSkeleton | DetailSectionSkeleton.tsx | both | DetailSectionSkeletonProps | Y | 53 |
+| DetailSectionSkeleton | skeletons.tsx | both | DetailFieldSkeletonProps | Y | 183 |
+| FieldInput | FieldInput.tsx | both | FieldInputProps | Y | 408 |
+| FieldRenderer | FieldRenderer.tsx | named | FieldRendererProps | Y | 390 |
+| IntegratedListTemplateV2 | IntegratedListTemplateV2.tsx | named | IntegratedListTemplateV2Props | Y | 1087 |
+
+### vehicle-management (3)
+
+| Component | File | Export | Props | Client | Lines |
+|-----------|------|--------|-------|--------|-------|
+| Config | config.tsx | none |  | Y | 431 |
+| Config | config.tsx | none |  | Y | 479 |
+| Config | config.tsx | none |  | Y | 266 |

claudedocs/dashboard/[IMPL-2026-02-11] favorites-feature.md

@@ -0,0 +1,122 @@
+# 즐겨찾기(Favorites) 기능 구현
+
+> 2026-02-11 | 상태: 완료 (localStorage 기반) | 추후: API 전환 예정
+
+## 개요
+
+사이드바 메뉴에 별표(즐겨찾기) 기능을 추가하여 사용자가 자주 쓰는 메뉴를 헤더에 동적으로 표시.
+기존 하드코딩된 종합분석/품질인정심사 버튼을 제거하고 사용자 선택 기반으로 전환.
+
+## 파일 구조
+
+| 파일 | 작업 | 설명 |
+|------|------|------|
+| `src/stores/favoritesStore.ts` | NEW | Zustand persist 스토어 |
+| `src/lib/utils/menuTransform.ts` | MODIFY | reverseIconMap, getIconName, DEFAULT_FAVORITES 추가 |
+| `src/components/layout/HeaderFavoritesBar.tsx` | NEW | 헤더 즐겨찾기 바 (반응형) |
+| `src/components/layout/Sidebar.tsx` | MODIFY | leaf 메뉴에 별표 토글 추가 |
+| `src/layouts/AuthenticatedLayout.tsx` | MODIFY | 하드코딩 버튼 → HeaderFavoritesBar 교체 |
+
+## 핵심 동작
+
+### 즐겨찾기 등록/해제
+- 사이드바 leaf 메뉴(children 없는 항목) hover 시 별표 아이콘 표시
+- 이미 즐겨찾기인 항목은 항상 노란 별표 표시
+- 별표 클릭으로 토글 (메뉴 클릭과 분리 - `e.stopPropagation()`)
+- sidebar collapsed 상태에서는 별표 숨김
+
+### 헤더 표시 (반응형)
+| 조건 | 표시 방식 |
+|------|----------|
+| 데스크톱 (1024px+), 1~8개 | 아이콘 버튼 + Tooltip |
+| 데스크톱 (1024px+), 9~10개 | ★ 드롭다운 |
+| 태블릿 (768~1024px) | ★ 드롭다운 |
+| 모바일 (<768px) | ★ 드롭다운 |
+
+### 제한
+- 최대 **10개**
+- 초과 시 토스트: `즐겨찾기는 최대 10개까지 등록할 수 있습니다.`
+
+### 저장
+- **현재**: localStorage (`sam-favorites-{userId}` 키)
+- Zustand persist 사용, 사용자별 분리 저장
+- 기본값 없음 (사용자가 직접 추가한 것만 표시)
+
+## 주요 구현 상세
+
+### favoritesStore.ts
+```typescript
+interface FavoriteItem {
+  id: string;       // 메뉴 id
+  label: string;    // 메뉴 라벨
+  iconName: string; // 아이콘 문자열 (iconMap 키)
+  path: string;     // 라우트 경로
+  addedAt: number;  // 추가 시각 (정렬용)
+}
+
+// toggleFavorite 반환값으로 토스트 제어
+type ToggleResult = 'added' | 'removed' | 'max_reached';
+```
+
+### menuTransform.ts 확장
+- `reverseIconMap`: iconMap을 뒤집어 `LucideIcon → string` 조회
+- `getIconName(icon)`: 아이콘 컴포넌트 → 문자열 이름 변환
+- `DEFAULT_FAVORITES`: 종합분석 + 품질인정심사 (현재 미사용, 참고용 보관)
+
+### button 중첩 방지
+별표 아이콘은 메뉴 `<button>` 바깥에 배치 (`<div className="group/row">` 래퍼).
+HTML 규격상 `<button>` 안에 `<button>`은 불가 → hydration 에러 유발.
+
+```
+<div class="flex items-center group/row">
+  <button>메뉴 항목</button>     ← 메뉴 클릭
+  <button>★</button>             ← 별표 클릭 (형제 관계)
+</div>
+```
+
+## API 전환 계획
+
+현재 localStorage 기반이라 기기/브라우저별로 동기화되지 않음.
+추후 API 준비되면 스토어 내부만 교체하면 됨.
+
+### 변경 범위
+- `favoritesStore.ts`만 수정 (컴포넌트 수정 불필요)
+
+### 예상 API 엔드포인트
+```
+GET    /api/v1/favorites          → 목록 조회
+POST   /api/v1/favorites          → 추가
+DELETE /api/v1/favorites/{menuId} → 삭제
+```
+
+### 전환 방식
+```typescript
+// Before (localStorage)
+toggleFavorite: (item) => {
+  // Zustand set()으로 localStorage 저장
+}
+
+// After (API)
+toggleFavorite: async (item) => {
+  const exists = get().favorites.some(f => f.id === item.id);
+  if (exists) {
+    await fetch(`/api/v1/favorites/${item.id}`, { method: 'DELETE' });
+  } else {
+    await fetch('/api/v1/favorites', { method: 'POST', body: JSON.stringify(item) });
+  }
+  // 성공 후 로컬 상태 업데이트
+}
+```
+
+### 초기 로딩
+```typescript
+// AuthenticatedLayout useEffect에서
+const res = await fetch('/api/v1/favorites');
+const data = await res.json();
+useFavoritesStore.getState().setFavorites(data);
+```
+
+### 주의사항
+- API 실패 시 localStorage fallback 고려
+- 낙관적 업데이트(optimistic update)로 UX 저하 방지
+- 서버 응답 전에 UI 먼저 반영 → 실패 시 롤백

claudedocs/dev/[FIX-2026-02-09] PDF-이미지-누락-해결.md

@@ -0,0 +1,180 @@
+# [FIX] PDF 변환 시 이미지 누락 문제 해결
+
+**날짜**: 2026-02-09
+**수정 파일**: `src/components/document-system/viewer/DocumentViewer.tsx`
+**영향 범위**: DocumentViewer를 사용하는 모든 문서 (공통 수정)
+
+---
+
+## 문제
+
+중간검사성적서 등 문서에서 **도해 이미지**가 화면에는 정상 표시되지만, **PDF 다운로드 시 이미지가 누락**되는 현상.
+
+## 원인 분석
+
+### PDF 생성 흐름
+
+```
+1. DocumentViewer.handlePdf()
+2. .print-area DOM 요소를 cloneWithInlineStyles()로 복제
+3. clone.outerHTML → HTML 문자열 추출
+4. /api/pdf/generate POST 전송
+5. Puppeteer가 page.setContent(html) → PDF 렌더링
+```
+
+### 핵심 원인: `setContent()`의 base URL 부재
+
+Puppeteer의 `page.setContent(html)`은 **로컬 HTML 문자열을 렌더링**하므로 base URL이 없다.
+
+| 이미지 src 유형 | 브라우저 (화면) | Puppeteer (PDF) |
+|----------------|----------------|-----------------|
+| 상대 경로 `/uploads/img.jpg` | `localhost:3000` 기준으로 해석 | base URL 없음 → 로드 실패 |
+| 절대 URL `https://api.example.com/img.jpg` | 정상 로드 | 서버 네트워크 환경에 따라 실패 가능 |
+| Blob URL `blob:http://...` | 브라우저 메모리 참조 | Puppeteer 컨텍스트에 없음 → 로드 실패 |
+| Data URL `data:image/png;base64,...` | 정상 | 정상 (HTML에 내장) |
+
+**결론**: `<img src="...">` 가 상대/절대/blob URL이면 Puppeteer PDF에서 이미지가 빠진다.
+
+## 해결 방법
+
+### 접근: 이미지를 base64 data URL로 인라인 변환
+
+PDF API로 HTML을 보내기 **전에**, 모든 `<img>` 태그의 `src`를 **base64 data URL로 변환**하여 HTML 자체에 이미지를 내장시킨다.
+
+### 구현: `convertImagesToBase64()`
+
+```typescript
+// DocumentViewer.tsx에 추가
+const convertImagesToBase64 = async (original: HTMLElement, clone: HTMLElement): Promise<void> => {
+  const originalImages = Array.from(original.querySelectorAll('img'));
+  const clonedImages = Array.from(clone.querySelectorAll('img'));
+
+  await Promise.all(
+    originalImages.map(async (img, index) => {
+      const clonedImg = clonedImages[index];
+      if (!clonedImg) return;
+
+      const src = img.src;
+      if (!src || src.startsWith('data:')) return; // 이미 data URL이면 스킵
+
+      try {
+        // 1차: fetch → blob → FileReader → dataURL
+        const response = await fetch(src);
+        const blob = await response.blob();
+        const dataUrl = await new Promise<string>((resolve, reject) => {
+          const reader = new FileReader();
+          reader.onloadend = () => resolve(reader.result as string);
+          reader.onerror = reject;
+          reader.readAsDataURL(blob);
+        });
+        clonedImg.setAttribute('src', dataUrl);
+      } catch {
+        // 2차 fallback: canvas 방식
+        try {
+          if (img.complete && img.naturalWidth > 0) {
+            const canvas = document.createElement('canvas');
+            canvas.width = img.naturalWidth;
+            canvas.height = img.naturalHeight;
+            const ctx = canvas.getContext('2d');
+            if (ctx) {
+              ctx.drawImage(img, 0, 0);
+              clonedImg.setAttribute('src', canvas.toDataURL('image/png'));
+            }
+          }
+        } catch {
+          // 변환 실패 시 원본 src 유지
+        }
+      }
+    })
+  );
+};
+```
+
+### 호출 위치: `handlePdf()` 내부
+
+```typescript
+// 변경 전
+const clonedElement = cloneWithInlineStyles(printAreaEl);
+const html = clonedElement.outerHTML;
+
+// 변경 후
+const clonedElement = cloneWithInlineStyles(printAreaEl);
+await convertImagesToBase64(printAreaEl, clonedElement);  // 이미지 인라인 변환
+const html = clonedElement.outerHTML;
+```
+
+## 영향 범위 (공통 적용)
+
+`DocumentViewer`가 모든 문서의 PDF 생성을 담당하므로, **1곳 수정으로 전체 해결**:
+
+| 화면 | 이미지 필드 | 적용 |
+|------|------------|------|
+| 스크린 중간검사 | `schematicImage` (도해) | 자동 적용 |
+| 슬랫 중간검사 | `schematicImage` (도해) | 자동 적용 |
+| 조인트바 중간검사 | `schematicImage` (도해) | 자동 적용 |
+| 절곡 중간검사 | `schematicImage` (도해) | 자동 적용 |
+| 절곡 재공품 중간검사 | `schematicImage` (도해) | 자동 적용 |
+| 제품검사 성적서 (품질) | `productImages` | 자동 적용 |
+| 기타 DocumentViewer 문서 | 모든 `<img>` | 자동 적용 |
+
+## 변환 전략 우선순위
+
+```
+1. data URL → 스킵 (이미 인라인)
+2. fetch → blob → FileReader → dataURL (동일 출처, CORS 허용)
+3. canvas drawImage → toDataURL (로컬 이미지 fallback)
+4. 실패 시 원본 src 유지 (graceful degradation)
+```
+
+---
+
+## 미해결: 도해 이미지 데이터 파이프라인 (2026-02-09 확인)
+
+### 현재 상황
+
+PDF 변환(파이프 끝)은 수정 완료했으나, **데이터 주입(파이프 시작)이 연결되지 않은 상태**.
+
+```
+[백엔드 설정 사이트]          [sam-api]              [프론트엔드]
+ 도해 이미지 업로드    →   inspection_setting?  →   inspectionSetting
+ 검사기준 설정               (❌ 미구현)            schematicImage
+                                                        ↓
+                                                   DocumentViewer
+                                                        ↓
+                                                   PDF (base64 변환 ✅)
+```
+
+### 백엔드 API 확인 결과
+
+| 항목 | 상태 |
+|------|------|
+| `ProcessStep` 테이블에 `inspection_setting` 컬럼 | ❌ 없음 |
+| `ApiProcessStep` → `inspectionSetting` 매핑 | ❌ 없음 |
+| 검사 설정 위치 | Process 레벨 `DocumentTemplate`으로 최근(2/10~11) 이동 |
+| 도해 이미지 URL 필드 | ❌ 백엔드에 미정의 |
+
+### 프론트 vs 백엔드 구조 불일치
+
+| 항목 | 프론트엔드 기대 | 백엔드 실제 |
+|------|----------------|-------------|
+| 위치 | `step.inspectionSetting` | `process.documentTemplate` |
+| 구조 | `{ standardName, schematicImage, appearance, dimension }` | DocumentTemplate (sections, fields) |
+| 이미지 | `schematicImage` 직접 필드 | 없음 |
+
+### 프론트 누락 코드 (합치고 나서 수정 필요)
+
+**`src/components/process-management/actions.ts`**:
+- `ApiProcessStep` 인터페이스에 `inspection_setting` 필드 미정의 (line 582)
+- `transformStepApiToFrontend()`에서 `inspectionSetting` 매핑 안 함 (line 599)
+
+### 해결 방향
+
+백엔드 머지 후 아래 중 하나로 진행:
+
+| 옵션 | 내용 | 수정 위치 |
+|------|------|----------|
+| A | ProcessStep에 `inspection_setting` JSON 컬럼 추가 | 백엔드 |
+| B | API에서 DocumentTemplate → InspectionSetting 변환하여 내려주기 | 백엔드 |
+| C | 프론트에서 `process.documentTemplate` 직접 사용하도록 변경 | 프론트 |
+
+**백엔드 담당자와 구조 협의 필요.**

claudedocs/dev/[PLAN-2026-02-03] claude-config-optimization.md

@@ -0,0 +1,163 @@
+# Claude 설정 최적화 계획
+
+**날짜**: 2026-02-03
+**목적**: 토큰 효율성 개선 + 규칙 분리 + 자동화 강화
+
+---
+
+## 배경 (왜 이 작업을 하는가?)
+
+### 문제 발견
+- `~/.claude/` 에 **16개 MD 파일 (3,549줄, ~119KB)** 가 매 대화마다 전부 로드됨
+- SAM 프로젝트 전용 규칙이 글로벌에 있어 다른 프로젝트에도 불필요하게 전파
+- 비즈니스 분석용 파일(BUSINESS_PANEL, RESEARCH_CONFIG 등)이 일상 개발에도 로드
+- type-check 같은 프로세스가 MD 규칙으로만 존재 → 강제성 없음
+
+### 기대 효과
+- 매 대화 토큰 사용량 감소 (불필요한 ~1,500줄 절약)
+- SAM 규칙과 범용 규칙의 명확한 분리
+- type-check 자동화로 실수 방지 강화
+
+---
+
+## 작업 계획
+
+### 1단계: 프로젝트 CLAUDE.md 분리
+**상태**: 🔄 진행 중
+
+**작업 내용**:
+- `~/.claude/RULES.md`에서 SAM 전용 규칙 추출
+- 프로젝트 루트에 `CLAUDE.md` 생성 (SAM 전용 규칙)
+- 글로벌 `RULES.md`는 범용 규칙만 남김
+
+**SAM 전용으로 분류된 규칙들** (프로젝트 CLAUDE.md로 이동):
+| 섹션 | 이유 |
+|------|------|
+| Common Table Standards | SAM ERP 테이블 패턴 |
+| Document Table Merging | SAM 성적서/보고서 전용 |
+| Page Layout Standards | SAM AuthenticatedLayout 구조 |
+| Design Popup Policy | SAM Radix UI 스택 |
+| Build Policy | SAM 빌드 정책 |
+| Client Component 사용 원칙 | SAM 폐쇄형 ERP 특성 |
+| SAM Project Structure | SAM 경로 구조 |
+| Backend API Analysis Policy | SAM 백엔드 연동 |
+| Test URL Documentation Rules | SAM 테스트 URL |
+| User Environment Knowledge | 사용자 환경 특화 |
+| HttpOnly Cookie API Communication | SAM 인증 패턴 |
+| Radix UI Select Bug | SAM 기술 스택 이슈 |
+| React → Next.js Migration | SAM 마이그레이션 |
+| Large File Migration Workflow | SAM 마이그레이션 |
+| Component Pattern Reuse | SAM 컴포넌트 패턴 |
+| 기획서/스크린샷 기반 UI 구현 | SAM 기획서 프로세스 |
+
+**글로벌에 남는 규칙들** (범용):
+| 섹션 | 이유 |
+|------|------|
+| Priority System | 모든 프로젝트 공통 |
+| Scope Discipline (일반 부분) | 모든 프로젝트 공통 |
+| Implementation Completeness | 모든 프로젝트 공통 |
+| Failure Investigation | 모든 프로젝트 공통 |
+| Professional Honesty | 모든 프로젝트 공통 |
+| Safety Rules | 모든 프로젝트 공통 |
+| Workflow & Session | 모든 프로젝트 공통 |
+| File & Code Organization | 모든 프로젝트 공통 |
+| Workspace Hygiene | 모든 프로젝트 공통 |
+| Git Rules | 모든 프로젝트 공통 |
+| Claude-Specific Rules | 모든 프로젝트 공통 |
+| Quick Reference | 모든 프로젝트 공통 |
+
+---
+
+### 2단계: 가끔 쓰는 MD 파일 임포트 해제
+**상태**: ⏳ 대기
+
+**작업 내용**:
+- `~/.claude/CLAUDE.md`에서 `@` 임포트 줄 제거 (파일 자체는 유지)
+
+**제거 대상 임포트** (일상 SAM 개발에 불필요):
+| 파일 | 줄 수 | 용도 |
+|------|-------|------|
+| @BUSINESS_PANEL_EXAMPLES.md | 278줄 | /sc:business-panel 전용 |
+| @BUSINESS_SYMBOLS.md | 211줄 | /sc:business-panel 전용 |
+| @MODE_Business_Panel.md | 334줄 | /sc:business-panel 전용 |
+| @RESEARCH_CONFIG.md | 445줄 | /sc:research 전용 |
+| @MODE_DeepResearch.md | 57줄 | /sc:research 전용 |
+| @MODE_Brainstorming.md | 43줄 | 가끔 사용 |
+| @MODE_Introspection.md | 38줄 | 거의 안 씀 |
+| @MODE_Token_Efficiency.md | 74줄 | 컨텍스트 압박 시만 |
+| **합계** | **~1,480줄** | **절약** |
+
+**유지 대상 임포트**:
+| 파일 | 이유 |
+|------|------|
+| @PRINCIPLES.md | 핵심 엔지니어링 원칙 |
+| @RULES.md | 범용 행동 규칙 |
+| @GIT_POLICY.md | Git 워크플로우 |
+| @FLAGS.md | 모드 활성화 플래그 |
+| @MODE_Task_Management.md | 멀티스텝 작업 관리 |
+| @MODE_Orchestration.md | 도구 선택 최적화 |
+
+---
+
+### 3단계: Hooks 추가
+**상태**: ⏳ 대기
+
+**작업 내용**:
+- `.claude/settings.local.json`에 PostToolUse hook 추가
+- Write/Edit 후 자동 `npx tsc --noEmit` 실행
+
+---
+
+### 4단계: 중복 제거
+**상태**: ⏳ 대기
+
+**작업 내용**:
+- RULES.md의 "Git Rules" 섹션과 GIT_POLICY.md 간 중복 정리
+- RULES.md에는 "git 올려줘" 단축 명령 + 기본 원칙만 남김
+- 상세 브랜치 전략/커밋 규칙은 GIT_POLICY.md로 통합
+- COMPLEX_TASK_PROTOCOL.md는 RULES.md의 Checklist-Driven Development와 중복 → 정리
+
+---
+
+## 진행 기록
+
+| 단계 | 상태 | 완료일 | 비고 |
+|------|------|--------|------|
+| 1단계: 프로젝트 CLAUDE.md 분리 | ✅ | 2026-02-03 | SAM 전용 16개 섹션 이동 |
+| 2단계: MD 임포트 해제 | ✅ | 2026-02-03 | 9개 파일 임포트 해제 (~1,759줄) |
+| 3단계: Hooks 추가 | ✅ | 2026-02-03 | PostToolUse typecheck hook |
+| 4단계: 중복 제거 | ✅ | 2026-02-03 | GIT_POLICY.md에서 87줄 중복 제거 |
+
+---
+
+## 최종 결과
+
+### 토큰 절약 수치
+```
+변경 전: 3,549줄 (전부 글로벌, 매 대화 로드)
+변경 후: 1,193줄 (글로벌 916 + 프로젝트 277)
+절약량:  2,356줄 (~66% 감소)
+```
+
+### 다른 프로젝트에서의 효과
+```
+변경 전: 3,549줄 (SAM 규칙 포함)
+변경 후:   916줄 (범용 규칙만)
+절약량:  2,633줄 (~74% 감소)
+```
+
+### 변경된 파일 목록
+| 파일 | 작업 |
+|------|------|
+| `프로젝트/CLAUDE.md` | 신규 생성 (SAM 전용 규칙) |
+| `~/.claude/CLAUDE.md` | 임포트 9개 해제 |
+| `~/.claude/RULES.md` | SAM 규칙 제거 (1017→258줄) |
+| `~/.claude/GIT_POLICY.md` | 중복 섹션 제거 (394→307줄) |
+| `.claude/hooks/typecheck-after-edit.sh` | 신규 생성 |
+| `.claude/settings.local.json` | hooks 설정 추가 |
+
+### Hook 동작 방식
+- **트리거**: Write/Edit 도구 사용 후
+- **대상**: .ts/.tsx 파일만
+- **실행**: `npx tsc --noEmit` (30초 타임아웃)
+- **에러 시**: Claude에 타입 에러 피드백 → 자동 수정 시도

claudedocs/dev/[REF-2026-02-19] todo-issue-tracker.md

@@ -0,0 +1,342 @@
+# SAM ERP TODO/FIXME 이슈 트래커
+
+> 자동 생성: 2026-02-19
+> 총 건수: 102건
+> 분류: A~F 카테고리
+> 검색 범위: `src/` 디렉토리 내 `*.ts`, `*.tsx` 파일
+
+---
+
+## 요약
+
+| 카테고리 | 건수 | 담당 | 비고 |
+|----------|------|------|------|
+| A. 백엔드 API 연동 대기 | 55 | 백엔드팀 | API 완성 시 해결 |
+| B. 백엔드 필드 추가 대기 | 10 | 백엔드팀 | DB/API 스키마 추가 |
+| C. UI/기능 구현 대기 | 16 | 프론트팀 | 백로그 |
+| D. Phase 2 / 장기 과제 | 10 | 전체 | 로드맵 반영 |
+| E. CEO 대시보드 목업 데이터 | 4 | 프론트팀 | 대시보드 API 연동 시 |
+| F. 기타 | 7 | - | - |
+
+---
+
+## A. 백엔드 API 연동 대기 (55건)
+
+### 모듈별 분류
+
+#### 품목기준관리 (Item Master Store) - 16건
+
+| 파일 | 라인 | TODO 내용 |
+|------|------|----------|
+| `src/stores/item-master/useItemMasterStore.ts` | 97 | `// TODO: API 호출` (createPage - 페이지 생성) |
+| `src/stores/item-master/useItemMasterStore.ts` | 160 | `// TODO: API 호출` (updatePage - 페이지 수정) |
+| `src/stores/item-master/useItemMasterStore.ts` | 214 | `// TODO: API 호출` (deletePage - 페이지 삭제) |
+| `src/stores/item-master/useItemMasterStore.ts` | 289 | `// TODO: API 호출` (createSection - 섹션 생성) |
+| `src/stores/item-master/useItemMasterStore.ts` | 335 | `// TODO: API 호출` (updateSection - 섹션 수정) |
+| `src/stores/item-master/useItemMasterStore.ts` | 370 | `// TODO: API 호출` (deleteSection - 섹션 삭제) |
+| `src/stores/item-master/useItemMasterStore.ts` | 423 | `// TODO: API 호출하여 서버에도 순서 저장` (reorderSections) |
+| `src/stores/item-master/useItemMasterStore.ts` | 460 | `// TODO: API 호출` (createField - 필드 생성) |
+| `src/stores/item-master/useItemMasterStore.ts` | 522 | `// TODO: API 호출` (updateField - 필드 수정) |
+| `src/stores/item-master/useItemMasterStore.ts` | 552 | `// TODO: API 호출` (deleteField - 필드 삭제) |
+| `src/stores/item-master/useItemMasterStore.ts` | 587 | `// TODO: API 호출` (updateFieldOptions - 필드 옵션 수정) |
+| `src/stores/item-master/useItemMasterStore.ts` | 640 | `// TODO: API 호출하여 서버에도 순서 저장` (reorderFields) |
+| `src/stores/item-master/useItemMasterStore.ts` | 677 | `// TODO: API 호출` (createTab - 탭 생성) |
+| `src/stores/item-master/useItemMasterStore.ts` | 707 | `// TODO: API 호출` (updateTab - 탭 수정) |
+| `src/stores/item-master/useItemMasterStore.ts` | 726 | `// TODO: API 호출` (deleteTab - 탭 삭제) |
+| `src/components/items/ItemMasterDataManagement/hooks/usePageManagement.ts` | 157 | `// TODO: 원본 페이지의 섹션들도 복제 필요 (별도 API 호출)` |
+
+#### 회계 (Accounting) - 19건
+
+| 파일 | 라인 | TODO 내용 |
+|------|------|----------|
+| `src/components/accounting/GiftCertificateManagement/actions.ts` | 32 | `// TODO: 실제 API 연동 시 교체` (getGiftCertificates) |
+| `src/components/accounting/GiftCertificateManagement/actions.ts` | 45 | `// TODO: 실제 API 연동 시 교체` (getGiftCertificateDetail) |
+| `src/components/accounting/GiftCertificateManagement/actions.ts` | 58 | `// TODO: 실제 API 연동 시 교체` (createGiftCertificate) |
+| `src/components/accounting/GiftCertificateManagement/actions.ts` | 86 | `// TODO: 실제 API 연동 시 교체` (updateGiftCertificate) |
+| `src/components/accounting/GiftCertificateManagement/actions.ts` | 113 | `// TODO: 실제 API 연동 시 교체` (deleteGiftCertificate) |
+| `src/components/accounting/GiftCertificateManagement/actions.ts` | 136 | `// TODO: 실제 API 연동 시 교체` (useGiftCertificate) |
+| `src/components/accounting/TaxInvoiceManagement/actions.ts` | 24 | `// TODO: 실제 API 연동 시 Mock 제거` (Mock 데이터) |
+| `src/components/accounting/TaxInvoiceManagement/actions.ts` | 44 | `// TODO: 실제 API 연동 시 아래 코드로 교체` (getTaxInvoices) |
+| `src/components/accounting/TaxInvoiceManagement/actions.ts` | 66 | `// TODO: 실제 API 연동 시 아래 코드로 교체` (getTaxInvoiceDetail) |
+| `src/components/accounting/TaxInvoiceManagement/actions.ts` | 99 | `// TODO: 실제 API 연동 시 Mock 제거` (세금계산서 상세) |
+| `src/components/accounting/TaxInvoiceManagement/actions.ts` | 115 | `// TODO: 실제 API 연동 시 아래 코드로 교체` (deleteTaxInvoice) |
+| `src/components/accounting/TaxInvoiceIssuance/actions.ts` | 36 | `// TODO: 실제 API 연동 시 아래 코드로 교체` (getTaxInvoices) |
+| `src/components/accounting/TaxInvoiceIssuance/actions.ts` | 59 | `// TODO: 실제 API 연동 시 아래 코드로 교체` (getTaxInvoiceDetail) |
+| `src/components/accounting/TaxInvoiceIssuance/actions.ts` | 86 | `// TODO: 실제 API 연동 시 아래 코드로 교체` (issueTaxInvoice) |
+| `src/components/accounting/TaxInvoiceIssuance/actions.ts` | 112 | `// TODO: 실제 API 연동 시 아래 코드로 교체` (sendEmail) |
+| `src/components/accounting/TaxInvoiceIssuance/actions.ts` | 127 | `// TODO: 실제 API 연동 시 교체` (cancelTaxInvoice) |
+| `src/components/accounting/TaxInvoiceIssuance/index.tsx` | 184 | `// TODO: 실제 API 연동 시 필터 조건으로 getTaxInvoices 호출` |
+| `src/components/accounting/PurchaseManagement/index.tsx` | 232 | `// TODO: API 호출로 저장` |
+| `src/components/accounting/SalesManagement/index.tsx` | 270 | `// TODO: API 호출로 저장` |
+
+#### 건설/사업 (Construction/Business) - 9건
+
+| 파일 | 라인 | TODO 내용 |
+|------|------|----------|
+| `src/components/business/construction/progress-billing/actions.ts` | 196 | `// TODO: 실제 API 호출로 대체` (getProgressBillings) |
+| `src/components/business/construction/progress-billing/actions.ts` | 230 | `// TODO: 실제 API 호출로 대체` (getProgressBillingDetail) |
+| `src/components/business/construction/progress-billing/actions.ts` | 263 | `// TODO: 실제 API 호출로 대체` (saveProgressBilling) |
+| `src/components/business/construction/progress-billing/actions.ts` | 292 | `// TODO: 실제 API 호출로 대체` (deleteProgressBilling) |
+| `src/components/business/construction/progress-billing/actions.ts` | 300 | `// TODO: 매출 자동 등록 API 호출` |
+| `src/components/business/construction/progress-billing/hooks/useProgressBillingDetailForm.ts` | 92 | `// TODO: API 호출` (handleSave) |
+| `src/components/business/construction/progress-billing/hooks/useProgressBillingDetailForm.ts` | 111 | `// TODO: API 호출` (handleDelete) |
+| `src/components/business/construction/progress-billing/ProgressBillingDetailForm.tsx` | 77 | `// TODO: API 호출` (handleDelete) |
+| `src/components/business/construction/management/actions.ts` | 20 | `// TODO: 실제 API 연동 시 구현` (프로젝트 관리 전체) |
+
+#### 건설/현장관리 (Site Management) - 4건
+
+| 파일 | 라인 | TODO 내용 |
+|------|------|----------|
+| `src/components/business/construction/structure-review/StructureReviewDetailForm.tsx` | 154 | `// TODO: API 연동` (handleSave) |
+| `src/components/business/construction/structure-review/StructureReviewDetailClientV2.tsx` | 76 | `// TODO: API 연동` (handleSave) |
+| `src/components/business/construction/site-management/SiteDetailForm.tsx` | 156 | `// TODO: API 연동` (handleSave) |
+| `src/components/business/construction/site-management/SiteDetailClientV2.tsx` | 68 | `// TODO: API 연동` (handleSave) |
+
+#### HR (인사관리) - 2건
+
+| 파일 | 라인 | TODO 내용 |
+|------|------|----------|
+| `src/app/[locale]/(protected)/hr/documents/page.tsx` | 73 | `// TODO: 백엔드 API 구현 필요` (인사서류함) |
+| `src/app/[locale]/(protected)/hr/documents/new/page.tsx` | 91 | `// TODO: 백엔드 API 구현 필요` (인사서류 신규등록) |
+
+#### 생산 (Production) - 2건
+
+| 파일 | 라인 | TODO 내용 |
+|------|------|----------|
+| `src/components/production/WorkOrders/WipProductionModal.tsx` | 106 | `// TODO: API 연동` (WIP 생산 모달) |
+| `src/app/[locale]/(protected)/quality/qms/components/InspectionModal.tsx` | 340 | `// TODO: 실제 저장 API 연동` (품질검사 저장) |
+
+#### 게시판 (Board) - 2건
+
+| 파일 | 라인 | TODO 내용 |
+|------|------|----------|
+| `src/components/board/BoardDetail/index.tsx` | 85 | `// TODO: 댓글 API 연동 (별도 작업)` |
+| `src/app/[locale]/(protected)/board/[boardCode]/[postId]/page.tsx` | 45 | `// TODO: 댓글 API 호출 추가` |
+
+#### 설정 (Settings) - 1건
+
+| 파일 | 라인 | TODO 내용 |
+|------|------|----------|
+| `src/components/settings/AttendanceSettingsManagement/index.tsx` | 18 | `// TODO: API 연동 시 작업 사항 - GET/PUT /api/settings/attendance` |
+
+---
+
+## B. 백엔드 필드 추가 대기 (10건)
+
+### 모듈별 분류
+
+#### 대시보드 트랜스포머 - 3건
+
+| 파일 | 라인 | TODO 내용 |
+|------|------|----------|
+| `src/lib/api/dashboard/transformers.ts` | 261 | `// TODO: 백엔드 daily_change 필드 제공 시 더미값 제거` |
+| `src/lib/api/dashboard/transformers.ts` | 427 | `// TODO: 백엔드 per-card sub_label/count 제공 시 더미값 제거` |
+| `src/lib/api/dashboard/transformers.ts` | 654 | `// TODO: 백엔드 sub_label 필드 제공 시 더미값 제거` |
+
+#### 공정관리 (Process Management) - 3건
+
+| 파일 | 라인 | TODO 내용 |
+|------|------|----------|
+| `src/components/process-management/actions.ts` | 486 | `// TODO: API 응답에 process_name, process_category 필드 추가 후 활성화` |
+| `src/components/process-management/RuleModal.tsx` | 285 | `// TODO: API에서 process_name, process_category 필드 지원 후 실제 데이터 표시` |
+| `src/components/process-management/RuleModal.tsx` | 322 | `// TODO: API 지원 후 item.processName / item.processCategory 표시` |
+
+#### 생산 (Production) - 2건
+
+| 파일 | 라인 | TODO 내용 |
+|------|------|----------|
+| `src/components/production/WorkOrders/WorkOrderList.tsx` | 181 | `// TODO: API에서 긴급 건수 제공 시 연동` |
+| `src/components/production/WorkOrders/WorkOrderList.tsx` | 187 | `// TODO: API에서 지연 건수 제공 시 연동` |
+
+#### 게시판 (Board) - 2건
+
+| 파일 | 라인 | TODO 내용 |
+|------|------|----------|
+| `src/components/board/BoardManagement/BoardForm.tsx` | 24 | `// TODO: API에서 부서 목록 가져오기` |
+| `src/components/board/BoardManagement/BoardForm.tsx` | 33 | `// TODO: API에서 권한 목록 가져오기` |
+
+---
+
+## C. UI/기능 구현 대기 (16건)
+
+### 모듈별 분류
+
+#### 다운로드/출력 기능 - 4건
+
+| 파일 | 라인 | TODO 내용 |
+|------|------|----------|
+| `src/components/accounting/BadDebtCollection/BadDebtDetail.tsx` | 268 | `// TODO: 실제 다운로드 로직` |
+| `src/app/[locale]/(protected)/quality/qms/components/Day1DocumentSection.tsx` | 149 | `// TODO: 다운로드 기능` |
+| `src/app/[locale]/(protected)/quality/qms/components/InspectionModal.tsx` | 472 | `// 다운로드 핸들러 (TODO: 실제 구현)` |
+| `src/components/material/ReceivingManagement/ReceivingReceiptDialog.tsx` | 23 | `// TODO: PDF 다운로드 기능` |
+
+#### 품목 (Items) - 4건
+
+| 파일 | 라인 | TODO 내용 |
+|------|------|----------|
+| `src/components/items/ItemForm/BOMSection.tsx` | 115 | `// TODO: 실제 itemMasters 데이터로 교체 필요` |
+| `src/components/items/ItemForm/BOMSection.tsx` | 196 | `// TODO: 품목 선택 시 데이터 채우기 로직` |
+| `src/components/items/ItemForm/BOMSection.tsx` | 209 | `// TODO: pricing에서 가져오기` (unitPrice) |
+| `src/components/items/ItemForm/hooks/useBOMManagement.ts` | 89 | `// TODO: pricing에서 가져오기` (unitPrice) |
+
+#### 생산 (Production) - 3건
+
+| 파일 | 라인 | TODO 내용 |
+|------|------|----------|
+| `src/components/production/WorkOrders/WorkOrderEdit.tsx` | 277 | `// TODO: API 호출로 서버에 상태 저장` |
+| `src/components/production/WorkOrders/WorkOrderEdit.tsx` | 310 | `// TODO: API 호출로 서버에 저장` |
+| `src/components/production/WorkOrders/WorkOrderEdit.tsx` | 327 | `// TODO: API 호출로 서버에서 삭제` |
+
+#### 기타 기능 - 5건
+
+| 파일 | 라인 | TODO 내용 |
+|------|------|----------|
+| `src/components/approval/DocumentDetail/index.tsx` | 161 | `// TODO: 공유 기능 추가 예정 - PDF 다운로드, 이메일, 팩스, 카카오톡 공유` |
+| `src/components/pricing/PricingListClient.tsx` | 177 | `// TODO: 이력 다이얼로그 열기` |
+| `src/components/pricing/PricingListClient.tsx` | 335 | `// TODO: API 연동 시 품목 마스터 동기화 로직 구현` |
+| `src/components/hr/SalaryManagement/index.tsx` | 253 | `// TODO: 지급항목 추가 다이얼로그 또는 로직 구현` |
+| `src/components/production/WorkResults/WorkResultList.tsx` | 70 | `// TODO: 상세 보기 기능 구현` |
+
+---
+
+## D. Phase 2 / 장기 과제 (10건)
+
+### 모듈별 분류
+
+#### 품목코드 생성 로직 개선 - 3건
+
+| 파일 | 라인 | TODO 내용 |
+|------|------|----------|
+| `src/components/items/DynamicItemForm/utils/itemCodeGenerator.ts` | 11 | `// TODO: 추후 백엔드 API 또는 품목기준관리에서 설정 가능하도록 변경` |
+| `src/components/items/DynamicItemForm/utils/itemCodeGenerator.ts` | 52 | `// TODO: 추후 품목기준관리에서 설정 가능하도록 변경` |
+| `src/components/items/DynamicItemForm/utils/itemCodeGenerator.ts` | 98 | `// TODO: 추후 품목기준관리에서 설정 가능하도록 변경` |
+
+#### 품목기준관리 하드코딩 대체 - 2건
+
+| 파일 | 라인 | TODO 내용 |
+|------|------|----------|
+| `src/components/items/ItemMasterDataManagement/hooks/useTabManagement.ts` | 104 | `// TODO: 나중에 백엔드에서 기준값 로드로 대체 예정` |
+| `src/components/items/ItemMasterDataManagement/hooks/useAttributeManagement.ts` | 80 | `// TODO: 나중에 백엔드 API로 대체` (속성 옵션 하드코딩) |
+
+#### 프로덕션 배포 준비 - 2건
+
+| 파일 | 라인 | TODO 내용 |
+|------|------|----------|
+| `src/lib/api/toast-utils.ts` | 14 | `// TODO: 프로덕션 배포 시 false로 변경하거나 환경변수 사용` (SHOW_ERROR_CODE) |
+| `src/lib/api/error-handler.ts` | 112 | `// TODO: 프로덕션 배포 시 false로 변경하거나 환경변수 사용` (SHOW_ERROR_CODE) |
+
+#### Phase 2 명시 - 2건
+
+| 파일 | 라인 | TODO 내용 |
+|------|------|----------|
+| `src/lib/api/item-master.ts` | 99 | `// TODO: Phase 2에서 구현` |
+| `src/components/document-system/viewer/DocumentViewer.tsx` | 314 | `// TODO: BlockRenderer 구현 시 연결` (Phase 2 블록 렌더링) |
+
+#### 기타 장기 - 1건
+
+| 파일 | 라인 | TODO 내용 |
+|------|------|----------|
+| `src/lib/api/items.ts` | 26 | `// TODO: 실제 인증 구현에 맞게 수정 필요` (getAuthToken) |
+
+---
+
+## E. CEO 대시보드 목업 데이터 (4건)
+
+| 파일 | 라인 | TODO 내용 |
+|------|------|----------|
+| `src/components/business/CEODashboard/mockData.ts` | 5 | `// TODO: API 연동 시 이 파일을 API 호출로 대체` |
+| `src/components/business/CEODashboard/CEODashboard.tsx` | 253 | `// TODO: API 호출하여 일정 저장` |
+| `src/components/business/CEODashboard/CEODashboard.tsx` | 260 | `// TODO: API 호출하여 일정 삭제` |
+| `src/components/business/CEODashboard/sections/TodayIssueSection.tsx` | 411 | `// TODO: 버튼 - API 구현 후 활성화` (승인/반려 버튼) |
+
+---
+
+## F. 기타 (7건)
+
+| 파일 | 라인 | TODO 내용 | 비고 |
+|------|------|----------|------|
+| `src/contexts/ItemMasterContext.tsx` | 1894 | `// TODO: 전체 init 데이터 새로고침 기능 구현 필요` | 리팩토링 |
+| `src/components/document-system/configs/index.ts` | 10 | `// TODO: Orders Configs` | 설정 추가 대기 |
+| `src/components/quotes/types.ts` | 737 | `// TODO: 동적으로 결정` (productCategory) | 로직 개선 |
+| `src/components/quotes/types.ts` | 875 | `// TODO: 동적으로 결정` (product_category) | 로직 개선 |
+| `src/components/production/WorkOrders/types.ts` | 516 | `// TODO: 실제 단계 추적 필요` (in_progress 상태) | 로직 개선 |
+| `src/components/items/ItemListClient.tsx` | 328 | `// TODO: 실제 API 호출로 데이터 저장` | API 연동 겸 로직 |
+| `src/components/business/construction/management/ProjectListClient.tsx` | 127 | `// TODO: 실제 API 연동 시 new Date()로 변경` (목업 데이터 임시 설정) | 목업 제거 |
+| `src/components/accounting/BadDebtCollection/BadDebtDetail.tsx` | 53 | `// TODO: API에서 조회` (담당자 목록 하드코딩) | API 연동 겸 데이터 |
+| `src/components/settings/CompanyInfoManagement/AddCompanyDialog.tsx` | 60 | `// TODO: 바로빌 API 연동` (외부 API) | 외부 서비스 연동 |
+| `src/components/accounting/SalesManagement/SalesDetail.tsx` | 500 | `// TODO: 거래명세서 조회 기능 연결` | 기능 연결 |
+| `src/app/[locale]/(protected)/hr/employee-management/csv-upload/page.tsx` | 8 | `// TODO: API 연동` (CSV 업로드) | API 연동 |
+| `src/app/[locale]/(protected)/hr/attendance/page.tsx` | 67 | `// TODO: 주소/좌표 설정 UI 추가 후 아래 주석 해제` | UI 추가 후 |
+| `src/components/business/construction/estimates/sections/EstimateDetailTableSection.tsx` | 224 | `// TODO: 견적 상세 기획서 수정 후 초기화 버튼 및 테이블 항목/데이터 재작업 필요` | 기획 대기 |
+| `src/components/material/ReceivingManagement/InspectionCreate.tsx` | 164 | `// TODO: API 호출` (검사 생성) | API 연동 |
+| `src/components/process-management/actions.ts` | 503 | `// TODO: 백엔드 API 수정 요청 - process_name, process_category 필드 추가` | 백엔드 요청 문서 |
+
+> 참고: F 카테고리는 A~E에 명확히 분류되지 않는 항목을 포함합니다. 일부는 API 연동과 겹치지만 외부 서비스, 기획 대기, 로직 개선 등 복합적인 성격을 가집니다.
+
+---
+
+## 백엔드 팀 전달 요약 (A + B = 65건)
+
+### 우선순위별 정리
+
+#### 즉시 필요 (Critical) - 완전 Mock 상태
+
+아래 모듈은 **전체 API가 Mock/로컬로 구현**되어 있어 백엔드 API 완성 즉시 교체 필요:
+
+| 모듈 | 건수 | actions.ts 파일 |
+|------|------|-----------------|
+| 상품권 관리 | 6 | `accounting/GiftCertificateManagement/actions.ts` |
+| 세금계산서 관리 | 5 | `accounting/TaxInvoiceManagement/actions.ts` |
+| 세금계산서 발행 | 6 | `accounting/TaxInvoiceIssuance/actions.ts` |
+| 기성관리 | 5+3 | `construction/progress-billing/actions.ts` + hooks |
+| 프로젝트관리 | 1 | `construction/management/actions.ts` (전체 Mock) |
+| 품목기준관리 스토어 | 16 | `stores/item-master/useItemMasterStore.ts` |
+
+**소계: 42건** - 이 모듈들은 프론트엔드 UI는 완성되었으나 백엔드 API 미구현 상태
+
+#### 필드 추가 요청 (Important)
+
+| 요청 대상 | 추가 필드 | 관련 파일 |
+|-----------|----------|----------|
+| CEO 대시보드 API | `daily_change`, `sub_label`, `count` | `lib/api/dashboard/transformers.ts` |
+| 공정관리 품목 API | `process_name`, `process_category` | `process-management/actions.ts`, `RuleModal.tsx` |
+| 작업지시 API | 긴급 건수, 지연 건수 | `WorkOrders/WorkOrderList.tsx` |
+| 게시판 관리 API | 부서 목록, 권한 목록 | `board/BoardManagement/BoardForm.tsx` |
+
+**소계: 10건**
+
+#### 신규 API 필요 (Normal)
+
+| API | 용도 | 관련 파일 |
+|-----|------|----------|
+| 인사서류함 CRUD | HR 문서 관리 | `hr/documents/page.tsx`, `new/page.tsx` |
+| 댓글 CRUD | 게시판 댓글 | `BoardDetail/index.tsx`, `[postId]/page.tsx` |
+| 출퇴근 설정 | GET/PUT | `AttendanceSettingsManagement/index.tsx` |
+| 건설 현장관리 저장 | 현장/구조검토 | `SiteDetailForm.tsx`, `StructureReviewDetailForm.tsx` |
+| WIP 생산 | 생산 모달 | `WipProductionModal.tsx` |
+| 품질검사 저장 | 검사 결과 | `InspectionModal.tsx` |
+
+**소계: 13건**
+
+---
+
+## 통계 요약
+
+```
+전체 TODO:         102건
+├── 백엔드 의존:    65건 (63.7%) ← A + B
+├── 프론트 백로그:  16건 (15.7%) ← C
+├── 장기 과제:     10건 (9.8%)  ← D
+├── 대시보드 목업:   4건 (3.9%)  ← E
+└── 기타:           7건 (6.9%)  ← F
+
+프론트 독립 해결 가능: 26건 (C + D 일부)
+백엔드 완성 필요:      69건 (A + B + E)
+```
+
+---
+
+> **주의사항**
+> - `src/app/[locale]/(protected)/dev/dashboard/_components/AIPoweredDashboard.tsx`의 `TODO_ITEMS`는 변수명이며 실제 TODO 주석이 아니므로 제외
+> - 일부 항목은 복합 성격(API 연동 + UI 구현)을 가지며, 주된 블로커 기준으로 분류
+> - 이 문서는 2026-02-19 기준 스냅샷이며, 코드 변경에 따라 갱신 필요

claudedocs/dev/[REF] all-pages-test-urls.md

@@ -88,10 +88,16 @@ http://localhost:3000/ko/sales/quote-management/test/1/edit   # 🧪 견적 수
 |--------|-----|------|
 | 품목기준관리 | `/ko/master-data/item-master-data-management` | ✅ |
 | **공정관리** | `/ko/master-data/process-management` | ✅ |
+| **단가표관리** | `/ko/master-data/pricing-table-management` | 🆕 NEW |
+| **└ 단가배포관리** | `/ko/master-data/price-distribution` | 🆕 NEW |
+| **점검표관리** | `/ko/master-data/checklist-management` | 🆕 NEW |
 
 ```
 http://localhost:3000/ko/master-data/item-master-data-management
-http://localhost:3000/ko/master-data/process-management   # 공정관리
+http://localhost:3000/ko/master-data/process-management            # 공정관리
+http://localhost:3000/ko/master-data/pricing-table-management      # 🆕 단가표관리
+http://localhost:3000/ko/master-data/price-distribution             # 🆕 단가배포관리
+http://localhost:3000/ko/master-data/checklist-management           # 🆕 점검표관리
 ```
 
 ---
@@ -129,9 +135,11 @@ http://localhost:3000/ko/material/stock-status     # 🆕 재고현황
 | 페이지 | URL | 상태 |
 |--------|-----|------|
 | **검사관리** | `/ko/quality/inspections` | 🆕 NEW |
+| **실적신고관리** | `/ko/quality/performance-reports` | 🆕 NEW |
 
 ```
-http://localhost:3000/ko/quality/inspections       # 🆕 검사관리
+http://localhost:3000/ko/quality/inspections              # 🆕 검사관리
+http://localhost:3000/ko/quality/performance-reports       # 🆕 실적신고관리
 ```
 
 ---
@@ -159,9 +167,11 @@ http://localhost:3000/ko/vehicle-management/forklift      # 🆕 지게차 관
 | 페이지 | URL | 상태 |
 |--------|-----|------|
 | **출하 목록** | `/ko/outbound/shipments` | 🆕 NEW |
+| **배차차량 목록** | `/ko/outbound/vehicle-dispatches` | 🆕 NEW |
 
 ```
-http://localhost:3000/ko/outbound/shipments        # 🆕 출하관리
+http://localhost:3000/ko/outbound/shipments              # 🆕 출하관리
+http://localhost:3000/ko/outbound/vehicle-dispatches      # 🆕 배차차량관리
 ```
 
 ---
@@ -178,9 +188,11 @@ http://localhost:3000/ko/outbound/shipments        # 🆕 출하관리
 | **출퇴근관리** | `/ko/settings/attendance-settings` | ✅ |
 | **계좌관리** | `/ko/settings/accounts` | ✅ |
 | **카드관리** | `/ko/hr/card-management` | 🆕 NEW |
+| **달력관리** | `/ko/settings/calendar-management` | 🆕 NEW |
 | **게시판관리** | `/ko/board/board-management` | 🆕 NEW |
 | **팝업관리** | `/ko/settings/popup-management` | 🆕 NEW |
 | **알림설정** | `/ko/settings/notification-settings` | 🆕 NEW |
+| **바로빌연동관리** | `/ko/settings/barobill-integration` | 🆕 NEW |
 
 ```
 http://localhost:3000/ko/settings/leave-policy
@@ -192,8 +204,10 @@ http://localhost:3000/ko/settings/attendance-settings    # 출퇴근관리
 http://localhost:3000/ko/settings/accounts               # 계좌관리
 http://localhost:3000/ko/settings/notification-settings  # 🆕 알림설정
 http://localhost:3000/ko/hr/card-management              # 🆕 카드관리
+http://localhost:3000/ko/settings/calendar-management          # 🆕 달력관리
 http://localhost:3000/ko/board/board-management          # 🆕 게시판관리
 http://localhost:3000/ko/settings/popup-management       # 🆕 팝업관리
+http://localhost:3000/ko/settings/barobill-integration   # 🆕 바로빌연동관리
 ```
 
 ---
@@ -231,6 +245,10 @@ http://localhost:3000/ko/approval/reference # ✅ 참조함
 | **입출금 계좌조회** | `/ko/accounting/bank-transactions` | ✅ |
 | **카드 내역 조회** | `/ko/accounting/card-transactions` | 🆕 NEW |
 | **악성채권 추심관리** | `/ko/accounting/bad-debt-collection` | 🆕 NEW |
+| **세금계산서 발행** | `/ko/accounting/tax-invoice-issuance` | 🆕 NEW |
+| **세금계산서 관리** | `/ko/accounting/tax-invoices` | 🆕 NEW |
+| **상품권관리** | `/ko/accounting/gift-certificates` | 🆕 NEW |
+| **일반전표입력** | `/ko/accounting/general-journal-entry` | 🆕 NEW |
 
 ```
 http://localhost:3000/ko/accounting/vendors               # 거래처관리
@@ -246,6 +264,10 @@ http://localhost:3000/ko/accounting/receivables-status    # 미수금 현황
 http://localhost:3000/ko/accounting/bank-transactions     # 입출금 계좌조회
 http://localhost:3000/ko/accounting/card-transactions     # 카드 내역 조회
 http://localhost:3000/ko/accounting/bad-debt-collection   # 악성채권 추심관리
+http://localhost:3000/ko/accounting/tax-invoice-issuance  # 🆕 세금계산서 발행
+http://localhost:3000/ko/accounting/tax-invoices          # 🆕 세금계산서 관리
+http://localhost:3000/ko/accounting/gift-certificates     # 🆕 상품권관리
+http://localhost:3000/ko/accounting/general-journal-entry # 🆕 일반전표입력
 ```
 
 ---
@@ -351,6 +373,8 @@ http://localhost:3000/ko/sales/pricing-management
 ### Master Data
 ```
 http://localhost:3000/ko/master-data/item-master-data-management
+http://localhost:3000/ko/master-data/pricing-table-management      # 🆕 단가표관리
+http://localhost:3000/ko/master-data/price-distribution             # 🆕 단가배포관리
 ```
 
 ### Production
@@ -367,12 +391,14 @@ http://localhost:3000/ko/material/stock-status     # 🆕 재고현황
 
 ### Quality
 ```
-http://localhost:3000/ko/quality/inspections       # 🆕 검사관리
+http://localhost:3000/ko/quality/inspections              # 🆕 검사관리
+http://localhost:3000/ko/quality/performance-reports       # 🆕 실적신고관리
 ```
 
 ### Outbound
 ```
-http://localhost:3000/ko/outbound/shipments        # 🆕 출하관리
+http://localhost:3000/ko/outbound/shipments              # 🆕 출하관리
+http://localhost:3000/ko/outbound/vehicle-dispatches      # 🆕 배차차량관리
 ```
 
 ### Vehicle Management (차량/지게차)
@@ -393,8 +419,10 @@ http://localhost:3000/ko/settings/attendance-settings    # 출퇴근관리
 http://localhost:3000/ko/settings/accounts               # 계좌관리
 http://localhost:3000/ko/settings/notification-settings  # 🆕 알림설정
 http://localhost:3000/ko/hr/card-management              # 🆕 카드관리
+http://localhost:3000/ko/settings/calendar-management          # 🆕 달력관리
 http://localhost:3000/ko/board/board-management          # 🆕 게시판관리
 http://localhost:3000/ko/settings/popup-management       # 🆕 팝업관리
+http://localhost:3000/ko/settings/barobill-integration   # 🆕 바로빌연동관리
 ```
 
 ### Approval
@@ -419,6 +447,9 @@ http://localhost:3000/ko/accounting/receivables-status    # 미수금 현황
 http://localhost:3000/ko/accounting/bank-transactions     # 입출금 계좌조회
 http://localhost:3000/ko/accounting/card-transactions     # 🆕 카드 내역 조회
 http://localhost:3000/ko/accounting/bad-debt-collection   # 악성채권 추심관리
+http://localhost:3000/ko/accounting/tax-invoice-issuance  # 🆕 세금계산서 발행
+http://localhost:3000/ko/accounting/gift-certificates     # 🆕 상품권관리
+http://localhost:3000/ko/accounting/general-journal-entry # 🆕 일반전표입력
 ```
 
 ### Board
@@ -474,6 +505,8 @@ http://localhost:3000/ko/dev/editable-table         # Editable Table 테스트
 
 // Master Data
 '/master-data/item-master-data-management'
+'/master-data/pricing-table-management'    // 단가표관리 (🆕 NEW)
+'/master-data/price-distribution'          // 단가배포관리 (🆕 NEW)
 
 // Production
 '/production/screen-production'
@@ -485,9 +518,11 @@ http://localhost:3000/ko/dev/editable-table         # Editable Table 테스트
 
 // Quality (품질관리)
 '/quality/inspections'             // 검사관리 (🆕 NEW)
+'/quality/performance-reports'     // 실적신고관리 (🆕 NEW)
 
 // Outbound (출고관리)
 '/outbound/shipments'              // 출하관리 (🆕 NEW)
+'/outbound/vehicle-dispatches'     // 배차차량관리 (🆕 NEW)
 
 // Vehicle Management (차량/지게차)
 '/vehicle-management/vehicle'       // 차량관리 (🆕 NEW)
@@ -504,8 +539,10 @@ http://localhost:3000/ko/dev/editable-table         # Editable Table 테스트
 '/settings/accounts'               // 계좌관리
 '/settings/notification-settings'  // 알림설정 (🆕 NEW)
 '/hr/card-management'              // 카드관리 (🆕 NEW)
+'/settings/calendar-management'          // 달력관리 (🆕 NEW)
 '/board/board-management'          // 게시판관리 (🆕 NEW)
 '/settings/popup-management'       // 팝업관리 (🆕 NEW)
+'/settings/barobill-integration'   // 바로빌연동관리 (🆕 NEW)
 
 // 계정/회사/구독 (사이드바 루트 레벨 별도 메뉴)
 '/settings/account-info'           // 계정정보 (🆕 NEW)
@@ -532,6 +569,9 @@ http://localhost:3000/ko/dev/editable-table         # Editable Table 테스트
 '/accounting/bank-transactions'   // 입출금 계좌조회
 '/accounting/card-transactions'   // 카드 내역 조회
 '/accounting/bad-debt-collection' // 악성채권 추심관리
+'/accounting/tax-invoice-issuance' // 세금계산서 발행 (🆕 NEW)
+'/accounting/gift-certificates'   // 상품권관리 (🆕 NEW)
+'/accounting/general-journal-entry' // 일반전표입력 (🆕 NEW)
 
 // Board (게시판)
 '/board'                          // 게시판 목록
@@ -551,4 +591,4 @@ http://localhost:3000/ko/dev/editable-table         # Editable Table 테스트
 ## 작성일
 
 - 최초 작성: 2025-12-06
-- 최종 업데이트: 2026-01-28 (차량/지게차 메뉴 추가)
+- 최종 업데이트: 2026-02-13 (일반전표입력 추가)

claudedocs/dev/[REPORT-2026-02-23] E2E-remaining-bugs-handoff.md

@@ -0,0 +1,129 @@
+# E2E 잔여 버그 전달 사항
+
+**작성일**: 2026-02-23
+**근거**: `sam-hotfix/e2e/results/hotfix/HOTFIX-REPORT_dev-team_2026-02-20.md`
+
+---
+
+## 프론트엔드 수정 완료 (3건 + 1건)
+
+| Bug ID | 내용 | 수정 상태 |
+|--------|------|:---------:|
+| BUG-SORT-001 | 컬럼 정렬 미구현 (14개 페이지) | ✅ 완료 |
+| BUG-FILTER-001 | 매출관리 필터 미동작 | ✅ 완료 |
+| BUG-REDIRECT-001 | 어음/입금 등록 후 리다이렉트 | ✅ 완료 |
+| BUG-BATCH-DELETE-001 (입금) | 삭제 후 빈 페이지 표시 | ✅ 완료 (UniversalListPage 공통 수정) |
+
+---
+
+## QA팀 확인 요청 (1건)
+
+### BUG-BATCH-DELETE-001 (어음관리) — E2E 테스트 패턴 불일치
+
+**현상**: `batch-create-acc-bills` 시나리오에서 VERIFY 단계 FAIL (기대 3건, 실제 0건)
+
+**원인 분석**:
+- E2E 테스트가 `E2E_TEST_어음_{timestamp}` 패턴으로 데이터를 검색
+- 그러나 실제 어음번호는 프론트엔드에서 `E2E_TEST_EB` 접두사로 생성됨
+- **백엔드 API 확인 결과**: `BillService.php:106`에서 `bill_number`를 프론트가 보낸 그대로 저장 (변환 없음)
+- `StoreBillRequest.php` 검증: `nullable|string|max:50` — 접두사 제한 없음
+
+**결론**: API는 정상. **E2E 테스트 스크립트의 검색 패턴(`E2E_TEST_어음_`)이 실제 생성 데이터 패턴(`E2E_TEST_EB`)과 불일치**
+
+**요청 사항**:
+- E2E 테스트의 어음번호 검색 패턴을 실제 프론트엔드가 생성하는 패턴에 맞게 수정
+- 또는 프론트엔드 어음 등록 폼에서 E2E 테스트 시 사용하는 어음번호 필드값 확인
+
+---
+
+## 백엔드팀 수정 요청 (1건)
+
+### BUG-PERF-001 — 품목관리 API 성능 문제 (10초+ 지연)
+
+**현상**: 생산관리 > 품목관리 (`/api/v1/items`) 테이블 로드 10초 타임아웃
+
+**원인 분석** (sam-api 코드 확인):
+
+#### 병목 1: `getItemsWithInspectionTemplate()` — 전체 테이블 스캔 (5-8초)
+
+**파일**: `app/Services/ItemService.php` (lines 1024-1060)
+
+```php
+$templates = \DB::table('document_templates')
+    ->where('tenant_id', $tenantId)
+    ->where('is_active', true)
+    ->whereNotNull('linked_item_ids')
+    ->where(function ($q) use ($categoryCode, $categoryName) {
+        $q->where('category', $categoryCode)
+            ->orWhere('category', $categoryName)
+            ->orWhere('category', 'LIKE', "%{$categoryName}%");
+    })
+    ->get(['linked_item_ids']);  // ← limit 없이 전체 로드
+```
+
+- `linked_item_ids`는 JSON 컬럼 → 인덱스 불가
+- 페이지에 20개만 표시하는데 **모든 document_templates 로드** 후 PHP에서 수동 매칭
+- 템플릿 수가 많을수록 지연 증가
+
+#### 병목 2: N+1 쿼리 (2-3초)
+
+**파일**: `app/Services/ItemService.php` (lines 376-390)
+
+```php
+->with(['category:id,name', 'details', 'files']);
+```
+
+- `details` (hasOne): 아이템당 1쿼리 → 20개 = 20쿼리
+- `files` (hasMany + document_type 필터): 아이템당 1쿼리 → 20개 = 20쿼리
+- 합계: ~40개 추가 쿼리
+
+#### 병목 3: 누락 인덱스
+
+- `files` 테이블: `document_id` + `document_type` 복합 인덱스 없음
+- `document_templates` 테이블: `linked_item_ids` JSON 인덱스 없음
+
+**예상 총 지연**: ~9-11초 (E2E 10초 타임아웃과 일치)
+
+**수정 제안**:
+1. `getItemsWithInspectionTemplate()`에서 필요한 `item_id` 목록만 IN 조건으로 조회하도록 변경
+2. `files`, `item_details` 테이블에 적절한 인덱스 추가
+3. Eager loading 최적화 (`with` 절에 필요한 컬럼만 select)
+
+---
+
+## 백엔드팀 참고 — 신규 리그레션 2건 (API 서버 상태)
+
+리그레션 리포트(`REGRESSION-REPORT_dev-team_2026-02-20.md`)에서 발견된 신규 이슈.
+**3차 테스트에서 PASS → 4차(Pull 후) FAIL로 전환된 건**으로, 서버 상태 확인 필요.
+
+### BUG-REGRESSION-001: 입금관리 CRUD 실패 (API 500 에러)
+
+- **시나리오**: `create-delete-acc-deposit`
+- **증상**: 다수 API 500 에러 (Welfare, Calendar, TodayIssue API)
+- **API 평균 응답**: 3,574ms (통상 84ms의 42배)
+- **테이블**: 0건 로드 (데이터 로드 실패)
+
+### BUG-REGRESSION-002: 자유게시판 CRUD 실패 (API 극심한 지연)
+
+- **시나리오**: `create-delete-board`
+- **증상**: vendorId 옵션 로드 실패, 테이블 로드 5초 타임아웃
+- **API 평균 응답**: 7,752ms (통상 84ms의 92배)
+- **에러**: `Failed to load options for vendorId: TypeError: Failed to fetch`
+
+**공통 추정 원인**: Pull 이후 API 서버 불안정 (500 에러, fetch 실패 다수)
+
+---
+
+## 재검증 명령
+
+```bash
+# 전체 재검증
+node C:/Users/codeb/sam/e2e/runner/run-all.js
+
+# 버그별 개별 검증
+node C:/Users/codeb/sam/e2e/runner/run-all.js --filter pagination-sort    # BUG-SORT-001 ← 프론트 수정 완료
+node C:/Users/codeb/sam/e2e/runner/run-all.js --filter search-filter      # BUG-FILTER-001 ← 프론트 수정 완료
+node C:/Users/codeb/sam/e2e/runner/run-all.js --filter reload-persist     # BUG-REDIRECT-001 ← 프론트 수정 완료
+node C:/Users/codeb/sam/e2e/runner/run-all.js --filter batch-create       # BUG-BATCH-DELETE-001 ← 프론트 일부 수정 + QA 테스트 패턴 확인
+node C:/Users/codeb/sam/e2e/runner/run-all.js --filter workflow           # BUG-PERF-001 ← 백엔드 수정 필요
+```

claudedocs/dev/[REVIEW] MD-to-PPTX 자동화 파이프라인 검토서.md

@@ -0,0 +1,313 @@
+# MD 기반 MES/ERP 기획서 자동화 파이프라인 검토서
+
+> **작성일**: 2026-02-10
+> **작성**: 류병철 / Claude Code
+> **목적**: 회의록/인터뷰 → MD → PPTX → 프론트엔드 자동화 파이프라인의 실현 가능성 검증 및 팀 검토
+> **PoC 대상**: 주일기업 MES (자동방화셔터 시공 관리 시스템)
+
+---
+
+## 1. 배경 및 목적
+
+### 1.1 해결하려는 문제
+
+MES/ERP 프로젝트에서 반복되는 비효율:
+
+| 단계 | 현재 문제 |
+|------|----------|
+| 요구사항 수집 | 인터뷰/회의 내용이 구두로만 전달, 누락 빈번 |
+| 기획서 작성 | 수작업 PPTX 제작에 1~2주 소요 |
+| 고객 확인 | 기획서 수정 → PPTX 재작업의 반복 |
+| 개발 착수 | 기획서와 실제 구현 간 해석 차이 발생 |
+| 변경 관리 | 기획서-코드 간 동기화 안 됨 |
+
+### 1.2 제안 개념
+
+**MD 파일을 Single Source of Truth로** 사용하여, 하나의 문서에서 기획서(PPTX)와 코드(프론트엔드)를 모두 파생시키는 자동화 파이프라인.
+
+```
+인터뷰/녹음 → MD 명세서 → PPTX 기획서 (고객 확인용)
+                       → 프론트엔드 코드 (개발용)
+                       → API 구조 설계 (백엔드용)
+```
+
+---
+
+## 2. 파이프라인 설계
+
+### 2.1 전체 흐름
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  1단계: 요구사항 수집                                             │
+│  인터뷰 / 현장 방문 / 녹음 → 녹취록 + 원본 자료                    │
+└──────────────────────────┬──────────────────────────────────────┘
+                           ▼
+┌─────────────────────────────────────────────────────────────────┐
+│  2단계: MD 명세서 작성                                            │
+│  녹취록 + 업종 체크리스트 → 구조화된 MD 파일                        │
+│  (화면 구성, 데이터 모델, 상태 머신, API 엔드포인트 포함)             │
+└──────────────────────────┬──────────────────────────────────────┘
+                           ▼
+┌─────────────────────────────────────────────────────────────────┐
+│  3단계: PPTX 기획서 자동 생성                                      │
+│  MD → Claude → python-pptx 스크립트 → 와이어프레임 PPTX             │
+│  고객과 화면 단위로 검토 및 승인                                     │
+└──────────────────────────┬──────────────────────────────────────┘
+                           ▼
+┌─────────────────────────────────────────────────────────────────┐
+│  4단계: 프론트엔드 + API 구조 설계                                  │
+│  승인된 MD + 기존 컴포넌트 라이브러리 → 화면 코드 생성                │
+│  Mock API로 즉시 동작 가능한 프로토타입 구성                         │
+└──────────────────────────┬──────────────────────────────────────┘
+                           ▼
+┌─────────────────────────────────────────────────────────────────┐
+│  5단계: 프로토타입 테스트                                          │
+│  Mock API 기반 프로토타입으로 고객/내부 테스트                       │
+│  피드백 → MD 역반영 → 영향 범위 파악                                │
+└──────────────────────────┬──────────────────────────────────────┘
+                           ▼
+┌─────────────────────────────────────────────────────────────────┐
+│  6단계: 실 API 연동 + 최종 검수                                    │
+│  Mock → 실제 API 교체 → 통합 테스트 → 고객 최종 검수                │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### 2.2 각 단계 상세
+
+#### 1단계: 요구사항 수집
+
+| 항목 | 내용 |
+|------|------|
+| 입력 | 고객 인터뷰, 현장 녹음, 기존 시스템 스크린샷, 업무 매뉴얼 |
+| 출력 | 녹취록 + 수집 자료 원본 |
+| 담당 | 기획자 / PM |
+| 도구 | 녹음 앱, 스크린샷 도구 |
+
+#### 2단계: MD 명세서 작성
+
+| 항목 | 내용 |
+|------|------|
+| 입력 | 녹취록 + 업종별 체크리스트 |
+| 출력 | 구조화된 MD 파일 (단일 파일) |
+| 담당 | 기획자 + Claude 보조 |
+| 도구 | Claude Code, 텍스트 에디터 |
+
+**MD에 포함되어야 할 섹션:**
+- 시스템 개요 (목적, 모듈 구성)
+- 역할/권한 시스템
+- 화면별 상세 명세 (레이아웃, 컴포넌트, 데이터)
+- 상태 머신 (비즈니스 흐름)
+- 데이터 모델
+- API 엔드포인트 목록
+- PPTX 레이아웃 규격 (색상, 치수, 컴포넌트 정의)
+
+#### 3단계: PPTX 자동 생성
+
+| 항목 | 내용 |
+|------|------|
+| 입력 | 2단계 MD 파일 |
+| 출력 | 와이어프레임 기반 PPTX (python-pptx) |
+| 담당 | Claude Code (자동) |
+| 도구 | Python + python-pptx |
+
+#### 4단계: 프론트엔드 + API 설계
+
+| 항목 | 내용 |
+|------|------|
+| 입력 | 승인된 MD + 기존 컴포넌트 라이브러리 |
+| 출력 | 동작하는 프론트엔드 코드 + Mock API |
+| 담당 | Claude Code + 개발자 검수 |
+| 도구 | Next.js, 기존 organisms/molecules 컴포넌트 |
+
+#### 5단계: 프로토타입 테스트
+
+| 항목 | 내용 |
+|------|------|
+| 입력 | Mock API 기반 프로토타입 |
+| 출력 | 피드백 목록 + MD 수정 사항 |
+| 담당 | 고객 + QA + 기획자 |
+| 도구 | 브라우저, 피드백 시트 |
+
+#### 6단계: 실 API 연동 + 검수
+
+| 항목 | 내용 |
+|------|------|
+| 입력 | 테스트 완료된 프론트 + 백엔드 API |
+| 출력 | 운영 배포 가능한 시스템 |
+| 담당 | 프론트엔드 + 백엔드 개발자 |
+| 도구 | Laravel API, Next.js |
+
+---
+
+## 3. PoC 검증 결과 (주일기업 MES)
+
+### 3.1 검증 범위
+
+주일기업 MES(자동방화셔터 시공 관리 시스템)를 대상으로 **2단계 → 3단계** 구간을 검증.
+
+```
+실제 동작하는 화면 스크린샷 22장
+    → 역기획서 MD 작성 (역기획서_주일기업MES.md)
+    → python-pptx 스크립트 생성 (generate_pptx.py, 약 71KB)
+    → PPTX 기획서 자동 생성 (22슬라이드, 102KB)
+    → PPTX 내용을 독립 MD 명세서로 변환 (주일기업_MES_PPTX_명세서.md, 891줄)
+    → 새 세션에서 MD만으로 PPTX 재생성 시도 (진행 중)
+```
+
+### 3.2 검증된 사항
+
+| 검증 항목 | 결과 | 비고 |
+|-----------|------|------|
+| MD → Python 스크립트 생성 | 성공 | Claude가 MD를 읽고 python-pptx 코드 자동 생성 |
+| 와이어프레임 PPTX 출력 | 성공 | 도형 기반 UI를 22슬라이드로 렌더링 |
+| PPTX → MD 역변환 | 성공 | 891줄 명세서로 구조화 |
+| MD만으로 PPTX 재생성 (새 세션) | 진행 중 | 이전 컨텍스트 없이 MD만으로 동일 품질 생성 가능한지 검증 |
+
+### 3.3 생성된 산출물
+
+```
+~/Desktop/역기획서_스크린샷/
+├── 01~22_*.png                          # 원본 스크린샷 22장
+└── 역기획서_주일기업MES.md               # 역기획서 (439줄)
+
+~/Desktop/주일기업_MES_기획서/
+├── generate_pptx.py                      # PPTX 생성 스크립트 (71KB)
+├── 주일기업_MES_Storyboard_D1.0_260210.pptx  # 생성된 PPTX (102KB)
+├── preview/                              # 슬라이드 미리보기 PNG 17장
+└── preview_markers.py                    # 마커 미리보기 스크립트
+
+~/Desktop/주일 md to pptx test/
+└── 주일기업_MES_PPTX_명세서.md           # 독립 MD 명세서 (891줄)
+```
+
+---
+
+## 4. 비판적 분석
+
+### 4.1 강점
+
+| 강점 | 설명 |
+|------|------|
+| MD 중심 일관성 | 하나의 문서에서 기획서와 코드가 파생되므로 "기획서와 코드가 다른" 문제 원천 차단 |
+| 기획서 작업 시간 단축 | 수작업 1~2주 → MD 작성 후 자동 생성으로 수 시간 내 완료 가능 |
+| 기존 자산 재활용 | SAM 프로젝트의 organisms/molecules 컴포넌트를 그대로 활용 |
+| 반복 가능한 프로세스 | 동일 파이프라인을 다른 고객사에도 적용 가능 |
+| Mock-first 개발 | API 완성 전 프로토타입으로 빠른 피드백 가능 |
+
+### 4.2 리스크 및 대응 방안
+
+#### 리스크 1: 1→2단계 정보 손실 (심각도: 높음)
+
+**문제**: 인터뷰/녹음에서 MD로 변환할 때 정보 손실이 가장 큼. MES/ERP 현장에는 "당연히 그렇게 하는" 암묵적 프로세스가 많아 인터뷰에서 언급되지 않는 경우가 빈번함.
+
+**예시**: "납기일 변경 시 관련 공정 전체 재계산", "특정 조건에서만 나타나는 승인 단계" 등
+
+**대응 방안**:
+- 업종별 필수 프로세스 체크리스트 사전 준비
+- 인터뷰 후 체크리스트 대조 → 누락 항목 2차 확인
+- MD 초안을 고객에게 텍스트 레벨로 먼저 검토받는 단계 추가 (2.5단계)
+
+#### 리스크 2: 고객의 와이어프레임 이해도 (심각도: 중간)
+
+**문제**: MES/ERP 사용자는 대부분 비개발자. 정적 와이어프레임만으로는 동적 흐름(상태 전환, 조건부 UI)을 파악하지 못하고, "확인했습니다" 후 프로토타입을 보고 "이게 아닌데요"가 발생.
+
+**대응 방안**:
+- PPTX에 상태 머신, 시나리오 흐름을 명시 (PoC에서 이미 적용)
+- 3단계와 5단계를 가까이 배치하여 클릭 가능한 프로토타입으로 보완
+- 주요 흐름은 슬라이드 여러 장으로 상태 변화를 시각적으로 나열
+
+#### 리스크 3: API 설계 시점 (심각도: 중간)
+
+**문제**: API 구조 설계가 4단계에서 시작되면, 백엔드 제약사항(기존 DB 스키마, 외부 연동)이 프론트 설계를 뒤집을 수 있음.
+
+**대응 방안**:
+- 2단계 MD에 데이터 모델 + API 엔드포인트 목록을 포함 (PoC에서 이미 적용)
+- 백엔드 개발자가 2단계 MD 리뷰에 참여
+- API 제약사항을 3단계 이전에 확인
+
+#### 리스크 4: 변경의 역전파 (심각도: 중간)
+
+**문제**: 5단계 테스트에서 변경 요청 발생 시, MD → PPTX → 코드 전체가 연쇄 수정되어야 함. 현재 파이프라인은 단방향이라 역방향 반영 체계가 없음.
+
+**대응 방안**:
+- MD 버전 관리 (Git)
+- 변경 요청 시 MD 먼저 수정 → PPTX/코드 재생성 순서 준수
+- 변경 영향 범위를 MD 섹션 단위로 추적
+
+#### 리스크 5: 동시 다중 프로젝트 (심각도: 낮음, 현재)
+
+**문제**: 1~2단계(인터뷰 → MD)는 자동화가 어려워, 동시에 3~5개 고객 프로젝트를 진행하면 병목 발생.
+
+**대응 방안**:
+- 업종별 MD 템플릿 사전 구축으로 2단계 작업량 감소
+- 3단계 이후는 자동화 비율이 높으므로 병목은 1~2단계에 집중 → 기획 인력 확보
+
+---
+
+## 5. 개선된 파이프라인 (제안)
+
+기존 6단계에 검증 게이트를 추가한 버전:
+
+```
+1단계  인터뷰/녹음 → 녹취록 + 원본 자료
+          │
+2단계  녹취록 + 업종 체크리스트 → MD 명세서 (데이터 모델 + API 포함)
+          │
+  ┌───── 2.5단계  고객 + 백엔드 개발자 MD 텍스트 리뷰 ──────┐
+  │       (화면 만들기 전에 내용의 정확성 먼저 확인)            │
+  │       승인 ✓                    수정 요청 → 2단계로 복귀   │
+  └───────┬───────────────────────────────────────────────────┘
+          │
+3단계  MD → PPTX 와이어프레임 자동 생성
+          │
+  ┌───── 3.5단계  고객 화면 검토 (서명) ──────────────────────┐
+  │       승인 ✓                    수정 요청 → MD 수정 → 재생성│
+  └───────┬───────────────────────────────────────────────────┘
+          │
+4단계  MD + 기존 컴포넌트 → 프론트엔드 + Mock API 프로토타입
+          │
+5단계  프로토타입 테스트 (고객 + 내부)
+          │
+  ┌───── 5.5단계  피드백 반영 ────────────────────────────────┐
+  │       피드백 → MD 수정 → 영향 범위 확인 → 코드 반영         │
+  │       완료 ✓                                              │
+  └───────┬───────────────────────────────────────────────────┘
+          │
+6단계  Mock → 실 API 교체 → 통합 테스트 → 최종 검수
+```
+
+---
+
+## 6. 필요 사전 작업
+
+파이프라인을 실전에 적용하기 위해 준비해야 할 것:
+
+| 항목 | 설명 | 우선순위 |
+|------|------|----------|
+| MD 템플릿 표준화 | PPTX 레이아웃 규격, 색상, 컴포넌트 정의를 포함한 MD 작성 가이드 | 높음 |
+| 업종별 체크리스트 | MES/ERP 업종별 필수 프로세스 목록 (제조, 시공, 물류 등) | 높음 |
+| 컴포넌트 라이브러리 정리 | 4단계에서 활용할 organisms/molecules 카탈로그 | 중간 |
+| Mock API 규격 | 프론트 프로토타입에서 사용할 Mock 데이터 구조 표준 | 중간 |
+| 변경 관리 프로세스 | MD 수정 → 영향 범위 파악 → 재생성 절차 문서화 | 낮음 (초기) |
+
+---
+
+## 7. 검토 요청 사항
+
+팀원들에게 확인받고 싶은 사항:
+
+1. **기획자**: 1→2단계에서 인터뷰 내용을 MD로 구조화하는 과정이 현실적인가? 어떤 보조 도구가 필요한가?
+2. **프론트엔드 개발자**: 4단계에서 MD 명세서만으로 화면 구현이 가능한 수준인가? 기존 컴포넌트 재활용 범위는?
+3. **백엔드 개발자**: 2단계 MD에 포함된 데이터 모델/API 명세가 백엔드 설계에 충분한가? 추가로 필요한 정보는?
+4. **PM**: 이 파이프라인의 단계별 소요 시간 예측이 가능한가? 고객 커뮤니케이션 포인트는 적절한가?
+
+---
+
+## 8. 다음 단계
+
+- [ ] MD만으로 PPTX 재생성 PoC 완료 (현재 진행 중)
+- [ ] 팀 검토 미팅 일정 확정
+- [ ] 검토 결과 반영하여 파이프라인 확정
+- [ ] MD 템플릿 표준 초안 작성
+- [ ] 실 고객 프로젝트 파일럿 적용 대상 선정

claudedocs/guides/[GUIDE] common-page-patterns.md

@@ -0,0 +1,522 @@
+# SAM 프로젝트 공통 페이지/컴포넌트 패턴 가이드
+
+신규 페이지·모달 작업 시 이 문서를 참고하여 기존 구조와 일관성을 유지한다.
+
+---
+
+## 목차
+
+1. [공통 컴포넌트 맵](#1-공통-컴포넌트-맵)
+2. [검색 모달 (SearchableSelectionModal)](#2-검색-모달)
+3. [리스트 페이지](#3-리스트-페이지)
+4. [상세/폼 페이지](#4-상세폼-페이지)
+5. [API 연동 패턴](#5-api-연동-패턴)
+6. [페이지 라우팅 구조](#6-페이지-라우팅-구조)
+
+---
+
+## 1. 공통 컴포넌트 맵
+
+### Organisms (`src/components/organisms/`)
+
+| 컴포넌트 | 용도 | 주요 Props |
+|----------|------|-----------|
+| `PageHeader` | 페이지 제목, 설명, 아이콘, 액션 버튼 | title, description, icon, actions |
+| `PageLayout` | 최대 너비 래퍼 + 버전 정보 | children, maxWidth? |
+| `StatCards` | 통계 카드 그리드 | stats[], onStatClick? |
+| `SearchFilter` | 검색 입력 + 모바일 필터 | searchTerm, onSearchChange, placeholder |
+| `DataTable` | 테이블 + 페이지네이션 + 정렬 | columns, renderRow, pagination |
+| `MobileCard` / `ListMobileCard` | 모바일 카드 레이아웃 | id, title, infoGrid, badges |
+| `EmptyState` | 빈 상태 (아이콘 + 메시지 + 액션) | icon, title, description, action |
+| `FormSection` | 카드 래퍼 (아이콘 + 제목 + 설명) | icon, title, description |
+| `FormFieldGrid` | 반응형 필드 그리드 (1~4열) | cols, children |
+| `FormActions` | 저장/취소 버튼 그룹 | onSave, onCancel, isSaving |
+| **`SearchableSelectionModal`** | **검색 → 목록 → 선택 모달** | **fetchData, renderItem, mode** |
+
+### Molecules (`src/components/molecules/`)
+
+| 컴포넌트 | 용도 |
+|----------|------|
+| `StatusBadge` | 상태 뱃지 (색상 자동) |
+| `TableActions` | 테이블 행 액션 버튼 |
+| `StandardDialog` / `ConfirmDialog` | 확인/경고 다이얼로그 |
+| `YearQuarterFilter` | 연도/분기 필터 |
+| `MobileFilter` | 모바일 필터 UI |
+
+### Templates (`src/components/templates/`)
+
+| 컴포넌트 | 용도 |
+|----------|------|
+| `UniversalListPage` | 리스트 페이지 올인원 템플릿 |
+
+---
+
+## 2. 검색 모달
+
+### 언제 사용하나
+
+"검색 → 목록 → 선택" 패턴이 필요할 때 → `SearchableSelectionModal<T>` 사용.
+Dialog + Input + 리스트를 직접 조합하지 않는다.
+
+### 위치
+
+```
+src/components/organisms/SearchableSelectionModal/
+├── SearchableSelectionModal.tsx  — 메인 컴포넌트
+├── useSearchableData.ts         — 검색+로딩 훅
+├── types.ts                     — Props 인터페이스
+└── index.ts
+```
+
+### 핵심 Props
+
+```typescript
+SearchableSelectionModal<T>
+  // 필수
+  open: boolean
+  onOpenChange: (open: boolean) => void
+  title: ReactNode
+  fetchData: (query: string) => Promise<T[]>  // API 호출 위임
+  keyExtractor: (item: T) => string
+  renderItem: (item: T, isSelected: boolean) => ReactNode
+  mode: 'single' | 'multiple'
+  onSelect: single → (item: T) | multiple → (items: T[])
+
+  // 검색 설정
+  searchPlaceholder?: string
+  searchMode?: 'debounce' | 'enter'       // 기본: debounce
+  validateSearch?: (q: string) => boolean  // 유효성 검사
+  loadOnOpen?: boolean                     // 열릴 때 자동 로드
+
+  // 메시지
+  emptyQueryMessage?: string
+  invalidSearchMessage?: string
+  noResultMessage?: string
+  loadingMessage?: string
+
+  // 레이아웃
+  dialogClassName?: string
+  listContainerClassName?: string
+  listWrapper?: (children, selectState?) => ReactNode  // Table 등 커스텀 구조
+  infoText?: (items, isLoading) => ReactNode
+
+  // 다중선택 전용
+  confirmLabel?: string
+  allowSelectAll?: boolean
+```
+
+### 패턴별 예제
+
+#### A. 단일선택 + 디바운스 검색 (가장 일반적)
+
+```tsx
+// 품목 검색, 거래처 검색 등
+<SearchableSelectionModal<ItemType>
+  open={open}
+  onOpenChange={setOpen}
+  title="품목 검색"
+  searchPlaceholder="품목코드 또는 품목명 검색..."
+  fetchData={async (q) => fetchItems({ search: q, per_page: 50 })}
+  keyExtractor={(item) => item.id}
+  validateSearch={(q) => /[a-zA-Z가-힣0-9]/.test(q)}
+  emptyQueryMessage="검색어를 입력하세요"
+  dialogClassName="sm:max-w-[500px]"
+  mode="single"
+  onSelect={(item) => { /* 선택 처리 */ }}
+  renderItem={(item) => (
+    <div className="p-3 hover:bg-blue-50 transition-colors">
+      <span className="font-semibold">{item.code}</span>
+      <span className="text-sm text-gray-600 ml-2">{item.name}</span>
+    </div>
+  )}
+/>
+```
+
+#### B. 단일선택 + 카드 UI + 열릴 때 자동 로드
+
+```tsx
+// 수주 선택, 견적 선택 등
+<SearchableSelectionModal<OrderType>
+  open={open}
+  onOpenChange={setOpen}
+  title="수주 선택"
+  fetchData={async (q) => { /* API 호출 + toast 에러 처리 */ }}
+  keyExtractor={(order) => order.id}
+  loadOnOpen                                    // ← 열릴 때 전체 로드
+  dialogClassName="sm:max-w-lg"
+  listContainerClassName="max-h-[400px] overflow-y-auto space-y-2"
+  mode="single"
+  onSelect={onSelect}
+  renderItem={(order) => (
+    <div className="p-4 border rounded-lg hover:bg-muted/50 transition-colors">
+      {/* 카드형 UI */}
+    </div>
+  )}
+/>
+```
+
+#### C. 다중선택 + Enter 검색 + 테이블
+
+```tsx
+// 수주 다중선택 (체크박스 테이블)
+<SearchableSelectionModal<OrderSelectItem>
+  open={open}
+  onOpenChange={setOpen}
+  title="수주 선택"
+  fetchData={handleFetchData}
+  keyExtractor={(item) => item.id}
+  searchMode="enter"                            // ← 수동 검색
+  loadOnOpen
+  dialogClassName="sm:max-w-2xl"
+  listContainerClassName="max-h-[400px] overflow-y-auto border rounded-md"
+  mode="multiple"
+  onSelect={onSelect}
+  confirmLabel="선택"
+  allowSelectAll
+  listWrapper={(children, selectState) => (     // ← Table 구조 래핑
+    <Table>
+      <TableHeader>
+        <TableRow>
+          <TableHead className="w-10">
+            {selectState && (
+              <Checkbox
+                checked={selectState.isAllSelected}
+                onCheckedChange={selectState.onToggleAll}
+              />
+            )}
+          </TableHead>
+          <TableHead>수주번호</TableHead>
+          <TableHead>현장명</TableHead>
+        </TableRow>
+      </TableHeader>
+      <TableBody>{children}</TableBody>
+    </Table>
+  )}
+  renderItem={(item, isSelected) => (
+    <TableRow className="cursor-pointer hover:bg-muted/50">
+      <TableCell onClick={(e) => e.stopPropagation()}>
+        <Checkbox checked={isSelected} />
+      </TableCell>
+      <TableCell>{item.orderNumber}</TableCell>
+      <TableCell>{item.siteName}</TableCell>
+    </TableRow>
+  )}
+/>
+```
+
+### 기존 모달 → 공통 컴포넌트 매핑
+
+| 기존 모달 | 위치 | 패턴 |
+|-----------|------|------|
+| `ItemSearchModal` | quotes/ | A (단일 + 디바운스) |
+| `SupplierSearchModal` | material/ReceivingManagement/ | A (단일 + 디바운스) |
+| `SalesOrderSelectModal` | production/WorkOrders/ | B (단일 + 카드 + loadOnOpen) |
+| `QuotationSelectDialog` | orders/ | B (단일 + 카드 + loadOnOpen) |
+| `OrderSelectModal` | quality/InspectionManagement/ | C (다중 + Enter + 테이블) |
+
+---
+
+## 3. 리스트 페이지
+
+### 방법 1: UniversalListPage 템플릿 (권장)
+
+`src/components/templates/UniversalListPage`에 config 객체를 전달하는 올인원 방식.
+
+```tsx
+'use client';
+
+import { UniversalListPage } from '@/components/templates/UniversalListPage';
+import type { UniversalListPageConfig } from '@/components/templates/UniversalListPage';
+
+export default function MyListPage() {
+  const config: UniversalListPageConfig<MyItem> = {
+    title: '목록 제목',
+    description: '설명',
+    icon: ListIcon,
+    basePath: '/path/to/list',
+    idField: 'id',
+
+    // 통계
+    stats: [
+      { label: '전체', value: totalCount, icon: Users },
+    ],
+
+    // 탭
+    tabs: [
+      { value: 'all', label: '전체', count: totalCount },
+      { value: 'active', label: '활성', count: activeCount },
+    ],
+
+    // 테이블 컬럼
+    columns: [
+      { key: 'name', label: '이름' },
+      { key: 'status', label: '상태' },
+    ],
+
+    // 검색
+    searchPlaceholder: '이름, 코드 검색...',
+    searchFilter: (item, q) => item.name.includes(q),
+    tabFilter: (item, tab) => tab === 'all' || item.status === tab,
+
+    // 렌더링
+    renderTableRow,
+    renderMobileCard,
+    headerActions: () => <Button>신규</Button>,
+  };
+
+  return <UniversalListPage config={config} initialData={data} />;
+}
+```
+
+### 방법 2: Organisms 직접 조합
+
+UniversalListPage가 맞지 않는 경우 organisms를 직접 조합.
+
+```tsx
+'use client';
+
+import { PageLayout, PageHeader, StatCards, SearchFilter, DataTable, EmptyState } from '@/components/organisms';
+
+export function MyList() {
+  return (
+    <PageLayout>
+      <PageHeader title="제목" description="설명" actions={<Button>신규</Button>} />
+      <StatCards stats={stats} />
+      <SearchFilter searchTerm={q} onSearchChange={setQ} placeholder="검색..." />
+      {data.length > 0 ? (
+        <DataTable columns={columns} renderRow={renderRow} pagination={pagination} />
+      ) : (
+        <EmptyState icon={FileX} title="데이터 없음" />
+      )}
+    </PageLayout>
+  );
+}
+```
+
+### 리스트 페이지 공통 규칙
+
+- **검색 디바운스**: 300ms
+- **테이블 컬럼 순서**: 체크박스 → 번호 → 데이터 컬럼 → 작업
+- **번호 계산**: `(currentPage - 1) * pageSize + index + 1`
+- **모바일**: `ListMobileCard` 또는 `MobileCard` 사용
+- **빈 상태**: `EmptyState` 사용 (검색 결과 없음 vs 데이터 없음 구분)
+- **삭제 확인**: `ConfirmDialog` 사용 (alert 금지)
+
+---
+
+## 4. 상세/폼 페이지
+
+### 표준 구조
+
+```tsx
+'use client';
+
+import { useState, useEffect, useCallback } from 'react';
+import { useRouter } from 'next/navigation';
+import { toast } from 'sonner';
+import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
+import { Button } from '@/components/ui/button';
+import { Input } from '@/components/ui/input';
+import { Label } from '@/components/ui/label';
+
+interface DetailProps {
+  id?: string;
+  mode: 'view' | 'edit' | 'new';
+}
+
+export function MyDetail({ id, mode }: DetailProps) {
+  const isViewMode = mode === 'view';
+  const isNewMode = mode === 'new';
+  const router = useRouter();
+
+  // 상태 (모든 hook은 최상단에 — 조건부 return 전에)
+  const [isLoading, setIsLoading] = useState(!isNewMode);
+  const [isSaving, setIsSaving] = useState(false);
+  const [formData, setFormData] = useState({ name: '', code: '' });
+
+  // 데이터 로드 (view/edit)
+  useEffect(() => {
+    if (!id || isNewMode) { setIsLoading(false); return; }
+    getDetail(id).then(data => {
+      setFormData(data);
+      setIsLoading(false);
+    });
+  }, [id, isNewMode]);
+
+  // 저장
+  const handleSubmit = async () => {
+    setIsSaving(true);
+    try {
+      if (isNewMode) await create(formData);
+      else await update(id!, formData);
+      toast.success('저장되었습니다.');
+      router.back();
+    } catch {
+      toast.error('저장에 실패했습니다.');
+    } finally {
+      setIsSaving(false);
+    }
+  };
+
+  if (isLoading) return <Skeleton />;
+
+  return (
+    <div className="container mx-auto py-6 max-w-4xl">
+      {/* 헤더 */}
+      <div className="mb-6">
+        <h1 className="text-2xl font-bold">
+          {isNewMode ? '신규 등록' : isViewMode ? '상세 보기' : '수정'}
+        </h1>
+      </div>
+
+      {/* 섹션 1 */}
+      <Card className="mb-6">
+        <CardHeader><CardTitle>기본 정보</CardTitle></CardHeader>
+        <CardContent className="space-y-4">
+          <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
+            <div className="space-y-2">
+              <Label>이름</Label>
+              <Input
+                value={formData.name}
+                onChange={(e) => setFormData(prev => ({ ...prev, name: e.target.value }))}
+                disabled={isViewMode}
+              />
+            </div>
+          </div>
+        </CardContent>
+      </Card>
+
+      {/* 하단 버튼 */}
+      <div className="flex justify-end gap-3">
+        <Button variant="outline" onClick={() => router.back()}>취소</Button>
+        {isViewMode ? (
+          <Button onClick={() => router.push(`?mode=edit`)}>수정</Button>
+        ) : (
+          <Button onClick={handleSubmit} disabled={isSaving}>
+            {isSaving ? '저장 중...' : '저장'}
+          </Button>
+        )}
+      </div>
+    </div>
+  );
+}
+```
+
+### 상세/폼 페이지 공통 규칙
+
+- **모드**: `view` | `edit` | `new` 3가지
+- **Hook 규칙**: 모든 hook은 최상단, 조건부 return은 그 아래
+- **레이아웃**: `Card > CardHeader + CardContent` 섹션 단위
+- **필드 그리드**: `grid grid-cols-1 md:grid-cols-2 gap-4`
+- **disabled**: view 모드에서 모든 입력 비활성화
+- **알림**: `toast.success()` / `toast.error()` (sonner)
+- **네비게이션**: `router.back()` 또는 `router.push()`
+- **로딩**: Skeleton 컴포넌트 사용
+- **Select 버그 대응**: `<Select key={...}>` 패턴 (CLAUDE.md 참조)
+
+---
+
+## 5. API 연동 패턴
+
+### Server Action 파일 구조
+
+```
+src/components/[domain]/[feature]/
+├── index.tsx        — 메인 컴포넌트 (또는 리스트)
+├── [Feature]Detail.tsx  — 상세/폼
+├── actions.ts       — Server Actions (API 호출)
+└── types.ts         — 타입 정의
+```
+
+### Server Action 패턴
+
+```typescript
+'use server';
+
+import { cookies } from 'next/headers';
+
+const API_BASE = process.env.BACKEND_API_URL;
+
+export async function getList(params?: { q?: string; page?: number; size?: number }) {
+  const cookieStore = await cookies();
+  const token = cookieStore.get('access_token')?.value;
+  if (!token) redirect('/login');
+
+  const searchParams = new URLSearchParams();
+  if (params?.q) searchParams.set('q', params.q);
+  // ...
+
+  const res = await fetch(`${API_BASE}/endpoint?${searchParams}`, {
+    headers: { Authorization: `Bearer ${token}` },
+  });
+
+  const data = await res.json();
+  return { success: true, data: data.data };
+}
+```
+
+### 클라이언트에서 호출
+
+```typescript
+// useEffect에서 호출
+useEffect(() => {
+  getList({ q: searchTerm })
+    .then(result => {
+      if (result.success) setData(result.data);
+      else toast.error(result.error);
+    });
+}, [searchTerm]);
+
+// SearchableSelectionModal의 fetchData에서 호출
+const handleFetchData = useCallback(async (query: string) => {
+  const result = await getList({ q: query });
+  if (result.success) return result.data;
+  toast.error(result.error);
+  return [];
+}, []);
+```
+
+---
+
+## 6. 페이지 라우팅 구조
+
+```
+src/app/[locale]/(protected)/[domain]/
+├── [list-page]/
+│   └── page.tsx              → <ListComponent />
+├── [detail-page]/
+│   ├── [id]/
+│   │   └── page.tsx          → <DetailComponent id={id} mode="view|edit" />
+│   └── new/
+│       └── page.tsx          → <DetailComponent mode="new" />
+```
+
+### page.tsx 패턴
+
+```typescript
+// 리스트
+'use client';
+import { MyList } from '@/components/[domain]/[Feature]';
+export default function Page() { return <MyList />; }
+
+// 상세 (view/edit)
+'use client';
+import { useParams, useSearchParams } from 'next/navigation';
+export default function Page() {
+  const { id } = useParams();
+  const mode = useSearchParams().get('mode') === 'edit' ? 'edit' : 'view';
+  return <MyDetail id={id as string} mode={mode} />;
+}
+
+// 신규
+'use client';
+export default function Page() { return <MyDetail mode="new" />; }
+```
+
+---
+
+## 변경 이력
+
+| 날짜 | 내용 |
+|------|------|
+| 2026-02-10 | 초기 작성: 검색 모달, 리스트, 상세/폼, API 패턴 |

claudedocs/guides/[IMPL-2025-11-06] i18n-usage-guide.md

@@ -6,6 +6,154 @@
 
 ---
 
+## 적용 현황 분석 (2026-02-03 기준)
+
+### 인프라 상태: 완비
+
+| 항목 | 상태 | 설명 |
+|------|------|------|
+| 라이브러리 | `next-intl` ^4.4.0 | 설치 및 설정 완료 |
+| 지원 언어 | ko, en, ja | 3개 locale |
+| 번역 파일 | `src/messages/{ko,en,ja}.json` | 13개 네임스페이스, ~215개 키 |
+| 미들웨어 | `src/middleware.ts` | locale 라우팅 + 인증 통합 완료 |
+| Provider | `[locale]/layout.tsx` | `NextIntlClientProvider` 정상 |
+| URL 라우팅 | `localePrefix: 'as-needed'` | ko는 URL 생략, en/ja는 prefix |
+
+### 실제 적용 현황: 극히 일부만 적용
+
+**`useTranslations` 사용 중인 파일: 3개 (전체의 ~1% 미만)**
+
+| 파일 | 사용 네임스페이스 |
+|------|-------------------|
+| `src/components/auth/LoginPage.tsx` | auth, common, validation |
+| `src/components/auth/SignupPage.tsx` | auth, signup, validation |
+| `src/app/[locale]/layout.tsx` | Provider 설정만 |
+
+**하드코딩된 한국어가 있는 파일: ~1,131개**
+
+### 영역별 하드코딩 현황
+
+| 영역 | 파일 수 | 주요 내용 |
+|------|---------|----------|
+| `business/` (건설) | ~171 | 계약, 입찰, 견적, 기성, 현장관리, 노무, 단가 |
+| `items/` (품목) | ~101 | 품목마스터, BOM, 폼, 동적 품목관리 |
+| `accounting/` (회계) | ~69 | 거래처, 입출금, 매출, 매입, 어음, 카드 |
+| `settings/` (설정) | ~59 | 계정, 권한, 팝업, 구독, 회사정보, 직급, 휴가정책 |
+| `hr/` (인사) | ~45 | 직원, 근태, 휴가, 급여, 카드, 부서 |
+| `production/` (생산) | ~38 | 작업지시, 작업일지, 검사, 작업자화면 |
+| `ui/` (공통 UI) | ~26 | file-list, confirm-dialog, error-card, inputs 등 |
+| `approval/` (결재) | ~26 | 결재 워크플로우, 문서생성, 상세 |
+| `quotes/` (견적) | ~21 | 견적 등록, 관리, 문서, 계산 |
+| `outbound/` (출고) | ~21 | 출고증, 배차차량 |
+| `quality/` (품질) | ~13 | 제품검사, 수입검사 |
+| 기타 (dashboard, board 등) | ~541 | 대시보드, 게시판, CRM 등 |
+
+### 하드코딩 유형 분류
+
+**1. Config 파일 (~47개)** - 페이지 타이틀, 설명, 라벨
+```typescript
+// 예: vehicleDispatchConfig.ts
+title: '배차차량 상세',
+description: '배차차량 정보를 조회합니다',
+backLabel: '목록',
+```
+
+**2. JSX 직접 텍스트** - 버튼, 라벨, placeholder
+```tsx
+<Button>삭제</Button>
+placeholder="거래처명"
+<Label>비고</Label>
+```
+
+**3. 토스트/알림 메시지**
+```typescript
+toast.success('저장되었습니다');
+toast.error('삭제에 실패했습니다');
+```
+
+**4. 상태/상수 정의 (types.ts)**
+```typescript
+export const STATUS_LABELS = { draft: '작성대기', completed: '작성완료' };
+export const FREIGHT_COST_LABELS = { prepaid: '선불', collect: '착불' };
+```
+
+**5. 로딩/에러 상태**
+```typescript
+if (isLoading) return <div>로딩 중...</div>;  // 79+ 인스턴스
+```
+
+**6. Mock 데이터 (~7개)**
+```typescript
+siteName: '위브 청라',
+orderCustomer: '두산건설(주)',
+```
+
+### 번역 파일 동기화 상태
+
+| 비교 | 상태 | 이슈 |
+|------|------|------|
+| ko ↔ en | 동기화 완료 | 231줄 일치 |
+| ko ↔ ja | 1건 누락 | `auth.loggingIn` 키 없음 (ja.json) |
+
+### 현재 번역 파일 네임스페이스
+
+```
+common       : ~25개 키 (기본 UI 액션)
+auth         : ~63개 키 (로그인, 회원가입, 역할, 직급)
+signup       : ~14개 키 (업종, 회사규모)
+navigation   : ~10개 키 (메인 메뉴)
+dashboard    : ~10개 키 (대시보드 위젯)
+inventory    : ~15개 키 (재고관리)
+finance      : ~11개 키 (회계)
+hr           : ~14개 키 (인사)
+crm          : ~8개 키 (고객관리)
+settings     : ~13개 키 (설정)
+errors       : ~7개 키 (에러 메시지)
+validation   : ~6개 키 (폼 유효성)
+messages     : ~8개 키 (성공/실패 알림)
+```
+
+### 작업 규모 (전체 적용 시)
+
+| 작업 항목 | 수량 | 비고 |
+|-----------|------|------|
+| 번역 키 추출 대상 파일 | ~1,131개 | 반복적 패턴 작업 |
+| 추가 필요 번역 키 (추정) | ~3,000~5,000개 | 3개 언어 동기화 필요 |
+| Config 파일 전환 | ~47개 | 패턴 동일, 일괄 처리 가능 |
+| 공통 UI 컴포넌트 | ~26개 | 영향 범위 넓음 (전체 앱) |
+| 비즈니스 컴포넌트 | ~1,000+개 | 단순 반복이나 양 많음 |
+
+### 단계별 적용 계획 (권장)
+
+**Phase 1: 공통 기반** - 효과 가장 큼
+- 공통 UI 컴포넌트 26개 (confirm-dialog, error-card, inputs 등)
+- 공통 라벨 (저장, 삭제, 취소, 검색, 로딩 중... 등)
+- "로딩 중..." 같은 반복 문자열 일괄 처리
+- 이것만 해도 전체 앱에 영향
+
+**Phase 2: Config 파일** - 기계적 작업
+- 47개 config 파일의 title/description/label
+- 패턴이 동일해서 일괄 처리 가능
+
+**Phase 3: 영역별 비즈니스 컴포넌트**
+- accounting (69개) → hr (45개) → production (38개) → ...
+- 영역당 번역 네임스페이스 1개씩 추가
+- business/ (171개)가 가장 큰 덩어리
+
+**Phase 4: 나머지 + 검증**
+- 누락 확인, 빌드 테스트
+- 실제 언어 전환 테스트 (ko → en → ja)
+- ja.json `auth.loggingIn` 누락 수정
+
+### 즉시 수정 필요 사항
+
+1. **ja.json 누락 키**: `auth.loggingIn` 추가 필요
+   - ko: `"loggingIn": "로그인 중..."`
+   - en: `"loggingIn": "Logging in..."`
+   - ja: (누락) → `"loggingIn": "ログイン中..."` 추가
+
+---
+
 ## 📦 설치된 패키지
 
 ```json
@@ -697,6 +845,7 @@ export default function ClientComponent() {
 | 날짜 | 버전 | 변경 내용 |
 |-----|------|---------|
 | 2025-11-06 | 1.0.0 | 초기 i18n 설정 구현 (ko, en, ja 지원) |
+| 2026-02-03 | 1.1.0 | 전체 프로젝트 다국어 적용 현황 분석 추가 (하드코딩 현황, 단계별 적용 계획) |
 
 ---
 

claudedocs/guides/badge-commonization-guide.md

@@ -0,0 +1,276 @@
+# Badge 공통화 가이드
+
+> 작성일: 2026-02-05
+> 목적: 리스트 페이지에서 Badge 스타일을 공통 유틸로 통일하는 방법 안내
+
+---
+
+## 📦 공통 유틸 위치
+
+```
+src/lib/utils/status-config.ts    ← Badge 스타일 및 상태 설정
+src/lib/constants/filter-presets.ts ← 필터 프리셋
+```
+
+---
+
+## 🎨 1. 프리셋 스타일 사용하기
+
+### 사용 가능한 프리셋
+
+| 프리셋 | 스타일 | 용도 |
+|--------|--------|------|
+| `default` | `bg-gray-100 text-gray-800` | 기본/일반 |
+| `success` | `bg-green-100 text-green-800` | 완료/성공/활성 |
+| `warning` | `bg-yellow-100 text-yellow-800` | 대기/주의 |
+| `destructive` | `bg-red-100 text-red-800` | 오류/반려/긴급 |
+| `info` | `bg-blue-100 text-blue-800` | 진행중/정보 |
+| `muted` | `bg-gray-100 text-gray-500` | 비활성/무효 |
+| `orange` | `bg-orange-100 text-orange-800` | 우선/경고 |
+| `purple` | `bg-purple-100 text-purple-800` | 제품/특수 |
+
+### 기본 사용법
+
+```tsx
+import { getPresetStyle } from '@/lib/utils/status-config';
+
+// 프리셋 스타일 가져오기
+const style = getPresetStyle('success'); // "bg-green-100 text-green-800"
+
+// Badge에 적용
+<Badge className={getPresetStyle('warning')}>대기</Badge>
+```
+
+---
+
+## 🏷️ 2. 우선순위 Badge
+
+### 공통 유틸 사용
+
+```tsx
+import { getPriorityLabel, getPriorityStyle } from '@/lib/utils/status-config';
+
+// 우선순위 Badge 렌더링
+function PriorityBadge({ priority }: { priority: string }) {
+  return (
+    <Badge variant="outline" className={getPriorityStyle(priority)}>
+      {getPriorityLabel(priority)}
+    </Badge>
+  );
+}
+
+// 사용
+<PriorityBadge priority="urgent" />  // 긴급 (빨간색)
+<PriorityBadge priority="priority" /> // 우선 (주황색)
+<PriorityBadge priority="normal" />   // 일반 (회색)
+```
+
+### Before (개별 정의) ❌
+
+```tsx
+// 각 페이지마다 반복되던 코드
+const PRIORITY_COLORS: Record<string, string> = {
+  '긴급': 'bg-red-100 text-red-700',
+  '우선': 'bg-orange-100 text-orange-700',
+  '일반': 'bg-gray-100 text-gray-700',
+};
+```
+
+### After (공통 유틸) ✅
+
+```tsx
+import { getPriorityLabel, getPriorityStyle } from '@/lib/utils/status-config';
+
+<Badge className={getPriorityStyle(item.priority)}>
+  {getPriorityLabel(item.priority)}
+</Badge>
+```
+
+---
+
+## 📦 3. 품목 유형 Badge
+
+### 공통 유틸 사용
+
+```tsx
+import { getItemTypeLabel, getItemTypeStyle } from '@/lib/utils/status-config';
+
+// 품목 유형 Badge 렌더링
+function ItemTypeBadge({ itemType }: { itemType: string }) {
+  return (
+    <Badge variant="outline" className={getItemTypeStyle(itemType)}>
+      {getItemTypeLabel(itemType)}
+    </Badge>
+  );
+}
+
+// 사용
+<ItemTypeBadge itemType="FG" /> // 제품 (보라색)
+<ItemTypeBadge itemType="PT" /> // 부품 (주황색)
+<ItemTypeBadge itemType="SM" /> // 부자재 (녹색)
+<ItemTypeBadge itemType="RM" /> // 원자재 (파란색)
+<ItemTypeBadge itemType="CS" /> // 소모품 (회색)
+```
+
+---
+
+## 🔧 4. 커스텀 상태 설정 만들기
+
+### createStatusConfig 사용법
+
+```tsx
+import { createStatusConfig } from '@/lib/utils/status-config';
+
+// 도메인별 커스텀 상태 정의
+const {
+  STATUS_OPTIONS,    // Select 옵션용
+  STATUS_LABELS,     // 라벨 맵
+  STATUS_STYLES,     // 스타일 맵
+  getStatusLabel,    // 라벨 헬퍼
+  getStatusStyle,    // 스타일 헬퍼
+} = createStatusConfig({
+  draft: { label: '임시저장', style: 'muted' },
+  pending: { label: '승인대기', style: 'warning' },
+  approved: { label: '승인완료', style: 'success' },
+  rejected: { label: '반려', style: 'destructive' },
+}, { includeAll: true, allLabel: '전체' });
+
+// 사용
+<Badge className={getStatusStyle(item.status)}>
+  {getStatusLabel(item.status)}
+</Badge>
+
+// Select 옵션으로도 사용 가능
+<Select>
+  {STATUS_OPTIONS.map(opt => (
+    <SelectItem key={opt.value} value={opt.value}>{opt.label}</SelectItem>
+  ))}
+</Select>
+```
+
+---
+
+## ✅ 5. 미리 정의된 공통 설정 사용하기
+
+### 바로 사용 가능한 설정들
+
+```tsx
+import {
+  COMMON_STATUS_CONFIG,    // 대기/진행/완료
+  WORK_STATUS_CONFIG,      // 작업대기/진행중/작업완료
+  APPROVAL_STATUS_CONFIG,  // 승인대기/승인완료/반려
+  ACTIVE_STATUS_CONFIG,    // 활성/비활성
+  SHIPMENT_STATUS_CONFIG,  // 출고예정/대기/중/완료
+  RECEIVING_STATUS_CONFIG, // 입고예정/대기/검사중/완료/반품
+} from '@/lib/utils/status-config';
+
+// 사용 예시
+<Badge className={COMMON_STATUS_CONFIG.getStatusStyle(item.status)}>
+  {COMMON_STATUS_CONFIG.getStatusLabel(item.status)}
+</Badge>
+
+// 필터 옵션으로 사용
+filterConfig: [
+  {
+    key: 'status',
+    label: '상태',
+    type: 'single',
+    options: WORK_STATUS_CONFIG.STATUS_OPTIONS.filter(opt => opt.value !== 'all'),
+  },
+],
+```
+
+---
+
+## 🔄 6. 마이그레이션 체크리스트
+
+### 기존 코드에서 공통 유틸로 전환하기
+
+1. **우선순위 색상 정의 찾기**
+   ```bash
+   # 검색
+   grep -r "PRIORITY_COLORS" src/components/
+   grep -r "'긴급'" src/components/
+   ```
+
+2. **import 추가**
+   ```tsx
+   import { getPriorityLabel, getPriorityStyle } from '@/lib/utils/status-config';
+   ```
+
+3. **기존 코드 교체**
+   ```tsx
+   // Before
+   const color = PRIORITY_COLORS[item.priority] || '';
+   <Badge className={color}>{item.priority}</Badge>
+
+   // After
+   <Badge className={getPriorityStyle(item.priority)}>
+     {getPriorityLabel(item.priority)}
+   </Badge>
+   ```
+
+4. **기존 상수 정의 삭제**
+   ```tsx
+   // 삭제
+   const PRIORITY_COLORS: Record<string, string> = { ... };
+   ```
+
+---
+
+## 📋 7. 필터 프리셋 함께 사용하기
+
+### filter-presets.ts와 연계
+
+```tsx
+import { COMMON_PRIORITY_FILTER, WORK_STATUS_FILTER } from '@/lib/constants/filter-presets';
+import { getPriorityStyle, WORK_STATUS_CONFIG } from '@/lib/utils/status-config';
+
+// UniversalListPage config
+const config: UniversalListConfig<MyItem> = {
+  // ...
+
+  // 필터 설정 (공통 프리셋 사용)
+  filterConfig: [
+    WORK_STATUS_FILTER,
+    COMMON_PRIORITY_FILTER,
+  ],
+
+  // 테이블 행에서 Badge 사용 (공통 스타일 사용)
+  renderTableRow: (item, index, globalIndex, handlers) => (
+    <TableRow>
+      {/* ... */}
+      <TableCell>
+        <Badge className={WORK_STATUS_CONFIG.getStatusStyle(item.status)}>
+          {WORK_STATUS_CONFIG.getStatusLabel(item.status)}
+        </Badge>
+      </TableCell>
+      <TableCell>
+        <Badge className={getPriorityStyle(item.priority)}>
+          {getPriorityLabel(item.priority)}
+        </Badge>
+      </TableCell>
+    </TableRow>
+  ),
+};
+```
+
+---
+
+## 📊 변경 효과
+
+| 항목 | Before | After |
+|------|--------|-------|
+| 우선순위 색상 정의 | 각 페이지 개별 | 1곳 (status-config.ts) |
+| 품목유형 색상 정의 | 각 페이지 개별 | 1곳 (status-config.ts) |
+| 색상 변경 시 | 모든 파일 수정 | 1개 파일만 수정 |
+| 일관성 | 파일마다 다를 수 있음 | 항상 동일 |
+| 신규 개발 시 | 기존 코드 복사 필요 | import만 하면 됨 |
+
+---
+
+## 🚨 주의사항
+
+1. **기존 기능 유지**: 마이그레이션 시 동작이 동일한지 확인
+2. **점진적 적용**: 한 번에 모든 파일 변경하지 말고, 수정하는 파일만 적용
+3. **테스트**: Badge 색상이 기존과 동일하게 표시되는지 확인

claudedocs/guides/migration/[IMPL-2026-02-06] datepicker-migration-checklist.md

@@ -0,0 +1,106 @@
+# DatePicker 전체 교체 계획서
+
+> `input type="date"` → `DatePicker` 컴포넌트 교체
+> 작성일: 2026-02-06
+
+## 개요
+- 기존 브라우저 기본 `input type="date"`를 공통 `DatePicker` 컴포넌트로 교체
+- 공휴일/토요일/일요일 색상, 연월 직접 선택, 오늘 버튼 등 통일된 UX 제공
+
+## 교체 패턴
+```tsx
+// Before
+<Input type="date" value={value} onChange={(e) => setValue(e.target.value)} />
+
+// After
+import { DatePicker } from '@/components/ui/date-picker';
+<DatePicker value={value} onChange={setValue} />
+```
+
+---
+
+## Phase 1: 공통 템플릿 (우선 - 파급 효과 큼) ✅ 완료
+- [x] `molecules/DateRangeSelector.tsx` (4곳)
+- [x] `molecules/FormField.tsx` (1곳)
+- [x] `templates/IntegratedDetailTemplate/FieldRenderer.tsx` (1곳)
+- [x] `templates/IntegratedDetailTemplate/FieldInput.tsx` (1곳)
+- [x] `items/DynamicItemForm/fields/DateField.tsx` (1곳)
+
+## Phase 2: 회계 ✅ 완료
+- [x] `accounting/DepositManagement/DepositDetail.tsx` (1곳)
+- [x] `accounting/WithdrawalManagement/WithdrawalDetail.tsx` (1곳)
+- [x] `accounting/BadDebtCollection/BadDebtDetail.tsx` (2곳)
+- [x] `accounting/DailyReport/index.tsx` (1곳)
+- [x] `accounting/PurchaseManagement/PurchaseDetailModal.tsx` (1곳)
+- [x] `accounting/PurchaseManagement/PurchaseDetail.tsx` (1곳)
+- [x] `accounting/BillManagement/BillDetailV2.tsx` (3곳)
+- [x] `accounting/BillManagement/BillDetail.tsx` (3곳)
+- [x] `accounting/SalesManagement/SalesDetail.tsx` (1곳)
+
+## Phase 3: 건설/현장 ✅ 완료
+- [x] `construction/bidding/BiddingDetailForm.tsx` (5곳)
+- [x] `construction/site-briefings/SiteBriefingForm.tsx` (2곳)
+- [x] `construction/issue-management/IssueDetailForm.tsx` (2곳)
+- [x] `construction/structure-review/StructureReviewDetailForm.tsx` (2곳)
+- [x] `construction/contract/ContractDetailForm.tsx` (3곳)
+- [x] `construction/management/ConstructionDetailClient.tsx` (1곳)
+- [x] `construction/management/ProjectEndDialog.tsx` (2곳)
+- [x] `construction/estimates/sections/EstimateInfoSection.tsx` (3곳)
+- [x] `construction/order-management/cards/ConstructionDetailCard.tsx` (2곳)
+- [x] `construction/order-management/tables/OrderDetailItemTable.tsx` (5곳)
+- [x] `construction/handover-report/HandoverReportDetailForm.tsx` (3곳)
+
+## Phase 4: 주문/견적/단가 ✅ 완료
+- [x] `quotes/QuoteRegistrationV2.tsx` (1곳)
+- [x] `quotes/QuoteRegistration.tsx` (2곳)
+- [x] `orders/OrderSalesDetailEdit.tsx` (2곳)
+- [x] `orders/OrderRegistration.tsx` (2곳)
+- [x] `pricing/PricingFormClient.tsx` (2곳)
+- [x] `pricing-distribution/PriceDistributionDetail.tsx` (1곳)
+
+## Phase 5: 인사 ✅ 완료
+- [x] `hr/VacationManagement/VacationRequestDialog.tsx` (2곳)
+- [x] `hr/VacationManagement/VacationGrantDialog.tsx` (1곳)
+- [x] `hr/EmployeeManagement/EmployeeDialog.tsx` (1곳)
+- [x] `hr/EmployeeManagement/EmployeeForm.tsx` (2곳)
+
+## Phase 6: 품질 ✅ 완료
+- [x] `quality/InspectionManagement/InspectionCreate.tsx` (3곳)
+- [x] `quality/InspectionManagement/InspectionDetail.tsx` (3곳)
+
+## Phase 7: 생산/자재/출고 ✅ 완료
+- [x] `production/WorkOrders/WorkOrderCreate.tsx` (1곳)
+- [x] `production/WorkOrders/WorkOrderEdit.tsx` (1곳)
+- [x] `production/WorkerScreen/index.tsx` (1곳)
+- [x] `material/ReceivingManagement/InspectionCreate.tsx` (1곳)
+- [x] `material/ReceivingManagement/ReceivingDetail.tsx` (2곳)
+- [x] `outbound/ShipmentManagement/ShipmentCreate.tsx` (2곳)
+- [x] `outbound/ShipmentManagement/ShipmentEdit.tsx` (2곳)
+
+## Phase 8: 결재/설정/기타 ✅ 완료
+- [x] `approval/DocumentCreate/ProposalForm.tsx` (1곳)
+- [x] `approval/DocumentCreate/ExpenseReportForm.tsx` (2곳)
+- [x] `settings/PopupManagement/PopupForm.tsx` (2곳)
+- [x] `items/ItemForm/forms/ProductForm.tsx` (2곳)
+- [x] `app/sales/order-management-sales/[id]/edit/page.tsx` (2곳)
+
+## 제외 대상
+- ~~`hr/documents/page.tsx`~~ - 메뉴 미연결 페이지
+- ~~`hr/documents/new/page.tsx`~~ - 메뉴 미연결 페이지
+- ~~`CEODashboard/TodayIssueSection.tsx`~~ - 이미 적용 완료
+- ~~`CEODashboard/ScheduleDetailModal.tsx`~~ - 이미 적용 완료
+
+---
+
+## 진행 상황
+| Phase | 파일 수 | 완료 | 상태 |
+|-------|---------|------|------|
+| 1. 공통 템플릿 | 5 | 5 | ✅ 완료 |
+| 2. 회계 | 9 | 9 | ✅ 완료 |
+| 3. 건설/현장 | 11 | 11 | ✅ 완료 |
+| 4. 주문/견적/단가 | 6 | 6 | ✅ 완료 |
+| 5. 인사 | 4 | 4 | ✅ 완료 |
+| 6. 품질 | 2 | 2 | ✅ 완료 |
+| 7. 생산/자재/출고 | 7 | 7 | ✅ 완료 |
+| 8. 결재/설정/기타 | 5 | 5 | ✅ 완료 |
+| **합계** | **49** | **49** | ✅ 전체 완료 |

claudedocs/guides/mobile/[FIX-2026-02-04] mobile-zoom-panning.md

@@ -0,0 +1,67 @@
+# [FIX] 모바일 핀치 줌 후 좌우 패닝 안 되는 문제
+
+## 문제
+- 모바일(iOS Safari, Android Chrome 동일)에서 핀치 줌으로 확대 후 **상하 스크롤은 되지만 좌우 이동(패닝)이 안 됨**
+
+## 원인 분석
+
+### 근본 원인: 모바일 레이아웃의 app-shell 패턴
+`AuthenticatedLayout.tsx`의 모바일 레이아웃이 **자체 스크롤 컨테이너**를 만들어 브라우저의 뷰포트 패닝을 가로챔.
+
+#### 문제가 된 3가지 요소
+
+| 요소 | 코드 | 문제 |
+|------|------|------|
+| 부모 div 고정 높이 | `style={{ height: 'var(--app-height)' }}` | 레이아웃을 뷰포트에 가둠 |
+| main overflow | `overflow-y-auto` / `overflow-auto` | main을 스크롤 컨테이너로 만듦 |
+| overscroll 차단 | `overscroll-contain` | 스크롤 이벤트 전파 차단 |
+
+#### 동작 메커니즘
+1. 핀치 줌 → 브라우저 visual viewport 확대
+2. 좌우 패닝 시도 → 터치 이벤트가 `<main>` 스크롤 컨테이너에 도달
+3. `<main>`에 가로 오버플로우 콘텐츠 없음 → 스크롤 불가
+4. `overscroll-behavior: contain` → 브라우저 뷰포트 패닝으로 전파 차단
+5. 결과: 좌우 이동 불가
+
+### 시도했지만 효과 없었던 방법들
+- `touchAction: 'pan-x pan-y pinch-zoom'` → 스크롤 컨테이너가 이벤트 가로채서 무효
+- `touchAction: 'manipulation'` → 동일
+- `html { touch-action: manipulation }` → 하위 스크롤 컨테이너가 우선
+- `overscrollBehaviorX: auto` 단독 적용 → 부모 고정 높이가 여전히 제약
+
+## 해결
+
+### 변경 사항
+
+**`src/layouts/AuthenticatedLayout.tsx`**
+
+```tsx
+// Before
+<div className="flex flex-col bg-background min-h-screen" style={{ height: 'var(--app-height)' }}>
+  ...
+  <main className="flex-1 overflow-y-auto px-3 overscroll-contain" style={{ WebkitOverflowScrolling: 'touch', touchAction: 'pan-y pinch-zoom' }}>
+
+// After
+<div className="flex flex-col bg-background min-h-screen">
+  ...
+  <main className="flex-1 px-3">
+```
+
+**`src/app/globals.css`** (추가)
+
+```css
+html {
+  touch-action: manipulation;
+}
+```
+
+### 핵심 원리
+- 부모 div의 `height: var(--app-height)` 제거 → 레이아웃이 자연스럽게 확장
+- `<main>`의 `overflow-auto`, `overscroll-contain` 제거 → 스크롤 컨테이너 해제
+- 스크롤이 body/html 레벨로 이동 → 브라우저가 줌 패닝 정상 처리
+
+### 확인 사항
+- [x] 핀치 줌 후 좌우 패닝
+- [ ] 일반 상하 스크롤
+- [ ] 헤더 sticky 유지
+- [ ] 데스크톱 레이아웃 영향 없음 (별도 분기)

claudedocs/item-master/[API-REQUEST-2026-02-12] dynamic-field-type-backend-spec.md

@@ -0,0 +1,390 @@
+# 동적 필드 타입 확장 — 백엔드 API 스펙
+
+> 작성일: 2026-02-12
+> 프론트 구현 완료: `[IMPL-2026-02-11] dynamic-field-components.md`
+> 설계 근거: `[DESIGN-2026-02-11] dynamic-field-type-extension.md`
+
+---
+
+## 요약
+
+프론트엔드에서 **14종 필드 타입** + **table 섹션 타입** + **조건부 표시 연산자 9종**을 렌더링할 준비가 완료되었습니다.
+
+백엔드에서 해당 `field_type`과 `properties` JSON을 DB에 저장하고 API로 반환하면, 프론트에서 추가 작업 없이 자동 렌더링됩니다.
+
+---
+
+## 1. field_type 확장
+
+### 현재 (6종)
+```
+textbox | number | dropdown | checkbox | date | textarea
+```
+
+### 추가 필요 (8종)
+```
+reference | multi-select | file | currency | unit-value | radio | toggle | computed
+```
+
+### 전체 (14종)
+```sql
+-- item_fields.field_type 컬럼의 허용값
+ENUM('textbox', 'number', 'dropdown', 'checkbox', 'date', 'textarea',
+     'reference', 'multi-select', 'file',
+     'currency', 'unit-value', 'radio',
+     'toggle', 'computed')
+```
+
+### 영향 범위
+- `item_fields` 테이블의 `field_type` 컬럼
+- `item_master_fields` 테이블의 `field_type` 컬럼 (deprecated지만 아직 사용 중이면)
+- 필드 생성/수정 API의 validation rule
+
+---
+
+## 2. 각 field_type별 properties JSON 스펙
+
+모든 설정은 기존 `item_fields.properties` JSON 컬럼에 저장합니다.
+
+### 2-1. reference (다른 테이블 검색/선택)
+
+```jsonc
+{
+  "source": "vendors",        // 필수. 프리셋: vendors|items|customers|employees|warehouses|processes|equipment|sites|vehicles
+  "displayField": "name",     // 선택. 기본 "name"
+  "valueField": "id",         // 선택. 기본 "id"
+  "searchFields": ["name"],   // 선택. 검색 대상 필드
+  "searchApiUrl": "/api/...", // source="custom"일 때만 필수
+  "columns": [                // 선택. 검색 모달 표시 컬럼
+    { "key": "code", "label": "코드", "width": "100px" },
+    { "key": "name", "label": "이름" }
+  ],
+  "displayFormat": "{code} - {name}",  // 선택. 선택 후 표시 포맷
+  "returnFields": ["id", "code", "name"] // 선택. 프론트에 반환할 필드
+}
+```
+
+**저장값**: `string` (선택한 항목의 valueField 값, 기본 id)
+
+**프론트 동작**: source 프리셋이 있으면 `/api/proxy/{source}?search={query}` 호출. 없으면 searchApiUrl 사용.
+
+---
+
+### 2-2. multi-select (복수 선택 태그)
+
+```jsonc
+{
+  "maxSelections": 5,       // 선택. 최대 선택 수 (기본: 무제한)
+  "allowCustom": false,     // 선택. 직접 입력 허용 (기본: false)
+  "layout": "chips"         // 선택. "chips" | "list" (기본: "chips")
+}
+```
+
+**options**: 기존 dropdown과 동일 `[{label, value}]` — `item_fields.options` 컬럼 사용
+
+**저장값**: `string[]` JSON (예: `["CUT","BEND","WELD"]`)
+
+---
+
+### 2-3. file (파일/이미지 첨부)
+
+```jsonc
+{
+  "accept": ".pdf,.doc,.jpg,.png",  // 선택. 허용 확장자 (기본: "*")
+  "maxSize": 10485760,              // 선택. 최대 파일 크기 bytes (기본: 10MB)
+  "maxFiles": 3,                    // 선택. 최대 파일 수 (기본: 1)
+  "preview": true,                  // 선택. 이미지 미리보기 (기본: true)
+  "category": "drawing"             // 선택. 파일 카테고리 태그
+}
+```
+
+**저장값**: 파일 업로드 후 반환된 URL 또는 file ID
+
+**필요 API**: `POST /v1/files/upload` (multipart) — 이미 있으면 그대로 사용
+
+---
+
+### 2-4. currency (통화 금액)
+
+```jsonc
+{
+  "currency": "KRW",       // 선택. 기본 "KRW". 지원: KRW|USD|EUR|JPY|CNY|GBP
+  "precision": 0,          // 선택. 소수점 자리 (기본: 0)
+  "showSymbol": true,      // 선택. 통화 기호 표시 (기본: true)
+  "allowNegative": false   // 선택. 음수 허용 (기본: false)
+}
+```
+
+**저장값**: `number` (포맷 없는 원시 숫자)
+
+---
+
+### 2-5. unit-value (값 + 단위 조합)
+
+```jsonc
+{
+  "units": [                // 필수. 단위 목록
+    { "label": "mm", "value": "mm" },
+    { "label": "cm", "value": "cm" },
+    { "label": "m", "value": "m" }
+  ],
+  "defaultUnit": "mm",     // 선택. 기본 단위
+  "precision": 2            // 선택. 소수점 자리
+}
+```
+
+**저장값**: `{"value": 100, "unit": "mm"}` JSON
+
+---
+
+### 2-6. radio (라디오 버튼 그룹)
+
+```jsonc
+{
+  "layout": "horizontal"   // 선택. "horizontal" | "vertical" (기본: "vertical")
+}
+```
+
+**options**: 기존 dropdown과 동일 `[{label, value}]` — `item_fields.options` 컬럼 사용
+
+**저장값**: `string` (선택한 value)
+
+---
+
+### 2-7. toggle (On/Off 스위치)
+
+```jsonc
+{
+  "onLabel": "사용",        // 선택. 기본 "ON"
+  "offLabel": "미사용",     // 선택. 기본 "OFF"
+  "onValue": "Y",          // 선택. 기본 "true"
+  "offValue": "N"           // 선택. 기본 "false"
+}
+```
+
+**저장값**: `string` (onValue 또는 offValue)
+
+---
+
+### 2-8. computed (계산 필드, 읽기전용)
+
+```jsonc
+{
+  "formula": "unit_price * quantity",  // 필수. 수식 (field_key 참조)
+  "dependsOn": ["unit_price", "quantity"], // 필수. 의존 필드 field_key 목록
+  "format": "currency",               // 선택. "currency" | "number" | "percent"
+  "precision": 0                       // 선택. 소수점 자리
+}
+```
+
+**저장값**: `number` (프론트에서 자동 계산, 백엔드 저장 시에도 계산 검증 권장)
+
+**지원 연산**: `+`, `-`, `*`, `/`, `(`, `)` — field_key를 변수로 사용
+
+---
+
+## 3. section type 확장
+
+### 현재
+```sql
+item_sections.type: ENUM('fields', 'bom')
+```
+
+### 추가 필요
+```sql
+item_sections.type: ENUM('fields', 'bom', 'table')
+```
+
+### table 섹션의 properties JSON
+
+`item_sections.properties` 컬럼 (신규 또는 기존 description 등과 함께):
+
+```jsonc
+{
+  "tableConfig": {
+    "columns": [
+      {
+        "key": "process_name",      // 컬럼 키
+        "label": "공정명",          // 컬럼 헤더
+        "fieldType": "reference",   // 셀 입력 타입 (ItemFieldType)
+        "width": "150px",          // 선택
+        "isRequired": true,        // 선택
+        "isReadonly": false,       // 선택
+        "options": [...],          // dropdown/radio/multi-select용
+        "properties": {            // 해당 필드 타입의 properties
+          "source": "processes"
+        }
+      },
+      {
+        "key": "cycle_time",
+        "label": "사이클타임(초)",
+        "fieldType": "number",
+        "width": "100px"
+      }
+    ],
+    "minRows": 1,               // 선택. 최소 행 수
+    "maxRows": 30,              // 선택. 최대 행 수
+    "summaryRow": [             // 선택. 합계행
+      { "columnKey": "cycle_time", "type": "sum" },
+      { "columnKey": "setup_time", "type": "avg" }
+    ]
+  }
+}
+```
+
+**summaryRow type**: `"sum"` | `"avg"` | `"count"` | `"label"`
+
+### table 섹션 데이터 저장/조회 API
+
+```
+GET  /v1/items/{itemId}/section-data/{sectionId}
+PUT  /v1/items/{itemId}/section-data/{sectionId}
+```
+
+**요청/응답 body**:
+```jsonc
+{
+  "rows": [
+    { "process_name": "절단", "cycle_time": 30, "setup_time": 10 },
+    { "process_name": "절곡", "cycle_time": 45, "setup_time": 15 }
+  ]
+}
+```
+
+> 이미 유사한 API가 있으면 그대로 사용. 없으면 신규 생성 필요.
+
+---
+
+## 4. display_condition 연산자 확장
+
+### 현재
+```jsonc
+// item_fields.display_condition
+{
+  "fieldConditions": [
+    {
+      "fieldKey": "item_type",
+      "expectedValue": "FG",          // 정확히 일치 (equals만)
+      "targetFieldIds": ["10", "11"]
+    }
+  ]
+}
+```
+
+### 확장 (operator 필드 추가)
+
+```jsonc
+{
+  "fieldConditions": [
+    {
+      "fieldKey": "item_type",
+      "operator": "in",                // 신규: 연산자
+      "expectedValue": "FG,PT",        // in/not_in은 콤마 구분
+      "targetFieldIds": ["10", "11"]
+    },
+    {
+      "fieldKey": "quantity",
+      "operator": "greater_than",
+      "expectedValue": "100",
+      "targetSectionIds": ["5"]
+    }
+  ]
+}
+```
+
+### 지원 연산자 목록
+
+| operator | 설명 | expectedValue 형식 | 예시 |
+|----------|------|-------------------|------|
+| `equals` | 정확히 일치 (기본값) | 단일값 | `"FG"` |
+| `not_equals` | 불일치 | 단일값 | `"RM"` |
+| `in` | 목록 중 하나 일치 | 콤마 구분 | `"FG,PT,SM"` |
+| `not_in` | 목록 중 어느 것에도 불일치 | 콤마 구분 | `"RM,CS"` |
+| `greater_than` | 초과 (숫자) | 숫자 문자열 | `"100"` |
+| `less_than` | 미만 (숫자) | 숫자 문자열 | `"0"` |
+| `gte` | 이상 (숫자) | 숫자 문자열 | `"50"` |
+| `lte` | 이하 (숫자) | 숫자 문자열 | `"1000"` |
+| `contains` | 부분 문자열 포함 | 문자열 | `"강판"` |
+
+**하위호환**: `operator`가 없으면 프론트에서 `equals`로 처리. 기존 데이터 마이그레이션 불필요.
+
+---
+
+## 5. 기존 API 변경 없음 (확인)
+
+다음 API들은 이미 `field_type`과 `properties`를 통과시키므로 **변경 불필요**:
+
+| API | 용도 | 비고 |
+|-----|------|------|
+| `GET /v1/item-master/pages/{id}/structure` | 페이지 구조 조회 | field_type, properties 이미 반환 |
+| `POST /v1/item-master/fields` | 필드 생성 | field_type, properties 이미 수신 |
+| `PUT /v1/item-master/fields/{id}` | 필드 수정 | 동일 |
+| `GET /v1/item-master/init` | 초기화 조회 | field_type 이미 반환 |
+
+**변경이 필요한 부분**:
+1. `field_type` validation rule에 8종 추가
+2. `item_sections.type`에 `'table'` 추가
+3. (선택) table 섹션 데이터 저장/조회 API 신규
+
+---
+
+## 6. 작업 우선순위 제안
+
+### 즉시 (프론트와 바로 연동 가능)
+
+| # | 작업 | 난이도 | 설명 |
+|---|------|--------|------|
+| 1 | field_type 허용값 8종 추가 | 낮음 | DB ENUM 또는 validation 수정만 |
+| 2 | display_condition operator 저장 허용 | 낮음 | JSON이므로 스키마 변경 없음 |
+
+### 다음 단계
+
+| # | 작업 | 난이도 | 설명 |
+|---|------|--------|------|
+| 3 | section type 'table' 추가 | 중간 | DB + API validation |
+| 4 | table 섹션 데이터 API | 중간 | 신규 엔드포인트 (CRUD) |
+| 5 | reference 소스별 검색 API | 높음 | 각 소스(vendors, items 등)의 검색 API 표준화 |
+
+### 나중 (필요 시)
+
+| # | 작업 | 난이도 | 설명 |
+|---|------|--------|------|
+| 6 | 파일 업로드 API | 높음 | `POST /v1/files/upload` (이미 있으면 불필요) |
+| 7 | computed 필드 서버사이드 검증 | 중간 | 저장 시 수식 재계산하여 값 검증 |
+
+---
+
+## 7. 테스트 방법
+
+백엔드 작업 완료 후 확인 순서:
+
+1. **페이지 빌더** (`/dev/page-builder`)에서 신규 field_type으로 필드 추가
+2. **품목 등록** 페이지에서 해당 필드가 올바르게 렌더링되는지 확인
+3. **저장/조회** 사이클 테스트 (값이 properties 형식에 맞게 저장/복원되는지)
+
+---
+
+## 부록: 프론트 파일 매핑
+
+| field_type | 프론트 컴포넌트 | 파일 |
+|------------|---------------|------|
+| textbox | TextField | `DynamicItemForm/fields/TextField.tsx` |
+| number | NumberField | `DynamicItemForm/fields/NumberField.tsx` |
+| dropdown | DropdownField | `DynamicItemForm/fields/DropdownField.tsx` |
+| checkbox | CheckboxField | `DynamicItemForm/fields/CheckboxField.tsx` |
+| date | DateField | `DynamicItemForm/fields/DateField.tsx` |
+| textarea | TextareaField | `DynamicItemForm/fields/TextareaField.tsx` |
+| **reference** | **ReferenceField** | `DynamicItemForm/fields/ReferenceField.tsx` |
+| **multi-select** | **MultiSelectField** | `DynamicItemForm/fields/MultiSelectField.tsx` |
+| **file** | **FileField** | `DynamicItemForm/fields/FileField.tsx` |
+| **currency** | **CurrencyField** | `DynamicItemForm/fields/CurrencyField.tsx` |
+| **unit-value** | **UnitValueField** | `DynamicItemForm/fields/UnitValueField.tsx` |
+| **radio** | **RadioField** | `DynamicItemForm/fields/RadioField.tsx` |
+| **toggle** | **ToggleField** | `DynamicItemForm/fields/ToggleField.tsx` |
+| **computed** | **ComputedField** | `DynamicItemForm/fields/ComputedField.tsx` |
+
+| section type | 프론트 컴포넌트 | 파일 |
+|-------------|---------------|------|
+| fields | (기존 필드 렌더링) | `DynamicItemForm/index.tsx` |
+| bom | DynamicBOMSection | `DynamicItemForm/sections/DynamicBOMSection.tsx` |
+| **table** | **DynamicTableSection** | `DynamicItemForm/sections/DynamicTableSection.tsx` |