BoardMark
เอกสาร

ไฟล์ .md

โครงสร้างไฟล์ Markdown ใน BoardMark: project.md, issue, comment และ sprint พร้อม frontmatter, version และประวัติ

ทำไมเก็บงานเป็นไฟล์ .md?

ไฟล์ .md อ่านได้ทั้งคนและ AI แก้ได้ด้วยเครื่องมือทั่วไป และมีประวัติทุกการเปลี่ยนแปลง ฐานข้อมูลเป็นเพียง index สำหรับค้นหาและแสดงบอร์ด ซึ่งสร้างใหม่จากไฟล์ได้เสมอ

ข้อมูลที่ไม่ใช่เนื้องาน เช่น สมาชิก ทีม สิทธิ์ seat และ billing เก็บในฐานข้อมูลตามปกติ

ไฟล์ถูกจัดเก็บอย่างไร?

โครงสร้างใน object storage
/c/{company_id}/p/{project_key}/
  project.md                       # config, board type, statuses, workflow
  sprints/S-{n}.md
  issues/{KEY}-{n}.md              # 1 issue = 1 file
  issues/{KEY}-{n}/comments/{seq:04d}.md

ไฟล์ issue หน้าตาเป็นอย่างไร?

Frontmatter ถูกตรวจด้วย JSON Schema เดียวกันทั้งฝั่งเว็บและ MCP ส่วนเนื้อหาเป็น Markdown ที่คุณเขียนผ่าน rich-text editor หรือแก้ตรง ๆ ก็ได้

issues/APP-101.md
---
id: APP-101
type: task                # epic | task | subtask | bug
status: in_progress       # must be one of project.md statuses
assignee: usr_01H...      # user id or null
reporter: usr_01H...
points: 3                 # nullable
sprint: S-12              # nullable (Kanban and pipeline = null)
parent: APP-90             # nullable; a subtask needs a parent
links:
  - { type: blocks, id: APP-77 }
  - { type: relates, id: APP-80 }
labels: [frontend]
rank: a0V                 # order on the board and in the backlog
created_at: 2026-09-23T09:00:00+07:00
updated_at: 2026-09-23T10:12:00+07:00
version: 14               # optimistic lock, +1 on every write
---
# Login page

Written in the rich-text editor, saved as Markdown:
mermaid, code, tables, checklists and images.

Comment เก็บอย่างไร?

1 comment = 1 ไฟล์ ถ้ามาจาก AI agent จะมี field agent ระบุ token ที่ใช้ การตอบกลับเก็บ reply_to (comment ต้นทางของ thread) และ in_reply_to (comment ที่ตอบโดยตรง)

issues/APP-101/comments/0005.md
---
seq: 5
author: usr_01H...
agent: tok_01H...         # null when a person wrote it; set when it came through MCP
created_at: 2026-09-23T10:12:00+07:00
reply_to: 3               # the thread's top-level comment; null on a top-level comment
in_reply_to: 4            # the exact comment answered
attachments:
  - attachments/APP-101/8f2a-spec.png
---
Fixed in the attached build, please re-test.

Version และประวัติทำงานอย่างไร?

  • ทุก write ต้องส่ง version ของไฟล์ที่อ่านมา (optimistic locking)
  • ทุก write สร้าง commit 1 รายการ: ใครแก้ ผ่าน agent token ใด ไฟล์ใดเปลี่ยน
  • ดูประวัติและ diff ผ่าน MCP (get_history, diff) ในแอป issue ที่ agent แก้มีป้ายกำกับ และหน้าเอเจนต์แสดง commit ล่าสุดจาก agent ของคุณ