버전: 개발 버전 (최신)

회차 완료 API

⚠️ DEPRECATED API

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

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

회차 완료

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

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

Headers

Header	Type	Description	Required
`Content-Type`	`application/json`	요청 본문 형식을 지정합니다.	Yes
`Authorization`	string	Bearer 토큰 형식의 JWT 액세스 토큰이 필요합니다.	Yes
`Accept-Language`	string	조회 언어 (허용 형식: de-DE, en-US, ko-KR)	No

Path Parameters

Parameter	Type	Description	Example
`roundId`	string	완료할 회차 ID	`round_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)
`success`	boolean	회차 완료 성공 여부	`true`	Yes

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'입니다.
회차 완료 시 관련 도메인 이벤트가 발행되어 다른 서비스에서 후속 처리를 할 수 있습니다.

번들 검증 프로세스

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

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

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

변경 이력

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

회차 완료​

Headers​

Path Parameters​

Request Body​

Responses​

설명​

번들 검증 프로세스​

변경 이력​