CS Arena API 문서

요약

도메인	기능	Method	URL (Base: /api/v1)	설명
인증	로그인	POST	/auth/signin	이메일/비번으로 토큰 발급
	회원가입	POST	/auth/signup	신규 유저 등록 및 자동 로그인
학습	세션 생성	POST	/sessions	주제/난이도 설정 후 방 생성
	세션 정보	GET	/sessions/{sessionId}	현재 진행 중인 세션 상태 조회
	질문 조회	GET	/sessions/{sessionId}/questions	현재 풀어야 할 문제 조회
	답변 제출	POST	/sessions/{sessionId}/answers	답안 제출 및 다음 문제 트리거
아카이브	기록 목록	GET	/users/{userId}/questions	내가 푼 문제 리스트 (최신순)
	상세 기록	GET	/users/{userId}/questions/{questionId}/answers	특정 문제의 내 풀이 히스토리

프론트 라우팅

페이지 이름	프론트 URL	연결된 API 기능	비고
로그인	/auth/signin	POST /auth/signin	로그인 성공 시 메인(/)으로 이동
회원가입	/auth/signup	POST /auth/signup	가입 성공 시 메인(/)으로 이동
메인 홈	/	(추후 유저 정보 조회 등)	사이드바 포함된 기본 화면
세션 설정	/interview/setup	POST /sessions	주제, 난이도 선택 화면
실전 인터뷰	/interview/:sessionId	GET /sessions/{id}/questions POST /sessions/{id}/answers	핵심 화면. 질문 표시 및 답변 입력
결과 화면	/interview/:sessionId/result	(추후 결과 조회 API 필요 가능성 있음)	모든 질문 종료 후 이동
문제 목록	/archive	GET /users/{myId}/questions	푼 문제 리스트 (카드 형태 등)
히스토리 상세	/archive/:questionId	GET /users/{myId}/questions/{qid}/answers	특정 문제 클릭 시 이동. 과거 내 답변 내역 확인

인증

로그인 API

1. 기본 정보

• URL: /api/v1/auth/signin
• Method: POST
• 설명: 사용자의 이메일과 비밀번호를 받아 액세스 토큰을 발급합니다.

2. 요청 (Request)

Headers

• Content-Type: application/json

Body

파라미터	타입	필수	설명
email	String	Y	사용자 이메일
password	String	Y	사용자 비밀번호

예시 코드

{
  "email": "user@example.com",
  "password": "password123"
}

3. 응답 (Response)

성공 (200 OK)

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUz..."
	}
}

실패 (400 Bad Request)

• message: “비밀번호가 일치하지 않습니다.”

회원가입 API

1. 기본 정보

• URL: /api/v1/auth/signup
• Method: POST
• 설명: 신규 사용자를 등록하고 초기 포인트를 지급합니다.

2. 요청 (Request)

Body

파라미터	타입	필수	설명
email	String	Y	사용자 이메일
password	String	Y	사용자 비밀번호 (최소 8자)
nickname	String	Y	사용자 닉네임

예시 코드

{
  "email": "newuser@example.com",
  "password": "password123",
  "nickname": "코딩하는고양이"
}

3. 응답 (Response)

성공 (201 Created)

{
  "success": true,
  "data": {
    "userId": 1,
    "email": "newuser@example.com",
    "accessToken": "eyJhbGciOiJIUz...", // 바로 로그인 처리
    "message": "회원가입이 완료되었습니다."
  }
}

실패 (400 Bad Request)

• message: “이미 존재하는 이메일입니다.”

2. 학습세션

면접 생성 API

1. 기본 정보

• URL: /api/v1/sessions
• Method: POST
• 설명: 주제와 난이도, 배팅 포인트를 설정하여 새로운 면접 세션을 생성합니다.

2. 요청 (Request)

Headers

• Authorization: Bearer {accessToken}

Body

파라미터	타입	필수	설명
category	String	Y	면접 주제 (예: “CS”, “Frontend”)
difficulty	String	Y	난이도 (“EASY”, “NORMAL”, “HARD”)
bettingPoint	Number	N	걸고 싶은 포인트 (기본값: 0)

예시 코드

{
  "category": "CS",             // DB: category
  "mode": "STUDY",          // DB: mode ('STUDY' or 'BATTLE')
  "difficulty": "NORMAL",       // DB: difficulty (질문 필터링용)
  "targetQuestionCount": 10,    // DB: target_question_count
  "bettingPoint": 10,
  "autoPass": true,
  "timerSetting": 60,           // DB: timer_setting
  "opponentId": null,            // (선택) 배틀일 경우 상대방 ID
}

3. 응답 (Response)

성공 (201 Created)

{
  "success": true,
  "data": {
    "sessionId": 105, // DB: study_sessions.id 
    "message": "세션이 생성되었습니다."
  }
}

실패 (400 Bad Request)

• message: “보유 포인트가 부족하여 배팅할 수 없습니다.”

---

면접 정보 조회 API

1. 기본 정보

• URL: /api/v1/sessions/{sessionId}
• Method: GET
• 설명: 면접 세션 정보를 가져옵니다.

2. 요청 (Request)

Headers

• Authorization: Bearer {accessToken}

3. 응답 (Response)

성공 (201 Created)

{
  "success": true,
  "data": {
    "sessionId": 105,
    "category": "OS", 
    "difficulty": "NORMAL",
    "mode": "STUDY",
	"bettingPoint": 10,
	"targetQuestionCount": 10,
	"currentSequence": 3,
	"autoPass": true,
	"timerSetting": 60,
	"opponentId": null
  }
}

실패 (400 Bad Request)

• message: “존재하지 않는 면접 세션입니다.”

질문 요청 API

1. 기본 정보

