버전: 개발 버전 (최신)

환자 리포트 조회 API

참고: 이 문서에 설명된 모든 API는 dta-wir-medi-api 애플리케이션에 구현되어 있습니다. (Go)

개요

환자 리포트 조회 API는 환자의 치료 진행 상황, 수면 기록, 설문 결과 등을 종합적으로 조회하는 기능을 제공합니다.

주요 기능

환자 리포트 조회: 인증된 사용자의 환자 리포트 조회
외부 토큰으로 환자 리포트 조회: 외부 액세스 토큰을 사용한 환자 리포트 조회

[GET] v1/users/{userId}/reports - 환자 리포트 조회

환자 리포트 조회

[클라이언트 수정 필요]
asis: /v1/patients/user-cycles/{userCycleId}/reports
tobe: /v1/users/{userId}/reports

특정 환자의 종합 리포트를 조회합니다.

HTTP Method: GET
인증: 액세스 토큰 (accessToken) 필요

Headers

Header	Type	Description	Required
Authorization	Bearer {accessToken}	사용자 인증을 통해 발급받은 액세스 토큰 입니다.	✔

Path Parameters

필드	타입	설명	Required
userId	number	사용자 ID	✔

Request 예시

GET /v1/users/123/reports

Responses

Http Status Code	설명	Error Code(s)
200 `OK`	조회 성공	-
400 `Bad Request`	잘못된 요청	`BAD_REQUEST` (40000)
401 `Unauthorized`	인증 실패	`UNAUTHORIZED` (40100)
404 `Not Found`	환자 미발견	`NOT_FOUND` (40400)
500 `Internal Server Error`	서버 내부 오류	`INTERNAL_SERVER_ERROR` (50000)

200 OK - 성공

{
  "period": {
    "startDate": "2024-01-01",
    "endDate": "2024-03-31"
  },
  "patient": {
    "name": "홍길동",
    "email": "patient@example.com",
    "phoneNumber": "01012345678",
    "birthdate": "1990-01-01",
    "accesscode": "ABC123",
    "accesscodeCreatedAt": "2024-01-01T09:00:00Z",
    "siteId": 1,
    "accountId": 10,
    "accountName": "김의사",
    "day": 15,
    "status": 1,
    "lastLogin": "2024-01-20T10:00:00Z",
    "startedAt": "2024-01-10T09:00:00Z",
    "endAt": "2024-04-10T09:00:00Z",
    "memo": "특이사항 없음",
    "medicalRegistrationNumber": "MRN-001"
  },
  "sleeps": {
    "2024-01-15": {
      "diary": {
        "dns": false,
        "lot": 1380,
        "ast": 1410,
        "aet": 450,
        "waso": 30,
        "pill": false,
        "nap": 0,
        "sleepQuality": 4,
        "tst": 420,
        "se": 93.3,
        "dse": 1,
        "sol": 30,
        "timezoneId": "Asia/Seoul",
        "timezoneOffset": 540
      },
      "goal": {
        "targetDate": "2024-01-15",
        "durationInMinutes": 450,
        "lot": 1380,
        "aet": 450,
        "timezoneId": "Asia/Seoul",
        "timezoneOffset": 540,
        "typeId": 1
      }
    }
  },
  "questionnaires": {
    "ISI": [
      {
        "completed": true,
        "score": 12,
        "maxScore": 28,
        "round": 1
      }
    ],
    "WIQ": [],
    "PHQ9": [
      {
        "completed": true,
        "score": 5,
        "maxScore": 27,
        "round": 1
      }
    ],
    "GAD7": [
      {
        "completed": true,
        "score": 3,
        "maxScore": 21,
        "round": 1
      }
    ],
    "ESS": [],
    "DBAS": [
      {
        "completed": true,
        "score": 5.5,
        "maxScore": 10,
        "round": 1
      }
    ]
  },
  "summary": {
    "treatmentProgress": {
      "currentDay": 15,
      "totalUsageDays": 15
    },
    "sleepRecord": {
      "count": 14,
      "appUsageDays": 15,
      "percentage": 93.3
    },
    "lotSuccess": {
      "count": 12,
      "appUsageDays": 15,
      "percentage": 80.0
    },
    "aetSuccess": {
      "count": 13,
      "appUsageDays": 15,
      "percentage": 86.7
    }
  }
}

