Agent Data 도메인 요구사항

1. 도메인 개요

1.1 목적

Agent Data 도메인은 사용자가 DTA-WIDE 서비스를 사용하면서 생성하는 다양한 도메인 데이터를 수집, 변환, 저장하여 AI Agent가 개인화된 치료 서비스를 제공할 수 있도록 지원하는 데이터 준비 계층입니다.

1.2 핵심 책임

각 도메인(Sleep, Questionnaire, Learning 등)에서 발생하는 이벤트를 구독
수집된 데이터를 LLM이 이해하고 활용하기 쉬운 JSON document 형태로 변환
변환된 데이터를 Firestore에 구조화하여 저장
AI Agent가 필요한 데이터에 접근할 수 있도록 지원

1.3 도메인 위치

Core Domain으로서 AI 기반 개인화 서비스의 핵심 데이터 인프라 역할
다른 도메인들과는 Event System을 통해 느슨하게 결합
dta-wide-agent-flow 서비스에 데이터를 제공하는 Supporting 역할

2. 기능 요구사항

2.1 이벤트 구독 및 데이터 수집

2.1.1 Sleep 도메인 데이터 수집

AGD-FR-001: 시스템은 수면기록 작성 완료 이벤트를 구독해야 한다.
AGD-FR-002: 시스템은 수면기록 수정 이벤트를 구독해야 한다.
AGD-FR-003: 시스템은 수면기록 삭제 이벤트를 구독해야 한다.
AGD-FR-004: 시스템은 다음 수면 데이터를 수집해야 한다:
- 수면 시작/종료 시간
- 총 수면 시간
- 수면 효율성
- 수면 중 각성 횟수 및 시간
- 수면의 질 평가
- 수면 관련 메모나 특이사항

2.1.2 Questionnaire 도메인 데이터 수집

AGD-FR-005: 시스템은 설문 응답 완료 이벤트를 구독해야 한다.
AGD-FR-006: 시스템은 설문 응답 수정 이벤트를 구독해야 한다.
AGD-FR-007: 시스템은 다음 설문 데이터를 수집해야 한다:
- 설문 유형 (ISI, PSQI, PHQ-9 등)
- 설문 응답 내용
- 설문 점수 및 해석
- 설문 작성 시간
- 설문 라운드 정보

2.1.3 Learning 도메인 데이터 수집

AGD-FR-008: 시스템은 레슨 시작 이벤트를 구독해야 한다.
AGD-FR-009: 시스템은 레슨 완료 이벤트를 구독해야 한다.
AGD-FR-010: 시스템은 레슨 진행 상태 변경 이벤트를 구독해야 한다.
AGD-FR-011: 시스템은 다음 학습 데이터를 수집해야 한다:
- 학습 내용 정보:
  - 레슨 타이틀 및 주제
  - 주요 학습 내용 및 핵심 개념
  - 학습 목표 및 기대 효과
  - 레슨 카테고리 (수면위생, 인지행동치료, 이완기법 등)
- 학습 행동 패턴:
  - 학습 진도 (완료한 레슨 수 / 전체 레슨 수)
  - 각 레슨별 소요 시간
  - 레슨 학습 시간대 패턴
  - 학습 빈도 및 규칙성
  - 퀴즈 정답률 및 이해도
- 참조 정보: 레슨 ID (내부 참조용)

2.1.4 Medication 도메인 데이터 수집

AGD-FR-046: 시스템은 약물 프로필 저장 이벤트(MedicationProfileCaptured)를 구독해야 한다.
AGD-FR-047: 시스템은 약물 필드 완료 대기 이벤트(MedicationProfileCompletionPending)를 구독해야 한다.
AGD-FR-048: 시스템은 약물 상호작용 경고 이벤트(MedicationInteractionAlerted)를 구독해야 한다.
AGD-FR-049: 시스템은 약물 감량 계획 생성 이벤트(MedicationTaperPlanGenerated)를 구독해야 한다.
AGD-FR-050: 시스템은 약물 추천 피드백 이벤트(MedicationRecommendationFeedbackRecorded)를 구독해야 한다.
AGD-FR-051: 시스템은 다음 약물 프로필 데이터를 수집해야 한다:
- 약물명 및 표준 성분 코드 (canonicalIngredientCode)
- 용량 (dosagePerIntake), 제형 (formFactor), 복용 패턴 (ingestionPattern)
- 수집 방법 (captureSource: 촬영/수동) 및 신뢰도 (confidenceScore)
- 처방 상태 (prescriptionStatus) 및 목적 (intendedPurpose)
- 남은 수량 (remainingQuantity) 및 마지막 복용 시각 (lastIntakeAt)
- 필드 완료 상태 (fieldCompletionStatus)
AGD-FR-052: 시스템은 다음 약물 지식 그래프 요약 데이터를 수집해야 한다:
- 수면 잠복기 영향 지표 (sedationLatencyImpact)
- 반동 위험 (reboundRisk)
- 상호작용 점수 (interactionScore)
- 반감기 (halfLifeHours) 및 작용 시간 (onsetTime, durationTime)
AGD-FR-053: 시스템은 다음 상호작용 경고 데이터를 수집해야 한다:
- 경고 유형 및 심각도
- 관련 약물 목록
- 권장 조치사항
AGD-FR-054: 시스템은 다음 약물 감량 계획 데이터를 수집해야 한다:
- 감량 단계 및 일정
- 대안 비약물 개입 (호흡법, CBT-I 루틴 등)
- 유효 기간 (dayIndex 범위)

