# Streamingle 플러그인 아키텍처 설계서

## 1. 시스템 개요

### 1.1 목적
- 스트림덱 플러그인과 유니티 간의 실시간 양방향 통신
- 여러 컨트롤러를 하나의 플러그인에서 통합 관리
- 연결 즉시 데이터 공유 및 동적 UI 업데이트

### 1.2 핵심 특징
- WebSocket 기반 실시간 통신
- JSON 프로토콜을 통한 구조화된 데이터 교환
- 연결 시 즉시 데이터 동기화
- 확장 가능한 컨트롤러 아키텍처

## 2. 통신 프로토콜

### 2.1 기본 메시지 구조
```json
{
  "type": "메시지_타입",
  "timestamp": "2024-01-01T00:00:00Z",
  "data": {
    // 메시지별 데이터
  }
}
```

### 2.2 메시지 타입 정의

#### 2.2.1 연결 관련
- `connection_established`: 연결 성공
- `connection_failed`: 연결 실패
- `heartbeat`: 연결 상태 확인

#### 2.2.2 데이터 요청/응답
- `request_data`: 데이터 요청
- `data_response`: 데이터 응답
- `data_update`: 데이터 업데이트 알림

#### 2.2.3 액션 실행
- `execute_action`: 액션 실행 요청
- `action_result`: 액션 실행 결과

#### 2.2.4 UI 업데이트
- `ui_update`: UI 업데이트 요청
- `ui_state`: UI 상태 정보

## 3. 연결 시 즉시 데이터 공유 구조

### 3.1 연결 핸드셰이크 프로세스
1. 스트림덱 → 유니티: 연결 시도
2. 유니티 → 스트림덱: `connection_established` + 초기 데이터
3. 스트림덱: UI 즉시 업데이트

### 3.2 초기 데이터 구조
```json
{
  "type": "connection_established",
  "timestamp": "2024-01-01T00:00:00Z",
  "data": {
    "available_controllers": [
      {
        "id": "camera_controller",
        "name": "카메라 컨트롤러",
        "type": "camera",
        "items": [
          {
            "id": "camera_1",
            "name": "메인 카메라",
            "description": "메인 스트리밍 카메라"
          }
        ]
      },
      {
        "id": "item_controller", 
        "name": "아이템 컨트롤러",
        "type": "item",
        "items": [
          {
            "id": "item_1",
            "name": "무기 1",
            "description": "기본 무기"
          }
        ]
      }
    ],
    "ui_state": {
      "current_selection": null,
      "available_actions": []
    }
  }
}
```

## 4. 컨트롤러 아키텍처

### 4.1 기본 컨트롤러 인터페이스
모든 컨트롤러는 다음 인터페이스를 구현해야 함:
- `GetControllerInfo()`: 컨트롤러 정보 반환
- `GetItems()`: 관리 항목 목록 반환
- `ExecuteAction(action_id, parameters)`: 액션 실행
- `OnDataUpdate()`: 데이터 업데이트 알림

### 4.2 컨트롤러 등록 시스템
- 유니티 시작 시 자동 컨트롤러 스캔
- 동적 컨트롤러 추가/제거 지원
- 컨트롤러별 설정 관리

### 4.3 지원 컨트롤러 타입
- CameraController: 카메라 전환, 설정
- ItemController: 아이템 관리, 장착
- AnimationController: 애니메이션 재생
- EffectController: 이펙트 제어
- AudioController: 오디오 제어

## 5. 데이터 동기화 전략

### 5.1 실시간 업데이트
- 컨트롤러 상태 변경 시 즉시 알림
- UI 상태 자동 동기화
- 연결 끊김 시 자동 재연결

### 5.2 데이터 캐싱
- 스트림덱 측 로컬 캐시
- 변경된 데이터만 전송
- 캐시 무효화 전략

### 5.3 동기화 우선순위
1. 연결 시 전체 데이터
2. 상태 변경 알림
3. 주기적 하트비트
4. 요청 시 데이터

## 6. 에러 처리 및 복구

### 6.1 연결 관리
- 자동 재연결 (지수 백오프)
- 연결 상태 모니터링
- 타임아웃 처리

### 6.2 데이터 무결성
- JSON 유효성 검증
- 필수 필드 확인
- 기본값 처리

### 6.3 로깅 및 디버깅
- 구조화된 로그 시스템
- 에러 추적 및 보고
- 성능 모니터링

## 7. 확장성 고려사항

### 7.1 새로운 컨트롤러 추가
- 인터페이스 구현만으로 추가 가능
- 플러그인 재시작 없이 동적 로드
- 설정 기반 컨트롤러 활성화

### 7.2 새로운 메시지 타입
- 프로토콜 버전 관리
- 하위 호환성 유지
- 점진적 기능 추가

### 7.3 성능 최적화
- 메시지 압축
- 배치 처리
- 연결 풀링

## 8. 개발 로드맵

### 8.1 Phase 1: 기본 구조
- WebSocket 통신 기반 구축
- 기본 컨트롤러 인터페이스
- 연결 시 데이터 공유

### 8.2 Phase 2: 컨트롤러 구현
- CameraController 구현
- ItemController 구현
- 기본 UI 업데이트

### 8.3 Phase 3: 고급 기능
- 동적 컨트롤러 로드
- 고급 에러 처리
- 성능 최적화

### 8.4 Phase 4: 확장
- 추가 컨트롤러 타입
- 고급 UI 기능
- 플러그인 마켓플레이스 준비

## 9. 기술 스택

### 9.1 유니티 측
- WebSocketSharp: WebSocket 서버
- JSON.NET: JSON 직렬화
- Unity Coroutines: 비동기 처리

### 9.2 스트림덱 측
- ws: WebSocket 클라이언트
- Node.js 내장 모듈: 파일 시스템, 로깅
- JSON: 데이터 직렬화

## 10. 보안 고려사항

### 10.1 인증
- 연결 시 인증 토큰 검증
- 권한 기반 액션 제어
- 세션 관리

### 10.2 데이터 보호
- 민감한 데이터 암호화
- 로그 데이터 마스킹
- 접근 제어

## 11. 테스트 전략

### 11.1 단위 테스트
- 컨트롤러 인터페이스 테스트
- JSON 프로토콜 검증
- 에러 처리 테스트

### 11.2 통합 테스트
- 전체 시스템 통합 테스트
- 성능 테스트
- 부하 테스트

### 11.3 사용자 테스트
- 실제 스트리밍 환경 테스트
- 사용자 피드백 수집
- UI/UX 개선