본문으로 건너뛰기

Sleep 도메인 비즈니스 규칙

1. 시간 처리 규칙​

1.1 TimeMachine 의존성​

  • 수면 도메인 내 모든 시간 관련 로직(타임스탬프 저장, 기간 계산, 날짜 비교 등)은 시스템 시간을 직접 사용하지 않고, 반드시 TimeMachine 도메인이 제공하는 가상 시간 또는 실제 시간을 사용해야 합니다. (요구사항 3.6)
  • 모든 시간 처리는 TimeMachine 도메인을 통해 이루어져야 하며, 이는 서머 타임(DST) 규칙을 포함한 시간대 변환을 포함합니다. (요구사항 3.6)
  • 시간 관련 데이터는 TimeMachine 기준 시간으로 저장되어야 하며, 필요시 Unix 타임스탬프와 DateTime 객체 간 변환이 도메인 경계에서 이루어져야 합니다. (모델 1)

1.2 TimeMachine 시간 변경 처리​

  • TimeMachine 도메인에서 시스템 시간을 현재보다 과거 시점으로 변경하는 경우, 수면 도메인은 변경된 과거 시점 이후에 해당하는 모든 사용자별 수면 관련 데이터(수면 기록, 계산된 주간 요약, rTIB 처방 내역, 목표 달성 기록 등)를 자동으로 삭제해야 합니다. (요구사항 3.9, 모델 5.1, 5.2, 5.4)

1.3 시간 입력 단위​

  • 사용자가 입력하는 모든 수면 관련 시간 값(잠자리에 든 시각, 일어난 시각, 수면 중 깬 시간, 낮잠 시간, 목표 기상 시각 등)은 5분 단위로만 입력 가능해야 합니다. 프론트엔드 UI 및 백엔드 유효성 검사에서 이를 강제해야 합니다. (요구사항 3.7)

2. 수면 기록 규칙​

2.1 기록 생성 및 수정 규칙​

  • 시스템은 사용자의 일일 수면 기록을 저장하고 관리해야 합니다. (요구사항 1.1)
  • 사용자는 이미 저장된 과거의 수면 기록을 수정하거나 삭제할 수 없습니다. 수면 기록은 생성 시점 이후 변경 불가능(immutable)합니다. (요구사항 3.8)
    • 다만, 당일 기록에 한해 자정(해당 날짜의 23:59:59)까지 수정이 가능합니다. (요구사항 1.1)
  • 수면 기록 수정 시에는 부분 업데이트(Partial Update)가 지원되어야 하며, 사용자가 변경하고자 하는 특정 필드만 전송하여 업데이트할 수 있어야 합니다. (요구사항 1.1)
  • 수정 API는 변경된 필드만 검증하고 업데이트해야 합니다. (요구사항 1.1)
  • 수면 여부(dns) 필드를 변경할 경우에는 해당 상태에 맞는 필수 입력 항목 검증을 다시 적용해야 합니다. (요구사항 1.1)
  • 수면 여부(dns)를 false에서 true로 변경하는 경우, DNS에 필요한 데이터(부정적 영향 요인, 수면제 복용 여부, 낮잠 시간) 이외의 모든 항목(수면의 질, 잠자리에 든 시각, 일어난 시각, 잠들기까지 걸린 시간, 수면 중 깬 시간 총합, 긍정적 영향 요인, 계산된 수면 지표 등)은 자동으로 초기화(null 또는 기본값으로 설정)되어야 합니다. (요구사항 1.1)
  • 수정은 3.8 제약사항에 명시된 대로 기록 당일 자정까지만 가능하다. (요구사항 3.8)
  • 수면 기록은 오늘(현재 날짜)에 한해서만 생성/수정이 가능하며, 과거나 미래 일차에 대한 기록 생성은 불가능합니다. (요구사항 3.9)
  • 클라이언트에서 dayIndex를 수면 기록 입력 정보로 전송할 때, 시스템은 해당 dayIndex가 현재 사용자의 치료 일차와 일치하는지 검증해야 합니다. (요구사항 3.9)
  • 현재 치료 일차와 요청의 dayIndex가 일치하지 않는 경우, 시스템은 오류를 발생시키고 수면 기록 생성/수정을 거부해야 합니다. (요구사항 3.9)

2.1.2 수면 기록 시간 검증 규칙​

  • 시스템은 수면 기록 생성 및 수정 시마다 다음과 같은 시간 관련 검증을 수행해야 합니다:
    • AET(일어난 시각)는 LOT(잠자리에 든 시각)보다 이전일 수 없습니다. (AET > LOT) (요구사항 1.1)
    • SE(수면 효율)는 1.0을 넘을 수 없습니다. (0 ≤ SE ≤ 1.0) (요구사항 1.1)
    • LOT(잠자리에 든 시각)는 18:00 이후여야 합니다. (요구사항 1.1)
  • 위 조건 중 하나라도 충족하지 않는 경우, 시스템은 해당 요청을 거부하고 적절한 오류 메시지를 반환해야 합니다. (요구사항 1.1)
  • 검증 오류 발생 시 어떤 항목이 유효하지 않은지와 허용 가능한 값의 범위를 명확히 안내해야 합니다. (요구사항 1.1)

