Files
vexplor/docs/screen-implementation-guide/00_analysis/v2-component-usage-guide.md
kjs e8c0828d91 feat: Add process work standard component implementation plan
- Introduced a comprehensive implementation plan for the v2-process-work-standard component, detailing the current state analysis, required database tables, API design, and implementation phases.
- Included a structured file organization plan for both frontend and backend components, ensuring clarity in development and integration.
- Updated the V2Repeater component to support new auto-fill functionalities, including parent sequence generation, enhancing data management capabilities.
- Enhanced the V2RepeaterConfigPanel to allow configuration of parent sequence settings, improving user experience in managing data entries.
2026-02-24 10:15:25 +09:00

25 KiB

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

목적: 다양한 회사에서 V2 컴포넌트를 활용하여 화면을 개발할 때 참고하는 범용 가이드 대상: 화면 설계자, 개발자 버전: 1.1.0 작성일: 2026-02-23 (최종 업데이트)


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

1.1 가능한 화면 유형

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

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

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

참고: 그룹화 테이블(v2-table-grouped)과 타임라인 스케줄러(v2-timeline-scheduler)는 v1.1에서 추가되어 이제 지원됩니다.


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

2.1 입력 컴포넌트 (4개)

ID 이름 용도 주요 옵션
v2-input 입력 텍스트, 숫자, 비밀번호, 슬라이더, 컬러 inputType(text/number/password/slider/color/button), format(email/tel/url/currency/biz_no), required, readonly, maxLength, min, max, step
v2-select 선택 드롭다운, 콤보박스, 라디오, 체크, 태그, 토글, 스왑 mode(dropdown/combobox/radio/check/tag/tagbox/toggle/swap), source(static/code/db/api/entity/category/distinct/select), searchable, multiple, cascading
v2-date 날짜 날짜, 시간, 날짜시간 dateType(date/time/datetime), format, range, minDate, maxDate, showToday
v2-file-upload 파일 업로드 파일/이미지 업로드 -

2.2 표시 컴포넌트 (3개)

ID 이름 용도 주요 옵션
v2-text-display 텍스트 표시 라벨, 제목, 설명 텍스트 fontSize, fontWeight, color, textAlign
v2-card-display 카드 디스플레이 테이블 데이터를 카드 형태로 표시 cardsPerRow, cardSpacing, columnMapping(titleColumn/subtitleColumn/descriptionColumn/imageColumn), cardStyle(imagePosition/imageSize), dataSource(table/static/api)
v2-aggregation-widget 집계 위젯 합계, 평균, 개수, 최대, 최소 items, filters, layout

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

ID 이름 용도 주요 옵션
v2-table-list 테이블 리스트 데이터 조회/편집 테이블 selectedTable, columns, pagination, filter, displayMode(table/card), checkbox, horizontalScroll, linkedFilters, excludeFilter, toolbar, tableStyle, autoLoad
v2-table-search-widget 검색 필터 테이블 검색/필터/그룹 autoSelectFirstTable, showTableSelector, title
v2-pivot-grid 피벗 그리드 다차원 분석 (행/열/데이터 영역) fields(area: row/column/data/filter, summaryType: sum/avg/count/min/max/countDistinct, groupInterval: year/quarter/month/week/day), dataSource(type: table/api/static, joinConfigs, filterConditions)
v2-table-grouped 그룹화 테이블 그룹핑 기능이 포함된 테이블 -

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

ID 이름 용도 주요 옵션
v2-split-panel-layout 분할 패널 마스터-디테일 좌우 분할 splitRatio, resizable, minLeftWidth, minRightWidth, syncSelection, panel별: displayMode(list/table/custom), relation(type/foreignKey), editButton, addButton, deleteButton, additionalTabs
v2-tabs-widget 탭 위젯 탭 전환, 탭 내 컴포넌트 tabs(id/label/order/disabled/components), defaultTab, orientation(horizontal/vertical), allowCloseable, persistSelection
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 리피터 반복 컨트롤 (inline/modal) -

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

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 미디어 이미지/동영상 표시 -
v2-timeline-scheduler 타임라인 스케줄러 시간축 기반 일정/작업 관리 -

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 테이블 설계 확인

가장 먼저 확인:

  1. 회사에서 사용할 테이블 목록
  2. 테이블 간 관계 (FK)
  3. 조회 조건으로 쓸 컬럼
