#P1758

RESOURCE /v2/scrumboard/boards

List Scrum Boards

این اندپوینت لیست بوردهای اسکرام را بازیابی می‌کند. نتایج شامل بوردهایی است که کاربر جاری یا سازنده (Owner) آن‌هاست و یا به عنوان عضو (Member) دربه آن‌ها دعوت شده است.

Request Overview

URL: /v2/scrumboard/boards

Method: GET

Controller: BoardController@index

Middleware: authWithJwt

Parameters

Parameter	Type	Location	Description
branch	Integer	Query	شناسه شعبه (الزامی برای فیلتر اولیه).
status	Integer	Query	(اختیاری) فیلتر بر اساس وضعیت فعال/غیرفعال.

Logic Details

سیستم پردازش‌های زیر را هنگام دریافت لیست انجام می‌دهد:

فیلتر دسترسی: تنها بوردهایی بازگردانده می‌شوند که operator_id برابر با کاربر جاری باشد یا شناسه کاربر در آرایه JSON ستون members وجود داشته باشد.
Hydration (تزریق داده‌ها):
- فیلد members ~~که در دیتابیس~~ (آرایه‌ای از ~~IDهاست،~~IDها) با ~~اطلاعات~~آبجکت کامل اطلاعات اپراتورها (نام، آواتار و...) جایگزین می‌شود.
- لیست‌های بورد (Lists) ~~از جدول~~ scrumboard_lists ~~دریافت~~ و ~~اضافه می‌شوند.~~
- لیبل‌~~های بورد~~ها (Labels) از ~~جدول~~جداول scrumboard_labelsمربوطه دریافت و به پاسخ اضافه می‌شوند.

Success Response Structure

نمونه پاسخ موفق

{
    "items": [
        {
            "id": 10,
            "title": "پروژه توسعه",
            "operator_id": 55,
            "members": [
                { "id": 60, "first_name": "Ali", "last_name": "Rezaei", "avatar": "..." }
            ],
            "lists": [
                { "id": 1, "title": "درحال انجام", "priority": 2 }
            ],
            "labels": [
                { "id": 5, "title": "فوری" }
            ]
        }
    ],
    "meta": { "timestamp": 1733754000 }
}

Create Scrum Board

این اندپوینت یک بورد اسکرام جدید ایجاد می‌کند. نکته مهم در این متد، ایجاد خودکار لیست‌ها و لیبل‌های پیش‌فرض همزمان با ساخت بورد است تا بورد بلافاصله قابل استفاده باشد.

URL: /v2/scrumboard/boards

Method: POST

Controller: BoardController@store

Middleware: authWithJwt

Parameters

Parameter	Type	Description
title	String	عنوان بورد (الزامی).
icon	String	آیکون یا ایموجی بورد (الزامی).
branch	Integer	شناسه شعبه (الزامی).
sprint_unit	String	(اختیاری) واحد زمان اسپرینت.
sprint_duration	Integer	(اختیاری) مدت زمان اسپرینت.

Logic Details (Default Data)

پس از درج بورد، سیستم موارد زیر را به صورت خودکار ایجاد می‌کند:

لیست‌های پیش‌فرض:

نیازمند بررسی (رنگ: #ffdb6d، اولویت: 3)

درحال انجام (رنگ: #4287f4، اولویت: 2)

انجام شده (رنگ: #4caf50، اولویت: 1)

لیبل‌های پیش‌فرض: بسیار فوری، بالا، متوسط، پایین.

Success Response

{
    "payload": {
        "id": 12,
        "title": "New Board",
        "lists": [ ... ],
        "labels": [ ... ]
    },
    "meta": { "timestamp": 1733754000 }
}

Show Scrum Board

دریافت اطلاعات کامل یک بورد خاص شامل اعضا، لیست‌ها و لیبل‌ها. دسترسی به داده‌های خروجی این متد محدود به سازنده یا اعضای آن بورد است.

URL: /v2/scrumboard/boards/{id}

Method: GET

Controller: BoardController@show

Path Parameters

Parameter	Type	Description
id	Integer	شناسه بورد.

Logic Details

این متد چک می‌کند که آیا کاربر درخواست کننده (`operator`) یا سازنده بورد است و یا شناسه او در فیلد JSON `members` وجود دارد. در غیر این صورت (یا اگر بورد وجود نداشته باشد)، نتیجه خالی برمی‌گرداند.

Success Response

{
    "payload": {
        "id": 12,
        "title": "Board Title",
        "members": [...],
        "lists": [...],
        "labels": [...]
    },
    "meta": { "timestamp": 1733754000 }
}

Update Scrum Board

بروزرسانی اطلاعات بورد. نکته امنیتی مهم این است که برخلاف نمایش، فقط سازنده بورد (Operator ID منطبق) اجازه ویرایش را دارد.

URL: /v2/scrumboard/boards/{id}

Method: PUT / PATCH

Controller: BoardController@update

Parameters

Parameter	Type	Description
title	String	عنوان جدید.
description	String	توضیحات.
members	Array (IDs)	لیست ID اعضای جدید (به JSON تبدیل می‌شود).
status	Integer	وضعیت (پیش‌فرض 1).

Error Response (Forbidden)

اگر کاربر جاری سازنده بورد نباشد:

{
    "error": {
        "code": 1001,
        "message": "You do not have permission to edit this scrum board."
    },
    "meta": { "timestamp": 1733754000 }
}

Success Response

{
    "payload": { "id": 12, "title": "Updated Title", ... },
    "meta": { "timestamp": 1733754000 }
}

Delete Scrum Board

حذف کامل بورد از دیتابیس. این عملیات نیز مانند ویرایش، تنها توسط سازنده بورد قابل انجام است.

URL: /v2/scrumboard/boards/{id}

Method: DELETE

Controller: BoardController@destroy

Logic Details

ابتدا مالکیت بورد بررسی می‌شود. اگر کاربر جاری سازنده نباشد، خطای کد 1001 بازگردانده می‌شود. در صورت موفقیت، رکورد از جدول scrumboard_boards حذف می‌شود.

Success Response

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