# Function listPledgerCharter ### #### · هدف: این متد برای واکشی لیستی از “متعهدان” (Pledgers) فعال در یک شعبه خاص طراحی شده است. متعهدان در اینجا همکارانی (Colleagues) هستند که به صورت رسمی در جدول `charter_pledgers` ثبت شده‌اند. هدف اصلی، تهیه یک لیست ساده و کارآمد برای استفاده در فرم‌ها و منوهای کشویی است که نیاز به انتخاب یک متعهد دارند. کوئری به طور همزمان به جداول `charter_pledgers` و `colleagues` متصل می‌شود و فقط رکوردهایی را بازمی‌گرداند که هم متعهد و هم خود همکار فعال باشند (`status=1`). خروجی برای استفاده آسان در فرانت‌اند بهینه‌سازی شده و شامل شناسه متعهد، شناسه همکار و یک آبجکت `title` با نسخه‌های فارسی و انگلیسی نام دفتر و نام کامل شخص است.
**ویژگی‌ها****توضیحات**
**هدف کلی**تهیه لیست متعهدان (همکاران) فعال یک شعبه برای استفاده در UI.
**فیلتر وضعیت**واکشی متعهدانی که هم خودشان و هم پروفایل همکارشان فعال است.
**فیلتر شعبه**محدود کردن نتایج به شعبه کاربر درخواست‌دهنده (`$request->get('branch')`).
**بهینه‌سازی خروجی**فرمت‌دهی داده‌ها برای نمایش ساده در لیست‌ها (شامل `id` و `title`).
**تجمیع نام**ایجاد عنوان فارسی و انگلیسی با ترکیب نام دفتر و نام و نام خانوادگی.
--- #### · ورودی‌ها (پارامتر‌ها):
**توضیحات****موقعیت****نوع داده****نام پارمتر**
**شناسه شعبه کاربر که به صورت خودکار به درخواست اضافه می‌شود.****`Token/Middleware`****`integer`****`$request->get('branch')`**
--- #### · خروجی (Return):
**توضیحات****نوع داده**
**یک آبجکت `JSON` با کلید `items` (آرایه‌ای از آبجکت‌های متعهد) و `meta`. هر آبجکت متعهد شامل `id`, `colleague_id` و آبجکت `title` است.****`Illuminate\Http\JsonResponse`**
**در صورت بروز خطا، یک پاسخ با کد `400 Bad Request` و جزئیات استثناء.****`Illuminate\Http\JsonResponse`**
--- #### · مثال استفاده / سناریو: **سناریو: یک کاربر از شعبه ۲ درخواست لیست متعهدان را می‌کند** - **Request URL:** `/api/panel/v2/charter/pledger/list` (با توکن کاربری از شعبه ۲) - **Action:** 1. یک کوئری `JOIN` بین `charter_pledgers` و `colleagues` اجرا می‌شود. 2. شرایط `WHERE charter_pledgers.branch = 2`, `charter_pledgers.status = 1` و `colleagues.status = 1` اعمال می‌شوند. 3. نتایج واکشی شده و برای هر رکورد، یک آبجکت با ساختار مشخص (`id`, `colleague_id`, `title`) ایجاد می‌شود. - **Response:** - `HTTP Status`: `200 OK` - `Body`:
json
``` { "items": [ { "id": 5, "colleague_id": 48, "title": { "fa": "آژانس پرواز طلایی احمد محمدی", "en": "Golden Flight Agency Ahmad Mohammadi" } } ], "meta": { "timestamp": ... } } ```