2.1.1 임시 수면 기록 규칙​

  • 시스템은 웨어러블 장치나 AI와의 대화를 통해 부분적으로 수집된 수면 데이터를 임시 수면 기록으로 저장할 수 있어야 합니다. (요구사항 1.1)
  • 임시 수면 기록은 일부 필수 필드가 누락되어도 저장이 가능해야 하며, 이를 위한 별도의 상태 플래그(isTemporary = true)를 포함해야 합니다. (요구사항 1.1)
  • 임시 수면 기록에는 최소한 다음 정보 중 하나 이상이 포함되어야 합니다: (요구사항 1.1)
    • 잠자리에 든 시각(lot)
    • 일어난 시각(sleepEndTime)
    • 수면의 질(sleepQuality)
    • 수면제 복용 여부(pill)
  • 임시 수면 기록은 사용자가 나머지 필수 정보를 입력하면 완전한 수면 기록으로 전환되어야 합니다. (요구사항 1.1)
  • 임시 수면 기록이라도 취침(lot) 또는 기상(sleepEndTime) 시각 정보가 포함되어 있다면, 해당 정보를 기반으로 수면 목표 달성 여부 계산에 부분적으로 포함해야 합니다. 두 시각 모두 있을 경우 완전한 목표 달성 평가를, 하나만 있을 경우 해당 항목에 대한 부분 평가를 진행합니다. (요구사항 1.1)
  • 웨어러블 장치로부터 수집된 수면 데이터가 있는 경우, 사용자가 수면 기록을 작성할 때 이를 기본값으로 제시하여 사용자 입력을 보조해야 합니다. (요구사항 1.1)
  • 임시 수면 기록도 수정은 당일 자정까지만 가능하며, 삭제 기능은 제공하지 않습니다. (요구사항 1.1)

2.2 필수 입력 항목​

  • 수면 기록 시 dns, timezoneId, timezoneOffset, dayIndex는 공통 필수 항목입니다. (모델 2.1, 8 - SleepLog)
  • dns이 true인 경우(전혀 못 잤을 경우) 필수 입력 항목:
    • 수면에 부정적인 영향을 준 요인(negativeFactorIds)
    • 수면제 복용 여부(pill)
    • 낮잠을 잔 시간(napMinutes)
  • dns이 false인 경우(잠을 잤을 경우) 필수 입력 항목:
    • 수면의 질(sleepQuality)
    • 잠자리에 든 시각(lot) - 눈을 감고 잠을 청한 시각
    • 일어난 시각(aet) - 잠에서 깬 시각
    • 잠들기까지 걸린 시간(sol, 기본값: 0분)
    • 수면 중 깬 시간 총합(waso, 기본값: 0분)
    • 수면에 긍정적인 영향을 준 요인(positiveFactorIds)
    • 수면에 부정적인 영향을 준 요인(negativeFactorIds)
    • 수면제 복용 여부(pill)
    • 낮잠을 잔 시간(napMinutes)

2.3 영향 요인 규칙​

  • 긍정적/부정적 영향 요인은 미리 정의된 목록에서 선택하거나, 사용자가 직접 입력할 수 있습니다. (요구사항 1.1)
  • 사용자가 직접 입력하는 영향 요인은 각 유형(긍정/부정)별로 최대 10개까지 추가 가능하며, 각 항목은 최대 100자까지 저장 가능합니다. (요구사항 1.1, 모델 2.1)
  • 긍정적/부정적 영향 요인 목록은 sleep.sleep_log_positive_factor 및 sleep.sleep_log_negative_factor 테이블에서 관리됩니다. (모델 2.5, 2.6, 8)

2.4 계산 지표 규칙​

  • TST(TotalSleepTimeMinutes), SE(SleepEfficiency), SOL(SleepOnsetLatency), WASO(WakeAfterSleepOnsetMinutes)는 수면 기록의 시간 정보를 기반으로 계산됩니다. (모델 2.1, 3.2)
  • 계산된 지표(tst, se, sol, waso)는 쿼리 편의성과 레거시 호환성을 위해 SleepLog 엔티티에 직접 저장합니다. (모델 2.1 주석)
  • 원본 시간 데이터 변경 시 (현재는 수정 불가 규칙으로 인해 발생하지 않음) 계산된 지표 값도 함께 업데이트되어야 데이터 일관성이 유지됩니다.

