본문으로 건너뛰기

External Health 도메인 요구사항

1. 개요​

1.1 도메인 목적​

External Health 도메인은 iOS HealthKit, Android Health Connect 등 외부 건강 데이터 플랫폼과 연동하여 사용자의 건강 데이터를 수집하고, LLM/AI Agent가 분석에 활용할 수 있는 형태로 제공하는 것을 목적으로 한다.

1.2 핵심 가치​

  • 개인화된 데이터 수집: 모든 사용자에게 동일한 데이터를 수집하는 것이 아니라, 백엔드(LLM/Agent)가 각 사용자별로 분석하여 필요한 데이터만 선택적으로 요청
  • LLM 친화적 데이터 포맷: 수집된 데이터를 LLM이 이해하기 쉬운 Verbose Fields와 집계(Interval Sum/Average) 형태로 가공하여 제공
  • 최적의 졸립지 섭취 시각 계산: 수집된 건강 데이터를 기반으로 LLM이 개인화된 분석 수행

1.3 Data Flow 개요​

전체 흐름​

개인화된 데이터 수집 예시​

시퀀스 다이어그램​

2. 기능 요구사항​

참고: 본 도메인의 모든 기능 요구사항에서 시간 관련 처리(타임스탬프, 기간 계산, 날짜 비교 등)는 반드시 TimeMachine 도메인이 제공하는 현재 시간(가상 또는 실제)을 기준으로 수행되어야 합니다. 시스템 시간을 직접 사용해서는 안 됩니다. (제약사항 4.6 참조)

2.1 개인화된 데이터 수집 요청 관리​

백엔드 요구사항​

  • EXH-FR-BE-001: 시스템은 LLM/Agent의 분석 결과를 기반으로 사용자별 개인화된 데이터 수집 요청(Data Collection Request)을 생성하고 관리해야 한다.

    • 데이터 수집 요청 항목:
      • 요청 ID (UUID)
      • 데이터 유형 (type): stepCount, heartRate, sleepAnalysis, heartRateVariability, respiratoryRate, oxygenSaturation
      • 수집 시작 시각 (startTime): Unix Epoch Time (milliseconds)
      • 수집 종료 시각 (endTime): Unix Epoch Time (milliseconds)
      • 집계 간격 (interval): 선택적
        • 간격 유형 (type): year, month, day, hour, minute, second
        • 간격 값 (value): 정수
    • 집계 간격이 없는 경우 Raw Data 반환

  • EXH-FR-BE-002: 시스템은 사용자별 활성화된 데이터 수집 요청 목록을 조회하는 API를 제공해야 한다.

    • 앱이 실행될 때마다 해당 API를 호출하여 수집해야 할 데이터 목록 확인
    • 요청 목록이 비어있는 경우 빈 배열 반환 (수집할 데이터 없음)

  • EXH-FR-BE-003: 시스템은 LLM/Agent가 사용자별로 다른 데이터 수집 요청을 생성할 수 있도록 API를 제공해야 한다.

    • Multi-Agent Orchestration 도메인과 연동
    • 사용자의 치료 단계, 수면 패턴, 건강 상태에 따라 필요한 데이터 유형 및 기간 결정
    • 데이터 수집 요청 생성/수정/삭제 API

  • EXH-FR-BE-004: 시스템은 완료된 데이터 수집 요청을 추적하고 관리해야 한다.

    • 요청별 상태 관리: PENDING, COLLECTED, EXPIRED, CANCELLED
    • 수집 완료된 요청은 COLLECTED 상태로 변경
    • 응답이 없는 오래된 요청은 EXPIRED 처리

프론트엔드 요구사항​

  • EXH-FR-FE-001: 앱은 다음 두 시점에서 데이터 수집 플로우를 실행해야 한다.
    • Onboarding 완료 시점: HealthKit/Health Connect 권한 동의 후 즉시 데이터 수집 시작
    • Home Screen 진입 시점: 앱 실행 또는 Home Screen 표시 시 데이터 수집 시작
  • EXH-FR-FE-002: 데이터 수집 플로우는 다음 순서로 실행되어야 한다.
    1. GET /external-health/requests - 대기 중인 데이터 수집 요청 조회
    2. HealthKit/Health Connect SDK를 통해 요청된 데이터 수집
    3. POST /external-health/responses - 수집된 데이터 서버에 제출
  • EXH-FR-FE-003: 데이터 수집 실패 시에도 앱의 주요 플로우(Onboarding, Home Screen 표시)는 차단되지 않아야 한다.

