Agent Data API 엔드포인트

접근 권한 매트릭스

엔드포인트	System Admin	AI Agent Service	Support	Regular User
GET /v1/agent-data/users/`{userId}`/profile	✓	✓	✓	자신만
GET /v1/agent-data/users/`{userId}`/context	✓	✓	✓	자신만
GET /v1/agent-data/users/`{userId}`/sleep/patterns	✓	✓	✓	자신만
GET /v1/agent-data/users/`{userId}`/sleep/trends	✓	✓	✓	자신만
GET /v1/agent-data/users/`{userId}`/sleep/day-index/`{dayIndex}`	✓	✓	✓	자신만
GET /v1/agent-data/users/`{userId}`/sleep/records	✓	✓	✓	자신만
GET /v1/agent-data/users/`{userId}`/sleep/recent	✓	✓	✓	자신만
GET /v1/agent-data/users/`{userId}`/questionnaires/history	✓	✓	✓	자신만
GET /v1/agent-data/users/`{userId}`/questionnaires/trends	✓	✓	✓	자신만
GET /v1/agent-data/users/`{userId}`/questionnaires/latest	✓	✓	✓	자신만
GET /v1/agent-data/users/`{userId}`/learning/progress	✓	✓	✓	자신만
GET /v1/agent-data/users/`{userId}`/learning/knowledge	✓	✓	✓	자신만
GET /v1/agent-data/users/`{userId}`/learning/patterns	✓	✓	✓	자신만
GET /v1/agent-data/users/`{userId}`/medications/profiles	✓	✓	✓	자신만
GET /v1/agent-data/users/`{userId}`/medications/interactions	✓	✓	✓	자신만
GET /v1/agent-data/users/`{userId}`/medications/taper-plans	✓	✓	✓	자신만
GET /v1/agent-data/users/`{userId}`/medications/daily-summary	✓	✓	✓	자신만
GET /v1/agent-data/users/`{userId}`/insights/daily	✓	✓	✓	자신만
GET /v1/agent-data/users/`{userId}`/insights/weekly	✓	✓	✓	자신만
GET /v1/agent-data/users/`{userId}`/insights/integrated	✓	✓	✓	자신만

참고:

✓: 접근 가능

✘: 접근 불가

AI Agent Service: dta-wide-agent-flow 서비스의 서비스 계정

(자신만): 자신의 데이터에만 접근 가능

사용자 프로필 API

📌 기술 구현 문서: TBD

사용자 프로필 API는 AI Agent가 사용자의 전반적인 치료 상태와 컨텍스트를 이해하는데 필요한 핵심 정보를 제공합니다. 모든 데이터는 LLM이 이해하기 쉬운 명확한 필드명으로 구조화되어 제공됩니다.

사용자 치료 프로필 조회

HTTP 메서드: GET
경로: /v1/agent-data/users/{userId}/profile
Headers:
- Authorization: Bearer {accessToken}
설명: 사용자의 전반적인 치료 상태와 패턴 요약을 제공합니다. AI Agent가 개인화된 응답을 생성하는데 필요한 핵심 정보를 포함합니다.

응답 (Response)

성공 응답 (200 OK)

{
  "userId": "user_123",
  "treatmentInfo": {
    "startDate": "2024-01-01",
    "currentDay": 45,
    "treatmentPhase": "ACTIVE",
    "enrollmentType": "STANDARD",
    "therapistAssigned": false
  },
  "overallProgress": {
    "sleepTracking": {
      "totalRecords": 40,
      "consistencyRate": 88.9,
      "lastRecordedDate": "2024-02-14"
    },
    "questionnaires": {
      "completedCount": 6,
      "latestISIScore": 12,
      "latestPSQIScore": 8,
      "overallTrend": "IMPROVING"
    },
    "learning": {
      "completedLessons": 42,
      "totalLessons": 46,
      "progressPercentage": 91.3,
      "currentStreak": 5
    }
  },
  "keyInsights": {
    "primaryConcerns": ["수면 유지 어려움", "잦은 각성"],
    "improvementAreas": ["수면 효율성 증가", "입면 시간 단축"],
    "strengths": ["규칙적인 수면 일정", "학습 참여도 높음"]
  },
  "lastUpdated": "2024-02-14T23:30:00Z"
}

사용자 컨텍스트 정보 조회

HTTP 메서드: GET
경로: /v1/agent-data/users/{userId}/context
Headers:
- Authorization: Bearer {accessToken}
설명: AI Agent가 현재 대화 컨텍스트를 이해하는데 필요한 최신 정보를 제공합니다.

응답 (Response)

성공 응답 (200 OK)

