Kanban StudioMarkdown & JSON Reference
📝

Markdown & JSON Reference

Full schema reference for board editing

ملخص

يتم دعم كل لوحة Kanban بمستند Markdown بنص عادي يمكنك قراءته وكتابته ونسخه والتحكم في الإصدار. تحتوي الوثيقة على قسمين: كتلة مهيكلة قابلة للقراءة آليًا تحتوي على بيانات اللوحة بتنسيق JSON، وكتلة مخصصة ذات شكل حر لملاحظاتك الشخصية.

المخطط v1JSON + تخفيض السعرآمن للتشغيل الجاف
💡

قم دائمًا بالتشغيل الجاف أولاً

قبل النقر فوق "تطبيق"، استخدم زر التشغيل الجاف للتحقق من صحة تعديلاتك. ستقوم الواجهة الخلفية بالإبلاغ عن الأخطاء وملخص الفرق دون تعديل اللوحة الخاصة بك.

هيكل الوثيقة

تتكون وثيقة Kanban Markdown الكاملة من ثلاثة أجزاء:

  • رأس يمكن قراءته بواسطة الإنسان (عنوان اللوحة، ملاحظة الجيل)
  • الكتلة المنظمة — بيانات JSON بين علامات تعليق HTML
  • الكتلة المخصصة — تخفيض مجاني (ملاحظات، مخططات حورية البحر، روابط)
board.md
# 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 الخاصة بها.

JSON
"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 }
]
مثال: أربعة أعمدة بألوان مميزة
FieldTypeRequiredDescription
idstringYesمعرف العمود الفريد (UUID أو أي سبيكة ثابتة)
titlestringYesيظهر عنوان العمود على السبورة
colorstringYesلون تمييز العمود (ست عشري). تظهر على أنها الحد الأيسر على البطاقات
orderintegerYesترتيب العرض على أساس صفري (تصاعدي، من اليسار إلى اليمين)
ℹ️

Note

يجب أن تكون معرفات الأعمدة فريدة داخل اللوحة. تشير المهام إلى الأعمدة حسب هذا id.

المهام

المهام هي الوحدة الأساسية للعمل. توجد كل مهمة داخل عمود (عبر columnId) ويتم فرزها حسب position داخل هذا العمود.

الحد الأدنى من المهمة

JSON
{
  "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": []
}
تم ملء الحقول المطلوبة فقط — جميع الحقول الاختيارية خالية / فارغة

مهمة كاملة مع كافة المجالات

JSON
{
  "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 }
  ]
}
مثال على الإنتاج مع الأولوية، والعلامات، والمكلفين، وقائمة المراجعة، وتتبع الوقت
FieldTypeRequiredDescription
idstringYesمعرف المهمة الفريد (UUID أو سبيكة ثابتة)
columnIdstringYesمعرف العمود الذي تنتمي إليه هذه المهمة
positionintegerYesترتيب فرز يستند إلى صفر داخل العمود
titlestringYesعنوان المهمة (1–280 حرفًا)
descriptionstringNoوصف أطول متوافق مع تخفيض السعر
priorityenum
"low""medium""high""critical"
Noمستوى إلحاح المهمة
tagsstring[]Noسلاسل تسمية ذات شكل حر للتصفية والتجميع
assigneeIdsstring[]Noمعرفات الأعضاء للأشخاص المعينين لهذه المهمة
mentionMemberIdsstring[]Noمعرفات الأعضاء المذكورة (تم إخطارها) في هذه المهمة
estimatePointsinteger|nullNoتقدير نقطة القصة (فيبوناتشي: 1، 2، 3، 5، 8، 13…)
dueDatestring|nullNoسلسلة التاريخ ISO 8601: YYYY-MM-DD
plannedStartAtstring|nullNoتاريخ ISO 8601: البداية المخطط لها
plannedEndAtstring|nullNoتاريخ ISO 8601: النهاية المخطط لها
timeboxMinutesinteger|nullNoمدة جلسة التركيز للملاكمة الزمنية
isCompletedbooleanNoوضع علامة على المهمة على أنها تم (يضيف يتوسطه خط في واجهة المستخدم)
archivedAtstring|nullNoISO 8601 التاريخ والوقت الذي تم فيه أرشفة المهمة. يتم إخفاء المهام المؤرشفة من اللوحة
checklistobject[]Noعناصر قائمة التحقق من المهام الفرعية (راجع قسم قائمة التحقق)

عناصر قائمة المراجعة

تدعم كل مهمة قائمة ثابتة من عناصر قائمة التحقق — وهي مهام فرعية خفيفة الوزن يمكن وضع علامة "إنجاز" عليها بشكل فردي دون إنشاء مهام منفصلة.