2.2 데이터 수집 요청 조회 (GET)​

백엔드 요구사항​

  • EXH-FR-BE-005: 시스템은 앱이 수집해야 할 데이터 목록을 조회할 수 있는 API를 제공해야 한다.

    • API 응답 스키마:
    {
      "requests": [
        {
          "id": "UUID",
          "type": "stepCount | heartRate | sleepAnalysis | ...",
          "startTime": 1764550800000,
          "endTime": 1764637200000,
          "interval": {
            "type": "year | month | day | hour | minute | second",
            "value": 1
          }
        }
      ]
    }
    • requests: 수집해야 할 데이터 요청 배열 (최소 빈 배열)
    • interval: 선택적 필드, 없을 경우 Raw Data 수집

  • EXH-FR-BE-005-1: 시스템은 데이터 수집 요청 조회 시 사용자의 권한을 검증해야 한다.

    • 필요한 데이터 유형에 대한 권한이 없는 경우, 적절한 오류 응답 반환 (에러 코드: PERMISSION_NOT_GRANTED)
    • 권한이 있는 데이터 유형의 요청만 필터링하여 반환하는 옵션 제공
    • 권한 관련 응답 스키마:
    {
      "code": 21022,
      "message": "PERMISSION_NOT_GRANTED",
      "detail": "요청된 데이터 유형에 대한 권한이 승인되지 않았습니다.",
      "requiredPermissions": ["heartRate", "sleepAnalysis"],
      "grantedPermissions": ["stepCount"]
    }

  • EXH-FR-BE-006: 시스템은 지원하는 데이터 유형(type)을 정의해야 한다.

    • Quantity 타입 (수치 데이터):
      • stepCount: 걸음 수
      • heartRate: 심박수
      • heartRateVariability: 심박변이도
      • respiratoryRate: 호흡수
      • oxygenSaturation: 산소포화도
      • activeEnergyBurned: 활동 에너지
    • Category 타입 (범주형 데이터):
      • sleepAnalysis: 수면 분석 (수면 단계 포함)

프론트엔드 요구사항​

  • EXH-FR-FE-004: 앱은 GET /external-health/requests API 호출 시 현재 플랫폼(iOS/Android)을 파라미터로 전달해야 한다.
  • EXH-FR-FE-005: 앱은 filterByGrantedPermissions=true 옵션을 사용하여 승인된 권한에 해당하는 요청만 조회해야 한다.
  • EXH-FR-FE-006: 요청 목록이 비어있는 경우(requests: []) 데이터 수집 단계를 건너뛰어야 한다.

2.3 수집 데이터 제출 (POST)​

백엔드 요구사항​

  • EXH-FR-BE-007: 시스템은 앱에서 수집한 건강 데이터를 수신하는 API를 제공해야 한다.

    • API 요청 스키마:
    {
      "responses": [
        {
          "requestId": "UUID",
          "os": "iOS | Android",
          "type": "stepCount | heartRate | sleepAnalysis | ...",
          "startTime": "2025-12-01T10:00:00.000+09:00",
          "endTime": "2025-12-02T10:00:00.000+09:00",
          "interval": {
            "type": "day",
            "value": 1
          },
          "extractedAt": "2025-12-03T07:00:00.000+09:00",
          "records": [
            {
              "startTime": "2025-12-01T10:00:00.000+09:00",
              "endTime": "2025-12-02T10:00:00.000+09:00",
              "sum": 100,
              "average": 110.123,
              "category": "inBed | asleepCore | asleepDeep | asleepREM | awake",
              "unit": "count | count/min | %"
            }
          ]
        }
      ]
    }

  • EXH-FR-BE-008: 시스템은 수신된 데이터를 검증하고 저장해야 한다.

    • requestId와 기존 요청 매칭 확인
    • 시간 형식 검증 (ISO8601 + TimeZone)
    • 데이터 유효 범위 검증
    • 중복 데이터 감지 및 처리 (멱등성)

  • EXH-FR-BE-009: 시스템은 수집 데이터의 메타데이터를 함께 저장해야 한다.

    • os: 수집 플랫폼 (iOS/Android)
    • extractedAt: 앱에서 데이터를 추출한 시각
    • 원본 시간대(TimeZone) 정보 보존

  • EXH-FR-BE-010: 시스템은 백그라운드 업로드를 지원해야 한다.

    • iOS: Background URLSession 활용
    • Android: WorkManager 활용
    • 업로드 실패 시 재시도 메커니즘