2.4.1 수면 효율 계산 규칙​

  • 시스템은 수면 기록 생성 및 수정 시 수면 효율(SE, Sleep Efficiency)을 즉시 계산하여 저장해야 합니다. (요구사항 1.1)
  • 수면 효율은 총 수면 시간(TST)을 침대에 있던 총 시간(TIB)으로 나눈 값으로 계산됩니다. (요구사항 1.1)
  • TST = AET - (LOT + SOL) - WASO 공식을 사용하여 계산합니다. (AET: 일어난 시각, LOT: 잠자리에 든 시각, SOL: 잠들기까지 걸린 시간, WASO: 수면 중 깬 시간 총합) (요구사항 1.1)
  • TIB = AET - LOT 공식을 사용하여 계산합니다. (요구사항 1.1)
  • 수면 효율은 0과 1 사이의 소수점 두 자리까지의 값으로 정규화하여 저장해야 합니다. (요구사항 1.1)
  • DNS(Did Not Sleep) 기록의 경우 수면 효율은 null로 설정합니다. (요구사항 1.1)

2.5 유효 기록 정의 (rTIB 계산용)​

  • dns이 true인 기록은 평균 계산에서 제외됩니다 (null 처리). (요구사항 1.2, 3.3)
  • tst가 720분을 초과하는 기록은 평균 계산에서 제외됩니다 (null 처리). (요구사항 1.2, 3.3)

2.6 주차별 데이터 계산 및 조회 규칙​

  • 주차별 데이터는 연속된 7일 단위로 계산하며, 시작 일차(dayIndex)를 기준으로 해당 일차부터 연속된 7일간의 데이터를 의미합니다. (요구사항 1.1)
  • 주차별 데이터 조회 시 모든 API는 시작 일차(dayIndex) 파라미터를 반드시 포함해야 합니다. (요구사항 1.1)
  • 주차별 데이터는 각 일차별로 구분되어 제공되어야 합니다. (요구사항 1.1)
  • 수면 기록 조회 시 치료 주기 일차(dayIndex) 정보와 함께 해당 일차에 해당하는 실제 달력상 날짜 정보도 함께 제공해야 합니다. (요구사항 1.1.1)
  • 백엔드 시스템은 앱의 7일 단위 표시 외에도 다양한 기간 범위로 데이터를 조회할 수 있는 유연한 API를 제공해야 합니다. (요구사항 1.1)
    • 사용자의 전체 치료 주기에 걸친 데이터 조회가 가능해야 합니다. (요구사항 1.1)
    • 특정 일차 범위(예: 10-30일차)를 지정하여 조회할 수 있어야 합니다. (요구사항 1.1)
    • 월별, 분기별 등 다양한 시간 단위로 집계된 통계 데이터를 제공할 수 있어야 합니다. (요구사항 1.1)
  • DNS(Did Not Sleep) 기록의 경우:
    • 총 수면 시간(tst)은 0분으로 간주합니다. (요구사항 1.1)
    • 수면의 질(sleepQuality) 정보는 없음으로 표시합니다. (요구사항 1.1)
    • 잠들기까지 걸린 시간(sol) 정보는 없음으로 표시합니다. (요구사항 1.1)
    • 긍정적 영향 요인 정보는 없음으로 표시합니다. (요구사항 1.1)
  • 다음과 같은 주차별 통계를 제공해야 합니다:
    • 수면 효율(SE) 범주(Poor, Moderate, Good) 및 일차별 수치 (요구사항 1.1)
    • 수면의 질 분포 (각 등급별 빈도수 및 비율) (요구사항 1.1)
    • 총 수면 시간(TST) 통계 (평균, 최소, 최대, 일차별 데이터) (요구사항 1.1)
    • 수면제 복용 빈도 및 패턴 (복용 일수, 복용 비율) (요구사항 1.1)
    • 잠들기까지 걸린 시간(SOL) 통계 (평균, 최소, 최대, 일차별 데이터) (요구사항 1.1)
    • 낮잠 시간 통계 (평균, 총합, 일차별 데이터) (요구사항 1.1)
    • 수면 영향 요인 통계 (긍정적/부정적 요인별 빈도수 및 비율) (요구사항 1.1)
    • 목표 취침/기상 시각 준수 횟수 및 일차별 달성 여부 (요구사항 1.1)

2.7 치료 일시 정지와 주차 단위 조회 규칙​

  • 주차 단위 데이터 조회 시 일시 정지 기간은 무시되며, dayIndex 기준으로 연속된 치료 일차를 하나의 주차로 처리합니다. (요구사항 1.1.1)
  • 주차 조회 시 실제 날짜의 연속성이 아닌 치료 진행의 연속성(dayIndex)을 기준으로 주차 데이터를 구성하여 제공합니다. (요구사항 1.1.1)
  • 예시:
    • 예시 1: 사용자가 1-5일차까지 기록 → 3일간 일시 정지 → 6-10일차 기록 상태에서
      • startDayIndex=1로 주차 조회 시: 1, 2, 3, 4, 5, 6, 7일차 데이터를 반환합니다.
      • 여기서 6, 7일차는 일시 정지 이후의 실제 날짜이지만, dayIndex 기준으로 연속된 7일로 처리됩니다.
    • 예시 2: 사용자가 1-3일차 기록 → 10일간 일시 정지 → 4-12일차 기록 상태에서
      • startDayIndex=1로 주차 조회 시: 1, 2, 3, 4, 5, 6, 7일차 데이터를 반환합니다.
      • 이때 4-7일차는 실제 달력상으로는 1-3일차와 10일 이상 떨어져 있지만, 치료 주기 일차 기준으로 연속된 데이터로 처리됩니다.

