Skip to main content
#P1763

RESOURCE /v2/scrumboard/cards


Card Deep Hydration Logic

کارت‌ها قلب سیستم اسکرام هستند. در تمامی متدها (Index, Store, Show, Update)، پس از دریافت اطلاعات خام کارت، یک فرآیند سنگین برای بارگذاری تمام وابستگی‌ها اجرا می‌شود. این فرآیند شامل دیکد کردن JSONها و کوئری‌های متعدد به جداول مختلف است.

Fetch Card(s) Data
↓
Step 1: JSON Fields
Decode `members` & `labels`
Fetch Operators & Label Objects via IDs
↓
Step 2: Sub-Entities
1. Get Comments (+ Hydrate Operators)
2. Get Checklists (+ Hydrate Operators + Decode Items)
3. Get Attachments (Media table)
4. Get Sprints (JSON Search)
↓
Return Fully Hydrated Card

Get Cards List

دریافت لیست کارت‌های موجود در یک لیست (ستون) خاص. تمامی اطلاعات وابسته (اعضا، لیبل‌ها، پیوست‌ها و...) به همراه کارت برگردانده می‌شوند.

URL: /v2/scrumboard/cards
Method: GET
Controller: CardController@index

Parameters

Parameter Type Location Description
list_id Integer Query (الزامی) شناسه لیست (ستون) والد.
status Integer Query (اختیاری) فیلتر وضعیت کارت.

Response Structure

{
    "items": [
        {
            "id": 101,
            "list_id": 5,
            "title": "Fix Login Bug",
            "description": "User cannot login with email...",
            "members": [
                { "id": 1, "first_name": "Ali", "avatar": "..." }
            ],
            "labels": [
                { "id": 2, "title": "Bug", "color": "#ff0000" }
            ],
            "comments": [ ... ], // لیست کامل نظرات با اطلاعات نویسنده
            "checklists": [ ... ], // لیست چک‌لیست‌ها با آیتم‌ها
            "attachments": [ ... ], // مدیاهای متصل
            "sprints": [ ... ], // اسپرینت‌های مرتبط
            "created_at": "..."
        }
    ],
    "meta": { "timestamp": 1733754000 }
}

Create Card

ایجاد یک کارت جدید ساده. پس از ایجاد، کارت بلافاصله بازیابی شده و ساختار کامل (با آرایه‌های خالی برای وابستگی‌ها) برگردانده می‌شود.

URL: /v2/scrumboard/cards
Method: POST
Controller: CardController@store

Parameters

Parameter Type Description
list_id Integer شناسه لیست مقصد.
title String عنوان کارت.

Success Response

{
    "payload": {
        "id": 102,
        "title": "New Feature",
        "members": [],
        "labels": [],
        "comments": [],
        "checklists": [],
        "attachments": [],
        "sprints": [],
        ...
    },
    "meta": { "timestamp": 1733754000 }
}

Show Card Details

دریافت جزئیات کامل یک کارت با شناسه مشخص.

URL: /v2/scrumboard/cards/{id}
Method: GET
Controller: CardController@show

Response

اگر کارت پیدا نشود، payload: false برمی‌گرداند.

{
    "payload": {
        "id": 101,
        "title": "Fix Login Bug",
        "members": [ ... ],
        "checklists": [
            {
                "id": 5,
                "title": "QA",
                "checkitems": [{ "text": "Test A", "done": true }],
                "operator": { ... }
            }
        ],
        ...
    },
    "meta": { "timestamp": 1733754000 }
}

Update Card & Sub-Resources

این متد علاوه بر آپدیت فیلدهای اصلی کارت، قابلیت مدیریت تو‌در‌توی (Nested Management) برای comments و checklists را نیز دارد. شما می‌توانید همزمان با ویرایش کارت، یک کامنت یا چک‌لیست را ایجاد، ویرایش یا حذف کنید.

URL: /v2/scrumboard/cards/{id}
Method: PUT / PATCH
Controller: CardController@update

Basic Parameters

Parameter Type Description
list_id Integer جابجایی کارت به لیست دیگر.
title String تغییر عنوان.
description String توضیحات تکمیلی.
due_date Date/String تاریخ سررسید.
members Array[Int] لیست جدید شناسه‌های اعضا (جایگزین کل لیست قبلی می‌شود).
labels Array[Int] لیست جدید شناسه‌های لیبل‌ها.
done_at DateTime زمان انجام شدن.
status Integer وضعیت (پیش‌فرض 1).

Advanced Parameters (Nested Actions)

ارسال این پارامترها اختیاری است و برای عملیات سریع روی زیرمجموعه‌ها استفاده می‌شود.

1. مدیریت کامنت (پارامتر comment)

Action Payload Structure
Create { "card_id": 1, "operator_id": 2, "message": "text" }
(بدون ارسال id)
Delete { "id": 10, "delete": true }

2. مدیریت چک‌لیست (پارامتر checklist)

Action Payload Structure
Create { "card_id": 1, "title": "Checklist 1", "checkitems": [...] }
(بدون ارسال id)
Update { "id": 5, "card_id": 1, "title": "New Title", "checkitems": [...] }
Delete { "id": 5, "delete": true }

Success Response

{
    "payload": {
        "id": 101,
        // کارت آپدیت شده به همراه تمام تغییرات اعمال شده در کامنت‌ها/چک‌لیست‌ها
        "comments": [ ... ], 
        "checklists": [ ... ],
        ...
    },
    "meta": { "timestamp": 1733754000 }
}

Delete Card

حذف کارت از دیتابیس. توجه: طبق کد فعلی، وابستگی‌ها (مثل کامنت‌ها) به صورت Cascade در کد PHP حذف نمی‌شوند مگر اینکه در سطح دیتابیس تنظیم شده باشد.

URL: /v2/scrumboard/cards/{id}
Method: DELETE
Controller: CardController@destroy

Success Response

{
    "payload": 1, // 1: موفق، 0: ناموفق
    "meta": { "timestamp": 1733754000 }
}
Back to top