{
  "userId": "user_123",
  "currentContext": {
    "treatmentDay": 45,
    "lastInteractionDate": "2024-02-14",
    "recentActivities": [
      {
        "type": "SLEEP_RECORD",
        "date": "2024-02-14",
        "summary": "총 수면시간 7시간 15분, 수면효율 85%"
      },
      {
        "type": "LESSON_COMPLETED",
        "date": "2024-02-13",
        "summary": "레슨 '수면과 면역 체계' 완료"
      }
    ],
    "upcomingTasks": [
      {
        "type": "QUESTIONNAIRE_DUE",
        "dueDate": "2024-02-16",
        "description": "ISI 설문 예정"
      }
    ],
    "currentChallenges": ["지난 주 대비 수면 효율성 5% 감소", "주말 수면 패턴 불규칙"]
  },
  "timestamp": "2024-02-14T23:45:00Z"
}

수면 데이터 API

📌 기술 구현 문서: TBD

수면 데이터 API는 사용자의 수면 패턴과 트렌드를 LLM이 이해하기 쉬운 형태로 제공합니다. 축약된 필드명을 명확한 이름으로 변환하고, 의미 있는 인사이트를 추가합니다.

수면 패턴 조회

HTTP 메서드: GET
경로: /v1/agent-data/users/{userId}/sleep/patterns
Headers:
- Authorization: Bearer {accessToken}
Query Parameters:
- period: 조회 기간 (7days, 30days, 90days) (기본값: 30days)
- includeDetails: 상세 데이터 포함 여부 (기본값: false)

응답 (Response)

성공 응답 (200 OK)

{
  "userId": "user_123",
  "period": "30days",
  "summary": {
    "averageSleepDuration": {
      "value": 6.8,
      "unit": "hours",
      "interpretation": "권장 수면 시간(7-9시간)보다 약간 부족"
    },
    "averageSleepEfficiency": {
      "value": 82.5,
      "unit": "percent",
      "interpretation": "양호한 수준 (85% 이상 권장)"
    },
    "averageSleepOnsetLatency": {
      "value": 22,
      "unit": "minutes",
      "interpretation": "정상 범위 (10-20분)를 약간 초과"
    },
    "averageWakeAfterSleepOnset": {
      "value": 35,
      "unit": "minutes",
      "interpretation": "정상 범위 내"
    },
    "weekdayVsWeekendPattern": {
      "weekdayAverage": 6.5,
      "weekendAverage": 7.2,
      "difference": 0.7,
      "interpretation": "주말에 수면 부채 보충 패턴 보임"
    }
  },
  "consistencyMetrics": {
    "bedtimeVariability": {
      "value": 45,
      "unit": "minutes",
      "interpretation": "일관성 개선 필요"
    },
    "waketimeVariability": {
      "value": 30,
      "unit": "minutes",
      "interpretation": "양호한 일관성"
    }
  },
  "trends": {
    "sleepEfficiencyTrend": "IMPROVING",
    "sleepDurationTrend": "STABLE",
    "sleepQualityTrend": "IMPROVING"
  },
  "analysisDate": "2024-02-14"
}

수면 트렌드 분석 조회

HTTP 메서드: GET
경로: /v1/agent-data/users/{userId}/sleep/trends
Headers:
- Authorization: Bearer {accessToken}
Query Parameters:
- compareWith: 비교 기간 (previousWeek, previousMonth, treatmentStart)

응답 (Response)

성공 응답 (200 OK)

{
  "userId": "user_123",
  "currentPeriod": {
    "start": "2024-02-08",
    "end": "2024-02-14"
  },
  "comparisonPeriod": {
    "start": "2024-02-01",
    "end": "2024-02-07"
  },
  "changes": {
    "sleepEfficiency": {
      "current": 82.5,
      "previous": 78.3,
      "changePercent": 5.4,
      "changeDirection": "IMPROVED",
      "significance": "임상적으로 의미 있는 개선"
    },
    "totalSleepTime": {
      "current": 6.8,
      "previous": 6.5,
      "changeHours": 0.3,
      "changeDirection": "INCREASED",
      "significance": "약간의 개선"
    },
    "sleepOnsetLatency": {
      "current": 22,
      "previous": 28,
      "changeMinutes": -6,
      "changeDirection": "IMPROVED",
      "significance": "눈에 띄는 개선"
    },
    "numberOfAwakenings": {
      "current": 2.3,
      "previous": 3.1,
      "changeCount": -0.8,
      "changeDirection": "DECREASED",
      "significance": "수면 연속성 개선"
    }
  },
  "insights": ["수면 효율성이 지속적으로 개선되고 있습니다", "입면 시간이 단축되어 수면 시작이 쉬워졌습니다", "밤중 각성 횟수가 감소하여 수면의 질이 향상되었습니다"]
}

특정 dayIndex 수면 데이터 조회

