sam-react-prod/claudedocs/architecture/[IMPL-2026-01-21] phase4-input-migration-rollout.md

Phase 4: 입력 컴포넌트 전체 적용 계획서

작성일: 2026-01-21 작성자: Claude Code 상태: 🔵 계획 수립 완료 근거 문서: [IMPL-2026-01-21] input-form-componentization.md

---

1. 스캔 결과 요약

1.1 대상 파일 통계

카테고리	파일 수	비고
type="number" 사용	52개	직접 Input 사용
전화번호 관련	70개	phone, tel, 전화, 연락처
사업자번호 관련	33개	businessNumber, 사업자번호
금액 관련	197개	price, amount, 금액, 단가
수량 관련	106개	quantity, qty, 수량

1.2 마이그레이션 접근 전략

전략 1: 템플릿 레벨 수정 (최고 효율)

• IntegratedDetailTemplate/FieldInput.tsx 수정
• IntegratedDetailTemplate/FieldRenderer.tsx 수정
• 이 템플릿을 사용하는 모든 페이지에 자동 적용

전략 2: FormField 타입 확장 (이미 완료)

• FormField.tsx에 새 타입 추가 완료
• FormField를 사용하는 컴포넌트는 타입만 변경하면 됨

전략 3: 개별 컴포넌트 수정

• 직접 <Input type="number"> 사용하는 컴포넌트
• 커스텀 로직이 있어 템플릿 적용 불가한 컴포넌트

---

2. 마이그레이션 우선순위

🔴 Tier 1: 템플릿 레벨 (최우선)

한 번 수정으로 다수 페이지에 적용

파일	수정 내용	영향 범위
IntegratedDetailTemplate/FieldInput.tsx	number 타입에 NumberInput/CurrencyInput 적용, phone/businessNumber 타입 추가	템플릿 사용 전체
IntegratedDetailTemplate/FieldRenderer.tsx	동일	템플릿 사용 전체
IntegratedDetailTemplate/types.ts	FieldType에 새 타입 추가	타입 시스템

🟠 Tier 2: 핵심 폼 컴포넌트

사용 빈도가 높거나 중요한 폼

회계 도메인 (accounting/)

파일	적용 대상	우선순위
✅ VendorDetail.tsx	phone, businessNumber, currency	완료
PurchaseDetail.tsx	currency (금액)	높음
SalesDetail.tsx	currency (금액)	높음
BillDetail.tsx	currency (금액)	높음
DepositDetail.tsx	currency (금액)	높음
WithdrawalDetail.tsx	currency (금액)	높음
BadDebtDetail.tsx	currency, phone	높음

주문/견적 도메인 (orders/, quotes/)

파일	적용 대상	우선순위
OrderRegistration.tsx	currency, quantity	높음
OrderSalesDetailEdit.tsx	currency, quantity	높음
QuoteRegistration.tsx	currency, quantity, number	높음
QuoteRegistrationV2.tsx	currency, quantity, number	높음
LocationDetailPanel.tsx	currency, quantity	중간
LocationListPanel.tsx	currency, quantity	중간

인사 도메인 (hr/)

파일	적용 대상	우선순위
EmployeeForm.tsx	phone, personalNumber	높음
EmployeeDetail.tsx	phone, personalNumber	높음
EmployeeDialog.tsx	phone	높음
SalaryDetailDialog.tsx	currency	중간
VacationRegisterDialog.tsx	number	중간
VacationGrantDialog.tsx	number	중간

고객 도메인 (clients/)

파일	적용 대상	우선순위
ClientDetail.tsx	phone, businessNumber	높음
ClientRegistration.tsx	phone, businessNumber	높음
ClientDetailClientV2.tsx	phone, businessNumber	높음

🟡 Tier 3: 보조 컴포넌트

중요하지만 사용 빈도 낮음

품목 관리 (items/)

파일	적용 대상
ItemDetailEdit.tsx	currency, quantity
ItemDetailView.tsx	currency, quantity
DynamicItemForm/	number, currency
BOMSection.tsx	quantity
ItemAddDialog.tsx (orders)	quantity, currency

