ATP - استخراج متن از فایل آپلودی (dev) (POST /api/v1/dev/ingest/extract)

Endpoint

POST /api/v1/dev/ingest/extract

هدف آزمون

اجرای کامل pipeline استخراج متن روی فایل آپلودشده و بازگرداندن متن نرمال‌شده.

شرایط آزمون

• APP_ENV برابر local یا docker-dev باشد
• سرویس API در حال اجرا باشد
• فایل نمونه با پسوند .pdf، .docx یا .txt آماده باشد

فرآیند آزمون

1. آماده‌سازی فایل نمونه
2. ارسال POST multipart با فیلد file
3. دریافت DevIngestResponse
4. بررسی normalized_text و متادیتا

معرفی ویژگی

endpoint توسعه‌ای برای تست دستی خط لوله LangGraph intake بدون RabbitMQ. همان گراف validate → parse (pdf/docx/txt) → normalize را که extraction-worker در production اجرا می‌کند، به‌صورت همزمان روی فایل آپلودی اجرا می‌کند.

• فرمت‌های پشتیبانی‌شده: pdf، docx، txt
• حداکثر حجم: ۵۰ مگابایت
• خروجی کامل: normalized_text بدون truncate
• فقط dev: در APP_ENV=docker/production ثبت نمی‌شود (404)
• بدون Milvus: chunking و index برداری انجام نمی‌شود

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

سناریو 1: استخراج موفق فایل txt

1. آپلود فایل sample.txt با محتوای متنی
2. ارسال POST به /api/v1/dev/ingest/extract
3. دریافت کد 200
4. بررسی file_type، pages_count، text_length و normalized_text

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

1. آپلود فایل با پسوند .exe
2. ارسال POST
3. دریافت کد 400 با پیام Unsupported file type

سناریو 3: خطا — فایل خالی

1. آپلود فایل txt با بدنه خالی
2. ارسال POST
3. دریافت کد 422 با پیام Uploaded file is empty

سناریو 4: استخراج PDF با OCR fallback

1. آپلود PDF اسکن‌شده یا با متن native ضعیف
2. ارسال POST
3. دریافت کد 200
4. بررسی warnings مربوط به OCR در پاسخ

قالب API

Swagger

post:
  summary: Run full intake pipeline on uploaded file (dev only)
  responses:
    200:
      description: Extraction completed
    400:
      description: Unsupported file type
    413:
      description: File too large
    422:
      description: Validation error
    500:
      description: Extraction failed
    404:
      description: Route not registered in production

نمونه ورودی

curl -X POST "http://127.0.0.1:8000/api/v1/dev/ingest/extract" \
  -F "file=@sample.txt;type=text/plain"

نمونه خروجی

{
  "file_type": "txt",
  "pages_count": 1,
  "text_length": 11,
  "normalized_text": "sample text",
  "text_sha256": "...",
  "warnings": [],
  "parser_version": "0.1.0"
}

Status Codes

• 200: استخراج با موفقیت انجام شد
• 400: نوع فایل پشتیبانی نمی‌شود
• 413: حجم فایل بیش از ۵۰MB
• 422: فایل خالی یا نام فایل نامعتبر
• 500: خطای داخلی pipeline
• 404: در محیط production مسیر وجود ندارد

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

در محیط dev، پاسخ JSON با normalized_text کامل و متادیتای استخراج با کد 200.

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

1. بررسی کد 200 برای فایل معتبر
2. بررسی تطابق normalized_text با محتوای فایل
3. بررسی text_sha256 و parser_version
4. بررسی 400 برای پسوند نامعتبر

توضیحات

• مسیر production: RabbitMQ document.extraction.requested v2 → extraction-worker
• خروجی production در completed به‌صورت normalized_text_inline است نه HTTP JSON
• جزئیات معماری در GET /architecture/ و ATP architecture
• Swagger فقط در APP_ENV=local|docker-dev یا ENABLE_API_DOCS=true