vexplor/화면_임베딩_시스템_Phase1-4_구현_완료.md

화면 임베딩 및 데이터 전달 시스템 구현 완료 보고서

📋 개요

입고 등록과 같은 복잡한 워크플로우를 지원하기 위해 화면 임베딩 및 데이터 전달 시스템을 구현했습니다.

• 구현 기간: 2025-11-27
• 구현 범위: Phase 1-4 (기본 인프라 ~ 핵심 컴포넌트)
• 상태: ✅ 핵심 기능 구현 완료

---

✅ 구현 완료 항목

Phase 1: 기본 인프라 (100% 완료)

1.1 데이터베이스 스키마

파일: db/migrations/040_create_screen_embedding_tables.sql

생성된 테이블:

1. screen_embedding (화면 임베딩 설정)

   • 한 화면을 다른 화면 안에 임베드
   • 위치 (left, right, top, bottom, center)
   • 모드 (view, select, form, edit)
   • 설정 (width, height, multiSelect 등)

2. screen_data_transfer (데이터 전달 설정)

   • 소스 화면 → 타겟 화면 데이터 전달
   • 데이터 수신자 배열 (JSONB)
   • 매핑 규칙, 조건, 검증
   • 전달 버튼 설정

3. screen_split_panel (분할 패널 통합)

   • 좌측/우측 임베딩 참조
   • 데이터 전달 설정 참조
   • 레이아웃 설정 (splitRatio, resizable 등)

샘플 데이터:

• 입고 등록 시나리오 샘플 데이터 포함
• 발주 목록 → 입고 처리 품목 매핑 예시

1.2 TypeScript 타입 정의

파일: frontend/types/screen-embedding.ts

주요 타입:

// 화면 임베딩
- EmbeddingMode: "view" | "select" | "form" | "edit"
- EmbeddingPosition: "left" | "right" | "top" | "bottom" | "center"
- ScreenEmbedding

// 데이터 전달
- ComponentType: "table" | "input" | "select" | "textarea" | ...
- DataReceiveMode: "append" | "replace" | "merge"
- TransformFunction: "sum" | "average" | "count" | "first" | ...
- MappingRule, DataReceiver, ScreenDataTransfer

// 분할 패널
- LayoutConfig, ScreenSplitPanel

// 컴포넌트 인터페이스
- DataReceivable, Selectable, EmbeddedScreenHandle

1.3 백엔드 API

파일:

• backend-node/src/controllers/screenEmbeddingController.ts
• backend-node/src/routes/screenEmbeddingRoutes.ts

API 엔드포인트:

화면 임베딩:

• GET /api/screen-embedding?parentScreenId=1 - 목록 조회
• GET /api/screen-embedding/:id - 상세 조회
• POST /api/screen-embedding - 생성
• PUT /api/screen-embedding/:id - 수정
• DELETE /api/screen-embedding/:id - 삭제

데이터 전달:

• GET /api/screen-data-transfer?sourceScreenId=1&targetScreenId=2 - 조회
• POST /api/screen-data-transfer - 생성
• PUT /api/screen-data-transfer/:id - 수정
• DELETE /api/screen-data-transfer/:id - 삭제

분할 패널:

• GET /api/screen-split-panel/:screenId - 조회
• POST /api/screen-split-panel - 생성 (트랜잭션)
• PUT /api/screen-split-panel/:id - 수정
• DELETE /api/screen-split-panel/:id - 삭제 (CASCADE)

특징:

• ✅ 멀티테넌시 지원 (company_code 필터링)
• ✅ 트랜잭션 처리 (분할 패널 생성/삭제)
• ✅ 외래키 CASCADE 처리
• ✅ 에러 핸들링 및 로깅

1.4 프론트엔드 API 클라이언트

파일: frontend/lib/api/screenEmbedding.ts

함수:

// 화면 임베딩
-getScreenEmbeddings(parentScreenId) -
  getScreenEmbeddingById(id) -
  createScreenEmbedding(data) -
  updateScreenEmbedding(id, data) -
  deleteScreenEmbedding(id) -
  // 데이터 전달
  getScreenDataTransfer(sourceScreenId, targetScreenId) -
  createScreenDataTransfer(data) -
  updateScreenDataTransfer(id, data) -
  deleteScreenDataTransfer(id) -
  // 분할 패널
  getScreenSplitPanel(screenId) -
  createScreenSplitPanel(data) -
  updateScreenSplitPanel(id, layoutConfig) -
  deleteScreenSplitPanel(id);

---

Phase 2: 화면 임베딩 기능 (100% 완료)

2.1 EmbeddedScreen 컴포넌트

파일: frontend/components/screen-embedding/EmbeddedScreen.tsx

주요 기능:

• ✅ 화면 데이터 로드
• ✅ 모드별 렌더링 (view, select, form, edit)
• ✅ 선택 모드 지원 (체크박스)
• ✅ 컴포넌트 등록/해제 시스템
• ✅ 데이터 수신 처리
• ✅ 로딩/에러 상태 UI

