M-001: Comment Module — Thiết kế Chi tiết v2

Version: v2-draft | Date: 2026-03-03 Lead: claude_ai | Critic: gemini Status: 🔨 Building — checkpoint UI + workflow integration Gốc: Migrate từ comment-module.md + bổ sung chi tiết kỹ thuật

---

1. Tổng quan

CommentModule = phòng họp của máy. Xây 1 lần, lắp khắp nơi:

<CommentModule :task-id="X" />

Mọi quy trình đều đi qua đây: planning, execution, review, monitoring.

2. Component Architecture

2.1 Cấu trúc file

components/modules/comment-module/
├── CommentModule.vue           # Entry point — component chính
├── composables/
│   └── useComments.ts          # Logic: CRUD comments, real-time, filters
├── types.ts                    # TypeScript interfaces
├── partials/
│   ├── CommentList.vue         # Danh sách comments (scroll, pagination)
│   ├── CommentEditor.vue       # Editor (markdown, mentions, actions)
│   ├── CommentItem.vue         # Từng comment (avatar, role badge, timestamp)
│   ├── TabBar.vue              # Tabs: planning | checklist | test | ...
│   └── CheckpointPanel.vue    # [v2] Panel 3 tầng checkpoint
└── README.md                  # Docs cho Claude Code CLI

2.2 Protocol Definition (theo Module Protocol Standard)

Mục	Chi tiết
Props	task-id (required, number) — ID task trong Directus
	tab-scope (optional, string) — Tab mặc định khi mount
	read-only (optional, boolean) — Chỉ xem, không comment
	show-checkpoints (optional, boolean) — Hiển thị panel checkpoint
Events	@comment-created — Khi comment mới được tạo
	@checkpoint-updated — Khi checkpoint tick/untick
	@tab-changed — Khi user đổi tab
Data Source	Collection: task_comments (Directus)
	Composable: useComments(taskId, tabScope)
Permissions	Public: read
Slots	#header — Custom header
	#empty — Empty state

2.3 useComments Composable

// composables/useComments.ts
interface UseCommentsOptions {
  taskId: number
  tabScope?: string
  autoRefresh?: boolean   // polling interval
}

interface UseCommentsReturn {
  comments: Ref<Comment[]>
  loading: Ref<boolean>
  error: Ref<string | null>
  createComment: (content: string, agentType?: string) => Promise<void>
  updateComment: (id: number, content: string) => Promise<void>
  deleteComment: (id: number) => Promise<void>
  filterByTab: (tab: string) => void
  filterByAgent: (agentType: string) => void
}

3. Data Model

3.1 Collection: task_comments (Directus)

Field	Type	Description
id	integer (PK)	Auto-increment
task_id	integer (FK → tasks)	Task liên kết
content	text	Nội dung markdown
agent_type	string	claude_code / claude_ai / gemini / gpt / codex / system / user
tab_scope	string	planning / checklist / test / reports / verify / prompt / rules
action	string (nullable)	checkpoint_auto / review_approve / review_reject
date_created	datetime	Auto
date_updated	datetime	Auto

3.2 Tab Scopes (8 tabs)

Tab	Mục đích	Ai dùng
planning	Thảo luận kế hoạch	AI Lead + Critic
checklist	Checkpoint tracking	System + AI
test	Kết quả test	AI Executor
reports	Báo cáo session	AI + System
verify	Xác minh kết quả	AI Critic
prompt	Prompt thực thi	AI Lead
rules	Quy tắc áp dụng	System
general	Trao đổi chung	Tất cả

4. v1 → v2 Delta

Feature	v1 (DONE)	v2 (Building)
CRUD comments	✅	✅
Tab filtering	✅	✅
Agent badges	✅	✅
Markdown render	✅	✅
Checkpoint panel	❌	🔨 3 tầng (L0/L1/L2)
Auto-tick checkpoint	❌	🔨 comment → checkpoint
Workflow liên thông	❌	🔨 M-002 integration
Real-time updates	❌	⏳ Prefect webhook

5. Liên kết

• Tầm nhìn đầy đủ: comment-module.md
• Checkpoint design: checkpoint-design.md
• Module Protocol: search_knowledge("module protocol standard")
• Execution Plan: modules-execution-plan.md

---

Claude Code CLI: Đọc file này TRƯỚC KHI code. Tuân thủ props/events/types đã định nghĩa.