본문으로 건너뛰기

SOL CoD SSE 이벤트 스키마

본 문서는 SOL Chain of Debate 백테스팅 워크플로우에서 서버가 전송하는 Server-Sent Events(SSE) 메시지의 스키마를 정의합니다. 웹 UI와 백엔드 간 실시간 진행률/상태/결과 동기화를 위한 표준입니다.

공통 Envelope​

모든 SSE 이벤트는 동일한 Envelope 형태로 전송됩니다.

{
  "type": string,            // 이벤트 타입 (아래 목록 참조)
  "sessionId": string,       // 시뮬레이션 세션 ID
  "timestamp": string,       // ISO8601 타임스탬프
  "data": any                // 이벤트별 페이로드
}

이벤트 타입 목록​

  • progress: 진행률 갱신
    • data: { progress: number; message?: string; currentDay?: number; totalDays?: number }
  • simulation-started: 백그라운드 작업 시작
    • data: { userId: string; sessionName?: string }
  • simulation-completed: 시뮬레이션 완료
    • data: { executionTime?: number; status?: string; metadata?: Record<string, any> }
  • simulation-failed: 시뮬레이션 실패
    • data: { error: string; dayIndex?: number }
  • simulation-queued: 큐 등록 성공
    • data: { userId: string; sessionName?: string; startedAt?: string }

단계(Phase) 이벤트​

  • phase: 워크플로우 단계 전환 알림
    • data: { phase: string; [extra: string]: any }
    • phase 값 예시:
      • workflow-started | workflow-finished
      • analysis-start | analysis-complete
      • debate-start | debate-complete
      • validation-start | validation-complete
      • graph-data-prep-start | graph-data-prep-complete
      • graph-sol-start | graph-sol-complete
      • graph-save-start | graph-save-complete | graph-completed

토론 라운드 이벤트​

  • debate-round-start
    • data: { round: number }
  • debate-round-complete
    • data: { round: number; durationMs?: number }
  • debate-round-details
    • data: { round: number; durationMs?: number; opinions: Array<{ agentType: string; sol?: number; confidence?: number; reasoning?: string; evidence?: { supporting?: string[]; counters?: string[] } }> }

합의/검증 이벤트​

  • consensus-built
    • data: { sol: number; confidence: number; consensus: number }
  • validation-complete
    • data: { validations: number }

예시​

event: message
data: {"type":"progress","sessionId":"92d6...","timestamp":"2025-09-13T10:45:31.123Z","data":{"progress":42,"message":"Day 25 completed","currentDay":25,"totalDays":60}}

event: message
data: {"type":"phase","sessionId":"92d6...","timestamp":"2025-09-13T10:45:31.234Z","data":{"phase":"debate-start"}}

event: message
data: {"type":"debate-round-details","sessionId":"92d6...","timestamp":"2025-09-13T10:45:31.567Z","data":{"round":1,"durationMs":11731,"opinions":[{"agentType":"SLEEP_PATTERN","sol":40,"confidence":0.75,"reasoning":"...","evidence":{"supporting":["trend stable"],"counters":[]}}]}}

호환성​

  • UI는 알 수 없는 type 값의 이벤트를 무시해야 합니다.
  • data 스키마는 하위 호환을 위해 선택 필드를 허용합니다. 신규 필드 추가 시에도 기존 UI는 기본 동작을 유지합니다.

버전 관리​

이 스키마는 저장소 태그와 함께 버전 관리됩니다. 클라이언트는 필요 시 서버와의 호환성 점검을 위해 type 목록과 data 필드 존재 여부를 검사해야 합니다.