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

source, section, created, audience, purpose, related, tags

source	section	created	audience	purpose	related	tags
Phase 0 분석 기반 아키텍처 옵션 상세 분석	백엔드-프론트엔드 협업 논의 자료 (상세 버전)	2025-11-13	백엔드 개발자 + 프론트엔드 개발자	아키텍처 결정을 위한 상세 분석 자료	ARCHITECTURE_OPTIONS_CORE.md	architecture detailed-analysis collaboration discussion

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

목적: 아키텍처 옵션별 상세 분석 및 실제 시나리오 기반 비교 대상: 백엔드 개발자 + 프론트엔드 개발자 협업 논의용 범위: 개념적 분석 (구현 상세 제외)

Note: 이 문서는 개념적 분석에 집중합니다. DB 스키마, API 스펙, 소스 코드 등 구현 상세는 옵션 결정 후 별도 설계합니다.

---

📊 현재 시스템 상세 분석

1. 품목 유형별 필드 상세

1.1 FG (제품) - 13개 필드

주요 필드 그룹:

• 기본 정보: 상품명, 품목명, 규격
• 분류: 카테고리, 태그
• 사양: 폭, 높이, 깊이, 무게
• 관리: 안전재고, 리드타임
• 가격: 표준가, 최소가

특징:

• 대부분 필수 필드
• 타입 안전성 높음 (숫자, 텍스트 명확)
• 검증 규칙 단순

---

1.2 PT-ASSEMBLY (조립 부품) - 12개 카테고리

카테고리별 핵심 필드:

guide_rail (가이드레일):

필수 필드:
├─ 설치유형 (wall/stand)
├─ 조립유형 (M/T/P/B/S - 5가지)
├─ 사이드규격 (width)
└─ 조립길이 (length)

코드 생성 로직:
설치유형 + 조립유형 + 사이즈코드
예: R + M + 53 → RM53

case (케이스):

필수 필드:
└─ 조립유형 (frame/body - 2가지)

코드 생성 로직:
C + 조립유형
예: C + F → CF (프레임형 케이스)

bottom_finish (하단마감재):

필수 필드:
├─ 재질 (steel/aluminum)
└─ 형상 (square/round)

코드 생성 로직:
재질코드 + 형상코드
예: BS (Steel + Square)

rod (봉):

필수 필드:
├─ 직경 (diameter)
└─ 길이 (length)

코드 생성 로직:
ROD + 직경 + 길이
예: ROD-25-3500 (25mm, 3500mm)

공통 패턴:

• 각 카테고리마다 고유한 필드 조합
• 필드 조합에 따라 코드 자동 생성
• 일부 필드는 선택값 제한 (드롭다운)
• 일부 필드는 자유 입력 (숫자, 텍스트)

---

1.3 PT-BENDING (절곡 부품) - 가변 필드

필수 필드:

├─ 재질 (material)
├─ 두께 (thickness)
├─ 절곡도면 (bending_diagram) - 이미지/파일
└─ 절곡상세 (bending_details) - JSON 구조

특징:

• 절곡도면: 파일 업로드 필요
• 절곡상세: 복잡한 데이터 구조 (각도, 위치, 순서 등)
• 코드 생성: 2가지 패턴 (카테고리 기반 / 재질 기반)

---

1.4 PT-PURCHASED (구매 부품) - 단순

필수 필드:

├─ 카테고리
├─ 구매처
└─ 규격

특징:

• 상대적으로 단순
• 외부 공급사 정보 연계

---

1.5 RM/SM/CS (자재) - 동일 구조

필수 필드:

├─ 재질
├─ 규격
├─ 단위
├─ 구매단가
└─ 공급사

특징:

• 3개 유형 구조 동일
• 재고 관리 중심
• 가격 변동 이력 필요

---

2. 현재 화면 동작 흐름 분석

2.1 품목 생성 플로우

Step 1: 품목 유형 선택
사용자: "품목 유형 선택" 드롭다운 클릭
    ↓
5개 옵션 표시: FG, PT, RM, SM, CS
    ↓
사용자: "PT (부품)" 선택
    ↓
화면: PT 전용 필드 표시 시작

