# 리스트 위젯 개발 계획서

## 📋 개요

차트와 동일한 방식으로 데이터를 가져오는 리스트(테이블) 위젯 개발

---

## 🎯 주요 기능

### 1. 데이터 소스 (차트와 동일)

- **내부 DB**: 현재 데이터베이스 쿼리
- **외부 DB**: 외부 커넥션 관리에서 설정된 DB 쿼리
- **REST API**: 외부 API 호출 (GET 방식)

### 2. 컬럼 설정

사용자가 두 가지 방식으로 컬럼을 설정할 수 있음:

#### 방식 1: 데이터 기반 자동 생성

1. 쿼리/API 실행 → 데이터 가져옴
2. 사용자가 표시할 컬럼 선택
3. 컬럼명을 원하는대로 변경 가능
4. 컬럼 순서 조정 가능

```
예시:
데이터: { userId: 1, userName: "홍길동", deptCode: "DPT001" }
↓
사용자 설정:
- userId → "사용자 ID"
- userName → "이름"
- deptCode → "부서 코드"
```

#### 방식 2: 수동 컬럼 정의

1. 사용자가 직접 컬럼 추가
2. 각 컬럼의 이름 지정
3. 각 컬럼에 들어갈 데이터 필드 매핑

```
예시:
컬럼 1: "직원 정보" → userName 필드
컬럼 2: "소속" → deptCode 필드
컬럼 3: "등록일" → regDate 필드
```

### 3. 테이블 기능

- **페이지네이션**: 한 페이지당 표시 개수 설정 (10, 20, 50, 100)
- **정렬**: 컬럼 클릭 시 오름차순/내림차순 정렬
- **검색**: 전체 컬럼에서 키워드 검색
- **자동 새로고침**: 설정된 시간마다 자동으로 데이터 갱신

---

## 🏗️ 구조 설계

### 파일 구조

```
frontend/components/admin/dashboard/widgets/
├── ListWidget.tsx              # 메인 위젯 컴포넌트
├── ListWidgetConfigModal.tsx   # 설정 모달
└── list-widget/
    ├── ColumnSelector.tsx      # 컬럼 선택 UI
    ├── ManualColumnEditor.tsx  # 수동 컬럼 편집 UI
    └── ListTable.tsx           # 실제 테이블 렌더링
```

### 데이터 타입 (`types.ts`에 추가)

```typescript
// 리스트 위젯 설정
export interface ListWidgetConfig {
  // 컬럼 설정 방식
  columnMode: "auto" | "manual"; // 자동 or 수동

  // 컬럼 정의
  columns: ListColumn[];

  // 테이블 옵션
  pageSize: number; // 페이지당 행 수 (기본: 10)
  enableSearch: boolean; // 검색 활성화 (기본: true)
  enableSort: boolean; // 정렬 활성화 (기본: true)
  enablePagination: boolean; // 페이지네이션 활성화 (기본: true)

  // 스타일
  showHeader: boolean; // 헤더 표시 (기본: true)
  stripedRows: boolean; // 줄무늬 행 (기본: true)
  compactMode: boolean; // 압축 모드 (기본: false)
}

// 리스트 컬럼
export interface ListColumn {
  id: string; // 고유 ID
  label: string; // 표시될 컬럼명
  field: string; // 데이터 필드명
  width?: number; // 너비 (px)
  align?: "left" | "center" | "right"; // 정렬
  sortable?: boolean; // 정렬 가능 여부
  visible?: boolean; // 표시 여부
}
```

---

## 📝 개발 단계

### Phase 1: 기본 구조 ✅ (예정)

- [ ] `ListWidget.tsx` 기본 컴포넌트 생성
- [ ] `types.ts`에 타입 정의 추가
- [ ] `DashboardSidebar.tsx`에 리스트 위젯 추가

### Phase 2: 데이터 소스 연동 ✅ (예정)

- [ ] 차트의 데이터 소스 로직 재사용
- [ ] `ListWidgetConfigModal.tsx` 생성
  - Step 1: 데이터 소스 선택 (DB/API)
  - Step 2: 쿼리/API 설정 및 실행
  - Step 3: 컬럼 설정

### Phase 3: 컬럼 설정 UI ✅ (예정)

- [ ] `ColumnSelector.tsx`: 데이터 기반 자동 생성
  - 컬럼 선택 (체크박스)
  - 컬럼명 변경 (인라인 편집)
  - 순서 조정 (드래그 앤 드롭)
- [ ] `ManualColumnEditor.tsx`: 수동 컬럼 정의
  - 컬럼 추가/삭제
  - 컬럼명 입력
  - 데이터 필드 매핑

### Phase 4: 테이블 렌더링 ✅ (예정)

- [ ] `ListTable.tsx` 구현
  - 기본 테이블 렌더링
  - 페이지네이션
  - 정렬 기능
  - 검색 기능
  - 반응형 디자인

### Phase 5: 자동 새로고침 ✅ (예정)

- [ ] 자동 새로고침 로직 구현 (차트와 동일)
- [ ] 수동 새로고침 버튼 추가

---

## 🎨 UI/UX 설계

### 위젯 크기별 표시

- **작은 크기 (2x2)**: 컬럼 3개까지만 표시, 페이지네이션 간략화
- **중간 크기 (3x3)**: 전체 기능 표시
- **큰 크기 (4x4+)**: 더 많은 행 표시

### 설정 모달 플로우

```
Step 1: 데이터 소스 선택
├─ 데이터베이스
│  ├─ 현재 DB
│  └─ 외부 DB (커넥션 선택)
└─ REST API

↓

Step 2: 데이터 가져오기
├─ SQL 쿼리 작성 (DB인 경우)
├─ API URL 설정 (API인 경우)
└─ [실행] 버튼 클릭 → 데이터 미리보기

↓

Step 3: 컬럼 설정
├─ 방식 선택: [자동 생성] / [수동 편집]
├─ 컬럼 선택 및 설정
├─ 테이블 옵션 설정
└─ [저장] 버튼
```

---

## 💡 참고 사항

### 차트와의 차이점

- **차트**: X축/Y축 매핑, 집계 함수, 그룹핑
- **리스트**: 컬럼 선택, 정렬, 검색, 페이지네이션

### 재사용 가능한 컴포넌트

- `DataSourceSelector` (차트에서 사용 중)
- `DatabaseConfig` (차트에서 사용 중)
- `ApiConfig` (차트에서 사용 중)
- `QueryEditor` (차트에서 사용 중)

---

## 🚀 시작하기

1. `types.ts`에 타입 추가
2. `ListWidget.tsx` 기본 구조 생성
3. 사이드바에 위젯 추가
4. 설정 모달 구현
5. 테이블 렌더링 구현
