본문으로 건너뛰기

Learning 도메인 비즈니스 규칙

1. 수면탐구 레슨 관리 규칙​

1.1 레슨 해금 규칙​

  • 사용자는 처음에 1번 레슨만 해금된 상태로 시작합니다
  • 레슨 1번부터 일반 레슨 마지막까지는 이전 레슨 완료 시 다음 레슨이 즉시 해금됩니다
  • 사용자가 레슨을 완료하면 바로 다음 레슨이 해금되므로, 하루에도 여러 레슨을 완료하여 진행할 수 있습니다
  • 최종 레슨은 모든 일반 레슨 완료 여부와 관계없이 무조건 치료 기간 끝나는 날에 해금됩니다
  • 해금된 레슨은 영구적으로 이용 가능합니다
  • 해금 순서는 미리 정의된 학습 경로를 따릅니다
  • 해금되지 않은 레슨은 접근 제한됩니다

1.2 레슨 콘텐츠 관리 규칙​

  • 시스템은 레슨 ID와 메타데이터만 관리하며, 실제 콘텐츠는 모바일 앱에서 관리됩니다
  • 각 레슨은 single page로 구성된 단일 콘텐츠 단위로 관리됩니다
  • 레슨들은 세션 단위로 그룹핑하여 관리됩니다
  • 세션별 진행 상태를 추적하고 완료 여부를 관리합니다

1.3 레슨 추천 규칙​

  • 매일 하나의 레슨을 사용자에게 추천합니다
  • 치료 기간 마지막 날에는 사용자의 진도나 미완료 레슨 수와 관계없이 최종 레슨만을 추천합니다
  • 추천 로직은 사용자의 학습 진도에 따라 구분됩니다:
    1. 치료 기간 마지막 날: 최종 레슨만 추천 (모든 일반 레슨 완료 여부 및 사용자 진도와 관계없이, 다른 미완료 레슨이 있어도 최종 레슨만 추천)
    2. 진도가 빠른 사용자 (예정 진도보다 빠르게 학습):
      • 학습 시작일 기준 일차에 해당하는 레슨을 추천
      • 예: 4일차에 10번 레슨까지 학습했더라도 4번 레슨 추천
      • 이미 완료한 레슨이라도 1일 1레슨 기준으로 추천
    3. 진도가 느린 사용자 (예정 진도보다 느리게 학습):
      • 하루 하나의 레슨 추천 원칙에 따라 일관된 추천 제공:
        • 오늘 이미 추천한 레슨이 있는 경우: 완료 여부와 상관없이 동일한 레슨을 계속 추천
        • 오늘 아직 추천하지 않은 경우: 현재 완료한 레슨의 다음 번호 레슨을 추천
      • 예: 4일차에 2번 레슨까지만 학습했고 오늘 3번 레슨을 추천받았다면 → 완료 여부와 관계없이 3번 레슨 계속 추천
      • 예: 4일차에 2번 레슨까지만 학습했고 오늘 아직 추천받지 않았다면 → 3번 레슨 추천
    4. 정상 진도 사용자 (1일 1레슨):
      • 학습 시작일 기준 일차에 해당하는 레슨을 추천
  • 모든 일반 레슨이 완료된 경우, 복습 퀴즈 제공
  • 학습 일정에 따른 콘텐츠 제공 우선순위:
    • 1일차 ~ 일반 레슨 완료 기간: 레슨 추천 (1일 1레슨)
    • (일반 레슨 수 + 1)일차 이후: 복습 퀴즈 제공 (모든 일반 레슨 완료한 사용자에 한함)

1.4 레슨 완료 규칙​

  • 사용자가 레슨 끝까지 스크롤하거나 [완료] 버튼을 눌렀을 때 학습 완료로 기록
  • 부분적인 레슨 열람은 완료로 처리되지 않음
  • 학습 완료된 레슨도 재열람 가능
  • 학습 완료 상태는 서버에 저장되며 기기 변경 시에도 유지
  • 한 번 완료된 레슨은 취소할 수 없음
  • 해금된 레슨은 순서와 관계없이 완료 가능
  • 레슨 완료 시 다음 레슨이 자동으로 해금됨 (최종 레슨 제외)