✅ 체크리스트:
□ 테이블명이 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,
    showSizeSelector: true,
    showPageInfo: true
  },
  displayMode: "table",       // "table" | "card"
  checkbox: {
    enabled: true,
    multiple: true,
    position: "left",
    selectAll: true
  },
  horizontalScroll: {         // 가로 스크롤 설정
    enabled: true,
    maxVisibleColumns: 8
  },
  linkedFilters: [],          // 연결 필터 (다른 컴포넌트와 연동)
  excludeFilter: {},          // 제외 필터
  autoLoad: true,             // 자동 데이터 로드
  stickyHeader: false,        // 헤더 고정
  autoWidth: true             // 자동 너비 조정
}

v2-split-panel-layout 필수 설정

{
  leftPanel: {
    displayMode: "table",         // "list" | "table" | "custom"
    tableName: "마스터_테이블명",
    columns: [],                  // 컬럼 설정
    editButton: {                 // 수정 버튼 설정
      enabled: true,
      mode: "auto",              // "auto" | "modal"
      modalScreenId: ""          // 모달 모드 시 화면 ID
    },
    addButton: {                  // 추가 버튼 설정
      enabled: true,
      mode: "auto",
      modalScreenId: ""
    },
    deleteButton: {               // 삭제 버튼 설정
      enabled: true,
      buttonLabel: "삭제",
      confirmMessage: "삭제하시겠습니까?"
    },
    addModalColumns: [],          // 추가 모달 전용 컬럼
    additionalTabs: []            // 추가 탭 설정
  },
  rightPanel: {
    displayMode: "table",
    tableName: "디테일_테이블명",
    relation: {
      type: "detail",            // "join" | "detail" | "custom"
      foreignKey: "master_id",   // 연결 키
      leftColumn: "",            // 좌측 연결 컬럼
      rightColumn: "",           // 우측 연결 컬럼
      keys: []                   // 복합 키
    }
  },
  splitRatio: 30,                 // 좌측 비율 (0-100)
  resizable: true,                // 리사이즈 가능
  minLeftWidth: 200,              // 좌측 최소 너비
  minRightWidth: 300,             // 우측 최소 너비
  syncSelection: true,            // 선택 동기화
  autoLoad: true                  // 자동 로드
}

v2-split-panel-layout 커스텀 모드 (NEW)

패널 내부에 자유롭게 컴포넌트를 배치할 수 있습니다. (v2-tabs-widget과 동일 구조)

{
  leftPanel: {
    displayMode: "custom",  // 커스텀 모드 활성화
    components: [           // 내부 컴포넌트 배열
      {
        id: "btn-save",
        componentType: "v2-button-primary",
        label: "저장",
        position: { x: 10, y: 10 },
        size: { width: 100, height: 40 },
        componentConfig: { buttonAction: "save" }
      },
      {
        id: "tbl-list",
        componentType: "v2-table-list",
        label: "목록",
        position: { x: 10, y: 60 },
        size: { width: 400, height: 300 },
        componentConfig: { selectedTable: "테이블명" }
      }
    ]
  },
  rightPanel: {
    displayMode: "table"  // 기존 모드 유지
  }
}

디자인 모드 기능:

  • 컴포넌트 클릭 → 좌측 설정 패널에서 속성 편집
  • 드래그 핸들(상단)로 이동
  • 리사이즈 핸들(모서리)로 크기 조절
  • 실제 컴포넌트 미리보기 렌더링

v2-card-display 필수 설정

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

5. 공통 컴포넌트 한계점

5.1 현재 불가능한 기능

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

v1.1 업데이트: 그룹화 테이블(v2-table-grouped)과 타임라인 스케줄러(v2-timeline-scheduler)가 추가되어 해당 기능은 이제 지원됩니다.

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: 화면 분석

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

Step 2: 컴포넌트 배치

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

Step 3: 연동 설정

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

Step 4: 테스트

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

9. 요약

V2 컴포넌트 커버리지

화면 유형 지원 여부 주요 컴포넌트
기본 CRUD 완전 v2-table-list, v2-table-search-widget
마스터-디테일 완전 v2-split-panel-layout
탭 화면 완전 v2-tabs-widget
카드 뷰 완전 v2-card-display
피벗 분석 완전 v2-pivot-grid
그룹화 테이블 지원 v2-table-grouped
타임라인/스케줄 지원 v2-timeline-scheduler
파일 업로드 지원 v2-file-upload
트리 뷰 미지원 개발 필요

개발 시 핵심 원칙

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

UI vs 제어 구분

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

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