# POST /v2/account-history/calculate-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>POST</td><td>/v2/account-history/calculate-daily</td><td>AccountHistoryController@calculateDailyBalanceForYear</td><td>authWithJwt</td></tr></tbody></table>

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

این API برای **محاسبه و ذخیره مانده‌های روزانه** یک همکار (Colleague) استفاده می‌شود. فرآیند محاسبه می‌تواند:

<div id="bkmrk-%D8%A8%D8%B1%D8%A7%DB%8C-%DA%A9%D9%84-%DB%8C%DA%A9-%D8%B3%D8%A7%D9%84-%D9%85%D8%B4%D8%AE%D8%B5-" style="direction: rtl; font-family: Vazir, Tahoma; line-height: 1.85; text-align: justify;">- برای کل یک سال مشخص (جلالی)
- یا برای یک بازه تاریخ خاص

</div>محاسبات امکان اجرا به صورت:

<div id="bkmrk-%D9%87%D9%85%D8%B2%D9%85%D8%A7%D9%86-%28sync%29-%D8%A8%D8%A7-%D8%A8%D8%A7%D8%B2" style="direction: rtl; font-family: Vazir, Tahoma; line-height: 1.85; text-align: justify;">- **همزمان (Sync)** با بازگردانی نتیجه
- **غیرهمزمان (Async)** با استفاده از Job در Queue

</div>نتیجه‌های محاسبه شده در Redis با TTL سی روزه ذخیره می‌شوند.

<div id="bkmrk--1" style="direction: rtl; font-family: Vazir, Tahoma; line-height: 1.85; text-align: justify;">  </div>### ورودی (Request Body)

```
{
  "colleague_id": 24,
  "year": 1403,          // optional
  "from": "1403-01-01",  // optional
  "to": "1403-12-29",    // optional
  "async": true          // optional, default = false
}
```

#### قوانین اعتبارسنجی

<div id="bkmrk-colleague_id-%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** الزامی و باید در جدول colleagues موجود باشد.
- **year** اختیاری، عدد بین 1300 تا 1500.
- **from/to** تاریخ شمسی در فرمت `Y-m-d`.
- **async** مقدار boolean.
- ارسال تاریخ‌های آینده ممنوع است.

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

<div id="bkmrk-%D8%A7%D9%88%D9%84-%D8%A7%D8%B9%D8%AA%D8%A8%D8%A7%D8%B1%D8%B3%D9%86%D8%AC%DB%8C-larav" style="direction: rtl; font-family: Vazir, Tahoma; line-height: 1.85; text-align: justify;">- اول اعتبارسنجی Laravel انجام می‌شود.
- اگر تاریخ آینده ارسال شود → خطا.
- اگر async=true → Job با پارامترهای: 
    - colleague\_id
    - year
    - type=daily
    
    Dispatch می‌شود.
- اگر async=false → `calculateAndStoreDailyBalance()` مستقیماً فراخوانی می‌شود.

</div>#### مشخصات Job

<div id="bkmrk-timeout%3A-3600-%D8%AB%D8%A7%D9%86%DB%8C%D9%87-" style="direction: rtl; font-family: Vazir, Tahoma; line-height: 1.85; text-align: justify;">- **timeout:** 3600 ثانیه
- **tries:** 3
- در صورت خطا → fail شدن job
- لاگ کامل برای شروع، پایان و خطا

  </div>### پاسخ موفق (Async Mode)

```
{
  "payload": null,
  "meta": {
    "colleague_id": 24,
    "year": 1403,
    "from": "1403-01-01",
    "to": "1403-12-29",
    "type": "daily",
    "status": "queued",
    "timestamp": "2025-12-01T10:15:00+03:30"
  }
}
```

<div id="bkmrk--2" style="direction: rtl; font-family: Vazir, Tahoma; line-height: 1.85; text-align: justify;">  </div>### پاسخ موفق (Sync Mode)

```
{
  "payload": {
    "1403-01-01": {
      "credit": 0,
      "debit": 1200000,
      "balance": -1200000
    },
    "1403-01-02": {
      "credit": 500000,
      "debit": 0,
      "balance": 500000
    }
  },
  "meta": {
    "colleague_id": 24,
    "from": "1403-01-01",
    "to": "1403-12-29",
    "total_days": 365,
    "timestamp": "2025-12-01T10:15:00+03:30"
  }
}
```

<div id="bkmrk--3" style="direction: rtl; font-family: Vazir, Tahoma; line-height: 1.85; text-align: justify;">  </div>### پاسخ‌های خطا (Error Responses)

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

```
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "colleague_id is required"
  },
  "meta": {
    "timestamp": "2025-12-01T10:18:00+03:30"
  }
}
```

#### تاریخ آینده مجاز نیست (400)

```
{
  "error": {
    "code": "FUTURE_DATE_NOT_ALLOWED",
    "message": "Cannot calculate for future dates."
  },
  "meta": {
    "colleague_id": 24,
    "to": "1404-01-01",
    "timestamp": "2025-12-01T10:18:00+03:30"
  }
}
```

#### خطای داخلی (500)

```
{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Unexpected error..."
  },
  "meta": {
    "colleague_id": 24,
    "timestamp": "2025-12-01T10:20:00+03:30"
  }
}
```

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

<div id="bkmrk-redis-key-format%3A-ac" style="direction: rtl; font-family: Vazir, Tahoma; line-height: 1.85; text-align: justify;">- Redis Key Format: `account_history:daily:{colleagueId}:{year}:{date}`
- TTL: 30 روز
- Job Class: `CalculateAccountHistoryJob`
- Service Method: `calculateAndStoreDailyBalance()`

</div>