Skip to main content
#P1649

POST /v2/batch-accounting/preview

Preview Batch Processing (Dry‑Run)

این اندپوینت یک پیش‌نمایش کامل از عملیات پردازش Batch را ارائه می‌دهد، بدون اینکه هیچ پردازش واقعی روی Redis یا دیتابیس انجام شود. این پیش‌نمایش برای تصمیم‌گیری مهندسی قبل از اجرای پردازش‌های سنگین استفاده می‌شود و شامل: - تعداد اسناد قابل پردازش، - تعداد Batch مورد نیاز، - زمان تخمینی، - تعداد روزهای شمسی در بازه، - و اطلاعات کامل بازه تاریخ می‌باشد.

Request Overview

URL: /v2/batch-accounting/preview
Method: POST
Middleware: authWithJwt, shamsiDate

Body Parameters

Field Type Required Description
start_date string yes تاریخ شمسی شروع بازه به فرمت دقیق YYYY-MM-DD. (اعتبارسنجی regex و همچنین اعتبارسنجی Jalali توسط Middleware)
end_date string yes تاریخ پایان بازه، فرمت مشابه start_date
batch_size integer no اندازه Batch بین 10 تا 1000. مقدار پیش‌فرض 100.

Validation Rules

  • start_date: required, string, regex:/^\\d{4}-\\d{2}-\\d{2}$/
  • end_date: required, string, regex:/^\\d{4}-\\d{2}-\\d{2}$/
  • batch_size: nullable, integer, min:10, max:1000

Response (Success)

Field Type Description
success boolean وضعیت کلی پیش‌نمایش
data.total_documents integer تعداد کل اسناد در دیتابیس بین start و end با status != 5
data.batch_size integer مقدار نهایی batch_size (ورودی یا پیش‌فرض)
data.estimated_batches integer تعداد Batch موردنیاز (ceil(total / batch_size))
data.estimated_time_seconds float تخمین زمان کل (0.5 ثانیه برای هر batch)
data.estimated_time_minutes float زمان تخمینی بر حسب دقیقه
data.working_days_count integer تعداد روزهای شمسی شامل start→end
data.date_range object شامل start، end، نسخه‌های فرمت‌شده (formatFull)، و اطلاعات بازه
message string پیام نهایی پیش‌نمایش: «پیش‌نمایش: X سند در Y batch پردازش خواهد شد» 
{
  "success": true,
  "data": {
    "total_documents": 1480,
    "batch_size": 100,
    "estimated_batches": 15,
    "estimated_time_seconds": 7.5,
    "estimated_time_minutes": 0.13,
    "working_days_count": 31,
    "date_range": {
      "start": "1403-01-01",
      "end": "1403-01-31",
      "start_formatted": "۱ فروردین ۱۴۰۳",
      "end_formatted": "۳۱ فروردین ۱۴۰۳"
    }
  },
  "message": "پیش‌نمایش: 1480 سند در 15 batch پردازش خواهد شد"
}

Response (Validation Error: 422)

{
  "success": false,
  "message": "خطا در اعتبارسنجی",
  "errors": {
    "start_date": [
      "فرمت تاریخ نامعتبر است."
    ]
  }
}

Response (Server Error)

{
  "success": false,
  "message": "خطا در پیش‌نمایش: Internal server error..."
}

Internal Architecture

Component Description
manual_documents table فیلتر اسناد بر اساس بازه تاریخ و حذف status=5
ShamsiDateHelper::generateDateRange() تولید تمام روزهای شمسی بین start و end
ShamsiDateHelper::formatFull() فرمت تبدیل YYYY-MM-DD به متن کامل مانند «۱ فروردین ۱۴۰۳»
estimatedBatches محاسبه تعداد Batch از طریق ceil(total/batch_size)
estimatedTime زمان تخمینی با مدل 0.5 ثانیه برای هر Batch

Process Flow

Validate JWT Token
↓
Validate Input (start_date, end_date, batch_size)
↓
Count DB Documents (manual_documents)
↓
Compute Estimated Batches
↓
Compute Estimated Time
↓
Generate Shamsi Date Range
↓
Return Preview JSON
Back to top