버전: 개발 버전 (최신)

[DEPRECATED] 전체 회차 결과 조회 API

DEPRECATED API

이 API는 더 이상 사용되지 않습니다. GET /questionnaires/rounds/cumulative-results를 이용

대신 누적 결과 조회 API를 roundNumber 파라미터 없이 사용하세요:

새로운 엔드포인트: GET /questionnaires/rounds/cumulative-results
사용법: Query Parameter 없이 호출하면 모든 회차 결과를 반환합니다.

이 문서는 하위 호환성을 위해 유지되지만, 새로운 개발에서는 사용하지 마세요.

사용자 전체 회차 결과 조회 API는 사용자의 모든 완료된 회차에 대한 설문 결과를 조회합니다. 최종 보고서 생성이나 전체 진행 상황 분석 시 사용됩니다.

주의사항

사용자가 참여하지 않은 설문: 사용자가 완료하지 않은 설문의 경우 해당 설문 정보는 undefined로 제공됩니다.
존재하지 않는 회차: 시스템에 정의되지 않은 회차가 있는 경우 HTTP 404 에러가 발생합니다.
최종 회차까지: 사용자의 번들에 정의된 최종 회차까지의 모든 결과를 반환합니다.

사용자 전체 회차 결과 조회

사용자의 모든 완료된 회차에 대한 설문 결과를 조회합니다.

HTTP Method: GET
Path: /questionnaires/users/me/results/all-rounds
인증: Access Token 필요 (Authorization: Bearer {accessToken})

Headers

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

Query Parameters

이 API는 Query Parameter를 사용하지 않습니다. 사용자의 모든 완료된 회차 결과를 반환합니다.

Responses

HTTP Status Code	설명	Error Code(s)
`200 OK`	전체 회차 결과 조회 성공	-
`401 Unauthorized`	인증 실패	`2051`
`404 Not Found`	리소스 없음 (사용자 상태, 번들, 회차)	`7008`, `9010`, `9031`, `9051`
`422 Unprocessable Entity`	잘못된 회차 번호	`9056`
`500 Internal Server Error`	서버 내부 오류	`9000`, `9500`

200 OK - 전체 회차 결과 조회 성공

성공적으로 전체 회차 결과를 조회하면 사용자의 모든 완료된 회차 설문 결과가 반환됩니다.