외부 인터페이스 (useImperativeHandle):

- getSelectedRows(): any[]
- clearSelection(): void
- receiveData(data, receivers): Promise<void>
- getData(): any

데이터 수신 프로세스:

1. 조건 필터링 (condition)
2. 매핑 규칙 적용 (mappingRules)
3. 검증 (validation)
4. 컴포넌트에 데이터 전달

---

Phase 3: 데이터 전달 시스템 (100% 완료)

3.1 매핑 엔진

파일: frontend/lib/utils/dataMapping.ts

주요 함수:

1. applyMappingRules(data, rules)

   • 일반 매핑: 각 행에 대해 필드 매핑
   • 변환 매핑: 집계 함수 적용

2. 변환 함수 지원:

   • sum: 합계
   • average: 평균
   • count: 개수
   • min, max: 최소/최대
   • first, last: 첫/마지막 값
   • concat, join: 문자열 결합

3. filterDataByCondition(data, condition)

   • 조건 연산자: equals, notEquals, contains, greaterThan, lessThan, in, notIn

4. validateMappingResult(data, rules)

   • 필수 필드 검증

5. previewMapping(sampleData, rules)

   • 매핑 결과 미리보기

특징:

• ✅ 중첩 객체 지원 (user.address.city)
• ✅ 타입 안전성
• ✅ 에러 처리

3.2 로거 유틸리티

파일: frontend/lib/utils/logger.ts

기능:

• debug, info, warn, error 레벨
• 개발 환경에서만 debug 출력
• 타임스탬프 포함

---

Phase 4: 분할 패널 UI (100% 완료)

4.1 ScreenSplitPanel 컴포넌트

파일: frontend/components/screen-embedding/ScreenSplitPanel.tsx

주요 기능:

• ✅ 좌우 화면 임베딩
• ✅ 리사이저 (드래그로 비율 조정)
• ✅ 데이터 전달 버튼
• ✅ 선택 카운트 표시
• ✅ 로딩 상태 표시
• ✅ 검증 (최소/최대 선택 수)
• ✅ 확인 메시지
• ✅ 전달 후 선택 초기화 (옵션)

UI 구조:

┌─────────────────────────────────────────────────────────┐
│  [좌측 패널 50%]  │  [버튼]  │  [우측 패널 50%]        │
│                   │          │                          │
│  EmbeddedScreen   │  [→]     │  EmbeddedScreen         │
│  (select 모드)    │          │  (form 모드)            │
│                   │          │                          │
│  선택됨: 3개      │          │                          │
└─────────────────────────────────────────────────────────┘

이벤트 흐름:

1. 좌측에서 행 선택 → 선택 카운트 업데이트
2. 전달 버튼 클릭 → 검증
3. 우측 화면의 컴포넌트들에 데이터 전달
4. 성공 토스트 표시

---

📁 파일 구조

ERP-node/
├── db/
│   └── migrations/
│       └── 040_create_screen_embedding_tables.sql  ✅ 마이그레이션
│
├── backend-node/
│   └── src/
│       ├── controllers/
│       │   └── screenEmbeddingController.ts        ✅ 컨트롤러
│       └── routes/
│           └── screenEmbeddingRoutes.ts            ✅ 라우트
│
└── frontend/
    ├── types/
    │   └── screen-embedding.ts                     ✅ 타입 정의
    │
    ├── lib/
    │   ├── api/
    │   │   └── screenEmbedding.ts                  ✅ API 클라이언트
    │   └── utils/
    │       ├── dataMapping.ts                      ✅ 매핑 엔진
    │       └── logger.ts                           ✅ 로거
    │
    └── components/
        └── screen-embedding/
            ├── EmbeddedScreen.tsx                  ✅ 임베드 화면
            ├── ScreenSplitPanel.tsx                ✅ 분할 패널
            └── index.ts                            ✅ Export

---

🎯 사용 예시

1. 입고 등록 시나리오

// 분할 패널 설정
const inboundConfig: ScreenSplitPanel = {
  screenId: 100,
  leftEmbedding: {
    childScreenId: 10, // 발주 목록 조회
    position: "left",
    mode: "select",
    config: {
      width: "50%",
      multiSelect: true,
    },
  },
  rightEmbedding: {
    childScreenId: 20, // 입고 등록 폼
    position: "right",
    mode: "form",
    config: {
      width: "50%",
    },
  },
  dataTransfer: {
    sourceScreenId: 10,
    targetScreenId: 20,
    dataReceivers: [
      {
        targetComponentId: "table-입고처리품목",
        targetComponentType: "table",
        mode: "append",
        mappingRules: [
          { sourceField: "품목코드", targetField: "품목코드" },
          { sourceField: "품목명", targetField: "품목명" },
          { sourceField: "미입고수량", targetField: "입고수량" },
        ],
      },
      {
        targetComponentId: "input-공급자",
        targetComponentType: "input",
        mode: "replace",
        mappingRules: [
          { sourceField: "공급자", targetField: "value", transform: "first" },
        ],
      },
      {
        targetComponentId: "input-품목수",
        targetComponentType: "input",
        mode: "replace",
        mappingRules: [
          { sourceField: "품목코드", targetField: "value", transform: "count" },
        ],
      },
    ],
    buttonConfig: {
      label: "선택 품목 추가",
      position: "center",
      icon: "ArrowRight",
      validation: {
        requireSelection: true,
        minSelection: 1,
        confirmMessage: "선택한 품목을 추가하시겠습니까?",
      },
    },
  },
  layoutConfig: {
    splitRatio: 50,
    resizable: true,
    orientation: "horizontal",
  },
};