2.1.5 Condition 도메인 데이터 수집

AGD-FR-071: 시스템은 증상 리포트 캡처 이벤트(ConditionReportCaptured)를 구독해야 한다.
AGD-FR-072: 시스템은 수면 인식 신념 캡처 이벤트(SleepAwarenessBeliefCaptured)를 구독해야 한다.
AGD-FR-073: 시스템은 증상 리포트 보강 완료 이벤트(ConditionReportEnriched)를 구독해야 한다.
AGD-FR-074: 시스템은 증상 경보 트리거 이벤트(ConditionAlertTriggered)를 구독해야 한다.
AGD-FR-075: 시스템은 증상 추세 스냅샷 생성 이벤트(ConditionTrendSnapshotGenerated)를 구독해야 한다.
AGD-FR-076: 시스템은 다음 증상 리포트 데이터를 수집해야 한다:
- 리포트 식별: conditionReportId, userId, accountType, programType, sessionType
- 개별 증상: symptomCode, displayName, experienceType (PHYSICAL/MENTAL/BEHAVIORAL)
- 증상 세부: severityScore (0-10), durationMinutes, onsetType, bodyRegion
- 영향 및 트리거: impactScale (ADL/SLEEP/MOOD), triggerTags
- 데이터 소스: sourceType (USER_REPORT/AI_AGENT/QUESTIONNAIRE), questionnaireCode
- 인지 정보: beliefScore (0-100), cognitivePattern (CATASROPHIZING/PERFECTIONISM/HYPERAROUSAL)
- 시간 정보: capturedAt, dayIndex
AGD-FR-077: 시스템은 다음 증상 경보 데이터를 수집해야 한다:
- 경보 식별: alertId, userId, symptomEntryId
- 경보 정보: severityScore, impactScale, triggerRule, state
- 시간 정보: triggeredAt, escalatedAt, acknowledgedAt
AGD-FR-078: 시스템은 다음 증상 추세 데이터를 수집해야 한다:
- 추세 기간: dayIndexRange, isoDateRange, windowSize (7/14/28일)
- 집계 정보: 롤링 평균, 최빈 증상, 트렌드 방향
- 상관 분석: 수면/약물/습관과의 상관계수

2.2 데이터 변환 및 구조화

2.2.1 LLM 친화적 데이터 변환

AGD-FR-012: 시스템은 원본 데이터의 축약된 컬럼명을 LLM이 이해하기 쉬운 명확한 필드명으로 변환해야 한다.
AGD-FR-013: 시스템은 다음과 같은 변환 규칙을 적용해야 한다:
- Sleep 도메인 예시:
  - se → sleepEfficiency
  - tst → totalSleepTime
  - sol → sleepOnsetLatency
  - waso → wakeAfterSleepOnset
  - nw → numberOfAwakenings
  - sq → sleepQuality
- Questionnaire 도메인 예시:
  - q1, q2, ... → question1Answer, question2Answer, ...
  - score → totalScore
  - severity → severityLevel
- Learning 도메인 예시:
  - lesson_title → lessonTitle
  - content_summary → contentSummary
  - key_concepts → keyConcepts
  - learning_objectives → learningObjectives
  - session_duration → sessionDuration
  - time_spent → timeSpentMinutes
  - completion_status → completionStatus
AGD-FR-014: 시스템은 JSON document 형태로 구조화된 데이터를 생성해야 한다.
AGD-FR-015: 시스템은 각 필드에 대한 설명이나 의미를 메타데이터로 포함할 수 있어야 한다.

2.2.2 시계열 데이터 구조화

AGD-FR-016: 시스템은 일별, 주별, 월별로 데이터를 집계하여 저장해야 한다.
AGD-FR-017: 시스템은 트렌드 분석이 가능하도록 시계열 데이터를 구조화해야 한다.
AGD-FR-018: 시스템은 이전 기간 대비 변화율을 계산하여 저장해야 한다.

2.2.3 컨텍스트 정보 추가

AGD-FR-019: 시스템은 각 데이터에 컨텍스트 정보를 추가해야 한다:
- 치료 시작일로부터 경과일
- 해당 기간의 치료 단계
- 관련된 다른 이벤트나 패턴
- 데이터 수집 시점 정보

2.2.4 Medication 데이터 변환

AGD-FR-055: 시스템은 약물 필드명을 LLM 친화적으로 변환해야 한다:
- Medication 도메인 예시:
  - name → medicationName
  - dosagePerIntake → dosagePerIntakeMg
  - formFactor → medicationForm (예: "tablet", "capsule", "liquid")
  - captureSource → dataCollectionMethod (예: "photo_ocr", "manual_input")
  - confidenceScore → dataConfidenceLevel (0-1 범위를 "high"/"medium"/"low"로 변환)
  - fieldCompletionStatus → dataCompletenessStatus (예: "complete", "pending")
  - prescriptionStatus → prescriptionType (예: "prescribed", "over_the_counter")
  - intendedPurpose → medicationPurpose
  - remainingQuantity → remainingDoses
  - lastIntakeAt → lastTakenAt
