sam-react-prod/claudedocs/guides/[DESIGN-2026-01-02] document-modal-common-component.md

문서 모달 공통 컴포넌트 설계 요구사항

Last Updated: 2026-01-06

현황 분석

전체 문서 모달 목록 (10개)

A. juil 비즈니스 모달 (프린트 중심)

컴포넌트	용도	헤더 구성	결재라인
ProcessWorkLogPreviewModal	공정 작업일지	로고 + 제목 + 결재	3열 (자체 구현)
WorkLogModal	생산 작업일지	로고 + 제목 + 결재	3열 (자체 구현)
EstimateDocumentModal	견적서	제목 + 결재	3열 (자체 구현)
ContractDocumentModal	계약서	PDF iframe	없음
HandoverReportDocumentModal	인수인계보고서	결재 먼저	4열 (자체 구현)
OrderDocumentModal (juil)	🆕 발주서	제목만	없음

B. 수주 문서 모달

컴포넌트	용도	헤더 구성
OrderDocumentModal (orders)	수주문서 3종	제목만 (분기)

C. 전자결재 문서 (approval)

컴포넌트	용도	결재라인
ProposalDocument	품의서	⭐ ApprovalLineBox 사용
ExpenseReportDocument	지출결의서	⭐ ApprovalLineBox 사용
ExpenseEstimateDocument	지출예상내역서	⭐ ApprovalLineBox 사용

---

⭐ 기존 공통 컴포넌트 발견

ApprovalLineBox (이미 존재!)

위치: src/components/approval/DocumentDetail/ApprovalLineBox.tsx

interface ApprovalLineBoxProps {
  drafter: Approver;     // 작성자
  approvers: Approver[]; // 결재자 배열 (동적 열 개수)
}

interface Approver {
  id: string;
  name: string;
  position: string;
  department: string;
  status: 'pending' | 'approved' | 'rejected' | 'none';
  approvedAt?: string;
}

특징:

• ✅ 동적 열 개수 지원 (approvers 배열 길이에 따라)
• ✅ 상태 아이콘 표시 (승인/반려/대기)
• ✅ 구분/이름/부서 3행 구조
• ⚠️ 현재 approval 문서에서만 사용 중

문제점

• juil 문서들은 자체 결재라인 구현 (코드 중복)
• 각 문서마다 결재라인 구조가 미묘하게 다름
  • 작업일지: 작성/검토/승인 + 날짜행
  • 견적서: 작성/승인 (2열)
  • 인수인계: 작성/검토/승인/승인 (4열)

---

공통 패턴 분석

✅ 완전히 동일한 패턴

1. 모달 프레임: Radix UI Dialog
2. 인쇄 처리: print-hidden + print-area 클래스
3. 인쇄 유틸: printArea() 함수 (lib/print-utils.ts)
4. 용지 크기: max-w-[210mm] (A4 기준)
5. 레이아웃: 고정 헤더 + 버튼 영역 + 스크롤 문서 영역
6. 모달 크기: max-w-[95vw] md:max-w-[800px] lg:max-w-[900px]

🔄 변동이 심한 영역

1. 문서 헤더 레이아웃

유형	문서	구조
3열	작업일지	[로고] [제목+코드] [결재]
2열	견적서, 품의서	[제목+번호] [결재]
1열+우측	인수인계	[결재 먼저] + [기본정보]
1열 중앙	발주서, 수주문서	[제목 중앙]

2. 결재라인 구성

문서	열 구조	행 구조
작업일지	작성/검토/승인	구분/이름/부서/날짜
견적서	작성/승인	구분/이름/부서
인수인계	작성/검토/승인/승인	구분/이름/부서
전자결재	동적 (ApprovalLineBox)	구분/이름/부서

3. 버튼 영역

문서	버튼 구성
견적서	수정, 상신, 인쇄
발주서	수정, 삭제, 인쇄
전자결재	수정, 복사, 승인, 반려, 상신

---

공통 컴포넌트 제안 (수정)

1. PrintableDocumentModal (Base)

모달 프레임 + 인쇄 기능만 담당 (변경 없음)

interface PrintableDocumentModalProps {
  open: boolean;
  onOpenChange: (open: boolean) => void;
  title: string;
  width?: 'sm' | 'md' | 'lg';
  actions?: ReactNode;       // 버튼 영역
  children: ReactNode;       // 문서 본문
}

2. ApprovalLine (확장)

기존 ApprovalLineBox 확장 또는 새로 통합

interface ApprovalLineProps {
  // 방법 1: 단순 열 지정
  columns?: 2 | 3 | 4;
  approvers?: Array<{
    role: string;           // '작성' | '검토' | '승인'
    name: string;
    department?: string;
    date?: string;
    status?: 'pending' | 'approved' | 'rejected';
  }>;

