ATP - ثبت پاسخ‌های context (POST /api/v1/invention-cases/{invention_case_id}/context-answers/)

Endpoint

POST /api/v1/invention-cases/{invention_case_id}/context-answers/

هدف آزمون

ثبت پاسخ‌های structured، بستن دور سوالات، و در صورت نیاز rerun استخراج با command_generation جدید.

شرایط آزمون

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

فرآیند آزمون

1. GET context-questions و استخراج question_idها
2. ساخت payload answers مطابق question_type
3. POST context-answers
4. بررسی saved_count برابر تعداد پاسخ
5. poll workflow-state برای ready یا run بعدی

معرفی ویژگی

ثبت پاسخ‌ها، بستن round، و در صورت نیاز rerun استخراج با command_generation جدید.

• پس از answers کافی: run به pending برمی‌گردد، generation افزایش می‌یابد، outbox جدید publish می‌شود
• پس از broker confirm: status → queued تا outcome بعدی
• readiness در این فاصله extracting می‌ماند
• outcome با generation/causation قدیمی = no-op

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

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

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

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

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

سناریو 3: پاسخ کامل همه blocking

1. دریافت N سوال blocking
2. ارسال N پاسخ
3. بررسی saved_count=N
4. poll تا readiness=ready

سناریو 4: خطا — پاسخ خالی

1. ارسال answers=[]
2. دریافت 400
3. بررسی "At least one answer is required"

قالب API

Swagger

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

نمونه ورودی

curl -X POST "http://localhost:8000/api/v1/invention-cases/{invention_case_id}/context-answers/" \
  -H "Authorization: Bearer <access>" \
  -H "Content-Type: application/json" \
  -d '{"answers":[{"question_id":"...","free_text":"Reduces thermal runaway in EV packs."}]}'

نمونه خروجی

{
  "success": true,
  "data": {
    "saved_count": 1,
    "readiness": { "state": "extracting", "blocking_question_count": 0 },
    "workflow_state": { "revision": 11 }
  }
}

Status Codes

• 201: منبع ایجاد شد
• 400: داده ورودی نامعتبر
• 401: احراز هویت نامعتبر

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

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

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

1. بررسی 200 و saved_count
2. بررسی بسته شدن round (GET questions → round null)
3. بررسی run.status=pending و افزایش command_generation پس از answers که rerun می‌سازند
4. بررسی readiness=extracting تا outcome با generation جدید

توضیحات

• پاسخ‌ها در ContextAnswer ذخیره می‌شوند
• ممکن است run استخراج مجدد با generation جدید trigger شود
• ADR-0005 / CONTEXT_WORKFLOW.md مرجع lifecycle و generation pin