POST /v2/batch-accounting/process/year

Process Batch Documents By Year 

 این اندپوینت اسناد حسابداری را بر اساس یک سال شمسی مشخص پردازش می‌کند. ابتدا تاریخ شروع سال و پایان سال شمسی محاسبه می‌شود، سپس عملیات دسته‌ای (Batch Processing) توسط متد processBatchByDateRange اجرا می‌گردد. نتیجه نهایی شامل تعداد اسناد پردازش‌شده، تعداد خطاها و مجموع Batchهای اجرا شده است. 

 

 Request Overview 

 

 

 URL: /v2/batch-accounting/process/year 

 Method: POST 

 Middleware: authWithJwt, shamsiDate 

 

 

 Body Parameters 

 

 

 

 

 Field 

 Type 

 Required 

 Description 

 

 

 

 

 year 

 integer 

 yes 

 سال شمسی بین 1300 تا 1500 برای پردازش اسناد 

 

 

 batch_size 

 integer 

 no 

 سایز هر Batch. حداقل 50 و حداکثر 2000. مقدار پیش‌فرض: 500. 

 

 

 

 

 Request Example 

 POST /v2/batch-accounting/process/year

{

 "year": 1402,

 "batch_size": 800

}

 

 

 Validation Rules 

 

 

 year: required + integer + min=1300 + max=1500 

 batch_size: integer + min=50 + max=2000 

 اعتبارسنجی سال و ورودی‌ها قبل از پردازش انجام می‌شود 

 

 

 Response (Success) 

 ساختار خروجی بر اساس BatchAccountingService::processBatchByYear است. 

 

 

 

 

 Field 

 Type 

 Description 

 

 

 

 

 success 

 boolean 

 نتیجه کلی پردازش 

 

 

 data.total_processed 

 integer 

 تعداد کل اسناد پردازش‌شده در سال 

 

 

 data.total_errors 

 integer 

 تعداد خطاهای رخ‌داده 

 

 

 data.batches_count 

 integer 

 تعداد Batchهای اجراشده 

 

 

 message 

 string 

 پیام نهایی پردازش سال 

 

 

 

 

 {

 "success": true,

 "data": {

 "success": true,

 "total_processed": 7800,

 "total_errors": 12,

 "batches_count": 16

 },

 "message": "پردازش سال 1402 کامل شد. 7800 سند پردازش شد."

}

 

 

 Response (Validation Error) 

 {

 "success": false,

 "message": "خطا در اعتبارسنجی",

 "errors": {

 "year": [

 "The year must be between 1300 and 1500."

 ]

 }

}

 

 

 Response (Server Error) 

 {

 "success": false,

 "message": "خطا در پردازش سال: Internal server error..."

}

 

 

 Internal Architecture 

 

 

 

 

 Component 

 Description 

 

 

 

 

 processBatchByYear() 

 محاسبه تاریخ آغاز سال و انتهای سال شمسی سپس فراخوانی processBatchByDateRange 

 

 

 ShamsiDateHelper::endOfYear 

 استخراج آخرین روز سال شمسی بر اساس تاریخ شروع 

 

 

 processBatchByDateRange() 

 پردازش دسته‌ای شامل chunking، sleep بین batchها و محاسبه خروجی 

 

 

 

 

 Process Flow 

 

 

 Validate JWT Token 

 ↓ 

 Validate Request Body (year + batch_size) 

 ↓ 

 Compute startOfYear = {year}-01-01 

 ↓ 

 Compute endOfYear via ShamsiDateHelper::endOfYear 

 ↓ 

 Call processBatchByDateRange(startOfYear, endOfYear, batchSize) 

 ↓ 

 Execute Batch Processing (chunking + throttling + batch execution) 

 ↓ 

 Aggregate Results (processed + errors + batch_count) 

 ↓ 

 Return Final JSON Response