3. rTIB 계산 및 처방 규칙​

3.1 계산 주기 및 데이터 요구사항​

  • rTIB(Recommended Time In Bed) 계산은 주 단위(7일 간격)로 수행됩니다. (요구사항 1.2, 3.1)
  • rTIB 계산은 직전 7일간의 유효 수면 기록을 기반으로 합니다. (요구사항 3.1)
  • rTIB 계산에는 최소 5개 이상의 유효한 수면 기록 데이터가 필요합니다. (단, 최초 계산 및 데이터 부족 시 예외 적용). (요구사항 1.2, 3.2)

3.2 최초 rTIB 계산 규칙​

  • 앱 사용 시작 후 첫 7일 동안은 rTIB를 제공하지 않습니다. (요구사항 1.2)
  • 기본적으로 8일차(D-8)가 최초 rTIB 제공의 기준일입니다. (요구사항 1.2)
  • 사용자가 1일차부터 7일차까지 4개 이상의 유효한 수면 기록을 작성한 경우, 8일차에 최초 rTIB가 제공됩니다. (요구사항 1.2)
  • 1일차부터 7일차까지 4개 미만의 수면 기록을 작성한 경우, 총 4개의 유효한 기록이 작성될 때까지 rTIB 제공이 지연됩니다. (예: 16일차에 총 4개가 작성되면 17일차에 최초 rTIB가 제공됨) (요구사항 1.2)
  • 최초 rTIB 계산 시 데이터 사용 규칙:
    • 사용 1~7일 사이 기록이 4개 이상이면 해당 기록 전체 사용. (요구사항 1.2)
    • 4개 미만이면 4번째 기록 작성 시점까지 기다려야 합니다. (요구사항 1.2)

3.3 후속 rTIB 계산 규칙​

  • rTIB는 최초 rTIB 제공 날짜를 기준으로 7일 주기로 제공됩니다. (요구사항 1.2, 3.1)
  • 이상적인 경우의 제공 주기: 8일차 → 15일차 → 22일차 → 29일차 등. (요구사항 1.2)
  • 최초 rTIB 제공이 지연된 경우에도 이후 rTIB는 최초 제공일 기준으로 7일 주기를 유지합니다. (예: 17일차에 최초 rTIB를 받았다면, 이후 rTIB는 24일차, 31일차 등에 제공) (요구사항 1.2)
  • 후속 rTIB 계산 시 데이터 사용 규칙:
    • 직전 rTIB 제공일로부터 7일간의 기록 사용. (요구사항 1.2)
    • 해당 기간 기록이 5개 이상이면 모두 사용. (요구사항 1.2)
    • 5개 미만이면 이전 기록 중 최신 기록을 포함하여 최대 5개 사용. (요구사항 1.2)
  • 직전 rTIB 제공일로부터 7일이 경과했을 때 rTIB 계산 조건에 부합하지 않으면, 이후 7일 동안은 직전에 계산된 rTIB를 유지합니다. (요구사항 1.2)

3.4 데이터 부족 시 처리 규칙​

  • 시스템은 7일차에 수면 기록이 4개 미만인 경우, 총 4개의 유효한 수면 기록이 쌓일 때까지 rTIB 계산 및 제공을 보류해야 합니다. (요구사항 1.2)
  • 후속 rTIB 계산 시(7일 주기), 해당 주에 수면 기록이 5개 미만인 경우 이전 주의 데이터를 포함하여 최대 5개의 최신 수면 기록을 활용해 rTIB를 계산해야 합니다. (요구사항 1.2)
  • 데이터 부족으로 rTIB 계산이 지연될 경우, 사용자에게 적절한 알림을 제공하여 수면 기록 작성을 독려해야 합니다. (요구사항 1.2)

