Skip to content

Interface Specification

Jump to bottom
yonmilk edited this page Nov 5, 2025 · 1 revision

Login / Signup

개요

항목 내용
구분 로그인 / 회원가입
목적 사용자 인증 또는 계정 생성 요청/응답
데이터 형식 JSON
사용 프로토콜 TCP / UDP / CoAP / MQTT (공통 포맷 사용)

공통 메시지 구조

{
  "command": "signup",
  "payload": {
    "userNm": "admin",
    "userNickNm": "관리자",
    "userEmail": "abc@xyz.com",
    "userPassword": "hashed_password"
  }
}
  • command: "login" 또는 "signup"
  • payload: 실제 데이터 영역

요청 명세

공통 필드

필드명 타입 필수 설명 매핑되는 DB 컬럼 (User)
command STRING 예 "login" 또는 "signup" -

signup 명령 시 payload

필드명 타입 필수 설명 매핑 DB 컬럼
userNm STRING 예 사용자 계정명 name
userNickNm STRING 예 사용자 표시 이름 nickname
userEmail STRING(100) 예 이메일 주소 email
userPassword STRING 예 해시된 비밀번호 password

login 명령 시 payload

필드명 타입 필수 설명 매핑 DB 컬럼
userEmail STRING(100) 예 이메일 주소 email
userPassword STRING 예 해시된 비밀번호 password

응답 명세

공통 응답 형식

{
  "resultCode": 1000,
  "resultMsg": "SUCCESS",
  "data": {
    "userId": 1,
    "token": "abc.def.ghi"
  }
}

응답 필드

필드명 타입 설명
resultCode INT 처리 결과 코드 (아래 참조)
resultMsg STRING 처리 결과 메시지
data OBJECT 성공 시 사용자 정보 및 토큰 포함

data 필드 (성공 시)

필드명 타입 설명 매핑 DB 컬럼
userId INT 사용자 고유 ID user_id
token STRING 로그인 토큰 (세션용) -

응답 코드 정의

코드 메시지 설명
1000 SUCCESS 요청 성공
2001 EMAIL_EXISTS 회원가입 시 이메일 중복
2002 USER_NOT_FOUND 로그인 시 이메일 없음
2003 INVALID_PASSWORD 비밀번호 불일치
5000 INTERNAL_ERROR 서버 내부 오류

프로토콜별 전송 방식 예시

TCP / UDP

  • 소켓 통신으로 JSON 그대로 전송
  • 구분자: 개행(\n) 또는 길이 프레임

MQTT

항목 값
Topic user/auth
Payload 위 JSON 메시지

CoAP

항목 값
Method POST
URI coap://host/user/signup or user/login
Payload 위 JSON 메시지

Chat Message

개요

항목 내용
구분 채팅 메시지
목적 사용자 입력 메시지 전송 및 펫 응답 수신 + 저장 처리
데이터 형식 JSON
사용 프로토콜 TCP / UDP || CoAP / MQTT

공통 메시지 구조

{
  "command": "send_message",
  "payload": {
    "userId": 1,
    "messageId": 10,
    "message": "괜찮을까?",
    "timestamp": "2025-03-23 14:25:00",
    "videoId": 101,
    "videoPath": "/video/101.mp4",
    "videoStartTimestamp": "00:00:05.000",
    "videoEndTimestamp": "00:00:08.500",
    "voiceId": 201,
    "voicePath": "/voice/201.wav",
    "voiceStartTimestamp": "00:00:05.000",
    "voiceEndTimestamp": "00:00:08.500"
  }
}

요청 명세

공통 필드

필드명 타입 필수 설명 매핑 DB 컬럼
command STRING 예 "send_message" 명령 -

payload 필드

