# POST /announcement/calculation

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

<div id="bkmrk-method-endpoint-cont" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"><table border="1" cellpadding="6" style="width: 96%; margin: 15px auto; text-align: center; border-collapse: collapse;"><tbody><tr style="background: #f9f9f9; font-weight: bold;"><td>Method</td><td>Endpoint</td><td>Controller</td><td>Middleware</td><td>Purpose</td></tr><tr><td dir="ltr">POST</td><td dir="ltr">/api/v2/announcement/calculation</td><td dir="ltr">V2CreditDebitController@calculationAnnouncement</td><td dir="ltr">authWithJwt</td><td dir="rtl">بازمحاسبه تراز مالی اعلان‌ها و بروزرسانی Balance کلی سیستم.</td></tr></tbody></table>

</div>### منطق عملکرد تابع

تابع **calculationAnnouncement** برای بازتولید محاسبات مالی (مانند مانده‌ها، جمع بدهکار و بستانکار، و وضعیت کلی حساب‌ها) طراحی شده است. هر زمان دادهٔ مالی جدید (مانند اعلان پرداخت یا دریافت) ثبت یا ویرایش شود، فراخوان این مسیر باعث تنظیم مجدد داده‌های تحلیلی می‌شود.

درون متد، سیستم با استفاده از `DB::table('announcements')` و `DB::raw()` مجموع عملیات مالی را از جدول‌های مرتبط (مثل `pays` و `checks`) واکشی و تجمیع کرده، سپس در جدول داخلی `announcement_calculations` یا کش Redis ثبت می‌کند. این فرآیند به صورت atomic در تراکنش دیتابیس انجام می‌شود تا از ناسازگاری داده جلوگیری شود.

<div id="bkmrk--1" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"></div>### ورودی‌ها

<div id="bkmrk-%D9%86%D8%A7%D9%85-%D9%BE%D8%A7%D8%B1%D8%A7%D9%85%D8%AA%D8%B1-%D9%86%D9%88%D8%B9-%D9%85%D9%86%D8%A8%D8%B9" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"><table border="1" cellpadding="6" style="width: 94%; margin: 15px auto; text-align: center; border-collapse: collapse;"><tbody><tr style="background: #f9f9f9; font-weight: bold;"><td>نام پارامتر</td><td>نوع</td><td>منبع</td><td>الزامی</td><td>توضیح</td></tr><tr><td>branch</td><td>integer</td><td>JWT/Header</td><td>بله</td><td>شناسه شعبه برای محاسبه محلی تراز.</td></tr><tr><td>from</td><td>string (Y-m-d)</td><td>Body</td><td>خیر</td><td>تاریخ شروع محدودهٔ مورد محاسبه.</td></tr><tr><td>to</td><td>string (Y-m-d)</td><td>Body</td><td>خیر</td><td>تاریخ پایان محدودهٔ مورد محاسبه.</td></tr><tr><td>type</td><td>string</td><td>Body</td><td>خیر</td><td>نوع اعلان (مثل `pay`، `receive`، `check`).</td></tr><tr><td>currency</td><td>string</td><td>Body</td><td>خیر</td><td>واحد ارزی مورد محاسبه.</td></tr><tr><td>refresh\_cache</td><td>boolean</td><td>Body</td><td>خیر</td><td>در صورت true، کش نتایج حذف و مجدداً محاسبه می‌شود.</td></tr></tbody></table>

</div>### خروجی (Response)

```
{
  "status": true,
  "branch": 3,
  "from": "1404-09-01",
  "to": "1404-09-23",
  "updated": 38,
  "currency": "IRR",
  "calculation": {
    "total_credit": 71250000,
    "total_debit": 53300000,
    "balance": 17950000,
    "last_update": "1404-09-23 13:44",
    "source": "rebuild"
  }
}
```

<div id="bkmrk--2" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"></div>### نکات امنیتی

<div id="bkmrk-%D8%AA%D9%88%DA%A9%D9%86-jwt-%D8%A7%D9%84%D8%B2%D8%A7%D9%85%DB%8C-%D8%A7%D8%B3%D8%AA." style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- توکن JWT الزامی است.
- نقش الزامی: `financial.announcement.manage` یا مدیر سیستم.
- هر درخواست تنها مجاز به محاسبه در محدوده شعبهٔ خود کاربر است.

