#P1499

POST /check/update

Route Info

Method	Endpoint	Controller	Middleware	Purpose
POST	/api/v2/check/update	V2CreditDebitController@updateCheck	authWithJwt	ویرایش و بروزرسانی اطلاعات چک مالی، با اعتبارسنجی مقادیر و بروزرسانی کش مالی سیستم.

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

تابع updateCheck نخست شناسه چک را از ورودی دریافت می‌کند، سپس داده‌های موردنظر برای بروزرسانی را اعتبارسنجی کرده و در جدول pays ثبت می‌کند. این داده‌ها ممکن است شامل اصلاح مبلغ، تاریخ سررسید، شماره پیگیری، وضعیت فعال/مسدود و توضیحات باشند.

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

ورودی‌ها

نام پارامتر	نوع	منبع	الزامی	توضیح
id	integer	Body	بله	شناسه چک مورد نظر برای بروزرسانی.
data	object	Body	بله	داده‌های بروزرسانی شامل `amount`، `status`، `deadline`، `description`.
branch	integer	JWT/Header	بله	شناسه شعبه مالی مرتبط.
operator	object	JWT	بله	اپراتور اجراکننده‌ی عملیات.
reason	string	Body	خیر	توضیح یا علت تغییر برای ثبت در لاگ ممیزی.

خروجی (Response)

{
  "status": true,
  "time": 1732287600,
  "result": {
    "check_id": 145,
    "changes": ["amount", "deadline", "status"],
    "cache": "financial:branch:5:refreshed",
    "message": "اطلاعات چک با موفقیت بروزرسانی شد"
  }
}

نکات امنیتی

احراز هویت JWT الزامی است.
مجوز نقش مالی financial.check.update باید بررسی شود.
ورودی‌ها با Validator سمت سرور تایید می‌شوند تا از تزریق داده و تغییر غیرمجاز جلوگیری گردد.

نکات عملکردی

به‌روزرسانی چک در تراکنش DB::transaction انجام می‌شود تا Atomic باشد.
بازسازی کش Redis محدود به داده‌های تغییر یافته برای جلوگیری از فشار غیرضروری است.
TTL کش‌های چک و شعبه به‌ترتیب 60 و 600 ثانیه تعیین شده‌اند.

وابستگی‌ها

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

کدهای خطا

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

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

ثبت IP و User-Agent اپراتور در ممیزی.
اعمال محدودیت زمانی برای ویرایش چک پس از تسویه.
رمزنگاری شناسه چک در سمت کلاینت.

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

افزودن فیلد updated_by برای نمایش نام کاربر ویرایشگر در گزارش‌ها.
افزودن قابلیت ویرایش گروهی چک‌های انتخاب‌شده.
پشتیبانی از ثبت تاریخچه تغییرات (versioning) برای هر چک.

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

نوع لاگ: UpdateCheck.
فیلدهای ذخیره‌شده: check_id, operator_id, branch, changes, reason.
سطح لاگ: Audit.
نگهداری: ۹۰ روز در جدول audit_logs.

جمع‌بندی

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