# POST /check/operation

<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/check/operation</td><td dir="ltr">V2CreditDebitController@operationCheck</td><td dir="ltr">authWithJwt</td><td dir="rtl">انجام عمل خاص بر روی چک مالی، مانند تغییر وضعیت، تأیید، لغو یا تسویه.</td></tr></tbody></table>

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

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

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

<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>id</td><td>integer</td><td>Body</td><td>بله</td><td>شناسه چک مورد نظر برای انجام عملیات.</td></tr><tr><td>action</td><td>string</td><td>Body</td><td>بله</td><td>نوع عملیات. مقادیر مجاز: `confirm`، `cancel`، `block`، `unblock`، `settle`.</td></tr><tr><td>branch</td><td>integer</td><td>JWT/Header</td><td>بله</td><td>شناسه شعبه مالی.</td></tr><tr><td>operator</td><td>object</td><td>JWT</td><td>بله</td><td>شناسه اپراتور اجرایی.</td></tr><tr><td>reason</td><td>string</td><td>Body</td><td>خیر</td><td>علت تغییر وضعیت (برای لاگ و ممیزی).</td></tr></tbody></table>

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

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

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

<div id="bkmrk-%D9%85%D8%AC%D9%88%D8%B2-%D9%84%D8%A7%D8%B2%D9%85%3A-financial" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- مجوز لازم: `financial.check.edit`.
- فقط کاربران نقش حسابدار ارشد یا مدیر شعبه حق انجام عملیات دارند.
- تمام تغییرات در جدول `audit_logs` ثبت می‌شوند.

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

<div id="bkmrk-%D8%A8%D9%87%E2%80%8C%D8%B1%D9%88%D8%B2%D8%B1%D8%B3%D8%A7%D9%86%DB%8C-%D9%87%D9%85%E2%80%8C%D8%B2%D9%85%D8%A7%D9%86-" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- به‌روزرسانی هم‌زمان کش Redis پس از هر تغییر وضعیت چک.
- استفاده از تراکنش `DB::transaction` برای جلوگیری از ناسازگاری وضعیت چک‌ها.
- TTL کش‌های مرتبط: 300 ثانیه برای داده‌ی شعبه و 30 ثانیه برای داده‌ی چک منفرد.

</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 Carbon\\Carbon;
- use App\\Helpers\\Functions;
- use App\\Models\\Pay;
- use App\\Http\\Controllers\\StaticController;

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

<div id="bkmrk-%DA%A9%D8%AF-%D8%B4%D8%B1%D8%AD-%D8%AE%D8%B7%D8%A7-%D9%85%D9%86%D8%A8%D8%B9-400-" 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>authWithJwt</td></tr><tr><td>404</td><td>چک مورد نظر یافت نشد.</td><td>DB</td></tr><tr><td>500</td><td>خطای داخلی پایگاه داده یا بروزرسانی کش.</td><td>Exception Handler</td></tr></tbody></table>

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

<div id="bkmrk-%D8%A7%D8%B9%D9%85%D8%A7%D9%84-rate%E2%80%91limit-%D8%A8%D8%B1%D8%A7" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- اعمال Rate‑Limit برای عملیات حساس مالی (۱ عمل در هر ۱۰ ثانیه).
- ثبت IP کاربر در ممیزی و ارسال هشدار در تغییر وضعیت غیرعادی.
- رمزنگاری شناسه چک در فرانت‌اند.

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

<div id="bkmrk-%D8%A7%D9%81%D8%B2%D9%88%D8%AF%D9%86-%D8%A7%D9%85%DA%A9%D8%A7%D9%86-%D8%A7%D9%86%D8%AC%D8%A7%D9%85-%D8%B9" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- افزودن امکان انجام عملیات گروهی روی چند چک.
- اضافه کردن فیلد `verified_at` در جدول برای ردیابی دقیق زمان تأیید.
- پشتیبانی از وب‌هوک برای اطلاع‌رسانی تغییر وضعیت به سرویس‌های همکار.

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

<div id="bkmrk-%D9%86%D9%88%D8%B9-%D9%84%D8%A7%DA%AF%3A-operationch" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- نوع لاگ: `OperationCheck`.
- فیلدهای ثبت‌شونده: `check_id, action, operator_id, branch, reason`.
- سطح لاگ: **Audit**.
- مدت نگهداری: ۹۰ روز.

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

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

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