21 KiB

Raw Blame History

V2 공통 컴포넌트 사용 가이드

목적: 다양한 회사에서 V2 컴포넌트를 활용하여 화면을 개발할 때 참고하는 범용 가이드 대상: 화면 설계자, 개발자 버전: 1.0.0 작성일: 2026-01-30

1. V2 컴포넌트로 가능한 것 / 불가능한 것

1.1 가능한 화면 유형

화면 유형	설명	대표 예시
마스터 관리	단일 테이블 CRUD	회사정보, 부서정보, 코드관리
마스터-디테일	좌측 선택 → 우측 상세	공정관리, 품목라우팅, 견적관리
탭 기반 화면	탭별 다른 테이블/뷰	검사정보관리, 거래처관리
카드 뷰	이미지+정보 카드 형태	설비정보, 대시보드
피벗 분석	다차원 집계	매출분석, 재고현황
반복 컨테이너	데이터 수만큼 UI 반복	주문 상세, 항목 리스트

1.2 불가능한 화면 유형 (별도 개발 필요)

화면 유형	이유	해결 방안
간트 차트 / 타임라인	시간축 기반 UI 없음	별도 컴포넌트 개발 or 외부 라이브러리
트리 뷰 (계층 구조)	트리 컴포넌트 미존재	`v2-tree-view` 개발 필요
그룹화 테이블	그룹핑 기능 미지원	`v2-grouped-table` 개발 필요
드래그앤드롭 보드	칸반 스타일 UI 없음	별도 개발
모바일 앱 스타일	네이티브 앱 UI	별도 개발
복잡한 차트	기본 집계 외 시각화	차트 라이브러리 연동

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

2.1 입력 컴포넌트 (3개)

ID	이름	용도	주요 옵션
`v2-input`	입력	텍스트, 숫자, 비밀번호, 이메일, 전화번호, URL, 여러 줄	inputType, required, readonly, maxLength
`v2-select`	선택	드롭다운, 콤보박스, 라디오, 체크박스	mode, source(distinct/static/code/entity), multiple
`v2-date`	날짜	날짜, 시간, 날짜시간, 날짜범위, 월, 연도	dateType, format, showTime

2.2 표시 컴포넌트 (3개)

ID	이름	용도	주요 옵션
`v2-text-display`	텍스트 표시	라벨, 제목, 설명 텍스트	fontSize, fontWeight, color, textAlign
`v2-card-display`	카드 디스플레이	테이블 데이터를 카드 형태로 표시	cardsPerRow, showImage, columnMapping
`v2-aggregation-widget`	집계 위젯	합계, 평균, 개수, 최대, 최소	items, filters, layout

2.3 테이블/데이터 컴포넌트 (3개)

ID	이름	용도	주요 옵션
`v2-table-list`	테이블 리스트	데이터 조회/편집 테이블	selectedTable, columns, pagination, filter
`v2-table-search-widget`	검색 필터	테이블 검색/필터/그룹	autoSelectFirstTable, showTableSelector
`v2-pivot-grid`	피벗 그리드	다차원 분석 (행/열/데이터 영역)	fields, totals, aggregation

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

ID	이름	용도	주요 옵션
`v2-split-panel-layout`	분할 패널	마스터-디테일 좌우 분할	splitRatio, resizable, relation
`v2-tabs-widget`	탭 위젯	탭 전환, 탭 내 컴포넌트	tabs, activeTabId
`v2-section-card`	섹션 카드	제목+테두리 그룹화	title, collapsible, padding
`v2-section-paper`	섹션 페이퍼	배경색 그룹화	backgroundColor, padding, shadow
`v2-divider-line`	구분선	영역 구분	orientation, thickness
`v2-repeat-container`	리피터 컨테이너	데이터 수만큼 반복 렌더링	dataSourceType, layout, gridColumns
`v2-repeater`	리피터	반복 컨트롤	-
`v2-repeat-screen-modal`	반복 화면 모달	모달 반복	-

