dev-front/DEV8_MIGRATION_MASTER_PLAN.md

# Dev8.py 듀얼 타이머 시스템 마이그레이션 계획서

## 🎯 프로젝트 개요

**목적**: 기존 Front 프로젝트를 dev8.py 백엔드의 듀얼 타이머 시스템에 맞춰 업그레이드

**주요 변경사항**:
- 단일 타이머 → 듀얼 타이머 (물리치료 15분 + 레이저치료 5분)
- 새로운 API 엔드포인트 및 Socket.IO 이벤트 구조
- 향상된 의료진 호출 시스템
- 파일 관리 및 디지털 사이니지 기능

---

## 📊 백엔드 분석 요약

### Dev8.py 핵심 특징

1. **듀얼 타이머 시스템**
   - 물리치료: 900초 (15분)
   - 레이저치료: 300초 (5분)
   - 동시 실행 가능, 독립적 제어

2. **실시간 통신**
   - Socket.IO 기반 100ms 정밀도 업데이트
   - 8개 태블릿 + 관제센터 지원
   - 역할 기반 권한 시스템

3. **의료진 호출 시스템**
   - 호출 생성, 확인, 취소 플로우
   - 실시간 상태 동기화

4. **파일 관리 & 디지털 사이니지**
   - 이미지/비디오 업로드 지원
   - 슬라이드 CRUD 관리
   - 시퀀스 기반 재생

---

## 🗂️ 마이그레이션 작업 계획

### Phase 1: 인프라 구조 업데이트

#### 1.1 Socket 연결 모듈 업그레이드 (`src/utils/realtime-socket.ts`)

**현재 (v7) → 목표 (v8)**:

```typescript
// ❌ 기존: 단일 타이머
interface TimerState {
  tablet_id: string;
  countdown: number;
  status: TimerStatus;
}

// ✅ 새로운: 듀얼 타이머
interface TimerState {
  tablet_id: string;
  timer_type: TimerType;  // 🆕 physical | laser
  countdown: number;
  status: TimerStatus;
  start_time?: number;
  pause_time?: number;
  completion_time?: number;  // 🆕 완료 시간
}

enum TimerType {  // 🆕 타이머 유형
  PHYSICAL = "physical",
  LASER = "laser"
}
```

**새로운 Socket 이벤트 지원**:
- `timer_tick`: 100ms 실시간 업데이트
- `timer_finished`: 타이머 완료 알림
- `treatment_completed`: 치료 완료 알림
- `reset_timer`: 완료된 타이머 리셋

#### 1.2 서버 URL 및 포트 변경

```typescript
// 변경: dev8.py 로컬 서버
const SERVER_URL = 'http://localhost:5005';
```

### Phase 2: UI 컴포넌트 업데이트

#### 2.1 SignageTabletScreen 듀얼 타이머 UI

**현재 구조**:
```
[단일 타이머 표시]
[시작/일시정지/정지 버튼]
```

**새로운 구조**:
```
[물리치료 타이머 (15분)]  [레이저치료 타이머 (5분)]
[독립적 제어 버튼들]      [독립적 제어 버튼들]
[동시 실행 상태 표시]
```

**구현 계획**:
1. 두 개의 독립적인 타이머 상태 관리
2. 타이머별 UI 컴포넌트 분리
3. 시각적 구분 (색상, 아이콘)
4. 완료 상태 및 리셋 기능

#### 2.2 NewControlScreen 관제센터 업그레이드

**새로운 기능**:
- 8개 태블릿의 듀얼 타이머 모니터링
- 모든 타이머 일괄 제어 (`stop_all_timers`)
- 의료진 호출 관리 (확인/취소)
- 실시간 통계 및 상태 표시

#### 2.3 NewTabletScreen 개발자 도구 확장

**추가 기능**:
- 듀얼 타이머 디버깅 정보
- Socket.IO 이벤트 실시간 로그
- API 테스트 도구
- 타이머 상태 상세 정보

### Phase 3: 새로운 기능 구현

#### 3.1 파일 관리 시스템

