ATP - شروع استخراج context (POST /api/v1/invention-cases/{invention_case_id}/start-context-extraction/)

Endpoint

POST /api/v1/invention-cases/{invention_case_id}/start-context-extraction/

هدف آزمون

ایجاد ContextExtractionRun و انتشار context.extraction.requested.

شرایط آزمون

سرویس core-api در حال اجرا باشد
هدر Authorization با access token معتبر
intake readiness برابر ready_to_continue باشد
حداقل یک source document با extraction completed وجود داشته باشد
RabbitMQ و context worker (ai-workflow / context-extraction-mock) فعال باشند

فرآیند آزمون

تأیید intake ready از workflow-state
ارسال POST بدون body
دریافت 202 با run.id و readiness.state=extracting
poll workflow-state تا context sub_state تغییر کند
در صورت questions_required: GET context-questions

معرفی ویژگی

تریگر صریح کاربر پس از intake. core-api کلیدهای artifact استخراج‌شده S3 را جمع‌آوری و رویداد context.extraction.requested را publish می‌کند. worker خارجی snapshot opaque و سوالات را پیشنهاد می‌دهد.

پیش‌شرط سخت: intake.state=ready_to_continue
input artifacts: normalized text keys از DocumentProcessingSummary
run status: pending → queued (broker confirm) → questions_required | ready | failed
command_generation: monotonic؛ هر start/rerun یک generation جدید + command_event_id
idempotent: run فعال (pending/queued) موجود دوباره برگردانده می‌شود
snapshot: InventionContextSnapshot در DB؛ payload کامل در S3
schema_version: 2 (workspace_id + command_generation)

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

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

ارسال POST /api/v1/invention-cases/{invention_case_id}/start-context-extraction/
دریافت پاسخ موفق
بررسی ساختار پاسخ

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

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

سناریو 3: idempotent — run فعال

POST اول → run A با status pending (یا queued پس از confirm)
POST دوم بلافاصله
دریافت 202 با همان run A
بررسی عدم ایجاد run B و عدم افزایش بی‌مورد generation

سناریو 4: خطا — intake در preparing

extraction هنوز complete نشده
POST start-context-extraction
دریافت 400
بررسی details.intake_readiness در خطا

قالب API

مولفه	نوع	نوع داده	اجباری	توضیحات
invention_case_id	Path	uuid	بله	شناسه پرونده اختراع

Swagger

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

نمونه ورودی

curl -X POST "http://localhost:8000/api/v1/invention-cases/{invention_case_id}/start-context-extraction/" \
  -H "Authorization: Bearer <access>" \
  -H "Content-Type: application/json"

نمونه خروجی

{
  "success": true,
  "data": {
    "run": {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "status": "pending",
      "command_generation": 1,
      "trigger_source": "user_action"
    },
    "readiness": {
      "state": "extracting",
      "blocking_question_count": 0,
      "can_continue_to_prior_art": false
    },
    "workflow_state": { "revision": 8 }
  }
}

Status Codes

202: run ایجاد یا بازگردانده شد
400: intake آماده نیست یا داده کافی نیست
401: احراز هویت نامعتبر
403: عدم مجوز update

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

202 با run pending و readiness extracting؛ پس از publisher confirm → queued؛ revision workflow افزایش یابد.

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

بررسی 202
بررسی run.status=pending و command_generation=1
بررسی outbox event با routing context.extraction.requested و schema_version=2
پس از confirm: status=queued
پس از inbox (matching generation + causation): snapshot یا questions_required
outcome با generation قدیمی = no-op (ack)

توضیحات

ADR-0005 مرجع معماری context extraction
inbox queue: core.context.extraction.events
سوالات blocking ممکن است prior-art را تا پاسخ متوقف کند
exhaustion انتشار: error_code=command_publish_exhausted

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

1. POST start-context-extraction
2. core-api: ContextExtractionRun(pending, generation=1) + command_event_id + S3 artifact keys
3. outbox publisher (confirm) → RabbitMQ: context.extraction.requested (v2)
4. domain → queued
5. ai-workflow worker: LLM extraction → snapshot JSON در S3
6. RabbitMQ (یکی از):
   - context.extraction.completed → snapshot ready
   - context.extraction.questions_required → سوالات در DB
   - context.extraction.failed
7. core-api inbox: InventionContextSnapshot + ContextQuestionRound (generation pin)
8. poll workflow-state / GET context-questions / SSE