# POST /v2/batch-accounting/preview

# Preview Batch Processing (Dry‑Run)

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

<div class="api-docs" id="bkmrk-"></div>## Request Overview

<div class="api-docs" id="bkmrk-url%3A-%2Fv2%2Fbatch-accou"><div class="endpoint-info"><div>**URL:** `/v2/batch-accounting/preview`</div><div>**Method:** <span class="method-post">POST</span></div><div>**Middleware:** authWithJwt, shamsiDate</div></div></div>## Body Parameters

<div class="api-docs" id="bkmrk-field-type-required-"><table class="schema-table"><thead><tr><th>Field</th><th>Type</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td>`start_date`</td><td>string</td><td>yes</td><td>تاریخ شمسی شروع بازه به فرمت دقیق `YYYY-MM-DD`. (اعتبارسنجی regex و همچنین اعتبارسنجی Jalali توسط Middleware)</td></tr><tr><td>`end_date`</td><td>string</td><td>yes</td><td>تاریخ پایان بازه، فرمت مشابه start\_date</td></tr><tr><td>`batch_size`</td><td>integer</td><td>no</td><td>اندازه Batch بین **10 تا 1000**. مقدار پیش‌فرض **100**.</td></tr></tbody></table>

</div>## Validation Rules

<div class="api-docs" id="bkmrk-start_date%3A-required">- 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

</div>## Response (Success)

<div class="api-docs" id="bkmrk-field-type-descripti"><table class="schema-table"><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>`success`</td><td>boolean</td><td>وضعیت کلی پیش‌نمایش</td></tr><tr><td>`data.total_documents`</td><td>integer</td><td>تعداد کل اسناد در دیتابیس بین start و end با status != 5</td></tr><tr><td>`data.batch_size`</td><td>integer</td><td>مقدار نهایی batch\_size (ورودی یا پیش‌فرض)</td></tr><tr><td>`data.estimated_batches`</td><td>integer</td><td>تعداد Batch موردنیاز (ceil(total / batch\_size))</td></tr><tr><td>`data.estimated_time_seconds`</td><td>float</td><td>تخمین زمان کل (0.5 ثانیه برای هر batch)</td></tr><tr><td>`data.estimated_time_minutes`</td><td>float</td><td>زمان تخمینی بر حسب دقیقه</td></tr><tr><td>`data.working_days_count`</td><td>integer</td><td>تعداد روزهای شمسی شامل start→end</td></tr><tr><td>`data.date_range`</td><td>object</td><td>شامل start، end، نسخه‌های فرمت‌شده (formatFull)، و اطلاعات بازه</td></tr><tr><td>`message`</td><td>string</td><td>پیام نهایی پیش‌نمایش: «پیش‌نمایش: X سند در Y batch پردازش خواهد شد»</td></tr></tbody></table>

</div>```
{
  "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 پردازش خواهد شد"
}
  
```

<div class="api-docs" id="bkmrk--1"></div>## Response (Validation Error: 422)

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

<div class="api-docs" id="bkmrk--2"></div>## Response (Server Error)

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

<div class="api-docs" id="bkmrk--3"></div>## Internal Architecture

<div class="api-docs" id="bkmrk-component-descriptio"><table class="schema-table"><thead><tr><th>Component</th><th>Description</th></tr></thead><tbody><tr><td>`manual_documents` table</td><td>فیلتر اسناد بر اساس بازه تاریخ و حذف status=5</td></tr><tr><td>`ShamsiDateHelper::generateDateRange()`</td><td>تولید تمام روزهای شمسی بین start و end</td></tr><tr><td>`ShamsiDateHelper::formatFull()`</td><td>فرمت تبدیل YYYY-MM-DD به متن کامل مانند «۱ فروردین ۱۴۰۳»</td></tr><tr><td>`estimatedBatches`</td><td>محاسبه تعداد Batch از طریق ceil(total/batch\_size)</td></tr><tr><td>`estimatedTime`</td><td>زمان تخمینی با مدل 0.5 ثانیه برای هر Batch</td></tr></tbody></table>

</div>## Process Flow

<div class="api-docs" id="bkmrk-validate-jwt-token-%E2%86%93"><div class="flowchart"><div class="flow-item">Validate JWT Token</div><div class="flow-arrow">↓</div><div class="flow-item">Validate Input (start_date, end_date, batch_size)</div><div class="flow-arrow">↓</div><div class="flow-item">Count DB Documents (manual_documents)</div><div class="flow-arrow">↓</div><div class="flow-item">Compute Estimated Batches</div><div class="flow-arrow">↓</div><div class="flow-item">Compute Estimated Time</div><div class="flow-arrow">↓</div><div class="flow-item">Generate Shamsi Date Range</div><div class="flow-arrow">↓</div><div class="flow-item">Return Preview JSON</div></div></div>