# 1. POST → 202 Accepted (request_id 반환)
POST /api/v1/ns/{ns}/gpu/ocr
  Content-Type: multipart/form-data  또는 application/json (image_b64)
  → 202 { "request_id": "ocr-1710000000000-a1b2c3d4" }

# 2. GET 폴링 → 완료 시 200
GET /api/v1/ns/{ns}/gpu/ocr/{request_id}
  → 202 { "status": "queued" }
  → 200 { "status": "completed", "text": "..." }

# 데이터 흐름
Client → POST /gpu/ocr (이미지 bytes) → Redis Queue → OCRWorker
  → PaddleOCR → text / blocks / tables → Redis Outbox → Client

{
  "ok": true,
  "data": {
    "request_id": "ocr-1710567890123-a1b2c3d4",
    "task_type":  "ocr",
    "hint":       "text_recommended"   // 4KB 미만 업로드 시에만 포함 — JSON 모드 권장 힌트
  }
}

hint 필드는 multipart 업로드가 4KB 미만일 때만 응답에 포함됩니다 (요청은 거부되지 않음). 작은 페이로드에는 base64 JSON 모드가 효율적입니다.

// output_format=text (기본)
{
  "ok": true,
  "data": {
    "request_id":    "ocr-1710567890123-a1b2c3d4",
    "status":        "completed",
    "text":          "Hello World\nThis is a test document.",
    "output_format": "text",
    "blocks":        null,       // text 모드 시 null
    "tables":        null,
    "page_count":    1,
    "language":      "en",
    "model":         "PaddleOCR/PP-OCRv4",
    "cached":        false,
    "elapsed_ms":    843.5
  }
}

// output_format=json_structured
{
  "data": {
    "text": "Hello World\nThis is a test...",
    "output_format": "json_structured",
    "blocks": [
      {
        "text": "Hello World",
        "confidence": 0.98,
        "bbox": { "x": 0.05, "y": 0.02, "width": 0.4, "height": 0.08 }
      }
    ],
    "tables": [
      {
        "rows": [["Name", "Age"], ["Alice", "30"]],
        "num_rows": 2, "num_cols": 2, "confidence": null
      }
    ]
  }
}

# Multipart 모드 (권장)
curl -X POST https://localhost:1443/api/v1/ns/HRM/gpu/ocr \
  -k \
  -H "X-API-Key: <your-key>" \
  -F "[email protected]" \
  -F "output_format=json_structured" \
  -F "language=en"

# JSON 모드 (소용량)
curl -X POST https://localhost:1443/api/v1/ns/HRM/gpu/ocr \
  -k \
  -H "X-API-Key: <your-key>" \
  -H "Content-Type: application/json" \
  -d '{"image_b64":"'"$(base64 -w0 document.png)"'","output_format":"text"}'

# 결과 조회 후 자동 삭제
curl "https://localhost:1443/api/v1/ns/HRM/gpu/ocr/ocr-xxx?auto_clear=true" \
  -k -H "X-API-Key: <your-key>"

Redis Pub/Sub으로 완료 알림을 수신 후 즉시 OCR 결과를 전송합니다.

// 인증: Sec-WebSocket-Protocol 헤더로 API 키 전달 (URL 쿼리 미지원)
// 브라우저: new WebSocket(url, ["redgx_ak_crm_..."])
wss://<host>/api/v1/ns/CRM/gpu/ocr/ocr-xxx/wait?timeout=90          // timeout 기본 10, 최대 300

// 완료 — REST GET과 동일 구조
{ "ok": true, "data": { "request_id": "ocr-...", "status": "completed",
    "text": "인식된 텍스트", "output_format": "text",
    "blocks": null, "tables": null, "page_count": 1, "language": "en",
    "model": "PaddleOCR/PP-OCRv4", "cached": false, "elapsed_ms": 420.0 } }

// 실패
{ "ok": true, "data": { "request_id": "ocr-...", "status": "failed", "error": {...} } }

// 인증 실패 → HTTP 403 (upgrade 거부, accept 전 — 4001 close 프레임 미전송)
// Not Found    → { "ok": false, "error": { "code": "GPU_NOT_FOUND" } } + close(4004)
// Timeout      → { "ok": false, "error": { "code": "GPU_TIMEOUT" } }  + close(4008)