// 컴포넌트 사용
<ScreenSplitPanel
  config={inboundConfig}
  onDataTransferred={(data) => {
    console.log("전달된 데이터:", data);
  }}
/>;

---

🔄 데이터 흐름

1. 좌측 화면 (발주 목록)
   ↓
   사용자가 품목 선택 (체크박스)
   ↓
2. [선택 품목 추가] 버튼 클릭
   ↓
3. 검증
   - 선택 항목 있는지?
   - 최소/최대 개수 충족?
   - 확인 메시지 동의?
   ↓
4. 데이터 전달 처리
   ├─ 조건 필터링 (condition)
   ├─ 매핑 규칙 적용 (mappingRules)
   │  ├─ 일반 매핑: 품목코드 → 품목코드
   │  └─ 변환 매핑: 품목코드 → count → 품목수
   └─ 검증 (validation)
   ↓
5. 우측 화면의 컴포넌트들에 데이터 주입
   ├─ table-입고처리품목: 행 추가 (append)
   ├─ input-공급자: 값 설정 (replace, first)
   └─ input-품목수: 개수 설정 (replace, count)
   ↓
6. 성공 토스트 표시
   ↓
7. 좌측 선택 초기화 (옵션)

---

🚀 다음 단계 (Phase 5-6)

Phase 5: 고급 기능 (예정)

1. DataReceivable 인터페이스 구현

   • TableComponent
   • InputComponent
   • SelectComponent
   • RepeaterComponent
   • 기타 컴포넌트들

2. 양방향 동기화

   • 우측 → 좌측 데이터 반영
   • 실시간 업데이트

3. 트랜잭션 지원

   • 전체 성공 또는 전체 실패
   • 롤백 기능

Phase 6: 설정 UI (예정)

1. 시각적 매핑 설정 UI

   • 드래그앤드롭으로 필드 매핑
   • 변환 함수 선택
   • 조건 설정

2. 미리보기 기능

   • 데이터 전달 결과 미리보기
   • 매핑 규칙 테스트

---

📝 사용 가이드

1. 마이그레이션 실행

# PostgreSQL에서 실행
psql -U postgres -d your_database -f db/migrations/040_create_screen_embedding_tables.sql

2. 백엔드 서버 재시작

라우트가 자동으로 등록되어 있으므로 재시작만 하면 됩니다.

3. 분할 패널 화면 생성

1. 화면 관리에서 새 화면 생성
2. 화면 타입: "분할 패널"
3. API를 통해 설정 저장:

import { createScreenSplitPanel } from "@/lib/api/screenEmbedding";

const result = await createScreenSplitPanel({
  screenId: 100,
  leftEmbedding: { ... },
  rightEmbedding: { ... },
  dataTransfer: { ... },
  layoutConfig: { ... },
});

4. 화면에서 사용

import { ScreenSplitPanel } from "@/components/screen-embedding";
import { getScreenSplitPanel } from "@/lib/api/screenEmbedding";

// 설정 로드
const { data: config } = await getScreenSplitPanel(screenId);

// 렌더링
<ScreenSplitPanel config={config} />;

---

✅ 체크리스트

구현 완료

• 데이터베이스 스키마 (3개 테이블)
• TypeScript 타입 정의
• 백엔드 API (15개 엔드포인트)
• 프론트엔드 API 클라이언트
• EmbeddedScreen 컴포넌트
• 매핑 엔진 (9개 변환 함수)
• ScreenSplitPanel 컴포넌트
• 로거 유틸리티

다음 단계

• DataReceivable 구현 (각 컴포넌트 타입별)
• 설정 UI (드래그앤드롭 매핑)
• 미리보기 기능
• 양방향 동기화
• 트랜잭션 지원
• 테스트 및 문서화

---

🎉 결론

화면 임베딩 및 데이터 전달 시스템의 핵심 기능이 완성되었습니다!

• ✅ 데이터베이스 스키마 완성
• ✅ 백엔드 API 완성
• ✅ 프론트엔드 컴포넌트 완성
• ✅ 매핑 엔진 완성

이제 입고 등록과 같은 복잡한 워크플로우를 구현할 수 있습니다. 다음 단계는 각 컴포넌트 타입별 DataReceivable 인터페이스 구현과 설정 UI 개발입니다.