ERP-node/플로우_위젯_컬럼_표시_설정_구현_완료.md

# 플로우 위젯 단계별 컬럼 표시 설정 기능 구현 완료

## 📋 개요

플로우 위젯에서 각 단계별로 표시할 컬럼을 선택할 수 있는 기능을 **하이브리드 방식**으로 구현하였습니다.

### 하이브리드 방식의 장점

1. **플로우 에디터**에서 각 스텝의 **기본 컬럼 설정** 정의
2. **화면관리**에서 특정 화면에만 **컬럼 오버라이드** 가능
3. **우선순위**: 화면 설정 > 플로우 기본 설정 > 전체 컬럼 표시

---

## 🎯 구현 내용

### Phase 1: 데이터베이스 스키마 확장 ✅

**파일**: `db/migrations/023_add_display_config_to_flow_step.sql`

- `flow_step` 테이블에 `display_config` 컬럼 추가 (JSONB 타입)
- 인덱스 추가 (GIN 인덱스로 JSONB 검색 최적화)

```sql
ALTER TABLE flow_step
ADD COLUMN IF NOT EXISTS display_config JSONB DEFAULT NULL;

CREATE INDEX IF NOT EXISTS idx_flow_step_display_config
ON flow_step USING gin(display_config);
```

**구조**:

```json
{
  "visibleColumns": ["column1", "column2", ...],
  "columnOrder": ["column1", "column2", ...],
  "columnLabels": {
    "column1": "커스텀 라벨 1"
  },
  "columnWidths": {
    "column1": 150
  }
}
```

---

### Phase 2: 백엔드 타입 정의 업데이트 ✅

**파일**: `backend-node/src/types/flow.ts`

**새로운 인터페이스**:

```typescript
export interface FlowStepDisplayConfig {
  visibleColumns?: string[];
  columnOrder?: string[];
  columnLabels?: Record<string, string>;
  columnWidths?: Record<string, number>;
}
```

**FlowStep 인터페이스 확장**:

```typescript
export interface FlowStep {
  // ... 기존 필드
  displayConfig?: FlowStepDisplayConfig; // 🆕
}
```

**CreateFlowStepRequest 및 UpdateFlowStepRequest에도 추가됨**

---

### Phase 3: 워크플로우 에디터 - 스텝 속성 패널 UI 추가 ✅

**파일**: `frontend/components/flow/FlowStepPanel.tsx`

#### 추가된 기능

1. **테이블 컬럼 목록 자동 로드**
   - 스텝의 테이블이 선택되면 해당 테이블의 컬럼 목록을 자동으로 가져옴
2. **"표시 설정" 카드 추가**
   - 전체 선택/해제 체크박스
   - 개별 컬럼 선택 체크박스
   - 선택된 컬럼 개수 표시

```typescript
// formData에 displayConfig 추가
const [formData, setFormData] = useState({
  // ... 기존 필드
  displayConfig: step.displayConfig || { visibleColumns: [] }, // 🆕
});
```

#### UI 구조

```
┌─ 표시 설정 카드 ─────────────────────┐
│ 표시할 컬럼 선택                      │
│ ┌────────────────────────────┐       │
│ │ ☐ 전체 선택/해제            │       │
│ ├────────────────────────────┤       │
│ │ ☑ id                        │       │
│ │ ☑ name                      │       │
│ │ ☐ description               │       │
│ │ ☑ created_at                │       │
│ └────────────────────────────┘       │
│                                       │
│ 💡 선택된 컬럼: 3개                  │
└───────────────────────────────────────┘
```

---

### Phase 4: 플로우 위젯 - 컬럼 표시 로직 업데이트 ✅

**파일**: `frontend/components/screen/widgets/FlowWidget.tsx`

#### 핵심 로직: getVisibleColumns 함수

```typescript
/**
 * 컬럼 표시 우선순위 결정 함수 (하이브리드 방식)
 * 1순위: 화면 위젯 설정 (stepColumnConfig)
 * 2순위: 플로우 스텝 기본 설정 (displayConfig)
 * 3순위: 모든 컬럼 표시
 */
const getVisibleColumns = (stepId: number, allColumns: string[]): string[] => {
  // 1순위: 화면 위젯 설정
  const widgetConfig = component.stepColumnConfig;
  if (widgetConfig && widgetConfig[stepId]) {
    const config = widgetConfig[stepId];
    if (config.selectedColumns && config.selectedColumns.length > 0) {
      return config.selectedColumns;
    }
  }

  // 2순위: 플로우 스텝 기본 설정
  const currentStep = steps.find((s) => s.id === stepId);
  if (
    currentStep?.displayConfig?.visibleColumns &&
    currentStep.displayConfig.visibleColumns.length > 0
  ) {
    return currentStep.displayConfig.visibleColumns;
  }

  // 3순위: 모든 컬럼 표시
  return allColumns;
};
```