프론트엔드 요구사항​

  • EXH-FR-FE-007: 앱은 각 요청(request)에 대해 HealthKit/Health Connect SDK를 통해 해당 데이터를 수집해야 한다.
  • EXH-FR-FE-008: 앱은 수집된 데이터를 API 스키마에 맞게 변환하여 POST /external-health/responses로 제출해야 한다.
  • EXH-FR-FE-009: 앱은 데이터 추출 시각(extractedAt)을 정확하게 기록해야 한다.
  • EXH-FR-FE-010: 앱은 시간 데이터를 ISO8601 형식(TimeZone 포함)으로 전송해야 한다.

2.4 데이터 집계 및 변환​

백엔드 요구사항​

  • EXH-FR-BE-011: 시스템은 Quantity 타입 데이터에 대해 집계를 지원해야 한다.

    • sum: 합계 (예: 걸음 수, 활동 에너지)
    • average: 평균 (예: 심박수, HRV)
    • 집계 단위: year, month, day, hour, minute, second

  • EXH-FR-BE-012: 시스템은 Category 타입 데이터에 대해 Raw Data 형태로 저장해야 한다.

    • 수면 분석 데이터는 각 수면 단계별 시작/종료 시각과 카테고리 저장
    • 수면 단계 카테고리:
      • iOS HealthKit: inBed, asleepUnspecified, awake, asleepCore, asleepDeep, asleepREM
      • Android Health Connect: awake, sleeping, out_of_bed, light, deep, rem

  • EXH-FR-BE-013: 시스템은 LLM이 이해하기 쉬운 Verbose Fields로 데이터를 변환해야 한다.

    • 약어 → 명확한 필드명 변환 (Agent Data 도메인 연동)
    • 단위 정보 명시
    • 컨텍스트 정보 추가 (치료 일차, 요일 등)

프론트엔드 요구사항​

  • EXH-FR-FE-011: 앱은 Quantity 타입 데이터(stepCount, heartRate 등) 수집 시 SDK가 제공하는 집계 기능을 활용해야 한다.
  • EXH-FR-FE-012: 앱은 Category 타입 데이터(sleepAnalysis) 수집 시 각 수면 단계별 Raw Data를 수집해야 한다.
  • EXH-FR-FE-013: 앱은 interval 설정이 있는 요청의 경우 해당 간격으로 집계된 데이터를 제출해야 한다.

2.5 외부 플랫폼 연동 관리​