</div>### نکات عملکردی

<div id="bkmrk-%D9%85%D8%AD%D8%A7%D8%B3%D8%A8%D9%87%E2%80%8C%D9%87%D8%A7-%D8%AF%D8%B1-%D8%AA%D8%B1%D8%A7%DA%A9%D9%86%D8%B4-" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- محاسبه‌ها در تراکنش DB و بهینه‌شده با شاخص‌های زمانی (date index) اجرا می‌شوند.
- در صورت فعال بودن کش Redis، نتیجه تا ۶۰۰ ثانیه نگهداری می‌شود.
- میانگین زمان اجرا برای بازهٔ ۱۰۰۰ اعلان ≈ ۲۵۰ ms.

</div>### وابستگی‌ها

<div id="bkmrk-use-illuminate%5Csuppo" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- use Illuminate\\Support\\Facades\\DB;
- use Illuminate\\Support\\Facades\\Redis;
- use App\\Helpers\\Functions;
- use Morilog\\Jalali\\Jalalian;

</div>### کدهای خطا

<div id="bkmrk-%DA%A9%D8%AF-%D8%B4%D8%B1%D8%AD-%D9%85%D9%86%D8%A8%D8%B9-400-%D9%BE%D8%A7%D8%B1%D8%A7" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"><table border="1" cellpadding="6" style="width: 90%; margin: 15px auto; text-align: center; border-collapse: collapse;"><tbody><tr style="background: #f9f9f9; font-weight: bold;"><td>کد</td><td>شرح</td><td>منبع</td></tr><tr><td>400</td><td>پارامتر زمانی یا نوع اعلان نادرست است.</td><td>Validator</td></tr><tr><td>403</td><td>دسترسی کافی برای بازمحاسبه وجود ندارد.</td><td>RBAC</td></tr><tr><td>404</td><td>هیچ اعلان فعالی در بازهٔ مورد نظر یافت نشد.</td><td>Query</td></tr><tr><td>500</td><td>خطای داخلی هنگام آپدیت تراز.</td><td>Transaction</td></tr></tbody></table>

</div>### پیشنهادهای امنیتی

<div id="bkmrk-%D8%AB%D8%A8%D8%AA-%D9%85%D9%85%DB%8C%D8%B2%DB%8C-%D8%AA%D9%85%D8%A7%D9%85-%D8%A8%D8%A7%D8%B2%D9%85%D8%AD" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- ثبت ممیزی تمام بازمحاسبات با شناسه اپراتور و IP در `system_logs`.
- محدودسازی نرخ فراخوانی مسیر (Rate Limiter: ۵ در دقیقه).
- قفل همزمانی مبتنی بر Redis برای جلوگیری از محاسبهٔ هم‌زمان چند درخواست یکسان.

</div>### پیشنهادهای بهبود

<div id="bkmrk-%D8%A7%D9%81%D8%B2%D9%88%D8%AF%D9%86-%DA%AF%D8%B2%DB%8C%D9%86%D9%87%D9%94-diff_m" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- افزودن گزینهٔ `diff_mode` برای محاسبه فقط تفاوت داده‌ها.
- ارائه خروجی تحلیلی با تفکیک بر اساس حساب یا کاربر.
- پشتیبانی از زمان‌بندی خودکار (cron-based recalculation) هر ۲۴ ساعت.

</div>### ممیزی و لاگ‌ها

<div id="bkmrk-%D9%86%D9%88%D8%B9-%D9%84%D8%A7%DA%AF%3A-rebuildcalc" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- نوع لاگ: `RebuildCalculation`.
- اقلام ممیزی: تاریخ بازه، شناسه اپراتور، مدت اجرای فرآیند، تعداد ردیف به‌روزشده.
- سطح حساسیت: **Critical Audit**.

</div>### جمع‌بندی

**calculationAnnouncement** مسیر اصلی برای هم‌ترازی اطلاعات مالی و بازسازی تراز سیستم است. این متد هرگونه تغییر در اعلان‌ها را به دادهٔ آماری منطبق تبدیل کرده و همواره موجب سازگاری داده‌های حسابداری کل با ردیف‌های تراکنشی می‌شود. اجرای آن برای پایداری و سلامت کامل ماژول مالی حیاتی است.

<div id="bkmrk-announcement-calculation" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"></div>