GET /v2/account-history/all-monthly

Route Info 

 

 

 

 

 Method 

 Endpoint 

 Controller 

 Middleware 

 

 

 GET 

 /v2/account-history/all-monthly 

 AccountHistoryController@getAllMonthlyBalances 

 authWithJwt 

 

 

 

 

 شرح عملکرد (Functionality) 

 این API برای دریافت یکجای تمام مانده‌های ماهانه یک سال مشخص استفاده می‌شود. 

 

 

 کاربرد: مناسب برای نمایش جداول خلاصه وضعیت سالانه یا نمودارهای میله‌ای ماهانه. 

 نحوه خواندن: داده‌ها را به صورت دسته‌ای (Bulk) با استفاده از الگوی Wildcard از Redis استخراج می‌کند. 

 بدون محاسبه (No Calculation): این متد صرفاً داده‌های موجود در کش را می‌خواند. اگر برای ماهی داده‌ای محاسبه نشده باشد، در خروجی ظاهر نخواهد شد (Trigger محاسبه ندارد). 

 

 

 ورودی (Query Parameters) 

 ?colleague_id=108&year=1403

 

 قوانین اعتبارسنجی (Validation Rules) 

 

 

 colleague_id: الزامی | integer | موجود در جدول colleagues . 

 year: الزامی | integer | بازه 1300 تا 1500. 

 

 

 منطق اجرا (Execution Logic) 

 

 

 بررسی ورودی‌ها توسط Validator. 

 جستجو در Redis با الگوی: MONTHLY_BALANCE_KEY{colleagueId}:{year}:* . 

 استخراج کلیدها و سپس دریافت مقادیر (Values). 

 استخراج شماره ماه: سیستم ماه را از انتهای کلید Redis جدا می‌کند (مثلاً از ...:1403:05 مقدار 05 برداشته می‌شود). 

 ذخیره در آرایه خروجی به صورتی که کلید آرایه، شماره ماه باشد . 

 مرتب‌سازی بر اساس ماه ( ksort ) تا داده‌ها به ترتیب زمانی (فروردین تا اسفند) باشند. 

 بازگشت پاسخ نهایی. 

 

 

 پاسخ موفق (200 OK) 

 خروجی به صورت Map (Dictionary) است که کلیدهای آن شماره ماه (معمولاً دو رقمی مثل "01") هستند. 

 {

 "payload": {

 "01": {

 "credit": 1000000,

 "debit": 500000,

 "balance": 500000

 },

 "02": {

 "credit": 200000,

 "debit": 0,

 "balance": 700000

 },

 "12": {

 "credit": 0,

 "debit": 100000,

 "balance": 600000

 }

 },

 "meta": {

 "colleague_id": 108,

 "year": 1403,

 "total_months": 3,

 "cached": true,

 "timestamp": "2025-12-01T16:30:00+03:30"

 }

}

 

 * در مثال بالا فقط ماه‌های 1، 2 و 12 محاسبه شده و در کش بوده‌اند. 

 پاسخ‌های خطا (Error Responses) 

 خطای اعتبارسنجی (400) 

 {

 "error": {

 "code": "VALIDATION_ERROR",

 "message": "The selected colleague id is invalid."

 },

 "meta": { ... }

}

 

 خطای سرور (500) 

 {

 "error": {

 "code": "INTERNAL_ERROR",

 "message": "Redis connection failed"

 },

 "meta": { ... }

}

 

 

 توضیحات فنی (Meta) 

 

 

 Redis Key Parse: منطق استخراج ماه به صورت substr($key, strrpos($key, ':') + 1) است. این یعنی ساختار کلید باید دقیقاً با : جدا شده باشد. 

 Missing Data: اگر ماه خاصی (مثلاً تیرماه) در خروجی نیست، به این معنی است که کاربر هنوز درخواست محاسبه برای آن سال/ماه را نداده است. فرانت‌اند باید این را مدیریت کند (مثلاً نمایش مقدار 0 یا دکمه "محاسبه").