# 기사 관리 위젯 구현 계획

## 개요

대시보드에 추가할 수 있는 기사 관리 위젯을 구현합니다. 실시간으로 기사와 차량의 운행 상태를 확인하고 관리할 수 있는 기능을 제공합니다.

## 주요 기능

### 1. 기사 정보 표시

- **차량 번호**: 예) 12가 3456
- **기사 이름**: 예) 홍길동
- **출발지**: 예) 서울시 강남구
- **목적지**: 예) 경기도 성남시
- **차량 유형**: 예) 1톤 트럭, 2.5톤 트럭, 5톤 트럭, 카고, 탑차, 냉동차 등
- **운행 상태**: 대기중, 운행중, 휴식중, 점검중
- **연락처**: 기사 전화번호
- **운행 시작 시간**: 출발 시간
- **예상 도착 시간**: 목적지 도착 예정 시간

### 2. 운행 상태 구분

- **대기중** (회색): 출발지/목적지가 없는 상태
- **운행중** (초록색): 출발지/목적지가 있고 운행 중
- **휴식중** (주황색): 휴게 중
- **점검중** (빨간색): 차량 점검 또는 수리 중

### 3. 뷰 타입

- **리스트 뷰**: 테이블 형식으로 전체 기사 목록 표시
- **맵 뷰** (향후 확장): 지도에 기사 위치 표시

### 4. 필터링 및 검색

- **상태별 필터**: 운행중, 대기중, 휴식중, 점검중
- **차량 유형별 필터**: 1톤, 2.5톤, 5톤 등
- **검색**: 기사 이름, 차량 번호로 검색

### 5. 정렬 기능

- 기사 이름순
- 차량 번호순
- 출발 시간순
- 운행 상태별

### 6. 설정 옵션

- **뷰 타입**: 리스트
- **자동 새로고침**: 실시간 데이터 갱신 (10초, 30초, 1분)
- **표시 항목**: 사용자가 원하는 컬럼만 표시
- **테마**: Light, Dark, 사용자 지정

## 데이터 구조

```typescript
interface DriverInfo {
  id: string; // 기사 고유 ID
  name: string; // 기사 이름
  vehicleNumber: string; // 차량 번호
  vehicleType: string; // 차량 유형
  phone: string; // 연락처
  status: "standby" | "driving" | "resting" | "maintenance"; // 운행 상태
  departure?: string; // 출발지 (운행 중일 때)
  destination?: string; // 목적지 (운행 중일 때)
  departureTime?: string; // 출발 시간
  estimatedArrival?: string; // 예상 도착 시간
  progress?: number; // 운행 진행률 (0-100)
}
```

## 목업 데이터

```typescript
const MOCK_DRIVERS: DriverInfo[] = [
  {
    id: "DRV001",
    name: "홍길동",
    vehicleNumber: "12가 3456",
    vehicleType: "1톤 트럭",
    phone: "010-1234-5678",
    status: "driving",
    departure: "서울시 강남구",
    destination: "경기도 성남시",
    departureTime: "2025-10-14T09:00:00",
    estimatedArrival: "2025-10-14T11:30:00",
    progress: 65,
  },
  {
    id: "DRV002",
    name: "김철수",
    vehicleNumber: "34나 7890",
    vehicleType: "2.5톤 트럭",
    phone: "010-2345-6789",
    status: "standby",
  },
  {
    id: "DRV003",
    name: "이영희",
    vehicleNumber: "56다 1234",
    vehicleType: "5톤 트럭",
    phone: "010-3456-7890",
    status: "driving",
    departure: "인천광역시",
    destination: "충청남도 천안시",
    departureTime: "2025-10-14T08:30:00",
    estimatedArrival: "2025-10-14T10:00:00",
    progress: 85,
  },
  {
    id: "DRV004",
    name: "박민수",
    vehicleNumber: "78라 5678",
    vehicleType: "카고",
    phone: "010-4567-8901",
    status: "resting",
  },
  {
    id: "DRV005",
    name: "정수진",
    vehicleNumber: "90마 9012",
    vehicleType: "냉동차",
    phone: "010-5678-9012",
    status: "maintenance",
  },
];
```

## 구현 단계

### ✅ Step 1: 타입 정의

- [x] `DriverManagementConfig` 인터페이스 정의
- [x] `DriverInfo` 인터페이스 정의
- [x] `types.ts`에 기사 관리 설정 타입 추가
- [x] 요소 타입에 'driver-management' subtype 추가

### ✅ Step 2: 목업 데이터 생성

- [x] `driverMockData.ts` - 기사 목업 데이터 생성
- [x] 다양한 운행 상태의 샘플 데이터 (15개)
- [x] 차량 유형별 샘플 데이터

### ✅ Step 3: 유틸리티 함수

- [x] `driverUtils.ts` - 기사 관리 유틸리티 함수
- [x] 운행 상태별 색상 반환
- [x] 진행률 계산
- [x] 시간 포맷팅
- [x] 필터링/정렬 로직

### ✅ Step 4: 리스트 뷰 컴포넌트

- [x] `DriverListView.tsx` - 테이블 형식 리스트 뷰
- [x] 상태별 색상 구분
- [x] 정렬 기능 (유틸리티에서 처리)
- [x] 반응형 테이블 디자인 (컴팩트 모드 포함)

### ✅ Step 5: 카드 뷰 컴포넌트

- [x] 카드 뷰는 현재 구현하지 않음 (리스트 뷰만 사용)
- [ ] `DriverCardView.tsx` - 향후 추가 예정

### ✅ Step 6: 메인 위젯 컴포넌트