자재/생산 (material/, production/)

파일	적용 대상
ReceivingDetail.tsx	quantity
ReceivingProcessDialog.tsx	quantity
StockStatusDetail.tsx	quantity
WorkOrderDetail.tsx	quantity
InspectionDetail.tsx	quantity
InspectionCreate.tsx	quantity

건설 도메인 (construction/)

파일	적용 대상
ContractDetailForm.tsx	currency
EstimateDetailForm.tsx	currency, quantity
BiddingDetailForm.tsx	currency
PartnerForm.tsx	phone, businessNumber
HandoverReportDetailForm.tsx	number
PricingDetailClient.tsx	currency
ProgressBillingItemTable.tsx	currency, quantity
OrderDetailItemTable.tsx	currency, quantity

🟢 Tier 4: 기타 컴포넌트

낮은 우선순위, 점진적 적용

설정 (settings/)

• CompanyInfoManagement/ - businessNumber
• PopupManagement/ - phone
• AddCompanyDialog.tsx - businessNumber

결재 (approval/)

• ExpenseReportForm.tsx - currency
• ProposalForm.tsx - currency

문서 컴포넌트 (documents/)

대부분 표시용으로 입력 필드 없음 - 확인 필요

• OrderDocumentModal.tsx
• TransactionDocument.tsx
• ContractDocument.tsx

---

3. 작업 단계별 계획

Phase 4-1: 템플릿 레벨 수정 (핵심)

목표: IntegratedDetailTemplate에 새 입력 타입 지원 추가

수정 파일:
1. src/components/templates/IntegratedDetailTemplate/types.ts
   - FieldType에 'phone' | 'businessNumber' | 'currency' | 'quantity' 추가

2. src/components/templates/IntegratedDetailTemplate/FieldInput.tsx
   - PhoneInput, BusinessNumberInput, CurrencyInput, QuantityInput import
   - switch case에 새 타입 처리 추가

3. src/components/templates/IntegratedDetailTemplate/FieldRenderer.tsx
   - 동일하게 수정

예상 영향: 템플릿 사용 페이지 전체 자동 적용

Phase 4-2: 회계 도메인 마이그레이션

1. PurchaseDetail.tsx → CurrencyInput
2. SalesDetail.tsx → CurrencyInput
3. BillDetail.tsx → CurrencyInput
4. DepositDetail.tsx → CurrencyInput
5. WithdrawalDetail.tsx → CurrencyInput
6. BadDebtDetail.tsx → CurrencyInput, PhoneInput

Phase 4-3: 주문/견적 도메인 마이그레이션

1. OrderRegistration.tsx → CurrencyInput, QuantityInput
2. OrderSalesDetailEdit.tsx → CurrencyInput, QuantityInput
3. QuoteRegistration.tsx → CurrencyInput, QuantityInput, NumberInput
4. QuoteRegistrationV2.tsx → CurrencyInput, QuantityInput, NumberInput

Phase 4-4: 인사 도메인 마이그레이션

1. EmployeeForm.tsx → PhoneInput, PersonalNumberInput
2. EmployeeDetail.tsx → PhoneInput, PersonalNumberInput
3. EmployeeDialog.tsx → PhoneInput
4. SalaryDetailDialog.tsx → CurrencyInput

Phase 4-5: 고객/품목/자재 도메인 마이그레이션

1. ClientDetail.tsx → PhoneInput, BusinessNumberInput
2. ClientRegistration.tsx → PhoneInput, BusinessNumberInput
3. ItemDetailEdit.tsx → CurrencyInput, QuantityInput
4. ReceivingDetail.tsx → QuantityInput
5. StockStatusDetail.tsx → QuantityInput

Phase 4-6: 건설/기타 도메인 마이그레이션

1. ContractDetailForm.tsx → CurrencyInput
2. EstimateDetailForm.tsx → CurrencyInput, QuantityInput
3. PartnerForm.tsx → PhoneInput, BusinessNumberInput
4. 기타 낮은 우선순위 파일들