3.5 rTIB 계산 로직​

  • 최근 7일간의 유효한 수면 기록(최소 5개 이상, 예외 규칙 따름)을 기반으로 avgTST, avgSE, avgDSE를 계산합니다. (요구사항 1.2)
  • 평균 계산: 유효한 기록의 합 / 유효한 일수. 소수점 셋째 자리에서 반올림하여 두 자리까지 표현합니다. (요구사항 1.2)
  • 계산된 avgSE를 기준으로 수면 효율 범주(Good, Poor, Moderate)를 판별합니다. (요구사항 1.2)
  • 수면 효율 범주에 따라 rTIB 계산 공식을 적용합니다:
    • Good SE (avgSE ≥ 0.95): rTib = avgDSE (요구사항 1.2)
    • Poor SE (avgSE ≤ 0.87): rTib = avgTST (요구사항 1.2)
    • Moderate SE (0.87 < avgSE < 0.95): rTib = avgTST + (avgDSE - avgTST) * (avgSE - 0.87) * 10 (요구사항 1.2)
  • rTIB 값은 최소 270분(4.5시간)에서 최대 600분(10시간) 범위로 제한해야 합니다. (요구사항 1.2, 3.16)
  • 최종 산출된 rTIB는 15분 단위로 올림해야 합니다. (요구사항 1.2, 3.4)
  • (옵션) ESS 점수 변화 또는 사용자 주간 졸림 피드백에 따라 rTIB 조정 로직을 포함할 수 있습니다. (요구사항 1.2)

3.6 rTIB 처방 및 저장 규칙​

  • rTIB 계산 결과는 RtibRecommendation 엔티티에 저장됩니다. (모델 2.3, 8)
  • RtibRecommendation에는 계산 날짜, 권장 TIB, 계산 근거(avgTst, avgSe, avgDse, 데이터 기간, 유효 로그 수 등)가 포함됩니다. (모델 2.3)
  • 사용자 주기별로 특정 계산 날짜에는 하나의 rTIB 처방만 존재해야 합니다. (모델 8 - RtibRecommendation @@unique)
  • 시스템은 매일 밤(시스템 로컬 시간대 기준 00:00) 조건을 만족하는 모든 사용자를 대상으로 rTIB 계산 및 처방 배치 작업을 수행해야 합니다. (요구사항 1.2)
    • 단, 해당 날짜에 수면 기록 작성 시점에 이미 rTIB가 계산된 사용자는 배치 작업 대상에서 제외합니다. (요구사항 1.2)
    • 배치 작업은 당일에 rTIB 계산이 되지 않은 사용자들에 대해서만 수행되어야 합니다. (요구사항 1.2)
  • 사용자가 rTIB 관련 정보 요청 시:
    • 해당 날짜의 rTIB 정보가 배치 작업을 통해 이미 계산/저장되어 있다면 저장된 값을 반환합니다. (요구사항 1.2)
    • 배치 작업 미완료 또는 실패 시, 실시간으로 rTIB를 계산하여 응답해야 합니다. (요구사항 1.2)

3.7 수면 기록 작성 시점의 rTIB 계산 규칙​

  • 시스템은 사용자가 수면 기록을 작성하여 저장하는 시점에 해당 사용자가 rTIB 계산 조건을 만족하는지 확인하고, 조건 충족 시 즉시 새로운 rTIB를 계산하여 제공해야 합니다. (요구사항 1.2)
  • 실시간 rTIB 계산 조건:
    • 최초 rTIB의 경우, 4개 이상의 유효 기록이 누적된 경우 (사용 8일차 이후) (요구사항 1.2)
    • 후속 rTIB의 경우, 직전 rTIB 제공일로부터 7일이 경과했으며, 해당 기간 내 5개 이상의 유효 기록이 있는 경우 (또는 기록이 5개 미만이면, 이전 기록을 포함해 최소 5개 이상의 유효 기록이 있는 경우) (요구사항 1.2)
    • 직전 rTIB 제공일로부터 7일이 경과했으나 rTIB 계산 조건에 부합하지 않을 경우, 이후 7일 동안은 직전에 계산된 rTIB를 유지합니다. (요구사항 1.2)
  • 계산 로직은 배치 작업에서 사용하는 것과 동일하게 적용합니다. (요구사항 1.2)
  • 계산된 새로운 rTIB는 즉시 저장되고, 사용자에게 알림을 통해 새로운 수면 목표가 설정되었음을 알려야 합니다. (요구사항 1.2, 모델 5.5)
  • 생성된 수면 목표의 type은 ALGORITHM으로 설정합니다. (요구사항 1.2)
  • 수면 기록 작성 시점에 rTIB가 계산된 경우, 해당 사용자는 당일 자정 배치 작업의 대상에서 제외됩니다. (요구사항 1.2)

3.8 목표 시간 제안 규칙​

  • rTIB 처방 시, 해당 계산에 사용된 수면 데이터 기간 내 median AET(Asleep End Time)를 기반으로 목표 기상/취침 시각을 함께 제안해야 합니다. (요구사항 1.2, 3.5)

3.9 rTIB 조정 범위 제한​

  • 새로 계산된 rTIB 값은 이전 계산값에서 최대 ±30분 범위 내에서만 변경될 수 있습니다. 단, 최초 rTIB 계산 시에는 이 제한이 적용되지 않습니다. (요구사항 3.15)
  • 이는 급격한 수면 시간 변화로 인한 사용자의 적응 어려움을 방지하고, 점진적인 수면 패턴 개선을 유도하기 위함입니다. (요구사항 3.15)

4. 수면 목표 규칙​