필드명 타입 필수 설명 매핑 DB 컬럼
userId INT 예 사용자 고유 ID user_id
messageId INT 예 채팅 메시지 고유 ID message_id
message STRING 예 사용자 입력 메시지 message
timestamp DATETIME 예 메시지 전송 시간 timestamp
videoId INT 옵션 동영상 ID video_id
videoPath STRING 옵션 동영상 경로 video_path
videoStartTimestamp STRING 옵션 동영상 시작 지점 (상대 timestamp) video_start_timestamp
videoEndTimestamp STRING 옵션 동영상 종료 지점 video_end_timestamp
voiceId INT 옵션 음성 ID voice_id
voicePath STRING 옵션 음성 파일 경로 voice_path
voiceStartTimestamp STRING 옵션 음성 시작 지점 voice_start_timestamp
voiceEndTimestamp STRING 옵션 음성 종료 지점 voice_end_timestamp

응답 명세

{
  "resultCode": 1000,
  "resultMsg": "SUCCESS",
  "data": {
    "chatId": 3001,
    "eId": 5,
    "petEmotion": "기분 좋아요",
    "replyMessage": "너무 잘하고 있어!"
  }
}

data 필드

필드명 타입 설명 매핑 DB 컬럼
chatId INT 채팅 세트 ID chat_id
eId INT 펫 감정 ID e_id
petEmotion STRING 분석된 펫 감정 텍스트 pet_emotion
replyMessage STRING 펫의 응답 메시지 reply_message

응답 코드 정의

코드 메시지 설명
1000 SUCCESS 채팅 저장 및 응답 성공
2001 USER_NOT_FOUND 사용자 ID 없음
2002 INVALID_MESSAGE 메시지 누락 또는 유효하지 않음
5000 INTERNAL_ERROR 서버 내부 오류

프로토콜별 전송 방식 예시

TCP / UDP

  • JSON 메시지 그대로 전송
  • 메시지 구분 방식: 개행 문자(\n) 또는 길이 prefix

MQTT

항목 값
Topic chat/message
Payload 위 JSON 메시지

CoAP

항목 값
Method POST
URI coap://host/chat/message
Payload 위 JSON 메시지

User Emotion Analysis Result

개요

항목 내용
구분 Emotion Result (사용자 감정 분석 결과)
목적 채팅 데이터를 기반으로 사용자 감정(얼굴/음성/텍스트) 분석 요청
데이터 형식 JSON
사용 프로토콜 TCP / UDP / CoAP / MQTT

공통 메시지 구조

{
  "command": "analyze_emotion",
  "payload": {
    "userId": 1,
    "chatId": 3001,
    "videoPath": "/video/101.mp4",
    "voicePath": "/voice/201.wav",
    "message": "괜찮을까?"
  }
}

요청 명세

공통 필드

필드명 타입 필수 설명 매핑 DB 컬럼
command STRING 예 "analyze_emotion" 명령 -

payload 필드

필드명 타입 필수 설명 매핑 DB 컬럼
userId INT 예 사용자 고유 ID user_id
chatId INT 예 채팅 세트 ID chat_id
videoPath STRING 예 사용자 영상 경로 video_path (참조 용도)
voicePath STRING 예 사용자 음성 경로 voice_path (참조 용도)
message STRING 예 사용자 채팅 텍스트 message (참조 용도)

응답 명세

{
  "resultCode": 1000,
  "resultMsg": "SUCCESS",
  "data": {
    "emotionId": 5001,
    "faceEmotion": "happy",
    "voiceEmotion": "calm",
    "textEmotion": "worried",
    "summary": "조금 걱정되지만 침착함",
    "time": "2025-03-23 14:26:00"
  }
}

data 필드

필드명 타입 설명 매핑 DB 컬럼
emotionId INT 감정 분석 고유 ID emotion_analysis_id
faceEmotion STRING 얼굴 표정 기반 감정 face_emotion
voiceEmotion STRING 음성 기반 감정 voice_emotion
textEmotion STRING 텍스트 기반 감정 text_emotion
summary STRING 통합 감정 해석 summary
time DATETIME 감정 분석 시각 time

응답 코드 정의

코드 메시지 설명
1000 SUCCESS 감정 분석 성공
2001 USER_NOT_FOUND 사용자 ID 없음
2002 CHAT_NOT_FOUND 채팅 ID 없음
2003 INVALID_INPUT message, 영상 또는 음성 누락
5000 INTERNAL_ERROR 서버 내부 오류