HTTP 메서드: GET
경로: /v1/agent-data/users/{userId}/sleep/day-index/{dayIndex}
Headers:
- Authorization: Bearer {accessToken}
Path Parameters:
- dayIndex: 조회할 치료 일차

응답 (Response)

성공 응답 (200 OK)

{
  "userId": "user_123",
  "dayIndex": 45,
  "date": "2024-02-14",
  "sleepData": {
    "bedTime": "23:15",
    "wakeTime": "06:45",
    "totalSleepTimeHours": 7.25,
    "sleepEfficiencyPercent": 85.4,
    "sleepOnsetLatencyMinutes": 18,
    "wakeAfterSleepOnsetMinutes": 25,
    "numberOfAwakenings": 2,
    "sleepQuality": "좋음",
    "didNotSleep": false,
    "sleepMedicationUsed": false,
    "napDurationMinutes": 30,
    "positiveFactors": ["규칙적인 운동", "저녁 독서"],
    "negativeFactors": [],
    "customPositiveFactors": ["따뜻한 샤워"],
    "customNegativeFactors": [],
    "notes": "카페인 섭취를 줄인 후 수면의 질이 개선됨"
  },
  "contextualInfo": {
    "dayOfWeek": "Wednesday",
    "treatmentDay": 45,
    "isTemporaryRecord": false,
    "comparedToAverage": {
      "sleepEfficiency": "+3.0%",
      "totalSleepTime": "+0.2 hours"
    }
  }
}

오류 응답 (404 Not Found)

{
  "code": 3001,
  "message": "SLEEP_DATA_NOT_FOUND",
  "detail": "해당 dayIndex의 수면 데이터가 없습니다."
}

변환된 수면 기록 목록 조회 (AI Agent Tool용)

📌 구현 위치: libs/feature/agent-data/src/lib/application/events/handlers/agent-data-cross-event-receiver.ts에서 변환된 데이터

HTTP 메서드: GET
경로: /v1/agent-data/users/{userId}/sleep/records
Headers:
- Authorization: Bearer {accessToken}
Query Parameters:
- limit: 조회할 기록 수 (기본값: 100, 최대: 500)
- sortOrder: 정렬 순서 (DESC: 최신순, ASC: 오래된순) (기본값: DESC)
- includeInvalidData: 유효하지 않은 데이터 포함 여부 (기본값: false)
- fromDayIndex: 시작 dayIndex (선택사항)
- toDayIndex: 종료 dayIndex (선택사항)
설명: LLM Tool이 사용자의 모든 수면 기록에 접근할 수 있도록 변환된 원시 데이터를 제공합니다. 크로스 이벤트 수신기에서 변환하여 Firestore에 저장된 데이터를 한번의 호출로 조회합니다.

응답 (Response)

성공 응답 (200 OK)

{
  "userId": "user_123",
  "totalRecords": 45,
  "returnedRecords": 10,
  "dayIndexRange": {
    "from": 36,
    "to": 45
  },
  "sleepRecords": [
    {
      "dayIndex": 45,
      "date": "2024-02-14",
      "hasValidData": true,
      "sleepData": {
        "bedTime": "23:15",
        "wakeTime": "06:45",
        "totalSleepTimeHours": 7.25,
        "sleepEfficiencyPercent": 85.4,
        "sleepOnsetLatencyMinutes": 18,
        "wakeAfterSleepOnsetMinutes": 25,
        "sleepQuality": "좋음",
        "didNotSleep": false,
        "sleepMedicationUsed": false,
        "napDurationMinutes": 30,
        "positiveFactors": ["규칙적인 운동", "저녁 독서"],
        "negativeFactors": [],
        "customPositiveFactors": ["따뜻한 샤워"],
        "customNegativeFactors": [],
        "notes": "오늘은 특별히 숙면을 취했음"
      },
      "contextInfo": {
        "treatmentDay": 45,
        "dayOfWeek": "Wednesday",
        "isWeekend": false,
        "isTemporaryRecord": false
      },
      "id": "sleep_data_123",
      "userCycleId": "cycle_123",
      "originalEventId": "event_123",
      "schemaVersion": "1.0",
      "recordedAt": "2024-02-15T07:30:00Z",
      "createdAt": "2024-02-15T08:00:00Z",
      "processedAt": "2024-02-15T08:00:05Z"
    },
    {
      "dayIndex": 44,
      "date": "2024-02-13",
      "hasValidData": true,
      "sleepData": {
        "bedTime": "23:30",
        "wakeTime": "06:45",
        "totalSleepTimeHours": 6.9,
        "sleepEfficiencyPercent": 82.1,
        "sleepOnsetLatencyMinutes": 22,
        "wakeAfterSleepOnsetMinutes": 30,
        "sleepQuality": "보통",
        "didNotSleep": false,
        "sleepMedicationUsed": true,
        "napDurationMinutes": 0,
        "positiveFactors": ["일정한 취침 시간"],
        "negativeFactors": ["카페인 과다 섭취"],
        "customPositiveFactors": [],
        "customNegativeFactors": ["스트레스"],
        "notes": null
      },
      "contextInfo": {
        "treatmentDay": 44,
        "dayOfWeek": "Tuesday",
        "isWeekend": false,
        "isTemporaryRecord": false
      },
      "id": "sleep_data_124",
      "userCycleId": "cycle_123",
      "originalEventId": "event_124",
      "schemaVersion": "1.0",
      "recordedAt": "2024-02-14T19:45:00Z",
      "createdAt": "2024-02-14T20:00:00Z",
      "processedAt": "2024-02-14T20:00:05Z"
    },
    {
      "dayIndex": 43,
      "date": "2024-02-12",
      "hasValidData": false,
      "sleepData": {
        "bedTime": null,
        "wakeTime": null,
        "totalSleepTimeHours": null,
        "sleepEfficiencyPercent": null,
        "sleepOnsetLatencyMinutes": null,
        "wakeAfterSleepOnsetMinutes": null,
        "sleepQuality": "데이터 없음",
        "didNotSleep": true,
        "sleepMedicationUsed": false,
        "napDurationMinutes": 0,
        "positiveFactors": [],
        "negativeFactors": [],
        "customPositiveFactors": [],
        "customNegativeFactors": ["밤새 깨어있음"],
        "notes": null
      },
      "contextInfo": {
        "treatmentDay": 43,
        "dayOfWeek": "Monday",
        "isWeekend": false,
        "isTemporaryRecord": false
      },
      "id": "sleep_data_125",
      "userCycleId": "cycle_123",
      "originalEventId": "event_125",
      "schemaVersion": "1.0",
      "recordedAt": null,
      "createdAt": "2024-02-13T08:00:00Z",
      "processedAt": "2024-02-13T08:00:05Z"
    }
  ]
}

