417 lines
9.0 KiB (Stored with Git LFS)
Markdown
417 lines
9.0 KiB (Stored with Git LFS)
Markdown
# 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 버전 확인
|
|
- 연결 시 버전 교환
|
|
- 호환성 검증
|
|
- 업그레이드 알림 |