# POST /v2/account-history/calculate-complete

<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-complete</td><td>AccountHistoryController@calculateCompleteHistory</td><td>authWithJwt</td></tr></tbody></table>

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

این API برای **محاسبه کامل مانده‌ها** استفاده می‌شود؛ یعنی:

<div id="bkmrk-%D9%85%D8%AD%D8%A7%D8%B3%D8%A8%D9%87-%D9%85%D8%A7%D9%86%D8%AF%D9%87%E2%80%8C%D9%87%D8%A7%DB%8C-%D8%B1%D9%88%D8%B2" style="direction: rtl; font-family: Vazir, Tahoma; line-height: 1.85; text-align: justify;">- محاسبه مانده‌های **روزانه**
- محاسبه مانده‌های **ماهانه**

</div>محاسبه‌ها می‌توانند بر اساس:

<div id="bkmrk-%DB%8C%DA%A9-%D8%B3%D8%A7%D9%84-%D9%85%D8%B4%D8%AE%D8%B5-%28year%29-%DB%8C" style="direction: rtl; font-family: Vazir, Tahoma; line-height: 1.85; text-align: justify;">- یک سال مشخص (year)
- یا بازه‌ای میان `from / to`

</div>روش اجرا:

<div id="bkmrk-%D9%87%D9%85%D8%B2%D9%85%D8%A7%D9%86-%28sync%29%3A-%D9%87%D8%B1-%D8%AF%D9%88" style="direction: rtl; font-family: Vazir, Tahoma; line-height: 1.85; text-align: justify;">- **همزمان (Sync)**: هر دو محاسبه انجام شده و پاسخ کامل داده می‌شود.
- **غیرهمزمان (Async)**: دو Job جداگانه (daily و monthly) در صف Dispatch می‌شوند.

</div>هر دو محاسبه از طریق سرویس `AccountHistoryService` انجام می‌شوند.

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

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

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

<div id="bkmrk-colleague_id-%D8%A7%D9%84%D8%B2%D8%A7%D9%85%DB%8C%D8%8C" style="direction: rtl; font-family: Vazir, Tahoma; line-height: 1.85; text-align: justify;">- **colleague\_id** الزامی، integer، موجود در colleagues.
- **year** اختیاری، عدد 1300 تا 1500.
- **from / to** تاریخ شمسی معتبر `Y-m-d`.
- **async** مقدار boolean (پیش‌فرض true).
- تاریخ آینده ممنوع → خطای **FUTURE\_DATE\_NOT\_ALLOWED**.
- در صورت عدم ارسال year و عدم ارسال from/to → خطای INVALID\_DATE\_RANGE (در سرویس).

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

<div id="bkmrk-%D8%A7%D8%A8%D8%AA%D8%AF%D8%A7-%D8%A7%D8%B9%D8%AA%D8%A8%D8%A7%D8%B1%D8%B3%D9%86%D8%AC%DB%8C-%D8%A7%D9%86%D8%AC" style="direction: rtl; font-family: Vazir, Tahoma; line-height: 1.85; text-align: justify;">- ابتدا اعتبارسنجی انجام می‌شود.
- اگر from یا to &gt; امروز باشد → خطا 400.
- اگر async=true: 
    - دو Job جدا dispatch می‌شوند: 
        - type = daily
        - type = monthly
    - پاسخ سریع با وضعیت queued برمی‌گردد.
- اگر async=false: 
    - `calculateAndStoreDailyBalance()`
    - `calculateAndStoreMonthlyBalance()`
    - خطای هرکدام → CALCULATION\_ERROR

</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
- job جداگانه برای daily و monthly
- در صورت خطا → fail شدن job
- لاگ کامل شروع، پایان، و خطا

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

```
{
  "payload": null,
  "meta": {
    "colleague_id": 108,
    "year": 1403,
    "from": "1403-01-01",
    "to": "1403-12-29",
    "jobs": ["daily", "monthly"],
    "status": "queued",
    "timestamp": "2025-12-01T14:20: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": {
    "daily": {
      "1403-01-01": { "credit": 0, "debit": 1200000, "balance": -1200000 },
      "1403-01-02": { "credit": 500000, "debit": 0, "balance": 500000 }
    },
    "monthly": {
      "1403-01": { "credit": 0, "debit": 900000, "balance": -900000 },
      "1403-02": { "credit": 500000, "debit": 0, "balance": 500000 }
    }
  },
  "meta": {
    "colleague_id": 108,
    "year": 1403,
    "from": "1403-01-01",
    "to": "1403-12-29",
    "daily_meta": { "...": "..." },
    "monthly_meta": { "...": "..." },
    "timestamp": "2025-12-01T14:20: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-01T14:25:00+03:30"
  }
}
```

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

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

#### خطای محاسباتی یکی از دو عملیات (400)

```
{
  "error": {
    "code": "CALCULATION_ERROR",
    "message": "Error in one or both calculations",
    "details": {
      "daily": null,
      "monthly": {
        "code": "INTERNAL_ERROR",
        "message": "..."
      }
    }
  },
  "meta": {
    "colleague_id": 108,
    "timestamp": "2025-12-01T14:26:00+03:30"
  }
}
```

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

```
{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Unexpected exception..."
  },
  "meta": {
    "colleague_id": 108,
    "timestamp": "2025-12-01T14:26: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-jobs%3A-calculateaccou" style="direction: rtl; font-family: Vazir, Tahoma; line-height: 1.85; text-align: justify;">- Jobs: `CalculateAccountHistoryJob`
- Job Types: `daily`, `monthly`
- Service Methods: 
    - `calculateAndStoreDailyBalance()`
    - `calculateAndStoreMonthlyBalance()`
- همه عملیات‌ها برای همکار `ID = 108` نمونه‌سازی شده‌اند.

</div>