Sleep Quality Chain of Debate API 엔드포인트

접근 권한 매트릭스

엔드포인트	System Admin	IAM Admin	Medical Professional	Service Account	Regular User	비고
POST /v1/sleep-quality-cod/predict	✓	✓	✓	✓	✓	수동 예측 요청
GET /v1/sleep-quality-cod/predictions/`{predictionId}`	✓	✓	✓	✓	✓	자신의 예측 결과만
GET /v1/sleep-quality-cod/predictions/history	✓	✓	✓	✓	✓	자신의 예측 히스토리
GET /v1/sleep-quality-cod/schedules/current	✓	✓	✓	✓	✓	현재 예측 스케줄
PUT /v1/sleep-quality-cod/schedules/update	✓	✓	✘	✓	✘	시스템 관리용
DELETE /v1/sleep-quality-cod/schedules/`{scheduleId}`	✓	✓	✘	✓	✘	스케줄 취소
GET /v1/sleep-quality-cod/debates/`{sessionId}`	✓	✓	✓	✓	✘	토론 상세 내역
GET /v1/sleep-quality-cod/analyses/expert/`{analysisId}`	✓	✓	✓	✓	✘	전문가 분석 상세
GET /v1/sleep-quality-cod/recommendations/`{predictionId}`	✓	✓	✓	✓	✓	권장사항 조회
GET /v1/sleep-quality-cod/performance/overview	✓	✓	✘	✓	✘	시스템 성능 개요
GET /v1/sleep-quality-cod/performance/agents	✓	✓	✘	✓	✘	에이전트별 성능
GET /v1/sleep-quality-cod/admin/users/`{userId}`/predictions	✓	✓	✓	✓	✘	관리자/의료진 전용
POST /v1/sleep-quality-cod/admin/users/`{userId}`/archive	✓	✓	✘	✘	✘	데이터 아카이빙
DELETE /v1/sleep-quality-cod/admin/users/`{userId}`/data	✓	✓	✘	✘	✘	데이터 삭제
GET /v1/sleep-quality-cod/users/me/data-export	✘	✘	✘	✘	✓	내 데이터 추출

참고:

✓: 접근 가능

✘: 접근 불가

Medical Professional: 의료진 (향후 연동 예정)

Service Account: MCP 서버, 배치 작업 등 시스템 계정

예측 관리 API

📌 구현 순서: 예측 관리 API는 SOL CoD 도메인의 핵심 기능이며 가장 먼저 구현되어야 합니다.

1.1 SOL(Sleep Onset Latency) 예측 요청 API

HTTP 메서드: POST
경로: /v1/sol-cod/predict
Headers:
- Content-Type: application/json
- Authorization: Bearer {accessToken}

요청 (Request)

{
  "triggerType": "MANUAL_REQUEST",
  "userId": "user123",
  "analysisScope": {
    "includeTreatmentCycleData": true,
    "includeQuestionnaireData": true,
    "customDateRange": {
      "startDate": "2025-01-01",
      "endDate": "2025-08-31"
    }
  },
  "options": {
    "forceExecution": false,
    "priority": "NORMAL"
  }
}

응답 (Response)

{
  "success": true,
  "data": {
    "predictionId": "pred_202508311400_user123",
    "status": "IN_PROGRESS",
    "estimatedCompletionTime": "2025-08-31T14:00:30Z",
    "participatingAgents": 4,
    "dataCompleteness": {
      "sleepDays": 14,
      "questionnaireAvailable": true,
      "totalScore": 0.95
    }
  },
  "meta": {
    "requestId": "req_12345",
    "timestamp": "2025-08-31T14:00:05Z"
  }
}

1.2 예측 결과 조회 API

HTTP 메서드: GET
경로: /v1/sol-cod/predictions/{predictionId}
Headers:
- Authorization: Bearer {accessToken}

응답 (Response)

{
  "success": true,
  "data": {
    "predictionId": "pred_202508311400_user123",
    "userId": "user123",
    "predictionDate": "2025-08-31",
    "status": "COMPLETED",
    "processingTime": 23500,
    "result": {
      "solScore": 35,
      "confidenceScore": 0.87,
      "participatingAgents": 4,
      "consensusReached": true,
      "keyFindings": ["수면 효율이 지속적으로 개선되고 있습니다", "입면 시간이 안정화되는 패턴을 보입니다", "수면 환경 최적화가 긍정적 효과를 보이고 있습니다"],
      "concernAreas": ["수면 중 각성 빈도 증가", "주말 수면 패턴 불일치"]
    },
    "dataUsed": {
      "sleepDataDays": 14,
      "questionnaireIncluded": true,
      "mobileDataAvailable": true,
      "dataQualityScore": 0.95
    },
    "debateInfo": {
      "sessionId": "debate_202508311400_001",
      "totalRounds": 2,
      "finalConsensusScore": 0.83,
      "debateTime": 18200
    }
  },
  "meta": {
    "requestId": "req_12346",
    "timestamp": "2025-08-31T14:01:30Z"
  }
}

