ERP-node/frontend/lib/registry/components/repeat-screen-modal/README.md

# RepeatScreenModal 컴포넌트 v3

## 개요

`RepeatScreenModal`은 선택한 데이터를 기반으로 여러 개의 카드를 생성하고, 각 카드의 내부 레이아웃을 자유롭게 구성할 수 있는 컴포넌트입니다.

## v3 주요 변경사항

### 자유 레이아웃 시스템

기존의 "simple 모드 / withTable 모드" 구분을 없애고, **행(Row)을 추가하고 각 행마다 타입을 선택**하는 방식으로 변경되었습니다.

```
┌─────────────────────────────────────────────────────────────────┐
│ 카드                                                            │
├─────────────────────────────────────────────────────────────────┤
│ [행 1] 타입: 헤더   → 품목코드, 품목명, 규격                     │
├─────────────────────────────────────────────────────────────────┤
│ [행 2] 타입: 집계   → 총수주잔량, 현재고, 가용재고               │
├─────────────────────────────────────────────────────────────────┤
│ [행 3] 타입: 테이블 → 수주번호, 거래처, 납기일, 출하계획         │
├─────────────────────────────────────────────────────────────────┤
│ [행 4] 타입: 테이블 → 또 다른 테이블도 가능!                     │
└─────────────────────────────────────────────────────────────────┘
```

### 행 타입

| 타입 | 설명 | 사용 시나리오 |
|------|------|---------------|
| **헤더 (header)** | 필드들을 가로/세로로 나열 | 품목정보, 거래처정보 표시 |
| **필드 (fields)** | 헤더와 동일, 편집 가능 | 폼 입력 영역 |
| **집계 (aggregation)** | 그룹 내 데이터 집계값 표시 | 총수량, 합계금액 등 |
| **테이블 (table)** | 그룹 내 각 행을 테이블로 표시 | 수주목록, 품목목록 등 |

### 자유로운 조합

```
예시 1: 헤더 + 집계 + 테이블 (출하계획)
├── [행 1] 헤더: 품목코드, 품목명
├── [행 2] 집계: 총수주잔량, 현재고
└── [행 3] 테이블: 수주별 출하계획

예시 2: 집계만
└── [행 1] 집계: 총매출, 총비용, 순이익

예시 3: 테이블만
└── [행 1] 테이블: 품목 목록

예시 4: 테이블 2개
├── [행 1] 테이블: 입고 내역
└── [행 2] 테이블: 출고 내역

예시 5: 헤더 + 헤더 + 필드
├── [행 1] 헤더: 기본 정보 (읽기전용)
├── [행 2] 헤더: 상세 정보 (읽기전용)
└── [행 3] 필드: 입력 필드 (편집가능)
```

## 설정 방법

### 1. 기본 설정 탭

- **카드 제목 표시**: 카드 상단에 제목을 표시할지 여부
- **카드 제목 템플릿**: `{field_name}` 형식으로 동적 제목 생성
- **카드 간격**: 카드 사이의 간격 (8px ~ 32px)
- **테두리**: 카드 테두리 표시 여부
- **저장 모드**: 전체 저장 / 개별 저장

### 2. 데이터 소스 탭

- **소스 테이블**: 데이터를 조회할 테이블
- **필터 필드**: formData에서 필터링할 필드 (예: selectedIds)

### 3. 그룹 탭

- **그룹핑 활성화**: 여러 행을 하나의 카드로 묶을지 여부
- **그룹 기준 필드**: 그룹핑할 필드 (예: part_code)
- **집계 설정**: 
  - 원본 필드: 합계할 필드 (예: balance_qty)
  - 집계 타입: sum, count, avg, min, max
  - 결과 필드명: 집계 결과를 저장할 필드명
  - 라벨: 표시될 라벨

### 4. 레이아웃 탭

#### 행 추가

4가지 타입의 행을 추가할 수 있습니다:
- **헤더**: 필드 정보 표시 (읽기전용)
- **집계**: 그룹 집계값 표시
- **테이블**: 그룹 내 행들을 테이블로 표시
- **필드**: 입력 필드 (편집가능)

