# JSON 통신 프로토콜 상세 명세서

## 1. 기본 메시지 구조

### 1.1 공통 헤더
모든 메시지는 다음 구조를 가져야 합니다:

```json
{
  "type": "메시지_타입",
  "timestamp": "ISO 8601 형식",
  "version": "1.0",
  "data": {
    // 메시지별 데이터
  }
}
```

### 1.2 필수 필드 설명
- `type`: 메시지 타입 (문자열, 필수)
- `timestamp`: 메시지 생성 시간 (ISO 8601, 필수)
- `version`: 프로토콜 버전 (문자열, 필수)
- `data`: 메시지 데이터 (객체, 필수)

## 2. 연결 관련 메시지

### 2.1 연결 성공 (connection_established)
```json
{
  "type": "connection_established",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "version": "1.0",
  "data": {
    "session_id": "unique_session_id",
    "available_controllers": [
      {
        "id": "camera_controller",
        "name": "카메라 컨트롤러",
        "type": "camera",
        "description": "카메라 전환 및 설정 관리",
        "items": [
          {
            "id": "camera_1",
            "name": "메인 카메라",
            "description": "메인 스트리밍 카메라",
            "status": "active",
            "properties": {
              "fov": 60,
              "position": [0, 0, 0],
              "rotation": [0, 0, 0]
            }
          }
        ],
        "available_actions": [
          {
            "id": "switch_camera",
            "name": "카메라 전환",
            "description": "선택된 카메라로 전환"
          },
          {
            "id": "adjust_fov",
            "name": "FOV 조정",
            "description": "시야각 조정"
          }
        ]
      }
    ],
    "ui_state": {
      "current_selection": null,
      "available_actions": [],
      "theme": "dark",
      "language": "ko"
    }
  }
}
```

### 2.2 연결 실패 (connection_failed)
```json
{
  "type": "connection_failed",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "version": "1.0",
  "data": {
    "error_code": "AUTH_FAILED",
    "error_message": "인증에 실패했습니다",
    "retry_after": 30
  }
}
```

### 2.3 하트비트 (heartbeat)
```json
{
  "type": "heartbeat",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "version": "1.0",
  "data": {
    "status": "alive",
    "uptime": 3600
  }
}
```

## 3. 데이터 요청/응답 메시지

### 3.1 데이터 요청 (request_data)
```json
{
  "type": "request_data",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "version": "1.0",
  "data": {
    "request_type": "controller_list",
    "controller_id": "camera_controller",
    "filters": {
      "status": "active",
      "category": "camera"
    }
  }
}
```

### 3.2 데이터 응답 (data_response)
```json
{
  "type": "data_response",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "version": "1.0",
  "data": {
    "request_id": "req_12345",
    "request_type": "controller_list",
    "result": {
      "controllers": [
        {
          "id": "camera_controller",
          "name": "카메라 컨트롤러",
          "items": [
            {
              "id": "camera_1",
              "name": "메인 카메라",
              "status": "active"
            }
          ]
        }
      ]
    }
  }
}
```

### 3.3 데이터 업데이트 알림 (data_update)
```json
{
  "type": "data_update",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "version": "1.0",
  "data": {
    "controller_id": "camera_controller",
    "update_type": "item_status_changed",
    "item_id": "camera_1",
    "changes": {
      "status": "inactive",
      "position": [10, 5, 0]
    }
  }
}
```

## 4. 액션 실행 메시지

### 4.1 액션 실행 요청 (execute_action)
```json
{
  "type": "execute_action",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "version": "1.0",
  "data": {
    "action_id": "switch_camera",
    "controller_id": "camera_controller",
    "parameters": {
      "target_camera_id": "camera_2",
      "transition_time": 1.0
    },
    "request_id": "action_12345"
  }
}
```

### 4.2 액션 실행 결과 (action_result)
```json
{
  "type": "action_result",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "version": "1.0",
  "data": {
    "request_id": "action_12345",
    "action_id": "switch_camera",
    "status": "success",
    "result": {
      "previous_camera": "camera_1",
      "current_camera": "camera_2",
      "transition_completed": true
    },
    "execution_time": 0.5
  }
}
```

### 4.3 액션 실행 실패
```json
{
  "type": "action_result",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "version": "1.0",
  "data": {
    "request_id": "action_12345",
    "action_id": "switch_camera",
    "status": "failed",
    "error": {
      "code": "CAMERA_NOT_FOUND",
      "message": "요청된 카메라를 찾을 수 없습니다"
    }
  }
}
```

