앱 사용자 관리 API

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

개요

앱 사용자 관리 API는 환자(앱 사용자)의 조회 기능을 제공합니다.

주요 기능

• 앱 사용자 목록 조회: 페이징, 정렬, 검색이 가능한 앱 사용자 목록 조회

[GET] /v1/user-management/app-users - 앱 사용자 목록 조회

앱 사용자 목록 조회

특정 사이트(병원)의 앱 사용자(환자) 목록을 조회합니다.

✅ 1.4 Migration 완료

⚠️ 변경 사항

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

엔드포인트 변경

• asis: /v1/users (Go API)
• tobe: /v1/user-management/app-users (TypeScript API)

변경된 필드

• siteId: 요청 파라미터 타입이 string (UUID)으로 변경되었습니다. (이전: number)
• sortBy: 파라미터 값이 snake_case에서 camelCase로 변경되었습니다. (예: created_at → createdAt)
• status: enum 값이 문자열로 변경되었습니다. (예: 1 → "ACTIVE")
• groupId: 단일 값에서 groupIds 배열로 변경 및 타입이 string으로 변경되었습니다. (이전 number)
• searchBy: 검색 기준 필드 (name, email)가 추가되었습니다. searchKey와 함께 사용하여 검색 대상을 지정할 수 있습니다.

삭제된 필드

• accesscode: 응답에서 제거되었습니다.
• accesscodeCreatedAt: 응답에서 제거되었습니다.

변경된 응답 구조

• groupId: 단일 값에서 groupIds 배열로 변경 및 타입이 string으로 번경되었습니다. (이전: number)
• accountId: operationUserId으로 이름 변경
• accountName: operationUserName으로 이름 변경
• email: 사용자 이메일 필드가 optional로 추가되었습니다.
• status: enum 값이 문자열로 변경되었습니다. (예: 1 → "ACTIVE")

---

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

Headers

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

Query Parameters

파라미터	타입	설명	Required	Default
siteId	string	사이트 UUID	✔	-
searchKey	string	검색어 (이름, 이메일, 의료등록번호)	✗	-
searchBy	string	검색 기준 (name, email) - searchKey와 함께 사용하여 검색 대상 지정	✗	-
status	string	환자 상태 (PENDING, ACTIVE, COMPLETED, CANCELLED, SUSPENDED, DELETED)	✗	-
limit	number	한 페이지당 조회할 사용자 수 (최대 100)	✗	10
page	number	조회할 페이지 번호 (1부터 시작)	✗	1
operationUserId	string	운영 사용자 ID (선택)	✗	-
sortBy	string	정렬 기준 (createdAt, updatedAt, lastLogin, startedAt, day, medicalRegistrationNumber, group)	✗	createdAt
sortOrder	string	정렬 방식 (asc, desc)	✗	desc

Responses

Http Status Code	설명	Error Code(s)
200 OK	조회 성공	-
400 Bad Request	잘못된 요청	1001
401 Unauthorized	인증 실패	1080
403 Forbidden	권한 없음	1081
500 Internal Server Error	서버 내부 오류	1000

200 OK - 성공

{
  "showGroup": true,
  "total": 3,
  "items": [
    {
      "userCycleId": "3d630a3f-7eec-4092-bf29-9d3fe7e22932",
      "userId": "a32224e8-ab57-4e27-9957-fff3d4f72f55",
      "name": "김철수",
      "email": "kim.cheolsu@example.com",
      "operationUserId": "a32224e8-ab57-4e27-9957-fff3d4f72f55",
      "operationUserName": "Dr. Kim Min-soo",
      "day": 60,
      "status": "ACTIVE",
      "lastLogin": "2026-01-06T04:29:28.327Z",
      "startedAt": "2025-11-08T04:29:28.327Z",
      "medicalRegistrationNumber": "MRN-TEST-001",
      "groupIds": [
        "patients.general"
      ]
    },
    {
      "userCycleId": "e4089b82-1303-4422-8664-c150df69c443",
      "userId": "babfcf45-8c2c-4613-a6f5-fcf92b6ea6f6",
      "name": "이영희",
      "email": "lee.younghee@example.com",
      "operationUserId": "a32224e8-ab57-4e27-9957-fff3d4f72f55",          
      "operationUserName": "Dr. Kim Min-soo",
      "day": 45,
      "status": "ACTIVE",
      "lastLogin": "2025-12-28T04:29:28.327Z",
      "startedAt": "2025-11-23T04:29:28.327Z",
      "medicalRegistrationNumber": "MRN-TEST-002",
      "groupIds": [
        "patients.kr"
      ]
    }
  ]
}

필드	타입	설명
totalCount	number	전체 항목 수 (필터 적용 전)
count	number	현재 페이지 항목 수
showGroup	boolean	그룹 표시 여부 (Welt 사이트인 경우 true)
data	array	사용자 데이터 배열

data 배열의 각 항목:

필드	타입	설명
userCycleId	string	사용자 사이클 UUID
userId	string	사용자 UUID
name	string	사용자 이름
email	string	사용자 이메일 (optional)
operationUserId	string	담당 운영자(의료진) UUID
operationUserName	string	담당 운영자(의료진) 이름
day	number	치료 일차
status	string	환자 상태 (PENDING, ACTIVE, COMPLETED, CANCELLED, SUSPENDED, DELETED)
lastLogin	string	마지막 로그인 일시 (ISO 8601)
startedAt	string	치료 시작 일시 (ISO 8601)
medicalRegistrationNumber	string	의료 등록 번호
groupIds	string[]	사용자가 속한 그룹 ID 배열 (예: ["patients.general", "patients.kr"])

showGroup 규칙:

• Welt 사이트 소속 계정인 경우 true
• 그 외 사이트는 false

400 Bad Request - 잘못된 요청

{
  "status": 400,
  "code": 1001,
  "message": "Bad Request",
  "detail": "요청한 정보가 유효하지 않습니다.",
  "errors": [
    {
      "field": "siteId",
      "message": "siteId is required"
    }
  ]
}

발생 가능한 에러 메시지:

• "siteId is required" - siteId가 제공되지 않음
• "Invalid siteId format" - siteId 형식이 올바르지 않음
• "Invalid status value" - 유효하지 않은 status 값
• "limit must be between 1 and 100" - limit 값이 허용 범위를 벗어남

401 Unauthorized - 인증 실패

{
  "statusCode": 401,
  "code": 1080,
  "message": "UNAUTHORIZED",
  "detail": "인증되지 않은 요청입니다"
}

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

403 Forbidden - 권한 없음

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

사용자가 해당 사이트에 대한 접근 권한이 없는 경우 발생합니다.

500 Internal Server Error - 서버 내부 오류

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