Step 2: 부품 유형 선택 (PT만)
화면: "부품 유형" 드롭다운 활성화
    ↓
3개 옵션: ASSEMBLY, BENDING, PURCHASED
    ↓
사용자: "ASSEMBLY" 선택
    ↓
화면: ASSEMBLY 전용 필드 표시

Step 3: 카테고리 선택 (ASSEMBLY만)
화면: "카테고리" 드롭다운 활성화
    ↓
12개 옵션: guide_rail, case, rod, ...
    ↓
사용자: "guide_rail" 선택
    ↓
화면: guide_rail 전용 필드 표시
    - 설치유형
    - 조립유형
    - 사이드규격
    - 조립길이

Step 4: 필드 입력
사용자: 각 필드 입력
    ↓
화면: 실시간 검증
    ↓
품목코드 자동 생성 (예: RM53)
    ↓
화면: 미리보기 표시

Step 5: 저장
사용자: "저장" 버튼 클릭
    ↓
100줄 검증 로직 실행
    ↓
362줄 저장 로직 실행
    ↓
API 호출

문제:

• 조건부 렌더링 깊이: 3-4단계
• 검증 시점: 저장 시 (즉시 피드백 제한)
• 코드 중복: 각 단계마다 if-else 반복

---

2.2 품목 조회 플로우

List View 구조:

7개 탭 (Desktop):
├─ 전체 (All) - 모든 품목
├─ FG - 제품만
├─ PT - 부품 (3개 서브탭)
│   ├─ ASSEMBLY
│   ├─ BENDING
│   └─ PURCHASED
├─ SM - 부자재
├─ RM - 원자재
└─ CS - 소모품

각 탭마다:
├─ 필터링 로직 (품목 유형별)
├─ 테이블 헤더 (컬럼 구성)
├─ 테이블 바디 (데이터 표시)
├─ 페이지네이션
└─ 액션 버튼 (보기/수정/삭제)

문제:

• 테이블 구조 10회 복사-붙여넣기
• 필터링 로직 7회 반복
• 페이지네이션 7회 반복
• DataTable 컴포넌트 존재하지만 미사용

---

3. 코드 복잡도 분석

3.1 조건부 렌더링 복잡도

현재 구조:

if (itemType === "FG") {
    // FG 전용 필드 (50줄)
} else if (itemType === "PT") {
    if (partType === "ASSEMBLY") {
        if (category1 === "guide_rail") {
            // guide_rail 필드 (80줄)
        } else if (category1 === "case") {
            // case 필드 (60줄)
        } else if (category1 === "rod") {
            // rod 필드 (70줄)
        }
        // ... 12개 카테고리 반복
    } else if (partType === "BENDING") {
        // BENDING 필드 (100줄)
    } else if (partType === "PURCHASED") {
        // PURCHASED 필드 (50줄)
    }
} else if (itemType === "RM") {
    // RM 필드 (40줄)
}
// ... 5개 품목 유형 반복

총 복잡도: 5 × (1 + 3 × 12) ≈ 185개 조건 분기

Cyclomatic Complexity:

• generateItemCode(): 25+
• handleSaveItem(): 30+
• 전체 컴포넌트: 100+ (추정)

영향:

• 테스트 케이스: 185개 필요
• 유지보수: 새 카테고리 추가 시 5-10곳 수정
• 버그 위험: 높음 (조건 누락 가능성)

---

🎯 아키텍처 옵션 상세 비교

Option A: 고정 화면 리팩토링 상세

A.1 컴포넌트 분리 전략

현재 → 개선:

Before:
ItemManagement.tsx (6,521줄)
└─ 모든 로직 포함

After:
Pages/
└─ ItemManagement.tsx (100줄)
    └─ 페이지 레이아웃만

Organisms/
├─ ItemListView.tsx (200줄)
│   └─ DataTable 재사용
├─ ItemFormDialog.tsx (300줄)
│   └─ 품목 유형별 폼 라우팅
└─ BOMEditor.tsx (300줄) - 기존 유지

