Files

hskwon 08a8259313 docs: 5130 레거시 분석 문서 및 기존 문서 초기 커밋

- 5130 레거시 시스템 분석 (00_OVERVIEW ~ 08_SAM_COMPARISON)
- MES 프로젝트 문서
- API/프론트엔드 스펙 문서
- 가이드 및 레퍼런스 문서

2025-12-04 18:47:19 +09:00

14 KiB

Raw Permalink Blame History

source, section, created, audience, purpose, tags

source

section

created

audience

purpose

품목 관리 시스템 아키텍처 옵션 분석

목적: 현재 품목 관리 화면의 구조적 문제를 해결하기 위한 아키텍처 접근 방식 비교 대상: 백엔드 개발자 + 프론트엔드 개발자 협업 논의용 범위: 개념적 분석 (구현 상세 제외)

📊 현재 구조 분석

1. 품목 유형 및 필드 구성

5가지 주요 품목 유형:

품목 유형 계층:
├─ FG (제품)
│  └─ 필드: 상품명, 품목명, 규격, ...
│
├─ PT (부품) ─┬─ ASSEMBLY (조립) ─── 12개 카테고리
│              │   ├─ guide_rail: 설치유형, 조립유형, 사이드규격, 조립길이
│              │   ├─ case: 조립유형
│              │   ├─ bottom_finish: 재질, 형상
│              │   ├─ rod: 직경, 길이
│              │   ├─ frame: 위치, 길이
│              │   ├─ bracket: 설치유형, 규격
│              │   ├─ cover: 재질, 길이
│              │   ├─ cap: 위치, 직경
│              │   ├─ endcap: 위치, 직경
│              │   ├─ stopper: 동작유형, 용량
│              │   ├─ safety: 안전장치유형, 용량
│              │   └─ motor: 모터타입, 출력
│              │
│              ├─ BENDING (절곡)
│              │   └─ 필드: 재질, 두께, 절곡도면, 절곡상세
│              │
│              └─ PURCHASED (구매)
│                  └─ 필드: 카테고리, 구매처, 규격
│
├─ RM (원자재)
│  └─ 필드: 재질, 규격, 단위, 구매단가
│
├─ SM (부자재)
│  └─ 필드: 재질, 규격, 단위, 구매단가
│
└─ CS (소모품)
   └─ 필드: 재질, 규격, 단위, 구매단가

핵심 특징:

품목 유형에 따라 완전히 다른 필드 세트 필요
PT-ASSEMBLY는 12개 카테고리별로 고유한 필드 조합
총 추정 40-50개 이상의 필드가 조건부로 표시됨

2. 현재 구현 방식

6,521줄 단일 파일 (ItemManagement.tsx)

구조:
├─ 40개 useState (모든 필드를 상태로 관리)
├─ 177줄 코드 생성 로직 (12개 if-else 분기)
├─ 100줄 검증 로직 (품목 유형별 검증 규칙)
├─ 1,911줄 리스트 뷰 (7개 탭 × 테이블 구조 반복)
└─ 1,780줄 폼 (품목 유형별 조건부 렌더링)

동작 방식:

사용자가 품목 유형 선택
    ↓
if (itemType === "FG") {
    → FG 전용 필드 표시
} else if (itemType === "PT" && partType === "ASSEMBLY") {
    if (category1 === "guide_rail") {
        → 가이드레일 전용 필드 표시
    } else if (category1 === "case") {
        → 케이스 전용 필드 표시
    }
    // ... 12개 카테고리 반복
}
// ... 5개 품목 유형 반복

문제점:

❌ 유지보수 불가능: 새로운 카테고리 추가 시 여러 곳 수정 필요
❌ 코드 중복: 테이블 구조 10회, 검증 로직 분산
❌ 확장성 제한: 필드 추가/수정 시 소스 코드 직접 변경 필요
❌ 성능 저하: 40개 useState, 거대한 단일 컴포넌트

🎯 아키텍처 옵션 비교

Option A: 고정 화면 유지 (현재 방식 개선)

개념:

