Skip to main content
#P1766

RESOURCE /v2/cartable/letters


Letter & Workflow Logic

ماژول کارتابل دارای یک منطق گردش کار (Workflow) است. زمانی که یک نامه ایجاد می‌شود، سیستم به صورت خودکار اولین مرحله (Step) آن فرآیند را ایجاد می‌کند. همچنین زمانی که وضعیت یک مرحله به "انجام شده" تغییر می‌کند، سیستم به صورت هوشمند مرحله بعدی را تشخیص داده و ایجاد می‌کند.

Create Letter Request
↓
Step 1: Initialization
Generate Serial ID
Insert Letter Record
↓
Step 2: Workflow Trigger
Fetch `cartable_subjects` (Process Config)
Decode `steps` JSON
Insert First Step into `cartable_letter_steps`
↓
Return Letter Resource

Get Letters List

دریافت لیست نامه‌های موجود در کارتابل. این متد از یک سیستم صفحه‌بندی (Pagination) خاص استفاده می‌کند که پارامترهای `length` و `start` را به شماره صفحه لاراول تبدیل می‌کند.

URL: /v2/cartable/letters
Method: GET
Controller: LetterController@index

Query Parameters

Parameter Type Description
paginate[length] Integer (اختیاری) تعداد آیتم در هر صفحه (پیش‌فرض: 30).
paginate[start] Integer (اختیاری) آفست شروع دیتا (برای محاسبه صفحه فعلی).
requester_id Integer (اختیاری) فیلتر بر اساس شناسه درخواست‌کننده.
subject Integer (اختیاری) فیلتر بر اساس شناسه موضوع نامه.
status Integer (اختیاری) فیلتر بر اساس وضعیت کلی نامه.

Response Structure

خروجی توسط LetterResource فرمت‌دهی می‌شود.

{
    "items": [
        {
            "id": 50,
            "serial": "LET-1402-001",
            "subject": { "id": 1, "title": "Leave Request" },
            "requester": { "id": 10, "name": "Ali..." },
            "current_step": { "id": 205, "status": "pending" },
            "created_at": "..."
        }
    ],
    "meta": { "timestamp": 1733754000 }
}

Create Letter

ایجاد یک نامه جدید.
نکته مهم: پس از ایجاد نامه، سیستم به جدول `cartable_subjects` مراجعه کرده و لیست مراحل تعریف شده برای آن موضوع (`subject`) را می‌خواند و به صورت خودکار اولین مرحله را در جدول `cartable_letter_steps` برای این نامه ثبت می‌کند.

URL: /v2/cartable/letters
Method: POST
Controller: LetterController@store

Body Parameters

Parameter Type Description
branch Integer (الزامی) شناسه شعبه (برای تولید شماره سریال).
subject Integer (الزامی) شناسه موضوع نامه (تعیین کننده مراحل گردش کار).
recipient String (اختیاری) گیرنده نامه.
title String (اختیاری) عنوان نامه.
description String (اختیاری) توضیحات نامه.
operators Array[Int] (اختیاری) لیست اپراتورهای دخیل (به صورت JSON ذخیره می‌شود).

Success Response

{
    "payload": {
        "id": 51,
        "serial": "100-2569",
        "subject": 5,
        "steps": [ ... ] // شامل اولین مرحله ایجاد شده
    },
    "meta": { "timestamp": 1733754000 }
}

Show Letter Details

مشاهده جزئیات کامل یک نامه. اگر نامه حذف شده باشد (`deleted_at` داشته باشد) یا وجود نداشته باشد، خطای 404 برمی‌گرداند.

URL: /v2/cartable/letters/{id}
Method: GET
Controller: LetterController@show

Update Letter

ویرایش اطلاعات عمومی نامه (عنوان، گیرنده، توضیحات و...). این متد مراحل گردش کار را تغییر نمی‌دهد.

URL: /v2/cartable/letters/{id}
Method: PUT / PATCH
Controller: LetterController@update

Body Parameters

Parameter Type Description
title String عنوان نامه.
subject Integer تغییر موضوع نامه.
operators Array[Int] لیست اپراتورها.
description String توضیحات.
recipient String گیرنده.

Delete Letter

حذف نرم (Soft Delete) نامه. فیلد deleted_at با زمان فعلی مقداردهی می‌شود.

URL: /v2/cartable/letters/{id}
Method: DELETE
Controller: LetterController@destroy

Update Step & Advance Workflow

توجه: این متد در کنترلر وجود دارد اما روت آن در اسنیپت ارائه شده نیست (احتمالاً روت سفارشی دارد).
این متد برای تغییر وضعیت یک مرحله (Step) استفاده می‌شود.
منطق هوشمند: اگر وضعیت ارسالی برابر با 3 (انجام شده) باشد، سیستم به صورت خودکار مرحله بعدی فرآیند را از تنظیمات موضوع (`subject steps`) پیدا کرده و آن را ایجاد می‌کند.

Method URL: (Custom Route) /v2/cartable/steps/{id}
Target ID: شناسه مرحله (cartable_letter_steps.id)
Controller: LetterController@updateLetterStep

Body Parameters

Parameter Type Description
status Integer (الزامی) وضعیت جدید مرحله (مثلاً 3 برای اتمام).
description String (اختیاری) توضیحات یا دستور انجام کار روی مرحله.
Update Step Request
↓
Update `status` & `description`
↓
Status == 3 ?
YES →
Find Current Step Index
Check for Next Step in Config
Insert Next Step
Back to top