2.5 액션/특수 컴포넌트 (6개)

ID	이름	용도	주요 옵션
`v2-button-primary`	기본 버튼	저장, 삭제 등 액션	text, actionType, variant
`v2-numbering-rule`	채번규칙	자동 코드/번호 생성	rule, prefix, format
`v2-category-manager`	카테고리 관리자	카테고리 관리 UI	-
`v2-location-swap-selector`	위치 교환	위치 선택/교환	-
`v2-rack-structure`	랙 구조	창고 랙 시각화	-
`v2-media`	미디어	이미지/동영상 표시	-

3. 화면 패턴별 컴포넌트 조합

3.1 패턴 A: 기본 마스터 화면 (가장 흔함)

적용 화면: 코드관리, 사용자관리, 부서정보, 창고정보 등

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

필수 컴포넌트:

v2-table-search-widget (1개)
v2-table-list (1개)

설정 포인트:

테이블명 지정
검색 대상 컬럼 설정
컬럼 표시/숨김 설정

3.2 패턴 B: 마스터-디테일 화면

적용 화면: 공정관리, 견적관리, 수주관리, 품목라우팅 등

┌──────────────────┬──────────────────────────────┐
│ v2-table-list    │ v2-table-list 또는 폼        │
│ (마스터)         │ (디테일)                     │
│ ───────────────  │                              │
│ □ A001 항목1     │ [상세 정보]                  │
│ □ A002 항목2 ←   │                              │
│ □ A003 항목3     │                              │
└──────────────────┴──────────────────────────────┘
        v2-split-panel-layout

필수 컴포넌트:

v2-split-panel-layout (1개)
v2-table-list (2개: 마스터, 디테일)

설정 포인트:

splitRatio: 좌우 비율 (기본 30:70)
relation.type: join / detail / custom
relation.foreignKey: 연결 키 컬럼

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

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

┌──────────────────┬──────────────────────────────┐
│ v2-table-list    │ v2-tabs-widget               │
│ (마스터)         │ ┌────┬────┬────┐            │
│                  │ │기본│이력│첨부│            │
│ □ A001 거래처1   │ └────┴────┴────┘            │
│ □ A002 거래처2 ← │ [탭별 컨텐츠]               │
└──────────────────┴──────────────────────────────┘

필수 컴포넌트:

v2-split-panel-layout (1개)
v2-table-list (1개: 마스터)
v2-tabs-widget (1개)

설정 포인트:

탭별 표시할 테이블/폼 설정
마스터 선택 시 탭 컨텐츠 연동

3.4 패턴 D: 카드 뷰

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

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

필수 컴포넌트:

v2-table-search-widget (1개)
v2-card-display (1개)

설정 포인트:

cardsPerRow: 한 행당 카드 수
columnMapping: 제목, 부제목, 이미지, 상태 필드 매핑
cardStyle: 이미지 위치, 크기

3.5 패턴 E: 피벗 분석

적용 화면: 매출분석, 재고현황, 생산실적 분석 등

┌─────────────────────────────────────────────────┐
│ v2-pivot-grid                                   │
│         │ 2024년 │ 2025년 │ 2026년 │ 합계     │
│ ─────────────────────────────────────────────── │
│ 지역A   │ 1,000  │ 1,200  │ 1,500  │ 3,700   │
│ 지역B   │ 2,000  │ 2,500  │ 3,000  │ 7,500   │
│ 합계    │ 3,000  │ 3,700  │ 4,500  │ 11,200  │
└─────────────────────────────────────────────────┘

필수 컴포넌트:

v2-pivot-grid (1개)

설정 포인트:

fields[].area: row / column / data / filter
fields[].summaryType: sum / avg / count / min / max
fields[].groupInterval: 날짜 그룹화 (year/quarter/month)

4. 회사별 개발 시 핵심 체크포인트

4.1 테이블 설계 확인

가장 먼저 확인:

