Kanban StudioMarkdown & JSON Reference
📝

Markdown & JSON Reference

Full schema reference for board editing

Шолу

Әрбір Kanban тақтасы оқуға, жазуға, көшіруге және нұсқаны басқаруға болатын қарапайым мәтінді Markdown құжатымен қамтамасыз етілген. Құжаттың екі бөлімі бар: тақта деректерін JSON ретінде сақтайтын машинада оқылатын Құрылымдық блогы және жеке жазбаларыңыз үшін еркін пішінді Теңшелетін блогы.

Схема v1JSON + MarkdownҚұрғақ қауіпсіз
💡

Әрқашан алдымен құрғатыңыз

«Қолдану» түймесін баспас бұрын, өңдеулерді растау үшін «Құрғақ іске қосу» түймесін пайдаланыңыз. Backend тақтаны өзгертпей қателер мен айырмашылықтар туралы есеп береді.

Құжат құрылымы

Толық Kanban Markdown құжаты үш бөліктен тұрады:

  • Адам оқи алатын тақырып (тақта тақырыбы, буын жазбасы)
  • Құрылымдық блок — HTML түсініктеме маркерлері арасындағы JSON деректері
  • Пайдаланушы блок — тегін Markdown (жазбалар, Mermaid диаграммалары, сілтемелер)
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 таңба)
descriptionstringNoMarkdown-үйлесімді ұзағырақ сипаттама
priorityenum
"low""medium""high""critical"
NoТапсырманың шұғыл деңгейі
tagsstring[]NoСүзгілеу және топтастыру үшін еркін пішінді жапсырма жолдары
assigneeIdsstring[]NoОсы тапсырмаға тағайындалған адамдардың мүше идентификаторлары
mentionMemberIdsstring[]NoОсы тапсырмада айтылған (хабарланған) мүше идентификаторлары
estimatePointsinteger|nullNoОқиға нүктесін бағалау (Фибоначчи: 1, 2, 3, 5, 8, 13…)
dueDatestring|nullNoISO 8601 күн жолы: ЖЖЖЖ-АА-КК
plannedStartAtstring|nullNoISO 8601 күні: жоспарланған басталуы
plannedEndAtstring|nullNoISO 8601 күні: жоспарланған аяқталу
timeboxMinutesinteger|nullNoТайм-бокс үшін фокус-сеанс ұзақтығы
isCompletedbooleanNoТапсырманы орындалды деп белгілейді (UI интерфейсінде сызып тастауды қосады)
archivedAtstring|nullNoТапсырма мұрағатталған кездегі ISO 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 -->
Mermaid Гант диаграммасы бар жазбалар
💡

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 параметрін нөлге қою тапсырманы мұрағаттан шығарады. Айырмашылық жиынтықта қазіргі уақытта тақтада белсенді тапсырмаларды мұрағаттайтын белгілеу суретін қолдану кезінде Archive тапсырмалары көрсетіледі.

Құрғақ басқару және диагностика

Құрғақ іске қосу мүмкіндігі өзгертулерді қолданбай-ақ таңбалауды растайды. Сервер 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
  }
}
ok: false — қолданбас бұрын қателерді түзетіңіз
FieldTypeRequiredDescription
codestringYesҚұрылғы оқылатын қате коды (мысалы, белгісіз_баған_идентификаторы)
messagestringYesМәселенің адам оқи алатын сипаттамасы
lineintegerYesБелгілеу құжатындағы жолдың шамамен нөмірі
severityenum
"error""warning"
Yes«Қате» (блоктар қолданылады) немесе «ескерту» (түсімдерді қолдану)
🚫

Қателерді блоктау Қолдану

Диагностикада маңыздылығы бар кез келген элемент болса: "қате", Қолдану әрекеті жалғастырудан бас тартады. Ескертулер кеңес беру болып табылады және блокталмайды.

Ұсынылатын жұмыс процесі

Markdown арқылы тақтаны өңдеу кезінде мына ағынды орындаңыз:

  • Тақтадағы Markdown тақтасын ашыңыз
  • Құрылымдық блокта JSON өңдеңіз — бағандарды немесе тапсырмаларды қосыңыз/өзгертіңіз
  • Ештеңені өзгертпестен растау үшін Құрғақ іске қосу түймесін басыңыз
  • Диагностика тізімінде көрсетілген қателерді түзетіңіз
  • Тікелей эфир тақтасына өзгерістер енгізу үшін Қолдану түймесін басыңыз
  • Жергілікті .md сақтық көшірмесін сақтау үшін Жүктеп алу опциясын пайдаланыңыз
💡

Нұсқаны басқару кеңесі

Құжат кәдімгі мәтін болғандықтан, оны Git репозиторийіне, diff нұсқаларына қоюға және ескі суретті қайта қолдану арқылы алдыңғы тақта күйлерін қалпына келтіруге болады.

Schema v1 · Updated September 2026