AGD-FR-056: 시스템은 지식 그래프 데이터를 통합하여 LLM 친화적 설명을 추가해야 한다:
- 반감기 데이터:
  - halfLifeHours → 숫자 값 유지
  - halfLifeDescription 추가 (예: "short-acting (<6h)", "intermediate-acting (6-12h)", "long-acting (>12h)")
- 수면 영향 데이터:
  - sedationLatencyImpact → sleepOnsetImpactScore (숫자 값)
  - sleepImpactLevel 추가 (예: "high_sedation", "moderate_sedation", "low_sedation", "none")
  - sleepImpactDescription 추가 (자연어 설명)
- 상호작용 데이터:
  - interactionScore → 숫자 값 유지
  - interactionRiskLevel 추가 (예: "none", "low", "moderate", "high", "severe")
  - interactionWarning 추가 (관련 상호작용 경고 텍스트)
AGD-FR-057: 시스템은 TimeMachine dayIndex 컨텍스트를 추가해야 한다:
- capturedAtDayIndex: 수집 시점의 dayIndex
- treatmentDaysSinceStart: 치료 시작 후 경과일
- taperPlanValidFromDayIndex: 감량 계획 시작 dayIndex (해당하는 경우)
- taperPlanValidToDayIndex: 감량 계획 종료 dayIndex (해당하는 경우)
AGD-FR-058: 시스템은 약물 지식 그래프 전체를 Firestore에 복제하지 않고, 사용자별 필요한 정보만 denormalize하여 저장해야 한다.

2.2.5 Condition 데이터 변환

AGD-FR-079: 시스템은 증상 필드명을 LLM 친화적으로 변환해야 한다:
- Condition 도메인 예시:
  - symptomCode → standardSymptomCode
  - displayName → symptomName
  - experienceType → symptomCategory (예: "physical", "mental", "behavioral")
  - severityScore → symptomSeverityLevel (0-10 점수와 함께 "mild"/"moderate"/"severe" 설명)
  - durationMinutes → symptomDurationMinutes
  - onsetType → symptomOnsetPattern (예: "acute", "chronic", "gradual")
  - bodyRegion → affectedBodyArea
  - impactScale → impactAreas (예: ["daily_activities", "sleep_quality", "mood"])
  - triggerTags → identifiedTriggers
  - sourceType → reportingSource (예: "user_reported", "ai_agent_collected", "questionnaire_derived")
  - questionnaireCode → relatedQuestionnaire
AGD-FR-080: 시스템은 인지 및 신념 데이터를 LLM 친화적으로 변환해야 한다:
- 인지 패턴 데이터:
  - beliefScore → cognitiveDistortionScore (0-100 점수)
  - beliefScoreDescription 추가 (예: "minimal", "moderate", "significant", "severe")
  - cognitivePattern → thinkingPattern (예: "catastrophizing", "perfectionism", "hyperarousal", "other")
  - thinkingPatternDescription 추가 (자연어 설명)
- 수면 인식 데이터:
  - sleepAwarenessBeliefs: 수면에 대한 생각/가치관 목록
  - sleepBeliefImpactLevel: 수면 신념의 영향 수준 (예: "low", "moderate", "high")
AGD-FR-081: 시스템은 증상 경보 데이터를 LLM 친화적으로 변환해야 한다:
- 경보 정보:
  - triggerRule → alertTriggerReason (예: "severity_threshold", "risk_combination", "repeat_occurrence")
  - state → alertStatus (예: "triggered", "escalated", "acknowledged", "resolved")
  - escalatedAt → escalationTime
  - acknowledgedAt → acknowledgmentTime
AGD-FR-082: 시스템은 증상 추세 데이터에 컨텍스트를 추가해야 한다:
- trendDirection: 증상 추세 방향 (예: "improving", "stable", "worsening")
- mostFrequentSymptoms: 가장 빈번한 증상 목록
- averageSeverity: 기간 내 평균 심각도
- correlationsWithSleep: 수면 지표와의 상관관계 설명
- correlationsWithMedication: 약물 복용과의 상관관계 설명

2.3 Firestore 저장 구조

2.3.1 컬렉션 구조 관리

AGD-FR-020: 시스템은 사용자별 계층적 데이터 구조를 관리해야 한다.
AGD-FR-021: 시스템은 수면, 설문, 학습 데이터를 도메인별로 분리하여 저장해야 한다.
AGD-FR-022: 시스템은 일별, 주별, 월별 집계 데이터를 별도로 관리해야 한다.
AGD-FR-023: 시스템은 학습 내용 숙지도와 지식 현황을 별도 컬렉션으로 관리해야 한다.

2.3.2 데이터 저장 규칙

AGD-FR-024: 시스템은 모든 데이터에 타임스탬프를 포함해야 한다.
AGD-FR-025: 시스템은 데이터 버전 관리를 위한 스키마 버전을 포함해야 한다.
AGD-FR-026: 시스템은 원본 이벤트 ID를 참조로 저장해야 한다.
AGD-FR-027: 시스템은 중복 데이터를 방지하기 위한 멱등성을 보장해야 한다.

2.3.3 Medication 데이터 저장 구조