**새로운 컴포넌트**: `FileManager.tsx`
- 드래그앤드롭 업로드
- 이미지/비디오 미리보기
- UUID 기반 파일 관리
- 파일 타입 검증

#### 3.2 슬라이드 관리 강화

**SlideManager.tsx 업그레이드**:
- 새로운 API 엔드포인트 연동
- 시퀀스 기반 정렬
- 미디어 타입별 처리
- 실시간 미리보기

### Phase 4: 상태 관리 최적화

#### 4.1 듀얼 타이머 상태 관리

```typescript
// 타이머별 상태 분리
const [physicalTimer, setPhysicalTimer] = useState<TimerState>({
  tablet_id: '',
  timer_type: TimerType.PHYSICAL,
  countdown: 0,
  status: TimerStatus.STOPPED
});

const [laserTimer, setLaserTimer] = useState<TimerState>({
  tablet_id: '',
  timer_type: TimerType.LASER,
  countdown: 0,
  status: TimerStatus.STOPPED
});
```

#### 4.2 실시간 이벤트 핸들러

```typescript
// 타이머별 이벤트 처리
const handleTimerTick = (data: TimerTickEvent) => {
  if (data.timer_type === TimerType.PHYSICAL) {
    setPhysicalTimer(prev => ({ ...prev, countdown: data.countdown }));
  } else {
    setLaserTimer(prev => ({ ...prev, countdown: data.countdown }));
  }
};

const handleTimerFinished = (data: TimerFinishedEvent) => {
  // 완료 알림 및 UI 업데이트
  showCompletionNotification(data.timer_type);
};
```

---

## 🎨 UI/UX 설계 변경사항

### 듀얼 타이머 시각적 설계