회사에서 사용할 테이블 목록
테이블 간 관계 (FK)
조회 조건으로 쓸 컬럼

✅ 체크리스트:
□ 테이블명이 DB에 존재하는가?
□ company_code 컬럼이 있는가? (멀티테넌시)
□ 마스터-디테일 관계의 FK가 정의되어 있는가?
□ 검색 대상 컬럼에 인덱스가 있는가?

4.2 화면 패턴 판단

질문을 통한 판단:

질문	예 → 패턴
단일 테이블만 조회/편집?	패턴 A (기본 마스터)
마스터 선택 시 디테일 표시?	패턴 B (마스터-디테일)
상세에 탭이 필요?	패턴 C (마스터-디테일+탭)
이미지+정보 카드 형태?	패턴 D (카드 뷰)
다차원 집계/분석?	패턴 E (피벗)

4.3 컴포넌트 설정 필수 항목

v2-table-list 필수 설정

{
  selectedTable: "테이블명",  // 필수
  columns: [                  // 표시할 컬럼
    { columnName: "id", displayName: "ID", visible: true, sortable: true },
    // ...
  ],
  pagination: {
    enabled: true,
    pageSize: 20
  }
}

v2-split-panel-layout 필수 설정

{
  leftPanel: {
    tableName: "마스터_테이블명"
  },
  rightPanel: {
    tableName: "디테일_테이블명",
    relation: {
      type: "detail",          // join | detail | custom
      foreignKey: "master_id"  // 연결 키
    }
  },
  splitRatio: 30  // 좌측 비율
}

v2-card-display 필수 설정

{
  dataSource: "table",
  columnMapping: {
    title: "name",       // 제목 필드
    subtitle: "code",    // 부제목 필드
    image: "image_url",  // 이미지 필드 (선택)
    status: "status"     // 상태 필드 (선택)
  },
  cardsPerRow: 3
}

5. 공통 컴포넌트 한계점

5.1 현재 불가능한 기능

기능	상태	대안
트리 뷰 (BOM, 조직도)	❌ 미지원	테이블로 대체 or 별도 개발
그룹화 테이블	❌ 미지원	일반 테이블로 대체 or 별도 개발
간트 차트	❌ 미지원	별도 개발 필요
드래그앤드롭 정렬	❌ 미지원	순서 컬럼으로 대체
인라인 편집	⚠️ 제한적	모달 편집으로 대체
복잡한 차트	❌ 미지원	외부 라이브러리 연동

5.2 권장하지 않는 조합

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

6. 제어관리 (비즈니스 로직) - 별도 설정 필수

핵심: V2 컴포넌트는 UI만 담당합니다. 비즈니스 로직은 제어관리에서 별도 설정해야 합니다.

6.1 UI vs 제어 분리 구조

┌─────────────────────────────────────────────────────────────────┐
│                         화면 구성                               │
├─────────────────────────────┬───────────────────────────────────┤
│        UI 레이아웃           │         제어관리                  │
│   (screen_layouts_v2)       │   (dataflow_diagrams)             │
├─────────────────────────────┼───────────────────────────────────┤
│ • 컴포넌트 배치              │ • 버튼 클릭 시 액션               │
│ • 검색 필드 구성             │ • INSERT/UPDATE/DELETE 설정      │
│ • 테이블 컬럼 표시           │ • 조건부 실행                     │
│ • 카드/탭 레이아웃           │ • 다중 행 처리                    │
│                             │ • 테이블 간 데이터 이동            │
└─────────────────────────────┴───────────────────────────────────┘

6.2 HTML에서 파악 가능/불가능

구분	HTML에서 파악	이유
컴포넌트 배치	✅ 가능	HTML 구조에서 보임
검색 필드	✅ 가능	input 태그로 확인
테이블 컬럼	✅ 가능	thead에서 확인
저장 테이블	❌ 불가능	JS/백엔드에서 처리
버튼 액션	❌ 불가능	제어관리에서 설정
전/후 처리	❌ 불가능	제어관리에서 설정
다중 행 처리	❌ 불가능	제어관리에서 설정
테이블 간 관계	❌ 불가능	DB/제어관리에서 설정