- [x] `DriverManagementWidget.tsx` - 메인 위젯
- [x] 리스트 뷰 표시
- [x] 필터링 UI (상태별)
- [x] 검색 기능
- [x] 자동 새로고침 (시뮬레이션)

### ✅ Step 7: 설정 UI

- [x] `DriverManagementSettings.tsx` - 설정 컴포넌트
- [x] 자동 새로고침 간격 설정
- [x] 표시 컬럼 선택
- [x] 테마 설정
- [x] 정렬 기준 설정

### ✅ Step 8: 통합

- [x] `DashboardSidebar`에 기사 관리 위젯 추가
- [x] `CanvasElement`에서 기사 관리 위젯 렌더링
- [x] `DashboardDesigner`에 기본값 설정
- [x] `ElementConfigModal`에 예외 처리 추가

### ✅ Step 9: 스타일링 및 최적화

- [ ] 반응형 디자인 (다양한 위젯 크기 대응)
- [ ] 컴팩트 모드 (작은 크기)
- [ ] 로딩 상태 처리
- [ ] 빈 데이터 상태 처리

### ✅ Step 10: 향후 확장 기능

- [ ] 실제 REST API 연동
- [ ] 웹소켓을 통한 실시간 업데이트
- [ ] 맵 뷰 (지도에 기사 위치 표시)
- [ ] 기사별 상세 정보 모달
- [ ] 운행 이력 조회
- [ ] 알림 기능 (지연, 긴급 상황 등)

## 위젯 크기별 최적화

### 2x2 (최소 크기)

- 요약 정보만 표시 (운행중 기사 수, 대기 기사 수)
- 간단한 상태 표시

### 3x3

- 카드 뷰 (2-3개 기사 표시)
- 기본 정보 표시

### 4x3 이상 (권장)

- 리스트 뷰 또는 카드 뷰 전체 표시
- 필터링 및 검색 기능
- 모든 정보 표시

## 완료 기준

- [x] 기본 타입 정의 완료
- [x] 목업 데이터 생성 완료
- [x] 리스트 뷰 구현 완료
- [ ] 카드 뷰 구현 완료 (향후 추가)
- [x] 필터링/검색 기능 구현 완료
- [x] 설정 UI 구현 완료
- [x] 대시보드 통합 완료
- [ ] 다양한 크기에서 테스트 완료 (사용자 테스트 필요)

## 주의사항

1. **성능 최적화**: 많은 기사 데이터를 처리할 때 가상 스크롤링 고려
2. **실시간 업데이트**: 자동 새로고침 시 부드러운 전환 애니메이션
3. **접근성**: 키보드 네비게이션 지원
4. **에러 처리**: API 연동 시 에러 상태 처리
5. **반응형**: 작은 크기에서도 정보가 잘 보이도록 디자인

## 추가 개선 사항 제안

### 1. 통계 정보

- 오늘 총 운행 건수
- 평균 운행 시간
- 차량 유형별 운행 통계

### 2. 긴급 상황 알림

- 운행 지연 알림 (예상 시간 초과)
- 차량 점검 필요 알림
- 기사 연락 두절 알림

### 3. 배차 관리 (고급 기능)

- 대기 중인 기사에게 배차
- 운행 스케줄 관리
- 경로 최적화 제안

### 4. 보고서 기능

- 일일 운행 보고서
- 기사별 운행 실적
- 차량별 가동률

---

## 🎯 구현 우선순위

1. **필수 (Phase 1)**
   - 타입 정의
   - 목업 데이터
   - 리스트 뷰
   - 기본 필터링

2. **중요 (Phase 2)**
   - 카드 뷰
   - 검색 기능
   - 설정 UI
   - 자동 새로고침

3. **추가 (Phase 3)**
   - 통계 정보
   - 상세 정보 모달
   - 운행 이력

4. **향후 (Phase 4)**
   - 맵 뷰
   - 실시간 위치 추적
   - 배차 관리
   - 보고서 기능

---

**구현 시작일**: 2025-10-14
**구현 완료일**: 2025-10-14
**현재 진행률**: 90% (카드 뷰 및 최종 테스트 제외)

## 🎉 구현 완료!

기사 관리 위젯의 핵심 기능이 모두 구현되었습니다!

### ✅ 구현된 기능

1. **데이터 구조**
   - DriverInfo, DriverManagementConfig 타입 정의
   - 15개의 다양한 목업 데이터
   - 6가지 차량 유형 지원

2. **리스트 뷰**
   - 테이블 형식의 깔끔한 UI
   - 상태별 색상 구분 (운행중/대기중/휴식중/점검중)
   - 컴팩트 모드 지원 (2x2 크기)

3. **필터링 및 검색**
   - 상태별 필터 (전체/운행중/대기중/휴식중/점검중)
   - 기사명, 차량번호 검색
   - 실시간 필터링

4. **정렬 기능**
   - 기사명, 차량번호, 운행상태, 출발시간 기준 정렬
   - 오름차순/내림차순 지원

5. **자동 새로고침**
   - 10초/30초/1분/5분 간격 설정 가능
   - 실시간 데이터 시뮬레이션

6. **설정 UI**
   - Popover 방식의 직관적인 설정
   - 표시 컬럼 선택 (9개 컬럼)
   - 테마 설정 (Light/Dark/Custom)
   - 정렬 기준 및 순서 설정

7. **대시보드 통합**
   - 사이드바에 드래그 가능한 위젯 추가
   - 캔버스에서 자유로운 배치 및 크기 조절
   - 설정 저장 및 불러오기

### 🚀 향후 개선 사항

- 카드 뷰 구현
- 맵 뷰 (지도 연동)
- 실제 REST API 연동
- 웹소켓 실시간 업데이트
- 통계 정보 추가
- 배차 관리 기능