ATP - وضعیت گردش‌کار پرونده (GET /api/v1/invention-cases/{invention_case_id}/workflow-state/)

Endpoint

GET /api/v1/invention-cases/{invention_case_id}/workflow-state/

هدف آزمون

دریافت projection یکپارچه stage، intake، context، prior-art و revision.

شرایط آزمون

• سرویس core-api در حال اجرا باشد
• هدر Authorization با access token معتبر
• پرونده متعلق به workspace قابل دسترس کاربر باشد
• PostgreSQL و S3 در دسترس باشند (برای projection کامل)

فرآیند آزمون

1. ایجاد پرونده و آپلود source document
2. poll با فاصله ۲–۵ ثانیه: GET workflow-state
3. مقایسه revision بین pollها برای تشخیص تغییر
4. بررسی sub_state هر section (information_collection، context_completion، prior_art_review)
5. توقف poll وقتی sub_state به حالت terminal یا actionable رسید

معرفی ویژگی

endpoint اصلی UI برای polling وضعیت پرونده. IntakeReadinessService و ContextReadinessService و PriorArtWorkflowProjection در یک پاسخ تجمیع می‌شوند.

• جایگزین readiness جدا: /intake-readiness/ و /context-readiness/ در urls فعلی expose نشده‌اند
• revision: عدد صحیح یکتا؛ با هر inbox event یا تغییر domain افزایش می‌یابد
• sub_state: awaiting_upload | extracting | complete | questions_required | failed
• advisory readiness: readiness به‌تنهایی current_stage را جابه‌جا نمی‌کند
• ui_hints: warnings و recommended_next_action برای رندر UI

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

سناریو 1: poll کامل از آپلود تا context ready

1. آپلود source document و دریافت extraction_request_id
2. poll تا information_collection.sub_state=complete
3. POST start-context-extraction
4. poll تا context_completion.sub_state=complete
5. بررسی can_continue_to_prior_art=true در readiness

سناریو 2: خطا — پرونده قفل یا آرشیو

1. قفل کردن پرونده (status=locked)
2. GET workflow-state
3. بررسی lock_summary.is_locked=true
4. بررسی عدم پیشنهاد actionهای مخرب در ui_hints

سناریو 3: intake در حال آماده‌سازی

1. آپلود source document
2. poll workflow-state
3. بررسی information_collection.sub_state="extracting"
4. بررسی intake.state="preparing"

سناریو 4: سوالات context باز

1. دریافت event questions_required از inbox
2. poll workflow-state
3. بررسی context_completion.sub_state="questions_required"
4. بررسی blocking_question_count > 0

قالب API

Swagger

get:
  summary: وضعیت گردش‌کار پرونده
  responses:
    200:
      description: عملیات موفق
    401:
      description: احراز هویت نامعتبر یا ناقص

نمونه ورودی

curl -X GET "http://localhost:8000/api/v1/invention-cases/{invention_case_id}/workflow-state/" \
  -H "Authorization: Bearer <access>" \
  -H "Content-Type: application/json"

نمونه خروجی

{
  "success": true,
  "data": {
    "case_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "current_stage": "information_collection",
    "revision": 14,
    "information_collection": {
      "sub_state": "extracting",
      "intake": {
        "state": "preparing",
        "message": "Preparing your next step..."
      }
    },
    "context_completion": {
      "sub_state": "not_started",
      "readiness": {
        "state": "not_started",
        "blocking_question_count": 0,
        "can_continue_to_prior_art": false
      }
    },
    "prior_art_review": {
      "sub_state": "not_started",
      "prior_art": { "sub_state": "not_started", "capabilities": {} }
    },
    "ui_hints": {
      "warnings": [],
      "recommended_next_action": "Wait for document extraction to finish."
    }
  }
}

Status Codes

• 200: projection برگردانده شد
• 401: احراز هویت نامعتبر
• 404: پرونده یافت نشد

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

پاسخ JSON با revision، sectionهای information_collection/context_completion/prior_art_review و ui_hints. با هر تغییر async (extraction، context، prior-art) revision باید افزایش یابد.

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

1. بررسی 200 و فیلد revision
2. بررسی هم‌خوانی intake.state با وضعیت extraction واقعی
3. بررسی افزایش revision پس از completed event
4. بررسی can_continue_to_prior_art فقط وقتی context ready است
5. بررسی عدم افشای payload خام snapshot در این endpoint

توضیحات

• UI ترجیحاً این endpoint را poll می‌کند
• برای timeline تفصیلی از workflow-events (SSE) استفاده کنید
• CONTEXT_WORKFLOW.md و PLATFORM_WORKFLOW.md مرجع معماری هستند

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

Frontend ──poll──▶ GET workflow-state
                      │
                      ├─ IntakeReadinessService (documents/extraction)
                      ├─ ContextReadinessService (internal_context)
                      └─ PriorArtWorkflowProjection (prior_art)

Async side-effects که revision را بالا می‌برند:
  document.extraction.completed|failed  → inbox → intake update
  context.extraction.completed|questions_required|failed → inbox
  prior_art.search|report completed|failed → DB update