프로토콜별 전송 방식 예시

TCP / UDP

  • JSON 메시지 그대로 전송

MQTT

항목 값
Topic emotion/analyze
Payload 위 JSON 메시지

CoAP

항목 값
Method POST
URI coap://host/emotion/analyze
Payload 위 JSON 메시지

Pet Character Setting

개요

항목 내용
구분 사용자 맞춤형 펫 성격 설정
목적 펫의 말투, 성격, 응답 참고 정보 설정 및 조회
데이터 형식 JSON
사용 프로토콜 TCP / UDP / CoAP / MQTT

공통 메시지 구조

{
  "command": "set_character",
  "payload": {
    "userId": 1,
    "speech": "존댓말",
    "character": "내향적",
    "resSetting": "땅콩 알레르기 있음"
  }
}

또는

{
  "command": "get_character",
  "payload": {
    "userId": 1
  }
}

요청 명세

공통 필드

필드명 타입 필수 설명 매핑 DB 컬럼
command STRING 예 "set_character" 또는 "get_character" -

payload – set_character

필드명 타입 필수 설명 매핑 DB 컬럼
userId INT 예 사용자 고유 ID user_id
speech STRING 예 펫 말투 설정 speech
character STRING 예 펫 성격 설정 character
resSetting STRING 예 응답 시 참고할 정보 res_setting

payload – get_character

필드명 타입 필수 설명 매핑 DB 컬럼
userId INT 예 사용자 고유 ID user_id

응답 명세

{
  "resultCode": 1000,
  "resultMsg": "SUCCESS",
  "data": {
    "characterId": 1001,
    "speech": "존댓말",
    "character": "내향적",
    "resSetting": "땅콩 알레르기 있음"
  }
}

data 필드

필드명 타입 설명 매핑 DB 컬럼
characterId INT 성격 설정 고유 ID character_id
speech STRING 말투 설정 speech
character STRING 성격 설정 character
resSetting STRING 응답 참고 정보 res_setting

응답 코드 정의

코드 메시지 설명
1000 SUCCESS 처리 성공
2001 USER_NOT_FOUND 사용자 ID 없음
2002 INVALID_INPUT 필수값 누락 또는 잘못된 요청
5000 INTERNAL_ERROR 서버 내부 오류

프로토콜별 전송 방식 예시

TCP / UDP

  • JSON 그대로 전송 (구분자 또는 길이 기반 메시지 처리)

MQTT

항목 값
Topic pet/character
Payload 위 JSON 메시지

CoAP

항목 값
Method POST
URI coap://host/pet/character
Payload 위 JSON 메시지

Pet Training Setting

개요

항목 내용
구분 사용자 정의 펫 응답 훈련 설정
목적 명령어, 키워드, 제스처 기반으로 펫 응답 행동 훈련 설정 및 조회
데이터 형식 JSON
사용 프로토콜 TCP / UDP / CoAP / MQTT

공통 메시지 구조

{
  "command": "set_response",
  "payload": {
    "userId": 1,
    "trainingText": "날씨",
    "keywordText": "날씨, 하늘",
    "gestureVideoPath": "/gesture/weather.mp4",
    "gestureRecognitionId": 3101,
    "recognizedGesture": "오늘의 날씨 데이터 가져오기"
  }
}

또는

{
  "command": "get_response",
  "payload": {
    "userId": 1
  }
}

요청 명세

공통 필드

필드명 타입 필수 설명 매핑 DB 컬럼
command STRING 예 "set_response" 또는 "get_response" -

payload – set_response

필드명 타입 필수 설명 매핑 DB 컬럼
userId INT 예 사용자 고유 ID user_id
trainingText STRING 예 훈련시킬 명령어 training_text
keywordText STRING 예 관련 키워드 keyword_text
gestureVideoPath STRING 예 제스처 영상 경로 gesture_video_path
gestureRecognitionId INT 예 제스처 인식 결과 ID gesture_recognition_id
recognizedGesture STRING 예 인식된 제스처 설명 recognized_gesture