최근 수면 기록 조회 (dayIndex 기준)

📌 구현 위치: libs/feature/agent-data/src/lib/application/events/handlers/agent-data-cross-event-receiver.ts에서 변환된 데이터

HTTP 메서드: GET
경로: /v1/agent-data/users/{userId}/sleep/recent
Headers:
- Authorization: Bearer {accessToken}
Query Parameters:
- fromDayIndex: 기준 dayIndex (기본값: 현재 사용자의 최신 dayIndex)
- days: 조회할 최근 일수 (기본값: 7, 최대: 30)
- includeInvalidData: 유효하지 않은 데이터 포함 여부 (기본값: false)
설명: 특정 dayIndex를 기준으로 최근 x일간의 변환된 수면 기록을 조회합니다. 내부적으로는 3.4 엔드포인트와 동일한 구조로 응답합니다.

응답 (Response)

성공 응답 (200 OK): 3.4 엔드포인트와 동일한 형식
오류 응답: 3.4 엔드포인트와 동일

설문 데이터 API

📌 기술 구현 문서: TBD

설문 데이터 API는 사용자가 작성한 다양한 설문(ISI, PSQI, PHQ-9 등)의 응답과 점수를 LLM이 이해하기 쉬운 형태로 제공합니다. 설문 점수의 의미와 변화 추이를 포함합니다.

설문 응답 이력 조회

HTTP 메서드: GET
경로: /v1/agent-data/users/{userId}/questionnaires/history
Headers:
- Authorization: Bearer {accessToken}
Query Parameters:
- type: 설문 유형 (ISI, PSQI, PHQ-9, ALL) (기본값: ALL)
- limit: 조회 개수 (기본값: 10)

응답 (Response)

성공 응답 (200 OK)

{
  "userId": "user_123",
  "questionnaires": [
    {
      "id": "response_456",
      "type": "ISI",
      "completedAt": "2024-02-10T20:00:00Z",
      "treatmentDay": 41,
      "score": {
        "total": 12,
        "maxPossible": 28,
        "severity": "MODERATE",
        "interpretation": "중등도 불면증"
      },
      "subscores": {
        "sleepOnset": 2,
        "sleepMaintenance": 3,
        "earlyAwakening": 2,
        "satisfaction": 2,
        "interference": 3
      },
      "keyFindings": ["수면 유지에 가장 큰 어려움", "일상 생활 방해 정도가 중간 수준"]
    },
    {
      "id": "response_789",
      "type": "PSQI",
      "completedAt": "2024-02-03T19:30:00Z",
      "treatmentDay": 34,
      "score": {
        "total": 8,
        "maxPossible": 21,
        "severity": "POOR_SLEEPER",
        "interpretation": "수면의 질 불량"
      },
      "components": {
        "subjectiveSleepQuality": 2,
        "sleepLatency": 2,
        "sleepDuration": 1,
        "habitualSleepEfficiency": 1,
        "sleepDisturbances": 1,
        "sleepMedication": 0,
        "daytimeDysfunction": 1
      },
      "keyFindings": ["주관적 수면의 질이 낮음", "입면 잠복기가 김", "수면제 사용하지 않음"]
    }
  ],
  "summary": {
    "totalResponses": 6,
    "latestAssessment": "전반적으로 개선 추세",
    "consistencyInResponses": "높음"
  }
}

