[AI Run][P1] Client용 AiRun 진행 상태 SSE 구독 추가

[hywznn]

한 줄 목표

Client가 AiRun 진행 상태를 실시간으로 볼 수 있도록 Server → Client 단방향 SSE 구독 API를 선택적으로 추가합니다.

이 기능은 실행의 기준이 아니라 화면 편의를 위한 보조 기능입니다. 실제 상태의 기준은 항상 Server DB의 AiRun이며 기존 조회 API를 유지합니다.

쉽게 설명하면

현재 기본 방식은 Client가 일정 간격으로 실행 상태를 조회하는 polling입니다.

Client → GET /api/v1/ai-runs/{aiRunId}

SSE를 추가하면 Server가 상태가 변할 때 화면에 알려줄 수 있습니다.

분석 대기 → 분석 중 → 정보 확인 중 → 검토 필요 → 완료

통신 경계

• SSE 방향은 Server → Client 한 방향입니다.
• Client 명령과 HR 답변은 기존 REST POST를 사용합니다.
• Server ↔ AI Runtime은 SSE로 변경하지 않고 #8의 REST·JSON 계약을 유지합니다.
• SSE 연결이 끊겨도 AiRun 실행은 계속됩니다.
• 재연결하거나 SSE를 지원하지 않는 Client는 기존 GET polling을 사용합니다.

제안 API

GET /api/v1/ai-runs/{aiRunId}/events
Accept: text/event-stream
Authorization: Bearer <access-token>

공개할 이벤트 예시:

RUN_QUEUED
RUN_STARTED
SLOT_CHECKING
NEEDS_INFO
REVIEW_REQUIRED
COMPLETED
FAILED

Agent의 자유문장 추론, Chain of Thought, Prompt, Provider 원문 응답은 이벤트로 노출하지 않습니다.

작업 범위

• 회사·사용자 권한을 검사하는 SSE 구독 API
• AiRun의 저장된 상태를 구조화된 공개 이벤트로 변환
• event id와 Last-Event-ID 기반 재연결 처리
• 일정 주기의 heartbeat와 유휴 연결 종료
• 완료·실패 후 스트림 정상 종료
• 한 사용자·AiRun당 연결 수 제한
• 서버 재시작·연결 종료 후 GET polling fallback
• 원문 개인정보·Agent 내부 추론·Secret 비노출 테스트
• OpenAPI와 Client 사용 예시 문서화

완료 조건

• 로그인한 사용자는 자기 사업장의 AiRun만 구독할 수 있습니다.
• 상태 변경을 중복 없이 순서대로 받을 수 있습니다.
• 연결이 끊겨도 AiRun 실행과 저장 상태에는 영향이 없습니다.
• SSE 없이도 기존 조회 API만으로 같은 최종 결과를 확인할 수 있습니다.
• 화면에 필요한 안전한 상태만 노출됩니다.

시작 조건

• [AI Run] 비동기 실행 상태·재시도·멱등성 구현 #24 AiRun 상태와 조회 API 구현
• Agent Slot 왕복 이슈의 상태·이벤트 구분 확정
• Client가 polling만으로 데모에 충분한지 먼저 확인

범위 밖

• Server ↔ Agent 양방향 스트리밍
• WebSocket
• Agent token streaming
• Chain of Thought 공개
• Task 자동 생성·승인·발송

관계

• Parent: [AI Run] 비동기 실행 상태·재시도·멱등성 구현 #24
• 선택적 후속 작업이며 MVP 핵심 흐름을 막지 않음