Kanban Studio›Markdown & JSON анықтамасы
📝

Markdown & JSON анықтамасы

Тақтаны өңдеуге арналған схема анықтамасы

Шолу

Әрбір 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 }
]
Мысал: әр түрлі түстері бар төрт баған
ӨрісТүрМіндеттіСипаттама
idstringИәБірегей баған идентификаторы (UUID немесе кез келген тұрақты слаг)
titlestringИәТақтада көрсетілген баған тақырыбы
colorstringИәБаған екпіні түсі (алтылық). Карталарда сол жақ жиек ретінде көрсетілген
orderintegerИәНөлге негізделген дисплей реті (өсу, солдан оңға қарай)
ℹ️

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 }
  ]
}
Басымдылығы, тегтері, тағайындаушылары, бақылау тізімі, уақытты бақылау бар өндіріс үлгісі
ӨрісТүрМіндеттіСипаттама
idstringИәБірегей тапсырма идентификаторы (UUID немесе тұрақты слаг)
columnIdstringИәОсы тапсырма тиесілі бағанның идентификаторы
positionintegerИәБағандағы нөлге негізделген сұрыптау реті
titlestringИәТапсырма тақырыбы (1–280 таңба)
descriptionstringЖоқMarkdown-үйлесімді ұзағырақ сипаттама
priorityenum
"low""medium""high""critical"
ЖоқТапсырманың шұғыл деңгейі
tagsstring[]ЖоқСүзгілеу және топтастыру үшін еркін пішінді жапсырма жолдары
assigneeIdsstring[]ЖоқОсы тапсырмаға тағайындалған адамдардың мүше идентификаторлары
mentionMemberIdsstring[]ЖоқОсы тапсырмада айтылған (хабарланған) мүше идентификаторлары
estimatePointsinteger|nullЖоқОқиға нүктесін бағалау (Фибоначчи: 1, 2, 3, 5, 8, 13…)
dueDatestring|nullЖоқISO 8601 күн жолы: ЖЖЖЖ-АА-КК
plannedStartAtstring|nullЖоқISO 8601 күні: жоспарланған басталуы
plannedEndAtstring|nullЖоқISO 8601 күні: жоспарланған аяқталу
timeboxMinutesinteger|nullЖоқТайм-бокс үшін фокус-сеанс ұзақтығы
isCompletedbooleanЖоқТапсырманы орындалды деп белгілейді (UI интерфейсінде сызып тастауды қосады)
archivedAtstring|nullЖоқТапсырма мұрағатталған кездегі ISO 8601 күні. Мұрағатталған тапсырмалар тақтадан жасырылады
checklistobject[]ЖоқТапсырманың қосалқы тізімінің элементтері (тексеру тізімі бөлімін қараңыз)

Тексеру тізімінің элементтері

Әрбір тапсырма бақылау тізімі элементтерінің тегіс тізімін қолдайды — жеке тапсырмаларды жасамай-ақ орындалды деп белгілеуге болатын жеңіл ішкі тапсырмалар.

JSON
"checklist": [
  { "title": "Design mockup",   "isDone": true  },
  { "title": "Code review",     "isDone": false },
  { "title": "Deploy to prod",  "isDone": false }
]
Бақылау тізімінің үш элементі: біріншісі орындалды, екеуі қалды
ӨрісТүрМіндеттіСипаттама
titlestringИәБақылау тізімі элементінің белгісі (1–255 таңба)
isDonebooleanИәБұл элемент өшірілген ба

Теңшелетін жазбалар бөлімі

<!-- 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 өрісі төрт мәннің дәл біреуін қабылдайды. Әрбір пайдаланушы интерфейсінде белгілі бір белгіше түсімен карталанады:

ӨрісТүрМіндеттіСипаттама
lowenum valueЖоқТөмен шұғылдық. Сланец/сұр түспен көрсетілген.
mediumenum valueЖоқӘдепкі. Сары/сары түсте көрсетілген. Бұған әдепкі басымдықты алып тастау.
highenum valueЖоқМаңызды. Қызғылт сары түспен көрсетілген.
criticalenum valueЖоқБлоктау. Қызыл/раушан түсте көрсетілген.

Мұрағаттау тапсырмалары

Тапсырманы мұрағаттау үшін оның 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 — қолданбас бұрын қателерді түзетіңіз
ӨрісТүрМіндеттіСипаттама
codestringИәҚұрылғы оқылатын қате коды (мысалы, белгісіз_баған_идентификаторы)
messagestringИәМәселенің адам оқи алатын сипаттамасы
lineintegerИәБелгілеу құжатындағы жолдың шамамен нөмірі
severityenum
"error""warning"
Иә«Қате» (блоктар қолданылады) немесе «ескерту» (түсімдерді қолдану)
🚫

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

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

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

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

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

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

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

Схема v1 · Жаңартылды November 2026