설문 점수 추이 조회

HTTP 메서드: GET
경로: /v1/agent-data/users/{userId}/questionnaires/trends
Headers:
- Authorization: Bearer {accessToken}
Query Parameters:
- type: 설문 유형 (ISI, PSQI, PHQ-9)

응답 (Response)

성공 응답 (200 OK)

{
  "userId": "user_123",
  "questionnaireType": "ISI",
  "trends": {
    "dataPoints": [
      {
        "date": "2024-01-07",
        "score": 18,
        "treatmentDay": 7,
        "severity": "MODERATE_TO_SEVERE"
      },
      {
        "date": "2024-01-21",
        "score": 15,
        "treatmentDay": 21,
        "severity": "MODERATE"
      },
      {
        "date": "2024-02-04",
        "score": 13,
        "treatmentDay": 35,
        "severity": "MODERATE"
      },
      {
        "date": "2024-02-10",
        "score": 12,
        "treatmentDay": 41,
        "severity": "MODERATE"
      }
    ],
    "analysis": {
      "overallTrend": "IMPROVING",
      "scoreReduction": 6,
      "percentImprovement": 33.3,
      "clinicallySignificant": true,
      "projectedTrajectory": "지속적 개선 예상"
    },
    "insights": ["치료 시작 이후 ISI 점수가 33% 감소했습니다", "임상적으로 의미 있는 개선을 보이고 있습니다", "현재 추세가 지속되면 경도 불면증 수준 도달 가능합니다"]
  }
}

학습 데이터 API

📌 기술 구현 문서: TBD

학습 데이터 API는 사용자의 수면탐구 학습 진행 상황과 숙지한 개념들을 AI Agent가 활용할 수 있는 형태로 제공합니다. 단순한 진도율뿐만 아니라 실제 학습한 내용과 이해도를 포함합니다.

학습 진도 현황 조회

HTTP 메서드: GET
경로: /v1/agent-data/users/{userId}/learning/progress
Headers:
- Authorization: Bearer {accessToken}

응답 (Response)

성공 응답 (200 OK)

{
  "userId": "user_123",
  "learningProgress": {
    "currentLessonId": "lesson_45",
    "totalLessons": 46,
    "completedLessons": 42,
    "progressPercentage": 91.3,
    "currentStreak": 5,
    "longestStreak": 12,
    "averageSessionDuration": 18.5,
    "totalLearningTime": 420
  },
  "recentActivity": [
    {
      "lessonId": "lesson_42",
      "lessonTitle": "수면과 면역 체계",
      "completedAt": "2024-02-13T20:30:00Z",
      "sessionDuration": 15,
      "comprehensionScore": 0.92
    }
  ],
  "upcomingLessons": [
    {
      "lessonId": "lesson_43",
      "lessonTitle": "스트레스와 수면",
      "estimatedDuration": 20,
      "difficulty": "INTERMEDIATE"
    }
  ]
}

숙지 개념 및 지식 조회

📌 구현 상태: 개발 예정

HTTP 메서드: GET
경로: /v1/agent-data/users/{userId}/learning/knowledge
Headers:
- Authorization: Bearer {accessToken}
설명: 사용자가 학습을 통해 숙지한 개념과 지식을 조회합니다.

응답 (Response)

성공 응답 (200 OK)

{
  "userId": "user_123",
  "knowledgeBase": {
    "masteredConcepts": [
      {
        "conceptId": "sleep_hygiene",
        "conceptName": "수면 위생",
        "masteryLevel": 0.95,
        "lastReviewed": "2024-02-10"
      }
    ],
    "keyLearnings": ["규칙적인 수면 스케줄의 중요성", "카페인이 수면에 미치는 영향"]
  }
}

학습 패턴 분석 조회

📌 구현 상태: 개발 예정

HTTP 메서드: GET
경로: /v1/agent-data/users/{userId}/learning/patterns
Headers:
- Authorization: Bearer {accessToken}
설명: 사용자의 학습 패턴과 선호도를 분석하여 제공합니다.

응답 (Response)

성공 응답 (200 OK)

