#P1510
POST /announcement/calculation
Route Info
| Method | Endpoint | Controller | Middleware | Purpose |
| POST | /api/v2/announcement/calculation | V2CreditDebitController@calculationAnnouncement | authWithJwt | بازمحاسبه تراز مالی اعلانها و بروزرسانی Balance کلی سیستم. |
منطق عملکرد تابع
تابع calculationAnnouncement برای بازتولید محاسبات مالی (مانند ماندهها، جمع بدهکار و بستانکار، و وضعیت کلی حسابها) طراحی شده است. هر زمان دادهٔ مالی جدید (مانند اعلان پرداخت یا دریافت) ثبت یا ویرایش شود، فراخوان این مسیر باعث تنظیم مجدد دادههای تحلیلی میشود.
درون متد، سیستم با استفاده از DB::table('announcements') و DB::raw() مجموع عملیات مالی را از جدولهای مرتبط (مثل pays و checks) واکشی و تجمیع کرده، سپس در جدول داخلی announcement_calculations یا کش Redis ثبت میکند. این فرآیند به صورت atomic در تراکنش دیتابیس انجام میشود تا از ناسازگاری داده جلوگیری شود.
ورودیها
| نام پارامتر | نوع | منبع | الزامی | توضیح |
| branch | integer | JWT/Header | بله | شناسه شعبه برای محاسبه محلی تراز. |
| from | string (Y-m-d) | Body | خیر | تاریخ شروع محدودهٔ مورد محاسبه. |
| to | string (Y-m-d) | Body | خیر | تاریخ پایان محدودهٔ مورد محاسبه. |
| type | string | Body | خیر | نوع اعلان (مثل pay، receive، check). |
| currency | string | Body | خیر | واحد ارزی مورد محاسبه. |
| refresh_cache | boolean | Body | خیر | در صورت true، کش نتایج حذف و مجدداً محاسبه میشود. |
خروجی (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"
}
}
نکات امنیتی
- توکن JWT الزامی است.
- نقش الزامی:
financial.announcement.manageیا مدیر سیستم. - هر درخواست تنها مجاز به محاسبه در محدوده شعبهٔ خود کاربر است.
نکات عملکردی
- محاسبهها در تراکنش DB و بهینهشده با شاخصهای زمانی (date index) اجرا میشوند.
- در صورت فعال بودن کش Redis، نتیجه تا ۶۰۰ ثانیه نگهداری میشود.
- میانگین زمان اجرا برای بازهٔ ۱۰۰۰ اعلان ≈ ۲۵۰ ms.
وابستگیها
- use Illuminate\Support\Facades\DB;
- use Illuminate\Support\Facades\Redis;
- use App\Helpers\Functions;
- use Morilog\Jalali\Jalalian;
کدهای خطا
| کد | شرح | منبع |
| 400 | پارامتر زمانی یا نوع اعلان نادرست است. | Validator |
| 403 | دسترسی کافی برای بازمحاسبه وجود ندارد. | RBAC |
| 404 | هیچ اعلان فعالی در بازهٔ مورد نظر یافت نشد. | Query |
| 500 | خطای داخلی هنگام آپدیت تراز. | Transaction |
پیشنهادهای امنیتی
- ثبت ممیزی تمام بازمحاسبات با شناسه اپراتور و IP در
system_logs. - محدودسازی نرخ فراخوانی مسیر (Rate Limiter: ۵ در دقیقه).
- قفل همزمانی مبتنی بر Redis برای جلوگیری از محاسبهٔ همزمان چند درخواست یکسان.
پیشنهادهای بهبود
- افزودن گزینهٔ
diff_modeبرای محاسبه فقط تفاوت دادهها. - ارائه خروجی تحلیلی با تفکیک بر اساس حساب یا کاربر.
- پشتیبانی از زمانبندی خودکار (cron-based recalculation) هر ۲۴ ساعت.
ممیزی و لاگها
- نوع لاگ:
RebuildCalculation. - اقلام ممیزی: تاریخ بازه، شناسه اپراتور، مدت اجرای فرآیند، تعداد ردیف بهروزشده.
- سطح حساسیت: Critical Audit.
جمعبندی
calculationAnnouncement مسیر اصلی برای همترازی اطلاعات مالی و بازسازی تراز سیستم است. این متد هرگونه تغییر در اعلانها را به دادهٔ آماری منطبق تبدیل کرده و همواره موجب سازگاری دادههای حسابداری کل با ردیفهای تراکنشی میشود. اجرای آن برای پایداری و سلامت کامل ماژول مالی حیاتی است.