4.1 목표 설정 규칙​

  • 사용자의 수면 목표(목표 취침/기상 시각)는 SleepGoal 엔티티에 기록됩니다. (모델 2.2, 8)
  • SleepGoal에는 목표 적용 날짜, 목표 취침/기상 시각, 권장 TIB(rTIB 처방 시), 목표 설정 주체(goalType)가 포함됩니다. (모델 2.2)
  • goalType은 사용자가 직접 설정(USER), rTIB 알고리즘 결과(RTIB_ALGORITHM), 시스템 생성(SYSTEM) 등을 구분합니다. (모델 2.2)
  • rTIB 처방과 사용자 입력(목표 기상 시각)을 기반으로 SleepGoal을 설정/업데이트 할 수 있습니다. 이때 목표 취침 시각은 (목표 기상 시각 - 권장 TIB)로 계산됩니다. (모델 5.2)

4.2 목표 기상 시각 변경 규칙​

  • 사용자는 rTIB를 처방받은 당일에 한해 목표 기상 시각을 변경할 수 있습니다. (요구사항 1.2)
  • 사용자가 목표 시각을 변경하지 않으면 기존 설정된 기상 시각 또는 median AET 기반 제안 시각을 유지하여 목표 취침/기상 시각을 설정해야 합니다. (요구사항 1.2, 3.5)

4.3 목표 유지 규칙​

  • 설정된 수면 목표(기상/취침 시각)는 다음 rTIB 처방일까지 유지됩니다. (요구사항 1.2)

4.4 목표 달성 규칙​

  • 특정 날짜의 수면 목표 달성 여부(SleepGoalAdherence)는 해당 날짜의 수면 기록(SleepLog)이 저장되는 즉시 계산되어 SleepGoalAdherence 엔티티에 기록/업데이트되어야 합니다. (요구사항 1.1)
  • 목표 달성 여부는 해당 날짜의 SleepLog와 SleepGoal을 비교하여 계산됩니다. (모델 5.4)
  • 목표 달성 기준: 처방된 목표 시각 ±30분 이내에 취침/기상 시 성공으로 간주합니다. (요구사항 1.2 프론트엔드)
  • 사용자 주기별로 특정 날짜에는 하나의 목표 달성 기록만 존재해야 합니다. (모델 8 - SleepGoalAdherence @@unique)
  • 시스템은 사용자가 치료 주기 일차(dayIndex)별로 수면 목표 준수 여부를 조회할 수 있도록 해야 합니다. 조회는 주차(7일) 단위로 이루어져야 하며, 결과에는 각 일차별 목표 취침/기상 시각과 실제 취침/기상 시각, 목표 달성 여부가 포함되어야 합니다. (요구사항 1.1)

5. 알림 규칙 (알림 도메인 의존)​

5.1 목표 시간 알림​

  • 사용자의 목표 기상 시각이 되면 푸시 알림을 보내야 합니다. (요구사항 1.2, 모델 5.5)
  • 사용자의 목표 취침 시각 1시간 전에 푸시 알림을 보내야 합니다. (요구사항 1.2, 모델 5.5)

5.2 rTIB 관련 알림​

  • rTIB 처방 시 사용자에게 알림을 보내야 합니다. (요구사항 1.2 프론트엔드, 모델 5.5)
  • 수면 기록 저장 후 새로운 rTIB가 계산되었을 경우, 이를 사용자에게 즉시 알리고 새로운 수면 목표를 확인할 수 있도록 안내해야 합니다. (요구사항 1.2 프론트엔드, 모델 5.5)
  • 데이터 부족으로 rTIB 처방이 지연될 경우 사용자에게 알림을 보내야 합니다. (요구사항 1.2 프론트엔드, 모델 5.5)
  • rTIB 계산 결과에 따른 피드백 메시지(예: 안정적 패턴)를 알림으로 보낼 수 있어야 합니다. (요구사항 1.2, 모델 5.5)

6. 데이터 저장 규칙​

6.1 스키마 분리 규칙​

  • 수면 기록(SleepLog), 수면 목표(SleepGoal), rTIB 처방(RtibRecommendation), 목표 달성 여부(SleepGoalAdherence) 등 사용자와 직접 관련된 민감 데이터는 private 스키마에 저장합니다. (모델 1, 8)
  • 수면 영향 요인(SleepLogPositiveFactor, SleepLogNegativeFactor) 등 일반 설정/조회 데이터는 sleep 스키마에 저장합니다. (모델 1, 8)

7. 관리자 및 서비스 계정의 데이터 접근 규칙​

