User Management 도메인 요구사항

범위: App User 정보 조회 및 관리
비범위(별도 도메인): 인증 및 권한 관리(Auth-Ops), 역할 관리(IAM-Ops)

1. 기능 요구사항

1.1 app-user 목록 조회

• USR-FR-BE-001: 시스템은 app-user 목록을 조회할 수 있어야 한다.
• USR-FR-BE-002: 시스템은 검색 키워드(searchKey)로 app-user를 검색할 수 있어야 한다.
• USR-FR-BE-003: 시스템은 상태(status)로 app-user를 필터링할 수 있어야 한다.
• USR-FR-BE-004: 시스템은 사이트 ID(siteId)로 app-user를 필터링할 수 있어야 한다.
• USR-FR-BE-005: 시스템은 담당자 ID(operationUserId)로 app-user를 필터링할 수 있어야 한다. (선택적 필터)
• USR-FR-BE-006: 시스템은 페이징을 지원해야 한다. (limit, page)
  • limit 기본값: 10
  • page 기본값: 1
• USR-FR-BE-007: 시스템은 정렬 기능을 지원해야 한다. (sortBy, sortOrder)
  • sortBy 기본값: "createdAt"
  • sortOrder 기본값: "desc"
• USR-FR-BE-008: 시스템은 마지막 로그인 시간(lastLogin)으로 정렬할 수 있어야 한다.
• USR-FR-BE-010: 시스템은 조회 결과에 총 개수(totalCount)와 현재 개수(count)를 포함해야 한다.
• USR-FR-BE-011: 시스템은 operators.medi-dashboard.admin 그룹의 경우 그룹 정보 표시 플래그(showGroup)를 true로 설정해야 한다.

1.2 권한 검증

• USR-FR-BE-012: 시스템은 요청 컨텍스트에서 계정 ID(operationUserId)와 계정 타입(operationUserType)을 추출해야 한다.
• USR-FR-BE-013: 시스템은 계정 정보를 조회하여 권한을 검증해야 한다.
  • GetOperationUserById로 계정 정보를 조회한다.
  • 계정 정보에는 Site와 Group이 포함된다.
• USR-FR-BE-014: 시스템은 계정 정보가 없는 경우 BAD_REQUEST 에러를 반환해야 한다.
• USR-FR-BE-015: 시스템은 operators.medi-dashboard.admin 그룹을 제외하고 다른 그룹 계정에 대해서는 요청한 siteId가 본인 계정의 siteId와 다른 경우 BAD_REQUEST 에러를 반환해야 한다.

1.3 app-user 리포트 조회

• USR-FR-BE-016: 시스템은 사용자 주기 ID(userCycleId)로 app-user 리포트를 조회할 수 있어야 한다.
• USR-FR-BE-017: 시스템은 app-user 리포트 조회 시 사용자 주기 정보와 시작/종료 날짜를 조회해야 한다.
• USR-FR-BE-018: 시스템은 현재 일차(day)를 계산해야 한다.
  • 현재 일차가 plan의 최종 일차 이후라면 plan에 정의된 일차로 설정한다.
• USR-FR-BE-019: 시스템은 app-user의 수면 일기 목록을 조회하여 포함해야 한다.
  • startDate부터 endDate 범위로 조회한다.
  • 총 개수(totalCount)를 포함한다.
• USR-FR-BE-020: 시스템은 첫 번째 rTIB 알고리즘 수면 목표 로그를 조회해야 한다.
• USR-FR-BE-021: 시스템은 수면 목표 로그 목록을 조회하여 포함해야 한다.
• USR-FR-BE-022: 시스템은 설문 응답 목록을 조회하여 포함해야 한다.
• USR-FR-BE-023: 시스템은 목표 성공 기록을 조회하여 성공 횟수를 계산해야 한다.
  • LotSuccess와 AetSuccess를 각각 카운트한다.
• USR-FR-BE-024: 시스템은 분모용 수면 일기 개수를 계산해야 한다.
• USR-FR-BE-025: 시스템은 LOT 일관성 퍼센티지를 계산하여 포함해야 한다.
  • 분모가 0보다 큰 경우 (successCount.Lot / 분모 * 100)로 계산한다.
  • successCount.Lot이 분모보다 크면 100으로 설정한다.
  • 소수점 첫째 자리에서 반올림한다.
• USR-FR-BE-026: 시스템은 AET 일관성 퍼센티지를 계산하여 포함해야 한다.
  • 분모가 0보다 큰 경우 (successCount.Aet / 분모 * 100)로 계산한다.
  • successCount.Aet이 분모보다 크면 100으로 설정한다.
  • 소수점 첫째 자리에서 반올림한다.
• USR-FR-BE-027: 시스템은 리포트에 요약 정보(Summary)를 포함해야 한다.
  • TreatmentProgress: 현재 일차(currentDay), 총 사용 일수(totalUsageDays=app-user의 plan에 정의된 값)
  • SleepRecord: 수면 일기 개수(count), 앱 사용 일수(appUsageDays), 퍼센티지(count/day * 100)
  • LotSuccess: LOT 성공 횟수, 앱 사용 일수, 분모용 수면 일기 개수, 퍼센티지
  • AetSuccess: AET 성공 횟수, 앱 사용 일수, 분모용 수면 일기 개수, 퍼센티지

1.4 외부 액세스 토큰을 통한 app-user 리포트 조회

• USR-FR-BE-028: 시스템은 외부 액세스 토큰으로 app-user 리포트를 조회할 수 있어야 한다.
• USR-FR-BE-029: 시스템은 토큰이 빈 문자열인 경우 BAD_REQUEST 에러를 반환해야 한다.
• USR-FR-BE-030: 시스템은 토큰을 검증해야 한다.
  • TokenTypeMdAccess 타입으로 검증한다.
• USR-FR-BE-031: 시스템은 토큰 claims에서 "sub"를 추출해야 한다.
• USR-FR-BE-032: 시스템은 "sub"가 존재하지 않는 경우 BAD_REQUEST 에러를 반환해야 한다.
• USR-FR-BE-033: 시스템은 "sub"를 float64로 변환할 수 없거나 userCycleId와 다른 경우 BAD_REQUEST 에러를 반환해야 한다.
• USR-FR-BE-034: 시스템은 토큰 검증 성공 후 app-user 리포트를 조회하여 반환해야 한다.

2. 비기능 요구사항

2.1 보안

• USR-NFR-001: 시스템은 app-user 정보 조회 시 권한 검증을 수행해야 한다.
• USR-NFR-002: 시스템은 계정 정보 조회 시 전화번호(phone_number)를 pgp_sym_decrypt로 복호화해야 한다.

3. 제약사항

3.1 권한 제약 (CR-001~099)

• USR-CR-001: operators.medi-dashboard.admin 계정을 제외한 모든 계정은 본인 사이트의 app-user만 조회할 수 있다.

3.2 데이터 제약 (CR-101~199)

• USR-CR-101: siteId는 필수 입력 값이다. ''인 경우 BAD_REQUEST 에러를 반환한다.
• USR-CR-102: operationUserId는 선택적 입력 값이다. ''이 아닌 경우에만 필터링에 사용한다.
• USR-CR-103: 리포트의 총 사용 일수(totalUsageDays)는 app-user의 plan을 기준으로 설정한다. (ex. 42, 90)

---

변경 이력

버전	날짜	작성자	변경 내용
0.1.0	2025-12-31	dalia@weltcorp.com	문서 최초 작성 - GetAppUsers, GetAppUserReport, GetAppUserReportWithExternalAccessToken 요구사항