Skip to main content
#P1709

GET /v2/modules/lottery/registrations

Module: Lottery Registrations List

این اندپوینت برای دریافت لیست ثبت‌نام‌کنندگان در ماژول قرعه‌کشی (Lottery) استفاده می‌شود.
این سرویس لیست فاکتورهایی را برمی‌گرداند که شامل آیتم خدمات با شناسه خاص (۱۷) هستند و محاسبات مالی سنگینی (سود، زیان، تراز دریافتی و پرداختی) برای هر ردیف انجام می‌دهد.

Request Overview

URL: /v2/modules/lottery/registrations
Method: GET
Controller: ModuleController@lotteryRegistrations
Middleware Stack: authWithJwt

Access Control

  • دسترسی معتبر JWT.
  • دسترسی به `branch` ارسال شده.

Query Parameters

توجه: پارامترها به صورت آرایه `json` و پارامتر مجزای `branch` ارسال می‌شوند.

Field Type Description
branch integer (الزامی - سطح بالا) شناسه شعبه مورد نظر.
json[length] integer تعداد رکورد در هر صفحه (Pagination Limit).
json[start] integer آفست شروع (Pagination Offset).
json[draw] integer شمارنده درخواست (جهت هماهنگی DataTables).
json[advanced][r] integer (اختیاری) فیلتر جستجو بر اساس شماره سریال فاکتور (سیستم به طور خودکار ۱۰,۰۰۰ واحد برای تطبیق با دیتابیس از آن کم می‌کند).

Logic Details

فرآیند تولید گزارش به شرح زیر است:

  1. تنظیم صفحه‌بندی: منطق صفحه‌بندی لاراول (`paginate`) با محاسبه `currentPage` بر اساس `start` و `length` تنظیم می‌شود.
  2. فیلترینگ سخت‌گیرانه (Hardcoded):
    • factors.operator = 1: فقط فاکتورهای مربوط به اپراتور با شناسه ۱ (احتمالاً سیستم یا ادمین اصلی).
    • factor_items.details->id = 17: شناسه ۱۷ در JSON جزئیات، نشان‌دهنده سرویس "قرعه‌کشی" است.
    • product = 'service': نوع آیتم باید خدمت باشد.
    • وضعیت فاکتور نباید ۲ (ابطال) یا ۵ (احتمالاً پیش‌نویس حذف شده) باشد.
  3. محاسبات مالی (Financial Analysis): برای هر رکورد یافت شده، تابع استاتیک TradeController::financial فراخوانی می‌شود. این تابع موارد زیر را محاسبه می‌کند:
    • مبالغ کل: جمع خرید، فروش، مرجوعی و جریمه‌ها.
    • اسناد مالی: بررسی جدول `pays` برای دریافت‌ها، پرداخت‌ها و اسناد تجمیعی (Aggregation).
    • تراز (Balance): محاسبه مانده بدهکاری/بستانکاری مسافر (`BalanceReceived`) و تامین‌کننده (`BalancePaid`).
    • سود (Profit): محاسبه دقیق سود با کسر تخفیفات و کارمزدها.

Response Structure

پاسخ موفق

  • Status Code: 200 OK
  • Body: شامل آرایه `data` با کلیدهای `snake_case` (به دلیل تنظیمات کنترلر).
{
  "status": true,
  "time": 1715000000,
  "draw": 1,
  "recordsTotal": 50,
  "data": [
    {
      "id": 101,                  // شناسه آیتم فاکتور
      "system_id": 5050,          // شناسه فاکتور
      "serial": 1001,             // سریال خام دیتابیس
      "details": {                // جزئیات سرویس قرعه‌کشی
        "id": 17,
        "name": "Lottery Name"
      },
      "customer_id": 200,
      "sale": 5000000,
      "discount": false,          // یا آبجکت تخفیف
      "status": 1,
      "description": "توضیحات فاکتور",
      "financial": {              // خروجی تابع Financial با فرمت snake_case
        "operator": {
          "title": "Admin User",
          "id": 1
        },
        "leader": {
          "id": 200,
          "title_fa": "علی محمدی",
          "mobile": "0912..."
        },
        "financial": {
          "sum_passenger": 1,
          "sum_buy": 4000000,
          "sum_sale": 5000000,
          "sum_receive": 5000000,
          "balance_received": 0,  // تراز مالی مسافر (0 یعنی تسویه)
          "balance_paid": -4000000, // تراز مالی تامین کننده
          "profit": 1000000,      // سود خالص
          "percent_profit": 25
        },
        "suppliers": { ... },     // لیست تامین‌کنندگان
        "serial_id": 11001        // سریال نمایشی (10000 + serial)
      }
    }
  ]
}

Flowchart

Start
↓
Prepare Query
Join `factors` & `factor_items`
Filter: Branch, Operator=1, ItemID=17
↓
Search Param (r)?
Yes
No
Filter Serial = (r - 10,000)
No Filter
↓
Execute Pagination
↓
Loop through Results
↓
Calculate Financials
(TradeController::financial)
Calc Sums, Balances, Profit
↓
Fetch Discount Info
↓
Return JSON Response
Back to top