ATP - جستجوی پیشینه فنی (POST /api/v1/prior-art/search)

Endpoint

POST /api/v1/prior-art/search

هدف آزمون

جستجوی پیشینه فنی بر اساس InventionContext و بازگرداندن references.

شرایط آزمون

• سرویس ai-workflow در حال اجرا باشد
• کلید LLM و کلید جستجو (AVALAI_API_KEY یا TAVILY_API_KEY) تنظیم شده باشد
• JSON خروجی استخراج (InventionContext) آماده باشد

فرآیند آزمون

1. آماده‌سازی JSON زمینه اختراع
2. ارسال POST با body JSON
3. دریافت PriorArtSearchResponse
4. بررسی references و search_strategy

معرفی ویژگی

مرحله ۱ گردش‌کار prior-art: جستجو در پایگاه‌های ثبت اختراع (Google Patents، WIPO، Espacenet و ...) و بازگرداندن مراجع.

• ورودی: InventionContext JSON یا {context: ...}
• خروجی: references[]، feature_comparisons، preliminary_report
• verbose: query parameter برای trace تفصیلی در لاگ
• مرحله بعد: خروجی به POST /api/v1/prior-art/report داده می‌شود
• Worker async: prior_art.search.requested → result.json + manifest.json در S3؛ completed فقط pointer/checksum برمی‌گرداند (بدون references inline)
• دفاع artifact key: context_artifact_key، search_result_artifact_key و manifest sibling باید زیر workspaces/{workspace_id}/ باشند

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

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

1. ارسال JSON خروجی extract به /api/v1/prior-art/search
2. دریافت کد 200
3. بررسی وجود references و schema_version

سناریو 2: خطا — body نامعتبر

1. ارسال body غیر JSON یا بدون ساختار context
2. ارسال POST
3. دریافت کد 400 یا 422

سناریو 3: Worker — کلید artifact نامعتبر

1. انتشار PriorArtSearchRequested با context_artifact_key خارج از prefix workspace
2. عدم فراخوانی search runner
3. دریافت prior_art.search.failed با error_code=INVALID_ARTIFACT_KEY
4. retryable=false

سناریو 4: Worker — redelivery از manifest

1. وجود manifest.json تکمیل‌شده با همان search_execution_id
2. عدم اجرای مجدد runner
3. republish prior_art.search.completed از manifest

سناریو 5: جستجوی موفق با wrapper context

1. قرار دادن InventionContext در فیلد context یک object
2. ارسال body به endpoint
3. دریافت کد 200
4. بررسی references و execution

سناریو 6: جستجوی موفق با verbose

1. ارسال context معتبر با query برابر verbose=true
2. دریافت کد 200
3. بررسی ثبت trace مرحله‌به‌مرحله در لاگ سرویس

سناریو 7: خطا — کلید LLM تنظیم نشده

1. حذف کلید فعال LLM
2. ارسال context معتبر
3. دریافت کد 503
4. بررسی پیام پیکربندی کلید API

سناریو 8: خطا — سرویس جستجو پیکربندی نشده

1. انتخاب OpenAI بدون تنظیم TAVILY_API_KEY
2. ارسال context معتبر
3. دریافت کد 503
4. بررسی اشاره پیام به TAVILY_API_KEY

سناریو 9: خطا — پاسخ ناموفق provider جستجو

1. شبیه‌سازی timeout یا خطای PriorArtSearchError در provider
2. ارسال context معتبر
3. دریافت کد 503
4. بررسی عدم بازگشت references ناقص به‌عنوان پاسخ موفق

سناریو 10: خطا — نوع body نامعتبر

1. ارسال array یا string به‌جای JSON object
2. دریافت کد 422
3. بررسی خطای validation بدنه درخواست

قالب API

Swagger

post:
  summary: Stage 1: prior-art search from InventionContext JSON
  responses:
    200:
      description: Search completed
    400:
      description: Invalid request body
    503:
      description: API keys not configured or search failed
    500:
      description: Internal error

نمونه ورودی

curl -X POST "http://127.0.0.1:8000/api/v1/prior-art/search" \
  -H "Content-Type: application/json" \
  -d @invention_context.json

نمونه خروجی

{
  "schema_version": "1.0",
  "references": [],
  "search_strategy": {},
  "preliminary_report": {},
  "warnings": []
}

Status Codes

• 200: جستجو با موفقیت انجام شد
• 400: بدنه درخواست نامعتبر
• 503: کلید API تنظیم نشده یا خطای جستجو
• 500: خطای داخلی

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

پاسخ JSON با references و متادیتای جستجو با کد 200.

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

1. بررسی کد 200 برای context معتبر
2. بررسی وجود فیلد references
3. بررسی 503 بدون کلید API

توضیحات

• با LLM_PROVIDER=avalai از Avalai Search استفاده می‌شود
• خروجی کامل را برای مرحله report ذخیره کنید
• Worker قبل از I/O، context/search_result/manifest keys را با workspace_id تطبیق می‌دهد
• کلید نامعتبر → prior_art.search.failed با error_code=INVALID_ARTIFACT_KEY (non-retryable)
• manifest.json در همان پوشه result باعث idempotency و republish امن completed در redelivery می‌شود