AGD-FR-059: 시스템은 약물 데이터를 다음 Firestore 컬렉션 구조로 저장해야 한다:

genai (Firestore Database)
└── medication
    ├── profiles
    │   └── {userId}
    │       └── {medicationId}        # 약물 프로필 (덮어쓰기 방식)
    ├── interactions
    │   └── {userId}
    │       └── {alertId}             # 상호작용 경고 (append-only)
    ├── recommendations
    │   └── {userId}
    │       └── {dayIndex}            # 일별 추천 결과
    ├── taper-plans
    │   └── {userId}
    │       └── {planId}              # 감량 계획
    └── daily-summaries
        └── {userId}
            └── {dayIndex}            # 일별 약물 사용 요약

AGD-FR-060: 약물 프로필 저장 시 다음 정보를 포함해야 한다:
- 기본 정보: medicationId, userId, userCycleId, dayIndex
- 변환된 필드: LLM 친화적 필드명 (AGD-FR-055 참조)
- 지식 그래프 요약: 수면 영향, 상호작용 위험 등 (AGD-FR-056 참조)
- 메타데이터: originalEventId, schemaVersion, createdAt, processedAt
- 컨텍스트: TimeMachine dayIndex 정보 (AGD-FR-057 참조)
AGD-FR-061: 상호작용 경고 저장 시 다음 정보를 포함해야 한다:
- 경고 식별: alertId, userId, triggeredAtDayIndex
- 경고 내용: interactionRiskLevel, relatedMedications, warningDescription
- 권장 조치: recommendedActions, severityLevel
- 타임스탬프: triggeredAt, expiresAt
AGD-FR-062: 약물 추천 데이터 저장 시 다음 정보를 포함해야 한다:
- 추천 식별: userId, dayIndex, recommendationType
- 추천 내용: recommendation, reasoning, alternativeInterventions
- 유효 기간: validFromDayIndex, validToDayIndex
- 피드백: feedbackReceived, feedbackScore, feedbackText
AGD-FR-063: 일별 요약 데이터 저장 시 다음 정보를 포함해야 한다:
- 날짜 정보: userId, dayIndex, date
- 약물 사용: activeMedications (해당 날짜에 복용한 약물 목록)
- 위험 지표: overallInteractionRisk, totalSedationImpact
- 추천 준수: recommendationAdherence, taperPlanProgress

2.3.4 Condition 데이터 저장 구조

AGD-FR-083: 시스템은 증상 데이터를 다음 Firestore 컬렉션 구조로 저장해야 한다:

genai (Firestore Database)
└── condition
    ├── reports
    │   └── {userId}
    │       └── {reportId}            # 증상 리포트 (append-only)
    ├── symptoms
    │   └── {userId}
    │       └── {symptomId}           # 개별 증상 항목
    ├── alerts
    │   └── {userId}
    │       └── {alertId}             # 증상 경보 (append-only)
    ├── trends
    │   └── {userId}
    │       └── {snapshotId}          # 증상 추세 스냅샷
    ├── beliefs
    │   └── {userId}
    │       └── {dayIndex}            # 수면 인식 신념 데이터
    └── daily-summaries
        └── {userId}
            └── {dayIndex}            # 일별 증상 요약

AGD-FR-084: 증상 리포트 저장 시 다음 정보를 포함해야 한다:
- 기본 정보: reportId, userId, accountType, programType, sessionType, dayIndex
- 증상 목록: symptoms (변환된 증상 항목 배열)
- 변환된 필드: LLM 친화적 필드명 (AGD-FR-079 참조)
- 메타데이터: originalEventId, schemaVersion, createdAt, processedAt
- 컨텍스트: capturedAt, treatmentDaysSinceStart
AGD-FR-085: 증상 경보 저장 시 다음 정보를 포함해야 한다:
- 경보 식별: alertId, userId, symptomId, reportId
- 경보 내용: alertTriggerReason, alertStatus, symptomSeverityLevel, impactAreas
- 조치 정보: recommendedActions, escalationLevel
- 타임스탬프: triggeredAt, escalatedAt, acknowledgedAt, resolvedAt
AGD-FR-086: 증상 추세 저장 시 다음 정보를 포함해야 한다:
- 추세 식별: snapshotId, userId, programType
- 기간 정보: dayIndexRange, isoDateRange, windowSize
- 집계 정보: mostFrequentSymptoms, averageSeverity, trendDirection
- 상관 분석: correlationsWithSleep, correlationsWithMedication, correlationsWithHabits
- 타임스탬프: generatedAt
AGD-FR-087: 수면 인식 신념 저장 시 다음 정보를 포함해야 한다:
- 날짜 정보: userId, dayIndex, date
- 신념 데이터: sleepAwarenessBeliefs (생각/가치관 목록)
- 변환된 필드: LLM 친화적 필드명 (AGD-FR-080 참조)
- 평가 정보: cognitiveDistortionScore, beliefScoreDescription, thinkingPattern, sleepBeliefImpactLevel

2.4 데이터 제공 요구사항

2.4.1 사용자 프로필 데이터 제공

AGD-FR-028: 시스템은 사용자의 전반적인 치료 상태와 패턴 요약을 제공해야 한다.
AGD-FR-029: 시스템은 AI Agent가 컨텍스트를 이해하는데 필요한 핵심 정보를 포함해야 한다.

