Skip to main content
#P1688

GET /v2/charter/pledger

Charter: List Branch Pledgers

این اندپوینت لیست ضامنین (Pledgers) یک شعبه را از جدول charter_pledgers به همراه اطلاعات همکار (colleague) بازیابی می‌کند. داده‌ها با join روی جدول colleagues enrich شده و خروجی نهایی یک آرایه items با ساختار title.fa و title.en بازمی‌گرداند.

Request Overview

URL: /v2/charter/pledger
Method: GET
Controller: CharterController@listPledgerCharter
Middleware: authWithJwt

Query Parameters

Parameter Type Required Description
branch integer yes شناسه شعبه‌ای که باید لیست ضامنین آن واکشی شود

Database Tables

Table: charter_pledgers

Column Type Description
id integer شناسه ضامن
colleague_id integer شناسه همکار ضامن
branch integer شناسه شعبه
status tinyint 1=فعال، 0=غیرفعال

Table: colleagues

Column Type Description
id integer شناسه همکار
first_name string نام
last_name string نام خانوادگی
office string نام دفتر به فارسی
office_en string نام دفتر به انگلیسی
status tinyint باید 1 باشد تا همکار معتبر محسوب شود

Core Processing Logic

$pledgers = DB::table('charter_pledgers')
    ->select(
        'charter_pledgers.id',
        'colleagues.id as colleague_id',
        'colleagues.first_name',
        'colleagues.last_name',
        'colleagues.office',
        'colleagues.office_en',
        'colleagues.status'
    )
    ->where('charter_pledgers.branch', $request->get('branch'))
    ->where('charter_pledgers.status', 1)
    ->where('colleagues.status', 1)
    ->leftJoin('colleagues', 'charter_pledgers.colleague_id', 'colleagues.id')
    ->orderBy('charter_pledgers.id', 'DESC')
    ->get();
  • فقط ضامنین فعال branch مدنظر انتخاب می‌شوند
  • leftJoin تضمین می‌کند اگر colleague حذف شده باشد، رکورد pledger حذف نشود (اما فیلتر status=1 جلوی آن را می‌گیرد)
  • مرتب‌سازی DESC بر اساس آخرین ضامن‌های ثبت‌شده انجام می‌شود

Output Mapping Logic

$return = $pledgers->map(function ($pledger) {
    return [
        'id' => $pledger->id,
        'colleague_id' => $pledger->colleague_id,
        'title' => [
            'fa' => $pledger->office .
                   ($pledger->last_name != '' 
                     ? ' ' . $pledger->first_name . ' ' . $pledger->last_name 
                     : ""),
            'en' => $pledger->office_en
        ]
    ];
});

ساختار title.fa مطابق الگوی زیر ساخته می‌شود:

Field Example Description
office آژانس هرمس نام دفتر
first_name علی نام همکار (در صورت وجود)
last_name کاظمی نام خانوادگی همکار (در صورت وجود)
Final Output Example → آژانس هرمس علی کاظمی

Response (Success)

{
  "items": [
    {
      "id": 18,
      "colleague_id": 92,
      "title": {
        "fa": "آژانس هرمس علی کاظمی",
        "en": "Hermes Agency"
      }
    }
  ],
  "meta": { "timestamp": 1710000000 }
}

Response (Error)

{
  "message": "SQLSTATE[HY000]: ...",
  "trace": [...]
}

Flowchart

Validate JWT
↓
Read Query Param: branch
↓
DB Query charter_pledgers WHERE branch, status=1
↓
LEFT JOIN colleagues ON colleague_id
↓
Filter colleagues.status=1
↓
ORDER BY id DESC
↓
Map → Build title.fa / title.en
↓
Return JSON: items[], meta.timestamp
Back to top