6.3 제어관리 설정 항목

트리거 타입

버튼 클릭 전 (before): 클릭 직전 실행
버튼 클릭 후 (after): 클릭 완료 후 실행

액션 타입

INSERT: 새로운 데이터 삽입
UPDATE: 기존 데이터 수정
DELETE: 데이터 삭제

조건 설정

// 예: 선택된 행의 상태가 '대기'인 경우에만 실행
{
  field: "status",
  operator: "=",
  value: "대기",
  dataType: "string"
}

필드 매핑

// 예: 소스 테이블의 값을 타겟 테이블로 이동
{
  sourceTable: "order_master",
  sourceField: "order_no",
  targetTable: "order_history",
  targetField: "order_no"
}

6.4 제어관리 예시: 수주 확정 버튼

시나리오: 수주 목록에서 3건 선택 후 [확정] 버튼 클릭

┌─────────────────────────────────────────────────────────────────┐
│ [확정] 버튼 클릭                                                 │
├─────────────────────────────────────────────────────────────────┤
│ 1. 조건 체크: status = '대기' 인 행만                            │
│ 2. UPDATE order_master SET status = '확정' WHERE id IN (선택)   │
│ 3. INSERT order_history (수주이력 테이블에 기록)                 │
│ 4. 외부 시스템 호출 (ERP 연동)                                   │
└─────────────────────────────────────────────────────────────────┘

제어관리 설정:

{
  "triggerType": "after",
  "actions": [
    {
      "actionType": "update",
      "targetTable": "order_master",
      "conditions": [{ "field": "status", "operator": "=", "value": "대기" }],
      "fieldMappings": [{ "targetField": "status", "defaultValue": "확정" }]
    },
    {
      "actionType": "insert",
      "targetTable": "order_history",
      "fieldMappings": [
        { "sourceField": "order_no", "targetField": "order_no" },
        { "sourceField": "customer_name", "targetField": "customer_name" }
      ]
    }
  ]
}

6.5 회사별 개발 시 제어관리 체크리스트

□ 버튼별 액션 정의
  - 어떤 버튼이 있는가?
  - 각 버튼 클릭 시 무슨 동작?

□ 저장/수정/삭제 대상 테이블
  - 메인 테이블은?
  - 이력 테이블은?
  - 연관 테이블은?

□ 조건부 실행
  - 특정 상태일 때만 실행?
  - 특정 값 체크 필요?

□ 다중 행 처리
  - 여러 행 선택 후 일괄 처리?
  - 각 행별 개별 처리?

□ 외부 연동
  - ERP/MES 등 외부 시스템 호출?
  - API 연동 필요?

7. 회사별 커스터마이징 영역

7.1 컴포넌트로 처리되는 영역 (표준화)

영역	설명
UI 레이아웃	컴포넌트 배치, 크기, 위치
검색 조건	화면 디자이너에서 설정
테이블 컬럼	표시/숨김, 순서, 너비
기본 CRUD	조회, 저장, 삭제 자동 처리
페이지네이션	자동 처리
정렬/필터	자동 처리

7.2 회사별 개발 필요 영역

영역	설명	개발 방법
비즈니스 로직	저장 전/후 검증, 계산	데이터플로우 또는 백엔드 API
특수 UI	간트, 트리, 차트 등	별도 컴포넌트 개발
외부 연동	ERP, MES 등 연계	외부 호출 설정
리포트/인쇄	전표, 라벨 출력	리포트 컴포넌트
결재 프로세스	승인/반려 흐름	워크플로우 설정

8. 빠른 개발 가이드

Step 1: 화면 분석

어떤 테이블을 사용하는가?
테이블 간 관계는?
어떤 패턴인가? (A/B/C/D/E)