Response 구조

period (조회 기간)

필드	타입	설명
startDate	string	시작 날짜
endDate	string	종료 날짜

patient (환자 정보)

필드	타입	설명
name	string	환자 이름
email	string	이메일
phoneNumber	string	전화번호
birthdate	string	생년월일
accesscode	string	액세스 코드
accesscodeCreatedAt	string	액세스 코드 생성일
siteId	number	사이트 ID
accountId	number	담당 의료진 계정 ID
accountName	string	담당 의료진 이름
day	number	치료 일차
status	number	환자 상태
lastLogin	string	마지막 로그인
startedAt	string	치료 시작일
endAt	string	치료 종료일
memo	string	메모
medicalRegistrationNumber	string	의무 등록 번호

sleeps (수면 기록)

날짜를 키로 하는 맵 형태로 제공됩니다. 각 날짜별로 수면 일지(diary)와 수면 목표(goal) 정보를 포함합니다.

diary (수면 일지):

필드	타입	설명
dns	boolean	Did Not Sleep (수면하지 않음)
lot	number	Lights Out Time (소등 시각, 분 단위)
ast	number	Actual Sleep Time (실제 수면 시각)
aet	number	Actual End Time (실제 기상 시각)
waso	number	Wake After Sleep Onset (중간 각성)
pill	boolean	수면제 복용 여부
nap	number	낮잠 시간 (분)
sleepQuality	number	수면 질 평가 (1-5)
tst	number	Total Sleep Time (총 수면 시간, 분)
se	number	Sleep Efficiency (수면 효율, %)
dse	number	Daily Sleep Efficiency
sol	number	Sleep Onset Latency (입면 잠복기)
timezoneId	string	타임존 ID
timezoneOffset	number	타임존 오프셋 (분)

goal (수면 목표):

필드	타입	설명
targetDate	string	목표 날짜
durationInMinutes	number	목표 수면 시간 (분)
lot	number	목표 소등 시각
aet	number	목표 기상 시각
timezoneId	string	타임존 ID
timezoneOffset	number	타임존 오프셋 (분)
typeId	number	수면 목표 타입 ID

questionnaires (설문 결과)

각 설문 타입별로 배열 형태로 제공됩니다.

설문 타입:

ISI: Insomnia Severity Index (불면증 심각도 지수)
WIQ: Work and Health Interview Questionnaire
PHQ9: Patient Health Questionnaire-9 (우울증)
GAD7: Generalized Anxiety Disorder-7 (불안장애)
ESS: Epworth Sleepiness Scale
DBAS: Dysfunctional Beliefs and Attitudes about Sleep

일반 설문 항목 (ISI, WIQ, PHQ9, GAD7, ESS):

필드	타입	설명
completed	boolean	완료 여부
score	number	점수 (optional)
maxScore	number	최대 점수
round	number	회차

DBAS 설문 항목:

필드	타입	설명
completed	boolean	완료 여부
score	number	점수 (소수점, optional)
maxScore	number	최대 점수
round	number	회차

summary (요약 정보)

treatmentProgress (치료 진행):

필드	타입	설명
currentDay	number	현재 치료 일차
totalUsageDays	number	총 앱 사용 일수

sleepRecord (수면 기록 통계):

필드	타입	설명
count	number	수면 기록 횟수
appUsageDays	number	앱 사용 일수
percentage	number	수면 기록 비율 (%)

lotSuccess (소등 시각 준수 통계):

필드	타입	설명
count	number	소등 시각 준수 횟수
appUsageDays	number	앱 사용 일수
percentage	number	소등 시각 준수 비율 (%)

aetSuccess (기상 시각 준수 통계):

