Skip to main content
#P1498

POST /check/operation

Route Info

Method Endpoint Controller Middleware Purpose
POST /api/v2/check/operation V2CreditDebitController@operationCheck authWithJwt انجام عمل خاص بر روی چک مالی، مانند تغییر وضعیت، تأیید، لغو یا تسویه.

منطق عملکرد تابع

تابع operationCheck عمل انتخاب‌شده را روی چک مشخص‌شده اجرا می‌کند. بسته به نوع ورودی (`action`) مقدار ستون‌های status، payment_state یا tracking_code در جدول pays بروزرسانی می‌شوند.

پس از موفقیت عملیات، کش Redis مربوط به چک و اطلاعات مالی شعبه با کلید‌های financial:branch:{branch} و check:{id}:information بروزرسانی یا حذف می‌شوند تا اطلاعات جدید منعکس گردد.

ورودی‌ها

نام پارامتر نوع منبع الزامی توضیح
id integer Body بله شناسه چک مورد نظر برای انجام عملیات.
action string Body بله نوع عملیات. مقادیر مجاز: confirm، cancel، block، unblock، settle.
branch integer JWT/Header بله شناسه شعبه مالی.
operator object JWT بله شناسه اپراتور اجرایی.
reason string Body خیر علت تغییر وضعیت (برای لاگ و ممیزی).

خروجی (Response)

{
  "status": true,
  "time": 1732287600,
  "result": {
    "check_id": 109,
    "action": "confirm",
    "verified_by": 2704,
    "financial_cache": "redis:branch:5:updated",
    "message": "وضعیت چک با موفقیت بروزرسانی شد"
  }
}

نکات امنیتی

  • مجوز لازم: financial.check.edit.
  • فقط کاربران نقش حسابدار ارشد یا مدیر شعبه حق انجام عملیات دارند.
  • تمام تغییرات در جدول audit_logs ثبت می‌شوند.

نکات عملکردی

  • به‌روزرسانی هم‌زمان کش Redis پس از هر تغییر وضعیت چک.
  • استفاده از تراکنش DB::transaction برای جلوگیری از ناسازگاری وضعیت چک‌ها.
  • TTL کش‌های مرتبط: 300 ثانیه برای داده‌ی شعبه و 30 ثانیه برای داده‌ی چک منفرد.

وابستگی‌ها

  • use Illuminate\Support\Facades\DB;
  • use Illuminate\Support\Facades\Redis;
  • use Carbon\Carbon;
  • use App\Helpers\Functions;
  • use App\Models\Pay;
  • use App\Http\Controllers\StaticController;

کدهای خطا

کد شرح خطا منبع
400 پارامترها ناقص یا نوع عملیات نامعتبر است. Validator
403 کاربر مجاز به انجام این عملیات نیست. authWithJwt
404 چک مورد نظر یافت نشد. DB
500 خطای داخلی پایگاه داده یا بروزرسانی کش. Exception Handler

پیشنهادهای امنیتی

  • اعمال Rate‑Limit برای عملیات حساس مالی (۱ عمل در هر ۱۰ ثانیه).
  • ثبت IP کاربر در ممیزی و ارسال هشدار در تغییر وضعیت غیرعادی.
  • رمزنگاری شناسه چک در فرانت‌اند.

پیشنهادهای بهبود

  • افزودن امکان انجام عملیات گروهی روی چند چک.
  • اضافه کردن فیلد verified_at در جدول برای ردیابی دقیق زمان تأیید.
  • پشتیبانی از وب‌هوک برای اطلاع‌رسانی تغییر وضعیت به سرویس‌های همکار.

ممیزی و لاگ‌ها

  • نوع لاگ: OperationCheck.
  • فیلدهای ثبت‌شونده: check_id, action, operator_id, branch, reason.
  • سطح لاگ: Audit.
  • مدت نگهداری: ۹۰ روز.

جمع‌بندی

تابع operationCheck مسئول تغییر وضعیت چک‌های مالی در سیستم است و ضمن رعایت کنترل دسترسی، بروزرسانی ایمن داده‌ها و کش Redis را انجام می‌دهد. این مسیر یکی از نقاط حساس چرخه مالی محسوب می‌شود و برای تضمین صحت داده باید تحت لاگ کامل و ممیزی نگهداری شود.

Back to top