ERP-node/docs/screen-implementation-guide/00_analysis/full-screen-analysis.md

WACE ERP 화면 구성 시스템 전체 분석

최종 업데이트: 2026-03-13 용도: LLM 챗봇 / AI 에이전트가 화면 개발 요청을 받았을 때 참조하는 시스템 구조 레퍼런스 핵심 규칙: 사용자 업무 화면은 React 코드(.tsx)로 직접 만들지 않는다. DB 등록(screen_definitions + screen_layouts_v2 + menu_info)으로 구현한다.

---

1. 시스템 아키텍처 요약

1.1 화면 렌더링 파이프라인

[DB] screen_definitions (화면 정의)
  + screen_layouts_v2 (레이아웃 JSON)
  + menu_info (메뉴 등록)
       │
       ▼
[Backend API] GET /api/screens/:screenId
       │
       ▼
[Frontend] /screens/[screenId]/page.tsx
       │
       ▼
[Converter] layoutV2Converter.ts → V2 JSON을 Legacy 포맷으로 변환
       │
       ▼
[Renderer] ResponsiveGridRenderer → RealtimePreview → DynamicComponentRenderer
       │
       ▼
[Registry] ComponentRegistry.getComponent(componentType) → 실제 React 컴포넌트 렌더링

1.2 화면 유형 분류