1.3 예측 히스토리 조회 API

HTTP 메서드: GET
경로: /v1/sol-cod/predictions/history
Query Parameters:
- limit: number (기본값: 20, 최대: 100)
- offset: number (기본값: 0)
- startDate: string (ISO 8601 형식, 선택사항)
- endDate: string (ISO 8601 형식, 선택사항)
- status: string (ALL, COMPLETED, FAILED, IN_PROGRESS, 기본값: ALL)

응답 (Response)

{
  "success": true,
  "data": {
    "predictions": [
      {
        "predictionId": "pred_202508311400_user123",
        "predictionDate": "2025-08-31T14:00:05Z",
        "status": "COMPLETED",
        "solScore": 35,
        "confidenceScore": 0.87,
        "processingTime": 23500,
        "participatingAgents": 4,
        "triggerType": "AUTO_SCHEDULE"
      }
    ],
    "pagination": {
      "total": 45,
      "limit": 20,
      "offset": 0,
      "hasNext": true
    },
    "summary": {
      "averageSOLScore": 32,
      "averageConfidenceScore": 0.82,
      "totalPredictions": 45,
      "lastPredictionDate": "2025-08-31T14:00:05Z"
    }
  },
  "meta": {
    "requestId": "req_12347",
    "timestamp": "2025-08-31T15:30:00Z"
  }
}

스케줄링 관리 API

2.1 현재 스케줄 조회 API

HTTP 메서드: GET
경로: /v1/sol-cod/schedules/current
Headers:
- Authorization: Bearer {accessToken}

응답 (Response)

{
  "success": true,
  "data": {
    "scheduleId": "sched_202508312200_user123",
    "userId": "user123",
    "bedtimeGoal": "2025-08-31T23:00:00Z",
    "scheduledTriggerTime": "2025-08-31T22:00:00Z",
    "status": "SCHEDULED",
    "retryCount": 0,
    "nextExecution": "2025-08-31T22:00:00Z",
    "timezone": "Asia/Seoul"
  },
  "meta": {
    "requestId": "req_12348",
    "timestamp": "2025-08-31T16:00:00Z"
  }
}

2.2 스케줄 업데이트 API (관리자 전용)

HTTP 메서드: PUT
경로: /v1/sol-cod/schedules/update
Headers:
- Content-Type: application/json
- Authorization: Bearer {accessToken}

요청 (Request)

{
  "userId": "user123",
  "newBedtimeGoal": "2025-08-31T23:30:00Z",
  "reason": "BEDTIME_GOAL_CHANGED",
  "forceReschedule": true
}

2.3 스케줄 취소 API (관리자 전용)

HTTP 메서드: DELETE
경로: /v1/sol-cod/schedules/{scheduleId}
Headers:
- Authorization: Bearer {accessToken}

분석 결과 조회 API

3.1 토론 세션 상세 조회 API

HTTP 메서드: GET
경로: /v1/sol-cod/debates/{sessionId}
Headers:
- Authorization: Bearer {accessToken}

응답 (Response)

{
  "success": true,
  "data": {
    "sessionId": "debate_202508311400_001",
    "predictionId": "pred_202508311400_user123",
    "participatingAgents": 4,
    "totalRounds": 2,
    "consensusReached": true,
    "finalConsensusScore": 0.83,
    "totalDebateTime": 18200,
    "rounds": [
      {
        "roundNumber": 1,
        "startTime": "2025-08-31T14:00:10Z",
        "endTime": "2025-08-31T14:00:18Z",
        "consensusScore": 0.65,
        "expertOpinions": [
          {
            "agentType": "SLEEP_PATTERN",
            "solScore": 32,
            "confidence": 0.88,
            "keyPoints": ["SOL 개선 트렌드 확인", "규칙적인 입면 시간 유지"],
            "responseTime": 7800
          },
          {
            "agentType": "CBTI",
            "solScore": 38,
            "confidence": 0.85,
            "keyPoints": ["입면 전 불안 수준 감소", "SOL 단축 기법 효과 나타남"],
            "responseTime": 8200
          }
        ]
      }
    ],
    "qualityMetrics": {
      "averageRoundTime": 9100,
      "opinionVariance": 0.25,
      "convergenceRate": 0.78,
      "participationBalance": 0.92
    }
  }
}