#### 적용된 위치

1. 스텝 클릭 시 데이터 로드 (`handleStepClick`)
2. 플로우 새로고침 시 (`refreshStepData`)

---

### Phase 5: 화면관리 - 플로우 위젯 설정 패널 UI 추가 ✅

**파일**: `frontend/components/screen/config-panels/FlowWidgetConfigPanel.tsx`

#### 추가된 기능

1. **스텝 목록 자동 로드**

   - 플로우가 선택되면 해당 플로우의 스텝 목록을 자동으로 가져옴

2. **테이블 컬럼 목록 자동 로드**

   - 플로우의 테이블 컬럼 목록을 자동으로 가져옴

3. **"스텝별 컬럼 설정 (고급)" 섹션 추가**
   - 토글 버튼으로 표시/숨김 가능
   - 각 스텝별로 컬럼 선택 가능
   - 커스텀 설정이 있으면 "초기화" 버튼 표시

#### UI 구조

```
┌─ 스텝별 컬럼 설정 (고급) ──────── [설정▼] ─┐
│                                               │
│ ┌─ 스텝 1: 주문 접수 ─────────── [초기화] ─┐ │
│ │ 커스텀 설정 (3개 컬럼)                   │ │
│ │ ┌──────────────────────────┐            │ │
│ │ │ ☑ id                      │            │ │
│ │ │ ☑ customer_name           │            │ │
│ │ │ ☐ order_date              │            │ │
│ │ │ ☑ amount                  │            │ │
│ │ └──────────────────────────┘            │ │
│ └─────────────────────────────────────────┘ │
│                                               │
│ ┌─ 스텝 2: 승인 대기 ──────────────────────┐ │
│ │ 기본 설정 사용                            │ │
│ │ (플로우 정의에서 설정된 컬럼 표시)        │ │
│ └─────────────────────────────────────────┘ │
└───────────────────────────────────────────────┘
```

---

### Phase 6: 프론트엔드 타입 정의 업데이트 ✅

**파일 1**: `frontend/types/flow.ts`

```typescript
export interface FlowStepDisplayConfig {
  visibleColumns?: string[];
  columnOrder?: string[];
  columnLabels?: Record<string, string>;
  columnWidths?: Record<string, number>;
}

export interface FlowStep {
  // ... 기존 필드
  displayConfig?: FlowStepDisplayConfig; // 🆕
}
```

**파일 2**: `frontend/types/screen-management.ts`

```typescript
export interface FlowStepColumnConfig {
  selectedColumns: string[];
  columnOrder?: string[];
}

export interface FlowComponent extends BaseComponent {
  type: "flow";
  // ... 기존 필드
  stepColumnConfig?: {
    [stepId: number]: FlowStepColumnConfig; // 🆕
  };
}
```

---

## 🔄 사용 시나리오

### 시나리오 1: 플로우 기본 설정 사용 (일반적인 경우)

1. 플로우 관리 페이지에서 플로우 스텝 편집
2. "표시 설정" 카드에서 표시할 컬럼 선택 (예: id, name, created_at)
3. 저장
4. **모든 화면**에서 이 플로우를 사용할 때 선택한 컬럼만 표시됨

### 시나리오 2: 화면별 컬럼 오버라이드 (특수한 경우)

1. 화면 설계자 모드에서 플로우 위젯 선택
2. 속성 패널 > "스텝별 컬럼 설정 (고급)" 클릭
3. 특정 스텝의 컬럼을 다르게 선택 (예: id, amount만 표시)
4. 저장
5. **이 화면에서만** 오버라이드된 컬럼이 표시됨

### 시나리오 3: 아무 설정도 하지 않은 경우

- 모든 컬럼이 자동으로 표시됨 (기본 동작)

---

## 📊 우선순위 다이어그램

