Incomex AI Portal
KB-3C26

MOW Unified Canvas — Spec (v1)

8 min read Revision 1
mowunified-canvasspecuidata-contractdot-actionscanonical2026-05-29

MOW Unified Canvas — Spec (v1)

project: mow
surface: unified-canvas
version: v1
status: draft
approval_status: pending_user_review
preview_url: https://vps.incomexsaigoncorp.vn/ui-preview/mow/unified-canvas/v1/
review_log: knowledge/dev/ui/mow/unified-canvas/review-log.md
migrated_from: knowledge/dev/ui/mow-unified-canvas-handoff-pack-v1.md
created_by: claude_code
created_at: 2026-05-29

Canonical technical source of truth for the MOW Unified Canvas surface. This file is the structured migration of the flat handoff pack knowledge/dev/ui/mow-unified-canvas-handoff-pack-v1.md. The visual source of truth is the static preview at the preview_url above. Google Drive remains the human/Cowork drafting channel.

Reading guide

  • Claude Code CLI: Component 3 (Data Contract) + Component 4 (DOT Actions) + Component 6 (Constraints)
  • Claude Design: Component 1 (UI Intent) + Component 2 (Interaction Model) + Component 5 (Visual Reference) + Component 6
  • GPT: whole document — architecture-consistency reviewer
  • Cowork: author — updates on change

COMPONENT 1 — UI Intent

Triết lý cốt lõi: MỘT khuôn UI duy nhất — SÁU tầng dữ liệu. Dữ liệu thay đổi khi đổi tầng; khuôn UI không đổi.

T6 Lĩnh vực   → các ô = Công ty
T5 Công ty    → các ô = Phòng ban
T4 Phòng ban  → các ô = Chuyên môn
T3 Chuyên môn → các ô = Nhiệm vụ/Workflow   ← default view
T2 Nhiệm vụ   → các ô = Task
T1 Task       → mở MOT Task Card

Màn hình DÙNG để: đọc cấu trúc quy trình theo tầng; drill-down T6→T1; đề xuất thay đổi qua Proposal Mode (Kaizen); xem trạng thái (traffic light). Màn hình KHÔNG dùng để: sửa trực tiếp workflow/DB; chứa business logic; hardcode tên tầng/quy trình/task.

COMPONENT 2 — Interaction Model

  • Tab navigation: click T6/T5/T4/T3/T2/T1 → canvas hiện nodes của tầng đó. Tab active = tầng đang xem. Badge = số items.
  • Breadcrumb: Lĩnh vực > Công ty > Phòng ban > Chuyên môn > (hiện tại). Click crumb → quay lên tầng đó.
  • Node card: click → drill-down xuống tầng con. Hiển thị: số thứ tự + tên + progress + traffic light + sub-list (max 3 + "··· +N").
  • Proposal Mode: nút "Đề xuất cải tiến" góc phải. Khi bật: toggle pill vàng/đỏ (sửa/xóa) trên mỗi card; nút "+" xanh giữa cards; "+ Thêm nhiệm vụ" cuối sub-list. Mọi action → tạo proposal, KHÔNG sửa DB trực tiếp.
  • Instance Mode: khi xem instance đang chạy: traffic light theo 9-state; progress bar; assignee avatar + SLA countdown.
  • Click T1: không drill-down — mở MOT Task Card (slide-in panel hoặc modal).

COMPONENT 3 — Data Contract

CanvasNode

CanvasNode:
  id: uuid
  code: string              # "NV01", "T03", "PB002"
  title: string
  tier: T1|T2|T3|T4|T5|T6
  parent_id: uuid|null
  order_index: integer
  status: draft|active|deprecated
  traffic_light: green|yellow|red|gray
  child_count: integer
  child_preview:            # max 3 items
    - code: string
      title: string
      status: string
      traffic_light: green|yellow|red|gray
  automation_level: full_auto|agent_in_loop|human_in_loop|manual|null
  workflow_ref: uuid|null
  task_type_ref: uuid|null
  iu_ref: string|null
  proposal_count: integer
  permission_actions: [view, propose, admin]
  instance_data:            # chỉ có khi view_mode=instance
    instance_id: uuid|null
    assignee_avatar: string|null
    assignee_name: string|null
    sla_due_at: datetime|null
    sla_traffic_light: green|yellow|red
    progress_ratio: float   # 0.0-1.0
    state: created|assigned|in_progress|waiting_for_input|
           waiting_for_approval|completed|overdue|blocked|cancelled

CanvasContext

CanvasContext:
  active_tier: T1|T2|T3|T4|T5|T6
  breadcrumb:
    - tier: T6
      id: uuid
      code: string
      title: string
  current_node_id: uuid|null
  view_mode: template|instance
  proposal_mode: boolean
  instance_id: uuid|null

