Kanban StudioMarkdown & JSON Reference
📝

Markdown & JSON Reference

Full schema reference for board editing

მიმოხილვა

Kanban-ის ყველა დაფა მხარდაჭერილია უბრალო ტექსტური Markdown დოკუმენტით, რომლის წაკითხვა, ჩაწერა, კოპირება და ვერსიის კონტროლი შეგიძლიათ. დოკუმენტს აქვს ორი სექცია: მანქანით წაკითხვადი სტრუქტურირებული ბლოკი, რომელიც შეიცავს დაფის მონაცემებს JSON-ად და თავისუფალი ფორმის მორგებული ბლოკი თქვენი პირადი შენიშვნებისთვის.

სქემა v1JSON + Markdownმშრალი გაშვების უსაფრთხო
💡

ჯერ ყოველთვის მშრალ-გაშვებით

სანამ დააწკაპუნებთ Apply-ზე, გამოიყენეთ მშრალი გაშვების ღილაკი თქვენი რედაქტირების დასადასტურებლად. Backend შეატყობინებს შეცდომებს და განსხვავებულ შეჯამებას თქვენი დაფის შეცვლის გარეშე.

დოკუმენტის სტრუქტურა

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სვეტის აქცენტის ფერი (hex). ნაჩვენებია როგორც მარცხენა საზღვარი ბარათებზე
orderintegerYesნულზე დაფუძნებული ჩვენების თანმიმდევრობა (აღმავალი, მარცხნიდან მარჯვნივ)
ℹ️

Note

სვეტის ID უნდა იყოს უნიკალური დაფაზე. ამოცანების მითითების სვეტები ამ 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": []
}
შევსებულია მხოლოდ აუცილებელი ველები - ყველა არჩევითი ველი არის null / ცარიელი

სრული დავალება ყველა ველით

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სვეტის ID, რომელსაც ეკუთვნის ეს ამოცანა
positionintegerYesნულზე დაფუძნებული დალაგების წესრიგი სვეტში
titlestringYesამოცანის სათაური (1–280 სიმბოლო)
descriptionstringNoMarkdown-თან თავსებადი უფრო გრძელი აღწერა
priorityenum
"low""medium""high""critical"
Noდავალების გადაუდებლობის დონე
tagsstring[]Noთავისუფალი ფორმის ლეიბლის სტრიქონები ფილტრაციისა და დაჯგუფებისთვის
assigneeIdsstring[]Noამ დავალებისთვის მინიჭებული ადამიანების წევრების ID
mentionMemberIdsstring[]Noამ ამოცანაში ნახსენები (შეტყობინებული) წევრების ID
estimatePointsinteger|nullNoსიუჟეტის წერტილის შეფასება (ფიბონაჩი: 1, 2, 3, 5, 8, 13…)
dueDatestring|nullNoISO 8601 თარიღის სტრიქონი: წწწ-თმ-დდ
plannedStartAtstring|nullNoISO 8601 თარიღი: დაგეგმილი დაწყება
plannedEndAtstring|nullNoISO 8601 თარიღის დრო: დაგეგმილი დასასრული
timeboxMinutesinteger|nullNoფოკუს-სესიის ხანგრძლივობა დრო-ბოქსისთვის
isCompletedbooleanNoმონიშნავს დავალებას შესრულებულად (ამატებს გადახაზვას UI-ში)
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 --> შორის არის თქვენი scratchpad. იგი მხარს უჭერს სრულ 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 Gantt სქემით
💡

Tip

გამოიყენეთ მორგებული განყოფილება სპრინტის შენიშვნებისთვის, გუნდის ბმულებისთვის, Gantt სქემებისთვის, არქიტექტურის დიაგრამებისთვის - ყველაფერი, რაც გსურთ, ხილული იყოს თქვენი დაფის მონაცემებთან ერთად.

პრიორიტეტული ღირებულებები

priority ველი იღებს ზუსტად ერთ-ერთ ოთხ მნიშვნელობას. თითოეული რუქა განსხვავებულ ბეჯის ფერს UI-ში:

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-ის ნულზე დაყენება ამოცანის არქივის გაუქმებას იწვევს. განსხვავებების შეჯამება აჩვენებს tasksToArchive-ს, როდესაც გამოიყენებთ მარკირების სნეპშოტს, რომელიც დაარქივებს დაფაზე მოქმედ ამოცანებს.

მშრალი გაშვება და დიაგნოსტიკა

მშრალი გაშვების ფუნქცია ამოწმებს თქვენს მარკირებას ცვლილებების გამოყენების გარეშე. backend აბრუნებს diffSummary (რა შეიცვლება) და diagnostics მასივს, სადაც ჩამოთვლილია ნებისმიერი შეცდომა ან გაფრთხილება.

მშრალ პერსპექტივაზე წარმატებული პასუხი

JSON
{
  "ok": true,
  "dryRun": true,
  "diagnostics": [],
  "diffSummary": {
    "columnsCreated": 1,
    "columnsTouched": 2,
    "tasksCreated": 3,
    "tasksTouched": 5,
    "tasksToArchive": 0
  }
}
ok: true ნიშნავს, რომ მარკირება მოქმედებს და უსაფრთხოა გამოსაყენებლად

მშრალი გაშვება შეცდომებით

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მანქანით წაკითხვადი შეცდომის კოდი (მაგ. უცნობი_სვეტის_id)
messagestringYesსაკითხის ადამიანისათვის წასაკითხი აღწერა
lineintegerYesმიახლოებითი სტრიქონის ნომერი მონიშვნის დოკუმენტში
severityenum
"error""warning"
Yesან „შეცდომა“ (მოქმედებს ბლოკები) ან „გაფრთხილება“ (შემოსავლების გამოყენება)
🚫

შეცდომების ბლოკის გამოყენება

თუ დიაგნოსტიკა შეიცავს რაიმე სიმძიმის პუნქტს: 'შეცდომას', განაცხადის ოპერაცია უარს იტყვის გაგრძელებაზე. გაფრთხილებები საკონსულტაციოა და არ ბლოკავს.

რეკომენდებული სამუშაო პროცესი

მიჰყევით ამ დინებას Markdown-ის საშუალებით დაფის რედაქტირებისას:

  • გახსენით Markdown პანელი თქვენს დაფაზე
  • შეცვალეთ JSON სტრუქტურულ ბლოკში — დაამატეთ/შეცვალეთ სვეტები ან ამოცანები
  • დააწკაპუნეთ Dry-run, რომ დაადასტუროთ არაფრის შეცვლის გარეშე
  • შეასწორეთ ნებისმიერი შეცდომა, რომელიც ნაჩვენებია დიაგნოსტიკის სიაში
  • დააწკაპუნეთ Apply ცვლილებების შესატანად ცოცხალ დაფაზე
  • გამოიყენეთ ჩამოტვირთვა ადგილობრივი .md სარეზერვო ასლის შესანახად
💡

ვერსიის კონტროლის წვერი

იმის გამო, რომ დოკუმენტი უბრალო ტექსტია, შეგიძლიათ ჩასვათ ის Git-ის საცავში, განასხვავოთ ვერსიები და აღადგინოთ დაფის წინა მდგომარეობა ძველი სნეპშოტის ხელახლა გამოყენებით.

Schema v1 · Updated September 2026