# GET /v2/account-history/daily

<div id="bkmrk-" style="direction: rtl; font-family: Vazir, Tahoma; line-height: 1.85; text-align: justify;">  </div>### Route Info

<div id="bkmrk-method-endpoint-cont" style="direction: rtl; font-family: Vazir, Tahoma; line-height: 1.85; text-align: justify;"><table border="1" style="width: 100%; border-collapse: collapse; text-align: center;"><tbody><tr style="background: #f5f5f5; font-weight: bold;"><td>Method</td><td>Endpoint</td><td>Controller</td><td>Middleware</td></tr><tr><td>GET</td><td>/v2/account-history/daily</td><td>AccountHistoryController@getDailyBalance</td><td>authWithJwt</td></tr></tbody></table>

  </div>### شرح عملکرد (Functionality)

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

<div id="bkmrk-%D8%A7%DB%8C%D9%86-%D9%85%D8%AA%D8%AF-%D9%87%DB%8C%DA%86-%D9%85%D8%AD%D8%A7%D8%B3%D8%A8%D9%87%E2%80%8C%D8%A7" style="direction: rtl; font-family: Vazir, Tahoma; line-height: 1.85; text-align: justify;">- این متد هیچ محاسبه‌ای انجام نمی‌دهد (Calculation Trigger نیست).
- داده‌ها را مستقیماً از **Cache (Redis)** بازیابی می‌کند.
- اگر داده‌ای برای تاریخ مورد نظر محاسبه نشده باشد (در کش نباشد)، خطای 404 برمی‌گرداند.

  </div>### ورودی (Query Parameters)

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

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

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

<div id="bkmrk-colleague_id%3A-%D8%A7%D9%84%D8%B2%D8%A7%D9%85%DB%8C" style="direction: rtl; font-family: Vazir, Tahoma; line-height: 1.85; text-align: justify;">- **colleague\_id:** الزامی | integer | باید در جدول `colleagues` موجود باشد.
- **year:** الزامی | integer | بازه 1300 تا 1500.
- **date:** الزامی | فرمت دقیق `Y-m-d` (تاریخ شمسی).

  </div>### منطق اجرا (Execution Logic)

<div id="bkmrk-%D8%A7%D8%A8%D8%AA%D8%AF%D8%A7-%D9%88%D8%B1%D9%88%D8%AF%DB%8C%E2%80%8C%D9%87%D8%A7-%D8%AA%D9%88%D8%B3%D8%B7-" style="direction: rtl; font-family: Vazir, Tahoma; line-height: 1.85; text-align: justify;">- ابتدا ورودی‌ها توسط `Validator` بررسی می‌شوند. 
    - در صورت شکست: بازگشت خطای **400** با کد `VALIDATION_ERROR`.
- متد سرویس `getDailyBalanceFromCache($colleagueId, $year, $date)` فراخوانی می‌شود.
- سرویس چک می‌کند آیا کلید مربوطه در Redis وجود دارد یا خیر.
- **بررسی نتیجه سرویس:**
    - اگر خروجی شامل کلید `error` باشد → بازگشت خطای **404** (Not Found).
    - در غیر این صورت → بازگشت داده‌ها با وضعیت **200**.
- مدیریت خطا (Exception Handling): هرگونه خطا در بلاک `try-catch` منجر به خطای **500** می‌شود.

  </div>### پاسخ موفق (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"
  }
}
```

<div class="align-right" id="bkmrk-%2A-%D8%B3%D8%A7%D8%AE%D8%AA%D8%A7%D8%B1-payload-%D8%A8%D8%B3%D8%AA" style="direction: rtl; font-family: Vazir, Tahoma; line-height: 1.85;"><small>\* ساختار payload بسته به خروجی سرویس ممکن است دقیقاً به این شکل باشد.</small>   </div>### پاسخ‌های خطا (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"
  }
}
```

<div id="bkmrk--1" style="direction: rtl; font-family: Vazir, Tahoma; line-height: 1.85; text-align: justify;">  </div>### توضیحات فنی (Meta)

<div id="bkmrk-service-method%3A-acco" style="direction: rtl; font-family: Vazir, Tahoma; line-height: 1.85; text-align: justify;">- **Service Method:** `AccountHistoryService::getDailyBalanceFromCache`
- **Redis Key Pattern:** معمولاً به فرمت `account_history:daily:{colleagueId}:{year}:{date}` می‌باشد.
- این متد Stateless است و فقط خواندن انجام می‌دهد.

</div>