현재 구조 유지, 리팩토링으로 품질 개선
품목 유형별로 화면을 작은 컴포넌트로 분리
여전히 화면은 "고정"되어 있음

구조 변경:
ItemManagement.tsx (6,521줄)
    ↓ 분리
├─ ItemListView.tsx (200줄) ← DataTable 재사용
├─ ItemFormDialog.tsx (300줄)
│   ├─ FGForm.tsx (150줄)
│   ├─ PTAssemblyForm.tsx (200줄)
│   │   ├─ GuideRailFields.tsx
│   │   ├─ CaseFields.tsx
│   │   └─ ... (12개 컴포넌트)
│   ├─ PTBendingForm.tsx (100줄)
│   └─ PTPurchasedForm.tsx (100줄)
└─ hooks/
    ├─ useItemForm.ts (상태 관리)
    └─ useItemValidation.ts (검증 로직)

장점:

✅ 단순하고 직관적
✅ 개발 속도 빠름 (리팩토링만)
✅ 프론트엔드 자체 완결 (백엔드 의존 최소)
✅ 타입 안전성 높음 (TypeScript 완전 지원)

단점:

❌ 새 품목 유형/카테고리 추가 시 소스 수정 필요
❌ 필드 변경 시 프론트엔드 배포 필요
❌ 여러 시스템에서 사용 시 중복 개발

백엔드 요구사항:

단순 CRUD API (GET/POST/PUT/DELETE /api/items)
품목 유형별 필드는 모두 고정 컬럼

프론트엔드 요구사항:

컴포넌트 분리 작업 (4-7주)
품목 유형별 폼 컴포넌트 개발 (12개)

Option B: 메타데이터 기반 동적 UI

개념:

화면 구성 정보를 데이터베이스에 저장
프론트엔드는 메타데이터를 읽어 동적으로 화면 구성
관리자 화면에서 필드 추가/수정 가능

동작 방식:

DB: item_field_metadata 테이블
┌────────────┬─────────────┬──────────────┬───────────────┐
│ item_type  │ field_name  │ field_type   │ field_config  │
├────────────┼─────────────┼──────────────┼───────────────┤
│ FG         │ productName │ text         │ {required}    │
│ FG         │ itemName    │ text         │ {required}    │
│ PT-guide   │ installType │ select       │ {wall,stand}  │
│ PT-guide   │ assemblyType│ select       │ {M,T,P,B,S}   │
└────────────┴─────────────┴──────────────┴───────────────┘
    ↓
프론트엔드가 읽음
    ↓
<MetaFormBuilder metadata={metadata} />
    ↓
화면 자동 생성

예시: 새 필드 추가

관리자: "guide_rail에 '표면처리' 필드 추가"
    ↓
DB에 메타데이터 INSERT
    ↓
화면 자동 반영 (소스 수정 없음)

장점:

✅ 확장성 최고: 필드 추가/수정 시 소스 변경 불필요
✅ 유연성: 품목 유형 추가 쉬움
✅ 중앙 관리: 메타데이터 한 곳에서 관리
✅ 재사용성: 다른 시스템에도 적용 가능

단점:

❌ 복잡도 높음: 메타데이터 시스템 개발 필요
❌ 개발 시간 김: 초기 구축 오래 걸림 (8-12주)
❌ 디버깅 어려움: 동적 생성으로 에러 추적 어려움
❌ 타입 안전성 낮음: 런타임 에러 가능성

백엔드 요구사항:

메타데이터 관리 시스템 (CRUD)
GET /api/items/metadata?itemType=FG
메타데이터 변경 이력 관리
메타데이터 기반 검증 로직

프론트엔드 요구사항:

메타데이터 기반 폼 렌더링 엔진
동적 검증 시스템
메타데이터 관리 화면

Option C: 하이브리드 (고정 + 동적)

개념:

핵심 필드는 고정 (고정 화면)
확장 필드는 동적 (메타데이터)
게시판 시스템의 board_settings 패턴 차용

필드 구분:

고정 필드 (Fixed Fields):
- itemType, itemName, specification, category
- → 테이블 컬럼, TypeScript 타입 정의
- → 고정 UI 컴포넌트