payload – get_response

필드명 타입 필수 설명 매핑 DB 컬럼
userId INT 예 사용자 고유 ID user_id

응답 명세

{
  "resultCode": 1000,
  "resultMsg": "SUCCESS",
  "data": {
    "responseSettingId": 7001,
    "trainingText": "날씨",
    "keywordText": "날씨, 하늘",
    "gestureVideoPath": "/gesture/weather.mp4",
    "gestureRecognitionId": 3101,
    "recognizedGesture": "오늘의 날씨 데이터 가져오기"
  }
}

data 필드

필드명 타입 설명 매핑 DB 컬럼
responseSettingId INT 훈련 설정 고유 ID training_setting_id
trainingText STRING 설정된 명령어 training_text
keywordText STRING 설정된 키워드 keyword_text
gestureVideoPath STRING 제스처 영상 경로 gesture_video_path
gestureRecognitionId INT 제스처 인식 결과 ID gesture_recognition_id
recognizedGesture STRING 인식된 제스처 설명 recognized_gesture

응답 코드 정의

코드 메시지 설명
1000 SUCCESS 처리 성공
2001 USER_NOT_FOUND 사용자 ID 없음
2002 INVALID_INPUT 필수 항목 누락 또는 형식 오류
5000 INTERNAL_ERROR 서버 내부 오류

프로토콜별 전송 방식 예시

TCP / UDP

  • JSON 메시지 전송 (길이 기반 또는 개행 구분)

MQTT

항목 값
Topic pet/training
Payload 위 JSON 메시지

CoAP

항목 값
Method POST
URI coap://host/pet/training
Payload 위 JSON 메시지

Gesture Event

개요

항목 내용
구분 Gesture Event (제스처 이벤트)
목적 감지된 제스처 정보를 서버에 전달
데이터 형식 JSON 또는 단문 문자열
사용 프로토콜 UDP

메시지 형식

1. JSON 메시지 예시

{
  "event": "gesture",
  "userId": "qpzja",
  "gesture": "wave",
  "trainingSettingId": 5001
}

2. 단문 문자열 예시 (옵션)

gesture|qpzja|wave|5001
  • 순서: 이벤트명 | 유저ID | 제스처명 | 훈련ID
  • 서버에서는 구분자(|) 기준으로 파싱

요청 필드 명세

필드명 타입 필수 설명 매핑 DB 컬럼
event STRING 예 "gesture" 고정 -
userId STRING 예 사용자 식별자
(User의 외부 식별자에 매핑 예정 시 고려 필요)		 -
gesture STRING 예 감지된 제스처 이름 recognized_gesture
trainingSettingId INT 예 훈련 설정 ID training_setting_id

User Setting

개요

항목 내용
구분 사용자 접근성/환경 설정
목적 사용자 글자 크기 등 설정 저장 및 조회
데이터 형식 JSON
사용 프로토콜 TCP / UDP / CoAP / MQTT

공통 메시지 구조

{
  "command": "set_setting",
  "payload": {
    "userId": 1,
    "fontSize": 18
  }
}

또는

{
  "command": "get_setting",
  "payload": {
    "userId": 1
  }
}

요청 명세

공통 필드

필드명 타입 필수 설명 매핑 DB 컬럼
command STRING 예 "set_setting" 또는 "get_setting" -

payload – set_setting

필드명 타입 필수 설명 매핑 DB 컬럼
userId INT 예 사용자 고유 ID user_id
fontSize INT 예 글자 크기 설정 font_size

payload – get_setting

필드명 타입 필수 설명 매핑 DB 컬럼
userId INT 예 사용자 고유 ID user_id

응답 명세

{
  "resultCode": 1000,
  "resultMsg": "SUCCESS",
  "data": {
    "settingId": 9001,
    "fontSize": 18
  }
}

data 필드

필드명 타입 설명 매핑 DB 컬럼
settingId INT 설정 고유 ID setting_id
fontSize INT 설정된 글자 크기 font_size