3.2 전문가 분석 상세 조회 API

HTTP 메서드: GET
경로: /v1/sol-cod/analyses/expert/{analysisId}
Headers:
- Authorization: Bearer {accessToken}

응답 (Response)

{
  "success": true,
  "data": {
    "analysisId": "analysis_202508311400_sleep_pattern",
    "predictionId": "pred_202508311400_user123",
    "agentType": "SLEEP_PATTERN",
    "solScore": 32,
    "confidenceScore": 0.88,
    "processingTime": 7800,
    "analysisResult": {
      "solTrend": "IMPROVING",
      "solConsistency": "STABLE",
      "sleepOnsetPatterns": "GOOD",
      "keyPatterns": ["주중 SOL 30분 이내 안정적 유지", "입면 시간 편차 10뵔 이내", "SOL 지속적 개선 추세"],
      "riskFactors": ["주말 입면 지연 패턴", "입면 전 과도한 각성"]
    },
    "evidenceData": [
      {
        "type": "SOL_TREND",
        "dataPoints": [
          { "date": "2025-08-24", "value": 42 },
          { "date": "2025-08-25", "value": 38 },
          { "date": "2025-08-26", "value": 35 }
        ],
        "relevanceScore": 0.95
      }
    ],
    "llmInfo": {
      "model": "gpt-4",
      "version": "2024-05-13",
      "promptVersion": "v1.2.3",
      "tokenUsage": {
        "input": 3420,
        "output": 1250,
        "total": 4670
      }
    }
  }
}

3.3 권장사항 조회 API

HTTP 메서드: GET
경로: /v1/sol-cod/recommendations/{predictionId}
Headers:
- Authorization: Bearer {accessToken}

응답 (Response)

{
  "success": true,
  "data": {
    "predictionId": "pred_202508311400_user123",
    "treatmentPhase": "MID",
    "totalRecommendations": 6,
    "primaryCategory": "CBTI",
    "recommendations": [
      {
        "id": "rec_001",
        "category": "CBTI",
        "priority": 1,
        "title": "점진적 근육 이완법",
        "description": "SOL 단축을 위해 입면 전 점진적 근육 이완법을 실시해보세요.",
        "expectedImpact": 0.85,
        "difficulty": "MODERATE",
        "estimatedTimeToEffect": 14,
        "actionSteps": ["침대에 누워 발가락부터 순차적으로 긴장 완화", "심호흡과 함께 10-15분간 실시", "SOL 30분 이내 달성 시까지 지속"],
        "rationale": "SOL이 지속적으로 개선되고 있어 근육 이완법이 추가적인 SOL 단축에 효과적일 것으로 예상됩니다."
      },
      {
        "id": "rec_002",
        "category": "SLEEP_HYGIENE",
        "priority": 2,
        "title": "주말 입면 패턴 일관성 유지",
        "description": "주말에도 평일과 동일한 입면 루틴을 유지하여 SOL 일관성을 향상시켜보세요.",
        "expectedImpact": 0.72,
        "difficulty": "DIFFICULT",
        "estimatedTimeToEffect": 21,
        "actionSteps": ["금요일 밤 늦게 자는 습관 개선", "토요일 아침 알람 설정", "주말 활동 계획을 수면 스케줄에 맞춰 조정"],
        "rationale": "주말 입면 지연이 전체적인 SOL 패턴의 일관성을 해치고 있습니다."
      }
    ],
    "summary": {
      "focusAreas": ["SOL 일관성", "SOL 최적화"],
      "expectedOverallImprovement": 0.78,
      "implementationPlan": "첫 2주간은 근육 이완법에 집중하고, 3주차부터 주말 패턴 개선을 병행하세요."
    }
  }
}

성능 모니터링 API

4.1 시스템 성능 개요 API (관리자 전용)

HTTP 메서드: GET
경로: /v1/sol-cod/performance/overview
Query Parameters:
- period: string (1d, 7d, 30d, 기본값: 7d)
Headers:
- Authorization: Bearer {accessToken}

응답 (Response)

{
  "success": true,
  "data": {
    "period": "7d",
    "overall": {
      "totalPredictions": 1240,
      "successRate": 0.97,
      "averageProcessingTime": 22800,
      "averageAccuracy": 0.83,
      "errorRate": 0.03
    },
    "trends": {
      "predictionVolume": [
        { "date": "2025-08-25", "count": 180 },
        { "date": "2025-08-26", "count": 195 },
        { "date": "2025-08-27", "count": 201 }
      ],
      "processingTime": [
        { "date": "2025-08-25", "avgTime": 23200 },
        { "date": "2025-08-26", "avgTime": 22100 },
        { "date": "2025-08-27", "avgTime": 21800 }
      ]
    },
    "alerts": [
      {
        "level": "WARNING",
        "message": "평균 처리 시간이 지난 3일간 증가 추세",
        "timestamp": "2025-08-31T12:00:00Z"
      }
    ]
  }
}

