# POST /check/list

<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/list</td><td dir="ltr">V2CreditDebitController@listCheck</td><td dir="ltr">authWithJwt</td><td dir="rtl">دریافت لیست چک‌های مالی ثبت‌شده برای شرکت یا شعبه، با فیلتر و مرتب‌سازی پیشرفته DataTables.</td></tr></tbody></table>

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

تابع **listCheck** از روی پارامترهای DataTables (مثل draw، start، length و فیلترهای پیشرفته) لیست چک‌ها را از جدول `announcements` یا `pays` واکشی می‌کند. این چک‌ها ممکن است متعلق به پرداخت یا دریافت در سیستم مالی باشند.

در صورت وجود داده کش‌شده، نتیجه از Redis با کلید `check:list:{branch}` خوانده می‌شود. اگر کش خالی بود، داده‌ها با فیلتر وضعیت (`status`)، تاریخ (`date\_from`, `date\_to`) و نوع چک (`payment` یا `receive`) واکشی می‌شوند و سپس در JSON نهایی با متادیتا و شمارنده رکوردها بازگردانده می‌شود.

<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>draw</td><td>integer</td><td>Body</td><td>بله</td><td>شناسه درخواست DataTables.</td></tr><tr><td>start</td><td>integer</td><td>Body</td><td>بله</td><td>موقعیت شروع رکورد.</td></tr><tr><td>length</td><td>integer</td><td>Body</td><td>بله</td><td>تعداد رکوردهای هر صفحه.</td></tr><tr><td>advanced</td><td>object</td><td>Body</td><td>خیر</td><td>فیلترهای پیشرفته شامل status، type، company، date\_from و date\_to.</td></tr><tr><td>branch</td><td>integer</td><td>JWT/Header</td><td>بله</td><td>شناسه شعبه فعلی برای تفکیک داده‌ها.</td></tr></tbody></table>

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

```
{
  "meta": { "timestamp": 1732287600, "draw": 1 },
  "data": [
    {
      "id": 107,
      "serial_id": 10087,
      "status": "active",
      "title": "چک پرداختی شرکت آلفا",
      "company": {
        "id": 504,
        "title": "آلفا سیستم"
      },
      "amount": 18500000,
      "currency": "IRR",
      "deadline": "1404/09/15",
      "type": "payment",
      "tracking_code": "CHK-984723",
      "created_at": "1404/08/30"
    }
  ],
  "recordsTotal": 27,
  "recordsFiltered": 27
}
```

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

<div id="bkmrk-%D8%AF%D8%B3%D8%AA%D8%B1%D8%B3%DB%8C-%D9%81%D9%82%D8%B7-%D8%A8%D8%B1%D8%A7%DB%8C-%D9%86%D9%82%D8%B4%E2%80%8C" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- دسترسی فقط برای نقش‌های دارای مجوز `financial.check.view`.
- درخواست‌ها باید دارای توکن JWT معتبر باشند.
- فیلترهای زمان باید اعتبارسنجی شوند تا از injection جلوگیری شود.

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

<div id="bkmrk-%D8%A7%D9%88%D9%84%D9%88%DB%8C%D8%AA-%D9%88%D8%A7%DA%A9%D8%B4%DB%8C-%D8%A7%D8%B2-redi" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- اولویت واکشی از Redis با TTL=900s.
- Queryهای دارای ایندکس روی فیلدهای `status`, `deadline`, `branch`.
- در صورت حجم بالا، مجموعه چک‌ها به‌صورت batch تقسیم می‌شوند.

</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\\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>500</td><td>خطا در Query یا کش Redis.</td><td>DB Layer</td></tr></tbody></table>

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

<div id="bkmrk-%D8%B1%D9%85%D8%B2%D9%86%DA%AF%D8%A7%D8%B1%DB%8C-%D8%B4%D9%86%D8%A7%D8%B3%D9%87-%DA%86%DA%A9-%D8%AF%D8%B1" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- رمزنگاری شناسه چک در فرانت‌اند قبل از ارسال.
- اعمال Rate Limit ۵ req/min برای جلوگیری از enumeration.
- استفاده از HTTPS و بررسی timestamp پاسخ برای جلوگیری از replay.

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

<div id="bkmrk-%D8%A7%D9%81%D8%B2%D9%88%D8%AF%D9%86-%D9%81%DB%8C%D9%84%D8%AA%D8%B1-%D8%A8%D8%B1%D8%A7%DB%8C-%D9%86%D9%85" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- افزودن فیلتر برای نمایش «چک‌های منقضی».
- پشتیبانی از export به Excel و PDF.
- افزودن گزینه search روی گیرنده یا شماره چک.

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

<div id="bkmrk-%D9%86%D9%88%D8%B9-%D9%84%D8%A7%DA%AF%3A-listcheck.-" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- نوع لاگ: `ListCheck`.
- فیلدهای ذخیره‌شده: `operator_id, branch, filters_applied`.
- سطح لاگ: **Info**.
- مدت نگهداری در جدول `audit_logs`: ۳۰ روز.

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

تابع **listCheck** لیست چک‌های مالی را با کش Redis، کنترل دسترسی مبتنی بر نقش، و فیلترهای DataTables ارائه می‌دهد. طراحی آن به گونه‌ای انجام شده که برای گزارش‌گیری بلادرنگ از حساب‌های پرداختی و دریافتی مناسب باشد.

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