ATP - بازنویسی بخش یا ادعای پیش‌نویس (POST /api/v1/draft/rewrite)

Endpoint

POST /api/v1/draft/rewrite

هدف آزمون

بازنویسی واحدهای ادعانامه یا توصیف بر اساس دستور فارسی، با آپلود multipart برای تست محلی/Swagger (مسیر محصول ویرایش: conversation agent_key=draft).

شرایط آزمون

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

فرآیند آزمون

1. آماده‌سازی فیلدهای form (instruction، scope، document_type و هدف)
2. آپلود فایل claims_draft و/یا description_draft متناسب با document_type
3. ارسال POST multipart به /api/v1/draft/rewrite
4. دریافت DraftRewriteResponse و بررسی replacements

معرفی ویژگی

endpoint توسعه/تست برای بازنویسی انتخاب، بخش، یا جایگزینی اصطلاح در کل سند. مسیر محصول ویرایش انتخاب‌شده از conversation.v1 (agent_key=draft + propose_draft_edit) است؛ صف‌های draft.edit. و draft.fragment_edit. میراث‌اند.

• ورودی: multipart/form-data (نه JSON خالص)
• scope: selection | section | document
• document_type: claims | description | both
• خروجی: replacements[] با unit_type، text_fa و change_summary_fa
• مسیر محصول: conversation.turn.requested با agent_key=draft → propose_draft_edit (متن ساده) → Core draft_edit_apply (Slice + accept/reject)
• Worker میراث: draft.edit.requested هنوز در compose است ولی مسیر محصول نیست؛ draft.fragment_edit.* بازنشسته شده (event-schema ADR-0011)

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

سناریو 1: بازنویسی موفق بخش توصیف

1. آپلود description_draft.json با scope=section و section_key معتبر
2. ارسال instruction فارسی و document_type=description
3. دریافت کد 200
4. بررسی replacements غیرخالی و section_key مطابق هدف

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

1. ارسال document_type=claims بدون claims_draft_file
2. ارسال POST
3. دریافت کد 400 با اشاره به claims_draft_file

سناریو 3: بازنویسی ادعای مشخص با scope=section

1. آپلود claims_draft.json با claim_number معتبر
2. ارسال document_type=claims و scope=section
3. دریافت کد 200
4. بررسی unit_type=claim و claim_number در replacements

سناریو 4: جایگزینی اصطلاح در کل سند (scope=document)

1. ارسال term_from و term_to همراه فایل پیش‌نویس
2. دریافت کد 200
3. بررسی اعمال جایگزینی در text_fa واحدهای برگشتی

سناریو 5: بازنویسی انتخاب متن (scope=selection)

1. ارسال selection_text غیرخالی همراه فایل مرتبط
2. دریافت کد 200
3. بررسی اینکه واحد حاوی آن انتخاب بازنویسی شده است

سناریو 6: خطا — claim_number نامعتبر

1. ارسال claim_number غیرعددی
2. دریافت کد 400
3. بررسی پیام الزام عدد صحیح

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

1. ارسال scope خارج از selection/section/document
2. دریافت کد 400

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

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

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

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

سناریو 10: مسیر محصول — ویرایش از conversation draft

1. انتشار ConversationTurnRequested با agent_key=draft و selection در attachments
2. انتشار tool_call propose_draft_edit با متن ساده (نه Slice)
3. Core draft_edit_proposal part می‌سازد و accept/reject را اعمال می‌کند

قالب API

Swagger

post:
  summary: Rewrite claim/section text (dev form+upload; product edit uses conversation draft agent)
  responses:
    200:
      description: Rewrite replacements returned
    400:
      description: Invalid form fields, missing uploads, or rewrite validation error
    503:
      description: LLM API key not configured
    500:
      description: Rewrite failed

نمونه ورودی

curl -X POST "http://127.0.0.1:8000/api/v1/draft/rewrite" \
  -F "instruction=عنوان را شفاف‌تر بنویس" \
  -F "scope=section" \
  -F "document_type=description" \
  -F "section_key=title" \
  -F "description_draft_file=@description_draft.json;type=application/json"

نمونه خروجی

{
  "document_type": "description",
  "replacements": [
    {
      "unit_type": "section",
      "section_key": "title",
      "text_fa": "عنوان جدید",
      "change_summary_fa": "شفاف‌سازی عنوان"
    }
  ],
  "warnings": [],
  "metrics": { "duration_ms": 800, "llm_calls": 1 }
}

Status Codes

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

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

پاسخ JSON با حداقل یک replacement و کد 200 برای مسیر HTTP توسعه؛ مسیر محصول ویرایش از conversation draft + Core draft_edit_apply است.

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

1. بررسی کد 200 برای form و فایل معتبر
2. بررسی وجود replacements و text_fa غیرخالی
3. بررسی 400 بدون فایل الزامی
4. بررسی 400 برای claim_number غیرعددی
5. بررسی 503 بدون کلید API

توضیحات

• این endpoint برای Swagger/dev است؛ ویرایش محصول از conversation-worker (agent_key=draft) و نه از این HTTP است
• فایل خالی اختیاری (مثل بخش خالی Swagger) به‌عنوان نبود فایل تفسیر می‌شود
• Worker میراث draft.edit خروجی را inline در DraftEditCompleted برمی‌گرداند
• کلید artifact نامعتبر روی مسیر میراث → draft.edit.failed با error_code=INVALID_ARTIFACT_KEY
• fragment-edit-mock را مقابل Core فعلی راه نیندازید