---

4. 마이그레이션 패턴

4.1 직접 Input → 새 컴포넌트 변환

Before (기존):

<Input
  type="number"
  value={formData.price}
  onChange={(e) => handleChange('price', e.target.value)}
/>

After (CurrencyInput):

import { CurrencyInput } from '@/components/ui/currency-input';

<CurrencyInput
  value={formData.price}
  onChange={(value) => handleChange('price', value ?? 0)}
/>

After (PhoneInput):

import { PhoneInput } from '@/components/ui/phone-input';

<PhoneInput
  value={formData.phone}
  onChange={(value) => handleChange('phone', value)}
/>

4.2 FormField 타입 변경

Before:

<FormField
  label="금액"
  type="number"
  value={price}
  onChange={setPrice}
/>

After:

<FormField
  label="금액"
  type="currency"
  value={price}
  onChangeNumber={setPrice}
/>

4.3 Config 기반 (IntegratedDetailTemplate)

Before (config):

{
  key: 'price',
  label: '금액',
  type: 'number',
}

After (config):

{
  key: 'price',
  label: '금액',
  type: 'currency',
}

---

5. 검증 계획

5.1 각 Phase 완료 후 검증

• TypeScript 컴파일 오류 없음
• 해당 페이지 렌더링 정상
• 입력 필드 동작 확인
  • 포맷팅 정상 (콤마, 하이픈 등)
  • leading zero 제거 확인
  • 값 저장/불러오기 정상

5.2 주요 테스트 시나리오

컴포넌트	테스트 입력	기대 결과
CurrencyInput	1234567	표시: ₩ 1,234,567, 값: 1234567
PhoneInput	01012345678	표시: 010-1234-5678, 값: 01012345678
BusinessNumberInput	1234567890	표시: 123-45-67890, 값: 1234567890
QuantityInput	007	표시: 7, 값: 7
NumberInput	00123.45	표시: 123.45, 값: 123.45

---

6. 롤백 계획

문제 발생 시:

1. 해당 파일의 import 변경 롤백
2. 컴포넌트 사용 부분을 기존 <Input> 으로 복원
3. 템플릿 수정의 경우 FieldInput.tsx, FieldRenderer.tsx 롤백

---

7. 진행 상황 체크리스트

Phase 4-1: 템플릿 수정

• IntegratedDetailTemplate/types.ts 수정
• IntegratedDetailTemplate/FieldInput.tsx 수정
• IntegratedDetailTemplate/FieldRenderer.tsx 수정
• 템플릿 사용 페이지 동작 확인

Phase 4-2: 회계 도메인

• PurchaseDetail.tsx
• SalesDetail.tsx
• BillDetail.tsx
• DepositDetail.tsx
• WithdrawalDetail.tsx
• BadDebtDetail.tsx

Phase 4-3: 주문/견적 도메인

• OrderRegistration.tsx
• OrderSalesDetailEdit.tsx
• QuoteRegistration.tsx
• QuoteRegistrationV2.tsx

Phase 4-4: 인사 도메인

• EmployeeForm.tsx
• EmployeeDetail.tsx
• EmployeeDialog.tsx
• SalaryDetailDialog.tsx

Phase 4-5: 고객/품목/자재 도메인

• ClientDetail.tsx
• ClientRegistration.tsx
• ItemDetailEdit.tsx
• ReceivingDetail.tsx
• StockStatusDetail.tsx

Phase 4-6: 건설/기타 도메인

• ContractDetailForm.tsx
• EstimateDetailForm.tsx
• PartnerForm.tsx
• 기타 파일들

---

8. 다음 단계

1. 즉시: Phase 4-1 템플릿 레벨 수정 (최대 효과)
2. 순차: Phase 4-2 ~ 4-6 도메인별 마이그레이션
3. 최종: 전체 빌드 및 통합 테스트

---

참고: VendorDetail.tsx 적용 결과 검증 완료됨 (2026-01-21)

• PhoneInput ✅
• BusinessNumberInput ✅
• CurrencyInput ✅
• NumberInput ✅