구분	구현 방식	코드 위치	예시
사용자 업무 화면	DB 등록 (SQL INSERT)	screen_definitions + screen_layouts_v2	수주관리, 품목정보, BOM관리
관리자 메뉴	React 코드 직접 작성	frontend/app/(main)/admin/*/page.tsx	사용자관리, 권한관리, 시스템설정

절대 규칙: 사용자 업무 화면(생산, 영업, 구매, 물류, 품질 등)은 React 하드코딩 금지. 반드시 DB 등록 방식으로 구현.

---

2. V2 컴포넌트 전체 목록 (32개)

모든 컴포넌트는 v2- 접두사를 사용한다. 접두사 없는 컴포넌트는 레거시이므로 사용 금지.

2.1 입력 컴포넌트 (9개)

ID	용도	핵심 설정
v2-input	텍스트, 숫자, 비밀번호, textarea, 슬라이더, 컬러, 버튼	inputType, format(email/tel/url/currency/biz_no), required, readonly, maxLength
v2-select	드롭다운, 콤보박스, 라디오, 체크박스, 태그, 토글, 스왑	mode, source(static/code/db/api/entity/category/distinct/select), searchable, multiple, cascading
v2-date	날짜, 시간, 날짜시간, 날짜범위, 월, 연도	dateType(date/time/datetime), format, range, minDate, maxDate
v2-file-upload	파일/이미지 업로드, 다중 업로드	accept, maxSize, multiple
v2-media	이미지, 비디오, 오디오 표시	mediaType
v2-location-swap-selector	출발지/도착지 선택 및 교환	-
v2-rack-structure	창고 랙 위치 일괄 생성	columns, rows
v2-process-work-standard	품목별 공정 작업기준 관리 (Pre/In/Post-Work)	-
v2-item-routing	품목별 라우팅 버전 및 공정 순서 관리 (3단계 계층)	-

2.2 표시/데이터 컴포넌트 (10개)

ID	용도	핵심 설정
v2-table-list	데이터 테이블 (조회/편집, 페이지네이션, 정렬, 필터)	selectedTable, columns, pagination, displayMode(table/card), checkbox, linkedFilters
v2-table-grouped	그룹화 테이블 (접기/펼치기, 그룹별 집계)	groupConfig(groupByColumn, summary), v2-table-list 기반 확장
v2-table-search-widget	테이블 검색/필터/그룹 바	autoSelectFirstTable, showTableSelector
v2-pivot-grid	다차원 피벗 분석 (행/열/데이터/필터 영역)	fields(area, summaryType, groupInterval), dataSource
v2-text-display	라벨, 제목, 설명 텍스트 표시	fontSize, fontWeight, color, textAlign
v2-card-display	테이블 데이터를 카드 형태로 표시	cardsPerRow, columnMapping(title/subtitle/image/status), cardStyle
v2-aggregation-widget	합계, 평균, 개수, 최대, 최소 집계 카드	items, filters, layout
v2-status-count	상태별 건수 카드 표시	statusField, countField
v2-numbering-rule	자동 코드/번호 채번 (접두사+날짜+순번)	rule, prefix, format
v2-category-manager	트리 기반 카테고리 관리 (3단계 계층)	-

2.3 레이아웃 컴포넌트 (8개)

ID	용도	핵심 설정
v2-split-panel-layout	마스터-디테일 좌우 분할	splitRatio, leftPanel(displayMode/tableName), rightPanel(relation/foreignKey), additionalTabs
v2-tabs-widget	탭 전환, 탭 내 컴포넌트 배치	tabs(id/label/components), defaultTab, orientation
v2-section-card	제목+테두리가 있는 그룹화 컨테이너	title, collapsible
v2-section-paper	배경색 기반 미니멀 그룹화 컨테이너	backgroundColor, padding
v2-divider-line	영역 구분선	orientation, thickness
v2-split-line	캔버스 좌우 분할용 드래그 가능 세로선	-
v2-repeat-container	데이터 수만큼 내부 컴포넌트 반복 렌더링	dataSourceType, layout, gridColumns
v2-repeater	인라인/모달/버튼 모드 반복 데이터 관리	mode(inline/modal/button)

2.4 특수/비즈니스 컴포넌트 (5개)

ID	용도	핵심 설정
v2-button-primary	저장/삭제/조회 등 액션 버튼	text, actionType, variant, webTypeConfig.dataflowConfig
v2-timeline-scheduler	간트차트형 일정/계획 시각화 (드래그/리사이즈)	selectedTable, resourceTable, fieldMapping, zoomLevel, editable
v2-approval-step	결재 단계 스테퍼 시각화	-
v2-bom-tree	BOM 계층 트리 표시 (정전개/역전개)	-
v2-bom-item-editor	BOM 하위품목 트리 편집	-

---

3. 화면 UI 패턴 분류 (7가지)

AI가 화면 개발 요청을 받았을 때, 아래 패턴 중 해당하는 것을 선택하여 구현한다.

패턴 A: 기본 마스터 (검색 + 테이블)

적용 비율: 약 50% (가장 흔함) 적용 화면: 코드관리, 부서정보, 창고정보, 검사기준, 불량관리, 공급업체관리 등

┌─────────────────────────────────────────────────┐
│ v2-table-search-widget                          │
│ [검색필드1] [검색필드2] [조회] [엑셀]            │
├─────────────────────────────────────────────────┤
│ v2-table-list                                   │
│ 제목        [신규] [삭제]                        │
│ ─────────────────────────────────────────────── │
│ □ | 코드 | 이름 | 상태 | 등록일                 │
└─────────────────────────────────────────────────┘

필수 컴포넌트: v2-table-search-widget (1개) + v2-table-list (1개)

패턴 B: 마스터-디테일 (좌우 분할)

적용 비율: 약 25% 적용 화면: 공정관리, 수주관리, 견적관리, 품목라우팅 등

┌──────────────────┬──────────────────────────────┐
│ 마스터 테이블     │ 디테일 테이블/폼              │
│ (좌측 패널)      │ (우측 패널)                   │
│ □ A001 항목1     │ [상세 정보 테이블]             │
│ □ A002 항목2 ←   │                              │
└──────────────────┴──────────────────────────────┘
           v2-split-panel-layout

필수 컴포넌트: v2-split-panel-layout (1개)

패턴 C: 마스터-디테일 + 탭

적용 비율: 약 10% 적용 화면: 거래처관리, 설비정보, 품목정보 등

┌──────────────────┬──────────────────────────────┐
│ 마스터 테이블     │ [기본] [이력] [첨부]          │
│                  │ ┌────────────────────────┐   │
│ □ A001 거래처1   │ │ 탭별 컨텐츠            │   │
│ □ A002 거래처2 ← │ └────────────────────────┘   │
└──────────────────┴──────────────────────────────┘

필수 컴포넌트: v2-split-panel-layout (1개, rightPanel에 additionalTabs 설정)

패턴 D: 카드 뷰

적용 비율: 약 5% 적용 화면: 설비정보, 대시보드, 상품 카탈로그 등

┌─────────────────────────────────────────────────┐
│ v2-table-search-widget                          │
├─────────────────────────────────────────────────┤
│ ┌─────────┐ ┌─────────┐ ┌─────────┐           │
│ │ [이미지]│ │ [이미지]│ │ [이미지]│           │
│ │ 제목    │ │ 제목    │ │ 제목    │           │
│ │ 설명    │ │ 설명    │ │ 설명    │           │
│ └─────────┘ └─────────┘ └─────────┘           │
│              v2-card-display                    │
└─────────────────────────────────────────────────┘

필수 컴포넌트: v2-card-display (1개) + v2-table-search-widget (선택)

패턴 E: 피벗 분석

적용 비율: 약 3% 적용 화면: 매출분석, 재고현황, 생산실적 분석 등

필수 컴포넌트: v2-pivot-grid (1개)

패턴 F: 그룹화 테이블

적용 비율: 약 5% 적용 화면: 품목정보(카테고리별), 입출고관리(구분별), 작업지시(공정별) 등

┌─────────────────────────────────────────────────┐
│ [전체 펼치기] [전체 접기]                         │
├─────────────────────────────────────────────────┤
│ ▼ □ 그룹A                    수량: 150  3건     │
│   ├─ □ 항목1  50개                              │
│   ├─ □ 항목2  50개                              │
│   └─ □ 항목3  50개                              │
│ ► □ 그룹B                    수량: 200  2건     │
└─────────────────────────────────────────────────┘

필수 컴포넌트: v2-table-grouped (1개)

패턴 G: 타임라인/간트차트

적용 비율: 약 2% 적용 화면: 생산계획관리, 설비가동현황 등

┌────────────┬─────────────────────────────────────┐
│            │ 15(수) │ 16(목) │ 17(금) │ 18(토)   │
├────────────┼─────────────────────────────────────┤
│ 설비A      │ ████████████████                    │
│ 설비B      │        █████████████████████        │
│ 설비C      │                    ████████████████ │
└────────────┴─────────────────────────────────────┘

필수 컴포넌트: v2-timeline-scheduler (1개)

---

4. 패턴 판단 의사결정 트리

AI가 화면 요청을 받았을 때 이 트리를 따라 패턴을 결정한다.

Q1. 시간축 기반 일정/간트차트가 필요한가?
├─ YES → 패턴 G (타임라인)
└─ NO ↓

Q2. 다차원 집계/피벗 분석이 필요한가?
├─ YES → 패턴 E (피벗)
└─ NO ↓

Q3. 데이터를 그룹별로 묶어서 접기/펼치기가 필요한가?
├─ YES → 패턴 F (그룹화 테이블)
└─ NO ↓

Q4. 이미지+정보를 카드 형태로 표시하는가?
├─ YES → 패턴 D (카드 뷰)
└─ NO ↓

Q5. 마스터 테이블 선택 시 연관 디테일이 필요한가?
├─ YES → Q5-1. 디테일에 탭이 필요한가?
│        ├─ YES → 패턴 C (마스터-디테일+탭)
│        └─ NO  → 패턴 B (마스터-디테일)
└─ NO → 패턴 A (기본 마스터)

---

5. 화면 구현 불가능/제한 사항

5.1 현재 불가능 (별도 React 개발 필요)

기능	상태	대안
칸반 보드 (드래그앤드롭)	미지원	별도 React 컴포넌트
모바일 네이티브 앱 스타일	미지원	별도 개발
복잡한 차트 (line, bar, pie)	미지원	외부 라이브러리 연동

5.2 이전에 불가능했으나 현재 지원되는 기능

기능	지원 컴포넌트	추가 시점
그룹화 테이블	v2-table-grouped	2026-01
타임라인/간트차트	v2-timeline-scheduler	2026-01
BOM 트리 (정전개/역전개)	v2-bom-tree	2026-02
BOM 하위품목 편집	v2-bom-item-editor	2026-02
결재 스테퍼	v2-approval-step	2026-02

5.3 권장하지 않는 조합

조합	이유
3단계 이상 중첩 분할	화면 복잡도 증가, 성능 저하
탭 안에 탭	사용성 저하
한 화면에 3개 이상 테이블	데이터 로딩 성능
피벗 + 상세 테이블 동시	데이터 과부하

---

6. 화면별 구현 현황 (메뉴 분류)

6.1 기준정보

화면명	패턴	구현 가능	비고
회사정보	A	완전 지원
부서정보	A	완전 지원
품목정보	F 또는 A	완전 지원	카테고리별 그룹화 시 F
BOM관리	B + v2-bom-tree	완전 지원	v2-bom-tree로 트리 구현
공정정보관리	B	완전 지원
공정작업기준	A	완전 지원	v2-process-work-standard 활용 가능
품목라우팅	B	완전 지원	v2-item-routing 활용 가능

6.2 영업관리

화면명	패턴	구현 가능	비고
수주관리	B	완전 지원
견적관리	B	완전 지원
거래처관리	C	완전 지원	탭(기본/이력/첨부)
판매품목정보	A	완전 지원
출하계획관리	A	완전 지원

6.3 생산관리

화면명	패턴	구현 가능	비고
생산계획관리	G	완전 지원	v2-timeline-scheduler
생산관리	A	완전 지원
생산실적관리	A	완전 지원
작업지시	F	완전 지원	공정별 그룹화
공정관리	B	완전 지원

6.4 구매관리

화면명	패턴	구현 가능	비고
발주관리	A	완전 지원
공급업체관리	A	완전 지원
구매입고	A	완전 지원

6.5 설비관리

화면명	패턴	구현 가능	비고
설비정보	C 또는 D	완전 지원	카드뷰 또는 탭

6.6 물류관리

화면명	패턴	구현 가능	비고
창고정보관리	A	완전 지원
입출고관리	F	완전 지원	구분별 그룹화
재고현황	A 또는 E	완전 지원	피벗 분석도 가능

6.7 품질관리

화면명	패턴	구현 가능	비고
검사기준	A	완전 지원
검사정보관리	C	완전 지원	탭(수입검사/공정검사/출하검사)
검사장비관리	A	완전 지원
불량관리	A	완전 지원
클레임관리	A	완전 지원

---

7. 컴포넌트 커버리지 요약

항목	수치
전체 분석 대상 화면	26개
V2 컴포넌트로 구현 가능	26개 (100%)
등록된 V2 컴포넌트 수	32개
화면 UI 패턴 수	7가지 (A~G)

이전 대비 변경 사항:

• BOM 트리 지원 추가 (v2-bom-tree) → BOM관리 완전 지원
• 그룹화 테이블 지원 추가 (v2-table-grouped) → 품목정보, 입출고 등 완전 지원
• 타임라인 지원 추가 (v2-timeline-scheduler) → 생산계획관리 완전 지원
• 결재 스테퍼 추가 (v2-approval-step) → 결재 프로세스 시각화 가능
• 전체 커버리지: 65% → 100% 달성

---

8. UI vs 비즈니스 로직 분리 구조

┌───────────────────────────────┬───────────────────────────────────┐
│        UI 레이아웃             │         제어관리 (비즈니스 로직)    │
│   screen_layouts_v2 (JSON)    │   dataflow_diagrams (JSONB)       │
├───────────────────────────────┼───────────────────────────────────┤
│ - 컴포넌트 배치/크기/위치      │ - 버튼 클릭 시 액션 (INSERT 등)    │
│ - 검색 필드 구성               │ - 조건부 실행                     │
│ - 테이블 컬럼 표시/숨김        │ - 다중 행 일괄 처리               │
│ - 카드/탭/분할 레이아웃        │ - 테이블 간 데이터 이동            │
│ - 페이지네이션/정렬 설정       │ - 외부 시스템 호출                │
└───────────────────────────────┴───────────────────────────────────┘

핵심: V2 컴포넌트는 UI만 담당한다. 버튼 클릭 시 INSERT/UPDATE/DELETE 같은 비즈니스 로직은 dataflow_diagrams 테이블에서 별도 설정한다.

비즈니스 로직 실행 흐름

v2-button-primary 클릭
  → webTypeConfig.dataflowConfig 확인
  → ImprovedButtonActionExecutor 실행
    1. Before 제어 실행 (조건 체크)
    2. Main 액션 실행 (save/delete/update)
    3. After 제어 실행 (후처리)

---

9. 화면 개발 순서 (AI 에이전트용)

Step 1: DB 테이블 생성
  └─ 모든 컬럼 VARCHAR(500), 기본 5개 컬럼 필수 (id, created_date, updated_date, writer, company_code)
  └─ table_labels, table_type_columns, column_labels 메타데이터 등록

Step 2: screen_definitions INSERT
  └─ screen_code = '{company_code}_{순번}'
  └─ table_name = 메인 테이블명

Step 3: screen_layouts_v2 INSERT
  └─ layout_data = V2 레이아웃 JSON (version: "2.0", components 배열)
  └─ 패턴(A~G)에 맞는 컴포넌트 배치

Step 4: dataflow_diagrams INSERT (비즈니스 로직이 필요한 경우)
  └─ 버튼별 액션 정의 (INSERT/UPDATE/DELETE)
  └─ 조건, 필드 매핑 설정

Step 5: menu_info INSERT
  └─ menu_url = '/screen/{screen_code}'
  └─ 적절한 parent_id로 메뉴 트리에 배치

---

10. DB 테이블 구조 레퍼런스

screen_definitions

컬럼	타입	설명
screen_id	integer PK (시퀀스)	화면 고유 ID
screen_name	varchar(100)	화면명
screen_code	varchar(50) UNIQUE	화면 코드 ({company_code}_{순번})
table_name	varchar(100)	기본 테이블명
company_code	varchar(50)	회사 코드
description	text	설명
is_active	char(1)	Y/N/D

screen_layouts_v2

컬럼	타입	설명
layout_id	integer PK	레이아웃 ID
screen_id	integer FK	화면 ID
company_code	varchar(20)	회사 코드
layer_id	integer	레이어 ID (1=기본)
layout_data	jsonb	전체 레이아웃 JSON

layout_data JSON 구조

{
  "version": "2.0",
  "components": [
    {
      "id": "comp_xxx",
      "url": "@/lib/registry/components/v2-table-list",
      "position": { "x": 0, "y": 150, "z": 1 },
      "size": { "width": 1920, "height": 600 },
      "displayOrder": 0,
      "overrides": {
        "label": "품목 목록",
        "tableName": "item_info",
        "columns": [
          { "columnName": "item_code", "displayName": "품목코드", "visible": true }
        ],
        "pagination": { "enabled": true, "pageSize": 20 }
      }
    }
  ],
  "gridSettings": { "columns": 12, "gap": 16, "padding": 16 },
  "screenResolution": { "width": 1920, "height": 1080 }
}

menu_info (주요 컬럼)

컬럼	설명
objid / menu_id	메뉴 PK
screen_id	연결된 화면 ID
menu_url	메뉴 URL (/screen/{screen_code})
company_code	회사 코드