ATP - ایجاد سند مبدأ (POST /api/v1/invention-cases/{invention_case_id}/source-documents/)

Endpoint

POST /api/v1/invention-cases/{invention_case_id}/source-documents/

هدف آزمون

آپلود ۱ تا N سند مبدأ، ذخیره در S3 و enqueue استخراج async.

شرایط آزمون

• سرویس core-api در حال اجرا باشد
• هدر Authorization با access token معتبر
• کاربر مجوز update روی پرونده داشته باشد
• S3/MinIO و RabbitMQ در دسترس باشند
• extraction-mock یا info-extraction worker در حال اجرا باشد (محیط local)

فرآیند آزمون

1. آماده‌سازی فایل(ها) و document_type متناظر
2. ارسال multipart/form-data با files و document_types
3. دریافت 201 با extraction_request_id برای هر فایل
4. poll GET document-extraction-requests/{id} یا workflow-state
5. بررسی transition به completed و ready_to_continue

معرفی ویژگی

مرحله اول intake: فایل خام در S3 ذخیره می‌شود، DocumentExtractionRequest با وضعیت pending ایجاد می‌شود و رویداد document.extraction.requested (schema_version: 2 + workspace_id) از transactional outbox به RabbitMQ publish می‌شود. پس از تأیید broker، وضعیت به queued می‌رود. worker خارجی (info-extraction / extraction-mock) متن استخراج‌شده را برمی‌گرداند و Core متن نرمال‌شده را در S3 می‌نویسد.

• multipart: فیلد files (چندفایلی) + document_types (JSON array یا تکرار فیلد)
• document_type: invention_description | prior_art_reference | ... (از enum مدل)
• محدودیت batch: تعداد فایل ≤ SOURCE_DOCUMENT_BATCH_UPLOAD_MAX_FILES
• RabbitMQ exchange: patent_genie.events
• routing key: document.extraction.requested
• inbox queue: core.document.extraction.events
• lifecycle: pending → queued (confirm) → completed | needs_review | failed
• running: unused — not in status enum

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

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

1. ارسال POST /api/v1/invention-cases/{invention_case_id}/source-documents/
2. دریافت پاسخ موفق
3. بررسی ساختار پاسخ

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

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

سناریو 3: آپلود batch دو فایل

1. آماده‌سازی disclosure.txt و prior_art.pdf
2. ارسال ۲ files با ۲ document_types
3. دریافت 201 با ۲ extraction_request_id
4. poll هر دو تا terminal state

سناریو 4: خطا — document_types ناهمخوان

1. ارسال ۲ files ولی ۱ document_type
2. دریافت 400
3. بررسی پیام "number of document types must match"

قالب API

Swagger

post:
  summary: ایجاد سند مبدأ
  responses:
    201:
      description: منبع ایجاد شد
    400:
      description: داده ورودی نامعتبر
    401:
      description: احراز هویت نامعتبر

نمونه ورودی

curl -X POST "http://localhost:8000/api/v1/invention-cases/{invention_case_id}/source-documents/" \
  -H "Authorization: Bearer <access>" \
  -F "files=@disclosure.txt;type=text/plain" \
  -F 'document_types=["invention_description"]'

نمونه خروجی

{
  "success": true,
  "data": {
    "uploads": [
      {
        "source_document": {
          "id": "a1b2c3d4-...",
          "original_filename": "disclosure.txt",
          "document_type": "invention_description",
          "upload_status": "stored",
          "extraction_status": "pending"
        },
        "extraction_request_id": "e5f6g7h8-..."
      }
    ],
    "workflow_state": { "revision": 3, "information_collection": { "sub_state": "extracting" } }
  }
}

Status Codes

• 201: آپلود و enqueue موفق
• 400: validation (فایل خالی، type نامعتبر، تعداد ناهمخوان)
• 401: احراز هویت نامعتبر
• 403: عدم دسترسی update به پرونده

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

201 با آرایه uploads؛ هر آیتم شامل source_document و extraction_request_id. workflow_state.revision افزایش یافته و intake در preparing/extracting است.

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

1. بررسی 201
2. بررسی upload_status=stored
3. بررسی extraction_status=pending بلافاصله پس از آپلود
4. پس از outbox publisher confirm: extraction_status=queued
5. بررسی publish رویداد در outbox (در تست integration) با schema_version=2 و workspace_id
6. poll تا extraction_status=completed

توضیحات

• worker پاسخ با document.extraction.completed یا failed می‌دهد
• ADR-0004 مرجع معماری event-driven document extraction
• در local از extraction-mock استفاده کنید
• exhaustion انتشار با error_code=command_publish_exhausted و امکان re-upload

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

1. POST source-documents (multipart)
2. core-api: S3 put + SourceDocument + DocumentExtractionRequest (pending) + command_event_id
3. outbox publisher (confirm) → RabbitMQ: document.extraction.requested
   payload: request_id, source_document_id, storage_key, invention_case_id, workspace_id
4. domain → queued
5. info-extraction worker: استخراج متن
6. RabbitMQ: document.extraction.completed | failed
7. core-api inbox (core.document.extraction.events):
   - به‌روز DocumentExtractionRequest.status (monotonic)
   - DocumentProcessingSummary + intake readiness
8. Frontend poll: workflow-state یا GET document-extraction-requests/{id}