백엔드 요구사항​

  • EXH-FR-BE-014: 시스템은 iOS HealthKit 연동을 지원해야 한다.

    • 수집 가능한 데이터 유형:
      • 수면 분석 (Sleep Analysis): 수면 시작/종료 시각, 수면 단계
      • 심박수 (Heart Rate): BPM, 측정 시각
      • 심박변이도 (HRV): SDNN, 측정 시각
      • 호흡수 (Respiratory Rate): 분당 호흡수
      • 산소포화도 (Blood Oxygen): SpO2 %
      • 걸음 수 (Step Count)
      • 활동 에너지 (Active Energy Burned)
    • HealthKit 권한 요청 및 승인 상태 관리

  • EXH-FR-BE-015: 시스템은 Android Health Connect 연동을 지원해야 한다.

    • 수집 가능한 데이터 유형:
      • 수면 세션 (Sleep Session): 수면 시작/종료 시각, 수면 단계
      • 심박수 (Heart Rate): BPM, 측정 시각
      • 심박변이도 (HRV): RMSSD, 측정 시각
      • 호흡수 (Respiratory Rate): 분당 호흡수
      • 산소포화도 (Oxygen Saturation): SpO2 %
      • 걸음 수 (Steps)
      • 활동 에너지 (Active Calories Burned)
    • Health Connect 권한 요청 및 승인 상태 관리

  • EXH-FR-BE-016: 시스템은 플랫폼별 데이터를 통합된 내부 형식으로 정규화해야 한다.

    • 수면 단계 매핑:
      • HealthKit awake / Health Connect awake → 내부 AWAKE
      • HealthKit asleepREM / Health Connect rem → 내부 REM
      • HealthKit asleepCore / Health Connect light → 내부 LIGHT
      • HealthKit asleepDeep / Health Connect deep → 내부 DEEP
    • HRV 단위 통합 (SDNN/RMSSD → 밀리초)
    • 시간대 정보 UTC 변환 및 원본 보존

  • EXH-FR-BE-017: 시스템은 외부 플랫폼 연동 상태를 관리해야 한다.

    • 연동된 플랫폼 목록 조회
    • 플랫폼별 권한 승인 상태 조회
    • 플랫폼별 마지막 동기화 시각 조회
    • 플랫폼 연동 해제 기능

프론트엔드 요구사항​

  • EXH-FR-FE-014: 앱은 Onboarding 시 HealthKit(iOS) 또는 Health Connect(Android) 권한 동의를 요청해야 한다.
  • EXH-FR-FE-015: 앱은 권한 동의 완료 후 즉시 GET /external-health/requests를 호출하여 데이터 수집을 시작해야 한다.
  • EXH-FR-FE-016: 앱은 설정 화면에서 플랫폼 연동 해제 기능을 제공해야 한다.
  • EXH-FR-FE-017: 앱은 권한 거부 또는 연동 해제 시 적절한 안내 메시지를 표시해야 한다.

2.6 수면 데이터 연동​

백엔드 요구사항​

  • EXH-FR-BE-018: 시스템은 외부 플랫폼에서 수집한 수면 데이터를 Sleep 도메인과 연동해야 한다.

    • 외부 수면 데이터를 임시 수면 기록(Temporary Sleep Log)으로 자동 생성
    • 사용자가 수면 기록 작성 시 외부 데이터를 기본값으로 제안
    • 매핑:
      • 외부 수면 시작 시각 → Sleep 도메인 LOT
      • 외부 수면 종료 시각 → Sleep 도메인 AET
      • 외부 각성 시간 합계 → Sleep 도메인 WASO 제안값

  • EXH-FR-BE-019: 시스템은 수면 단계 데이터를 분석하여 수면 품질 지표를 계산해야 한다.

    • 수면 단계별 시간 비율 계산 (REM, Light, Deep, Awake)
    • 수면 효율 추정값 계산
    • 수면 분절 횟수 계산

프론트엔드 요구사항​

  • EXH-FR-FE-018: 앱은 수면 데이터(sleepAnalysis) 수집 시 모든 수면 단계(inBed, asleepCore, asleepDeep, asleepREM, awake)를 포함해야 한다.
  • EXH-FR-FE-019: 앱은 수면 기록 작성 화면에서 외부 플랫폼 데이터를 기본값으로 표시할 수 있어야 한다 (서버에서 제공 시).

2.7 데이터 품질 관리​

백엔드 요구사항​

  • EXH-FR-BE-020: 시스템은 수집된 데이터의 품질을 검증해야 한다.

    • 데이터 유효 범위 검증:
      • 심박수: 30-250 BPM
      • 산소포화도: 70-100%
      • 호흡수: 4-60회/분
      • 수면 시간: 0-24시간
    • 이상치 자동 감지 및 플래그 처리
    • 데이터 무결성 검증 (타임스탬프 순서, 중복 등)

  • EXH-FR-BE-021: 시스템은 데이터 소스별 메타데이터를 저장해야 한다.

    • 디바이스 모델 (hardwareModel)
    • 소프트웨어 버전 (softwareVersion)
    • 앱 버전 (appVersion)
    • 데이터 소스 (source)