{
  "userId": "user_abc_123",
  "requestedRoundNumber": 5,
  "allRounds": [
    {
      "id": "round_123",
      "roundNumber": 1,
      "questionnaireResponses": [
        {
          "id": "q_isi123",
          "type": "ISI",
          "title": "불면증 심각도 지수",
          "score": {
            "calculationType": "SUM",
            "range": {
              "min": {
                "value": 0
              },
              "max": {
                "value": 28
              }
            },
            "userScore": 18,
            "level": {
              "id": "sl_isi3",
              "range": {
                "min": {
                  "value": 15
                },
                "max": {
                  "value": 21
                }
              },
              "label": "중간 정도의 불면증",
              "chartLabel": "수면 불량",
              "description": "중등도의 불면 증상이 나타날 수 있습니다.",
              "feedback": "중등도의 불면 증상이 나타날 수 있습니다. 의료 전문가의 도움이 필요한 상황입니다."
            }
          },
          "completedAt": 1711929600000,
          "completedDayIndex": 12
        }
      ]
    },
    {
      "id": "round_456",
      "roundNumber": 2,
      "questionnaireResponses": [
        {
          "id": "q_isi456",
          "type": "ISI",
          "title": "불면증 심각도 지수",
          "score": {
            "calculationType": "SUM",
            "range": {
              "min": {
                "value": 0
              },
              "max": {
                "value": 28
              }
            },
            "userScore": 16,
            "level": {
              "id": "sl_isi3",
              "range": {
                "min": {
                  "value": 15
                },
                "max": {
                  "value": 21
                }
              },
              "label": "중간 정도의 불면증",
              "chartLabel": "수면 불량",
              "description": "중등도의 불면 증상이 나타날 수 있습니다.",
              "feedback": "중등도의 불면 증상이 나타날 수 있습니다. 의료 전문가의 도움이 필요한 상황입니다."
            }
          },
          "completedAt": 1712534400000,
          "completedDayIndex": 19
        }
      ]
    },
    {
      "id": "round_789",
      "roundNumber": 3,
      "questionnaireResponses": [
        {
          "id": "q_isi789",
          "type": "ISI",
          "title": "불면증 심각도 지수",
          "score": {
            "calculationType": "SUM",
            "range": {
              "min": {
                "value": 0
              },
              "max": {
                "value": 28
              }
            },
            "userScore": 12,
            "level": {
              "id": "sl_isi2",
              "range": {
                "min": {
                  "value": 8
                },
                "max": {
                  "value": 14
                }
              },
              "label": "약간의 불면증",
              "chartLabel": "수면 양호",
              "description": "경미한 불면 증상이 나타날 수 있습니다.",
              "feedback": "수면 상태가 개선되고 있습니다. 현재 수준을 유지하세요."
            }
          },
          "completedAt": 1713139200000,
          "completedDayIndex": 26
        }
      ]
    },
    {
      "id": "round_890",
      "roundNumber": 4,
      "questionnaireResponses": [
        {
          "id": "q_isi890",
          "type": "ISI",
          "title": "불면증 심각도 지수",
          "score": {
            "calculationType": "SUM",
            "range": {
              "min": {
                "value": 0
              },
              "max": {
                "value": 28
              }
            },
            "userScore": 8,
            "level": {
              "id": "sl_isi2",
              "range": {
                "min": {
                  "value": 8
                },
                "max": {
                  "value": 14
                }
              },
              "label": "약간의 불면증",
              "chartLabel": "수면 양호",
              "description": "경미한 불면 증상이 나타날 수 있습니다.",
              "feedback": "수면 상태가 지속적으로 개선되고 있습니다."
            }
          },
          "completedAt": 1713744000000,
          "completedDayIndex": 33
        }
      ]
    },
    {
      "id": "round_901",
      "roundNumber": 5,
      "questionnaireResponses": [
        {
          "id": "q_isi901",
          "type": "ISI",
          "title": "불면증 심각도 지수",
          "score": {
            "calculationType": "SUM",
            "range": {
              "min": {
                "value": 0
              },
              "max": {
                "value": 28
              }
            },
            "userScore": 5,
            "level": {
              "id": "sl_isi1",
              "range": {
                "min": {
                  "value": 0
                },
                "max": {
                  "value": 7
                }
              },
              "label": "정상",
              "chartLabel": "수면 우수",
              "description": "정상적인 수면 상태입니다.",
              "feedback": "수면 상태가 매우 개선되었습니다. 현재 관리 방법을 지속하세요."
            }
          },
          "completedAt": 1714348800000,
          "completedDayIndex": 40
        }
      ]
    }
  ]
}

필드	타입	설명	예시	필수 (Yes/No)
`userId`	string	사용자 ID	`"user_abc_123"`	Yes
`requestedRoundNumber`	integer	최종 회차 번호 (자동 결정됨)	`5`	Yes
`allRounds`	`RoundSummaryDto[]`	1회차부터 최종 회차까지의 모든 회차 정보	-	Yes
`allRounds[].id`	string	회차 ID	`"round_123"`	Yes
`allRounds[].roundNumber`	integer	회차 번호	`1`	Yes
`allRounds[].questionnaireResponses`	`QuestionnaireResponseInRoundDto[]`	해당 회차의 설문 응답 목록	-	Yes

설문 응답 객체 (QuestionnaireResponseInRoundDto) 필드:

필드	타입	설명	예시	필수 (Yes/No)
`id`	string	설문 ID	`"q_isi123"`	Yes
`type`	string	설문 타입	`"ISI"`	Yes
`title`	string	설문 제목	`"불면증 심각도 지수"`	Yes
`score`	`QuestionnaireScoreSectionDto`	점수 관련 정보 (점수가 없으면 undefined)	-	No
`score.calculationType`	string	점수 계산 유형 (SUM, AVERAGE, WEIGHTED)	`"SUM"`	Yes (score가 있을 때)
`score.range`	`RangeDto`	설문지 전체 점수 범위	-	No
`score.range.min`	`RangeValueDto`	설문지 최소 점수	`{"value": 0.0}`	Yes (range가 있을 때)
`score.range.max`	`RangeValueDto`	설문지 최대 점수	`{"value": 28.0}`	Yes (range가 있을 때)
`score.userScore`	float	사용자 점수	`18.0`	No
`score.level`	`ScoreLevelDto`	점수 구간 정보 (구간이 없으면 undefined)	-	No
`score.level.id`	string	점수 구간 ID	`"sl_isi3"`	Yes (level이 있을 때)
`score.level.range`	`RangeDto`	점수 구간 범위	-	Yes (level이 있을 때)
`score.level.range.min`	`RangeValueDto`	구간 최소 점수	`{"value": 15.0}`	Yes (level range가 있을 때)
`score.level.range.max`	`RangeValueDto`	구간 최대 점수	`{"value": 21.0}`	Yes (level range가 있을 때)
`score.level.label`	string	점수 구간 라벨	`"중간 정도의 불면증"`	No
`score.level.chartLabel`	string	차트용 라벨	`"수면 불량"`	No
`score.level.description`	string	점수 구간 설명	`"중등도의 불면 증상..."`	No
`score.level.feedback`	string	피드백 메시지	`"의료 전문가의 도움..."`	No
`completedAt`	integer	완료 시간 (Unix timestamp in milliseconds, Kotlin: `Long`, Swift: `Int64`, 완료하지 않았으면 undefined)	`1711929600000`	No
`completedDayIndex`	integer	완료 일자 인덱스 (사이클 시작일로부터, 완료하지 않았으면 undefined)	`12`	No

401 Unauthorized - 인증 실패

{
  "code": 2051,
  "message": "INVALID_TOKEN",
  "detail": "토큰이 유효하지 않습니다"
}

404 Not Found - 리소스 없음

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

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

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

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

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

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

예시: 사용자 회차 요약을 찾을 수 없음 (9051)

{
  "code": 9051,
  "message": "USER_ROUND_SUMMARY_NOT_FOUND",
  "detail": "사용자의 회차 요약 데이터를 찾을 수 없습니다"
}

422 Unprocessable Entity - 잘못된 회차 번호