```
데이터 로드
    ↓
┌────────────────────────────────────────┐
│ 1. 화면 위젯 설정 확인                 │
│    (stepColumnConfig[stepId])         │
└────────────────────────────────────────┘
    ↓ 없음
┌────────────────────────────────────────┐
│ 2. 플로우 스텝 기본 설정 확인          │
│    (step.displayConfig.visibleColumns)│
└────────────────────────────────────────┘
    ↓ 없음
┌────────────────────────────────────────┐
│ 3. 모든 컬럼 표시                      │
│    (Object.keys(data[0]))             │
└────────────────────────────────────────┘
    ↓
테이블 렌더링
```

---

## 🎨 UI/UX 특징

### 1. 점진적 공개 (Progressive Disclosure)

- 기본적으로는 간단한 UI만 표시
- "스텝별 컬럼 설정 (고급)"은 토글로 숨김/표시

### 2. 명확한 피드백

- 선택된 컬럼 개수 표시
- "커스텀 설정" vs "기본 설정 사용" 명확히 표시
- 초기화 버튼으로 쉽게 되돌리기 가능

### 3. 검색 가능한 체크박스 리스트

- 컬럼이 많을 경우 스크롤 가능
- font-mono로 컬럼명 명확히 표시

---

## 🧪 테스트 체크리스트

### 기능 테스트

- [ ] 데이터베이스 마이그레이션 실행 (`023_add_display_config_to_flow_step.sql`)
- [ ] 플로우 관리 페이지에서 스텝 속성 패널 열기
- [ ] "표시 설정" 카드에서 컬럼 선택 및 저장
- [ ] 플로우 위젯에서 선택한 컬럼만 표시되는지 확인
- [ ] 화면관리에서 특정 스텝의 컬럼 오버라이드 설정
- [ ] 오버라이드가 우선 적용되는지 확인
- [ ] 오버라이드 초기화 버튼 동작 확인

### 우선순위 테스트

1. **모든 설정 없음**: 전체 컬럼 표시 ✓
2. **플로우 기본 설정만**: 선택한 컬럼만 표시 ✓
3. **화면 오버라이드 설정**: 오버라이드된 컬럼만 표시 (최우선) ✓

### 엣지 케이스

- [ ] 컬럼이 없는 테이블 선택 시
- [ ] 모든 컬럼 선택 해제 시 (빈 배열) → 전체 표시
- [ ] 존재하지 않는 컬럼명 선택 시 (무시)
- [ ] 플로우 삭제 후 화면에서 참조하는 경우

---

## 📝 주의사항

### 1. 데이터베이스 마이그레이션

- 운영 환경에 배포하기 전에 반드시 마이그레이션 실행 필요
- 기존 데이터에는 영향 없음 (NULL 허용)

### 2. 하위 호환성

- `displayConfig`가 없으면 자동으로 전체 컬럼 표시 (기존 동작 유지)
- `stepColumnConfig`가 없으면 플로우 기본 설정 사용

### 3. 성능

- 컬럼 목록 로드는 테이블 선택 시 1회만 실행
- GIN 인덱스로 JSONB 검색 최적화

---

## 🚀 향후 개선 방안 (선택사항)

### 1. 컬럼 순서 변경 기능

- Drag & Drop으로 컬럼 순서 변경
- `columnOrder` 필드 활용

### 2. 컬럼별 커스텀 라벨

- 표시명을 사용자가 직접 지정
- `columnLabels` 필드 활용

### 3. 컬럼 너비 설정

- 각 컬럼의 표시 너비 조정
- `columnWidths` 필드 활용

### 4. 빠른 프리셋

- "기본 정보만", "전체 정보", "요약 정보" 등 프리셋 제공

---

## 📚 관련 파일 목록

### 데이터베이스

- `db/migrations/023_add_display_config_to_flow_step.sql`

### 백엔드

- `backend-node/src/types/flow.ts`

### 프론트엔드 (타입)

- `frontend/types/flow.ts`
- `frontend/types/screen-management.ts`

### 프론트엔드 (컴포넌트)

- `frontend/components/screen/widgets/FlowWidget.tsx`
- `frontend/components/flow/FlowStepPanel.tsx`
- `frontend/components/screen/config-panels/FlowWidgetConfigPanel.tsx`

---

## ✅ 구현 완료

모든 Phase가 성공적으로 완료되었습니다!

**구현 날짜**: 2025-10-24

**구현 방식**: 하이브리드 (플로우 에디터 기본 설정 + 화면관리 오버라이드)

**적용 범위**:

- 플로우 관리 시스템 (플로우 정의 편집)
- 화면관리 시스템 (플로우 위젯 설정)
- 실제 화면 표시 (플로우 위젯 렌더링)