1.5 진행률 관리 규칙​

  • 전체 진행률 = (완료한 콘텐츠 수 / 전체 콘텐츠 수) × 100%
  • 진행률은 실시간으로 업데이트
  • 진행률은 0%에서 100% 사이 값으로 표시
  • 진행률은 해금 여부와 관계없이 전체 레슨 기준으로 계산
  • 진행률은 소수점 2자리까지 표시 (예: 23.81%)
  • 모든 레슨 완료(100%) 시 복습 퀴즈 기능 해금

1.6 사용자 시작일 규칙​

  • 사용자 계정 생성 시 학습 시작일 자동 설정
  • 학습 시작일은 최종 레슨 해금 일정의 기준점이 됩니다

1.7 레슨 상태 관리 규칙​

  • 레슨은 다음 5가지 상태로 관리됩니다:
    1. 미해금 상태(LOCKED): 아직 해금이 되지 않은 상태
    2. 열람 가능 상태(UNLOCKED): 해금이 되어 열람이 가능한 상태
    3. 열람 불가 상태(BLOCKED): 특정 조건에 의해 해금되었지만 열람이 제한된 상태
    4. 열람 중 상태(IN_PROGRESS): 해금이 되었고 현재 열람 중인 상태
    5. 완료 상태(COMPLETED): 열람을 완료한 상태
  • 레슨 상태 간 관계:
    • 열람 중(IN_PROGRESS) 상태는 열람 가능(UNLOCKED) 상태의 확장으로, 사용자가 실제로 레슨 콘텐츠에 접근했음을 나타냄
    • 열람 중(IN_PROGRESS)과 열람 가능(UNLOCKED) 상태의 레슨 모두 콘텐츠 접근 권한이 있음
    • UI에서는 열람 중(IN_PROGRESS) 상태를 현재 접근 중인 레슨으로 시각적으로 강조하여 표시
  • 레슨 상태 전환 규칙:
    • 계정 생성 시 1번 레슨만 UNLOCKED 상태로 시작
    • 이전 번호 레슨이 완료되면 다음 번호 레슨이 자동으로 LOCKED → UNLOCKED로 변경됨 (최종 레슨 제외)
    • 최종 레슨은 모든 일반 레슨 완료 여부와 관계없이 치료 기간 끝나는 날에 LOCKED → UNLOCKED로 변경됨
    • 사용자가 레슨 콘텐츠에 접근 시 UNLOCKED → IN_PROGRESS로 변경됨
    • BLOCKED 상태의 레슨 접근 시도 시 열람 불가 메시지 표시 (상태 변경 없음)
    • 사용자가 레슨 끝까지 스크롤하여 [완료] 버튼을 누르면 IN_PROGRESS → COMPLETED로 변경됨
    • 한번 COMPLETED 상태가 된 레슨은 다시 다른 상태로 변경되지 않음
  • 레슨 상태에 따른 접근 제어:
    • LOCKED, BLOCKED 상태의 레슨은 콘텐츠에 접근할 수 없음
    • UNLOCKED, IN_PROGRESS, COMPLETED 상태의 레슨은 콘텐츠에 접근 가능

1.8 레슨 접근 및 업데이트 규칙​

  • 사용자가 레슨에 접근할 때마다 상태를 업데이트하고 마지막 접근 시간을 기록합니다
  • 레슨 완료 시 다음 레슨이 해금되었다는 알림을 제공합니다

2. 텍스트 설정 규칙​

