مرجع Markdown و JSON
مرجع کامل طرحواره برای ویرایش تابلو
نمای کلی
هر برد Kanban توسط یک سند Markdown متن ساده پشتیبانی می شود که می توانید آن را بخوانید، بنویسید، کپی کنید و نسخه را کنترل کنید. این سند دارای دو بخش است: یک بلوک ساختار یافته قابل خواندن توسط ماشین که داده های برد را به صورت JSON نگهداری می کند و یک بلوک سفارشی آزاد برای یادداشت های شخصی شما.
همیشه ابتدا به صورت خشک کار کنید
قبل از کلیک بر روی Apply، از دکمه Dry-run برای تایید ویرایش های خود استفاده کنید. پشتیبان خطاها و خلاصه تفاوت را بدون تغییر تابلوی شما گزارش خواهد کرد.
ساختار سند
یک سند کامل Kanban Markdown از سه بخش تشکیل شده است:
- هدر قابل خواندن برای انسان (عنوان تابلو، یادداشت نسل)
- بلاک ساختاریافته - داده های JSON بین نشانگرهای نظر HTML
- بلوک سفارشی — Markdown رایگان (یادداشت ها، نمودارهای پری دریایی، پیوندها)
# My Project Board
Generated by Kanban Markdown schema v1.
<!-- KANBAN:STRUCTURED:START -->
```kanban-structured
{
"version": 1,
"board": {
"id": "board-abc123",
"title": "My Project Board"
},
"columns": [
{ "id": "col-1", "title": "Backlog", "color": "#64748b", "order": 0 },
{ "id": "col-2", "title": "In Progress", "color": "#6366f1", "order": 1 },
{ "id": "col-3", "title": "Done", "color": "#10b981", "order": 2 }
],
"tasks": [
{
"id": "task-1",
"columnId": "col-2",
"position": 0,
"title": "Build authentication flow",
"description": "Implement JWT login, register, and token refresh.",
"priority": "high",
"tags": ["backend", "security"],
"assigneeIds": ["member-uuid-1"],
"mentionMemberIds": ["member-uuid-2"],
"estimatePoints": 5,
"dueDate": "2025-03-15",
"plannedStartAt": "2025-03-10",
"plannedEndAt": "2025-03-15",
"timeboxMinutes": 90,
"isCompleted": false,
"archivedAt": null,
"checklist": [
{ "title": "Design DB schema", "isDone": true },
{ "title": "Write unit tests", "isDone": false },
{ "title": "Deploy to staging", "isDone": false }
]
}
]
}
```
<!-- KANBAN:STRUCTURED:END -->
<!-- KANBAN:CUSTOM:START -->
## Team Notes
- Sprint ends Friday
- Backend review at 3 PM
```mermaid
flowchart LR
A[Backlog] --> B[In Progress] --> C[Done]
```
<!-- KANBAN:CUSTOM:END -->نشانگرهای نظر را حذف نکنید
نشانگرهای <!-- KANBAN:STRUCTURED:START -->، <!-- KANBAN:STRUCTURED:END -->، <!-- KANBAN:CUSTOM:START --> و <!-- KANBAN:CUSTOM:END --> مورد نیاز است. حذف آنها باعث خطای تجزیه می شود.
ستون ها
ستون ها مراحل گردش کار برد شما را مشخص می کنند. آنها با مقدار order آنها از چپ به راست رندر می شوند.
"columns": [
{ "id": "col-1", "title": "To Do", "color": "#64748b", "order": 0 },
{ "id": "col-2", "title": "In Progress", "color": "#6366f1", "order": 1 },
{ "id": "col-3", "title": "Review", "color": "#f59e0b", "order": 2 },
{ "id": "col-4", "title": "Done", "color": "#10b981", "order": 3 }
]| میدان | تایپ کنید | مورد نیاز | پیش فرض | توضیحات |
|---|---|---|---|---|
id | string | بله | — | شناسه ستون منحصر به فرد (UUID یا هر حلزون ثابت) |
title | string | بله | — | عنوان ستون روی تابلو نشان داده شده است |
color | string | بله | #64748b | رنگ تاکیدی ستون (هگز). به عنوان حاشیه سمت چپ روی کارت ها نشان داده می شود |
order | integer | بله | — | ترتیب نمایش بر اساس صفر (صعودی، چپ به راست) |
Note
شناسه های ستون باید در تابلو منحصر به فرد باشد. ستون های وظایف با این id ارجاع می دهند.
وظایف
وظایف واحد اصلی کار هستند. هر کار در یک ستون (از طریق columnId) زندگی می کند و بر اساس position در آن ستون مرتب می شود.
کار حداقلی
{
"id": "task-abc",
"columnId": "col-1",
"position": 0,
"title": "Write release notes",
"description": "",
"priority": "medium",
"tags": [],
"assigneeIds": [],
"mentionMemberIds": [],
"estimatePoints": null,
"dueDate": null,
"plannedStartAt": null,
"plannedEndAt": null,
"timeboxMinutes": null,
"isCompleted": false,
"archivedAt": null,
"checklist": []
}کار کامل با تمام فیلدها
{
"id": "task-xyz",
"columnId": "col-2",
"position": 0,
"title": "Redesign checkout page",
"description": "Full UX overhaul based on user research findings.",
"priority": "critical",
"tags": ["ux", "frontend", "q1-goal"],
"assigneeIds": ["member-alice", "member-bob"],
"mentionMemberIds": ["member-pm"],
"estimatePoints": 8,
"dueDate": "2025-04-01",
"plannedStartAt": "2025-03-20",
"plannedEndAt": "2025-04-01",
"timeboxMinutes": 120,
"isCompleted": false,
"archivedAt": null,
"checklist": [
{ "title": "User interviews", "isDone": true },
{ "title": "Wireframes approved", "isDone": true },
{ "title": "Implement components", "isDone": false },
{ "title": "A/B test live", "isDone": false }
]
}| میدان | تایپ کنید | مورد نیاز | پیش فرض | توضیحات |
|---|---|---|---|---|
id | string | بله | — | شناسه تکلیف (UUID یا Slug پایدار) |
columnId | string | بله | — | شناسه ستونی که این کار به آن تعلق دارد |
position | integer | بله | — | ترتیب مرتب سازی بر اساس صفر در ستون |
title | string | بله | — | عنوان کار (1 تا 280 نویسه) |
description | string | خیر | "" | توضیحات طولانی تر سازگار با Markdown |
priority | enum "low""medium""high""critical" | خیر | medium | سطح فوریت کار |
tags | string[] | خیر | [] | رشته های برچسب آزاد برای فیلتر کردن و گروه بندی |
assigneeIds | string[] | خیر | [] | شناسه اعضای افرادی که به این کار اختصاص داده شده اند |
mentionMemberIds | string[] | خیر | [] | شناسه های عضو ذکر شده (اعلام شده) در این کار |
estimatePoints | integer|null | خیر | null | تخمین نقطه داستان (فیبوناچی: 1، 2، 3، 5، 8، 13…) |
dueDate | string|null | خیر | null | رشته تاریخ ISO 8601: YYYY-MM-DD |
plannedStartAt | string|null | خیر | null | تاریخ تاریخ ISO 8601: شروع برنامه ریزی شده |
plannedEndAt | string|null | خیر | null | تاریخ تاریخ ISO 8601: پایان برنامه ریزی شده |
timeboxMinutes | integer|null | خیر | null | طول جلسه تمرکز برای تایم بوکس |
isCompleted | boolean | خیر | false | کار را به عنوان انجام شده علامت گذاری می کند (خط خطی را در رابط کاربری اضافه می کند) |
archivedAt | string|null | خیر | null | ISO 8601 تاریخ زمانی که کار بایگانی شد. وظایف بایگانی شده از هیئت مدیره پنهان می شوند |
checklist | object[] | خیر | [] | موارد چک لیست زیر وظایف (به بخش چک لیست مراجعه کنید) |
موارد چک لیست
هر کار از یک لیست مسطح از موارد چک لیست پشتیبانی می کند - وظایف فرعی سبکی که می توانند به صورت جداگانه بدون ایجاد وظایف جداگانه علامت گذاری شوند.
"checklist": [
{ "title": "Design mockup", "isDone": true },
{ "title": "Code review", "isDone": false },
{ "title": "Deploy to prod", "isDone": false }
]| میدان | تایپ کنید | مورد نیاز | پیش فرض | توضیحات |
|---|---|---|---|---|
title | string | بله | — | برچسب آیتم چک لیست (1 تا 255 نویسه) |
isDone | boolean | بله | — | آیا این مورد علامت زده شده است یا خیر |
بخش یادداشت های سفارشی
همه چیز بین <!-- KANBAN:CUSTOM:START --> و <!-- KANBAN:CUSTOM:END --> صفحه خراش شما است. از نمودارهای Markdown و Mermaid کامل پشتیبانی می کند. محتوا هرگز توسط موتور برد تجزیه نمی شود - فقط در برگه پیش نمایش نشان داده می شود.
<!-- KANBAN:CUSTOM:START -->
## Sprint Notes
- Daily standup at 10:00 AM
- Backend API freeze on Friday
```mermaid
gantt
title Sprint 12
section Tasks
Auth flow :done, 2025-03-10, 3d
Dashboard UI :active, 2025-03-13, 4d
API docs :2025-03-17, 2d
```
> Reminder: update JIRA tickets before end of day.
<!-- KANBAN:CUSTOM:END -->Tip
از بخش سفارشی برای یادداشتهای سرعتی، پیوندهای تیم، نمودارهای گانت، نمودارهای معماری استفاده کنید - هر چیزی که میخواهید در کنار دادههای تخته خود قابل مشاهده باشد.
ارزش های اولویت دار
فیلد priority دقیقاً یکی از چهار مقدار را میپذیرد. هر نقشه به رنگ نشان مجزا در رابط کاربری نشان داده می شود:
| میدان | تایپ کنید | مورد نیاز | پیش فرض | توضیحات |
|---|---|---|---|---|
low | enum value | خیر | — | فوریت کم به رنگ تخته سنگ/خاکستری نشان داده شده است. |
medium | enum value | خیر | — | پیش فرض به رنگ کهربایی/زرد نشان داده شده است. حذف پیشفرض اولویتها برای این. |
high | enum value | خیر | — | مهم است. به رنگ نارنجی نشان داده شده است. |
critical | enum value | خیر | — | مسدود کردن. به رنگ قرمز/رز نشان داده شده است. |
وظایف بایگانی
برای بایگانی یک کار، فیلد archivedAt آن را روی یک رشته تاریخ تاریخ ISO تنظیم کنید. کارهای بایگانی شده از نمای تابلوی فعال حذف شده اند اما در تاریخ حفظ می شوند.
{
"id": "task-old",
"columnId": "col-1",
"position": 99,
"title": "Old completed task",
"archivedAt": "2025-01-10T14:30:00.000Z",
...
}Note
تنظیم archivedAt به null، کار را بایگانی می کند. خلاصه تفاوت tasksToArchive را هنگام اعمال یک عکس فوری نشانه گذاری نشان می دهد که وظایفی را که در حال حاضر روی برد فعال هستند بایگانی می کند.
خشک اجرا و تشخیص
ویژگی Dry-run علامت گذاری شما را بدون اعمال تغییرات تأیید می کند. باطن یک آرایه diffSummary (چه چیزی تغییر میکند) و یک آرایه diagnostics را برمیگرداند که هر گونه خطا یا هشدار را فهرست میکند.
پاسخ خشک موفقیت آمیز
{
"ok": true,
"dryRun": true,
"diagnostics": [],
"diffSummary": {
"columnsCreated": 1,
"columnsTouched": 2,
"tasksCreated": 3,
"tasksTouched": 5,
"tasksToArchive": 0
}
}اجرای خشک با خطا
{
"ok": false,
"dryRun": true,
"diagnostics": [
{
"code": "unknown_column_id",
"message": "Task 'task-xyz' references unknown column 'col-999'.",
"line": 42,
"severity": "error"
},
{
"code": "duplicate_task_id",
"message": "Task ID 'task-abc' is used more than once.",
"line": 67,
"severity": "error"
}
],
"diffSummary": {
"columnsCreated": 0,
"columnsTouched": 0,
"tasksCreated": 0,
"tasksTouched": 0,
"tasksToArchive": 0
}
}| میدان | تایپ کنید | مورد نیاز | پیش فرض | توضیحات |
|---|---|---|---|---|
code | string | بله | — | کد خطای قابل خواندن توسط ماشین (به عنوان مثال شناسه_column_known) |
message | string | بله | — | توصیف انسان قابل خواندن از موضوع |
line | integer | بله | — | شماره خط تقریبی در سند علامت گذاری |
severity | enum "error""warning" | بله | — | یا "خطا" (بلاک ها اعمال می شوند) یا "اخطار" (اعمال درآمد) |
خطاها بلوک اعمال کنید
اگر تشخیص حاوی مواردی با شدت باشد: «خطا»، عملیات Apply از ادامه دادن امتناع خواهد کرد. هشدارها توصیه ای هستند و مسدود نمی شوند.
گردش کار توصیه شده
هنگام ویرایش تابلو از طریق Markdown این جریان را دنبال کنید:
- پانل Markdown را روی برد خود باز کنید
- JSON را در بلوک ساختاریافته ویرایش کنید — ستون ها یا وظایف را اضافه/تغییر دهید
- روی Dry-run کلیک کنید تا بدون تغییر چیزی تایید شود
- هر گونه خطای نشان داده شده در لیست عیب یابی را برطرف کنید
- روی اعمال کلیک کنید تا تغییرات را در صفحه زنده انجام دهید
- برای ذخیره یک نسخه پشتیبان محلی
.mdاز Download استفاده کنید
نکته کنترل نسخه
از آنجایی که سند یک متن ساده است، میتوانید آن را در یک مخزن Git جایگذاری کنید، نسخههای مختلف را تغییر دهید و با اعمال مجدد یک عکس قدیمیتر، حالتهای قبلی برد را بازیابی کنید.