# v2-timeline-scheduler

간트차트 형태의 일정/계획 시각화 및 편집 컴포넌트

## 개요

`v2-timeline-scheduler`는 생산계획, 일정관리 등에서 사용할 수 있는 타임라인 기반의 스케줄러 컴포넌트입니다. 리소스(설비, 작업자 등)별로 스케줄을 시각화하고, 드래그/리사이즈로 일정을 조정할 수 있습니다.

## 핵심 기능

| 기능 | 설명 |
|------|------|
| 타임라인 그리드 | 일/주/월 단위 그리드 표시 |
| 스케줄 바 | 시작~종료 기간 바 렌더링 |
| 리소스 행 | 설비/작업자별 행 구분 |
| 드래그 이동 | 스케줄 바 드래그로 날짜 변경 |
| 리사이즈 | 바 양쪽 핸들로 기간 조정 |
| 줌 레벨 | 일/주/월 단위 전환 |
| 진행률 표시 | 바 내부 진행률 표시 |
| 오늘 표시선 | 현재 날짜 표시선 |

## 사용법

### 기본 사용

```tsx
import { TimelineSchedulerComponent } from "@/lib/registry/components/v2-timeline-scheduler";

<TimelineSchedulerComponent
  config={{
    selectedTable: "production_schedule",
    resourceTable: "equipment",
    fieldMapping: {
      id: "id",
      resourceId: "equipment_id",
      title: "plan_name",
      startDate: "start_date",
      endDate: "end_date",
      status: "status",
      progress: "progress",
    },
    resourceFieldMapping: {
      id: "id",
      name: "equipment_name",
    },
    defaultZoomLevel: "day",
    editable: true,
  }}
  onScheduleClick={(event) => {
    console.log("클릭된 스케줄:", event.schedule);
  }}
  onDragEnd={(event) => {
    console.log("드래그 완료:", event);
  }}
/>
```

### 설정 옵션

| 옵션 | 타입 | 기본값 | 설명 |
|------|------|--------|------|
| `selectedTable` | string | - | 스케줄 데이터 테이블명 |
| `resourceTable` | string | - | 리소스 테이블명 |
| `fieldMapping` | object | - | 스케줄 필드 매핑 |
| `resourceFieldMapping` | object | - | 리소스 필드 매핑 |
| `defaultZoomLevel` | "day" \| "week" \| "month" | "day" | 기본 줌 레벨 |
| `editable` | boolean | true | 편집 가능 여부 |
| `draggable` | boolean | true | 드래그 이동 가능 |
| `resizable` | boolean | true | 리사이즈 가능 |
| `rowHeight` | number | 50 | 행 높이 (px) |
| `headerHeight` | number | 60 | 헤더 높이 (px) |
| `resourceColumnWidth` | number | 150 | 리소스 컬럼 너비 (px) |
| `showTodayLine` | boolean | true | 오늘 표시선 |
| `showProgress` | boolean | true | 진행률 표시 |
| `showToolbar` | boolean | true | 툴바 표시 |
| `height` | number \| string | 500 | 컴포넌트 높이 |

### 필드 매핑

스케줄 테이블의 컬럼을 매핑합니다:

```typescript
fieldMapping: {
  id: "id",                    // 필수: 고유 ID
  resourceId: "equipment_id",  // 필수: 리소스 ID (FK)
  title: "plan_name",          // 필수: 표시 제목
  startDate: "start_date",     // 필수: 시작일
  endDate: "end_date",         // 필수: 종료일
  status: "status",            // 선택: 상태
  progress: "progress",        // 선택: 진행률 (0-100)
  color: "color",              // 선택: 바 색상
}
```

### 이벤트

| 이벤트 | 파라미터 | 설명 |
|--------|----------|------|
| `onScheduleClick` | `{ schedule, resource }` | 스케줄 클릭 |
| `onCellClick` | `{ resourceId, date }` | 빈 셀 클릭 |
| `onDragEnd` | `{ scheduleId, newStartDate, newEndDate }` | 드래그 완료 |
| `onResizeEnd` | `{ scheduleId, newStartDate, newEndDate, direction }` | 리사이즈 완료 |
| `onAddSchedule` | `(resourceId, date)` | 추가 버튼 클릭 |

### 상태별 색상

기본 상태별 색상:

| 상태 | 색상 | 의미 |
|------|------|------|
| `planned` | 파랑 (#3b82f6) | 계획됨 |
| `in_progress` | 주황 (#f59e0b) | 진행중 |
| `completed` | 초록 (#10b981) | 완료 |
| `delayed` | 빨강 (#ef4444) | 지연 |
| `cancelled` | 회색 (#6b7280) | 취소 |

## 파일 구조

```
v2-timeline-scheduler/
├── index.ts                          # Definition
├── types.ts                          # 타입 정의
├── config.ts                         # 기본 설정값
├── TimelineSchedulerComponent.tsx    # 메인 컴포넌트
├── TimelineSchedulerConfigPanel.tsx  # 설정 패널
├── TimelineSchedulerRenderer.tsx     # 레지스트리 등록
├── README.md                         # 문서
├── components/
│   ├── index.ts
│   ├── TimelineHeader.tsx            # 날짜 헤더
│   ├── ScheduleBar.tsx               # 스케줄 바
│   └── ResourceRow.tsx               # 리소스 행
└── hooks/
    └── useTimelineData.ts            # 데이터 관리 훅
```

## v2-table-list와의 차이점

| 특성 | v2-table-list | v2-timeline-scheduler |
|------|---------------|----------------------|
| 표현 방식 | 행 기반 테이블 | 시간축 기반 간트차트 |
| 데이터 구조 | 단순 목록 | 리소스 + 스케줄 (2개 테이블) |
| 편집 방식 | 폼 입력 | 드래그/리사이즈 |
| 시간 표현 | 텍스트 | 시각적 바 |
| 용도 | 일반 데이터 | 일정/계획 관리 |

## 향후 개선 사항

- [ ] 충돌 감지 및 표시
- [ ] 가상 스크롤 (대량 데이터)
- [ ] 마일스톤 표시
- [ ] 의존성 연결선
- [ ] 드래그로 새 스케줄 생성
- [ ] 컨텍스트 메뉴

---

**버전**: 2.0.0  
**최종 수정**: 2026-01-30