{
  "userId": "user_123",
  "learningPatterns": {
    "preferredLearningTime": "evening",
    "optimalSessionDuration": 18,
    "retentionRate": 0.87,
    "challengingTopics": ["REM 수면", "수면 아키텍처"]
  }
}

약물 데이터 API

📌 기술 구현 문서: TBD

약물 데이터 API는 사용자의 약물 프로필, 상호작용 경고, 감량 계획 등을 AI Agent가 활용할 수 있는 형태로 제공합니다. 지식 그래프 기반 약물 정보와 OCR/LLM 메타데이터를 포함하여 안전한 약물 관리를 지원합니다.

약물 프로필 조회

HTTP 메서드: GET
경로: /v1/agent-data/users/{userId}/medications/profiles
Headers:
- Authorization: Bearer {accessToken}
Query Parameters:
- activeOnly: 현재 복용 중인 약물만 조회 (기본값: true)
- includeStopped: 중단된 약물 포함 (기본값: false)
설명: 사용자의 약물 프로필 목록을 지식 그래프 요약 정보와 함께 제공합니다.

응답 (Response)

성공 응답 (200 OK)

{
  "userId": "user_123",
  "medications": [
    {
      "medicationId": "med_001",
      "medicationProfile": {
        "medicationName": "Zolpidem",
        "dosagePerIntakeMg": 10,
        "medicationForm": "tablet",
        "intakeTimesOfDay": ["21:30"],
        "isPrescription": true,
        "prescriptionType": "Acute",
        "startDate": "2024-01-15",
        "endDate": null,
        "indicationCategory": "sleep_medication"
      },
      "knowledgeGraphSummary": {
        "activeIngredients": ["Zolpidem tartrate"],
        "therapeuticClass": "Hypnotic",
        "indicationTags": ["insomnia", "sleep_onset_difficulty"],
        "interactionRiskLevel": "Moderate",
        "sideEffects": ["drowsiness", "dizziness", "headache"]
      },
      "dataCollectionMetadata": {
        "dataCollectionMethod": "manual",
        "dataConfidenceLevel": "high",
        "needsVerification": false
      }
    },
    {
      "medicationId": "med_002",
      "medicationProfile": {
        "medicationName": "Sertraline",
        "dosagePerIntakeMg": 50,
        "medicationForm": "tablet",
        "intakeTimesOfDay": ["08:00"],
        "isPrescription": true,
        "prescriptionType": "Chronic",
        "startDate": "2023-11-20",
        "endDate": null,
        "indicationCategory": "antidepressant"
      },
      "knowledgeGraphSummary": {
        "activeIngredients": ["Sertraline hydrochloride"],
        "therapeuticClass": "SSRI",
        "indicationTags": ["depression", "anxiety", "ocd"],
        "interactionRiskLevel": "Moderate",
        "sideEffects": ["nausea", "insomnia", "dry_mouth"]
      },
      "dataCollectionMetadata": {
        "dataCollectionMethod": "ocr",
        "dataConfidenceLevel": "medium",
        "ocrModelVersion": "vision-1.2.0",
        "imageHash": "abc123def456",
        "needsVerification": true
      }
    }
  ],
  "summary": {
    "totalActive": 2,
    "prescriptionCount": 2,
    "overTheCounterCount": 0
  }
}

약물 상호작용 경고 조회

HTTP 메서드: GET
경로: /v1/agent-data/users/{userId}/medications/interactions
Headers:
- Authorization: Bearer {accessToken}
Query Parameters:
- severity: 심각도 필터 (Low, Moderate, High, Severe) (선택사항)
- activeOnly: 활성 경고만 조회 (기본값: true)
설명: 사용자의 약물 간 상호작용 경고를 제공합니다 (5초 이내 SLA).

응답 (Response)

성공 응답 (200 OK)

{
  "userId": "user_123",
  "interactionAlerts": [
    {
      "alertId": "alert_001",
      "interactions": [
        {
          "medication1": "Zolpidem",
          "medication2": "Sertraline",
          "interactionType": "drug_drug",
          "severity": "Moderate",
          "description": "세로토닌 증후군 위험 증가 가능성",
          "clinicalRecommendation": "증상 모니터링 필요. 혼란, 근육 경련, 발한 등 발생 시 즉시 의료진 상담"
        }
      ],
      "recommendations": {
        "actionRequired": true,
        "suggestedAction": "정기적인 증상 모니터링 및 의사와 상담",
        "consultPhysician": true,
        "monitoringRequired": true
      },
      "contextInfo": {
        "dayIndex": 45,
        "triggeredBy": "medication-profile-captured"
      },
      "alertedAt": "2024-02-14T08:15:00Z",
      "expiresAt": null
    }
  ],
  "summary": {
    "totalAlerts": 1,
    "highSeverityCount": 0,
    "requiresImmediateAction": 0
  }
}

약물 감량 계획 조회

