본문으로 건너뛰기
버전: 0.68.0

회차 완료 API

⚠️ DEPRECATED API

이 API는 더 이상 사용되지 않습니다.

회차 완료 API는 사용자가 특정 설문 회차의 모든 설문을 완료했을 때, 해당 회차를 완료 상태로 변경합니다.

회차 완료​

특정 설문 회차를 완료 처리합니다.

  • HTTP Method: POST
  • Path: /questionnaires/rounds/:roundId/complete
  • 인증: Access Token 필요 (Authorization: Bearer {accessToken})

Headers​

HeaderTypeDescriptionRequired
Content-Typeapplication/json요청 본문 형식을 지정합니다.Yes
AuthorizationstringBearer 토큰 형식의 JWT 액세스 토큰이 필요합니다.Yes
Accept-Languagestring조회 언어 (허용 형식: de-DE, en-US, ko-KR)No

Path Parameters​

ParameterTypeDescriptionExample
roundIdstring완료할 회차 IDround_456

Request Body​

회차 완료 요청에는 별도의 request body가 필요하지 않습니다. 사용자 정보는 Authorization header의 access token에서 추출됩니다.

Request body는 비어있거나 빈 객체입니다:

Responses​

HTTP Status Code설명Error Code(s)
200 OK회차 완료 성공-
400 Bad Request잘못된 요청 (회차 미완료, 번들 불일치)9050, 9012
401 Unauthorized인증 실패2051
404 Not Found리소스 없음 (회차, 사용자 주기, 번들)9031, 7008, 9010
410 Gone회차 진행 기간 만료9055
412 Precondition Failed전제 조건 실패 (회차 시작 전)9054
422 Unprocessable Entity데이터 일관성 오류9034
500 Internal Server Error서버 내부 오류9000, 9500
200 OK - 회차 완료 성공

성공적으로 회차를 완료하면 단순한 성공 응답이 반환됩니다.

{
  "success": true
}
필드타입설명예시필수 (Yes/No)
successboolean회차 완료 성공 여부trueYes
400 Bad Request - 회차 미완료
{
  "code": 9050,
  "message": "ROUND_INCOMPLETE",
  "detail": "회차의 모든 설문이 완료되지 않았습니다"
}

이 오류는 회차에 속한 모든 설문이 COMPLETED 상태가 아닐 때 발생합니다.

400 Bad Request - 번들과 회차 불일치
{
  "code": 9012,
  "message": "ROUND_BUNDLE_MISMATCH",
  "detail": "요청한 회차가 사용자의 설문 번들에 포함되지 않습니다"
}

이 오류는 사용자의 설문 번들에 요청한 회차의 설문지들이 포함되지 않을 때 발생합니다.

401 Unauthorized - 인증 실패
{
  "code": 2051,
  "message": "INVALID_TOKEN",
  "detail": "토큰이 유효하지 않습니다"
}
404 Not Found - 리소스 없음

예시: 회차를 찾을 수 없음 (9031)

{
  "code": 9031,
  "message": "QUESTIONNAIRE_ROUND_NOT_FOUND",
  "detail": "설문지 회차를 찾을 수 없습니다"
}

예시: 사용자 활성 주기를 찾을 수 없음 (7008)

{
  "code": 7008,
  "message": "USER_STATE_NOT_FOUND",
  "detail": "사용자의 활성 주기를 찾을 수 없습니다"
}

예시: 설문 번들을 찾을 수 없음 (9010)

{
  "code": 9010,
  "message": "QUESTIONNAIRE_BUNDLE_NOT_FOUND",
  "detail": "설문지 번들을 찾을 수 없습니다"
}
410 Gone - 회차 진행 기간 만료
{
  "code": 9055,
  "message": "ROUND_EXPIRED",
  "detail": "해당 회차 진행 기간이 만료되었습니다"
}

이 오류는 사용자의 현재 진행 일차가 해당 회차의 마감일을 초과했을 때 발생합니다.

