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: تولید گزارش تخصصی فارسی بر اساس نتایج جستجو و مراجع انتخاب‌شده.

• ورودی: JSON کامل خروجی search
• خروجی JSON: فیلد markdown با محتوای گزارش
• دانلود: query download=true یا header Accept: text/markdown
• verbose: trace تفصیلی در لاگ
• Worker async: prior_art.report.requested → report.md + report.json + manifest در S3؛ completed فقط pointer/checksum برمی‌گرداند (بدون markdown inline)
• دفاع 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 غیرخالی

سناریو 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: دانلود گزارش با query parameter

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

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

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

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

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

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

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

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

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

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

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

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

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,
  "warnings": []
}

Status Codes

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

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

پاسخ JSON با markdown فارسی یا فایل .report.md قابل دانلود با کد 200.

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

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

توضیحات

• برای دانلود از ?download=true یا Accept: text/markdown استفاده کنید
• worker جداگانه prior-art-report-worker این مرحله را async اجرا می‌کند
• 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 می‌شود