ATP - تولید گزارش تخصصی پیشینه فنی (POST /api/v1/prior-art/report)

Endpoint

POST /api/v1/prior-art/report

هدف آزمون

تولید گزارش تخصصی فارسی (markdown) از خروجی جستجوی پیشینه.

شرایط آزمون

• سرویس ai-workflow در حال اجرا باشد
• کلید LLM تنظیم شده باشد
• JSON خروجی POST /api/v1/prior-art/search آماده باشد

فرآیند آزمون

1. آماده‌سازی JSON نتایج جستجو
2. ارسال POST با body JSON
3. دریافت PriorArtReportResponse یا فایل markdown
4. بررسی markdown و reference_count

معرفی ویژگی

مرحله ۲ گردش‌کار prior-art: انتخاب نمایندگان خانوادهٔ اختراع (top-k متمایز)، تحلیل agent، و تولید گزارش تخصصی فارسی بر اساس نتایج جستجو.

• ورودی: JSON کامل خروجی search
• انتخاب خانواده: تا PRIOR_ART_REPORT_TOP_K خانوادهٔ متمایز (نه صرفاً top-k انتشار خام)
• خروجی JSON: markdown، reference_count، reference_analyses_count، warnings
• دانلود: query download=true یا header Accept: text/markdown
• verbose: trace تفصیلی در لاگ (شامل selection diagnostics)
• Worker async: prior_art.report.requested → report.md + report.json + manifest در S3؛ completed فقط pointer/checksum برمی‌گرداند (بدون markdown inline)؛ report_config.top_k تا سقف تنظیمات clamp می‌شود
• دفاع artifact key: search_result، report_markdown، report_json و manifest sibling باید زیر workspaces/{workspace_id}/ باشند

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

سناریو 1: تولید گزارش JSON

1. ارسال JSON search به /api/v1/prior-art/report
2. دریافت کد 200
3. بررسی فیلد markdown غیرخالی
4. بررسی reference_count برابر تعداد خانواده‌های انتخاب‌شده (حداکثر top-k)

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

1. ارسال JSON ناقص یا بدون schema_version
2. ارسال POST
3. دریافت کد 400 یا 422

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

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

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

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

سناریو 5: Worker — clamp مقدار top_k رویداد

1. انتشار PriorArtReportRequested با report_config.top_k بزرگ‌تر از PRIOR_ART_REPORT_TOP_K
2. اجرای runner با effective_top_k برابر سقف تنظیمات
3. بررسی اینکه تعداد خانواده‌های انتخاب‌شده از سقف بیشتر نباشد

سناریو 6: انتخاب خانواده‌های متمایز (نه تکرار هم‌خانواده)

1. آماده‌سازی search result با چند انتشار هم‌خانواده در رتبهٔ بالا
2. ارسال POST به /api/v1/prior-art/report
3. دریافت کد 200
4. بررسی اینکه در گزارش/انتخاب، بیش از یک نماینده از همان خانواده نباشد

سناریو 7: دانلود گزارش با query parameter

1. ارسال search result معتبر با download=true
2. دریافت کد 200 و Content-Type برابر text/markdown
3. بررسی Content-Disposition و پسوند .report.md
4. بررسی غیرخالی بودن محتوای فایل

سناریو 8: دانلود گزارش با Accept header

1. ارسال search result معتبر با header برابر Accept: text/markdown
2. دریافت کد 200
3. بررسی دانلود markdown بدون نیاز به download=true

سناریو 9: تولید گزارش با verbose

1. ارسال search result معتبر با verbose=true
2. دریافت پاسخ JSON با کد 200
3. بررسی ثبت trace تفصیلی و diagnostics انتخاب در لاگ

سناریو 10: نام فایل پیش‌فرض بدون case_id

1. ارسال search result معتبر بدون case_id با download=true
2. دریافت فایل با نام prior-art.report.md
3. بررسی Content-Disposition پاسخ

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

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

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

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

سناریو 13: خطا — شکست تولید گزارش

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

قالب API

Swagger

post:
  summary: Stage 2: Persian expert report from prior-art search JSON
  responses:
    200:
      description: Report as JSON or markdown download
    400:
      description: Invalid request body
    503:
      description: API keys not configured or report failed
    500:
      description: Internal error

نمونه ورودی

curl -X POST "http://127.0.0.1:8000/api/v1/prior-art/report?download=true" \
  -H "Content-Type: application/json" \
  -d @search_result.json \
  -o report.md

نمونه خروجی

{
  "case_id": "case-001",
  "markdown": "# گزارش پیشینه فنی\n\n...",
  "reference_count": 3,
  "reference_analyses_count": 3,
  "warnings": []
}

Status Codes

• 200: گزارش با موفقیت تولید شد (JSON یا markdown)
• 400: بدنه درخواست نامعتبر
• 503: کلید API تنظیم نشده یا خطای گزارش
• 500: خطای داخلی

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

پاسخ JSON با markdown فارسی و شمارش مراجع/تحلیل‌های substantive، یا فایل .report.md قابل دانلود با کد 200.

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

1. بررسی کد 200 برای search result معتبر
2. بررسی markdown غیرخالی و فارسی
3. بررسی اینکه reference_count از PRIOR_ART_REPORT_TOP_K بیشتر نباشد
4. بررسی دانلود با download=true
5. بررسی 503 بدون کلید API

توضیحات

• برای دانلود از ?download=true یا Accept: text/markdown استفاده کنید
• مسیر async محصول: core-api پس از prior_art.search.completed رویداد prior_art.report.requested را جداگانه منتشر می‌کند؛ prior-art-report-worker پاسخ می‌دهد
• انتخاب گزارش بر پایهٔ خانواده‌های متمایز است؛ اعضای هم‌خانواده collapse می‌شوند
• Worker قبل از I/O، search_result/report/manifest keys را با workspace_id تطبیق می‌دهد
• کلید نامعتبر → prior_art.report.failed با error_code=INVALID_ARTIFACT_KEY (non-retryable)
• manifest.json در همان پوشه report باعث idempotency و republish امن completed در redelivery می‌شود
• تحلیل‌های non-substantive از رندر مشتری فیلتر می‌شوند؛ abstract خالی/بازاریابی scrub می‌شود