Markdown & JSON Reference
Full schema reference for board editing
ملخص
يتم دعم كل لوحة Kanban بمستند Markdown بنص عادي يمكنك قراءته وكتابته ونسخه والتحكم في الإصدار. تحتوي الوثيقة على قسمين: كتلة مهيكلة قابلة للقراءة آليًا تحتوي على بيانات اللوحة بتنسيق JSON، وكتلة مخصصة ذات شكل حر لملاحظاتك الشخصية.
قم دائمًا بالتشغيل الجاف أولاً
قبل النقر فوق "تطبيق"، استخدم زر التشغيل الجاف للتحقق من صحة تعديلاتك. ستقوم الواجهة الخلفية بالإبلاغ عن الأخطاء وملخص الفرق دون تعديل اللوحة الخاصة بك.
هيكل الوثيقة
تتكون وثيقة Kanban Markdown الكاملة من ثلاثة أجزاء:
- رأس يمكن قراءته بواسطة الإنسان (عنوان اللوحة، ملاحظة الجيل)
- الكتلة المنظمة — بيانات JSON بين علامات تعليق HTML
- الكتلة المخصصة — تخفيض مجاني (ملاحظات، مخططات حورية البحر، روابط)
# 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 }
]| Field | Type | Required | Default | Description |
|---|---|---|---|---|
id | string | Yes | — | معرف العمود الفريد (UUID أو أي سبيكة ثابتة) |
title | string | Yes | — | يظهر عنوان العمود على السبورة |
color | string | Yes | #64748b | لون تمييز العمود (ست عشري). تظهر على أنها الحد الأيسر على البطاقات |
order | integer | Yes | — | ترتيب العرض على أساس صفري (تصاعدي، من اليسار إلى اليمين) |
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 }
]
}| Field | Type | Required | Default | Description |
|---|---|---|---|---|
id | string | Yes | — | معرف المهمة الفريد (UUID أو سبيكة ثابتة) |
columnId | string | Yes | — | معرف العمود الذي تنتمي إليه هذه المهمة |
position | integer | Yes | — | ترتيب فرز يستند إلى صفر داخل العمود |
title | string | Yes | — | عنوان المهمة (1–280 حرفًا) |
description | string | No | "" | وصف أطول متوافق مع تخفيض السعر |
priority | enum "low""medium""high""critical" | No | medium | مستوى إلحاح المهمة |
tags | string[] | No | [] | سلاسل تسمية ذات شكل حر للتصفية والتجميع |
assigneeIds | string[] | No | [] | معرفات الأعضاء للأشخاص المعينين لهذه المهمة |
mentionMemberIds | string[] | No | [] | معرفات الأعضاء المذكورة (تم إخطارها) في هذه المهمة |
estimatePoints | integer|null | No | null | تقدير نقطة القصة (فيبوناتشي: 1، 2، 3، 5، 8، 13…) |
dueDate | string|null | No | null | سلسلة التاريخ ISO 8601: YYYY-MM-DD |
plannedStartAt | string|null | No | null | تاريخ ISO 8601: البداية المخطط لها |
plannedEndAt | string|null | No | null | تاريخ ISO 8601: النهاية المخطط لها |
timeboxMinutes | integer|null | No | null | مدة جلسة التركيز للملاكمة الزمنية |
isCompleted | boolean | No | false | وضع علامة على المهمة على أنها تم (يضيف يتوسطه خط في واجهة المستخدم) |
archivedAt | string|null | No | null | ISO 8601 التاريخ والوقت الذي تم فيه أرشفة المهمة. يتم إخفاء المهام المؤرشفة من اللوحة |
checklist | object[] | No | [] | عناصر قائمة التحقق من المهام الفرعية (راجع قسم قائمة التحقق) |
عناصر قائمة المراجعة
تدعم كل مهمة قائمة ثابتة من عناصر قائمة التحقق — وهي مهام فرعية خفيفة الوزن يمكن وضع علامة "إنجاز" عليها بشكل فردي دون إنشاء مهام منفصلة.
"checklist": [
{ "title": "Design mockup", "isDone": true },
{ "title": "Code review", "isDone": false },
{ "title": "Deploy to prod", "isDone": false }
]| Field | Type | Required | Default | Description |
|---|---|---|---|---|
title | string | Yes | — | تسمية عنصر قائمة التحقق (1–255 حرفًا) |
isDone | boolean | Yes | — | ما إذا تم تحديد هذا العنصر أم لا |
قسم الملاحظات المخصصة
كل شيء بين <!-- 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 إحدى القيم الأربع بالضبط. يتم تعيين كل منها إلى لون شارة مميز في واجهة المستخدم:
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
low | enum value | No | — | إلحاح منخفض. تظهر باللون الرمادي/الأردوازي. |
medium | enum value | No | — | تقصير. يظهر باللون الكهرماني/الأصفر. حذف الإعدادات الافتراضية ذات الأولوية لهذا. |
high | enum value | No | — | مهم. تظهر باللون البرتقالي. |
critical | enum value | No | — | الحظر. تظهر باللون الأحمر/الوردي. |
مهام الأرشفة
لأرشفة مهمة، قم بتعيين الحقل archivedAt الخاص بها إلى سلسلة تاريخ ووقت ISO. يتم استبعاد المهام المؤرشفة من عرض اللوحة النشطة ولكن يتم الاحتفاظ بها في السجل.
{
"id": "task-old",
"columnId": "col-1",
"position": 99,
"title": "Old completed task",
"archivedAt": "2025-01-10T14:30:00.000Z",
...
}Note
يؤدي تعيين archivedAt إلى قيمة خالية إلى إلغاء أرشفة المهمة. سيُظهر ملخص الفرق المهام ToArchive عند تطبيق لقطة تخفيض السعر التي تقوم بأرشفة المهام النشطة حاليًا على اللوحة.
التشغيل الجاف والتشخيص
تعمل ميزة التشغيل الجاف على التحقق من صحة تخفيض السعر الخاص بك دون تطبيق التغييرات. تقوم الواجهة الخلفية بإرجاع 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
}
}| Field | Type | Required | Default | Description |
|---|---|---|---|---|
code | string | Yes | — | رمز خطأ يمكن قراءته آليًا (على سبيل المثال،known_column_id) |
message | string | Yes | — | وصف للمشكلة يمكن قراءته من قبل الإنسان |
line | integer | Yes | — | رقم السطر التقريبي في مستند تخفيض السعر |
severity | enum "error""warning" | Yes | — | إما "خطأ" (يتم تطبيق الكتل) أو "تحذير" (تطبيق العائدات) |
تطبيق كتلة الأخطاء
إذا كانت التشخيصات تحتوي على أي عنصر خطير: "خطأ"، فسترفض عملية التطبيق المتابعة. التحذيرات استشارية ولا تمنع.
سير العمل الموصى به
اتبع هذا التدفق عند تحرير اللوحة عبر Markdown:
- افتح لوحة Markdown على اللوحة الخاصة بك
- قم بتحرير JSON في الكتلة المنظمة — إضافة/تعديل الأعمدة أو المهام
- انقر فوق التشغيل الجاف للتحقق من الصحة دون تغيير أي شيء
- قم بإصلاح أي أخطاء تظهر في قائمة التشخيص
- انقر تطبيق لإجراء التغييرات على اللوحة المباشرة
- استخدم التنزيل لحفظ نسخة احتياطية محلية من
.md
نصيحة للتحكم في الإصدار
نظرًا لأن المستند عبارة عن نص عادي، يمكنك لصقه في مستودع Git، والإصدارات المختلفة، واستعادة حالات اللوحة السابقة عن طريق إعادة تطبيق لقطة قديمة.