- 여러 문서의 내용을 업데이트하여 최신 정보를 반영하였습니다.
- 컴포넌트 개발 가이드와 관련된 문서의 목차를 재구성하고, V2 및 Zod 레이아웃 시스템에 대한 내용을 추가하였습니다.
- 화면 컴포넌트 개발 가이드를 개선하여 핵심 원칙과 패턴을 명확히 설명하였습니다.
- 불필요한 문서 및 가이드를 삭제하고, 통합된 가이드를 통해 개발자들이 쉽게 참고할 수 있도록 하였습니다.
현재 68개 이상으로 파편화된 화면 관리 컴포넌트들을 **9개의 핵심 통합 컴포넌트(V2 Components)**로 재편합니다.
각 컴포넌트는 속성(Config) 설정을 통해 다양한 형태(View Mode)와 기능(Behavior)을 수행하도록 설계되어, 유지보수성과 확장성을 극대화합니다.
현재 컴포넌트 현황 (AS-IS)
카테고리
파일 수
주요 파일들
Widget 타입별
14개
TextWidget, NumberWidget, SelectWidget, DateWidget, EntityWidget 등
Config Panel
28개
TextConfigPanel, SelectConfigPanel, DateConfigPanel 등
TO-BE: V2List 컴포넌트 배치 후 editable: true, viewMode: "table" 설정.
4. 실행 로드맵 (Action Plan)
Phase 0: 준비 단계 (1주)
통합 작업 전 필수 분석 및 설계를 진행합니다.
기존 컴포넌트 사용 현황 분석 (화면별 위젯 사용 빈도 조사)
데이터 마이그레이션 전략 설계 (widgetType → V2Widget.type 매핑 정의)
sys_input_type 테이블 JSON Schema 설계
DynamicConfigPanel 프로토타입 설계
Phase 1: 입력 위젯 통합 (2주)
가장 중복이 많고 효과가 즉각적인 입력 필드부터 통합합니다.
V2Input 구현: Text, Number, Email, Tel, Password 통합
V2Select 구현: Select, Radio, Checkbox, Boolean 통합
V2Date 구현: Date, DateTime, Time 통합
기존 위젯과 병행 운영 (deprecated 마킹, 삭제하지 않음)
Phase 2: Config Panel 통합 (2주)
28개의 ConfigPanel을 단일 동적 패널로 통합합니다.
DynamicConfigPanel 구현: DB 스키마 기반 속성 UI 자동 생성
sys_input_type 테이블에 위젯별 JSON Schema 정의 저장
기존 ConfigPanel과 병행 운영 (삭제하지 않음)
Phase 3: 데이터/레이아웃 위젯 통합 (2주)
프로젝트의 데이터를 보여주는 핵심 뷰를 통합합니다.
V2List 구현: Table, Card, Repeater 통합 렌더러 개발
V2Layout 구현: Split Panel, Grid, Flex 통합
V2Group 구현: Tab, Accordion, Modal 통합
Phase 4: 안정화 및 마이그레이션 (2주)
신규 컴포넌트 안정화 후 점진적 전환을 진행합니다.
신규 화면은 V2 컴포넌트만 사용하도록 가이드
기존 화면 데이터 마이그레이션 스크립트 개발
마이그레이션 테스트 (스테이징 환경)
문서화 및 개발 가이드 작성
Phase 5: 레거시 정리 (추후 결정)
충분한 안정화 기간 후 레거시 컴포넌트 정리를 검토합니다.
사용 현황 재분석 (V2 전환율 확인)
미전환 화면 목록 정리
레거시 컴포넌트 삭제 여부 결정 (별도 회의)
5. 데이터 마이그레이션 전략
5.1 위젯 타입 매핑 테이블
기존 widgetType을 신규 V2 컴포넌트로 매핑합니다.
기존 widgetType
신규 컴포넌트
속성 설정
text
V2Input
type: "text"
number
V2Input
type: "number"
email
V2Input
type: "text", format: "email"
tel
V2Input
type: "text", format: "tel"
select
V2Select
mode: "dropdown"
radio
V2Select
mode: "radio"
checkbox
V2Select
mode: "check"
date
V2Date
type: "date"
datetime
V2Date
type: "datetime"
textarea
V2Text
mode: "simple"
file
V2Media
type: "file"
image
V2Media
type: "image"
5.2 마이그레이션 원칙
비파괴적 전환: 기존 데이터 구조 유지, 신규 필드 추가 방식
하위 호환성: 기존 widgetType 필드는 유지, v2Type 필드 추가
점진적 전환: 화면 수정 시점에 자동 또는 수동 전환
6. 기대 효과
컴포넌트 수 감소: 68개 → 9개 (관리 포인트 87% 감소)
Config Panel 통합: 28개 → 1개 (DynamicConfigPanel)
유연한 UI 변경: 컴포넌트 교체 없이 속성 변경만으로 UI 모드 전환 가능
Low-Code 확장성: 새로운 유형의 입력 방식이 필요할 때 코딩 없이 DB 설정만으로 추가 가능
7. 리스크 및 대응 방안
리스크
영향도
대응 방안
기존 화면 호환성 깨짐
높음
병행 운영 + 하위 호환성 유지
마이그레이션 데이터 손실
높음
백업 필수 + 롤백 스크립트 준비
개발자 학습 곡선
중간
상세 가이드 문서 + 예제 코드 제공
성능 저하 (동적 렌더링)
중간
메모이제이션 + 지연 로딩 적용
8. 현재 컴포넌트 매핑 분석
8.1 Registry 등록 컴포넌트 전수 조사 (44개)
현재 frontend/lib/registry/components/에 등록된 모든 컴포넌트의 통합 가능 여부를 분석했습니다.
V2Input으로 통합 (4개)
현재 컴포넌트
매핑 속성
비고
text-input
type: "text"
number-input
type: "number"
slider-basic
type: "slider"
속성 추가 필요
button-primary
type: "button"
별도 검토
V2Select로 통합 (8개)
현재 컴포넌트
매핑 속성
비고
select-basic
mode: "dropdown"
checkbox-basic
mode: "check"
radio-basic
mode: "radio"
toggle-switch
mode: "toggle"
속성 추가 필요
autocomplete-search-input
mode: "dropdown", searchable: true
entity-search-input
source: "entity"
mail-recipient-selector
mode: "multi", type: "email"
복합 컴포넌트
location-swap-selector
mode: "swap"
특수 UI
V2Date로 통합 (1개)
현재 컴포넌트
매핑 속성
비고
date-input
type: "date"
V2Text로 통합 (1개)
현재 컴포넌트
매핑 속성
비고
textarea-basic
mode: "simple"
V2Media로 통합 (3개)
현재 컴포넌트
매핑 속성
비고
file-upload
type: "file"
image-widget
type: "image"
image-display
type: "image", readonly: true
V2List로 통합 (8개)
현재 컴포넌트
매핑 속성
비고
table-list
viewMode: "table"
card-display
viewMode: "card"
repeater-field-group
editable: true
modal-repeater-table
viewMode: "table", modal: true
simple-repeater-table
viewMode: "table", simple: true
repeat-screen-modal
viewMode: "card", modal: true
table-search-widget
viewMode: "table", searchable: true
tax-invoice-list
viewMode: "table", bizType: "tax"
특수 비즈니스
V2Layout으로 통합 (4개)
현재 컴포넌트
매핑 속성
비고
split-panel-layout
type: "split"
split-panel-layout2
type: "split", version: 2
divider-line
type: "divider"
속성 추가 필요
screen-split-panel
type: "screen-embed"
화면 임베딩
V2Group으로 통합 (5개)
현재 컴포넌트
매핑 속성
비고
accordion-basic
type: "accordion"
tabs
type: "tabs"
section-paper
type: "section"
section-card
type: "card-section"
universal-form-modal
type: "form-modal"
복합 컴포넌트
V2Biz로 통합 (7개)
현재 컴포넌트
매핑 속성
비고
flow-widget
type: "flow"
플로우 관리
rack-structure
type: "rack"
창고 렉 구조
map
type: "map"
지도
numbering-rule
type: "numbering"
채번 규칙
category-manager
type: "category"
카테고리 관리
customer-item-mapping
type: "mapping"
거래처-품목 매핑
related-data-buttons
type: "related-buttons"
연관 데이터
별도 검토 필요 (3개)
현재 컴포넌트
문제점
제안
conditional-container
조건부 렌더링 로직
공통 속성으로 분리
selected-items-detail-input
복합 (선택+상세입력)
V2List + V2Group 조합
text-display
읽기 전용 텍스트
V2Input (readonly: true)
8.2 매핑 분석 결과
┌─────────────────────────────────────────────────────────┐
│ 전체 44개 컴포넌트 분석 결과 │
├─────────────────────────────────────────────────────────┤
│ ✅ 즉시 통합 가능 : 36개 (82%) │
│ ⚠️ 속성 추가 후 통합 : 5개 (11%) │
│ 🔄 별도 검토 필요 : 3개 (7%) │
└─────────────────────────────────────────────────────────┘
8.3 속성 확장 필요 사항
V2Input 속성 확장
// 기존
type:"text"|"number"|"password";// 확장
type:"text"|"number"|"password"|"slider"|"color"|"button";
V2Select 속성 확장
// 기존
mode:"dropdown"|"radio"|"check"|"tag";// 확장
mode:"dropdown"|"radio"|"check"|"tag"|"toggle"|"swap";
V2Layout 속성 확장
// 기존
type:"grid"|"split"|"flex";// 확장
type:"grid"|"split"|"flex"|"divider"|"screen-embed";
8.4 조건부 렌더링 공통화
conditional-container의 기능을 모든 컴포넌트에서 사용 가능한 공통 속성으로 분리합니다.
// 모든 V2 컴포넌트에 적용 가능한 공통 속성
interfaceBaseV2Props{// ... 기존 속성
/** 조건부 렌더링 설정 */conditional?:{enabled: boolean;field: string;// 참조할 필드명
operator:"="|"!="|">"|"<"|"in"|"notIn";value: any;// 비교 값
hideOnFalse?: boolean;// false일 때 숨김 (기본: true)
};}
9. 계층 구조(Hierarchy) 컴포넌트 전략
9.1 현재 계층 구조 지원 현황
DB 테이블 cascading_hierarchy_group에서 4가지 계층 타입을 지원합니다:
타입
설명
예시
MULTI_TABLE
다중 테이블 계층
국가 > 도시 > 구
SELF_REFERENCE
자기 참조 (단일 테이블)
조직도, 메뉴
BOM
자재명세서 구조
부품 > 하위부품
TREE
일반 트리
카테고리
9.2 통합 방안: V2Hierarchy 신설 (10번째 컴포넌트)
계층 구조는 일반 입력/표시 위젯과 성격이 다르므로 별도 컴포넌트로 분리합니다.
interfaceV2HierarchyProps{/** 계층 유형 */type:"tree"|"org"|"bom"|"cascading";/** 표시 방식 */viewMode:"tree"|"table"|"indent"|"dropdown";/** 계층 그룹 코드 (cascading_hierarchy_group 연동) */source: string;/** 편집 가능 여부 */editable?: boolean;/** 드래그 정렬 가능 */draggable?: boolean;/** BOM 수량 표시 (BOM 타입 전용) */showQty?: boolean;/** 최대 레벨 제한 */maxLevel?: number;}
9.3 활용 예시
설정
결과
type: "tree", viewMode: "tree"
카테고리 트리뷰
type: "org", viewMode: "tree"
조직도
type: "bom", viewMode: "indent"
BOM 들여쓰기 테이블
type: "cascading", viewMode: "dropdown"
연쇄 셀렉트 (국가>도시>구)
10. 최종 통합 컴포넌트 목록 (10개)
#
컴포넌트
역할
커버 범위
1
V2Input
단일 값 입력
text, number, slider, button 등
2
V2Select
선택 입력
dropdown, radio, checkbox, toggle 등
3
V2Date
날짜/시간 입력
date, datetime, time, range
4
V2Text
다중 행 텍스트
textarea, rich editor, markdown
5
V2Media
파일/미디어
file, image, video, audio
6
V2List
데이터 목록
table, card, repeater, kanban
7
V2Layout
레이아웃 배치
grid, split, flex, divider
8
V2Group
콘텐츠 그룹화
tabs, accordion, section, modal
9
V2Biz
비즈니스 특화
flow, rack, map, numbering 등
10
V2Hierarchy
계층 구조
tree, org, bom, cascading
11. 연쇄관계 관리 메뉴 통합 전략
11.1 현재 연쇄관계 관리 현황
관리 메뉴: 연쇄 드롭다운 통합 관리 (6개 탭)
탭
DB 테이블
실제 데이터
복잡도
2단계 연쇄관계
cascading_relation
2건
낮음
다단계 계층
cascading_hierarchy_group/level
1건
높음
조건부 필터
cascading_condition
0건
중간
자동 입력
cascading_auto_fill_group/mapping
0건
낮음
상호 배제
cascading_mutual_exclusion
0건
낮음
카테고리 값 연쇄
category_value_cascading_group/mapping
2건
중간
11.2 통합 방향: 속성 기반 vs 공통 정의
판단 기준
기능
재사용 빈도
설정 복잡도
권장 방식
2단계 연쇄
낮음
간단
속성에 inline 정의
다단계 계층
높음
복잡
공통 정의 유지
조건부 필터
낮음
간단
속성에 inline 정의
자동 입력
낮음
간단
속성에 inline 정의
상호 배제
낮음
간단
속성에 inline 정의
카테고리 값 연쇄
중간
중간
카테고리 관리와 통합
11.3 속성 통합 설계
2단계 연쇄 → V2Select 속성
// AS-IS: 별도 관리 메뉴에서 정의 후 참조
<SelectWidgetcascadingRelation="WAREHOUSE_LOCATION"/>// TO-BE: 컴포넌트 속성에서 직접 정의
<V2Selectsource="db"table="warehouse_location"valueColumn="location_code"labelColumn="location_name"cascading={{parentField:"warehouse_code",// 같은 화면 내 부모 필드
filterColumn:"warehouse_code",// 필터링할 컬럼
clearOnChange: true// 부모 변경 시 초기화
}}/>
조건부 필터 → 공통 conditional 속성
// AS-IS: 별도 관리 메뉴에서 조건 정의
// cascading_condition 테이블에 저장
// TO-BE: 모든 컴포넌트에 공통 속성으로 적용
<V2Inputconditional={{enabled: true,field:"order_type",// 참조할 필드
operator:"=",// 비교 연산자
value:"EXPORT",// 비교 값
action:"show",// show | hide | disable | enable
}}/>
자동 입력 → autoFill 속성
// AS-IS: cascading_auto_fill_group 테이블에 정의
// TO-BE: 컴포넌트 속성에서 직접 정의
<V2InputautoFill={{enabled: true,sourceTable:"company_mng",// 조회할 테이블
filterColumn:"company_code",// 필터링 컬럼
userField:"companyCode",// 사용자 정보 필드
displayColumn:"company_name",// 표시할 컬럼
}}/>
상호 배제 → mutualExclusion 속성
// AS-IS: cascading_mutual_exclusion 테이블에 정의
// TO-BE: 컴포넌트 속성에서 직접 정의
<V2SelectmutualExclusion={{enabled: true,targetField:"sub_category",// 상호 배제 대상 필드
type:"exclusive",// exclusive | inclusive
}}/>
11.4 관리 메뉴 정리 계획
현재 메뉴
TO-BE
비고
연쇄 드롭다운 통합 관리
삭제
6개 탭 전체 제거
├─ 2단계 연쇄관계
V2Select 속성
inline 정의
├─ 다단계 계층
테이블관리로 이동
복잡한 구조 유지 필요
├─ 조건부 필터
공통 conditional 속성
모든 컴포넌트에 적용
├─ 자동 입력
autoFill 속성
컴포넌트별 정의
├─ 상호 배제
mutualExclusion 속성
컴포넌트별 정의
└─ 카테고리 값 연쇄
카테고리 관리로 이동
기존 메뉴 통합
11.5 DB 테이블 정리 (Phase 5)
테이블
조치
시점
cascading_relation
마이그레이션 후 삭제
Phase 5
cascading_condition
삭제 (데이터 없음)
Phase 5
cascading_auto_fill_*
삭제 (데이터 없음)
Phase 5
cascading_mutual_exclusion
삭제 (데이터 없음)
Phase 5
cascading_hierarchy_*
유지
-
category_value_cascading_*
유지 (카테고리 관리)
-
11.6 마이그레이션 스크립트 필요 항목
-- cascading_relation → 화면 레이아웃 데이터로 마이그레이션
-- 기존 2건의 연쇄관계를 사용하는 화면을 찾아서
-- 해당 컴포넌트의 cascading 속성으로 변환
-- 예시: WAREHOUSE_LOCATION 연쇄관계
-- 이 관계를 사용하는 화면의 컴포넌트에
-- cascading: { parentField: "warehouse_code", filterColumn: "warehouse_code" }
-- 속성 추가
12. 최종 아키텍처 요약
12.1 통합 컴포넌트 (10개)
#
컴포넌트
역할
1
V2Input
단일 값 입력 (text, number, slider 등)
2
V2Select
선택 입력 (dropdown, radio, checkbox 등)
3
V2Date
날짜/시간 입력
4
V2Text
다중 행 텍스트 (textarea, rich editor)
5
V2Media
파일/미디어 (file, image)
6
V2List
데이터 목록 (table, card, repeater)
7
V2Layout
레이아웃 배치 (grid, split, flex)
8
V2Group
콘텐츠 그룹화 (tabs, accordion, section)
9
V2Biz
비즈니스 특화 (flow, rack, map 등)
10
V2Hierarchy
계층 구조 (tree, org, bom, cascading)
12.2 공통 속성 (모든 컴포넌트에 적용)
interfaceBaseV2Props{// 기본 속성
id: string;label?: string;required?: boolean;readonly?:boolean;disabled?: boolean;// 스타일
style?: ComponentStyle;className?: string;// 조건부 렌더링 (conditional-container 대체)
conditional?:{enabled: boolean;field: string;operator:|"="|"!="|">"|"<"|"in"|"notIn"|"isEmpty"|"isNotEmpty";value: any;action:"show"|"hide"|"disable"|"enable";};// 자동 입력 (autoFill 대체)
autoFill?:{enabled: boolean;sourceTable: string;filterColumn: string;userField:"companyCode"|"userId"|"deptCode";displayColumn: string;};// 유효성 검사
validation?: ValidationRule[];}
12.3 V2Select 전용 속성
interfaceV2SelectPropsextendsBaseV2Props{// 표시 모드
mode:"dropdown"|"radio"|"check"|"tag"|"toggle"|"swap";// 데이터 소스
source:"static"|"code"|"db"|"api"|"entity";// static 소스
options?: Array<{value: string;label: string}>;// db 소스
table?: string;valueColumn?: string;labelColumn?: string;// code 소스
codeGroup?: string;// 연쇄 관계 (cascading_relation 대체)
cascading?:{parentField: string;// 부모 필드명
filterColumn: string;// 필터링할 컬럼
clearOnChange?: boolean;// 부모 변경 시 초기화
};// 상호 배제 (mutual_exclusion 대체)
mutualExclusion?:{enabled: boolean;targetField: string;// 상호 배제 대상
type:"exclusive"|"inclusive";};// 다중 선택
multiple?: boolean;maxSelect?: number;}
12.4 관리 메뉴 정리 결과
AS-IS
TO-BE
연쇄 드롭다운 통합 관리 (6탭)
삭제
- 2단계 연쇄관계
→ V2Select.cascading 속성
- 다단계 계층
→ 테이블관리 > 계층 구조 설정
- 조건부 필터
→ 공통 conditional 속성
- 자동 입력
→ 공통 autoFill 속성
- 상호 배제
→ V2Select.mutualExclusion 속성
- 카테고리 값 연쇄
→ 카테고리 관리와 통합
13. 주의사항
기존 컴포넌트 삭제 금지
모든 Phase에서 기존 컴포넌트는 삭제하지 않고 병행 운영합니다.
레거시 정리는 Phase 5에서 충분한 안정화 후 별도 검토합니다.
연쇄관계 마이그레이션 필수
관리 메뉴 삭제 전 기존 cascading_relation 데이터(2건)를
해당 화면의 컴포넌트 속성으로 마이그레이션해야 합니다.
95bef976a5