2.1 텍스트 크기 조절 규칙​

  • 텍스트 크기는 배율로 조정 가능합니다
  • 기본 Body 텍스트 크기: 16pt
  • 한번 지정한 텍스트 크기를 레슨 전체에 동일하게 적용합니다
  • 설정은 사용자 계정에 저장되어 기기 변경 시에도 유지됩니다
  • 텍스트 크기 조절 UI를 제공하고 실시간으로 크기 미리보기를 표시합니다
  • 오프라인 상태에서도 마지막 설정을 유지합니다
  • 설정 변경 시 즉시 저장 및 적용됩니다
  • 레슨의 텍스트 크기를 시스템 접근성 폰트 크기와 별개로 관리합니다

2.2 TTS(음성 읽기) 기능 규칙​

  • TTS 기능은 [오디오] 버튼으로 활성화/비활성화합니다
  • 지원 언어: 독일어, 영어
  • TTS 기본 설정: 비활성화, 독일어, 보통 속도 (임상시험 버전에서는 제외)
  • 재생 속도 옵션: 기본, 느림, 빠름 중 선택 가능 (임상시험 버전에서는 제외)
  • TTS 활성화 시 재생 중인 문장을 파란색으로 강조 표시 (임상시험 버전에서는 제외)
  • 재생 제어 기능: 시작, 일시정지, 중단 (임상시험 버전에서는 제외)
  • Background TTS 재생 기능은 제공하지 않습니다
  • TTS 사용 전 단말기 용량을 확인하여 부족할 시 사용자에게 알림
  • [오디오] 버튼 탭 시 백엔드로부터 음성 파일을 다운로드하여 재생
  • TTS 설정은 사용자 계정에 저장됩니다

2.3 설정 동기화 규칙​

  • 설정은 사용자 계정과 연결하여 영구 저장합니다
  • 모든 기기에서 동일한 설정을 적용할 수 있도록 동기화 기능을 제공합니다
  • 오프라인 상태에서도 마지막 설정을 유지합니다
  • 설정 변경 시 즉시 저장 및 적용됩니다

3. 미디어 관리 규칙​

3.1 이미지 관리 규칙​

  • 시스템은 이미지 파일의 메타데이터와 참조 정보만 관리하며, 실제 미디어 파일은 모바일 앱에서 관리합니다
  • 본문 내 이미지 탭 시 이미지 오버레이 화면을 전체 화면으로 표시합니다
  • 이미지 확대/축소는 두 손가락 제스처로 제어합니다
  • 최대 확대 배율: 원본의 2배
  • 최소 축소 배율: 원본 크기
  • 확대/축소 상태는 제스처 후에도 유지됩니다
  • 이미지 오버레이 화면에서 배경 탭 시 본문 화면으로 돌아갑니다
  • 미디어 파일 메타데이터에서 개인정보(EXIF 데이터 등)를 자동으로 제거합니다

3.2 영상 관리 규칙​

  • 실제 미디어 파일은 Backend에서 관리되며 메타데이터에 download URL을 제공합니다
  • 영상 재생은 iOS 기본 비디오 플레이어를 사용합니다
  • 지원 형식: MP4, MOV
  • 영상 플레이어는 전체화면 모드만 지원합니다
  • Backend에서 제공하는 download URL을 통해 영상을 스트리밍 또는 다운로드하여 재생할 수 있습니다

3.3 오디오 클립 관리 규칙​

  • 실제 미디어 파일은 Backend에서 관리되며 메타데이터에 download URL을 제공합니다
  • 오디오 클립은 레슨 본문 내에 삽입되어 해당 레슨에 대한 부가 설명을 제공합니다
  • 오디오 클립은 TTS와 구별되는 미리 녹음된 콘텐츠입니다
  • 재생 제어 기능을 제공합니다: 재생, 일시정지, 중단
  • 재생 상태(재생/일시정지/중단) 및 재생 진행률을 시각적으로 표시합니다
  • 다른 오디오(TTS 포함) 재생 시 기존 재생 중인 오디오를 자동으로 중단하여 오디오 충돌을 방지합니다
  • 지원 형식: MP3, AAC, WAV
  • Backend에서 제공하는 download URL을 통해 오디오 클립을 스트리밍 또는 다운로드하여 재생할 수 있습니다
  • 재생 완료 후 재생 버튼 상태를 자동으로 초기화합니다
  • 오디오 클립과 TTS는 별도의 재생 컨트롤러로 관리하여 독립적으로 동작합니다

