ATP - جزئیات درخواست استخراج (GET /api/v1/document-extraction-requests/{request_id}/)

Endpoint

GET /api/v1/document-extraction-requests/{request_id}/

هدف آزمون

polling وضعیت DocumentExtractionRequest پس از enqueue.

شرایط آزمون

• سرویس core-api در حال اجرا باشد
• هدر Authorization با access token معتبر

فرآیند آزمون

1. ثبت request_id از پاسخ آپلود source-documents
2. loop: GET هر ۳ ثانیه تا status terminal
3. در completed: بررسی extracted_text_available در source document list
4. در failed: نمایش error_message و امکان re-upload

معرفی ویژگی

endpoint اختصاصی polling یک job استخراج. وضعیت از pending → queued (پس از broker confirm) → completed | failed | needs_review می‌رود. پس از completed، normalized text در S3 و DocumentProcessingSummary در DB ثبت می‌شود.

• status enum: pending, queued, completed, failed, needs_review
• attempts: شمارنده retry worker
• error_code / error_message: در failed (از جمله command_publish_exhausted)
• tenancy: DocumentExtractionRequestSelector.get_for_user

سناریوی آزمون

سناریو 1: مسیر موفق

1. ارسال GET /api/v1/document-extraction-requests/{request_id}/
2. دریافت پاسخ موفق
3. بررسی ساختار پاسخ

سناریو 2: خطا - درخواست نامعتبر

1. ارسال درخواست با داده یا شناسه نامعتبر
2. دریافت کد خطای 4xx
3. بررسی پیام خطای استاندارد API

سناریو 3: polling تا completed

1. آپلود فایل و دریافت request_id
2. poll هر ۳ ثانیه
3. توقف وقتی status=completed
4. بررسی completed_at و attempts=1

سناریو 4: failed با error_code

1. شبیه‌سازی worker failure
2. poll تا status=failed
3. بررسی error_code و error_message غیرخالی
4. بررسی intake.state=extraction_failed در workflow-state

قالب API

Swagger

get:
  summary: جزئیات درخواست استخراج
  responses:
    200:
      description: عملیات موفق
    401:
      description: احراز هویت نامعتبر یا ناقص

نمونه ورودی

curl -X GET "http://localhost:8000/api/v1/document-extraction-requests/{request_id}/" \
  -H "Authorization: Bearer <access>" \
  -H "Content-Type: application/json"

نمونه خروجی

{
  "success": true,
  "data": {
    "id": "e5f6g7h8-1234-5678-90ab-cdef12345678",
    "source_document_id": "a1b2c3d4-...",
    "invention_case_id": "7c9e6679-...",
    "status": "completed",
    "attempts": 1,
    "error_code": "",
    "error_message": "",
    "started_at": "2026-07-12T09:00:00Z",
    "completed_at": "2026-07-12T09:00:45Z"
  }
}

Status Codes

• 200: عملیات موفق
• 401: احراز هویت نامعتبر یا ناقص

نتیجه مورد انتظار

در صورت موفقیت، پاسخ JSON استاندارد با کد وضعیت مناسب برای GET برگردانده می‌شود.

روال صحت‌سنجی

1. بررسی transitions مجاز: pending → queued → terminal (بدون overwrite ترمینال)
2. بررسی status=pending بلافاصله پس از آپلود؛ queued پس از confirm
3. بررسی completed_at پر شده در completed
4. بررسی 404 برای request متعلق به کاربر دیگر
5. late outcome روی completed/failed = no-op

توضیحات

• مسیر alias: /api/v1/document-extraction-jobs/{request_id}/
• workflow-state برای UI aggregate ترجیح دارد

جریان یکپارچه‌سازی

POST source-documents → request_id
     ↓
RabbitMQ document.extraction.requested → worker
     ↓
RabbitMQ document.extraction.completed|failed
     ↓
core-api inbox → UPDATE DocumentExtractionRequest
     ↓
GET document-extraction-requests/{request_id}