Skip to main content
#P1620

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 یا دکمه "محاسبه").
Back to top