응답 코드 정의

코드 메시지 설명
1000 SUCCESS 설정 저장/조회 성공
2001 USER_NOT_FOUND 사용자 ID 없음
2002 INVALID_INPUT 필수 항목 누락 또는 형식 오류
5000 INTERNAL_ERROR 서버 내부 오류

프로토콜별 전송 방식 예시

TCP / UDP

  • JSON 메시지 그대로 전송

MQTT

항목 값
Topic user/setting
Payload 위 JSON 메시지

CoAP

항목 값
Method POST
URI coap://host/user/setting
Payload 위 JSON 메시지

Log

개요

항목 내용
구분 사용자 행위 및 시스템 이벤트 로그 기록
목적 사용자 활동, 오류, 시스템 상태 등의 로그 저장
데이터 형식 JSON
사용 프로토콜 TCP / UDP / CoAP / MQTT

공통 메시지 구조

{
  "command": "write_log",
  "payload": {
    "userId": 1,
    "logType": "emotion_analysis",
    "timestamp": "2025-03-23 14:30:00",
    "detail": "감정 분석 완료",
    "location": "mobile_app",
    "deviceInfo": "iPhone 14, iOS 17.2",
    "errorCode": "E2001",
    "ipAddress": "192.168.0.15"
  }
}

요청 명세

공통 필드

필드명 타입 필수 설명 매핑 DB 컬럼
command STRING 예 "write_log" -

payload – write_log

필드명 타입 필수 설명 매핑 DB 컬럼
userId INT 예 사용자 고유 ID user_id
logType STRING 예 로그 유형 log_type
timestamp DATETIME 예 로그 발생 시각 timestamp
detail STRING 예 로그 상세 메시지 detail
location STRING 예 로그 발생 위치 location
deviceInfo STRING 예 디바이스 정보 device_info
errorCode STRING or null 아니오 오류 코드 error_code
ipAddress STRING 예 IP 주소 ip_address

응답 명세

{
  "resultCode": 1000,
  "resultMsg": "SUCCESS",
  "data": {
    "logId": 8001,
    "errorCode": "E2001",
    "ipAddress": "192.168.0.15",
    "deviceInfo": "iPhone 14, iOS 17.2"
  }
}

data 필드

필드명 타입 설명 매핑 DB 컬럼
logId INT 생성된 로그 고유 ID log_id
errorCode STRING or null 저장된 오류 코드 error_code
ipAddress STRING 저장된 IP 주소 ip_address
deviceInfo STRING 저장된 디바이스 정보 device_info

응답 코드 정의

코드 메시지 설명
1000 SUCCESS 로그 저장 성공
2001 USER_NOT_FOUND 사용자 ID 없음
2002 INVALID_INPUT 필수값 누락 또는 오류
5000 INTERNAL_ERROR 서버 내부 오류

프로토콜별 전송 방식 예시

TCP / UDP

  • JSON 메시지 전송

MQTT

항목 값
Topic system/log
Payload 위 JSON 메시지

CoAP

항목 값
Method POST
URI coap://host/system/log
Payload 위 JSON 메시지

Video Stream

개요

항목 내용
구분 실시간 영상 스트림 전송
목적 클라이언트가 요청한 영상 스트림을 서버가 전송
데이터 형식 요청/응답: JSON, 스트림: Binary (JPEG)
사용 프로토콜 UDP

요청 명세

1. 스트림 시작 요청

{
  "command": "get_video_stream",
  "videoId": 101,
  "quality": "high",
  "fps": 15
}
필드명 타입 필수 설명
command STRING 예 "get_video_stream" 명령
videoId INT 예 영상 고유 ID
quality STRING 예 영상 품질 (low / medium / high)
fps INT 예 초당 프레임 수

2. 스트림 종료 요청

{
  "command": "stop_stream",
  "videoId": 101
}
필드명 타입 필수 설명
command STRING 예 "stop_stream" 명령
videoId INT 예 종료할 영상 ID

응답 명세 (스트림 시작 시)