7.1 접근 권한 범위​

  • 시스템은 적절한 권한을 가진 다른 역할의 사용자(System Admin, IAM Admin, Service Account 등)가 데이터 분석, 품질 관리, 연구 등의 목적으로 사용자의 수면 데이터에 접근할 수 있도록 허용해야 합니다. (요구사항 1.1.2)
  • 역할별 접근 범위는 다음과 같이 구분됩니다:
    • System Admin: 모든 사용자의 수면 기록, 수면 목표, rTIB 처방 데이터 등 전체 수면 도메인 데이터에 접근 가능. (요구사항 1.1.2)
    • IAM Admin: 관리 권한이 할당된 범위 내 사용자들의 수면 기록, 수면 목표 데이터에 접근 가능. (요구사항 1.1.2)
    • Service Account: 할당된 권한에 따라 API를 통해 특정 사용자 또는 익명화된 집계 데이터에 접근 가능. (요구사항 1.1.2)

7.2 데이터 접근 API​

  • 시스템은 다음과 같은 데이터 접근 API를 제공해야 합니다:
    • 특정 사용자 또는 사용자 그룹의 모든 수면 기록 조회 (요구사항 1.1.2)
    • 특정 기간 동안의 수면 기록 통계 및 집계 데이터 조회 (요구사항 1.1.2)
    • 사용자별 rTIB 처방 이력 및 수면 목표 달성률 조회 (요구사항 1.1.2)
    • 수면 영향 요인 분포 및 트렌드 분석 데이터 조회 (요구사항 1.1.2)

7.3 데이터 조회 유연성​

  • 시스템은 관리자와 서비스 계정을 위해 특히 유연한 데이터 조회 옵션을 제공해야 합니다:
    • 사용자의 전체 치료 주기에 걸친 모든 수면 데이터 조회 (요구사항 1.1.2)
    • 여러 사용자 또는 그룹 간의 비교 분석을 위한 데이터 추출 (요구사항 1.1.2)
    • 특정 조건(수면 효율, 수면제 복용 여부 등)에 따른 필터링 및 집계 기능 (요구사항 1.1.2)
    • 일별, 주별, 월별, 분기별 등 다양한 시간 단위로 데이터 집계 및 분석 (요구사항 1.1.2)
    • 치료 일차(dayIndex) 기준으로 특정 기간(예: 치료 초기 vs 후기)에 따른 데이터 비교 분석 (요구사항 1.1.2)
    • 특정 기간 동안의 rTIB 변화 추세 및 수면 패턴 변화 분석 (요구사항 1.1.2)

7.4 보안 및 감사​

  • 시스템은 관리자 및 서비스 계정의 데이터 접근에 대해 상세한 감사 로그를 기록해야 합니다. (요구사항 1.1.2)
  • 시스템은 데이터 분석 목적으로 익명화된 데이터 추출 API를 제공해야 합니다. (요구사항 1.1.2)
  • 모든 데이터 접근은 IAM 도메인에서 정의한 권한 체계를 따라야 하며, 최소 권한 원칙을 준수해야 합니다. (요구사항 1.1.2)

8. 데이터 관리 및 개인정보 보호 규칙 (GDPR 준수)​

8.1 데이터 보관 및 아카이빙 규칙​

  • 보관 기간: 수면 기록 및 관련 분석 데이터는 개인정보 처리방침에 명시된 대로 5년간 보관해야 합니다. (요구사항 1.3, 3.12)
  • 비활성 사용자 식별: 최근 6개월간 앱에 로그인하지 않았거나, 치료 종료 후 6개월이 경과한 사용자는 '비활성(inactive)' 상태로 식별되어야 합니다. (요구사항 1.3, 3.12)
  • 데이터 아카이빙:
    • 비활성 상태로 1년이 경과한 사용자의 데이터(수면 기록, 목표, rTIB 이력 등)는 주 데이터베이스에서 콜드 스토리지로 이전(아카이빙)되어야 합니다. (요구사항 1.3, 3.12)
    • 아카이빙 시 데이터는 압축 및 암호화되어야 합니다. (요구사항 1.3, 2.2)
    • 아카이빙 후 주 데이터베이스에서는 해당 데이터가 삭제되어야 하나, 사용자 식별 정보 및 최소 메타데이터는 유지될 수 있습니다. (요구사항 1.3)
    • 아카이빙 작업은 시스템 부하가 적은 시간대에 배치 작업으로 수행되어야 합니다. (요구사항 2.1)
  • 아카이빙 시스템 가용성: 아카이빙 시스템은 99.9% 이상의 가용성을 유지해야 하며, 콜드 스토리지 데이터는 재해 복구를 위해 지리적으로 분산되어 복제되어야 합니다. (요구사항 2.3)

8.2 데이터 복원 규칙​

  • 자동 복원: 아카이빙된 사용자가 다시 서비스를 이용(로그인 등)할 경우, 콜드 스토리지에서 해당 사용자의 과거 데이터가 자동으로 복원되어야 합니다. (요구사항 1.3, 3.12)
  • 복원 프로세스: 복원 시 데이터는 복호화 및 압축 해제 후 주 데이터베이스로 이전되어야 합니다. (요구사항 1.3)
  • 복원 성능: 사용자 데이터 복원은 사용자 로그인 후 최대 5초 이내에 완료되어야 합니다. (요구사항 2.1)
  • 복원 데이터 처리: 복원된 데이터는 이전 치료 주기와 현재 치료 주기를 명확히 구분할 수 있는 메타데이터를 포함해야 하며, 사용자에게 복원 사실을 알려야 합니다. (요구사항 1.3, 3.12)

