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

Endpoint

POST /api/v1/draft/claims

هدف آزمون

تولید ادعاهای فارسی ساخت‌یافته و markdown از InventionContext و PriorArtSearchResult.

شرایط آزمون

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

فرآیند آزمون

1. آماده‌سازی body با فیلدهای context و prior_art
2. ارسال POST به /api/v1/draft/claims
3. دریافت ClaimsDraftResponse یا فایل markdown
4. بررسی claims، grounding_claims، claim_prose و markdown_fa

معرفی ویژگی

endpoint تولید ادعانامه فارسی: از زمینه اختراع و نتیجه جستجوی پیشینه، لایه‌های grounding/prose/claims و متن markdown ساخته می‌شود.

• ورودی: {context: InventionContext, prior_art: PriorArtSearchResult} (context می‌تواند خود root باشد اگر prior_art جدا باشد)
• خروجی JSON: schema_version=claims.v2، claims، grounding_claims، claim_prose، markdown_fa، validation، metrics
• دانلود: query download=true یا header Accept: text/markdown → فایل .claims.md
• verbose: trace تفصیلی در لاگ
• Worker async: draft.claims.requested → completed با claims_draft inline (بدون نوشتن نتیجه به S3)؛ ورودی‌ها فقط از artifact کلیدها خوانده می‌شوند
• دفاع artifact key: context و prior_art_search_result باید زیر workspaces/{workspace_id}/ باشند

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

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

1. ارسال body با context و prior_art معتبر
2. دریافت کد 200
3. بررسی schema_version برابر claims.v2 و غیرخالی بودن claims و markdown_fa

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

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

سناریو 3: دانلود ادعانامه با query parameter

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

سناریو 4: دانلود ادعانامه با Accept header

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

سناریو 5: تولید با verbose

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

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

1. حذف کلید فعال LLM
2. ارسال body معتبر
3. دریافت کد 503
4. بررسی اشاره پیام به AVALAI_API_KEY یا OPENAI_API_KEY

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

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

سناریو 8: Worker — ادعا ناقص یا نامعتبر

1. شبیه‌سازی خروجی بدون claims یا validation.is_valid=false
2. عدم انتشار ClaimsDraftCompleted
3. دریافت draft.claims.failed با error_code=CLAIMS_GENERATION_ERROR

قالب API

Swagger

post:
  summary: Generate Persian patent claims from invention context and prior-art analysis
  responses:
    200:
      description: Persian claims draft as JSON or downloadable markdown
    400:
      description: Invalid body or claims generation validation error
    503:
      description: LLM API key not configured
    500:
      description: Claims generation failed

نمونه ورودی

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

نمونه خروجی

{
  "schema_version": "claims.v2",
  "case_id": "case-001",
  "markdown_fa": "ادعانامه\n\nآنچه ادعا می شود:\n\n...",
  "grounding_claims": [],
  "claim_prose": [],
  "claims": [],
  "claim_strategy": {},
  "validation": { "is_valid": true },
  "warnings": [],
  "metrics": { "duration_ms": 1200 }
}

Status Codes

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

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

پاسخ JSON با claims.v2 و markdown_fa فارسی، یا فایل .claims.md قابل دانلود با کد 200.

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

1. بررسی کد 200 برای body معتبر
2. بررسی وجود claims و markdown_fa
3. بررسی دانلود با download=true و Content-Type برابر text/markdown
4. بررسی 400 بدون prior_art
5. بررسی 503 بدون کلید API

توضیحات

• نام فایل دانلود: {case_id}.claims.md یا claims.claims.md
• مسیر async محصول: صف draft.claims.requested و رویدادهای progress/completed/failed
• Worker خروجی را inline در ClaimsDraftCompleted برمی‌گرداند (نه artifact S3)
• ادعا خالی یا validation.is_valid≠true → Failed با CLAIMS_GENERATION_ERROR (non-retryable)
• کلید artifact نامعتبر → draft.claims.failed با error_code=INVALID_ARTIFACT_KEY