확장 필드 (Dynamic Fields):
- 품목 유형별 추가 속성
- → JSON 컬럼 (attributes) 저장
- → 메타데이터 기반 동적 렌더링

예시:
products 테이블
├─ 고정: id, item_type, item_name, specification (컬럼)
└─ 동적: attributes (JSON) ← {installationType: 'wall', assemblyType: 'M'}

게시판 패턴 참고:

현재 SAM 게시판 시스템:
├─ boards (게시판 기본 설정)
├─ board_settings (동적 필드 정의)
└─ post_custom_field_values (동적 필드 값)
    ↓
품목 시스템 적용:
├─ item_types (품목 기본 설정)
├─ item_field_settings (동적 필드 정의)
└─ product_attributes (동적 필드 값)

장점:

✅ 균형: 단순함 + 확장성 조화
✅ 점진 확장: 필요시 동적 필드 추가
✅ 성능: 핵심 필드는 빠름 (인덱싱 가능)
✅ 타입 안전성: 핵심 필드는 타입 보장

단점:

⚠️ 복잡도 중간: 두 시스템 혼재
⚠️ 경계 모호: 어디까지 고정? 어디부터 동적?
⚠️ 학습 곡선: 두 방식 모두 이해 필요

백엔드 요구사항:

고정 필드: 일반 CRUD
동적 필드: 메타데이터 시스템 (간소화 버전)
Hybrid 검증 로직

프론트엔드 요구사항:

고정 폼 컴포넌트
동적 필드 렌더러
Hybrid 상태 관리

⚖️ Trade-off 분석

1. 개발 시간

옵션	백엔드	프론트엔드	총계	비고
A. 고정 화면	1-2주	4-7주	5-9주	리팩토링 작업
B. 메타데이터	4-6주	4-6주	8-12주	시스템 구축
C. 하이브리드	2-4주	4-7주	6-11주	점진적 확장

2. 유지보수성

시나리오	Option A	Option B	Option C
새 품목 유형 추가	❌ 소스 수정 필요 (1-2일)	✅ 메타데이터만 추가 (1시간)	⚠️ 고정 필드 추가 + 메타 (반나절)
기존 필드 수정	❌ 소스 + 배포 (반나절)	✅ 메타데이터 수정 (즉시)	⚠️ 고정 필드는 배포 필요
검증 규칙 변경	❌ 소스 수정 필요	✅ 메타데이터 규칙 변경	⚠️ 고정은 소스, 동적은 메타

3. 성능

관점	Option A	Option B	Option C
초기 로딩	✅ 빠름 (정적)	⚠️ 느림 (메타 로딩)	⚠️ 중간
검색/필터	✅ 빠름 (인덱싱)	❌ 느림 (JSON 검색)	⚠️ 고정 필드만 빠름
렌더링	✅ 최적화 쉬움	❌ 동적 생성 오버헤드	⚠️ Hybrid

4. 확장성

요구사항	Option A	Option B	Option C
새 화면 추가	❌ 컴포넌트 개발 필요	✅ 메타데이터로 자동	⚠️ 부분 자동화
다른 시스템 적용	❌ 재개발 필요	✅ 메타데이터 복사	⚠️ 고정 부분 재개발
비즈니스 변화 대응	❌ 개발팀 의존	✅ 관리자가 직접 설정	⚠️ 간단한 건 관리자, 복잡한 건 개발

5. 복잡도

관점	Option A	Option B	Option C
시스템 복잡도	✅ 단순	❌ 복잡	⚠️ 중간
디버깅	✅ 쉬움	❌ 어려움 (동적)	⚠️ 중간
타입 안전성	✅ 높음	❌ 낮음	⚠️ 고정만 높음

🤔 논의 포인트

1. 비즈니스 요구사항

질문:

품목 유형/카테고리가 얼마나 자주 추가/변경되는가?
- 거의 없음 → Option A 유리
- 자주 변경 → Option B/C 유리
관리자가 직접 필드를 추가/수정할 필요가 있는가?
- 필요 없음 → Option A
- 필요함 → Option B/C
이 시스템을 다른 곳에도 적용할 계획인가?
- 없음 → Option A
- 있음 → Option B/C