• URL: /api/v1/sessions/{sessionId}/questions
• Method: GET
• 설명: 현재 인터뷰에 해당하는 질문을 정보를 조회합니다.

2. 요청 (Request)

Headers

• Authorization: Bearer {accessToken}

3. 응답 (Response)

성공 (200 OK) - 질문이 남았을 때

{
  "success": true,
  "data": {
    "status": "ONGOING",
    "questionId": 105,
    "question": "멀티 스레드 환경의 문제점은?",
    "type": "SHORT_ANSWER",              // DB: questions.type
    "details": null,                     // 객관식이면 보기 배열 포함
    
    // 진행 상황 표시용
    "currentSequence": 3,                // solved_question_count + 1
    "targetQuestionCount": 10,
    "timer": 60
  },
  "error": null
}

성공 (200 OK) - 면접 종료 시

{
  "success": true,
  "data": {
    "status": "COMPLETED",
    "resultSessionId": 105, // 결과 페이지로 이동시키기 위함
    "message": "모든 질문이 완료되었습니다."
  }
}

실패 (400 Bad Request)

• message: “존재하지 않는 면접 세션입니다.”

답변 제출 API

1. 기본 정보

• URL: /api/v1/sessions/{sessionId}/answers
• Method: POST
• 설명: 사용자의 답변(텍스트/음성)을 저장하고 AI의 다음 질문을 받아옵니다.

2. 요청 (Request)

Headers

• Authorization: Bearer {accessToken}

Body

파라미터	타입	필수	설명
questionId	Number	Y	질문 id
answerContent	String	Y	사용자의 답변 텍스트
currentSequence	Number	Y	현재 몇 번째 질문인지 (1, 2…)

예시 코드

{
  "questionId": 201,
  "content": "데드락이 발생할 수 있습니다.", // 사용자가 쓴 답
  "elapsedTime": 15,                     // 사용자가 쓴 시간 (초 단위)
  "currentSequence": 3,
}

3. 응답 (Response)

**성공 (200 OK)

{
  "success": true,
  "data": {
    "message":  "답변이 완료 되었습니다."   
    "score": 0 // (면접은 Async라 0일 수 있고, 배틀은 즉시 100/0 나옴)
  }
}

---

3. 기록 보관소 (Archive)

기록 목록 조회 API

1. 기본 정보

• URL: `/api/v1/users/{userId}/questions?answered=true
• Method: GET
• 설명: 사용자가 완료한 과거 질문 리스트를 최신순으로 조회합니다.

2. 요청 (Request)

Headers

• Authorization: Bearer {accessToken}

Query Parameter

• page: 페이지 번호 (기본: 1)

3. 응답 (Response)

성공 (200 OK)

{
  "success": true,
  "data": {
    "list": [
      {
        "questionId": 105,           // 클릭 시 이 ID를 들고 상세 페이지로 이동
        "category": "CS",
        "questionContent": "프로세스와 스레드의 차이는?",
        "mode": "STUDY",
        "difficulty": "NORMAL",
		"type": "LONG_ANSWER",
		"details": null,
        
        // [최신 풀이 정보 요약]
        "lastAnswerId": 505,         // 가장 최근 답변 ID
        "lastScore": 90,             // 가장 최근 점수 (성장했는지 확인용)
        "lastAnsweredAt": "2026-01-23T18:00:00",
        
        // [핵심] 몇 번 도전했는지 표시 (UX 포인트!)
        "attemptCount": 3            // "3번의 풀이 기록이 있습니다" 배지 표시용
      },
      {
        "questionId": 102,
        "category": "NETWORK",
        "questionContent": "TCP와 UDP의 차이?",
        "mode": "STUDY",
        "difficulty": "NORMAL",
        "type": "LONG_ANSWER",
        "details": null
    
        "lastAnswerId": 501,
        "lastScore": 50,             // 아직 점수가 낮음 (복습 필요)
        "lastAnsweredAt": "2026-01-22T10:00:00",
        "attemptCount": 1
      }
    ],
    "totalCount": 2 // 유니크한 질문 개수
  }
}

---

질문에 대한 답변 조회 API

1. 기본 정보

• URL: /api/v1/users/{userId}/questions/{questionsId}/answers
• Method: GET
• 설명: 특정 면접의 질문, 내 답변, 그리고 AI 피드백을 상세 조회합니다.

2. 요청 (Request)

Headers

• Authorization: Bearer {accessToken}

3. 응답 (Response)

성공 (200 OK)

{
  "success": true,
  "data": {
    "question": {
	    "id": 105,
        "category": "CS",
        "questionContent": "프로세스와 스레드의 차이는?",
        "mode": "STUDY",
        "difficulty": "NORMAL",
		"type": "LONG_ANSWER",
		"details": null,
    },
    "history": [ // 최신순 정렬
      {
        "answerId": 505,
        "content": "프로세스는 독립적이고 스레드는 공유합니다...",
        "score": 90,
        "feedbackContent": "완벽합니다! 저번보다 훨씬 좋아졌네요.",
        "elapsedTime": 30,
        "answeredAt": "2026-01-23T18:00:00" // 오늘 푼 것
      },
      {
        "answerId": 402,
        "content": "프로세스는 실행 중인 프로그램입니다.",
        "score": 50,
        "feedbackContent": "스레드에 대한 설명이 누락되었습니다.",
        "elapsedTime": 15,
        "answeredAt": "2026-01-20T14:00:00" // 3일 전 푼 것 (과거 기록)
      },
      {
        "answerId": 301,
        "content": "잘 모르겠습니다.",
        "score": 0,
        "feedbackContent": "학습이 필요합니다.",
        "elapsedTime": 5,
        "answeredAt": "2026-01-10T09:00:00" // 처음 푼 것
      }
    ]
  }
}