프론트엔드 요구사항​

  • EXH-FR-FE-020: 앱은 데이터 수집 시 SDK에서 제공하는 디바이스/소스 메타데이터를 함께 전송해야 한다 (선택적).
  • EXH-FR-FE-021: 앱은 데이터 수집 실패 시 로컬에 캐싱하고 이후 재시도해야 한다.

2.8 관리자 및 서비스 계정의 외부 건강 데이터 접근​

백엔드 요구사항​

  • EXH-FR-BE-022: 시스템은 적절한 권한을 가진 역할의 사용자가 외부 건강 데이터에 접근할 수 있도록 해야 한다.

    • System Admin: 모든 사용자의 외부 건강 데이터 및 연동 상태에 접근 가능
    • IAM Admin: 관리 권한이 할당된 범위 내 사용자들의 데이터에 접근 가능
    • Service Account: 할당된 권한에 따라 특정 사용자 또는 익명화된 집계 데이터에 접근 가능

  • EXH-FR-BE-023: 시스템은 다음과 같은 관리용 API를 제공해야 한다.

    • 사용자별 데이터 수집 요청 현황 조회
    • 데이터 수집 완료율 통계
    • 플랫폼별 데이터 수집 통계
    • 데이터 품질 대시보드

  • EXH-FR-BE-024: 시스템은 관리자 접근에 대한 감사 로그를 기록해야 한다.

프론트엔드 요구사항​

  • EXH-FR-FE-022: 관리자/의료진 웹앱은 사용자별 외부 건강 데이터 수집 현황을 조회할 수 있어야 한다.
  • EXH-FR-FE-023: 관리자 웹앱은 데이터 수집 통계 대시보드를 제공해야 한다 (선택적).

3. 비기능 요구사항​

3.1 성능​

  • EXH-NFR-001: 데이터 수집 요청 조회 API(GET)는 500ms 이내에 응답해야 한다.
  • EXH-NFR-002: 데이터 제출 API(POST)는 1000개 레코드 기준 5초 이내에 처리 완료되어야 한다.
  • EXH-NFR-003: 백그라운드 업로드는 배터리 소모를 최소화해야 한다 (1회 동기화당 배터리 1% 미만).
  • EXH-NFR-004: 대량 데이터 처리 시 메모리 사용량을 제한해야 한다 (페이징 처리).

3.2 보안​

  • EXH-NFR-005: 외부 건강 데이터는 사용자의 민감 정보로 간주되어 안전하게 저장 및 전송되어야 한다.
  • EXH-NFR-006: (공통 정책 참조) 데이터 암호화는 Platform 도메인 표준을 따른다:
  • EXH-NFR-007: 데이터 제출 API는 인증된 사용자만 접근 가능해야 한다.
  • EXH-NFR-008: requestId 검증을 통해 권한 없는 데이터 제출을 방지해야 한다.

3.3 가용성​

  • EXH-NFR-009: 데이터 수집 요청 조회 API는 99.9% 이상의 가용성을 유지해야 한다.
  • EXH-NFR-010: (공통 정책 참조) 가용성/재해복구/백업 기준은 Platform 도메인의 정책을 따른다.
  • EXH-NFR-011: 서버 장애 시에도 앱은 로컬에 데이터를 캐싱하고 복구 후 재전송해야 한다.

3.4 호환성​

  • EXH-NFR-012: iOS 15.0 이상의 HealthKit API를 지원해야 한다.
  • EXH-NFR-013: Android API Level 28 (Android 9.0) 이상의 Health Connect를 지원해야 한다.
  • EXH-NFR-014: 향후 추가 외부 플랫폼 연동을 위한 확장 가능한 아키텍처를 유지해야 한다.

3.5 운영 품질 속성 (Platform 연계)​

  • (공통 정책 참조) 무중단 배포는 Platform 도메인의 기준을 따른다: PLT-NFR-007

3.6 규제 준수 (감사 추적)​

4. 제약사항​