2.4.2 수면 데이터 제공

AGD-FR-030: 시스템은 지정된 기간의 수면 패턴과 트렌드를 제공해야 한다.
AGD-FR-031: 시스템은 LLM이 이해하기 쉬운 필드명으로 구조화된 JSON 데이터를 제공해야 한다.

2.4.3 설문 데이터 제공

AGD-FR-032: 시스템은 설문 응답 이력과 점수 변화 추이를 제공해야 한다.
AGD-FR-033: 시스템은 각 설문 유형별 인사이트를 포함해야 한다.

2.4.4 학습 데이터 제공

AGD-FR-034: 시스템은 학습 진도와 패턴 분석 결과를 제공해야 한다.
AGD-FR-035: 시스템은 완료한 학습 내용 및 숙지 개념 목록을 포함해야 한다.
AGD-FR-036: 시스템은 사용자가 학습한 주제별 지식 현황을 제공해야 한다.
AGD-FR-037: 시스템은 학습한 핵심 개념과 이해도 수준을 포함해야 한다.

2.4.5 통합 인사이트 제공

AGD-FR-038: 시스템은 모든 도메인 데이터를 종합한 일일/주간 인사이트를 제공해야 한다.
AGD-FR-039: 시스템은 AI Agent의 개인화 응답 생성에 필요한 핵심 정보 요약을 제공해야 한다.

2.4.6 Medication 데이터 제공

AGD-FR-064: 시스템은 사용자의 약물 프로필 목록과 상세 정보를 제공해야 한다.
AGD-FR-065: 시스템은 약물 프로필에 지식 그래프 요약 정보를 포함해야 한다 (수면 영향, 상호작용 위험 등).
AGD-FR-066: 시스템은 활성 상호작용 경고 목록을 제공해야 한다.
AGD-FR-067: 시스템은 약물 추천 이력과 피드백 정보를 제공해야 한다.
AGD-FR-068: 시스템은 감량 계획 진행 상황을 제공해야 한다.
AGD-FR-069: 시스템은 일별 약물 사용 요약과 추세 분석을 제공해야 한다.
AGD-FR-070: 시스템은 LLM이 이해하기 쉬운 필드명과 자연어 설명으로 구조화된 JSON 데이터를 제공해야 한다.

2.4.7 Condition 데이터 제공

AGD-FR-088: 시스템은 사용자의 증상 리포트 이력과 상세 정보를 제공해야 한다.
AGD-FR-089: 시스템은 증상 리포트에 LLM 친화적으로 변환된 필드와 자연어 설명을 포함해야 한다.
AGD-FR-090: 시스템은 활성 증상 경보 목록과 조치 필요 사항을 제공해야 한다.
AGD-FR-091: 시스템은 증상 추세 분석 결과를 제공해야 한다 (롤링 평균, 트렌드 방향, 가장 빈번한 증상).
AGD-FR-092: 시스템은 증상과 수면/약물/습관 간의 상관관계 분석을 제공해야 한다.
AGD-FR-093: 시스템은 수면 인식 신념 데이터와 인지 왜곡 평가를 제공해야 한다.
AGD-FR-094: 시스템은 일별 증상 요약과 패턴 인사이트를 제공해야 한다.
AGD-FR-095: 시스템은 LLM이 이해하기 쉬운 필드명과 컨텍스트 정보로 구조화된 JSON 데이터를 제공해야 한다.

2.5 데이터 처리 파이프라인

2.5.1 실시간 처리

AGD-FR-040: 시스템은 이벤트 수신 후 5초 이내에 데이터를 변환하고 저장해야 한다.
AGD-FR-041: 시스템은 처리 실패 시 재시도 메커니즘을 구현해야 한다.
AGD-FR-042: 시스템은 처리 상태를 모니터링하고 로깅해야 한다.

2.5.2 배치 처리

AGD-FR-043: 시스템은 매일 자정에 일일 요약 데이터를 생성해야 한다.
AGD-FR-044: 시스템은 매주 월요일에 주간 트렌드 분석을 수행해야 한다.
AGD-FR-045: 시스템은 매월 1일에 월간 리포트를 생성해야 한다.

3. 비기능 요구사항

3.1 성능

AGD-NFR-001: 이벤트 처리 지연시간은 평균 1초, 최대 5초를 초과하지 않아야 한다.
AGD-NFR-002: 데이터 조회 응답 시간은 평균 200ms, 최대 1초를 초과하지 않아야 한다.
AGD-NFR-003: 시스템은 초당 100개 이상의 이벤트를 처리할 수 있어야 한다.
AGD-NFR-004: Firestore 쿼리는 인덱스를 활용하여 최적화되어야 한다.
AGD-NFR-018: Medication 상호작용 경고 이벤트는 실시간 처리가 필요하므로 5초 이내 변환 및 저장을 완료해야 한다.
AGD-NFR-019: 약물 지식 그래프 조인 작업은 캐시를 활용하여 평균 처리 시간 2초 이내를 유지해야 한다.
AGD-NFR-020: Medication 데이터 조회는 지식 그래프 요약 정보 포함 시에도 평균 응답 시간 500ms를 초과하지 않아야 한다.

3.2 확장성