{
  "code": 9056,
  "message": "INVALID_ROUND_NUMBER",
  "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의 getAllRoundsResults 메서드의 로직을 기반으로 합니다.
주요 처리 단계 (서비스 로직 내):
1. 사용자 상태 조회: 사용자의 활성 사이클 ID와 현재 진행 상태 조회 (getUserState)
2. 최종 회차 결정: 사용자 번들의 최종 회차를 자동으로 결정
3. 전체 응답 조회: GetUserAllRoundsQuestionnaireResultsQuery를 통해 모든 회차의 설문 응답 조회
4. 데이터 변환: 조회된 결과를 CumulativeQuestionnaireResultsDto 형태로 변환
조회 범위: 사용자의 설문 번들에 정의된 1회차부터 최종 회차까지의 모든 완료된 설문 결과를 반환합니다.
에러 처리: 회차 정의 조회 실패 시 더 이상 fallback 처리를 하지 않고 명확한 에러를 반환합니다.
점수 정보: 각 설문 응답에는 사용자 점수, 점수 구간 정보, 피드백 등이 포함됩니다. 점수가 계산되지 않은 설문의 경우 score 필드가 undefined로 제공됩니다.
시간 정보: 설문 완료 시점(completedAt)과 사용자 사이클 기준 완료 일자(completedDayIndex)를 제공합니다. 완료하지 않은 설문의 경우 두 필드 모두 undefined로 제공됩니다.
누락된 회차: 사용자가 참여하지 않은 회차의 경우 해당 회차 정보가 allRounds 배열에서 제외됩니다.
최종 회차 자동 결정: requestedRoundNumber는 사용자 번들의 최종 회차 번호로 자동 설정됩니다.
Accept-Language 헤더를 통해 조회 언어를 지정할 수 있으며, 기본값은 'de-DE'입니다.

사용 예시

예시: 사용자의 모든 회차 결과 조회

GET /questionnaires/users/me/results/all-rounds
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Accept-Language: ko-KR

DTO 상세 설명

CumulativeQuestionnaireResultsDto

사용자 전체 회차 결과 조회 API의 응답 DTO입니다.

필드	타입	설명	필수 (Yes/No)
`userId`	string	사용자 ID	Yes
`requestedRoundNumber`	integer	요청한 회차 번호 (최종 회차)	Yes
`allRounds`	`RoundSummaryDto[]`	1회차부터 최종 회차까지의 모든 회차 정보	Yes

RoundSummaryDto

회차별 설문 응답 정보를 담는 DTO입니다.

필드	타입	설명	필수 (Yes/No)
`id`	string	회차 ID	Yes
`roundNumber`	integer	회차 번호	Yes
`questionnaireResponses`	`QuestionnaireResponseInRoundDto[]`	해당 회차의 설문 응답 목록	Yes

QuestionnaireResponseInRoundDto

개별 설문 응답 정보를 담는 DTO입니다.

필드	타입	설명	필수 (Yes/No)
`id`	string	설문 ID	Yes
`type`	string	설문 타입	Yes
`title`	string	설문 제목	Yes
`score`	`QuestionnaireScoreSectionDto`	점수 관련 정보 (점수가 없으면 undefined)	No
`completedAt`	integer	완료 시간 (Unix timestamp in milliseconds, Kotlin: `Long`, Swift: `Int64`, 완료하지 않았으면 undefined)	No
`completedDayIndex`	integer	완료 일자 인덱스 (사이클 시작일로부터, 완료하지 않았으면 undefined)	No

QuestionnaireScoreSectionDto

설문 점수 관련 정보를 담는 DTO입니다.

필드	타입	설명	필수 (Yes/No)
`calculationType`	string	점수 계산 유형 (SUM, AVERAGE, WEIGHTED)	Yes
`range`	`RangeDto`	설문지 전체 점수 범위	No
`userScore`	float	사용자 점수	No
`level`	`ScoreLevelDto`	점수 구간 정보 (구간이 없으면 undefined)	No

RangeDto

점수 범위 정보를 담는 DTO입니다.

필드	타입	설명	필수 (Yes/No)
`min`	`RangeValueDto`	최소값	Yes
`max`	`RangeValueDto`	최대값	Yes

RangeValueDto

범위 값 정보를 담는 DTO입니다.

필드	타입	설명	필수 (Yes/No)
`value`	float	값	Yes
`label`	string	라벨	No

ScoreLevelDto

점수 구간 정보를 담는 DTO입니다.

필드	타입	설명	필수 (Yes/No)
`id`	string	점수 구간 ID	Yes
`range`	`RangeDto`	범위	Yes
`label`	string	라벨	No
`chartLabel`	string	차트 라벨	No
`description`	string	점수 구간 설명	No
`feedback`	string	피드백	No

활용 사례

최종 보고서 생성: 사용자의 전체 치료 과정과 진행 상황에 대한 종합 보고서 작성
전체 진행 분석: 1회차부터 최종 회차까지의 점수 변화 추이 분석
치료 효과 평가: 전체 치료 과정에서의 개선 정도와 효과성 측정
완료 인증서: 모든 회차를 완료한 사용자에 대한 완료 증명서 발급
데이터 내보내기: 사용자 요청 시 개인 데이터 전체 내보내기 (GDPR 준수)

누적 결과 조회 API와의 차이점

구분	누적 결과 조회 API	전체 회차 결과 조회 API
엔드포인트	`/rounds/cumulative-results`	`/users/me/results/all-rounds`
Query Parameter	`roundNumber` (선택적)	없음
조회 범위	지정된 회차까지	사용자 번들의 모든 회차
회차 결정	사용자 지정 또는 현재 최대 회차	번들의 최종 회차 자동 결정
주요 용도	진행 중 상황 확인, 중간 분석	최종 보고서, 완료 후 전체 분석
requestedRoundNumber	사용자가 요청한 회차 또는 현재 최대 회차	번들의 최종 회차

변경 이력

버전	날짜	작성자	변경 내용
0.1.0	2025-06-30	elizabeth@weltcorp.com	최초 문서 작성
0.2.0	2025-07-03	elizabeth@weltcorp.com	API deprecated 상태로 변환

사용자 전체 회차 결과 조회​

Headers​

Query Parameters​

Responses​

설명​

사용 예시​

DTO 상세 설명​

CumulativeQuestionnaireResultsDto​

RoundSummaryDto​

QuestionnaireResponseInRoundDto​

QuestionnaireScoreSectionDto​

RangeDto​

RangeValueDto​

ScoreLevelDto​

활용 사례​

누적 결과 조회 API와의 차이점​

변경 이력​