Skip to main content
#P1497

POST /check/store

Route Info

Method Endpoint Controller Middleware Purpose
POST /api/v2/check/store V2CreditDebitController@storeCheck authWithJwt ثبت گروهی چک‌های مالی در جدول پرداخت‌ها و بروزرسانی کش مالی شعبه.

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

تابع storeCheck داده‌های ارسالی مربوط به چک‌های مالی را از بدنه درخواست دریافت می‌کند و پس از بررسی نوع پرداخت (پرداخت یا دریافت)، آن‌ها را در جدول pays درج می‌کند.

شناسه سریال هر چک از طریق تابع StaticController::getSerialId('pay', branch, year) تعیین می‌شود. بعد از ثبت درون تراکنش DB::transaction، کش اطلاعات مالی در Redis بروزرسانی می‌شود تا تغییرات لحظه‌ای اعمال شوند.

ورودی‌ها

نام پارامتر نوع منبع الزامی توضیح
data array Body بله آرایه‌ای از چک‌ها جهت ثبت تکی یا گروهی.
branch integer JWT/Header بله شناسه شعبه ثبت‌کننده.
operator object JWT بله شناسه کاربر ثبت‌کننده چک‌ها.
object_type string Body بله نوع هدف چک (reference, aggregation, colleague).
object integer Body بله شناسه منبع مالی یا فاکتور مربوط.

خروجی (Response)

{
  "status": true,
  "time": 1732287600,
  "result": {
    "inserted": 5,
    "tracking_ids": ["CHK-88421", "CHK-88422", "CHK-88423"],
    "cached": "financial:branch:5:synced"
  }
}

نکات امنیتی

  • احراز هویت JWT اجباری است.
  • فقط نقش‌های دارای سطح financial.check.store مجاز به درج هستند.
  • بررسی موجودی حساب قبل از درج تراکنش‌ها انجام می‌شود (Wallet Check).

نکات عملکردی

  • ثبت چک‌ها درون DB::transaction باعث حفظ یکپارچگی داده‌های مالی می‌شود.
  • در پایان درج، داده‌های مرتبط در Redis با کلید reference:{object}:information بروزرسانی می‌شوند.
  • می‌توان در نسخه آینده cache invalidation هوشمند بر اساس year financial افزود.

وابستگی‌ها

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

کدهای خطا

کد شرح خطا منبع
400 داده‌های چک ناقص یا نامعتبر. Validator
403 دسترسی مجاز برای ثبت چک وجود ندارد. authWithJwt
500 خطا در درج داده‌ها یا بروزرسانی کش Redis. DB Layer / Redis

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

  • رمزنگاری شناسه چک و شماره حساب در فرانت‌اند.
  • اعمال محدودیت ۵ درخواست در دقیقه برای هر کاربر.
  • بررسی Anti‑Replay برای درخواست‌های تکراری با همان Tracking Code.

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

  • افزودن فیلد wallet_effect:true برای بروزرسانی بلادرنگ کیف پول.
  • پشتیبانی از درج async جهت کاهش latency.
  • اتصال به سرویس گزارش مالی مرکزی جهت اعتبارسنجی چک‌ها قبل از ثبت.

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

  • نوع لاگ: StoreCheck.
  • ثبت فیلدها: operator_id, branch, count_inserted.
  • سطح لاگ: Notice.
  • مدت نگهداری: ۳۰ روز در جدول audit_logs.

جمع‌بندی

تابع storeCheck مسئول ثبت تراکنش‌های مالی نوع چک است و پس از درج در پایگاه داده، تمام کش‌های مالی مرتبط با شعبه یا منبع هدف را بروزرسانی می‌کند. طراحی تابع به‌صورت اتمیک، امن و مناسب عملیات گروهی چک‌ها پیاده شده است.

Back to top