AGD-NFR-005: 시스템은 새로운 도메인 이벤트 타입을 쉽게 추가할 수 있어야 한다.
AGD-NFR-006: 시스템은 데이터 변환 규칙을 설정으로 관리할 수 있어야 한다.
AGD-NFR-007: 시스템은 수평적 확장이 가능한 구조로 설계되어야 한다.

3.3 신뢰성

(공통 정책 참조) 가용성/복구/백업/무중단 배포는 Platform 도메인 기준을 따른다: PLT-NFR-004, PLT-NFR-005, PLT-NFR-006, PLT-NFR-007
AGD-NFR-008: 시스템은 99.9% 이상의 가용성을 제공해야 한다.
AGD-NFR-009: 시스템은 이벤트 처리 실패 시 Dead Letter Queue로 전송해야 한다.
AGD-NFR-010: 시스템은 데이터 무결성을 보장하기 위한 검증 로직을 포함해야 한다.

3.4 보안

AGD-NFR-011: 시스템은 사용자 데이터에 대한 접근 권한을 엄격히 관리해야 한다.
AGD-NFR-012: 시스템은 데이터 접근 요청에 대한 인증과 인가를 검증해야 한다.
AGD-NFR-013: 시스템은 민감한 건강 정보를 안전하게 저장하고 전송해야 한다.
AGD-NFR-014: 시스템은 GDPR 및 의료 데이터 보호 규정을 준수해야 한다.
AGD-NFR-021: 약물 데이터는 PII 레벨 2로 분류하며, Firestore 저장 시 필드 수준 암호화를 적용해야 한다.
AGD-NFR-022: OCR/LLM 추론 메타데이터(원본 이미지 해시, 모델 버전, 신뢰도)는 별도 컬렉션에 저장하고, 감사 추적이 가능해야 한다.
AGD-NFR-023: 약물 지식 그래프 요약 데이터는 사용자별로 격리되어 저장되어야 하며, 다른 사용자의 데이터와 혼합되지 않아야 한다.
AGD-NFR-024: Medication 상호작용 경고 데이터는 만료 시간(expiresAt) 이후 자동으로 삭제되어야 한다.

3.5 모니터링

AGD-NFR-015: 시스템은 이벤트 처리 메트릭을 실시간으로 모니터링해야 한다.
AGD-NFR-016: 시스템은 데이터 품질 지표를 추적하고 알림을 제공해야 한다.
AGD-NFR-017: 시스템은 데이터 접근 사용량과 성능 지표를 기록해야 한다.

3.6 규제 준수(감사 추적)

(교차참조) 도메인 데이터 및 설정의 중요 변경은 Audit 기준을 준수한다: AUD-NFR-023, AUD-NFR-024, AUD-NFR-026

4. 제약사항

4.1 기술적 제약

AGD-CR-001: Firestore의 문서 크기 제한(1MB)을 고려하여 데이터를 분할 저장해야 한다.
AGD-CR-002: 이벤트 시스템을 통한 느슨한 결합을 유지해야 한다.
AGD-CR-003: 각 도메인은 Agent Data 도메인의 존재를 알 필요가 없어야 한다.

4.2 데이터 제약

AGD-CR-004: 개인 식별 정보는 최소화하고 필요시 암호화해야 한다.
AGD-CR-005: 원본 데이터의 무결성을 유지하면서 변환해야 한다.
AGD-CR-006: 데이터 보존 기간은 관련 규정을 준수해야 한다.

4.3 운영 제약

AGD-CR-007: 배치 처리는 사용자 서비스에 영향을 주지 않는 시간대에 수행해야 한다.
AGD-CR-008: 시스템 업데이트는 무중단으로 수행되어야 한다.

AGD-CR-009: 시스템은 GDPR 및 관련 개인정보 보호 법률을 준수하는 데이터 처리 메커니즘을 구현해야 한다.
AGD-CR-010: 데이터 보관 기간:
- Agent Data는 개인정보 처리방침에 명시된 대로 5년간 보관한다.
- 회원 탈퇴 시 사용자 식별 정보는 즉시 삭제하되, 익명화된 형태로 데이터는 통계 및 연구 목적으로 보관할 수 있다.
AGD-CR-011: 비활성 사용자 데이터 처리:
- 서비스 이용 종료 또는 마지막 활동으로부터 6개월이 경과한 사용자의 데이터는 '비활성(inactive)' 상태로 표시한다.
- 비활성 상태로 1년이 경과한 사용자 데이터는 주 Firestore에서 '콜드 스토리지'로 이전한다.
AGD-CR-012: 데이터 복원 메커니즘:
- 비활성 사용자가 서비스에 재접속할 경우, 콜드 스토리지에서 해당 사용자의 과거 데이터를 자동으로 복원한다.
- 복원 과정은 사용자에게 투명하게 이루어져야 하며, 복원 완료 후 사용자에게 알림을 제공한다.

5. 가정사항

5.1 시스템 환경

AGD-AR-001: 시스템은 클라우드 기반 서버에서 운영될 것이다.
AGD-AR-002: 시스템은 모바일 앱과의 API 통신을 통해 데이터를 주고받을 것이다.
AGD-AR-003: 시스템은 인증된 사용자에게만 데이터를 제공할 것이다.

5.2 사용자 환경

