Skip to main content
#P1618

GET /v2/account-history/monthly

Route Info

Method Endpoint Controller Middleware
GET /v2/account-history/monthly AccountHistoryController@getMonthlyBalance authWithJwt

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

این API برای دریافت مانده حساب ماهانه طراحی شده است و دارای مکانیزم هوشمند (Read-Through Cache) است:

  1. بررسی کش: ابتدا سعی می‌کند داده را از Redis بخواند.
  2. محاسبه خودکار (Auto-Calculation): اگر داده در کش نباشد، سیستم به طور خودکار متد calculateAndStoreMonthlyBalance را اجرا می‌کند تا داده‌های آن سال تولید و ذخیره شوند.
  3. بازخوانی: پس از محاسبه، مجدداً داده را از کش می‌خواند و برمی‌گرداند.

توجه: اگر کش خالی باشد، پاسخ این سرویس ممکن است کمی طول بکشد (به اندازه زمان محاسبه مانده سالانه)

ورودی (Query Parameters)

?colleague_id=108&year=1403&month=2

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

  • colleague_id: الزامی | integer | موجود در جدول colleagues.
  • year: الزامی | integer | بازه 1300 تا 1500.
  • month: الزامی | integer | بازه 1 تا 12 (نیاز به ارسال صفر قبل عدد نیست، سیستم خودکار Pad می‌کند).

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

  • اعتبارسنجی ورودی‌ها.
    • خطا → 400 (VALIDATION_ERROR).
  • تبدیل ماه ورودی به فرمت دورقمی (مثلاً 2 به 02).
  • فراخوانی سرویس getMonthlyBalanceFromCache.
  • Logic داخل سرویس:
    1. ساخت کلید Redis.
    2. چک کردن وجود کلید. اگر بود → بازگشت (Meta: cached: true).
    3. اگر نبود → اجرای متد محاسبه (Calculation).
    4. چک کردن مجدد Redis. اگر بود → بازگشت (Meta: cached: false, calculated: true).
    5. اگر باز هم نبود → بازگشت آرایه خطا (CACHE_MISS).
  • اگر خروجی سرویس حاوی error باشد → پاسخ 404.
  • در غیر این صورت → پاسخ 200.

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

حالت ۱: داده در کش موجود بود (Cache Hit)

{
  "payload": {
    "credit": 500000,
    "debit": 0,
    "balance": 500000
  },
  "meta": {
    "colleague_id": 108,
    "year": 1403,
    "month": "02",
    "cached": true,
    "timestamp": "2025-12-01T16:00:00+03:30"
  }
}

حالت ۲: داده محاسبه شد (Cache Miss -> Calculated)

{
  "payload": {
    "credit": 500000,
    "debit": 0,
    "balance": 500000
  },
  "meta": {
    "colleague_id": 108,
    "year": 1403,
    "month": "02",
    "cached": false,
    "calculated": true,
    "timestamp": "2025-12-01T16:00:05+03:30"
  }
}

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

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

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The month must be at least 1."
  },
  "meta": { ... }
}

خطای عدم یافتن/محاسبه (404)

زمانی رخ می‌دهد که حتی پس از تلاش برای محاسبه، داده‌ای در کش ذخیره نشود.

{
  "error": {
    "code": "CACHE_MISS",
    "message": "Balance not found in cache and calculation failed"
  },
  "meta": {
    "colleague_id": 108,
    "year": 1403,
    "month": "02",
    "cached": false,
    "timestamp": "..."
  }
}

خطای سرور (500)

{
  "error": {
    "code": "INTERNAL_ERROR",
Back to top