본문으로 건너뛰기
버전: 개발 버전 (최신)

설문 스케줄 조회 API

설문 스케줄 조회 API는 사용자의 다음 진행할 설문 스케줄을 조회하는 기능을 제공합니다. 모바일 클라이언트에서 사용자의 설문 진행 상태를 확인하고, 어떤 설문을 진행해야 하는지 또는 어떤 안내를 해야 하는지에 대한 정보를 조회할 수 있습니다.

사용자 다음 진행할 설문 스케줄 조회​

사용자의 현재 dayIndex를 기준으로 설문 진행 상태를 확인하고, 어떤 설문을 진행해야 하는지 정보를 제공합니다.

  • HTTP Method: GET
  • Path: /v1/questionnaires/users/me/schedule/next-pending/latest
  • 인증: Access Token 필요 (Authorization: Bearer {accessToken})

Headers​

HeaderTypeDescriptionRequired
AuthorizationstringBearer 토큰 형식의 JWT 액세스 토큰 (userId 자동 추출)Yes
Accept-Languagestring조회 언어 (de-DE 기본값, en-US, ko-KR)Yes

Responses​

HTTP Status Code설명Error Code(s)
200 OK설문 스케줄 조회 성공-
401 Unauthorized인증 실패2010
404 Not Found설문 번들 또는 사용자 스케줄 정보 없음9010, 9052
500 Internal Server Error서버 내부 오류9000
200 OK - 설문 스케줄 조회 성공

설문 스케줄 조회가 성공하면 사용자의 현재 진행 상태에 따라 다른 응답이 반환됩니다.

시나리오 1: 진행할 설문이 있는 경우 - 스킵 불가능한 회차

{
  "userId": "user_abc_123",
  "bundleId": "bundle_questionnaire_2024_v1",
  "currentRound": {
    "id": "round_xyz_456",
    "roundNumber": 1,
    "isSkippable": false,
    "questionnaires": [
      {
        "id": "q_dbas123",
        "type": "DBAS16",
        "orderIndex": 0
      },
      {
        "id": "q_phq9_123",
        "type": "PHQ9",
        "orderIndex": 3
      }
    ]
  }
}

시나리오 2: 진행할 설문이 있는 경우 - 스킵 가능한 회차

{
  "userId": "user_abc_123",
  "bundleId": "bundle_questionnaire_2024_v1",
  "currentRound": {
    "id": "round_xyz_456",
    "roundNumber": 2,
    "isSkippable": true,
    "remainingSkipDays": 0,
    "questionnaires": [
      {
        "id": "q_dbas123",
        "type": "DBAS16",
        "orderIndex": 0
      },
      {
        "id": "q_phq9_123",
        "type": "PHQ9",
        "orderIndex": 3
      }
    ]
  }
}

시나리오 3: 회차 기간 만료 후 대기 & 중간 회차 완료 후 대기 상태

{
  "userId": "user_abc_123",
  "bundleId": "bundle_questionnaire_2024_v1",
  "remainingDaysToNext": 12
}

시나리오 4: 최종 회차 완료

{
  "userId": "user_abc_123",
  "bundleId": "bundle_questionnaire_2024_v1"
}
필드타입설명예시필수 (Yes/No)
userIdstring사용자 IDuser_abc_123Yes
bundleIdstring번들 IDbundle_questionnaire_2024_v1Yes
remainingDaysToNextinteger다음 설문까지 남은 일수 (진행할 설문이 없을 때)12No
currentRoundobject현재 회차 정보 (CurrentRoundDto)No
currentRound.idstring회차 IDround_xyz_456Yes
currentRound.roundNumberinteger회차 번호2Yes
currentRound.isSkippableboolean스킵 가능 여부trueYes
currentRound.remainingSkipDaysinteger스킵 가능한 남은 일수 (유효기간 경과 시 undefined)0No
currentRound.questionnairesarray해당 회차의 미완료 설문들 (ScheduleQuestionnaireDto[])Yes
questionnaires[].idstring설문 IDq_dbas123Yes
questionnaires[].typestring설문 유형 (QuestionnaireType)DBAS16Yes
questionnaires[].orderIndexinteger정렬 순서0Yes
401 Unauthorized - 인증 실패
{
  "code": 2010,
  "message": "UNAUTHORIZED",
  "detail": "로그인이 필요합니다."
}
404 Not Found - 리소스 없음

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

{
  "code": 9010,
  "message": "QUESTIONNAIRE_BUNDLE_NOT_FOUND",
  "detail": "설문지 번들을 찾을 수 없습니다"
}

예시: 사용자 설문 스케줄 정보 없음 (9052)

{
  "code": 9052,
  "message": "USER_QUESTIONNAIRE_SCHEDULE_NOT_FOUND",
  "detail": "사용자의 설문 스케줄을 찾을 수 없습니다"
}
401 Unauthorized - 인증 실패
{
  "code": 2051,
  "message": "INVALID_TOKEN",
  "detail": "토큰이 유효하지 않습니다"
}
404 Not Found - 설문 스케줄 정보 없음
{
  "code": 9052,
  "message": "USER_QUESTIONNAIRE_SCHEDULE_NOT_FOUND",
  "detail": "사용자의 설문 스케줄을 찾을 수 없습니다"
}
500 Internal Server Error - 서버 내부 오류
{
  "code": 9000,
  "message": "SERVER_ERROR",
  "detail": "서버 내부 오류"
}

