Skip to main content
#P1639

POST /v2/batch-accounting/process/date-range

Batch Process Documents by Date Range

این اندپوینت پردازش دسته‌ای اسناد حسابداری را در یک بازه تاریخی شمسی انجام می‌دهد. تمام اسنادی که در تاریخ مشخص‌شده قرار دارند از دیتابیس فراخوانی شده، در چانک‌های کنترل‌شده پردازش می‌شوند و داده‌های Redis Accounting شامل اسناد و مانده‌ها آپدیت می‌گردند. این عملیات برای عملیات‌های Rebuild، Sync و Mass‑Recalculate استفاده می‌شود.

Request Overview

URL: /v2/batch-accounting/process/date-range
Method: POST
Middleware: authWithJwt, shamsiDate
Controller: BatchAccountingController@processByDateRange

Authentication

این اندپوینت کاملاً محافظت‌شده بوده و فقط کاربران دارای JWT معتبر می‌توانند آن را اجرا کنند. در صورت نامعتبر بودن Token، خطاهای استاندارد میدلور AuthWithJWT بازگردانده می‌شود.

Request Body Parameters

Field Type Required Description
start_date string (shamsi) yes تاریخ شروع بازه (فرمت شمسی YYYY-MM-DD) — توسط middleware اعتبارسنجی می‌شود
end_date string (shamsi) yes تاریخ پایان بازه (فرمت شمسی YYYY-MM-DD)
batch_size integer no تعداد پردازش در هر چانک. حداقل 10، حداکثر 1000. پیش‌فرض: 100

Request Example

POST /v2/batch-accounting/process/date-range
Content-Type: application/json

{
  "start_date": "1403-01-01",
  "end_date": "1403-01-31",
  "batch_size": 200
}

Response (Success)

Field Type Description
success boolean True در صورت موفقیت
data.total_processed integer تعداد کل اسناد پردازش‌شده در همه چانک‌ها
data.total_errors integer تعداد خطاهای رخ‌داده در پردازش Batchها
data.batch_results array خروجی کامل تمامی Batchها
data.date_range object محدوده تاریخی پردازش‌شده 
{
  "success": true,
  "data": {
    "success": true,
    "total_processed": 283,
    "total_errors": 2,
    "batch_results": [
      {
        "processed": 100,
        "errors": 0
      },
      {
        "processed": 98,
        "errors": 1
      },
      {
        "processed": 85,
        "errors": 1
      }
    ],
    "date_range": {
      "start": "1403-01-01",
      "end": "1403-01-31"
    }
  },
  "message": "پردازش کامل شد. 283 سند پردازش شد."
}

Response (Validation Error)

{
  "success": false,
  "message": "خطا در اعتبارسنجی",
  "errors": {
    "start_date": [
      "The start_date field format is invalid."
    ]
  }
}

Response (Shamsi Date Middleware Error)

{
  "success": false,
  "message": "فیلد start_date باید تاریخ شمسی معتبر به فرمت YYYY-MM-DD باشد",
  "field": "start_date",
  "received_value": "2024-01-01",
  "example": "1404-05-27"
}

Response (Server Error)

{
  "success": false,
  "message": "خطا در پردازش: Redis connection timeout"
}

Internal Processing Architecture

این عملیات تمام اسناد جدول manual_documents را در بازه تاریخی مشخص دریافت می‌کند، سپس آنها را در چانک‌های کنترل‌شده پردازش می‌کند. بین هر Batch یک توقف 0.1 ثانیه‌ای برای جلوگیری از فشار Redis انجام می‌شود.

Module Description
manual_documents فیلتر بر اساس تاریخ و وضعیت (status != 5)
processBatch() پردازش هر چانک (ذخیره سند، بروزرسانی مانده‌ها، آپدیت ایندکس‌ها)
usleep(100000) توقف 0.1s بین Batchها برای جلوگیری از فشار Redis

Process Flow

Validate JWT Authentication
↓
Validate Shamsi Dates (middleware)
↓
Request Validation (start_date, end_date, batch_size)
↓
Query DB: manual_documents (date range, status != 5)
↓
Chunk Documents (batch_size)
↓
Loop Through Chunks
↓
Process Each Batch (processBatch)
↓
Update Redis: documents + indexes + balances
↓
usleep(100ms) Throttle
↓
Aggregate Results (processed/errors)
↓
Return Final JSON Response
Back to top