Molecules/
├─ FGFormFields.tsx (150줄)
├─ PTAssemblyFormFields.tsx (200줄)
│   ├─ GuideRailFields.tsx (80줄)
│   ├─ CaseFields.tsx (60줄)
│   ├─ RodFields.tsx (70줄)
│   └─ ... (12개 컴포넌트)
├─ PTBendingFormFields.tsx (100줄)
├─ PTPurchasedFormFields.tsx (50줄)
├─ RMFormFields.tsx (40줄)
├─ SMFormFields.tsx (40줄)
└─ CSFormFields.tsx (40줄)

Hooks/
├─ useItemForm.ts (200줄)
│   └─ useState 통합 관리
├─ useItemValidation.ts (150줄)
│   └─ 검증 로직 분리
└─ useItemCodeGenerator.ts (177줄 → 200줄)
    └─ 코드 생성 로직 분리

총계: 6,521줄 → 약 2,000줄 (68% 감소)

감소 메커니즘:

• 테이블 중복 제거: 1,911줄 → 200줄 (DataTable 재사용)
• 로직 분리: 상태/검증/생성 hooks 분리
• 컴포넌트 재사용: 공통 필드 컴포넌트화

---

A.2 상태 관리 개선

현재 문제:

40개 useState:
- 모든 필드를 개별 state로 관리
- 연관된 필드 간 동기화 어려움
- 리렌더링 과다

예: guide_rail 입력 시
→ 8개 state 업데이트
→ 컴포넌트 8회 리렌더링

개선 방향:

useItemForm hook:
- 단일 reducer로 통합
- 필드 간 종속성 관리
- 최적화된 리렌더링

예: guide_rail 입력 시
→ 1회 dispatch
→ 필요한 부분만 리렌더링

---

A.3 신규 카테고리 추가 시나리오

예: "hinge (경첩)" 카테고리 추가

Step 1: 필드 정의
백엔드 회의: hinge에 필요한 필드는?
- 힌지타입 (left/right/center)
- 힌지사이즈 (small/medium/large)
- 재질 (steel/aluminum)

Step 2: 백엔드 작업
- DB 스키마 변경 없음 (기존 컬럼 재사용)
- API 수정 없음

Step 3: 프론트엔드 작업 (4-6시간)
1. HingeFields.tsx 컴포넌트 생성 (80줄)
2. useItemCodeGenerator.ts 수정 (10줄 추가)
3. useItemValidation.ts 수정 (15줄 추가)
4. 카테고리 드롭다운 옵션 추가 (1줄)

Step 4: 테스트
- HingeFields 단위 테스트
- 통합 테스트

Step 5: 배포
- 프론트엔드 빌드 및 배포
- 백엔드 변경 없음

총 작업시간: 4-6시간

장점:

• 명확한 작업 범위
• 타입 안전성 유지
• 단계별 테스트 가능

단점:

• 프론트엔드 배포 필요
• 소스 코드 수정 필수

---

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

B.1 메타데이터 구조 개념

필드 메타데이터 개념:

각 필드의 정보를 데이터로 저장:

예: guide_rail의 "설치유형" 필드

메타데이터 구성:
├─ 필드 식별: fieldName: "installationType"
├─ 표시 정보: label: "설치유형"
├─ 필드 타입: type: "select"
├─ 옵션 목록: options: ["wall", "stand"]
├─ 검증 규칙: required: true
├─ 표시 조건: showWhen: "category1 === 'guide_rail'"
└─ 코드 생성: codePattern: "{installationType}"

동작 원리:

프론트엔드 로딩 시:
1. API 호출: GET /api/items/metadata?category=guide_rail
2. 메타데이터 수신 (JSON)
3. 메타데이터 기반 폼 생성
4. 사용자 입력 처리
5. 메타데이터 기반 검증
6. 메타데이터 기반 코드 생성
7. API 호출: POST /api/items

---

B.2 동적 렌더링 메커니즘

MetaFormBuilder 컴포넌트 개념:

입력:
├─ metadata (필드 정의 목록)
└─ formData (현재 입력값)

처리:
1. metadata 순회
2. 각 필드의 type에 따라 적절한 컴포넌트 선택
   - type: "text" → <Input />
   - type: "number" → <Input type="number" />
   - type: "select" → <Select />
   - type: "file" → <FileUpload />