#### 헤더/필드 행 설정

- **방향**: 가로 / 세로
- **배경색**: 없음, 파랑, 초록, 보라, 주황
- **컬럼**: 필드명, 라벨, 타입, 너비, 편집 가능, 필수
- **소스 설정**: 직접 / 조인 / 수동
- **저장 설정**: 저장할 테이블과 컬럼

#### 집계 행 설정

- **레이아웃**: 가로 나열 / 그리드
- **그리드 컬럼 수**: 2, 3, 4개
- **집계 필드**: 그룹 탭에서 정의한 집계 결과 선택
- **스타일**: 배경색, 폰트 크기

#### 테이블 행 설정

- **테이블 제목**: 선택사항
- **헤더 표시**: 테이블 헤더 표시 여부
- **테이블 컬럼**: 필드명, 라벨, 타입, 너비, 편집 가능
- **저장 설정**: 편집 가능한 컬럼의 저장 위치

## 데이터 흐름

```
1. formData에서 selectedIds 가져오기
   ↓
2. 소스 테이블에서 해당 ID들의 데이터 조회
   ↓
3. 그룹핑 활성화 시 groupByField 기준으로 그룹화
   ↓
4. 각 그룹에 대해 집계값 계산
   ↓
5. 카드 렌더링 (contentRows 기반)
   ↓
6. 사용자 편집
   ↓
7. 저장 시 targetConfig에 따라 테이블별로 데이터 분류 후 저장
```

## 사용 예시

### 출하계획 등록

```typescript
{
  showCardTitle: true,
  cardTitle: "{part_code} - {part_name}",
  dataSource: {
    sourceTable: "sales_order_mng",
    filterField: "selectedIds"
  },
  grouping: {
    enabled: true,
    groupByField: "part_code",
    aggregations: [
      { sourceField: "balance_qty", type: "sum", resultField: "total_balance", label: "총수주잔량" },
      { sourceField: "id", type: "count", resultField: "order_count", label: "수주건수" }
    ]
  },
  contentRows: [
    {
      id: "row-1",
      type: "header",
      columns: [
        { id: "c1", field: "part_code", label: "품목코드", type: "text", editable: false },
        { id: "c2", field: "part_name", label: "품목명", type: "text", editable: false }
      ],
      layout: "horizontal"
    },
    {
      id: "row-2",
      type: "aggregation",
      aggregationLayout: "horizontal",
      aggregationFields: [
        { aggregationResultField: "total_balance", label: "총수주잔량", backgroundColor: "blue" },
        { aggregationResultField: "order_count", label: "수주건수", backgroundColor: "green" }
      ]
    },
    {
      id: "row-3",
      type: "table",
      tableTitle: "수주 목록",
      showTableHeader: true,
      tableColumns: [
        { id: "tc1", field: "order_no", label: "수주번호", type: "text", editable: false },
        { id: "tc2", field: "partner_name", label: "거래처", type: "text", editable: false },
        { id: "tc3", field: "balance_qty", label: "미출하", type: "number", editable: false },
        { 
          id: "tc4", 
          field: "plan_qty", 
          label: "출하계획", 
          type: "number", 
          editable: true,
          targetConfig: { targetTable: "shipment_plan", targetColumn: "plan_qty", saveEnabled: true }
        }
      ]
    }
  ]
}
```

## 레거시 호환

v2에서 사용하던 `cardMode`, `cardLayout`, `tableLayout` 설정도 계속 지원됩니다.
새로운 프로젝트에서는 `contentRows`를 사용하는 것을 권장합니다.

## 주의사항

1. **집계는 그룹핑 필수**: 집계 행은 그룹핑이 활성화되어 있어야 의미가 있습니다.
2. **테이블은 그룹핑 필수**: 테이블 행도 그룹핑이 활성화되어 있어야 그룹 내 행들을 표시할 수 있습니다.
3. **단순 모드**: 그룹핑 없이 사용하면 1행 = 1카드로 동작합니다. 이 경우 헤더/필드 타입만 사용 가능합니다.