Markdown & JSON Reference
Full schema reference for board editing
Шолу
Әрбір Kanban тақтасы оқуға, жазуға, көшіруге және нұсқаны басқаруға болатын қарапайым мәтінді Markdown құжатымен қамтамасыз етілген. Құжаттың екі бөлімі бар: тақта деректерін JSON ретінде сақтайтын машинада оқылатын Құрылымдық блогы және жеке жазбаларыңыз үшін еркін пішінді Теңшелетін блогы.
Әрқашан алдымен құрғатыңыз
«Қолдану» түймесін баспас бұрын, өңдеулерді растау үшін «Құрғақ іске қосу» түймесін пайдаланыңыз. Backend тақтаны өзгертпей қателер мен айырмашылықтар туралы есеп береді.
Құжат құрылымы
Толық Kanban Markdown құжаты үш бөліктен тұрады:
- Адам оқи алатын тақырып (тақта тақырыбы, буын жазбасы)
- Құрылымдық блок — HTML түсініктеме маркерлері арасындағы JSON деректері
- Пайдаланушы блок — тегін Markdown (жазбалар, Mermaid диаграммалары, сілтемелер)
# 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 | "" | Markdown-үйлесімді ұзағырақ сипаттама |
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 күн жолы: ЖЖЖЖ-АА-КК |
plannedStartAt | string|null | No | null | ISO 8601 күні: жоспарланған басталуы |
plannedEndAt | string|null | No | null | ISO 8601 күні: жоспарланған аяқталу |
timeboxMinutes | integer|null | No | null | Тайм-бокс үшін фокус-сеанс ұзақтығы |
isCompleted | boolean | No | false | Тапсырманы орындалды деп белгілейді (UI интерфейсінде сызып тастауды қосады) |
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 параметрін нөлге қою тапсырманы мұрағаттан шығарады. Айырмашылық жиынтықта қазіргі уақытта тақтада белсенді тапсырмаларды мұрағаттайтын белгілеу суретін қолдану кезінде Archive тапсырмалары көрсетіледі.
Құрғақ басқару және диагностика
Құрғақ іске қосу мүмкіндігі өзгертулерді қолданбай-ақ таңбалауды растайды. Сервер 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 | — | Құрылғы оқылатын қате коды (мысалы, белгісіз_баған_идентификаторы) |
message | string | Yes | — | Мәселенің адам оқи алатын сипаттамасы |
line | integer | Yes | — | Белгілеу құжатындағы жолдың шамамен нөмірі |
severity | enum "error""warning" | Yes | — | «Қате» (блоктар қолданылады) немесе «ескерту» (түсімдерді қолдану) |
Қателерді блоктау Қолдану
Диагностикада маңыздылығы бар кез келген элемент болса: "қате", Қолдану әрекеті жалғастырудан бас тартады. Ескертулер кеңес беру болып табылады және блокталмайды.
Ұсынылатын жұмыс процесі
Markdown арқылы тақтаны өңдеу кезінде мына ағынды орындаңыз:
- Тақтадағы Markdown тақтасын ашыңыз
- Құрылымдық блокта JSON өңдеңіз — бағандарды немесе тапсырмаларды қосыңыз/өзгертіңіз
- Ештеңені өзгертпестен растау үшін Құрғақ іске қосу түймесін басыңыз
- Диагностика тізімінде көрсетілген қателерді түзетіңіз
- Тікелей эфир тақтасына өзгерістер енгізу үшін Қолдану түймесін басыңыз
- Жергілікті
.mdсақтық көшірмесін сақтау үшін Жүктеп алу опциясын пайдаланыңыз
Нұсқаны басқару кеңесі
Құжат кәдімгі мәтін болғандықтан, оны Git репозиторийіне, diff нұсқаларына қоюға және ескі суретті қайта қолдану арқылы алдыңғы тақта күйлерін қалпына келтіруге болады.