3. 표시 조건 (showWhen) 평가
4. 검증 규칙 (validation) 적용
5. 필드 렌더링

출력:
└─ 동적으로 생성된 폼

장점:

• 메타데이터 변경만으로 화면 변경
• 소스 코드 수정 불필요

단점:

• 디버깅 어려움 (런타임 생성)
• 복잡한 UI 표현 제한
• 성능 오버헤드

---

B.3 신규 카테고리 추가 시나리오

예: "hinge (경첩)" 카테고리 추가

Step 1: 필드 정의
백엔드 회의: hinge에 필요한 필드는?
- 힌지타입 (left/right/center)
- 힌지사이즈 (small/medium/large)
- 재질 (steel/aluminum)

Step 2: 백엔드 작업 (2-3시간)
관리자 화면에서 메타데이터 등록:

필드 1:
- fieldName: "hingeType"
- label: "힌지타입"
- type: "select"
- options: ["left", "right", "center"]
- required: true

필드 2:
- fieldName: "hingeSize"
- label: "힌지사이즈"
- type: "select"
- options: ["small", "medium", "large"]
- required: true

필드 3:
- fieldName: "material"
- label: "재질"
- type: "select"
- options: ["steel", "aluminum"]
- required: true

코드 생성 패턴:
- pattern: "HINGE-{hingeType}-{hingeSize}"

Step 3: 프론트엔드 작업
- 없음! (메타데이터 자동 반영)

Step 4: 테스트
- 관리자 화면에서 메타데이터 검증
- 품목 등록 화면에서 동작 확인

Step 5: 배포
- 백엔드 배포 없음 (DB 데이터만 변경)
- 프론트엔드 배포 없음

총 작업시간: 2-3시간 (관리자 입력 시간)

장점:

• 개발자 개입 최소화
• 관리자가 직접 설정 가능
• 배포 불필요

단점:

• 메타데이터 관리 시스템 사전 구축 필요
• 복잡한 UI는 제한적
• 타입 안전성 낮음

---

Option C: 하이브리드 상세

C.1 필드 분류 전략

고정 필드 기준:

다음 필드는 "고정"으로 분류:
✓ 모든 품목에 공통
✓ 검색/필터 대상
✓ 필수 비즈니스 로직
✓ 성능 중요

예:
├─ itemType (품목 유형)
├─ itemName (품목명)
├─ category (카테고리)
├─ specification (규격)
└─ unitPrice (단가)

동적 필드 기준:

다음 필드는 "동적"으로 분류:
✓ 품목 유형별 특수 속성
✓ 자주 변경되는 속성
✓ 선택적 속성
✓ 확장 가능성 높은 속성

예:
├─ installationType (설치유형 - guide_rail만)
├─ assemblyType (조립유형 - guide_rail만)
├─ diameter (직경 - rod만)
└─ thickness (두께 - BENDING만)

---

C.2 데이터 저장 전략

고정 필드:

products 테이블 컬럼으로 저장:
- 장점: 빠른 검색, 인덱싱 가능
- 단점: 스키마 변경 필요

동적 필드:

JSON 컬럼 또는 별도 테이블로 저장:

옵션 1: JSON 컬럼
products.attributes = {
  "installationType": "wall",
  "assemblyType": "M",
  "sideSpecWidth": 3500
}

옵션 2: EAV 패턴 (게시판 방식)
product_attributes 테이블:
├─ product_id
├─ field_name
└─ field_value

---

C.3 신규 카테고리 추가 시나리오

예: "hinge (경첩)" 카테고리 추가

Step 1: 필드 정의 및 분류
백엔드 회의: hinge에 필요한 필드는?

고정 필드 (기존 활용):
✓ itemName, category, specification

동적 필드 (신규 추가):
- hingeType (left/right/center)
- hingeSize (small/medium/large)
- material (steel/aluminum)

Step 2: 백엔드 작업 (1-2시간)
동적 필드 메타데이터 등록:
- 관리자 화면에서 3개 필드 정의
- 검증 규칙 설정
- 코드 생성 패턴 정의

Step 3: 프론트엔드 작업 (2-3시간)
- 카테고리 드롭다운 옵션 추가 (1줄)
- 고정 필드 폼은 기존 재사용
- 동적 필드는 자동 렌더링

