Skip to main content
#P1617

GET /v2/account-history/daily

Route Info

Method Endpoint Controller Middleware
GET /v2/account-history/daily AccountHistoryController@getDailyBalance authWithJwt

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

این API صرفاً برای خواندن سریع اطلاعات محاسبه‌شده از قبل استفاده می‌شود.

  • این متد هیچ محاسبه‌ای انجام نمی‌دهد (Calculation Trigger نیست).
  • داده‌ها را مستقیماً از Cache (Redis) بازیابی می‌کند.
  • اگر داده‌ای برای تاریخ مورد نظر محاسبه نشده باشد (در کش نباشد)، خطای 404 برمی‌گرداند.

ورودی (Query Parameters)

پارامترها به صورت Query String ارسال می‌شوند:

?colleague_id=108&year=1403&date=1403-01-05

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

  • colleague_id: الزامی | integer | باید در جدول colleagues موجود باشد.
  • year: الزامی | integer | بازه 1300 تا 1500.
  • date: الزامی | فرمت دقیق Y-m-d (تاریخ شمسی).

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

  • ابتدا ورودی‌ها توسط Validator بررسی می‌شوند.
    • در صورت شکست: بازگشت خطای 400 با کد VALIDATION_ERROR.
  • متد سرویس getDailyBalanceFromCache($colleagueId, $year, $date) فراخوانی می‌شود.
  • سرویس چک می‌کند آیا کلید مربوطه در Redis وجود دارد یا خیر.
  • بررسی نتیجه سرویس:
    • اگر خروجی شامل کلید error باشد → بازگشت خطای 404 (Not Found).
    • در غیر این صورت → بازگشت داده‌ها با وضعیت 200.
  • مدیریت خطا (Exception Handling): هرگونه خطا در بلاک try-catch منجر به خطای 500 می‌شود.

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

{
  "payload": {
    "credit": 0,
    "debit": 1500000,
    "balance": -1500000
  },
  "meta": {
    "colleague_id": 108,
    "year": 1403,
    "date": "1403-01-05",
    "source": "cache",
    "timestamp": "2025-12-01T15:30:00+03:30"
  }
}
* ساختار payload بسته به خروجی سرویس ممکن است دقیقاً به این شکل باشد.

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

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

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The date does not match the format Y-m-d."
  },
  "meta": {
    "timestamp": "2025-12-01T15:30:00+03:30"
  }
}

داده یافت نشد / محاسبه نشده (404)

{
  "error": {
    "code": "NOT_FOUND",
    "message": "No data found for this date. Please calculate first."
  },
  "meta": {
    "timestamp": "2025-12-01T15:31:00+03:30"
  }
}

خطای سرور (500)

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Redis connection failed..."
  },
  "meta": {
    "colleague_id": 108,
    "timestamp": "2025-12-01T15:32:00+03:30"
  }
}

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

  • Service Method: AccountHistoryService::getDailyBalanceFromCache
  • Redis Key Pattern: معمولاً به فرمت account_history:daily:{colleagueId}:{year}:{date} می‌باشد.
  • این متد Stateless است و فقط خواندن انجام می‌دهد.
Back to top