#### 색상 스키마
- **물리치료**: 파란색 계열 (#3B82F6)
- **레이저치료**: 빨간색 계열 (#EF4444)
- **완료 상태**: 녹색 계열 (#10B981)

#### 레이아웃 구조
```
┌─────────────────────────────────────────┐
│ [헤더 - 연결상태, 설정버튼]                  │
├─────────────────────────────────────────┤
│                                         │
│ [사이니지 백그라운드]                        │
│                                         │
│ ┌─────────────┐  ┌─────────────┐         │
│ │ 물리치료     │  │ 레이저치료    │         │
│ │ 15:00      │  │ 05:00       │         │
│ │ [⏯][⏹]     │  │ [⏯][⏹]      │         │
│ └─────────────┘  └─────────────┘         │
│                                         │
│ [의료진 호출 상태]                           │
└─────────────────────────────────────────┘
```

#### 반응형 설계
- **태블릿 모드**: 듀얼 타이머 나란히 배치
- **모바일 모드**: 세로 스택 배치
- **터치 최적화**: 44px 이상 터치 영역

### 상태 표시 시스템

#### 타이머 상태별 시각적 피드백
- **STOPPED**: 회색 테두리, 시작 버튼 활성화
- **RUNNING**: 진행 중 애니메이션, 일시정지/정지 버튼
- **PAUSED**: 주황색 표시, 재개/정지 버튼
- **FINISHED**: 녹색 배경, 리셋 버튼

#### 의료진 호출 상태
- **NONE**: 호출 버튼 표시
- **CALLING**: 애니메이션 효과, 취소 버튼
- **ACKNOWLEDGED**: 확인됨 표시, 완료 버튼

---

## 🔧 기술적 구현 세부사항

### API 통신 계층

#### HTTP Client 설정
```typescript
const API_BASE_URL = 'http://localhost:5005/api';

// 새로운 API 엔드포인트
const apiEndpoints = {
  health: '/health',
  status: '/status',
  timers: '/timers',
  calls: '/calls',
  slides: '/slides',
  files: '/files'
};
```

#### Socket.IO 클라이언트 설정
```typescript
const socket = io('http://localhost:5005', {
  transports: ['websocket', 'polling'],
  timeout: 5000,
  reconnection: true,
  reconnectionAttempts: 5,
  reconnectionDelay: 1000
});
```

### 에러 처리 및 복구

#### 연결 실패 처리
- 자동 재연결 시도
- 오프라인 모드 지원
- 사용자 알림 시스템

#### 데이터 검증
- TypeScript 타입 체크
- 런타임 데이터 유효성 검사
- 에러 바운더리 구현

---

## 🧪 테스트 전략

### 단위 테스트
- 타이머 로직 테스트
- Socket.IO 이벤트 핸들러 테스트
- UI 컴포넌트 렌더링 테스트

### 통합 테스트
- 백엔드 API 연동 테스트
- 실시간 통신 테스트
- 듀얼 타이머 시나리오 테스트

### 사용자 테스트
- 터치 인터페이스 테스트
- 의료진 호출 플로우 테스트
- 다중 태블릿 동시 사용 테스트

---

## 📅 마이그레이션 일정

### Week 1: 인프라 및 기본 구조
- [ ] Socket 연결 모듈 업그레이드
- [ ] 타이머 상태 인터페이스 정의
- [ ] 기본 UI 컴포넌트 수정

### Week 2: 듀얼 타이머 구현
- [ ] SignageTabletScreen 듀얼 타이머 UI
- [ ] 타이머 제어 로직 구현
- [ ] 실시간 업데이트 처리

### Week 3: 관제센터 및 고급 기능
- [ ] NewControlScreen 업그레이드
- [ ] 의료진 호출 시스템 완성
- [ ] 파일 관리 기능 구현

### Week 4: 최적화 및 테스트
- [ ] 성능 최적화
- [ ] 통합 테스트
- [ ] 사용자 테스트 및 피드백 반영

---

## 🎯 성공 지표

### 기능적 요구사항
- ✅ 듀얼 타이머 독립적 제어
- ✅ 실시간 100ms 정밀도 업데이트
- ✅ 8개 태블릿 동시 지원
- ✅ 의료진 호출 완전 플로우
- ✅ 디지털 사이니지 통합

### 비기능적 요구사항
- ✅ 1초 이내 UI 반응성
- ✅ 99% 연결 안정성
- ✅ 터치 인터페이스 최적화
- ✅ 크로스 브라우저 호환성

### 사용자 경험
- ✅ 직관적인 듀얼 타이머 인터페이스
- ✅ 명확한 상태 시각적 피드백
- ✅ 실수 방지 UX 패턴
- ✅ 접근성 표준 준수

---

## 🚀 배포 계획

### 개발 환경
- **포트**: 5071 (dev-front)
- **백엔드**: localhost:5005 (dev8.py)
- **데이터베이스**: SQLite (개발용)

### 스테이징 환경
- **도메인**: dev.ysl.0bin.in
- **리버스 프록시**: Nginx
- **SSL**: Let's Encrypt

### 프로덕션 환경
- **도메인**: ysl.0bin.in
- **CDN**: 정적 자원 최적화
- **모니터링**: 실시간 상태 감시

---

## 📋 위험 요소 및 대응 방안

### 기술적 위험
1. **실시간 통신 안정성**
   - 대응: 연결 상태 모니터링, 자동 재연결
2. **듀얼 타이머 동기화**
   - 대응: 서버 시간 기준 동기화, 로컬 보정
3. **대용량 파일 업로드**
   - 대응: 청크 업로드, 진행률 표시

### 사용자 경험 위험
1. **복잡성 증가**
   - 대응: 단계별 사용자 가이드, 직관적 UI
2. **터치 오작동**
   - 대응: 확인 다이얼로그, 실행 취소 기능

### 운영 위험
1. **기존 시스템과의 호환성**
   - 대응: 점진적 마이그레이션, 롤백 계획
2. **사용자 교육**
   - 대응: 트레이닝 자료, 실시간 도움말

---

이 계획서는 dev8.py 백엔드 시스템의 모든 기능을 완전히 활용하는 현대적이고 직관적인 프론트엔드를 구축하기 위한 종합적인 로드맵을 제공합니다.