{
  "resultCode": 1000,
  "resultMsg": "SUCCESS",
  "data": {
    "streamPort": 5005,
    "protocol": "UDP",
    "format": "JPEG",
    "quality": "high",
    "fps": 15
  }
}
필드명 타입 설명
streamPort INT 영상 스트림 전송 포트
protocol STRING "UDP" 고정
format STRING "JPEG" 고정
quality STRING 요청된 품질 수준
fps INT 초당 프레임 수

데이터 전송 (UDP 스트림)

항목 내용
포맷 JPEG 인코딩된 이미지 바이너리
예시 cv2.imencode('.jpg', frame)[1].tobytes()
전송 설정된 streamPort로 UDP 전송

DB 컬럼 매핑

필드명 매핑 DB 컬럼
videoId Chat.video_id
videoPath Chat.video_path
videoStartTimestamp Chat.video_start_timestamp
videoEndTimestamp Chat.video_end_timestamp

참고 사항

  • quality에 따라 JPEG 압축률 및 해상도 조절됨

    • low: 320x240 (저해상도, 빠른 전송)
    • medium: 640x480 (중간 품질)
    • high: 1280x720 이상 (고화질)

  • stop_stream 명령 수신 시 스트리밍 중단

  • UDP 특성상 일부 프레임 손실 가능 (복구 불가)

Audio Stream

개요

항목 내용
구분 실시간 오디오 스트림 전송 (마이크 입력)
목적 클라이언트 요청에 따라 오디오 스트림 전송
데이터 형식 요청/응답: JSON, 스트림: Binary (PCM/MP3)
사용 프로토콜 UDP

요청 명세

1. 스트림 시작 요청

{
  "command": "get_audio_stream",
  "audioId": 201,
  "codec": "pcm",
  "sampleRate": 16000,
  "channels": 1,
  "chunkSize": 1024
}
필드명 타입 필수 설명
command STRING 예 "get_audio_stream" 명령
audioId INT 예 오디오 스트림 고유 ID
codec STRING 예 오디오 코덱 ("pcm", "mp3")
sampleRate INT 예 샘플링 레이트 (Hz)
channels INT 예 채널 수 (1 = mono, 2 = stereo)
chunkSize INT 예 오디오 버퍼 크기 (byte 단위)

2. 스트림 종료 요청

{
  "command": "stop_stream",
  "audioId": 201
}
필드명 타입 필수 설명
command STRING 예 "stop_stream" 명령
audioId INT 예 종료할 오디오 ID

응답 명세 (스트림 시작 시)

{
  "resultCode": 1000,
  "resultMsg": "SUCCESS",
  "data": {
    "streamPort": 5010,
    "protocol": "UDP",
    "codec": "pcm",
    "sampleRate": 16000,
    "channels": 1,
    "chunkSize": 1024
  }
}
필드명 타입 설명
streamPort INT 오디오 스트림 전송 포트
protocol STRING "UDP" 고정
codec STRING 설정된 오디오 코덱
sampleRate INT 설정된 샘플링 레이트 (Hz)
channels INT 설정된 채널 수
chunkSize INT 설정된 오디오 버퍼 크기

데이터 전송 (UDP 스트림)

항목 내용
포맷 PCM 버퍼 또는 MP3 프레임
예시 data = mic.read(1024)
전송 설정된 streamPort로 UDP 전송

DB 컬럼 매핑

필드명 매핑 DB 컬럼
audioId Chat.voice_id
voicePath Chat.voice_path
voiceStartTimestamp Chat.voice_start_timestamp
voiceEndTimestamp Chat.voice_end_timestamp

참고 사항

  • PCM: 압축되지 않은 원시(raw) 오디오, 지연이 적고 실시간 재생에 적합
  • MP3: 압축률이 높으나 디코딩 과정 필요
  • stop_stream 명령 수신 시 해당 스트림 즉시 종료
  • UDP 특성상 일부 패킷 손실 가능 (복구 불가)
  • 클라이언트는 수신 데이터를 실시간 재생 또는 저장 가능

Clone this wiki locally