Skip to main content
#P1496

POST /check/list

Route Info

Method Endpoint Controller Middleware Purpose
POST /api/v2/check/list V2CreditDebitController@listCheck authWithJwt دریافت لیست چک‌های مالی ثبت‌شده برای شرکت یا شعبه، با فیلتر و مرتب‌سازی پیشرفته DataTables.

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

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

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

ورودی‌ها

نام پارامتر نوع منبع الزامی توضیح
draw integer Body بله شناسه درخواست DataTables.
start integer Body بله موقعیت شروع رکورد.
length integer Body بله تعداد رکوردهای هر صفحه.
advanced object Body خیر فیلترهای پیشرفته شامل status، type، company، date_from و date_to.
branch integer JWT/Header بله شناسه شعبه فعلی برای تفکیک داده‌ها.

خروجی (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
}

نکات امنیتی

  • دسترسی فقط برای نقش‌های دارای مجوز financial.check.view.
  • درخواست‌ها باید دارای توکن JWT معتبر باشند.
  • فیلترهای زمان باید اعتبارسنجی شوند تا از injection جلوگیری شود.

نکات عملکردی

  • اولویت واکشی از Redis با TTL=900s.
  • Queryهای دارای ایندکس روی فیلدهای status, deadline, branch.
  • در صورت حجم بالا، مجموعه چک‌ها به‌صورت batch تقسیم می‌شوند.

وابستگی‌ها

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

کدهای خطا

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

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

  • رمزنگاری شناسه چک در فرانت‌اند قبل از ارسال.
  • اعمال Rate Limit ۵ req/min برای جلوگیری از enumeration.
  • استفاده از HTTPS و بررسی timestamp پاسخ برای جلوگیری از replay.

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

  • افزودن فیلتر برای نمایش «چک‌های منقضی».
  • پشتیبانی از export به Excel و PDF.
  • افزودن گزینه search روی گیرنده یا شماره چک.

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

  • نوع لاگ: ListCheck.
  • فیلدهای ذخیره‌شده: operator_id, branch, filters_applied.
  • سطح لاگ: Info.
  • مدت نگهداری در جدول audit_logs: ۳۰ روز.

جمع‌بندی

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

Back to top