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

리팩토링 로드맵

작성일: 2026-02-06 목적: 전체 코드베이스 리팩토링 포인트 점검 및 실행 계획 상태: 분석 완료, 실행 대기

---

현재 코드베이스 수치 (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줄 중복)

현재: 모든 도메인이 이 구조를 복붙

'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 서비스 팩토리

// 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곳에서 반복

// 이 패턴이 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: 공통 훅 추출 (1-2주) 프론트 단독 ROI 최고

새 훅 생성 + 고빈도 페이지 20개 우선 적용

작업 항목:

- [ ] useListData 훅 생성 (페칭 + 페이지네이션 + 필터 통합)
- [ ] useFormSubmit 훅 생성 (제출 + 로딩 + 에러 + 토스트)
- [ ] usePagination 훅 생성
- [ ] useModal<T> 훅 생성
- [ ] 고빈도 리스트 페이지 10개 마이그레이션
      - vendors, clients, items, orders, quotes
      - production, quality, material, hr, accounting 각 1개
- [ ] 고빈도 폼 페이지 10개 마이그레이션
      - 위 도메인의 등록/수정 폼 각 1개

예상 효과: ~8,500줄 절감, 패턴 일관성 +60%

---

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: 액션 파일 제네릭화 (2-3주) 프론트 단독 최대 코드 감소

CRUD 서비스 팩토리 생성 + 80개 actions.ts 점진적 마이그레이션

작업 항목:

- [ ] createCrudService<TApi, TFront> 팩토리 함수 구현
      - getList, getById, create, update, delete, bulkDelete
      - transform / reverseTransform 자동 적용
      - 에러 핸들링 표준화
- [ ] 공통 transform 유틸리티 (lib/transformers/)
      - API snake_case → 프론트 camelCase 자동 변환
      - 날짜 문자열 파싱 공통화
- [ ] 고빈도 도메인 마이그레이션 (10개)
      - orders, quotes, clients, vendors
      - production, quality, material
      - hr/employee, hr/vacation, accounting
- [ ] 나머지 70개 점진적 마이그레이션

예상 효과: ~24,000줄 → ~8,000줄 (67% 감소)

---

Phase 4: 템플릿/패턴 통일 (2-3주) 프론트 단독

UniversalListPage 확대 + 검증 표준화 + 모달 통합

작업 항목:

- [ ] UniversalListPage 기능 보강
      - 고급 필터 UI
      - 컬럼 커스터마이징
      - 내보내기 기능
- [ ] 레거시 리스트 페이지 → UniversalListPage 마이그레이션 (우선 20개)
- [ ] SearchableSelectionModal<T> 공통 컴포넌트 생성
      - ItemSearchModal, AssigneeSelectModal 등 5개 통합
- [ ] Zod 검증 스키마 라이브러리 구축
      - lib/validations/common.ts (이메일, 전화, 사업자번호)
      - lib/validations/vendor.ts, order.ts, item.ts 등
- [ ] 수동 검증 50+ 폼 → Zod 마이그레이션 (우선 10개)

예상 효과: ~5,000줄 절감, UX 일관성 +80%

---

Phase 5: 성능 + 타입 정리 (1-2주) 프론트 단독

React.memo 적용 + any 제거 + 타입 통합

작업 항목:

- [ ] React.memo 적용 (리스트 아이템 컴포넌트 30+개)
      - WorkItemCard, CommentItem, ProjectCard 등
      - *Row, *Item, *Card 패턴 전수 조사
- [ ] 대형 컴포넌트 useCallback 적용
      - MainDashboard, WorkerScreen, DynamicItemForm
- [ ] any 타입 제거 (102곳)
      - Phase 1: types/ 파일 (4개)
      - Phase 2: action error handler (50+ 파일)
      - Phase 3: 컴포넌트 props (20개)
- [ ] 공통 타입 라이브러리 정리
      - types/shared/ 폴더 생성
      - ApiResponse<T>, PaginatedResponse<T>, FormState<T> 등
      - 엔티티별 정규 타입 단일화
- [ ] @ts-ignore / eslint-disable 제거 (25개 파일)

예상 효과: 리스트 렌더링 30-50% 개선, 타입 안전성 +60%

---

전체 예상 효과 요약

지표	Phase 1	Phase 2	Phase 3	Phase 4	Phase 5	합계
코드 절감	~8,500줄	(구조 개선)	~16,000줄	~5,000줄	(품질 개선)	~29,500줄
패턴 일관성	+60%	+50%	+40%	+80%	+60%	종합 개선
유지보수성	높음	매우 높음	높음	중간	중간	종합 개선
위험도	낮음	중간	중간	낮음	낮음	-

---

병렬 진행 가능 조합

[독립 진행 가능]
├─ Phase 1 (공통 훅) ──→ 즉시 시작
├─ Phase 5 (성능/타입) ─→ 즉시 시작 (Phase 1과 병렬)
│
[Phase 1 완료 후]
├─ Phase 2 (God 컴포넌트 분리) ──→ 훅 활용하여 분리
├─ Phase 3 (액션 제네릭화) ────→ 독립 진행 가능
│
[Phase 1+3 완료 후]
└─ Phase 4 (템플릿 통일) ─────→ 훅 + 서비스 활용

---

관련 문서

문서	설명
[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 로드맵

---

모든 Phase 프론트 단독 가능 - 백엔드 의존성 없음