AGD-AR-004: 사용자는 모바일 디바이스를 통해 서비스에 접근할 것이다.
AGD-AR-005: 사용자는 인터넷 연결 상태에서 대부분의 기능을 사용할 것이다.
AGD-AR-006: AI Agent는 변환된 데이터를 활용하여 개인화된 서비스를 제공할 것이다.

5.3 데이터 환경

AGD-AR-007: 각 도메인에서 발생하는 이벤트는 일관된 스키마를 가질 것이다.
AGD-AR-008: 원본 데이터는 변환 과정에서 의미가 손실되지 않을 것이다.
AGD-AR-009: AI Agent는 변환된 데이터 형태를 이해하고 활용할 수 있을 것이다.

6. 의존성

6.1 내부 의존성

AGD-DR-001: Event System: 도메인 간 이벤트 통신 인프라
AGD-DR-002: Auth Domain: API 인증 및 사용자 권한 검증
AGD-DR-003: User Domain: 사용자 기본 정보 및 치료 정보 조회
AGD-DR-004: Sleep Domain: 수면 기록 이벤트 제공
AGD-DR-005: Questionnaire Domain: 설문 응답 이벤트 제공
AGD-DR-006: Learning Domain: 학습 진행 이벤트 제공
AGD-DR-011: Medication Domain: 약물 프로필, 상호작용 경고, 감량 계획, 추천 피드백 이벤트 제공
AGD-DR-012: Condition Domain: 증상 리포트, 경보, 추세 스냅샷, 수면 인식 신념 이벤트 제공

6.2 외부 의존성

AGD-DR-007: Google Firestore: 변환된 데이터의 주 저장소
AGD-DR-008: Google Cloud Pub/Sub: 도메인 간 이벤트 메시징
AGD-DR-009: Redis: 이벤트 중복 처리 방지를 위한 캐시
AGD-DR-010: dta-wide-agent-flow: 변환된 데이터의 주요 소비자

7.1 통합 데이터 처리

백엔드 요구사항

AGD-FR-BE-026: 시스템은 통합 데이터 처리 시 개인정보를 보호해야 한다.
- MCP 인터페이스 데이터 암호화
- 도메인 간 데이터 전송 시 최소화
- 집계 데이터 익명화
- 실시간 데이터 스트림 보호
AGD-FR-BE-027: 시스템은 데이터 접근 권한을 관리해야 한다.
- MCP 도구별 접근 권한 설정
- 데이터 쿼리 감사 로그
- 민감 데이터 필터링
- 사용자별 데이터 격리

7.2 인사이트 생성

백엔드 요구사항

AGD-FR-BE-028: 시스템은 인사이트 생성 시 개인정보를 보호해야 한다.
- AI 모델 입력 데이터 익명화
- 생성된 인사이트 개인정보 검증
- 패턴 분석 시 집단 레벨 처리
- 개인별 추천 암호화

8. ISO27001 정보보호 관리

8.1 데이터 통합 보안

백엔드 요구사항

AGD-FR-BE-029: 시스템은 데이터 통합 파이프라인을 보호해야 한다.
- ETL 프로세스 암호화
- 데이터 변환 무결성 검증
- 임시 데이터 안전 삭제
- 파이프라인 접근 통제
AGD-FR-BE-030: 시스템은 MCP 인터페이스 보안을 강화해야 한다.
- 인증 키 관리
- Rate limiting
- 요청/응답 로깅
- 이상 패턴 탐지

8.2 데이터 아카이빙

백엔드 요구사항

AGD-FR-BE-031: 시스템은 데이터 아카이빙을 안전하게 관리해야 한다.
- 콜드 스토리지 암호화
- 아카이브 접근 감사
- 복원 프로세스 보안
- 아카이브 무결성 검증

9. 변경 이력

버전	날짜	작성자	변경 내용
0.1.0	2025-05-03	-	최초 작성
0.1.1	2025-05-03	-	LLM 친화적 데이터 변환 방식 수정 (자연어→JSON 필드명 변환)
0.1.2	2025-05-03	-	Learning 도메인 데이터 수집 방식 개선 (lessonId → 학습 내용 중심)
0.1.3	2025-05-03	-	API endpoint 명세 제거, 요구사항 중심으로 구조 변경
0.1.4	2025-05-03	-	데이터 모델 및 이벤트 구독 명세 제거, questionnaire 요구사항 구조와 일치
0.2.0	2025-08-07	bok@weltcorp.com	요구사항 ID 체계 적용 - AGD 도메인 코드 적용 (AGD-FR-xxx, AGD-NFR-xxx, AGD-CR-xxx, AGD-AR-xxx, AGD-DR-xxx)
0.3.0	2025-08-12	bok@weltcorp.com	GDPR 및 ISO27001 컴플라이언스 요구사항 추가 (섹션 7, 8) - 통합 데이터 처리, 데이터 통합 보안
0.4.0	2025-11-10	bok@weltcorp.com	Medication 도메인 데이터 수집/변환/저장 요구사항 추가 - 2.1.4 (AGD-FR-046~~054), 2.2.4 (AGD-FR-055~~058), 2.3.3 (AGD-FR-059~~063), 2.4.6 (AGD-FR-064~~070), 성능/보안 요구사항 (AGD-NFR-018~024), 내부 의존성 (AGD-DR-011)
0.5.0	2025-11-10	bok@weltcorp.com	Condition 도메인 데이터 수집/변환/저장 요구사항 추가 - 2.1.5 (AGD-FR-071~~078), 2.2.5 (AGD-FR-079~~082), 2.3.4 (AGD-FR-083~~087), 2.4.7 (AGD-FR-088~~095), 내부 의존성 (AGD-DR-012); API 구현 용어 제거 - 섹션 2.4 "조회 API" → "데이터 제공", "JSON 응답" → "JSON 데이터"로 변경하여 요구사항 추상화
0.5.1	2025-11-25	codex@weltcorp.com	Condition 도메인 명칭/경로 변경에 맞춰 용어 및 계층 경로를 업데이트