4.2 에이전트별 성능 API (관리자 전용)

HTTP 메서드: GET
경로: /v1/sol-cod/performance/agents
Query Parameters:
- period: string (1d, 7d, 30d, 기본값: 7d)
- agentType: string (선택사항, 특정 에이전트만 조회)
Headers:
- Authorization: Bearer {accessToken}

응답 (Response)

{
  "success": true,
  "data": {
    "period": "7d",
    "agents": [
      {
        "agentType": "SLEEP_PATTERN",
        "metrics": {
          "totalAnalyses": 1240,
          "successRate": 0.99,
          "averageResponseTime": 7800,
          "averageConfidence": 0.87,
          "consistencyScore": 0.91
        },
        "performance": {
          "accuracy": 0.85,
          "reliability": 0.96,
          "debateParticipation": 0.94
        }
      },
      {
        "agentType": "QUESTIONNAIRE",
        "metrics": {
          "totalAnalyses": 892,
          "successRate": 0.96,
          "averageResponseTime": 8200,
          "averageConfidence": 0.82,
          "consistencyScore": 0.88
        },
        "performance": {
          "accuracy": 0.79,
          "reliability": 0.92,
          "debateParticipation": 0.89
        }
      }
    ],
    "comparison": {
      "bestPerforming": "SLEEP_PATTERN",
      "improvementNeeded": "MOBILE_ANALYTICS",
      "overallRanking": ["SLEEP_PATTERN", "CBTI", "QUESTIONNAIRE", "MOBILE_ANALYTICS"]
    }
  }
}

데이터 관리 및 개인정보 보호 API

5.1 사용자 예측 데이터 조회 API (관리자/의료진 전용)

HTTP 메서드: GET
경로: /v1/sol-cod/admin/users/{userId}/predictions
Query Parameters:
- limit: number (기본값: 50, 최대: 200)
- startDate: string (ISO 8601 형식)
- endDate: string (ISO 8601 형식)
- includeDetails: boolean (상세 분석 포함 여부, 기본값: false)
Headers:
- Authorization: Bearer {accessToken}

5.2 사용자 데이터 아카이빙 API (관리자 전용)

HTTP 메서드: POST
경로: /v1/sol-cod/admin/users/{userId}/archive
Headers:
- Content-Type: application/json
- Authorization: Bearer {accessToken}

요청 (Request)

{
  "reason": "USER_INACTIVE_6_MONTHS",
  "archiveDate": "2025-08-31",
  "retentionPolicy": "STANDARD_5_YEARS"
}

5.3 사용자 데이터 영구 삭제 API (관리자 전용)

HTTP 메서드: DELETE
경로: /v1/sol-cod/admin/users/{userId}/data
Headers:
- Content-Type: application/json
- Authorization: Bearer {accessToken}

요청 (Request)

{
  "reason": "USER_REQUEST_GDPR",
  "confirmationCode": "DELETE_CONFIRM_ABC123",
  "cascadeDelete": true
}

5.4 내 데이터 추출 요청 API

HTTP 메서드: GET
경로: /v1/sol-cod/users/me/data-export
Query Parameters:
- format: string (JSON, CSV, 기본값: JSON)
- includeRawData: boolean (원시 데이터 포함 여부, 기본값: false)
Headers:
- Authorization: Bearer {accessToken}

응답 (Response)

{
  "success": true,
  "data": {
    "exportId": "export_202508311500_user123",
    "status": "IN_PROGRESS",
    "estimatedCompletionTime": "2025-08-31T15:05:00Z",
    "format": "JSON",
    "downloadUrl": null,
    "expiresAt": null
  }
}

오류 코드

일반 오류 코드

COD_001: 요청 데이터 유효성 검증 실패
COD_002: 사용자 인증 실패
COD_003: 권한 부족
COD_004: 예측 리소스를 찾을 수 없음
COD_005: 시스템 내부 오류

예측 관련 오류 코드

COD_P001: 최소 데이터 요구사항 미충족
COD_P002: 예측 프로세스 타임아웃 (25초 초과)
COD_P003: Chain of Debate 토론 실패
COD_P004: 외부 LLM 서비스 연결 실패
COD_P005: 예측 스케줄링 충돌

스케줄링 관련 오류 코드