HTTP 메서드: GET
경로: /v1/agent-data/users/{userId}/medications/taper-plans
Headers:
- Authorization: Bearer {accessToken}
Query Parameters:
- medicationId: 특정 약물의 감량 계획 조회 (선택사항)
설명: AI/의사가 생성한 약물 감량 계획을 제공합니다.

응답 (Response)

성공 응답 (200 OK)

{
  "userId": "user_123",
  "taperPlans": [
    {
      "planId": "taper_001",
      "medicationId": "med_001",
      "medicationName": "Zolpidem",
      "currentDosageMg": 10,
      "targetDosageMg": 0,
      "durationWeeks": 4,
      "schedule": [
        {
          "weekNumber": 1,
          "dosageMg": 7.5,
          "notes": "25% 감량 - 취침 전 복용"
        },
        {
          "weekNumber": 2,
          "dosageMg": 5,
          "notes": "50% 감량 - 수면 패턴 모니터링"
        },
        {
          "weekNumber": 3,
          "dosageMg": 2.5,
          "notes": "75% 감량 - 반드시 필요시만 복용"
        },
        {
          "weekNumber": 4,
          "dosageMg": 0,
          "notes": "완전 중단 - CBT-I 기법 활용"
        }
      ],
      "rationale": "수면 효율성이 85% 이상 유지되고 있어 약물 감량 적합 시기",
      "generatedAt": "2024-02-10T15:30:00Z"
    }
  ]
}

일일 약물 요약 조회

HTTP 메서드: GET
경로: /v1/agent-data/users/{userId}/medications/daily-summary
Headers:
- Authorization: Bearer {accessToken}
Query Parameters:
- dayIndex: 조회할 일차 (기본값: 현재 dayIndex)
설명: 특정 일차의 약물 복용 현황 요약을 제공합니다.

응답 (Response)

성공 응답 (200 OK)

{
  "userId": "user_123",
  "dayIndex": 45,
  "date": "2024-02-14",
  "medicationsActive": {
    "totalCount": 2,
    "prescriptionCount": 2,
    "overTheCounterCount": 0,
    "byTherapeuticClass": {
      "Hypnotic": 1,
      "SSRI": 1
    }
  },
  "complianceStatus": {
    "expectedIntakes": 2,
    "recordedIntakes": 2,
    "complianceRate": 100,
    "missedDoses": []
  },
  "alertsSummary": {
    "interactionAlertsCount": 1,
    "highSeverityAlertsCount": 0,
    "recommendations": ["세로토닌 증후군 증상 모니터링"]
  }
}

통합 인사이트 API

📌 기술 구현 문서: 개발 예정

통합 인사이트 API는 사용자의 수면, 설문, 학습 데이터를 종합 분석하여 의미 있는 인사이트를 제공합니다.

일일 인사이트 조회

📌 구현 상태: 개발 예정

HTTP 메서드: GET
경로: /v1/agent-data/users/{userId}/insights/daily
Headers:
- Authorization: Bearer {accessToken}
Query Parameters:
- date: 조회할 날짜 (YYYY-MM-DD) (기본값: 오늘)

응답 (Response)

성공 응답 (200 OK)

{
  "userId": "user_123",
  "date": "2024-02-14",
  "dailyInsights": {
    "sleepQuality": "양호",
    "moodTrend": "개선",
    "learningEngagement": "높음",
    "recommendations": ["오늘 수면 효율이 좋았습니다. 동일한 루틴을 유지하세요.", "학습 참여도가 높습니다. 심화 내용 학습을 고려해보세요."]
  }
}

주간 인사이트 조회

📌 구현 상태: 개발 예정

HTTP 메서드: GET
경로: /v1/agent-data/users/{userId}/insights/weekly
Headers:
- Authorization: Bearer {accessToken}
Query Parameters:
- week: 조회할 주 (YYYY-Www) (기본값: 이번 주)

응답 (Response)

성공 응답 (200 OK)

{
  "userId": "user_123",
  "week": "2024-W07",
  "weeklyInsights": {
    "overallTrend": "개선",
    "keyAchievements": ["수면 효율 85% 달성", "ISI 점수 2점 감소"],
    "areasForImprovement": ["주말 수면 패턴 일관성"]
  }
}

종합 인사이트 조회

📌 구현 상태: 개발 예정

HTTP 메서드: GET
경로: /v1/agent-data/users/{userId}/insights/integrated
Headers:
- Authorization: Bearer {accessToken}
Query Parameters:
- period: 분석 기간 (30days, 90days) (기본값: 30days)

응답 (Response)

성공 응답 (200 OK)