2. 기술적 제약

질문:

개발 일정이 얼마나 타이트한가?
- 빠른 출시 필요 → Option A
- 장기 프로젝트 → Option B/C
팀의 기술 수준은?
- 메타데이터 시스템 경험 없음 → Option A/C
- 복잡한 시스템 경험 있음 → Option B
성능 요구사항은?
- 매우 중요 → Option A
- 유연성이 더 중요 → Option B/C

3. 백엔드-프론트엔드 역할 분담

작업	Option A	Option B	Option C
새 필드 추가 시	백+프 둘 다 작업	백엔드만 (메타데이터)	백+프 (필드 유형에 따라)
검증 로직	프론트 중심	백엔드 중심	협의 필요
UI 렌더링	프론트 완전 제어	메타데이터 제약	Hybrid

4. 점진적 확장 가능성

질문:

Option A로 시작해서 나중에 Option B/C로 전환 가능한가?
- 가능하지만 전면 재작업 필요
Option C를 선택하면 어디까지를 "고정"으로 할 것인가?
- 제안: 핵심 필드 (itemType, itemName, specification, category) 고정
- 제안: 품목 유형별 특수 속성은 동적

💡 권장 방향 (토의용)

상황별 권장 옵션

다음 경우 Option A 권장:

✓ 품목 유형이 거의 고정되어 있음
✓ 빠른 출시가 중요
✓ 시스템이 단일 프로젝트에만 사용됨
✓ 프론트엔드 팀이 리팩토링 경험 풍부

다음 경우 Option B 권장:

✓ 품목 유형이 자주 변경됨
✓ 관리자가 직접 설정 변경 필요
✓ 여러 시스템에 적용 계획
✓ 장기 프로젝트 (충분한 개발 기간)

다음 경우 Option C 권장:

✓ Option A와 B 사이에서 고민
✓ 현재는 고정, 미래에 확장 가능성
✓ 성능과 유연성 둘 다 중요
✓ 게시판 패턴 경험 있음

📌 다음 단계

이 문서를 바탕으로 팀 내 토의
- 비즈니스 요구사항 명확화
- 기술적 제약 확인
- 우선순위 결정
옵션 선택 후:
- 백엔드: DB 스키마 설계
- 프론트엔드: 컴포넌트 구조 설계
- 함께: API 계약 정의
프로토타입 개발 고려:
- 선택한 옵션으로 1-2개 품목 유형 먼저 구현
- 실제 사용성 검증 후 전체 확장

📚 참고 자료

Phase 0 분석 보고서: claudedocs/mes/00_baseline/PHASE_0_FINAL_REPORT.md
현재 코드 분석: claudedocs/mes/00_baseline/docs_breakdown/react_code_analysis_summary.md
API 분석: claudedocs/mes/00_baseline/docs_breakdown/api_code_analysis_summary.md
Gap 검증: claudedocs/mes/00_baseline/docs_breakdown/api_gap_validation_report.md

작성일: 2025-11-13 버전: 1.0 (핵심 버전) 다음: 상세 버전 (ARCHITECTURE_OPTIONS_DETAILED.md)

14 KiB Raw Permalink Blame History Unescape Escape

품목 관리 시스템 아키텍처 옵션 분석

📊 현재 구조 분석

1. 품목 유형 및 필드 구성

2. 현재 구현 방식

🎯 아키텍처 옵션 비교

Option A: 고정 화면 유지 (현재 방식 개선)

Option B: 메타데이터 기반 동적 UI

Option C: 하이브리드 (고정 + 동적)

⚖️ Trade-off 분석

1. 개발 시간

2. 유지보수성

3. 성능

4. 확장성

5. 복잡도

🤔 논의 포인트

1. 비즈니스 요구사항

2. 기술적 제약

3. 백엔드-프론트엔드 역할 분담

4. 점진적 확장 가능성

💡 권장 방향 (토의용)

상황별 권장 옵션

📌 다음 단계

📚 참고 자료

14 KiB

Raw Permalink Blame History