Streamingle_URP/Streamdeck/Streamingle_Plugin_Architecture.md

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

1. 시스템 개요

1.1 목적

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

1.2 핵심 특징

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

2. 통신 프로토콜

2.1 기본 메시지 구조

{
  "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 초기 데이터 구조

{
  "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 개선