Step 4: 테스트
- 고정 필드: 기존 테스트 패스
- 동적 필드: 메타데이터 기반 테스트

Step 5: 배포
- 백엔드: 메타데이터만 변경 (배포 불필요)
- 프론트엔드: 카테고리 옵션 추가 (배포 필요)

총 작업시간: 3-5시간

장점:

• 고정 필드는 성능/타입 안전성 유지
• 동적 필드는 유연성 확보
• 배포 빈도 감소

단점:

• 두 시스템 혼재로 복잡도 증가
• 고정/동적 경계 결정 필요

---

🔍 실제 시나리오별 비교

시나리오 1: 초기 개발 (12개 카테고리 전부 구현)

항목	Option A	Option B	Option C
백엔드 작업	단순 CRUD (1주)	메타시스템 (4주)	Hybrid (2주)
프론트 작업	12개 컴포넌트 (4주)	MetaFormBuilder (4주)	고정+동적 (4주)
테스트	컴포넌트별 (1주)	메타 기반 (2주)	Hybrid (1.5주)
총계	6주	10주	7.5주

---

시나리오 2: 신규 카테고리 1개 추가

항목	Option A	Option B	Option C
백엔드 작업	없음	메타데이터 등록 (2시간)	메타데이터 등록 (1시간)
프론트 작업	컴포넌트 개발 (4시간)	없음	드롭다운 옵션 (30분)
테스트	컴포넌트 테스트 (2시간)	메타데이터 검증 (1시간)	Hybrid (1.5시간)
배포	프론트 배포 필요	배포 불필요	프론트 배포 필요
총계	6시간 + 배포	3시간	3시간 + 배포

---

시나리오 3: 기존 필드 수정 (예: 옵션 추가)

예: guide_rail의 조립유형에 'X' 옵션 추가

항목	Option A	Option B	Option C
수정 위치	컴포넌트 코드	메타데이터	메타데이터 (동적 필드)
작업 시간	30분	5분	5분
테스트	컴포넌트 테스트	메타 검증	메타 검증
배포	프론트 배포 필요	배포 불필요	배포 불필요
총계	30분 + 배포	5분	5분

---

시나리오 4: 복잡한 UI 요구사항

예: guide_rail에 "미리보기" 3D 렌더링 추가

항목	Option A	Option B	Option C
구현 난이도	쉬움	매우 어려움	중간 (고정으로 처리)
개발 시간	1-2일	5-7일 (메타 확장)	1-2일 (고정 컴포넌트)
유지보수	쉬움	어려움	쉬움
성능	최적화 쉬움	오버헤드	최적화 쉬움

분석:

• Option B는 동적 시스템에 복잡한 UI 통합 어려움
• Option A/C는 전용 컴포넌트로 자유롭게 구현 가능

---

시나리오 5: 성능 중요 상황 (1만개 품목 검색)

항목	Option A	Option B	Option C
검색 속도	매우 빠름 (인덱싱)	느림 (JSON 검색)	고정 필드만 빠름
필터링	쉬움	어려움	Hybrid
정렬	빠름	느림	고정 필드만 빠름
페이지네이션	효율적	비효율적	Hybrid

분석:

• Option A: 모든 필드 인덱싱 가능
• Option B: JSON 검색은 전체 스캔 필요
• Option C: 자주 검색되는 필드만 고정으로 처리

---

💡 결정 가이드

다음 질문에 답하면서 옵션 선택:

질문 1: 품목 유형/카테고리 변경 빈도는?

• 거의 없음 (1년에 0-2회) → Option A 유리
• 가끔 있음 (1년에 3-6회) → Option C 고려
• 자주 있음 (1년에 7회+) → Option B 고려

---

질문 2: 관리자의 기술 수준은?

• 개발자가 직접 관리 → Option A/C 가능
• 비개발자 관리자 → Option B/C 필요

---

질문 3: 개발 일정은?

• 빠른 출시 필요 (1-2개월) → Option A
• 중간 (2-4개월) → Option C
• 장기 프로젝트 (4개월+) → Option B

---

질문 4: 복잡한 UI 요구사항이 있나?