3.4 미디어 접근 제어 규칙​

  • 미디어가 속한 레슨이 해금된 사용자만 접근 가능합니다
  • 레슨별 미디어 자원 목록과 식별자를 제공합니다
  • 모든 미디어 URL이 서명되어야 하며 만료 시간이 설정되어야 합니다

3.5 콘텐츠 보안 규칙​

  • 모든 학습 콘텐츠 및 미디어 파일에 대해 직접적인 외부 스토리지 URL 노출을 금지합니다
  • 콘텐츠 요청 시 App Token을 통한 디바이스 무결성 검증을 수행합니다
  • 사용자 식별 정보는 POST 요청의 body에만 포함하여 로깅 및 캐싱 위험을 최소화합니다
  • GET 방식을 통한 URL 파라미터나 헤더를 통한 민감정보 전송을 금지합니다
  • JSON 콘텐츠는 API 응답에 직접 포함하여 제공하고, 미디어 파일만 Google Cloud Storage Signed URL을 생성하여 제공합니다
  • 콘텐츠 제공 방식은 유형에 따라 차등 적용합니다:
    • JSON 콘텐츠: API 응답에 직접 포함 (별도 만료시간 없음)
    • 미디어 파일: Signed URL 제공 (30분 유효)
  • 콘텐츠 접근 시 다음 순서로 보안 검증을 수행합니다:
    1. App Token 유효성 검증 (Auth 도메인 연동)
    2. 사용자 레슨 해금 상태 확인
    3. 요청된 콘텐츠의 접근 권한 검증
    4. 해금되지 않은 경우 접근 거부, 해금된 경우 JSON 콘텐츠 직접 응답

4. 복습 퀴즈 규칙​

4.1 퀴즈 제공 자격 및 시작 시점​

  • 모든 일반 레슨(현재 45개)을 완료한 사용자에게만 제공됩니다
  • 복습 퀴즈 제공 시작 시점은 사용자의 학습 진도에 따라 다릅니다:
    1. 빠른 진도 사용자 ((일반 레슨 수 + 1)일차 이전에 모든 일반 레슨 완료):
      • 학습 시작일로부터 (일반 레슨 수 + 1)일차부터 퀴즈 제공 시작
      • 일반 레슨 완료 기간까지는 레슨 추천이 우선되므로 대기
    2. 정상 진도 사용자 (일반 레슨 완료 기간에 모든 일반 레슨 완료):
      • (일반 레슨 수 + 1)일차부터 퀴즈 제공 시작 (완료 다음날)
    3. 느린 진도 사용자 ((일반 레슨 수 + 1)일차 이후에 모든 일반 레슨 완료):
      • 모든 일반 레슨 완료 다음날부터 즉시 퀴즈 제공 시작
  • 예시:
    • 1일차에 모든 일반 레슨을 완료한 경우: (일반 레슨 수 + 1)일차부터 퀴즈 제공
    • 일반 레슨 완료 기간에 모든 일반 레슨을 완료한 경우: (일반 레슨 수 + 1)일차부터 퀴즈 제공
    • 50일차에 모든 일반 레슨을 완료한 경우: 51일차부터 퀴즈 제공

4.2 퀴즈 제공 주기 및 진행 규칙​

  • 퀴즈는 제공 시작일부터 치료 기간 만료 전날까지 매일 하루에 1개씩 제공됩니다 (치료 완료일에는 퀴즈를 제공하지 않음)
  • 중요: 퀴즈 제공은 사용자의 퀴즈 완료 여부와 무관하게 날짜 기준으로 진행됩니다
  • 퀴즈 진행 방식:
    • 매일 지정된 순서의 퀴즈를 제공
    • 사용자가 해당 퀴즈를 완료하지 않았더라도 다음 날에는 다음 순서의 퀴즈를 제공
    • 이전 퀴즈가 미완료 상태여도 새로운 퀴즈가 추가로 제공됨
  • 예시 (정상 진도 사용자, 일반 레슨 수 45개 가정):
    • 46일차: 1번 레슨 관련 퀴즈 제공 (사용자가 완료하지 않음)
    • 47일차: 2번 레슨 관련 퀴즈 제공 (1번 퀴즈 미완료여도 2번 퀴즈 추가 제공)
    • 48일차: 3번 레슨 관련 퀴즈 제공 (1, 2번 퀴즈 미완료여도 3번 퀴즈 추가 제공)