412 Precondition Failed - 회차 시작 전
{
  "code": 9054,
  "message": "ROUND_NOT_STARTED",
  "detail": "아직 해당 회차 진행 기간이 시작되지 않았습니다"
}

이 오류는 사용자의 현재 진행 일차가 해당 회차의 시작일에 도달하지 않았을 때 발생합니다.

422 Unprocessable Entity - 데이터 일관성 오류
{
  "code": 9034,
  "message": "QUESTIONNAIRE_ROUND_DATA_INCONSISTENCY",
  "detail": "회차 데이터에 일관성 오류가 발생했습니다"
}

이 오류는 회차 데이터에 일관성 문제가 있어 요청을 처리할 수 없을 때 발생합니다.

500 Internal Server Error - 서버 내부 오류

일반적인 서버 오류 (9000)

{
  "code": 9000,
  "message": "SERVER_ERROR",
  "detail": "서버 내부 오류"
}

데이터베이스 접근 오류 (9500)

{
  "code": 9500,
  "message": "REPOSITORY_ERROR",
  "detail": "데이터베이스 접근 중 오류가 발생했습니다"
}

이 오류들은 처리 중 예기치 않은 서버 내부 문제나 데이터베이스 접근 문제가 발생했을 때 반환됩니다.

설명​

  • 이 API는 apps/dta-wide-api/src/app/questionnaire/services/questionnaire-round.service.ts의 completeRound 메서드의 로직을 기반으로 합니다.
  • 주요 처리 단계 (서비스 로직 내):
    1. 번들 검증: 사용자의 모바일 설정에서 bundleId 조회 및 요청된 회차가 해당 번들에 포함되는지 검증 (validateUserBundleAndRound)
    2. 사용자 상태 조회: 사용자의 활성 사이클 ID 조회 (getUserState)
    3. 회차 기간 검증: CompleteQuestionnaireRoundHandler에서 사용자의 currentDayIndex를 기반으로 회차 진행 가능 기간 검증 (validateRoundTiming)
    4. 회차 완료 처리: CompleteQuestionnaireRoundCommand를 통한 회차 완료 처리 및 이벤트 발행
  • 보안 검증: 사용자가 자신에게 할당된 설문 번들의 회차만 완료할 수 있도록 번들-회차 일치성을 검증합니다.
  • Accept-Language 헤더를 통해 처리 언어를 지정할 수 있으며, 기본값은 'de-DE'입니다.
  • 회차 완료 시 관련 도메인 이벤트가 발행되어 다른 서비스에서 후속 처리를 할 수 있습니다.

번들 검증 프로세스​

회차 완료 전에 다음과 같은 검증이 수행됩니다:

  1. 사용자 모바일 설정 조회: GetUserMobileSettingsQuery를 통해 사용자의 questionnaireBundleId 조회
  2. 번들 존재 확인: GetQuestionnaireBundleByIdQuery를 통해 해당 번들이 존재하는지 확인
  3. 회차 정보 조회: GetRoundWithQuestionnairesQuery를 통해 요청된 회차의 설문지 목록 조회
  4. 일치성 검증: 회차의 모든 설문지가 사용자의 번들에 포함되어 있는지 확인

이 검증을 통해 사용자가 다른 번들의 회차를 완료하려는 시도를 방지합니다.

변경 이력​

버전날짜작성자변경 내용
0.1.02025-06-12elizabeth@weltcorp.com최초 문서 작성
0.2.02025-06-20elizabeth@weltcorp.com숫자 타입 명시 (integer/float), score 관련 float 적용
0.3.02025-06-23elizabeth@weltcorp.comDTO 파일과 일치하도록 score 필드 구조 수정, maxPossible 필드 추가
0.4.02025-06-26elizabeth@weltcorp.com번들 검증 로직 추가, 응답 구조 단순화, 새로운 에러 코드 추가
0.5.02025-07-03elizabeth@weltcorp.comAPI 폐기 예정 공지 - 개별 설문 완료 API 사용 권장