Step 2: 컴포넌트 배치

화면 디자이너에서 패턴에 맞는 컴포넌트 배치
각 컴포넌트에 테이블/컬럼 설정

Step 3: 연동 설정

마스터-디테일 관계 설정 (FK)
검색 조건 설정
버튼 액션 설정

Step 4: 테스트

데이터 조회 확인
마스터 선택 시 디테일 연동 확인
저장/삭제 동작 확인

9. 요약

V2 컴포넌트 커버리지

화면 유형	지원 여부	주요 컴포넌트
기본 CRUD	✅ 완전	v2-table-list, v2-table-search-widget
마스터-디테일	✅ 완전	v2-split-panel-layout
탭 화면	✅ 완전	v2-tabs-widget
카드 뷰	✅ 완전	v2-card-display
피벗 분석	✅ 완전	v2-pivot-grid
그룹화 테이블	❌ 미지원	개발 필요
트리 뷰	❌ 미지원	개발 필요
간트 차트	❌ 미지원	개발 필요

개발 시 핵심 원칙

테이블 먼저: DB 테이블 구조 확인이 최우선
패턴 판단: 5가지 패턴 중 어디에 해당하는지 판단
표준 조합: 검증된 컴포넌트 조합 사용
한계 인식: 불가능한 UI는 조기에 식별하여 별도 개발 계획
멀티테넌시: 모든 테이블에 company_code 필터링 필수
제어관리 필수: UI 완성 후 버튼별 비즈니스 로직 설정 필수

UI vs 제어 구분

영역	담당	설정 위치
화면 레이아웃	V2 컴포넌트	화면 디자이너
비즈니스 로직	제어관리	dataflow_diagrams
외부 연동	외부호출 설정	external_call_configs

HTML에서 배낄 수 있는 것: UI 구조만 별도 설정 필요한 것: 저장 테이블, 버튼 액션, 조건 처리, 다중 행 처리

21 KiB Raw Blame History

V2 공통 컴포넌트 사용 가이드

1. V2 컴포넌트로 가능한 것 / 불가능한 것

1.1 가능한 화면 유형

1.2 불가능한 화면 유형 (별도 개발 필요)

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

2.1 입력 컴포넌트 (3개)

2.2 표시 컴포넌트 (3개)

2.3 테이블/데이터 컴포넌트 (3개)

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

2.5 액션/특수 컴포넌트 (6개)

3. 화면 패턴별 컴포넌트 조합

3.1 패턴 A: 기본 마스터 화면 (가장 흔함)

3.2 패턴 B: 마스터-디테일 화면

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

3.4 패턴 D: 카드 뷰

3.5 패턴 E: 피벗 분석

4. 회사별 개발 시 핵심 체크포인트

4.1 테이블 설계 확인

4.2 화면 패턴 판단

4.3 컴포넌트 설정 필수 항목

v2-table-list 필수 설정

v2-split-panel-layout 필수 설정

v2-card-display 필수 설정

5. 공통 컴포넌트 한계점

5.1 현재 불가능한 기능

5.2 권장하지 않는 조합

6. 제어관리 (비즈니스 로직) - 별도 설정 필수

6.1 UI vs 제어 분리 구조

6.2 HTML에서 파악 가능/불가능

6.3 제어관리 설정 항목

트리거 타입

액션 타입

조건 설정

필드 매핑

6.4 제어관리 예시: 수주 확정 버튼

6.5 회사별 개발 시 제어관리 체크리스트

7. 회사별 커스터마이징 영역

7.1 컴포넌트로 처리되는 영역 (표준화)

7.2 회사별 개발 필요 영역

8. 빠른 개발 가이드

Step 1: 화면 분석

Step 2: 컴포넌트 배치

Step 3: 연동 설정

Step 4: 테스트

9. 요약

V2 컴포넌트 커버리지

개발 시 핵심 원칙

UI vs 제어 구분

21 KiB

Raw Blame History