4.3 퀴즈 순서 및 내용 규칙​

  • 복습 퀴즈는 1번 레슨부터 일반 레슨 마지막까지의 내용을 순차적으로 다룹니다
  • 각 퀴즈는 해당 번호의 레슨 내용을 기반으로 출제됩니다
  • 퀴즈 제공 순서 예시 (일반 레슨 수 45개, 정상 진도 사용자):
    • (일반 레슨 수 + 1)일차 = 46일차 → 1번 레슨 관련 퀴즈
    • (일반 레슨 수 + 2)일차 = 47일차 → 2번 레슨 관련 퀴즈
    • (일반 레슨 수 + 3)일차 = 48일차 → 3번 레슨 관련 퀴즈
    • ... 순차적으로 진행
  • 퀴즈 순서는 사용자의 실제 학습 순서와 무관하게 레슨 번호 순서를 따릅니다
  • 퀴즈가 관련된 수면탐구 레슨과 연결되도록 관리됩니다
  • 퀴즈 내용을 정기적으로 업데이트할 수 있습니다

4.4 퀴즈 풀이 규칙​

  • 퀴즈 유형: O/X 또는 객관식(사지선다형)을 관리합니다
  • 각 퀴즈는 단일 선택만 가능합니다
  • 답변 선택 시 [다음] 버튼을 활성화합니다
  • 정답 제출 후 결과를 즉시 확인할 수 있습니다
  • 오답 선택 시에도 정답과 설명을 제공합니다
  • 한번 푼 퀴즈도 [다시 풀기] 버튼으로 재시도 가능합니다
  • 퀴즈 재시도 시 최종 입력된 결과가 정답률 통계에 반영됩니다
  • [관련 레슨으로 이동] 버튼을 제공하여 연관된 수면탐구 레슨으로 이동할 수 있습니다

4.6 퀴즈 결과 관리 규칙​

  • 퀴즈 결과를 기록하고 관리합니다
  • 사용자별 퀴즈 정답률 통계를 제공합니다
  • 퀴즈 결과(정답/오답)는 서버에 기록됩니다
  • 퀴즈 이력은 사용자 계정에 저장되어 확인 가능합니다
  • 퀴즈 재시도 시 다음과 같이 처리됩니다:
    • 이전 결과는 덮어쓰기되며, 최종 결과만 저장됩니다
    • 정답률은 각 퀴즈의 최종 결과를 기준으로 계산됩니다
    • 재시도 횟수는 기록하지만 통계에는 영향을 주지 않습니다
  • 각 퀴즈 응답에는 응답한 퀴즈의 버전 정보가 함께 기록됩니다

4.7 퀴즈 버전 관리 규칙​

  • 퀴즈는 버전 관리를 통해 개선 및 업데이트를 추적합니다
  • 각 퀴즈는 생성 시 버전 1로 시작합니다
  • 퀴즈 내용이 변경될 때마다 새로운 버전이 생성됩니다
  • 사용자는 항상 최신 활성 버전의 퀴즈를 제공받습니다
  • 이전 버전의 퀴즈 응답 데이터는 보존되어 성능 비교 분석에 활용됩니다
  • 퀴즈 버전 변경 시 다음 규칙을 따릅니다:
    • 문제 내용, 선택지, 정답 변경 시 새 버전 생성
    • 설명 텍스트만 변경된 경우는 동일 버전 유지
    • 버전 번호는 순차적으로 증가 (1, 2, 3...)
  • 퀴즈 성능 분석 규칙:
    • 정답률이 30% 미만인 경우: 너무 어려움 → 개선 권장
    • 정답률이 90% 초과인 경우: 너무 쉬움 → 개선 권장
    • 평균 응답 시간이 너무 짧거나 긴 경우 검토 필요
  • 레슨 버전 업데이트 시 관련 퀴즈도 다음과 같이 처리합니다:
    • 레슨 내용의 중요한 변경이 있을 경우 퀴즈 버전 업데이트 검토
    • 레슨과 퀴즈의 내용 일관성 유지
    • 필요시 새로운 퀴즈 버전 생성

