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

환자 메모 관리 API

참고: 이 문서에 설명된 모든 API는 dta-wi-mono 모노레포의 dta-wi-medi-api 애플리케이션에 구현되어 있습니다.

개요​

환자 메모 관리 API는 의료진이 환자에 대한 메모를 작성하고 업데이트하는 기능을 제공합니다.

주요 기능​

  • 환자 메모 업데이트: 환자 메모 생성 및 업데이트 (Upsert)
[PUT] /v1/user-management/app-users/{appUserId}/memo - 환자 메모 업데이트

환자 메모 업데이트

특정 환자의 메모를 생성하거나 업데이트합니다. 메모가 없으면 새로 생성하고, 이미 있으면 기존 메모를 업데이트합니다 (Upsert).

✅ 1.4 Migration 완료​

⚠️ 변경 사항​

주의: 이전 버전에서 다음 사항이 변경되었습니다. 클라이언트 코드 수정이 필요합니다.

엔드포인트 변경​

  • asis: PUT /v1/patients/user-cycles/{userCycleId}/memo (Go API)
  • tobe: PUT /v1/user-management/app-users/{appUserId}/memo (TypeScript API)

변경된 path 파라미터​

항목LegacyCurrent
Path ParameteruserCycleId (number)userId (string UUID)
식별 방식App User 의 UserCycle ID로 식별App User 의 User ID로 식별 (활성 UserCycle 자동 조회)
  • HTTP Method: GET
  • 인증: 액세스 토큰 (accessToken) 필요

Headers​

HeaderTypeDescriptionRequired
AuthorizationBearer {accessToken}사용자 인증을 통해 발급받은 액세스 토큰 입니다.✔
Content-Typeapplication/json요청 본문 형식✔

Path Parameters​

필드타입설명Required
appUserIdstring사용자 UUID✔

Request Body​

필드타입설명Required
memostring메모 내용 (최대 2000자)✔

Request Body 예시​

{
  "memo": "환자가 수면제 복용을 중단했습니다. 지속적인 관찰이 필요합니다."
}

Responses​

Http Status Code설명Error Code(s)
200 OK메모 업데이트 성공-
400 Bad Request잘못된 요청1001
401 Unauthorized인증 실패1080
403 Forbidden권한 없음1081
404 Not Found환자 미발견1040
500 Internal Server Error서버 내부 오류1000
200 OK - 성공
{
  "success": true
}
필드타입설명
successboolean성공 여부

Upsert 동작:

  • 해당 userId, UserCycle 에 대한 메모가 없으면 새로 생성
  • 메모가 이미 있으면 기존 메모를 새로운 내용으로 업데이트
  • createdBy 필드에 요청자(의료진) ID 자동 기록
400 Bad Request - 잘못된 요청
{
  "status": 400,
  "code": 1001,
  "message": "Bad Request",
  "detail": "요청한 정보가 유효하지 않습니다.",
  "errors": [
    {
      "field": "memo",
      "message": "memo must be less than 2000 characters"
    }
  ]
}

발생 가능한 에러 메시지:

  • "memo is required" - memo 필드가 비어있거나 누락됨
  • "memo must be less than 2000 characters" - 메모 길이 초과
  • "Invalid userId format" - 유효하지 않은 userId UUID 형식
401 Unauthorized - 인증 실패
{
  "statusCode": 401,
  "code": 1080,
  "message": "UNAUTHORIZED",
  "detail": "인증되지 않은 요청입니다"
}

액세스 토큰이 유효하지 않거나 만료된 경우 발생합니다.

403 Forbidden - 권한 없음
{
  "statusCode": 403,
  "code": 1081,
  "message": "FORBIDDEN",
  "detail": "권한이 없습니다"
}

해당 요청에 대한 접근 권한이 없는 경우 발생합니다.

404 Not Found - 환자 미발견
{
  "statusCode": 404,
  "code": 1040,
  "message": "NOT_FOUND",
  "detail": "유효하지 않은 사용자입니다."
}

해당 userId에 해당하는 환자가 존재하지 않거나, 활성 UserCycle이 없는 경우 발생합니다.

500 Internal Server Error - 서버 내부 오류
{
  "statusCode": 500,
  "code": 1000,
  "message": "Internal Server Error",
  "detail": "서버 내부 오류가 발생했습니다."
}

사용 사례​

메모 작성 예시​

초기 진료 메모:

{
  "memo": "초진 상담 완료. 환자는 만성 불면증을 호소하며, 수면제 복용 이력이 있습니다. CBT-i 프로그램 시작을 권장했습니다."
}

경과 관찰 메모:

{
  "memo": "Day 15 진행 중. 수면 효율이 80%에서 90%로 개선되었습니다. 환자의 순응도가 높아 치료 진행이 원활합니다."
}

특이사항 메모:

{
  "memo": "환자가 개인 사정으로 인해 1주일간 앱 사용을 중단했습니다. 재개 후 수면 패턴 변화를 면밀히 모니터링 필요."
}

권한 및 보안​

  • 접근 권한: 해당 환자를 담당하는 의료진 또는 관리자만 메모를 작성/수정할 수 있습니다.
  • 개인정보 보호: 메모에는 민감한 의료 정보가 포함될 수 있으므로, GDPR 및 개인정보보호법을 준수해야 합니다.
  • 감사 추적: 메모의 생성 및 수정 이력이 시스템에 기록됩니다.

메모 작성 가이드라인​

  1. 객관적 기록: 관찰한 사실과 데이터를 객관적으로 기록합니다.
  2. 간결성: 핵심 내용을 간결하게 작성합니다.
  3. 날짜 명시: 특정 사건이나 관찰 내용에는 날짜를 명시합니다.
  4. 전문 용어 사용: 의학적으로 정확한 용어를 사용합니다.
  5. 개인정보 주의: 불필요한 개인 식별 정보는 기록하지 않습니다.