sam-docs/projects/mes/00_baseline/ARCHITECTURE_OPTIONS_CORE.md

---
source: Phase 0 분석 기반 아키텍처 옵션 분석
section: 백엔드-프론트엔드 협업 논의 자료 (핵심 버전)
created: 2025-11-13
audience: 백엔드 개발자 + 프론트엔드 개발자
purpose: 아키텍처 방향 결정을 위한 논의 자료
tags: [architecture, options, collaboration, discussion]
---

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

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

---

## 📊 현재 구조 분석

### 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 사이에서 고민
- ✓ 현재는 고정, 미래에 확장 가능성
- ✓ 성능과 유연성 둘 다 중요
- ✓ 게시판 패턴 경험 있음

---

## 📌 다음 단계

1. **이 문서를 바탕으로 팀 내 토의**
   - 비즈니스 요구사항 명확화
   - 기술적 제약 확인
   - 우선순위 결정

2. **옵션 선택 후:**
   - 백엔드: DB 스키마 설계
   - 프론트엔드: 컴포넌트 구조 설계
   - 함께: API 계약 정의

3. **프로토타입 개발 고려:**
   - 선택한 옵션으로 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`)