4.1 플랫폼별 제약​

  • EXH-CR-001: HealthKit 데이터는 iOS 디바이스에서만 접근 가능하며, 서버로의 직접 동기화가 불가능하다. 반드시 앱을 통해 데이터를 전송해야 한다.
  • EXH-CR-002: Health Connect 데이터는 Android 디바이스에서만 접근 가능하며, 사용자가 Health Connect 앱을 설치하고 권한을 승인해야 한다.
  • EXH-CR-003: 외부 플랫폼의 API 변경 시 즉시 대응이 필요하며, 이를 위한 버전 관리 전략이 필요하다.

4.2 데이터 수집 제약​

  • EXH-CR-004: HealthKit은 최대 최근 1년간의 데이터만 조회 가능하다 (플랫폼 정책에 따라 변경 가능).
  • EXH-CR-005: Health Connect는 최대 최근 30일간의 데이터만 조회 가능하다 (플랫폼 정책에 따라 변경 가능).
  • EXH-CR-006: 데이터 수집은 앱 실행 시점 또는 백그라운드 작업 시점에만 수행 가능하다.

4.3 권한 제약​

  • EXH-CR-007: 사용자는 언제든지 외부 플랫폼 연동 권한을 철회할 수 있으며, 시스템은 이를 즉시 반영해야 한다.
  • EXH-CR-008: 권한이 철회된 경우 해당 플랫폼으로부터의 신규 데이터 수집은 중단되어야 한다.
  • EXH-CR-009: 각 데이터 유형별로 개별 권한 승인이 필요할 수 있다.

4.4 데이터 정확성 제약​

  • EXH-CR-010: 외부 플랫폼에서 제공하는 데이터의 정확성은 해당 플랫폼 및 소스 디바이스에 의존하며, DTA Wide는 이를 보장하지 않는다.
  • EXH-CR-011: 외부 데이터는 참고용으로만 사용되어야 하며, 의료적 진단이나 치료 결정에 단독으로 사용되어서는 안 된다.

4.5 저장 제약​

  • EXH-CR-012: 시계열 생체 데이터는 저장 용량 최적화를 위해 일정 기간 후 집계 데이터로 변환될 수 있다.
  • EXH-CR-013: 원시 데이터 보관 기간: 90일, 이후 일별 집계 데이터로 변환

4.6 기술적 제약​

  • EXH-CR-014: 외부 건강 도메인 내 모든 시간 관련 로직은 시스템 시간을 직접 사용하지 않고, 반드시 TimeMachine 도메인이 제공하는 가상 시간 또는 실제 시간을 사용해야 한다.
  • EXH-CR-015: 모든 시간 데이터는 ISO8601 형식(밀리초 + TimeZone)으로 저장한다.
  • EXH-CR-016: 데이터 수집 요청의 시간은 Unix Epoch Time (milliseconds)으로 전달한다.

5. 가정사항​

5.1 사용자 행동​

  • EXH-AR-001: 사용자는 웨어러블 디바이스를 지속적으로 착용하여 건강 데이터를 수집할 것이다.
  • EXH-AR-002: 사용자는 외부 플랫폼 연동의 가치를 이해하고 필요한 권한을 승인할 것이다.
  • EXH-AR-003: 사용자는 주기적으로 앱을 실행하여 데이터 동기화를 수행할 것이다.

5.2 시스템 환경​

  • EXH-AR-004: 사용자의 디바이스는 HealthKit 또는 Health Connect를 지원하는 OS 버전을 사용할 것이다.
  • EXH-AR-005: 외부 플랫폼의 API는 합리적인 안정성을 유지할 것이다.
  • EXH-AR-006: 네트워크 연결은 데이터 동기화에 충분한 대역폭을 제공할 것이다.

5.3 LLM/Agent 연동​

  • EXH-AR-007: LLM/Agent는 사용자별 분석을 통해 적절한 데이터 수집 요청을 생성할 것이다.
  • EXH-AR-008: 데이터 수집 요청은 사용자의 치료 목표와 연관된 데이터만 포함할 것이다.

6. 의존성​

