공시한입 Docs

Appearance

GET /api/v1/ai/analyze/ ​

의도 ​

공시 AI 분석 메타 조회. quota 차감 없이 분석 상태 + summary를 반환한다. 결과(result)는 조건에 따라 자동 동봉되거나 null로 반환된다 — FE는 result가 null이면 POST reveal 호출.

인증 ​

비로그인 허용 (lazy auth, 2026-05-07~). GET /api/v1/ai/analyze/{rceptNo} 만 public — sub-path (/feedback, /reveal) 는 로그인 필수. 비로그인 응답은 result 필드를 항상 omit (짧은 공시라도) — 한줄요약(summary)으로 충분, 본문(key_points)은 로그인 게이트.

입력 ​

  • Path: rceptNo — 14자리 공시 접수번호 (예: 20260413800802)

응답 ​

200 OK — COMPLETED + 일반 공시 + 미reveal ​

json
{
  "status": "COMPLETED",
  "doc_length": 8500,
  "is_short": false,
  "already_revealed": false,
  "summary": "삼성전자, 1분기 영업이익 전년 대비 50% 증가",
  "result": null
}

200 OK — COMPLETED + 짧은 공시 (is_short=true) 또는 이미 reveal (로그인) ​

json
{
  "status": "COMPLETED",
  "doc_length": 1200,
  "is_short": true,
  "already_revealed": false,
  "summary": "...",
  "result": {
    "summary": "...",
    "key_points": ["...", "..."],
    "sentiment": "positive",
    "model": "RedHatAI/Qwen3.6-35B-A3B-NVFP4"
  }
}

200 OK — 비로그인 (어떤 케이스든 result 는 항상 null) ​

json
{
  "status": "COMPLETED",
  "doc_length": 1200,
  "is_short": true,
  "already_revealed": false,
  "summary": "...",
  "result": null
}

짧은 공시여도 result 동봉 X — FE 가 result == null 보고 로그인 게이트 띄움.

202 — PENDING / BODY_PENDING / UNAVAILABLE ​

json
{ "status": "PENDING" }
{ "status": "BODY_PENDING" }
{ "status": "UNAVAILABLE" }
  • PENDING — 분석 대기 또는 진행 중 (일반 케이스). FE 는 "AI 가 분석 중입니다" 표시.
  • BODY_PENDING — DART OpenAPI 가 status=014 (본문 미존재) 응답을 보냈고 24h 이내. 정기보고서/정정/대량보유 등 인덱싱 지연 케이스. BodyRecoveryWorker (5분 주기) 가 회수 시도 중. FE 는 "DART 본문 등록 대기 중" 메시지 + 시계 아이콘으로 일반 PENDING 과 시각적 분기.
  • UNAVAILABLE — 본문 영구 부재 확정 (BODY_PENDING 24h 경과 또는 일반 LLM 실패 + retry_count ≥ 임계).

503 — DB 오류 ​

curl 예제 ​

bash
# 로컬
curl -s -H "Authorization: Bearer $TOKEN" \
  http://localhost:8000/api/v1/ai/analyze/20260413800802 | jq

# prod
curl -s -H "Authorization: Bearer $TOKEN" \
  https://api.dartbrief.com/api/v1/ai/analyze/20260413800802 | jq

비즈니스 메모 ​

  • SHORT_DOC_THRESHOLD 환경변수 미만이면 is_short=true → result 무료 노출
  • already_revealed: 이전에 POST reveal 호출한 공시 — 재진입 시 quota 차감 없이 result 동봉
  • status: "BODY_PENDING" 조건: analysis_cache.status='BODY_PENDING'. DART OpenAPI status=014 응답을 받았으나 24h 이내라 본문 인덱싱 지연 가능성. BodyRecoveryWorker 가 5분 주기로 회수 시도. PR #82 (2026-05-13) — 이전엔 status=014 즉시 UNAVAILABLE 마킹 → 정기보고서 오분류 문제.
  • status: "UNAVAILABLE" 조건: 분석이 FAILED 이면서 retry_count >= unavailableRetryThreshold (=90). BODY_PENDING 24h 경과 또는 viewer fallback 도 본문 미회수 시 MarkFailedPermanent 가 retry_count 를 99 로 한 번에 올려 영구 분류. 일반 LLM 실패 (retry_count < 90) 는 PENDING 으로 응답 — backend internal/ai/policy.go 의 UnavailableRetryThreshold / BodyPendingMaxAge 참조.
  • HTTP 캐시 없음 — 이 엔드포인트는 서버 캐시 미적용 (공시 원문 캐시는 GET /disclosures/{rceptNo}에 적용)