JSON
"checklist": [
  { "title": "Design mockup",   "isDone": true  },
  { "title": "Code review",     "isDone": false },
  { "title": "Deploy to prod",  "isDone": false }
]
ثلاثة عناصر في قائمة المراجعة: تم الانتهاء من العنصر الأول، ويتبقى اثنان
FieldTypeRequiredDescription
titlestringYesتسمية عنصر قائمة التحقق (1–255 حرفًا)
isDonebooleanYesما إذا تم تحديد هذا العنصر أم لا

قسم الملاحظات المخصصة

كل شيء بين <!-- KANBAN:CUSTOM:START --> و<!-- KANBAN:CUSTOM:END --> هو لوحة المسودة الخاصة بك. وهو يدعم الرسوم البيانية الكاملة لـ Markdown و Mermaid. لا يتم تحليل المحتوى مطلقًا بواسطة محرك اللوحة - فهو يظهر فقط في علامة التبويب "معاينة".

Markdown
<!-- 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 إحدى القيم الأربع بالضبط. يتم تعيين كل منها إلى لون شارة مميز في واجهة المستخدم:

FieldTypeRequiredDescription
lowenum valueNoإلحاح منخفض. تظهر باللون الرمادي/الأردوازي.
mediumenum valueNoتقصير. يظهر باللون الكهرماني/الأصفر. حذف الإعدادات الافتراضية ذات الأولوية لهذا.
highenum valueNoمهم. تظهر باللون البرتقالي.
criticalenum valueNoالحظر. تظهر باللون الأحمر/الوردي.

مهام الأرشفة

لأرشفة مهمة، قم بتعيين الحقل archivedAt الخاص بها إلى سلسلة تاريخ ووقت ISO. يتم استبعاد المهام المؤرشفة من عرض اللوحة النشطة ولكن يتم الاحتفاظ بها في السجل.

JSON
{
  "id": "task-old",
  "columnId": "col-1",
  "position": 99,
  "title": "Old completed task",
  "archivedAt": "2025-01-10T14:30:00.000Z",
  ...
}
المهمة المؤرشفة — مخفية من اللوحة، ومحفوظة في لقطة
ℹ️

Note

يؤدي تعيين archivedAt إلى قيمة خالية إلى إلغاء أرشفة المهمة. سيُظهر ملخص الفرق المهام ToArchive عند تطبيق لقطة تخفيض السعر التي تقوم بأرشفة المهام النشطة حاليًا على اللوحة.

التشغيل الجاف والتشخيص

تعمل ميزة التشغيل الجاف على التحقق من صحة تخفيض السعر الخاص بك دون تطبيق التغييرات. تقوم الواجهة الخلفية بإرجاع diffSummary (ما يمكن أن يتغير) ومصفوفة diagnostics تسرد أي أخطاء أو تحذيرات.

استجابة ناجحة للتشغيل الجاف

JSON
{
  "ok": true,
  "dryRun": true,
  "diagnostics": [],
  "diffSummary": {
    "columnsCreated": 1,
    "columnsTouched": 2,
    "tasksCreated": 3,
    "tasksTouched": 5,
    "tasksToArchive": 0
  }
}
حسنًا: صحيح يعني أن تخفيض السعر صالح وآمن للتطبيق

التشغيل الجاف مع وجود أخطاء

JSON
{
  "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
  }
}
حسنًا: خطأ - قم بإصلاح الأخطاء قبل التقديم
FieldTypeRequiredDescription
codestringYesرمز خطأ يمكن قراءته آليًا (على سبيل المثال،known_column_id)
messagestringYesوصف للمشكلة يمكن قراءته من قبل الإنسان
lineintegerYesرقم السطر التقريبي في مستند تخفيض السعر
severityenum
"error""warning"
Yesإما "خطأ" (يتم تطبيق الكتل) أو "تحذير" (تطبيق العائدات)
🚫

تطبيق كتلة الأخطاء

إذا كانت التشخيصات تحتوي على أي عنصر خطير: "خطأ"، فسترفض عملية التطبيق المتابعة. التحذيرات استشارية ولا تمنع.

سير العمل الموصى به

اتبع هذا التدفق عند تحرير اللوحة عبر Markdown:

  • افتح لوحة Markdown على اللوحة الخاصة بك
  • قم بتحرير JSON في الكتلة المنظمة — إضافة/تعديل الأعمدة أو المهام
  • انقر فوق التشغيل الجاف للتحقق من الصحة دون تغيير أي شيء
  • قم بإصلاح أي أخطاء تظهر في قائمة التشخيص
  • انقر تطبيق لإجراء التغييرات على اللوحة المباشرة
  • استخدم التنزيل لحفظ نسخة احتياطية محلية من .md
💡

نصيحة للتحكم في الإصدار

نظرًا لأن المستند عبارة عن نص عادي، يمكنك لصقه في مستودع Git، والإصدارات المختلفة، واستعادة حالات اللوحة السابقة عن طريق إعادة تطبيق لقطة قديمة.

Schema v1 · Updated September 2026