{
  "userId": "user_123",
  "period": "30days",
  "integratedInsights": {
    "treatmentProgress": "우수",
    "correlations": [
      {
        "factor1": "학습 완료율",
        "factor2": "수면 효율",
        "correlation": 0.73,
        "interpretation": "학습 참여도가 높을수록 수면의 질이 향상됨"
      }
    ],
    "predictiveInsights": ["현재 추세가 지속되면 4주 내 목표 달성 가능"]
  }
}

오류 코드

오류 코드	설명	HTTP 상태
3001	SLEEP_DATA_NOT_FOUND	404
3002	QUESTIONNAIRE_DATA_NOT_FOUND	404
3003	LEARNING_DATA_NOT_FOUND	404
3004	INSIGHT_GENERATION_FAILED	500
3005	DATA_AGGREGATION_ERROR	500
3006	INVALID_DATE_RANGE	400
3007	USER_DATA_ACCESS_DENIED	403
3008	MEDICATION_DATA_NOT_FOUND	404
3009	MEDICATION_INTERACTION_CHECK_FAILED	500
3010	KNOWLEDGE_GRAPH_UNAVAILABLE	503
3011	TAPER_PLAN_GENERATION_FAILED	500

변경 이력

v1.0.0 (2024-02-15)

초기 API 엔드포인트 정의
사용자 프로필 API 구현
수면 데이터 API 구현
설문 데이터 API 구현
학습 데이터 API 기본 구조 정의

v1.1.0 (2025-11-10)

약물 데이터 API 추가
약물 프로필, 상호작용 경고, 감량 계획 엔드포인트 정의
지식 그래프 기반 약물 정보 제공 구조 설계
OCR/LLM 메타데이터 포함 구조 추가

개발 예정

통합 인사이트 API 구현 (약물 데이터 포함)
학습 패턴 분석 고도화
실시간 데이터 스트리밍 지원
약물-수면 상관관계 분석 API

목차​

관련 문서​

접근 권한 매트릭스​

사용자 프로필 API​

사용자 치료 프로필 조회​

응답 (Response)​

사용자 컨텍스트 정보 조회​

응답 (Response)​

수면 데이터 API​

수면 패턴 조회​

응답 (Response)​

수면 트렌드 분석 조회​

응답 (Response)​

특정 dayIndex 수면 데이터 조회​

응답 (Response)​

변환된 수면 기록 목록 조회 (AI Agent Tool용)​

응답 (Response)​

최근 수면 기록 조회 (dayIndex 기준)​

응답 (Response)​

설문 데이터 API​

설문 응답 이력 조회​

응답 (Response)​

설문 점수 추이 조회​

응답 (Response)​

최신 설문 결과 조회​

응답 (Response)​

학습 데이터 API​

학습 진도 현황 조회​

응답 (Response)​

숙지 개념 및 지식 조회​

응답 (Response)​

학습 패턴 분석 조회​

응답 (Response)​

약물 데이터 API​

약물 프로필 조회​

응답 (Response)​

약물 상호작용 경고 조회​

응답 (Response)​

약물 감량 계획 조회​

응답 (Response)​

일일 약물 요약 조회​

응답 (Response)​

통합 인사이트 API​

일일 인사이트 조회​

응답 (Response)​

주간 인사이트 조회​

응답 (Response)​

종합 인사이트 조회​

응답 (Response)​

오류 코드​

변경 이력​

v1.0.0 (2024-02-15)​

v1.1.0 (2025-11-10)​

개발 예정​

목차

관련 문서

접근 권한 매트릭스

사용자 프로필 API

사용자 치료 프로필 조회

응답 (Response)

사용자 컨텍스트 정보 조회

응답 (Response)

수면 데이터 API

수면 패턴 조회

응답 (Response)

수면 트렌드 분석 조회

응답 (Response)

특정 dayIndex 수면 데이터 조회

응답 (Response)

변환된 수면 기록 목록 조회 (AI Agent Tool용)

응답 (Response)

최근 수면 기록 조회 (dayIndex 기준)

응답 (Response)

설문 데이터 API

설문 응답 이력 조회

응답 (Response)

설문 점수 추이 조회

응답 (Response)

최신 설문 결과 조회

응답 (Response)

학습 데이터 API

학습 진도 현황 조회

응답 (Response)

숙지 개념 및 지식 조회

응답 (Response)

학습 패턴 분석 조회

응답 (Response)

약물 데이터 API

약물 프로필 조회

응답 (Response)

약물 상호작용 경고 조회

응답 (Response)

약물 감량 계획 조회

응답 (Response)

일일 약물 요약 조회

응답 (Response)

통합 인사이트 API

일일 인사이트 조회

응답 (Response)

주간 인사이트 조회

응답 (Response)

종합 인사이트 조회

응답 (Response)

오류 코드

변경 이력

v1.0.0 (2024-02-15)

v1.1.0 (2025-11-10)

개발 예정