## 5. UI 업데이트 메시지

### 5.1 UI 업데이트 요청 (ui_update)
```json
{
  "type": "ui_update",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "version": "1.0",
  "data": {
    "update_type": "selection_changed",
    "controller_id": "camera_controller",
    "selection": {
      "item_id": "camera_1",
      "item_name": "메인 카메라"
    }
  }
}
```

### 5.2 UI 상태 정보 (ui_state)
```json
{
  "type": "ui_state",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "version": "1.0",
  "data": {
    "current_selection": {
      "controller_id": "camera_controller",
      "item_id": "camera_1"
    },
    "available_actions": [
      {
        "id": "switch_camera",
        "name": "카메라 전환",
        "enabled": true
      },
      {
        "id": "adjust_fov",
        "name": "FOV 조정",
        "enabled": false
      }
    ],
    "ui_theme": "dark",
    "language": "ko"
  }
}
```

## 6. 컨트롤러별 데이터 구조

### 6.1 카메라 컨트롤러 (CameraController)
```json
{
  "id": "camera_controller",
  "name": "카메라 컨트롤러",
  "type": "camera",
  "items": [
    {
      "id": "camera_1",
      "name": "메인 카메라",
      "description": "메인 스트리밍 카메라",
      "status": "active",
      "properties": {
        "fov": 60,
        "position": [0, 1.7, -5],
        "rotation": [0, 0, 0],
        "near_clip": 0.1,
        "far_clip": 1000
      },
      "actions": [
        {
          "id": "activate",
          "name": "활성화",
          "description": "카메라 활성화"
        },
        {
          "id": "adjust_fov",
          "name": "FOV 조정",
          "description": "시야각 조정",
          "parameters": {
            "min": 30,
            "max": 120,
            "step": 5
          }
        }
      ]
    }
  ]
}
```

### 6.2 아이템 컨트롤러 (ItemController)
```json
{
  "id": "item_controller",
  "name": "아이템 컨트롤러",
  "type": "item",
  "items": [
    {
      "id": "weapon_1",
      "name": "기본 무기",
      "description": "기본 공격 무기",
      "status": "equipped",
      "properties": {
        "damage": 10,
        "range": 5,
        "durability": 100
      },
      "actions": [
        {
          "id": "equip",
          "name": "장착",
          "description": "무기 장착"
        },
        {
          "id": "unequip",
          "name": "해제",
          "description": "무기 해제"
        }
      ]
    }
  ]
}
```

## 7. 에러 코드 정의

### 7.1 연결 관련 에러
- `CONNECTION_REFUSED`: 연결 거부
- `AUTH_FAILED`: 인증 실패
- `TIMEOUT`: 연결 타임아웃
- `INVALID_PROTOCOL`: 잘못된 프로토콜

### 7.2 데이터 관련 에러
- `INVALID_REQUEST`: 잘못된 요청
- `DATA_NOT_FOUND`: 데이터 없음
- `PERMISSION_DENIED`: 권한 없음
- `VALIDATION_FAILED`: 데이터 검증 실패

### 7.3 액션 관련 에러
- `ACTION_NOT_FOUND`: 액션 없음
- `INVALID_PARAMETERS`: 잘못된 매개변수
- `EXECUTION_FAILED`: 실행 실패
- `RESOURCE_BUSY`: 리소스 사용 중

## 8. 메시지 우선순위

### 8.1 높은 우선순위 (즉시 처리)
- `connection_established`
- `connection_failed`
- `heartbeat`
- `action_result` (실패)

### 8.2 중간 우선순위 (순차 처리)
- `execute_action`
- `data_update`
- `ui_update`

### 8.3 낮은 우선순위 (배치 처리)
- `request_data`
- `data_response`
- `ui_state`

## 9. 메시지 크기 제한

### 9.1 단일 메시지 제한
- 최대 크기: 1MB
- 권장 크기: 100KB 이하
- 압축 사용 권장

### 9.2 배치 메시지
- 최대 항목 수: 100개
- 페이지네이션 사용
- 스트리밍 응답 지원

## 10. 버전 관리

### 10.1 호환성 정책
- 하위 호환성 유지
- 점진적 기능 추가
- 마이그레이션 가이드 제공

### 10.2 버전 형식
- Semantic Versioning (MAJOR.MINOR.PATCH)
- 예: "1.0.0", "1.1.2"

### 10.3 버전 확인
- 연결 시 버전 교환
- 호환성 검증
- 업그레이드 알림