5. 세션 관리 규칙​

5.1 세션 그룹핑 규칙​

  • 여러 레슨을 세션 단위로 그룹화하여 관리합니다
  • 세션별 진행 상태를 추적하고 완료 여부를 관리합니다
  • 세션 단위로 확장/축소 가능한 목록 UI를 제공합니다
  • 세션 완료 상태를 시각적 요소(체크 표시 등)로 표현합니다

6. 보안 규칙​

6.1 데이터 접근 규칙​

  • 사용자는 자신의 학습 데이터만 접근 가능합니다
  • 모든 API 요청에 대해 사용자 인증을 검증합니다
  • 사용자 간 데이터 접근 제한을 엄격히 관리합니다
  • 인증되지 않은 요청은 거부됩니다
  • 관리자만 전체 사용자의 학습 통계 접근 가능합니다

6.2 데이터 보호 규칙​

  • 학습 진행 데이터를 백업 정책에 따라 정기 백업합니다
  • 모든 액세스에 대한 로그를 기록합니다
  • 미디어 파일 메타데이터에서 개인정보를 자동 제거합니다 (EXIF 데이터 등)
  • 모든 미디어 URL은 서명되어야 하며 만료 시간을 설정합니다

6.3 콘텐츠 전송 보안 규칙​

  • 모든 콘텐츠 요청은 App Token으로 디바이스 검증을 수행합니다
  • 민감정보는 POST request body로만 전송하여 로깅/캐싱 위험을 방지합니다
  • 직접 클라우드 스토리지 URL 노출을 금지하고 Signed URL만 제공합니다
  • 콘텐츠 유형별 차등 만료시간을 적용합니다 (JSON: 1시간, 미디어: 30분)
  • 해금되지 않은 콘텐츠 요청 시 403 Forbidden으로 접근을 거부합니다

7. 성능 규칙​

7.1 응답 시간 규칙​

  • 콘텐츠 조회: 1초 이내
  • 퀴즈 결과 기록: 500ms 이내
  • 이미지 로딩: 2초 이내
  • 영상 버퍼링: 3초 이내
  • 오디오 클립 로딩: 2초 이내
  • 진행률 조회: 100ms 이내
  • 설정 조회: 100ms 이내
  • 설정 업데이트: 200ms 이내

7.2 동시 접속 처리 규칙​

  • 최소 5,000명 이상의 동시 접속자 처리
  • 부하 증가 시 자동 스케일링이 가능해야 합니다
  • 각 API의 초당 최대 요청 수 제한을 적용합니다
  • 비정상적인 접근 패턴을 감지하고 차단할 수 있어야 합니다

8. 변경 이력​

버전날짜작성자변경 내용
0.1.02025-04-03bok@weltcorp.com최초 작성
0.2.02025-05-23bok@weltcorp.comrequirements.md 변경사항 반영 - 하이라이트/사용자 입력 기능 제거, 세션 관리 규칙 추가, TTS/미디어 관리 규칙 업데이트
0.2.12025-06-09bok@weltcorp.com퀴즈 버전 관리 규칙 추가 - 버전 관리, 성능 분석, 레슨 연동 규칙 추가
0.3.02025-06-10bok@weltcorp.com오디오 클립 기능 추가 - 레슨 본문 내 부가 설명용 오디오 재생 기능 비즈니스 규칙 추가