8.3 데이터 삭제 및 익명화 규칙​

  • 사용자 요청 시 삭제: 사용자 탈퇴 또는 데이터 삭제 요청 시, 주 데이터베이스와 콜드 스토리지에서 해당 사용자의 개인 식별 정보 및 모든 수면 데이터를 즉시 영구적으로 삭제해야 합니다. (요구사항 1.3, 3.12)
  • 익명화 보관 (선택적): 사용자가 완전 삭제를 명시적으로 요청하지 않는 한, 개인 식별 정보 삭제 후 수면 데이터는 통계 및 연구 목적으로 익명화하여 보관할 수 있습니다. (요구사항 1.3, 3.12)
  • 자동 파기: 데이터 보관 기간(5년)이 경과한 데이터는 자동으로 파기되어야 합니다. (요구사항 1.3)
  • 삭제/익명화 기준: 익명화는 GDPR 기준에 따라 재식별이 불가능하도록 처리되어야 합니다. (요구사항 2.2)
  • 삭제 기록: 모든 데이터 삭제 및 익명화 작업은 감사 로그에 기록되어야 합니다. (요구사항 1.3, 3.12)

8.4 데이터 이동성 규칙​

  • 데이터 추출: 사용자가 요청할 경우, 자신의 모든 수면 데이터를 표준 형식(JSON, CSV 등)으로 추출하여 제공할 수 있는 API가 있어야 합니다. (요구사항 1.3, 3.12)
  • 요청 처리: 데이터 추출 요청은 적절한 사용자 인증 후 처리되어야 합니다. (요구사항 1.3)
  • 데이터 보안: 추출된 데이터는 압축 및 암호화되어 안전하게 전송되어야 합니다. (요구사항 1.3)

8.5 보안 규칙 (GDPR 관련)​

  • 데이터 암호화: 저장 데이터(at rest)는 AES-256 이상, 전송 데이터(in transit)는 TLS 1.2 이상으로 암호화되어야 합니다. 콜드 스토리지 데이터는 이중 암호화되어야 합니다. (요구사항 2.2)
  • 접근 제어: 사용자 개인정보 및 수면 데이터 접근은 역할 기반 최소 권한 원칙을 따라야 합니다. 모든 관리자 접근은 감사 로그에 기록되어야 합니다. 콜드 스토리지 접근은 전용 API를 통해서만 가능해야 합니다. (요구사항 2.2)
  • 데이터 침해 대응: 데이터 침해 발생 시 GDPR 규정에 따라 감독 기관 및 해당 사용자에게 통보할 수 있는 프로세스를 갖추어야 합니다. (요구사항 2.2)

8.6 관리자 도구 규칙​

  • 데이터 보관 정책(보관 기간, 비활성 기준 등)을 설정하고, 아카이빙/복원 프로세스를 모니터링 및 수동 제어할 수 있는 관리자 도구가 필요합니다. (요구사항 1.3, 3.12)

9. 변경 이력​

버전날짜작성자변경 내용
0.1.02025-04-15bok@weltcorp.com최초 작성
0.2.02025-04-19bok@weltcorp.com수면 기록 작성 시점의 rTIB 계산 규칙 추가
0.3.02025-04-30bok@weltcorp.com수면 기록 필수 입력 항목 상세화 및 didNotSleep에 따른 필수/선택 입력값 명확화
0.4.02025-05-04bok@weltcorp.com임시 수면 기록 규칙, DNS 상태 변경 시 데이터 초기화, 주차별 데이터 계산 및 조회 관련 규칙 추가
0.5.02025-05-04bok@weltcorp.com수면 기록 시간 검증 규칙, 데이터 조회 범위 유연성, 관리자 및 서비스 계정의 데이터 접근 규칙 추가
0.6.02025-05-05bok@weltcorp.com수면 기록 생성/수정 시 날짜 검증 제약 규칙 추가
0.7.02025-05-08bok@weltcorp.comrTIB 계산 조건 미충족 시 기존 rTIB 유지 규칙 추가
0.8.02025-05-12bok@weltcorp.com수면 기록 생성 시 날짜 대신 일차(dayIndex)만 사용하도록 변경
0.9.02025-05-13bok@weltcorp.comGDPR 준수 및 데이터 보관 정책 관련 규칙 추가 (데이터 관리 및 개인정보 보호 규칙 섹션 추가)
1.0.02025-08-20bok@weltcorp.com첫 rTIB 계산 조건 변경 (3개→4개 수면기록) 및 AET 목표 시간 제안 방식 개선 (평균→median) - 섹션 3.2, 3.8 수정