  // 방법 2: 기존 ApprovalLineBox 호환
  drafter?: Approver;
  dynamicApprovers?: Approver[];

  // 옵션
  showDateRow?: boolean;    // 날짜행 표시 여부
  showStatusIcon?: boolean; // 상태 아이콘 표시 여부
}

3. DocumentHeaderLayout (프리셋)

type HeaderVariant =
  | 'three-column'   // [로고] [제목] [결재]
  | 'two-column'     // [제목+번호] [결재]
  | 'single-center'  // [제목 중앙]
  | 'approval-first' // [결재] + [정보 테이블]

<DocumentHeaderLayout variant="three-column">
  <CompanyLogo type="KD" />
  <DocumentTitle title="작업일지" code="WL-001" />
  <ApprovalLine columns={3} approvers={...} />
</DocumentHeaderLayout>

---

컴포넌트 구조 제안 (수정)

src/components/common/document/
├── PrintableDocumentModal.tsx    # 기본 모달 프레임
├── DocumentHeader/
│   ├── index.tsx                 # 헤더 레이아웃 프리셋
│   ├── DocumentTitle.tsx         # 문서 타이틀
│   └── CompanyLogo.tsx           # 회사 로고
├── ApprovalLine/
│   ├── index.tsx                 # 통합 결재라인 (★ 핵심)
│   └── ApprovalLineBox.tsx       # 기존 컴포넌트 이동/확장
├── DocumentTable/
│   ├── index.tsx                 # 기본 문서 테이블
│   ├── InfoGrid.tsx              # 정보 그리드 (2×4 등)
│   └── SummaryRow.tsx            # 합계행
└── index.ts                      # 배럴 export

---

마이그레이션 전략

Phase 1: ApprovalLine 통합 (우선)

1. 기존 ApprovalLineBox → common/document/ApprovalLine/로 이동
2. columns 기반 간단 모드 추가
3. showDateRow, showStatusIcon 옵션 추가

Phase 2: PrintableDocumentModal 생성

1. 모달 프레임 공통화
2. print-hidden/print-area 자동 적용
3. 버튼 영역 슬롯 제공

Phase 3: 기존 모달 리팩토링

순서	모달	작업량
1	WorkLogModal 계열	구조 동일, 리팩토링 쉬움
2	EstimateDocumentModal	결재라인 교체
3	전자결재 문서들	ApprovalLineBox 경로 변경만
4	OrderDocumentModal (juil)	결재라인 없음, 프레임만 적용
5	HandoverReportDocumentModal	4열 결재라인

---

결정 필요 사항

Q1. ApprovalLine 통합 방식

• A) 확장: 기존 ApprovalLineBox에 옵션 추가
• B) 새로 작성: columns 기반 단순 버전 + 기존 호환 어댑터

Q2. 위치 결정

• A) common/document/: 문서 전용 공통 컴포넌트
• B) approval/에서 re-export: 기존 위치 유지, 공용 export

Q3. 날짜행 처리

• A) 옵션화: showDateRow={true}
• B) 별도 컴포넌트: ApprovalLineWithDate

---

예상 작업량 (수정)

단계	내용	파일 수
1	ApprovalLine 통합	3개
2	PrintableDocumentModal	2개
3	DocumentHeader 컴포넌트	3개
4	기존 모달 리팩토링	10개

총 예상: ~18개 파일 수정/생성

---

참고: 인쇄 유틸리티

// src/lib/print-utils.ts
printArea(options?: { title?: string; styles?: string })

• .print-area 클래스 요소를 새 창에서 인쇄
• A4 용지 설정 자동 적용
• 기존 스타일시트 자동 로드

---

관련 파일 경로

문서 모달 관련 파일들:

src/components/
├── process-management/
│   └── ProcessWorkLogPreviewModal.tsx
├── production/WorkerScreen/
│   └── WorkLogModal.tsx
├── orders/documents/
│   └── OrderDocumentModal.tsx (수주)
├── approval/DocumentDetail/
│   ├── ApprovalLineBox.tsx ⭐ 기존 공통
│   ├── ProposalDocument.tsx
│   ├── ExpenseReportDocument.tsx
│   ├── ExpenseEstimateDocument.tsx
│   └── types.ts
└── business/juil/
    ├── estimates/modals/EstimateDocumentModal.tsx
    ├── contract/modals/ContractDocumentModal.tsx
    ├── handover-report/modals/HandoverReportDocumentModal.tsx
    └── order-management/modals/OrderDocumentModal.tsx 🆕