1. 도메인 개요​

1.1 목적​

1.2 핵심 책임​

1.3 도메인 위치​

2. 기능 요구사항​

2.1 이벤트 구독 및 데이터 수집​

2.1.1 Sleep 도메인 데이터 수집​

2.1.2 Questionnaire 도메인 데이터 수집​

2.1.3 Learning 도메인 데이터 수집​

2.1.4 Medication 도메인 데이터 수집​

2.1.5 Condition 도메인 데이터 수집​

2.2 데이터 변환 및 구조화​

2.2.1 LLM 친화적 데이터 변환​

2.2.2 시계열 데이터 구조화​

2.2.3 컨텍스트 정보 추가​

2.2.4 Medication 데이터 변환​

2.2.5 Condition 데이터 변환​

2.3 Firestore 저장 구조​

2.3.1 컬렉션 구조 관리​

2.3.2 데이터 저장 규칙​

2.3.3 Medication 데이터 저장 구조​

2.3.4 Condition 데이터 저장 구조​

2.4 데이터 제공 요구사항​

2.4.1 사용자 프로필 데이터 제공​

2.4.2 수면 데이터 제공​

2.4.3 설문 데이터 제공​

2.4.4 학습 데이터 제공​

2.4.5 통합 인사이트 제공​

2.4.6 Medication 데이터 제공​

2.4.7 Condition 데이터 제공​

2.5 데이터 처리 파이프라인​

2.5.1 실시간 처리​

2.5.2 배치 처리​

3. 비기능 요구사항​

3.1 성능​

3.2 확장성​

3.3 신뢰성​

3.4 보안​

3.5 모니터링​

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

4. 제약사항​

4.1 기술적 제약​

4.2 데이터 제약​

4.3 운영 제약​

4.4 GDPR 준수 및 데이터 보관 정책​

5. 가정사항​

5.1 시스템 환경​

5.2 사용자 환경​

5.3 데이터 환경​

6. 의존성​

6.1 내부 의존성​

6.2 외부 의존성​

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

7.1 통합 데이터 처리​

백엔드 요구사항​

7.2 인사이트 생성​

백엔드 요구사항​

8. ISO27001 정보보호 관리​

8.1 데이터 통합 보안​

백엔드 요구사항​

8.2 데이터 아카이빙​

백엔드 요구사항​

9. 변경 이력​

1. 도메인 개요

1.1 목적

1.2 핵심 책임

1.3 도메인 위치

2. 기능 요구사항

2.1 이벤트 구독 및 데이터 수집

2.1.1 Sleep 도메인 데이터 수집

2.1.2 Questionnaire 도메인 데이터 수집

2.1.3 Learning 도메인 데이터 수집

2.1.4 Medication 도메인 데이터 수집

2.1.5 Condition 도메인 데이터 수집

2.2 데이터 변환 및 구조화

2.2.1 LLM 친화적 데이터 변환

2.2.2 시계열 데이터 구조화

2.2.3 컨텍스트 정보 추가

2.2.4 Medication 데이터 변환

2.2.5 Condition 데이터 변환

2.3 Firestore 저장 구조

2.3.1 컬렉션 구조 관리

2.3.2 데이터 저장 규칙

2.3.3 Medication 데이터 저장 구조

2.3.4 Condition 데이터 저장 구조

2.4 데이터 제공 요구사항

2.4.1 사용자 프로필 데이터 제공

2.4.2 수면 데이터 제공

2.4.3 설문 데이터 제공

2.4.4 학습 데이터 제공

2.4.5 통합 인사이트 제공

2.4.6 Medication 데이터 제공

2.4.7 Condition 데이터 제공

2.5 데이터 처리 파이프라인

2.5.1 실시간 처리

2.5.2 배치 처리

3. 비기능 요구사항

3.1 성능

3.2 확장성

3.3 신뢰성

3.4 보안

3.5 모니터링

3.6 규제 준수(감사 추적)

4. 제약사항

4.1 기술적 제약

4.2 데이터 제약

4.3 운영 제약

4.4 GDPR 준수 및 데이터 보관 정책

5. 가정사항

5.1 시스템 환경

5.2 사용자 환경

5.3 데이터 환경

6. 의존성

6.1 내부 의존성

6.2 외부 의존성

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

7.1 통합 데이터 처리

백엔드 요구사항

7.2 인사이트 생성

백엔드 요구사항

8. ISO27001 정보보호 관리

8.1 데이터 통합 보안

백엔드 요구사항

8.2 데이터 아카이빙

백엔드 요구사항

9. 변경 이력