#P1769

RESOURCE /v2/cartable/recipients

Department Recipients Management Logic

این کنترلر وظیفه مدیریت لیست "گیرندگان" (`recipients`) را در سطح دپارتمان‌ها بر عهده دارد.
این جدول (`cartable_department_recipients`) عناوین شغلی یا واحدهایی را نگهداری می‌کند که در یک شعبه و دپارتمان خاص مجاز به دریافت نامه هستند (مانند: "دبیرخانه"، "مدیریت مالی" و ...).

Define Recipient Title

↓

Link to Branch & Department
(e.g. Branch: 100, Dept: 5, Title: "Secretariat")

↓

Saved in `cartable_department_recipients`

List Recipients

دریافت لیست تمام گیرندگان تعریف شده. این لیست بر اساس تاریخ ایجاد (نزولی) مرتب شده است.

URL: /v2/cartable/recipients

Method: GET

Controller: RecipientController@index

Query Parameters

Parameter	Type	Description
department	Integer	(اختیاری) فیلتر بر اساس شناسه دپارتمان.
status	Integer	(اختیاری) فیلتر بر اساس وضعیت فعال/غیرفعال بودن (در صورتی که در دیتابیس این فیلد پر شده باشد).

Response Structure

{
    "items": [
        {
            "id": 10,
            "department": 5,
            "branch": 101,
            "title": "دبیرخانه مرکزی",
            "created_at": "...",
            "updated_at": "..."
        }
    ],
    "meta": { "timestamp": 1733762000 }
}

Create Recipient

تعریف یک گیرنده جدید برای یک شعبه و دپارتمان خاص.

URL: /v2/cartable/recipients

Method: POST

Controller: RecipientController@store

Body Parameters

Parameter	Type	Description
department	Integer	(الزامی) شناسه دپارتمان مربوطه.
branch	Integer	(الزامی) شناسه شعبه.
title	String	(الزامی) عنوان گیرنده (مثلاً: "حسابداری").

Success Response

{
    "payload": {
        "id": 12,
        "department": 5,
        "branch": 101,
        "title": "حسابداری",
        "created_at": "...",
        "updated_at": "..."
    },
    "meta": { "timestamp": 1733762000 }
}

Show Recipient Details

مشاهده جزئیات یک گیرنده خاص.

URL: /v2/cartable/recipients/{id}

Method: GET

Controller: RecipientController@show

Response Structure

{
    "payload": {
        "id": 12,
        "department": 5,
        "branch": 101,
        "title": "حسابداری",
        "created_at": "...",
        "updated_at": "..."
    },
    "meta": { "timestamp": 1733762000 }
}

Update Recipient

ویرایش اطلاعات گیرنده.
نکته مهم: طبق منطق کد، فیلد `branch` در متد Update قابل تغییر نیست و فقط `department` و `title` بروزرسانی می‌شوند.

URL: /v2/cartable/recipients/{id}

Method: PUT / PATCH

Controller: RecipientController@update

Body Parameters

Parameter	Type	Description
department	Integer	شناسه دپارتمان جدید.
title	String	عنوان جدید.

Success Response

{
    "payload": {
        "id": 12,
        "department": 6, // Changed
        "branch": 101,
        "title": "حسابداری ارشد", // Changed
        "created_at": "...",
        "updated_at": "..."
    },
    "meta": { "timestamp": 1733762000 }
}

Delete Recipient

حذف فیزیکی (Hard Delete) یک گیرنده از سیستم.

URL: /v2/cartable/recipients/{id}

Method: DELETE

Controller: RecipientController@destroy

Success Response

{
    "payload": 1, // تعداد رکوردهای حذف شده
    "meta": { "timestamp": 1733762000 }
}