COD_S001: 취침목표시간 조회 실패
COD_S002: 스케줄 업데이트 권한 없음
COD_S003: 중복 스케줄 생성 시도
COD_S004: 사용자 치료 일시정지 상태

데이터 관리 관련 오류 코드

COD_D001: 데이터 아카이빙 실패
COD_D002: 데이터 복원 실패
COD_D003: 데이터 추출 권한 없음
COD_D004: GDPR 준수 요구사항 미충족

API 응답 형식

성공 응답 형식

{
  "success": true,
  "data": {
    // 실제 응답 데이터
  },
  "meta": {
    "requestId": "req_12345",
    "timestamp": "2025-08-31T14:00:00Z",
    "version": "1.0"
  }
}

오류 응답 형식

{
  "success": false,
  "error": {
    "code": "COD_P001",
    "message": "최소 데이터 요구사항을 충족하지 않습니다",
    "details": {
      "required": "최소 3일간의 수면 기록",
      "current": "1일간의 수면 기록",
      "suggestion": "더 많은 수면 데이터 수집 후 재시도하세요"
    }
  },
  "meta": {
    "requestId": "req_12345",
    "timestamp": "2025-08-31T14:00:00Z",
    "version": "1.0"
  }
}

변경 이력

버전	날짜	작성자	변경 내용
0.1.0	2025-08-31	bok@weltcorp.com	최초 작성 (예측 관리, 스케줄링, 분석 결과 조회, 성능 모니터링 API 포함)

목차​

관련 문서​

접근 권한 매트릭스​

예측 관리 API​

1.1 SOL(Sleep Onset Latency) 예측 요청 API​

요청 (Request)​

응답 (Response)​

1.2 예측 결과 조회 API​

응답 (Response)​

1.3 예측 히스토리 조회 API​

응답 (Response)​

스케줄링 관리 API​

2.1 현재 스케줄 조회 API​

응답 (Response)​

2.2 스케줄 업데이트 API (관리자 전용)​

요청 (Request)​

2.3 스케줄 취소 API (관리자 전용)​

분석 결과 조회 API​

3.1 토론 세션 상세 조회 API​

응답 (Response)​

3.2 전문가 분석 상세 조회 API​

응답 (Response)​

3.3 권장사항 조회 API​

응답 (Response)​

성능 모니터링 API​

4.1 시스템 성능 개요 API (관리자 전용)​

응답 (Response)​

4.2 에이전트별 성능 API (관리자 전용)​

응답 (Response)​

데이터 관리 및 개인정보 보호 API​

5.1 사용자 예측 데이터 조회 API (관리자/의료진 전용)​

5.2 사용자 데이터 아카이빙 API (관리자 전용)​

요청 (Request)​

5.3 사용자 데이터 영구 삭제 API (관리자 전용)​

요청 (Request)​

5.4 내 데이터 추출 요청 API​

응답 (Response)​

오류 코드​

일반 오류 코드​

예측 관련 오류 코드​

스케줄링 관련 오류 코드​

데이터 관리 관련 오류 코드​

API 응답 형식​

성공 응답 형식​

오류 응답 형식​

변경 이력​

목차

관련 문서

접근 권한 매트릭스

예측 관리 API

1.1 SOL(Sleep Onset Latency) 예측 요청 API

요청 (Request)

응답 (Response)

1.2 예측 결과 조회 API

응답 (Response)

1.3 예측 히스토리 조회 API

응답 (Response)

스케줄링 관리 API

2.1 현재 스케줄 조회 API

응답 (Response)

2.2 스케줄 업데이트 API (관리자 전용)

요청 (Request)

2.3 스케줄 취소 API (관리자 전용)

분석 결과 조회 API

3.1 토론 세션 상세 조회 API

응답 (Response)

3.2 전문가 분석 상세 조회 API

응답 (Response)

3.3 권장사항 조회 API

응답 (Response)

성능 모니터링 API

4.1 시스템 성능 개요 API (관리자 전용)

응답 (Response)

4.2 에이전트별 성능 API (관리자 전용)

응답 (Response)

데이터 관리 및 개인정보 보호 API

5.1 사용자 예측 데이터 조회 API (관리자/의료진 전용)

5.2 사용자 데이터 아카이빙 API (관리자 전용)

요청 (Request)

5.3 사용자 데이터 영구 삭제 API (관리자 전용)

요청 (Request)

5.4 내 데이터 추출 요청 API

응답 (Response)

오류 코드

일반 오류 코드

예측 관련 오류 코드

스케줄링 관련 오류 코드

데이터 관리 관련 오류 코드

API 응답 형식

성공 응답 형식

오류 응답 형식

변경 이력