설명​

  • 이 API는 apps/dta-wide-api/src/app/questionnaire/services/questionnaire-schedule.service.ts의 getUserNextPendingSchedule 메서드의 로직을 기반으로 합니다.
  • 주요 비즈니스 로직:
    1. Bundle 유효성 검증 (최신 번들 여부 확인)
    2. 사용자 상태 기반 설문 스케줄 계산
    3. 라운드 완료 상태 및 미완료 설문 필터링
    4. Round 1 특별 처리 (완료할 때까지 진행 불가)
    5. Final Round 지속 제공 로직
  • JWT 토큰에서 사용자 ID가 자동으로 추출되어 사용됩니다 (req.user).
  • API 호출 예시: GET /v1/questionnaires/users/me/schedule/next-pending/latest
  • 클라이언트는 이 API를 통해 다음과 같은 정보를 얻을 수 있습니다:
    • 유저의 현재 dayIndex에 진행해야 할 설문 목록
    • 다음 설문이 언제 시작되는지
    • 설문 번들 업데이트가 필요한지
  • 응답의 questionnaires 배열이 비어있으면 현재 진행할 설문이 없다는 의미입니다.

응답 시나리오 상세 설명​

1. 진행할 설문이 있는 경우 - 스킵 불가능한 회차​

  • currentRound.questionnaires 배열에 미완료 설문 정보가 포함됩니다.
  • isSkippable이 false이므로 사용자는 반드시 설문을 완료해야 합니다.
  • 나중에 하기가 불가능하므로 remainingSkipDays 필드는 포함되지 않습니다.
  • 클라이언트는 설문 진행 UI를 표시하고 스킵 옵션을 제공하지 않습니다.

2. 진행할 설문이 있는 경우 - 스킵 가능한 회차​

  • currentRound.questionnaires 배열에 미완료 설문 정보가 포함됩니다.
  • isSkippable이 true이고 remainingSkipDays에 스킵 가능한 남은 일수가 포함됩니다.
  • 클라이언트는 설문 진행 UI와 함께 스킵 옵션을 제공할 수 있습니다.

3. 중간 회차 완료 후 대기 상태​

  • currentRound 정보가 포함되지 않습니다.
  • 현재 회차의 모든 설문을 완료했고, 다음 회차 시작까지 기다리는 상태입니다.
  • remainingDaysToNext에 다음 회차까지 남은 일수가 포함됩니다.
  • 클라이언트는 완료 메시지와 함께 다음 설문 시작일을 안내할 수 있습니다.

4. 최종 회차 완료​

  • currentRound 정보가 포함되지 않습니다.
  • 모든 설문 프로그램을 완료한 상태로, 더 이상 진행할 설문이 없습니다.
  • remainingDaysToNext 필드는 포함되지 않습니다 (다음 설문이 없으므로).
  • 클라이언트는 모든 설문 완료 메시지를 표시할 수 있습니다.

5. 회차 기간 만료 후 대기​

  • currentRound 정보가 포함되지 않습니다.
  • 현재 회차 참여 기간이 지났지만, 다음 회차가 아직 시작되지 않은 상태입니다.
  • remainingDaysToNext에 다음 회차 시작까지 남은 일수가 포함됩니다.
  • 클라이언트는 대기 화면과 함께 다음 설문 시작일을 안내할 수 있습니다.

UserQuestionnaireScheduleResponseDto 상세​

설문 스케줄 응답 정보를 담는 DTO에 대한 상세 설명입니다.

필드타입설명예시필수 (Yes/No)
userIdstring사용자 IDuser_abc_123Yes
bundleIdstring번들 IDbundle_questionnaire_2024_v1Yes
remainingDaysToNextinteger다음 설문까지 남은 일수 (진행할 설문이 없을 때)5No
currentRoundobject현재 회차 정보CurrentRoundDtoNo

CurrentRoundDto 상세​

현재 회차 정보를 담는 DTO에 대한 상세 설명입니다.

필드타입설명예시필수 (Yes/No)
idstring회차 IDround_xyz_456Yes
roundNumberinteger회차 번호2Yes
isSkippableboolean스킵 가능 여부falseYes
remainingSkipDaysinteger스킵 가능한 남은 일수 (유효기간 경과 시 undefined)5No
questionnairesarray해당 회차의 미완료 설문들ScheduleQuestionnaireDto[]Yes

ScheduleQuestionnaireDto 상세​

스케줄된 설문 정보를 담는 DTO에 대한 상세 설명입니다.

필드타입설명예시필수 (Yes/No)
idstring설문 IDq_dbas123Yes
typestring설문 유형 (QuestionnaireType 참조)DBAS16Yes
orderIndexinteger정렬 순서0Yes

변경 이력​

버전날짜작성자변경 내용
0.1.02025-11-14dalia@weltcorp.com최초 문서 작성