필드	타입	설명
count	number	기상 시각 준수 횟수
appUsageDays	number	앱 사용 일수
percentage	number	기상 시각 준수 비율 (%)

400 Bad Request - 잘못된 요청

{
  "status": 400,
  "code": 40000,
  "message": "잘못된 요청입니다."
}

401 Unauthorized - 인증 실패

{
  "status": 401,
  "code": 40100,
  "message": "UNAUTHORIZED"
}

404 Not Found - 환자 미발견

{
  "status": 404,
  "code": 40400,
  "message": "환자 정보를 찾을 수 없습니다."
}

500 Internal Server Error - 서버 내부 오류

{
  "status": 500,
  "code": 50000,
  "message": "INTERNAL_SERVER_ERROR"
}

[GET] /v1/users/{userId}/reports/external - 외부 토큰으로 환자 리포트 조회

외부 토큰으로 환자 리포트 조회

[클라이언트 수정 필요]
asis: /v1/patients/user-cycles/{userCycleId}/reports/external
tobe: /v1/users/{userId}/reports/external

외부 액세스 토큰을 사용하여 환자 리포트를 조회합니다. 일반 인증 토큰이 아닌 별도의 외부 액세스 토큰으로 인증합니다.

HTTP Method: GET
인증: 외부 액세스 토큰 (token) 필요

Query Parameters

필드	타입	설명	Required
token	string	외부 액세스 토큰	✔

Path Parameters

필드	타입	설명	Required
userId	number	사용자 ID	✔

Request 예시

GET /v1/users/123/reports/external?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Responses

Http Status Code	설명	Error Code(s)
200 `OK`	조회 성공	-
400 `Bad Request`	잘못된 요청	`BAD_REQUEST` (40000)
401 `Unauthorized`	인증 실패	`UNAUTHORIZED` (40100)
404 `Not Found`	환자 미발견	`NOT_FOUND` (40400)
500 `Internal Server Error`	서버 내부 오류	`INTERNAL_SERVER_ERROR` (50000)

200 OK - 성공

응답 형식은 일반 환자 리포트 조회와 동일합니다.

토큰 검증 로직:

외부 액세스 토큰의 유효성 검증
토큰의 타입이 MD_ACCESS 타입인지 확인
토큰의 sub (subject) 클레임이 요청한 userCycleId와 일치하는지 확인

400 Bad Request - 잘못된 요청

{
  "status": 400,
  "code": 40000,
  "message": "잘못된 요청입니다."
}

발생 가능한 에러 메시지:

"잘못된 요청입니다." - 토큰이 제공되지 않음
"유효하지 않은 토큰 정보 입니다." - 토큰의 sub 클레임이 없거나 userCycleId와 불일치

401 Unauthorized - 인증 실패

{
  "status": 401,
  "code": 40100,
  "message": "UNAUTHORIZED"
}

토큰이 만료되었거나 유효하지 않은 경우 발생합니다.

404 Not Found - 환자 미발견

{
  "status": 404,
  "code": 40400,
  "message": "환자 정보를 찾을 수 없습니다."
}

500 Internal Server Error - 서버 내부 오류

{
  "status": 500,
  "code": 50000,
  "message": "INTERNAL_SERVER_ERROR"
}

토큰 타입

타입	설명	사용처
MD_ACCESS	의료진 대시보드 외부 액세스 토큰	외부 시스템 연동

개요​

주요 기능​

환자 리포트 조회

Headers​

Path Parameters​

Request 예시​

Responses​

Response 구조​

period (조회 기간)​

patient (환자 정보)​

sleeps (수면 기록)​

questionnaires (설문 결과)​

summary (요약 정보)​

외부 토큰으로 환자 리포트 조회

Query Parameters​

Path Parameters​

Request 예시​

Responses​

토큰 타입​

개요

주요 기능

Headers

Path Parameters

Request 예시

Responses

Response 구조

period (조회 기간)

patient (환자 정보)

sleeps (수면 기록)

questionnaires (설문 결과)

summary (요약 정보)

Query Parameters

Path Parameters

Request 예시

Responses

토큰 타입