• 있음 (3D, 그래프, 복잡한 인터랙션) → Option A/C
• 단순 폼만 → Option B 가능

---

질문 5: 이 시스템을 다른 곳에도 적용?

• 이 프로젝트만 → Option A
• 향후 확장 가능성 → Option C
• 여러 프로젝트 계획 → Option B

---

질문 6: 성능 요구사항은?

• 매우 중요 (대용량 데이터) → Option A
• 중간 → Option C
• 성능보다 유연성 → Option B

---

📊 의사결정 매트릭스

가중치 기반 평가 (예시)

기준	가중치	Option A	Option B	Option C
개발 속도	20%	9점	5점	7점
유지보수성	25%	6점	9점	8점
확장성	20%	4점	10점	7점
성능	15%	10점	5점	8점
복잡도	10%	9점	4점	6점
타입 안전성	10%	10점	4점	8점
총점	100%	7.35	6.9	7.5

해석:

• Option A: 빠른 개발, 성능 우선 시
• Option B: 장기 확장성, 유연성 우선 시
• Option C: 균형 잡힌 접근

Note: 가중치는 프로젝트 상황에 따라 조정 필요

---

🔄 하이브리드 구현 전략 상세

단계별 진화 전략

Phase 1: Option A로 시작 (빠른 출시)

목표: 2개월 내 운영 시작
- 12개 카테고리 고정 화면 구현
- 리팩토링으로 품질 확보
- 운영하며 피드백 수집

Phase 2: 자주 변경되는 부분 파악 (3-6개월 운영)

운영 데이터 분석:
- 어떤 필드가 자주 추가/수정 되는가?
- 어떤 카테고리가 자주 추가되는가?
- 관리자의 불편 사항은?

Phase 3: 동적 시스템 부분 도입 (Option C로 전환)

선별적 전환:
- 자주 변경되는 필드 → 동적으로 전환
- 고정된 필드 → 그대로 유지
- 핵심 비즈니스 로직 → 고정 유지

Phase 4: 완전 동적 시스템 (Option B로 전환, 선택사항)

장기 전략 (필요시):
- 모든 시스템 메타데이터 기반 전환
- 다른 모듈 (견적, 생산)에도 적용
- 통합 메타데이터 관리 플랫폼

---

🎓 참고: 다른 시스템 사례

SAM 게시판 시스템 (Option C 패턴)

구조:

고정 필드:
├─ board_id (게시판 ID)
├─ title (제목)
├─ content (내용)
└─ author (작성자)

동적 필드:
├─ board_settings (필드 정의)
└─ post_custom_field_values (필드 값)

장점:

• 새 게시판 타입 추가 쉬움
• 게시판별 커스텀 필드 지원
• 핵심 기능 (제목, 내용)은 고정으로 성능 확보

이 패턴을 품목에 적용:

고정:
- item_type, item_name, specification

동적:
- item_field_settings (필드 정의)
- product_attributes (필드 값)

---

📝 다음 단계 체크리스트

의사결정 후 해야 할 일:

Option A 선택 시:

• 컴포넌트 구조 상세 설계
• 상태 관리 전략 확정
• 코드 생성/검증 로직 설계
• 리팩토링 우선순위 결정

Option B 선택 시:

• 메타데이터 스키마 설계
• 메타데이터 관리 화면 설계
• 동적 렌더링 엔진 설계
• 검증 규칙 표현 방법 결정

Option C 선택 시:

• 고정/동적 경계 정의
• 하이브리드 데이터 모델 설계
• 게시판 패턴 적용 방법 검토
• 단계별 전환 전략 수립

---

🔗 관련 문서

• 핵심 버전: ARCHITECTURE_OPTIONS_CORE.md - 간략 비교용
• Phase 0 보고서: PHASE_0_FINAL_REPORT.md - 전체 분석 결과
• React 분석: docs_breakdown/react_code_analysis_summary.md - 현재 코드 상세
• API 분석: docs_breakdown/api_code_analysis_summary.md - 백엔드 현황

---

작성일: 2025-11-13 버전: 1.0 (상세 버전) 문의: 백엔드 + 프론트엔드 개발자 협업 논의