# GET /v2/account-history/all-monthly

<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/all-monthly</td><td>AccountHistoryController@getAllMonthlyBalances</td><td>authWithJwt</td></tr></tbody></table>

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

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

<div id="bkmrk-%DA%A9%D8%A7%D8%B1%D8%A8%D8%B1%D8%AF%3A-%D9%85%D9%86%D8%A7%D8%B3%D8%A8-%D8%A8%D8%B1%D8%A7%DB%8C-%D9%86" style="direction: rtl; font-family: Vazir, Tahoma; line-height: 1.85; text-align: justify;">- **کاربرد:** مناسب برای نمایش جداول خلاصه وضعیت سالانه یا نمودارهای میله‌ای ماهانه.
- **نحوه خواندن:** داده‌ها را به صورت دسته‌ای (Bulk) با استفاده از الگوی Wildcard از Redis استخراج می‌کند.
- **بدون محاسبه (No Calculation):** این متد صرفاً داده‌های موجود در کش را می‌خواند. اگر برای ماهی داده‌ای محاسبه نشده باشد، در خروجی ظاهر نخواهد شد (Trigger محاسبه ندارد).

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

```
?colleague_id=108&year=1403
```

#### قوانین اعتبارسنجی (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.

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

<div id="bkmrk-%D8%A8%D8%B1%D8%B1%D8%B3%DB%8C-%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.
- جستجو در Redis با الگوی: `MONTHLY_BALANCE_KEY{colleagueId}:{year}:*`.
- استخراج کلیدها و سپس دریافت مقادیر (Values).
- **استخراج شماره ماه:** سیستم ماه را از انتهای کلید Redis جدا می‌کند (مثلاً از `...:1403:05` مقدار `05` برداشته می‌شود).
- ذخیره در آرایه خروجی به صورتی که **کلید آرایه، شماره ماه باشد**.
- مرتب‌سازی بر اساس ماه (`ksort`) تا داده‌ها به ترتیب زمانی (فروردین تا اسفند) باشند.
- بازگشت پاسخ نهایی.

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

<div id="bkmrk-%2A-%D8%AF%D8%B1-%D9%85%D8%AB%D8%A7%D9%84-%D8%A8%D8%A7%D9%84%D8%A7-%D9%81%D9%82%D8%B7-%D9%85" style="direction: rtl; font-family: Vazir, Tahoma; line-height: 1.85; text-align: justify;"><small>\* در مثال بالا فقط ماه‌های 1، 2 و 12 محاسبه شده و در کش بوده‌اند.</small>   </div>### پاسخ‌های خطا (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": { ... }
}
```

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

<div id="bkmrk-redis-key-parse%3A-%D9%85%D9%86%D8%B7" style="direction: rtl; font-family: Vazir, Tahoma; line-height: 1.85; text-align: justify;">- **Redis Key Parse:** منطق استخراج ماه به صورت `substr($key, strrpos($key, ':') + 1)` است. این یعنی ساختار کلید باید دقیقاً با `:` جدا شده باشد.
- **Missing Data:** اگر ماه خاصی (مثلاً تیرماه) در خروجی نیست، به این معنی است که کاربر هنوز درخواست محاسبه برای آن سال/ماه را نداده است. فرانت‌اند باید این را مدیریت کند (مثلاً نمایش مقدار 0 یا دکمه "محاسبه").

</div>