API Endpoints (qua Directus — Nuxt KHÔNG gọi PG trực tiếp)

GET  /api/canvas/nodes?tier={T}&parent_id={id}&view_mode={mode}   → CanvasNode[]
GET  /api/canvas/context?node_id={id}                              → CanvasContext
POST /api/canvas/proposals                                         → body: ProposalPayload

A concrete instance of this contract (mock) lives at the preview: ./mock-data.json, and is documented in knowledge/dev/ui/mow/unified-canvas/mock-data-contract.md.

COMPONENT 4 — DOT Actions (Điều 35)

DOT Purpose Verify against live
dot_mow_canvas_get_nodes nodes theo tier + parent dot_iu_command_catalog
dot_mow_canvas_get_context breadcrumb + context state catalog
dot_mow_design_propose_change tạo change proposal — KHÔNG edit trực tiếp; gate permission_action="propose"; reuse workflow_change_requests catalog
dot_mow_canvas_drill_down chuyển view xuống tầng con catalog
dot_mot_get_task_card full data cho MOT Task Card (T1) catalog

DOTs here are spec-only until ratified against dot_iu_command_catalog (per Đ35 / handoff pack note).

COMPONENT 5 — Visual Reference

PHU-LUC files (Google Drive — owner-private)

File Drive ID Use
PHU-LUC-A — MOW Normal + Proposal 1uy16CJ3lmH6llDroV18Gy5ZbAyH6cJaB canvas style, tabs T6→T1, step boxes, arrows
PHU-LUC-C — Proposal Flow v2 1hxm3qBYc1uZF1-ayGaFx3Im1k7F3zC1mABMskpuekSs proposal mode — toggle pill, "+" nút, form đề xuất
PHU-LUC-D — MOT Task Card 1btm_SHoZUk1n2SDK3QgKzOaY-F5BHbWg_0zfvlGlKNE 9-state badge, progressive disclosure layout
PHU-LUC-E — MOW TreeView 1wrIByOIyzodxJsRUwv2K0b5ER1z8NmZD4ymoA split-view layout, tree navigation

Access note: these are stored as text/plain HTML, shared owner-only. They were read-extracted; the static preview's index.html faithfully reproduces PHU-LUC-A's structure. To host them verbatim, set Drive sharing to "anyone with link" and re-run deploy.

Design Tokens

--accent: #639922;  --accent-dark: #3b6d11;  --accent-light: #eaf3de;
--warn: #ef9f27;    --danger: #e24b4a;       --neutral-bg: #f0f0f0;
font: system-ui / Be Vietnam Pro ; mono: JetBrains Mono

Traffic Light (Master Design Rev2)

green  → completed / on-track / active / ok
yellow → in_progress / warning / sắp hạn
red    → overdue / blocked / error / failed
gray   → created / pending / chưa active
blue   → assigned / waiting_for_input
orange → waiting_for_approval

Style direction: Clean & dense — enterprise SaaS (Linear, Retool). KHÔNG spacious/calm kiểu Notion, KHÔNG industrial kiểu CAD. Card: radius 10px, border 0.5px, white bg. Theme: LIGHT (desktop-first).

COMPONENT 6 — Constraints

Claude Code CLI KHÔNG được: viết Nuxt component custom cho canvas; hardcode tier/quy trình/task trong code; query PG trực tiếp từ Nuxt; tạo bảng mới ngoài registry (reuse-first); bật vector realtime; business logic trong Nuxt/Vue; tạo DOT khi DOT tương đương đã có.

Claude Design KHÔNG được: thay đổi triết lý "một khuôn, sáu tầng"; bỏ tab T6→T1; bỏ breadcrumb; bỏ Proposal Mode; thêm nút "Sửa trực tiếp"; hardcode tên tầng/quy trình; thêm business logic; đổi traffic-light colors; mobile-first trước khi desktop xong.

Mọi agent KHÔNG được: implement UI Nuxt trước khi live PG survey xong; sửa trực tiếp workflow/task trong DB; dùng Lark làm canonical store; bỏ IU ref; tạo bot/agent ngoài "For Gem".

Pipeline status

Component Status
UI Intent ✅ Chốt
Interaction Model ✅ Chốt
Data Contract 🟡 Draft — cần Code verify vs live PG
DOT Actions 🟡 Draft — cần Code verify vs catalog
Visual Reference ✅ PHU-LUC A/C/D/E (read-extracted)
Constraints ✅ Chốt
Static preview ✅ Deployed (this surface) — pending_user_review
Live PG survey 🔴 BLOCKING for backend contract validation
Nuxt shell 🔴 only after user approval (Đ28)