ATP - تولید پیش‌نویس توصیف اختراع (POST /api/v1/draft/description)

Endpoint

POST /api/v1/draft/description

هدف آزمون

تولید توصیف فارسی ساخت‌یافته، ماتریس پشتیبانی ادعا، و خلاصه جداگانه از InventionContext، PatentClaimsDraft و prior_art اختیاری.

شرایط آزمون

• سرویس ai-workflow در حال اجرا باشد
• کلید LLM تنظیم شده باشد
• JSON زمینه اختراع و خروجی draft/claims (claims_draft) آماده باشد

فرآیند آزمون

1. آماده‌سازی body با context و claims_draft (و در صورت نیاز prior_art)
2. ارسال POST به /api/v1/draft/description
3. دریافت DescriptionDraftResponse یا فایل markdown
4. بررسی sections، markdown_fa، abstract_markdown_fa و support_matrix

معرفی ویژگی

endpoint تولید توصیف اختراع فارسی: بخش‌های استاندارد توصیف، ماتریس پشتیبانی ادعا، markdown توصیف و abstract جداگانه را برمی‌گرداند.

• ورودی: {context, claims_draft, prior_art?} — prior_art اختیاری است
• خروجی JSON: schema_version=description.v2، sections، support_matrix، markdown_fa، abstract_markdown_fa، validation، metrics
• دانلود توصیف: download=true یا download=description → .description.md
• دانلود خلاصه: download=abstract → .abstract.md
• Accept: text/markdown: بدون query، markdown توصیف (نه abstract) دانلود می‌شود
• Worker async: draft.description.requested → completed با description_draft inline؛ prior_art_search_result_artifact_key اختیاری است
• دفاع artifact key: context، claims_draft و prior_art (در صورت وجود) زیر workspace

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

سناریو 1: تولید موفق توصیف JSON

1. ارسال body با context و claims_draft معتبر
2. دریافت کد 200
3. بررسی schema_version برابر description.v2 و وجود markdown_fa و abstract_markdown_fa
4. بررسی اینکه abstract داخل markdown_fa تکرار نشده باشد

سناریو 2: خطا — نبود claims_draft

1. ارسال body فقط با context و بدون claims_draft
2. ارسال POST
3. دریافت کد 400 با پیام الزام claims_draft

سناریو 3: دانلود توصیف با download=true

1. ارسال body معتبر با download=true
2. دریافت کد 200 و Content-Type برابر text/markdown
3. بررسی Content-Disposition با پسوند .description.md
4. بررسی عدم وجود عنوان خلاصه اختراع در محتوای دانلودشده

سناریو 4: دانلود خلاصه با download=abstract

1. ارسال body معتبر با download=abstract
2. دریافت کد 200 و فایل .abstract.md
3. بررسی وجود # خلاصه اختراع در محتوا

سناریو 5: تولید همراه prior_art اختیاری

1. ارسال body با context، claims_draft و prior_art
2. دریافت کد 200
3. بررسی تکمیل بخش background_art در صورت وجود داده پیشینه

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

1. حذف کلید فعال LLM
2. ارسال body معتبر
3. دریافت کد 503

سناریو 7: خطا — ورودی نامعتبر pipeline

1. شبیه‌سازی DescriptionInputError در runner
2. ارسال body معتبر از نظر schema
3. دریافت کد 400

سناریو 8: خطا — timeout تولید توصیف

1. شبیه‌سازی DescriptionTimeoutError
2. ارسال body معتبر
3. دریافت کد 500

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

1. انتشار DescriptionDraftRequested با claims_draft_artifact_key خارج از workspace
2. عدم فراخوانی description runner
3. دریافت draft.description.failed با error_code=INVALID_ARTIFACT_KEY
4. retryable=false

قالب API

Swagger

post:
  summary: Generate Persian patent description from context, claims, and optional prior art
  responses:
    200:
      description: Persian patent description as JSON or downloadable markdown
    400:
      description: Invalid body or description input/validation error
    500:
      description: Description agent/timeout/generation failed
    503:
      description: LLM API key not configured

نمونه ورودی

curl -X POST "http://127.0.0.1:8000/api/v1/draft/description" \
  -H "Content-Type: application/json" \
  -d @description_request.json

نمونه خروجی

{
  "schema_version": "description.v2",
  "case_id": "case-001",
  "sections": [{ "section_type": "title", "text_fa": "..." }],
  "support_matrix": [],
  "markdown_fa": "# توصیف اختراع\n\n...",
  "abstract_markdown_fa": "# خلاصه اختراع\n\n...",
  "validation": { "is_valid": true },
  "warnings": [],
  "metrics": { "duration_ms": 2500 }
}

Status Codes

• 200: توصیف با موفقیت تولید شد (JSON یا markdown)
• 400: بدنه نامعتبر یا خطای ورودی/اعتبارسنجی توصیف
• 500: timeout، خطای agent یا شکست تولید
• 503: کلید LLM تنظیم نشده

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

پاسخ JSON با description.v2، markdown توصیف و abstract جدا، یا فایل .description.md / .abstract.md با کد 200.

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

1. بررسی کد 200 برای body معتبر
2. بررسی وجود sections و markdown_fa و abstract_markdown_fa
3. بررسی دانلود توصیف با download=true
4. بررسی دانلود خلاصه با download=abstract
5. بررسی 400 بدون claims_draft
6. بررسی 503 بدون کلید API

توضیحات

• نام فایل‌ها: {case_id}.description.md و {case_id}.abstract.md
• مسیر async محصول: صف draft.description.requested و progress/completed/failed
• Worker خروجی را inline در DescriptionDraftCompleted برمی‌گرداند
• DescriptionInputError/ValidationError → HTTP 400؛ Timeout/AgentError → HTTP 500
• کلید artifact نامعتبر → draft.description.failed با error_code=INVALID_ARTIFACT_KEY