sam-react-prod/claudedocs/guides/[ANALYSIS] common-component-patterns.md

공통 컴포넌트 패턴 분석

Phase 3 마이그레이션 진행하면서 발견되는 공통화 후보 패턴 수집 페이지 마이그레이션 완료 후 이 리스트 기반으로 공통 컴포넌트 설계

최종 목표: IntegratedDetailTemplate Config 통합

공통 컴포넌트 추출 후 IntegratedDetailTemplate의 필드 config 옵션으로 통합

현재 지원 타입:

type: 'text' | 'select' | 'date' | 'textarea' | 'number' | 'checkbox'

확장 예정 타입:

// 주소 입력
{ name: 'address', label: '주소', type: 'address', withCoords?: boolean }

// 파일 업로드
{ name: 'files', label: '첨부파일', type: 'file-upload', maxSize?: number, multiple?: boolean, accept?: string }

// 음성 메모
{ name: 'memo', label: '메모', type: 'voice-memo' }

// 삭제 확인 (페이지 레벨 옵션)
deleteConfirm?: { title: string, message: string }

장점:

• 페이지별 config만 수정하면 UI 자동 구성
• 일관된 UX/UI 보장
• 유지보수 용이

발견된 패턴 목록

1. 주소 입력 (Address Input)

발견 위치	구성 요소	특이사항
site-management/SiteDetailForm	우편번호 찾기 버튼 + 주소 Input + 상세주소	경도/위도 필드 별도

공통 요소:

• Daum Postcode API 연동 (useDaumPostcode 훅 이미 존재)
• 우편번호 찾기 버튼
• 기본주소 (자동 입력)
• 상세주소 (수동 입력)

변형 가능성:

• 경도/위도 필드 포함 여부
• 읽기 전용 모드 지원

---

2. 파일 업로드 (File Upload)

발견 위치	구성 요소	특이사항
site-management/SiteDetailForm	드래그앤드롭 영역 + 파일 목록	10MB 제한, 다중 파일
structure-review/StructureReviewDetailForm	드래그앤드롭 영역 + 파일 목록	10MB 제한, 다중 파일 (동일 패턴)

공통 요소:

• 드래그앤드롭 영역 (점선 박스)
• 클릭하여 파일 선택
• 드래그 중 시각적 피드백
• 파일 크기 검증

변형 가능성:

• 허용 파일 타입 (이미지만 / 문서만 / 전체)
• 단일 vs 다중 파일
• 최대 파일 크기
• 최대 파일 개수

---

3. 파일 목록 (File List)

발견 위치	구성 요소	특이사항
site-management/SiteDetailForm	파일명 + 크기 + 다운로드/삭제	view/edit 모드별 다른 액션
structure-review/StructureReviewDetailForm	파일명 + 크기 + 다운로드/삭제	동일 패턴

공통 요소:

• 파일 아이콘
• 파일명 표시
• 파일 크기 표시
• 액션 버튼

변형 가능성:

• view 모드: 다운로드 버튼
• edit 모드: 삭제(X) 버튼
• 미리보기 지원 (이미지)
• 업로드 날짜 표시 여부

---

4. 음성 녹음 (Voice Recorder)

발견 위치	구성 요소	특이사항
site-management/SiteDetailForm	녹음 버튼 (Textarea 내부)	edit 모드에서만 표시

공통 요소:

• 녹음 시작/중지 버튼
• Textarea와 연동 (STT 결과 입력)

변형 가능성:

• 버튼 위치 (Textarea 내부 / 외부)
• 녹음 시간 제한
• 녹음 중 시각적 피드백

---

5. 삭제 확인 다이얼로그 (Delete Confirmation Dialog)

발견 위치	구성 요소	특이사항
structure-review/StructureReviewDetailForm	AlertDialog + 제목 + 설명 + 취소/삭제 버튼	view 모드에서 삭제 버튼 클릭 시

공통 요소:

• AlertDialog 컴포넌트 사용
• 제목: "[항목명] 삭제"
• 설명: 삭제 확인 메시지 + 되돌릴 수 없음 경고
• 취소/삭제 버튼

변형 가능성:

• 항목명 커스터마이징
• 삭제 후 리다이렉트 경로
• 추가 경고 메시지

---

추가 예정

Phase 3 마이그레이션 진행하면서 새로운 패턴 발견 시 여기에 추가

예상 패턴 (확인 필요)

• 이미지 미리보기 (썸네일)
• 서명 입력
• 날짜/시간 선택
• 검색 가능한 Select (Combobox)
• 태그 입력
• 금액 입력 (천단위 콤마)

---

공통화 우선순위 (마이그레이션 완료 후 결정)

우선순위	패턴	사용 빈도	복잡도
-	주소 입력	1	중
-	파일 업로드	2	상
-	파일 목록	2	중
-	음성 녹음	1	상
-	삭제 확인 다이얼로그	1	하

사용 빈도는 마이그레이션 진행하면서 카운트

---

변경 이력

• 2025-01-19: 초안 작성, site-management에서 4개 패턴 발견
• 2025-01-19: structure-review에서 동일 패턴 확인 (파일 업로드/목록), 삭제 확인 다이얼로그 패턴 추가