6.1 내부 의존성​

  • EXH-DR-001: Sleep 도메인: 외부 수면 데이터를 Sleep 도메인의 임시 수면 기록으로 연동하기 위해 의존한다.
  • EXH-DR-002: User 도메인: 사용자 식별 및 치료 주기 일차(dayIndex) 정보를 위해 의존한다.
  • EXH-DR-003: TimeMachine 도메인: 모든 시간 관련 처리를 위해 의존한다.
  • EXH-DR-004: Notification 도메인: 동기화 완료, 데이터 누락 등의 알림을 위해 의존한다.
  • EXH-DR-005: Agent Data 도메인: 외부 건강 데이터를 AI Agent가 활용할 수 있는 형태로 변환하여 제공하기 위해 의존한다.
  • EXH-DR-006: Multi-Agent Orchestration 도메인: LLM/Agent가 개인화된 데이터 수집 요청을 생성하기 위해 의존한다.

6.2 외부 의존성​

  • EXH-DR-007: Apple HealthKit API: iOS 디바이스의 건강 데이터 접근을 위해 의존한다.
  • EXH-DR-008: Android Health Connect API: Android 디바이스의 건강 데이터 접근을 위해 의존한다.

7. API 데이터 구조​

7.1 데이터 수집 요청 조회 (GET Response)​

interface DataCollectionRequestsResponse {
  requests: DataCollectionRequest[];
}

interface DataCollectionRequest {
  id: string;                    // UUID
  type: DataType;                // 데이터 유형
  startTime: number;             // Unix Epoch Time (ms)
  endTime: number;               // Unix Epoch Time (ms)
  interval?: IntervalConfig;     // 집계 간격 (선택적)
}

type DataType =
  | 'stepCount'
  | 'heartRate'
  | 'sleepAnalysis'
  | 'heartRateVariability'
  | 'respiratoryRate'
  | 'oxygenSaturation'
  | 'activeEnergyBurned';

interface IntervalConfig {
  type: 'year' | 'month' | 'day' | 'hour' | 'minute' | 'second';
  value: number;
}

7.2 수집 데이터 제출 (POST Request)​

interface DataCollectionResponsesRequest {
  responses: DataCollectionResponse[];
}

interface DataCollectionResponse {
  requestId: string;             // 요청 ID (UUID)
  os: 'iOS' | 'Android';         // 플랫폼
  type: DataType;                // 데이터 유형
  startTime: string;             // ISO8601 + TimeZone
  endTime: string;               // ISO8601 + TimeZone
  interval?: IntervalConfig;     // 집계 간격
  extractedAt: string;           // 추출 시각 (ISO8601 + TimeZone)
  records: DataRecord[];         // 데이터 레코드
}

interface DataRecord {
  startTime: string;             // ISO8601 + TimeZone
  endTime: string;               // ISO8601 + TimeZone
  sum?: number;                  // 합계 (Quantity 타입)
  average?: number;              // 평균 (Quantity 타입)
  category?: string;             // 카테고리 (Category 타입)
  unit?: string;                 // 단위
}

7.3 예상 DTO​

  • DataCollectionRequestDto: 데이터 수집 요청
  • DataCollectionResponseDto: 수집 데이터 응답
  • ExternalSleepDataDto: 외부 수면 데이터
  • HeartRateDataDto: 심박수 데이터
  • HrvDataDto: 심박변이도 데이터
  • ActivityDataDto: 활동량 데이터
  • PlatformConnectionDto: 플랫폼 연동 상태

8. GDPR 컴플라이언스 (개인정보 보호)​

8.1 외부 건강 데이터 처리​

백엔드 요구사항​

  • EXH-FR-BE-025: 시스템은 외부 건강 데이터 처리 목적을 명확히 정의해야 한다.
    • 최적의 졸립지 섭취 시각 계산을 위한 LLM 분석
    • 수면 패턴 분석 보조 목적
    • 생체 신호 기반 건강 상태 모니터링 목적
    • 치료 효과 측정 보조 목적
    • 연구 목적 활용 (별도 동의 필요)
  • EXH-FR-BE-026: 시스템은 외부 건강 데이터 보관 기간을 체계적으로 관리해야 한다.
    • 원시 시계열 데이터: 90일
    • 집계 데이터: 치료 종료 후 1년
    • 익명화 데이터: 연구 목적 무기한
    • 자동 삭제 스케줄러 구현
  • EXH-FR-BE-027: 시스템은 외부 건강 데이터 익명화를 구현해야 한다.
    • 개인 식별 정보 제거
    • 디바이스 식별자 제거
    • 재식별 위험 평가

8.2 데이터 주체 권리​

백엔드 요구사항​

  • EXH-FR-BE-028: 시스템은 외부 건강 데이터 열람권을 보장해야 한다.
    • 수집된 모든 외부 건강 데이터 조회 API
    • 데이터 소스 및 수집 시점 정보 제공
    • 플랫폼별 수집 현황 조회
  • EXH-FR-BE-029: 시스템은 데이터 이동권을 지원해야 한다.
    • 표준 형식(JSON/CSV) 내보내기
    • FHIR(Fast Healthcare Interoperability Resources) 형식 지원 (선택적)
  • EXH-FR-BE-030: 시스템은 연동 해제 및 데이터 삭제권을 보장해야 한다.
    • 플랫폼 연동 해제 기능
    • 연동 해제 시 해당 플랫폼 데이터 선택적 삭제 옵션
    • 완전 삭제 요청 처리

9. ISO27001 정보보호 관리​

9.1 외부 건강 데이터 보안​

백엔드 요구사항​

  • EXH-FR-BE-031: (공통 정책 참조) 외부 건강 데이터 암호화는 Platform 도메인 표준을 따른다.
  • EXH-FR-BE-032: 시스템은 데이터 전송 보안을 강화해야 한다.
    • TLS 1.3 이상 사용
    • 인증서 피닝 (Certificate Pinning) 적용

9.2 데이터 무결성​

백엔드 요구사항​

  • EXH-FR-BE-033: 시스템은 외부 건강 데이터 무결성을 보장해야 한다.
    • requestId 기반 데이터 매칭 검증
    • 타임스탬프 유효성 검증
    • 중복 데이터 감지 및 처리
  • EXH-FR-BE-034: 시스템은 데이터 수집 이력을 추적해야 한다.
    • 요청 생성/수집/완료 시각 기록
    • 수집된 데이터 범위 기록
    • 수집 결과 (성공/실패/부분 성공) 기록

9.3 감사 및 모니터링​

백엔드 요구사항​

  • EXH-FR-BE-035: 시스템은 외부 플랫폼 연동 관련 감사 로그를 생성해야 한다.
    • 플랫폼 연동/해제 이력
    • 데이터 수집 요청 생성/완료 이력
    • 데이터 접근 이력
  • EXH-FR-BE-036: 시스템은 데이터 수집 이상 상황을 모니터링해야 한다.
    • 장기간 미응답 요청 감지
    • 비정상적인 데이터 패턴 감지
    • 알림 및 대응 메커니즘

10. 참고 자료​

10.1 DBM (Device Biometric Data) 레거시 참조​

기존 DBM v2.5 (2024년 5월 21일 이후) 데이터 구조 참조:

struct DbmData: Encodable, Sendable {
    struct Record: Encodable, Sendable {
        let recordType: String
        let value: String
        let extraValue: String
        let unit: String
        let source: String
        let startTime: String
        let endTime: String
        let sessionId: String
        let isAggregated: String
        let hardwareModel: String
        let softwareVersion: String
    }

    let userId: String
    let userProjectCycleId: String
    let deployEnv: String
    let dbmVersion: String
    let extractedAt: String
    let appVersion: String
    let numOfRecords: Int
    let records: [Record]
}

변경 이력​

버전날짜작성자변경 내용
0.1.02025-12-15claude@weltcorp.com최초 작성
0.2.02025-12-15claude@weltcorp.com개인화된 데이터 수집 요청 패턴 반영, API 스키마 구체화, LLM 연동 목적 명시
0.3.02025-12-16claude@weltcorp.com프론트엔드 요구사항 추가 (EXH-FR-FE-001 ~ EXH-FR-FE-023), Onboarding/Home Screen 데이터 수집 플로우 명시