Files

Ho Ngoc Hai 76d75c753b Migrate

2026-05-23 18:37:02 +07:00

24 KiB

Raw Permalink Blame History

Hướng dẫn Sơ đồ Mermaid

Tổng quan

Hướng dẫn này giúp bạn chọn loại sơ đồ Mermaid phù hợp cho tài liệu của bạn và cung cấp ví dụ cho các trường hợp sử dụng phổ biến.

Tham chiếu Nhanh

Loại Sơ đồ	Sử dụng cho	Độ phức tạp
Flowchart	Quy trình, cây quyết định
Sequence Diagram	Tương tác API, luồng request
Class Diagram	Cấu trúc code, patterns
Graph	Kiến trúc hệ thống, dependencies
ER Diagram	Schema database
Gantt	Timeline, lịch trình dự án
C4 Diagram	Bối cảnh hệ thống, containers

1. Sơ đồ Luồng (Flowcharts)

Khi nào sử dụng

Sử dụng flowcharts cho:

Hướng dẫn từng bước và quy trình (ví dụ: Quy trình đăng ký tài khoản)
Cây quyết định và logic điều kiện (ví dụ: Luồng phê duyệt đơn hàng)
Luồng quy trình với nhiều nhánh (ví dụ: Xử lý thanh toán đa kênh)
Thủ tục khắc phục sự cố (ví dụ: Các bước debug lỗi server)

Basic Flowchart

flowchart TD
 Start([Start]) --> Input[Get Input]
 Input --> Check{Valid?}
 Check -->|Yes| Process[Process Data]
 Check -->|No| Error[Show Error]
 Process --> Output[Return Result]
 Output --> End([End])
 Error --> End

 style Start fill:#2C3E50,color:#ECF0F1,stroke:#34495E,stroke-width:3px
 style End fill:#27AE60,color:#ECF0F1,stroke:#229954,stroke-width:3px
 style Check fill:#E67E22,color:#ECF0F1,stroke:#D35400,stroke-width:2px
 style Error fill:#C0392B,color:#ECF0F1,stroke:#A93226,stroke-width:2px
 style Input fill:#8E44AD,color:#ECF0F1,stroke:#7D3C98,stroke-width:2px
 style Process fill:#8E44AD,color:#ECF0F1,stroke:#7D3C98,stroke-width:2px
 style Output fill:#8E44AD,color:#ECF0F1,stroke:#7D3C98,stroke-width:2px

Giải thích: Sơ đồ này minh họa quy trình từ lúc Bắt đầu -> Nhận đầu vào -> Kiểm tra tính hợp lệ -> Xử lý (nếu hợp lệ) hoặc Báo lỗi (nếu không) -> Kết thúc.

Code:

```mermaid
flowchart TD
 Start([Start]) --> Input[Get Input]
 Input --> Check{Valid?}
 Check -->|Yes| Process[Process Data]
 Check -->|No| Error[Show Error]
 Process --> Output[Return Result]
 Output --> End([End])
 Error --> End

 style Start fill:#2C3E50,color:#ECF0F1,stroke:#34495E,stroke-width:3px
 style End fill:#27AE60,color:#ECF0F1,stroke:#229954,stroke-width:3px
 style Check fill:#E67E22,color:#ECF0F1,stroke:#D35400,stroke-width:2px
 style Error fill:#C0392B,color:#ECF0F1,stroke:#A93226,stroke-width:2px
 style Input fill:#8E44AD,color:#ECF0F1,stroke:#7D3C98,stroke-width:2px
 style Process fill:#8E44AD,color:#ECF0F1,stroke:#7D3C98,stroke-width:2px
 style Output fill:#8E44AD,color:#ECF0F1,stroke:#7D3C98,stroke-width:2px
```

Advanced Flowchart with Subgraphs

flowchart LR
 A[Client Request] --> B{Auth?}
 B -->|No| C[401 Unauthorized]
 B -->|Yes| D[Process]

 subgraph Processing["Request Processing"]
 D --> E[Validate Input]
 E --> F[Execute Logic]
 F --> G[Format Response]
 end

 G --> H[Return 200 OK]
 C --> I[End]
 H --> I

 style A fill:#3498DB,color:#ECF0F1,stroke:#2980B9,stroke-width:2px
 style B fill:#E67E22,color:#ECF0F1,stroke:#D35400,stroke-width:2px
 style C fill:#C0392B,color:#ECF0F1,stroke:#A93226,stroke-width:2px
 style D fill:#8E44AD,color:#ECF0F1,stroke:#7D3C98,stroke-width:2px
 style E fill:#8E44AD,color:#ECF0F1,stroke:#7D3C98,stroke-width:2px
 style F fill:#8E44AD,color:#ECF0F1,stroke:#7D3C98,stroke-width:2px
 style G fill:#8E44AD,color:#ECF0F1,stroke:#7D3C98,stroke-width:2px
 style H fill:#27AE60,color:#ECF0F1,stroke:#229954,stroke-width:2px
 style I fill:#7F8C8D,color:#ECF0F1,stroke:#5D6D7E,stroke-width:2px
 style Processing fill:#2C3E50,color:#ECF0F1,stroke:#34495E,stroke-width:2px

Giải thích: Sơ đồ này cho thấy quy trình xử lý request phức tạp hơn với các logic nhóm trong subgraph. Nếu Auth thất bại, trả về 401. Nếu thành công, tiếp tục xử lý, validate, chạy logic, format và trả về 200 OK.

2. Sơ đồ Tuần tự (Sequence Diagrams)

Khi nào sử dụng

Sử dụng sequence diagrams cho:

Luồng giao tiếp API (ví dụ: API tạo đơn hàng mới)
Luồng xác thực/phân quyền (ví dụ: Luồng đăng nhập và cấp Token)
Tương tác giữa các service (ví dụ: Order Service gọi Inventory Service)
Chu kỳ request/response (ví dụ: Xử lý Request trả về JSON)

Basic Sequence Diagram

sequenceDiagram
 participant Client
 participant API
 participant Service
 participant DB

 Client->>API: POST /login
 API->>Service: authenticate(credentials)
 Service->>DB: findUser(email)
 DB-->>Service: user
 Service->>Service: verifyPassword()
 Service-->>API: JWT token
 API-->>Client: 200 OK {token}

Giải thích: Sơ đồ tuần tự mô tả luồng đăng nhập: Client gửi thông tin -> API gọi Service -> Service kiểm tra DB -> DB trả về User -> Service xác thực pass -> Service trả Token -> API trả về cho Client.

Code:

```mermaid
sequenceDiagram
 participant Client
 participant API
 participant Service
 participant DB

 Client->>API: POST /login
 API->>Service: authenticate(credentials)
 Service->>DB: findUser(email)
 DB-->>Service: user
 Service->>Service: verifyPassword()
 Service-->>API: JWT token
 API-->>Client: 200 OK {token}
```

Advanced with Alt/Opt/Loop

sequenceDiagram
 participant Client
 participant API
 participant Cache
 participant DB

 Client->>API: GET /users/:id
 API->>Cache: get(key)

 alt Cache Hit
 Cache-->>API: cached data
 API-->>Client: 200 OK (from cache)
 else Cache Miss
 Cache-->>API: null
 API->>DB: SELECT * FROM users
 DB-->>API: user data
 API->>Cache: set(key, data, ttl)
 API-->>Client: 200 OK (from DB)
 end

Giải thích: Sơ đồ này sử dụng khối alt để mô tả logic rẽ nhánh: Nếu có Cache (Cache Hit) thì trả về ngay. Nếu không (Cache Miss) thì query DB, lưu vào Cache rồi mới trả về.

3. Sơ đồ Class (Class Diagrams)

Khi nào sử dụng

Sử dụng class diagrams cho:

Design patterns và cấu trúc code (ví dụ: Singleton Pattern cho Logger)
Kiến trúc hướng đối tượng (ví dụ: Cấu trúc Class User và Admin)
Kế thừa và mối quan hệ (ví dụ: BaseRepository và UserRepository)
Dependencies giữa các module (ví dụ: PaymentModule phụ thuộc OrderModule)

Basic Class Diagram

%%{init: {'theme':'dark'}}%%
classDiagram
 class BaseRepository {
 #prisma: PrismaClient
 #modelName: string
 +findById(id: string) T
 +findAll(options: QueryOptions) T[]
 +create(data: CreateDto) T
 +update(id: string, data: UpdateDto) T
 +delete(id: string) void
 }

 class UserRepository {
 +findByEmail(email: string) User
 +findByUsername(username: string) User
 }

 class FeatureRepository {
 +findByName(name: string) Feature
 +toggleStatus(id: string) Feature
 }

 BaseRepository <|-- UserRepository
 BaseRepository <|-- FeatureRepository

Giải thích: Sơ đồ Class thể hiện mối quan hệ kế thừa (<|--): UserRepository và FeatureRepository đều kế thừa từ BaseRepository, tận dụng các phương thức chung như findById, create.

4. Sơ đồ Graph (Graph Diagrams)

Khi nào sử dụng

Sử dụng graph diagrams cho:

Tổng quan kiến trúc hệ thống (ví dụ: Kiến trúc Microservices)
Mối quan hệ giữa các thành phần (ví dụ: Web Client kết nối Gateway)
Sơ đồ luồng dữ liệu (ví dụ: Dữ liệu từ API xuống Database)
Đồ thị dependencies (ví dụ: Các gói npm phụ thuộc lẫn nhau)

System Architecture

graph TD
 Client[Web Client] --> Gateway[Traefik Gateway]
 Gateway --> Auth[Auth Service]
 Gateway --> IAM[IAM Service]
 Gateway --> User[User Service]

 Auth --> DB[(PostgreSQL)]
 IAM --> DB
 User --> DB

 Auth --> Cache[(Redis)]
 IAM --> Cache
 User --> Cache

 style Client fill:#3498DB,color:#ECF0F1,stroke:#2980B9,stroke-width:2px
 style Gateway fill:#3498DB,color:#ECF0F1,stroke:#2980B9,stroke-width:3px
 style Auth fill:#8E44AD,color:#ECF0F1,stroke:#7D3C98,stroke-width:2px
 style IAM fill:#8E44AD,color:#ECF0F1,stroke:#7D3C98,stroke-width:2px
 style User fill:#8E44AD,color:#ECF0F1,stroke:#7D3C98,stroke-width:2px
 style DB fill:#34495E,color:#ECF0F1,stroke:#2C3E50,stroke-width:2px
 style Cache fill:#34495E,color:#ECF0F1,stroke:#2C3E50,stroke-width:2px

Giải thích: Sơ đồ kiến trúc tổng quan: Web Client đi qua Traefik Gateway, sau đó được điều hướng đến các microservices (Auth, IAM, User). Các service này đều kết nối đến Database chung và Redis Cache.

Data Flow

graph LR
 Input[User Input] --> Validation[Zod Validation]
 Validation --> Controller[Controller]
 Controller --> Service[Service Layer]
 Service --> Repository[Repository]
 Repository --> Prisma[Prisma ORM]
 Prisma --> DB[(Database)]

 Service --> Cache[Cache Service]
 Cache --> Redis[(Redis)]

 style Input fill:#3498DB,color:#ECF0F1,stroke:#2980B9,stroke-width:2px
 style Validation fill:#27AE60,color:#ECF0F1,stroke:#229954,stroke-width:2px
 style Controller fill:#8E44AD,color:#ECF0F1,stroke:#7D3C98,stroke-width:2px
 style Service fill:#8E44AD,color:#ECF0F1,stroke:#7D3C98,stroke-width:2px
 style Repository fill:#8E44AD,color:#ECF0F1,stroke:#7D3C98,stroke-width:2px
 style Prisma fill:#8E44AD,color:#ECF0F1,stroke:#7D3C98,stroke-width:2px
 style DB fill:#34495E,color:#ECF0F1,stroke:#2C3E50,stroke-width:2px
 style Cache fill:#8E44AD,color:#ECF0F1,stroke:#7D3C98,stroke-width:2px
 style Redis fill:#34495E,color:#ECF0F1,stroke:#2C3E50,stroke-width:2px

Giải thích: Sơ đồ luồng dữ liệu chi tiết: Input đi qua lớp Validation -> Controller -> Service -> Repository -> ORM -> DB. Đồng thời Service cũng tương tác với Cache.

5. Sơ đồ ER (ER Diagrams)

Khi nào sử dụng

Sử dụng ER diagrams cho:

Tài liệu schema database
Mối quan hệ giữa các entity
Mô hình dữ liệu
Visualization Prisma schema

Database Schema

%%{init: {'theme':'dark'}}%%
erDiagram
 User ||--o{ Session : has
 User ||--o{ RefreshToken : has
 User ||--o{ UserRole : has
 Role ||--o{ UserRole : has
 Role ||--o{ RolePermission : has
 Permission ||--o{ RolePermission : has

 User {
 string id PK
 string email UK
 string passwordHash
 boolean mfaEnabled
 datetime createdAt
 datetime updatedAt
 }

 Session {
 string id PK
 string userId FK
 string token UK
 string deviceId
 string ipAddress
 datetime expiresAt
 }

 Role {
 string id PK
 string name UK
 string description
 datetime createdAt
 }

 Permission {
 string id PK
 string code UK
 string resource
 string action
 string scope
 }

Giải thích: Sơ đồ ER mô tả quan hệ thực thể: Một User có nhiều Session, RefreshToken và UserRole. Quan hệ ||--o{ nghĩa là "một-nhiều".

6. Biểu đồ Gantt (Gantt Charts)

Khi nào sử dụng

Sử dụng Gantt charts cho:

Timeline dự án
Các giai đoạn triển khai
Lịch trình migration
Kế hoạch deployment

Project Timeline

gantt
 title Documentation Update Project Timeline
 dateFormat YYYY-MM-DD
 section Phase 1
 Analysis & Research :done, p1, 2024-01-01, 1d
 section Phase 2
 Templates & Strategy :active, p2, 2024-01-02, 0.5d
 section Phase 3
 High Priority Docs :p3, 2024-01-03, 2d
 section Phase 4
 Remaining Docs :p4, 2024-01-05, 3d
 section Phase 5
 QA & Verification :p5, 2024-01-08, 1d

Giải thích: Biểu đồ Gantt giúp theo dõi tiến độ dự án theo thời gian. Các thanh màu thể hiện trạng thái: done (đã xong), active (đang làm), hoặc chưa làm.

7. Sơ đồ C4 (C4 Diagrams)

Khi nào sử dụng

Sử dụng C4 diagrams cho:

Bối cảnh hệ thống (cấp cao nhất)
Sơ đồ container (services, databases)
Sơ đồ component (modules trong services)
Sơ đồ code (classes, functions)

System Context

%%{init: {'theme':'dark'}}%%
C4Context
 title System Context Diagram for IAM System

 Person(user, "User", "System user needing authentication")
 Person(admin, "Admin", "System administrator")

 System(iam, "IAM System", "Identity and Access Management")

 System_Ext(email, "Email Service", "SendGrid/AWS SES")
 System_Ext(oauth, "OAuth Providers", "Google, Facebook, GitHub")

 Rel(user, iam, "Authenticates with", "HTTPS")
 Rel(admin, iam, "Manages users and permissions", "HTTPS")
 Rel(iam, email, "Sends emails", "SMTP/API")
 Rel(iam, oauth, "OAuth login", "OAuth 2.0")

Giải thích: Sơ đồ C4 Context cho thấy bối cảnh hệ thống ở mức cao nhất: Người dùng và Admin tương tác với IAM System. Hệ thống này lại tương tác với các hệ thống bên ngoài như Email Service và OAuth Providers.

Bảng màu Tối (Dark Color Palette)

Tham chiếu Bảng màu Đầy đủ

Sử dụng bảng màu tối để tạo sơ đồ có độ tương phản cao và dễ đọc trong môi trường ánh sáng yếu:

graph LR
 A[" Primary<br/>#2C3E50"] --> B[" Data/Cache<br/>#34495E"]
 B --> C[" Success<br/>#27AE60"]
 C --> D[" Warning<br/>#E67E22"]
 D --> E[" Error<br/>#C0392B"]
 E --> F[" Processing<br/>#8E44AD"]
 F --> G["ℹ Info<br/>#3498DB"]
 G --> H[" Neutral<br/>#7F8C8D"]

 style A fill:#2C3E50,color:#ECF0F1,stroke:#34495E,stroke-width:2px
 style B fill:#34495E,color:#ECF0F1,stroke:#2C3E50,stroke-width:2px
 style C fill:#27AE60,color:#ECF0F1,stroke:#229954,stroke-width:2px
 style D fill:#E67E22,color:#ECF0F1,stroke:#D35400,stroke-width:2px
 style E fill:#C0392B,color:#ECF0F1,stroke:#A93226,stroke-width:2px
 style F fill:#8E44AD,color:#ECF0F1,stroke:#7D3C98,stroke-width:2px
 style G fill:#3498DB,color:#ECF0F1,stroke:#2980B9,stroke-width:2px
 style H fill:#7F8C8D,color:#ECF0F1,stroke:#5D6D7E,stroke-width:2px

Bảng Màu Chi tiết

Màu	Mã Hex	Sử dụng cho	Màu Viền	Màu Chữ
Primary	`#2C3E50`	Node chính, bắt đầu, khối chính	`#34495E`	`#ECF0F1`
Data/Cache	`#34495E`	Database, Cache, Storage	`#2C3E50`	`#ECF0F1`
Success	`#27AE60`	Kết thúc thành công, xác nhận	`#229954`	`#ECF0F1`
Warning	`#E67E22`	Cảnh báo, điều kiện quan trọng	`#D35400`	`#ECF0F1`
Error	`#C0392B`	Lỗi, thất bại, hủy bỏ	`#A93226`	`#ECF0F1`
Processing	`#8E44AD`	Xử lý, quá trình chạy	`#7D3C98`	`#ECF0F1`
ℹ Info	`#3498DB`	Thông tin, ghi chú	`#2980B9`	`#ECF0F1`
Neutral	`#7F8C8D`	Trung lập, không ưu tiên	`#5D6D7E`	`#ECF0F1`

Checklist Áp dụng Màu

Nguyên tắc Cơ bản:

Sử dụng màu tối cho nền (dark background)
Màu chữ sáng (#ECF0F1 hoặc #fff) để tạo tương phản
Viền tối hơn nền một chút để tạo chiều sâu
Độ dày viền: 2px hoặc 3px

Pattern theo Loại Node:

Start/End Nodes (Bắt đầu/Kết thúc):

style Start fill:#2C3E50,color:#ECF0F1,stroke:#34495E,stroke-width:3px
style End fill:#27AE60,color:#ECF0F1,stroke:#229954,stroke-width:3px

Decision Nodes (Quyết định):

style Decision fill:#E67E22,color:#ECF0F1,stroke:#D35400,stroke-width:2px

Error Nodes (Lỗi):

style Error fill:#C0392B,color:#ECF0F1,stroke:#A93226,stroke-width:2px

Processing Nodes (Xử lý):

style Process fill:#8E44AD,color:#ECF0F1,stroke:#7D3C98,stroke-width:2px

Data/Storage Nodes (Dữ liệu/Lưu trữ):

style DB fill:#34495E,color:#ECF0F1,stroke:#2C3E50,stroke-width:2px
style Cache fill:#34495E,color:#ECF0F1,stroke:#2C3E50,stroke-width:2px

Gateway/API Nodes (Gateway/API):

style Gateway fill:#3498DB,color:#ECF0F1,stroke:#2980B9,stroke-width:3px

Ví dụ Áp dụng Đầy đủ

flowchart TD
 Start([Bắt đầu]) --> Auth{Xác thực?}
 Auth -->|Không| Error[Lỗi 401]
 Auth -->|Có| Process[Xử lý Request]
 Process --> DB[(Database)]
 DB --> Cache[(Redis Cache)]
 Cache --> Success[Thành công]
 Error --> End([Kết thúc])
 Success --> End

 style Start fill:#2C3E50,color:#ECF0F1,stroke:#34495E,stroke-width:3px
 style Auth fill:#E67E22,color:#ECF0F1,stroke:#D35400,stroke-width:2px
 style Error fill:#C0392B,color:#ECF0F1,stroke:#A93226,stroke-width:2px
 style Process fill:#8E44AD,color:#ECF0F1,stroke:#7D3C98,stroke-width:2px
 style DB fill:#34495E,color:#ECF0F1,stroke:#2C3E50,stroke-width:2px
 style Cache fill:#34495E,color:#ECF0F1,stroke:#2C3E50,stroke-width:2px
 style Success fill:#27AE60,color:#ECF0F1,stroke:#229954,stroke-width:2px
 style End fill:#27AE60,color:#ECF0F1,stroke:#229954,stroke-width:3px

Cú pháp Style

style NodeId fill:#colorcode,color:#textcolor,stroke:#bordercolor,stroke-width:2px

Template Mẫu:

style NodeName fill:#2C3E50,color:#ECF0F1,stroke:#34495E,stroke-width:2px

Thực hành Tốt nhất

Giữ đơn giản: Đừng làm phức tạp sơ đồ quá mức
Sử dụng Styling nhất quán: Áp dụng bảng màu tối nhất quán
Thêm Chú giải: Giải thích ký hiệu và màu sắc khi cần
Giới hạn Độ phức tạp: Chia thành nhiều sơ đồ nếu quá phức tạp
Test Rendering: Luôn test sơ đồ render chính xác với dark theme

Cạm bẫy Thường gặp

Too Complex

graph TD
 A --> B
 A --> C
 B --> D
 B --> E
 C --> F
 C --> G
 D --> H
 E --> H
 F --> I
 G --> I
 H --> J
 I --> J

 style A fill:#E67E22,color:#ECF0F1,stroke:#D35400,stroke-width:2px
 style B fill:#8E44AD,color:#ECF0F1,stroke:#7D3C98,stroke-width:2px
 style C fill:#8E44AD,color:#ECF0F1,stroke:#7D3C98,stroke-width:2px
 style D fill:#8E44AD,color:#ECF0F1,stroke:#7D3C98,stroke-width:2px
 style E fill:#8E44AD,color:#ECF0F1,stroke:#7D3C98,stroke-width:2px
 style F fill:#8E44AD,color:#ECF0F1,stroke:#7D3C98,stroke-width:2px
 style G fill:#8E44AD,color:#ECF0F1,stroke:#7D3C98,stroke-width:2px
 style H fill:#8E44AD,color:#ECF0F1,stroke:#7D3C98,stroke-width:2px
 style I fill:#8E44AD,color:#ECF0F1,stroke:#7D3C98,stroke-width:2px
 style J fill:#C0392B,color:#ECF0F1,stroke:#A93226,stroke-width:2px

Simplified with Subgraphs

graph TD
 A[Start] --> B[Process A]
 B --> C[Process B]

 subgraph DetailedProcessing["Detailed Processing"]
 C --> D[Step 1]
 D --> E[Step 2]
 end

 E --> F[End]

 style A fill:#2C3E50,color:#ECF0F1,stroke:#34495E,stroke-width:3px
 style B fill:#8E44AD,color:#ECF0F1,stroke:#7D3C98,stroke-width:2px
 style C fill:#8E44AD,color:#ECF0F1,stroke:#7D3C98,stroke-width:2px
 style D fill:#8E44AD,color:#ECF0F1,stroke:#7D3C98,stroke-width:2px
 style E fill:#8E44AD,color:#ECF0F1,stroke:#7D3C98,stroke-width:2px
 style F fill:#27AE60,color:#ECF0F1,stroke:#229954,stroke-width:3px
 style DetailedProcessing fill:#2C3E50,color:#ECF0F1,stroke:#34495E,stroke-width:2px

Kiểm tra Sơ đồ

Luôn test sơ đồ trước khi commit:

# Install mermaid-cli
npm install -g @mermaid-js/mermaid-cli

# Test render (SVG)
mmdc -i your-doc.md -o test-output.svg

# Render PNG chất lượng cao, nền đen
mmdc -i your-doc.md -o test-output.png -b black -t dark -s 3

# Render TOÀN BỘ sơ đồ trong file markdown
mmdc -i your-doc.md

# Giải thích các tham số:
# -i: File đầu vào (.md hoặc .mmd)
# -o: File đầu ra (định dạng dựa trên đuôi .svg, .png, .pdf)
# -b: Màu nền (hex code hoặc tên màu như black, white, transparent)
# -t: Theme (default, forest, dark, neutral)
# -s: Scale (tăng độ phân giải, ví dụ: 3 cho ảnh nét hơn)

Quick Tips

Lỗi Mermaid Thường gặp

1. Lỗi Cú pháp

Vấn đề: Sơ đồ không render

 SAI: flowchart TD A -> B
 ĐÚNG: flowchart TD
 A --> B

Nguyên nhân:

Thiếu xuống dòng sau khai báo loại diagram
Sử dụng -> thay vì -->
Thiếu khoảng trắng đúng

2. Lỗi Node ID

Vấn đề: Node ID trùng lặp

 SAI:
graph TD
 A[Start]
 A[Process] <!-- Trùng ID -->

 ĐÚNG:
graph TD
 A[Start]
 B[Process]

3. Lỗi Style

Vấn đề: Style không áp dụng

 SAI: style Node fill:#2C3E50 <!-- Thiếu dấu phẩy -->

 ĐÚNG: style Node fill:#2C3E50,color:#ECF0F1

4. Lỗi Subgraph

Vấn đề: Subgraph không hiển thị đúng

 SAI:
subgraph "My Group"
A --> B
end

 ĐÚNG:
subgraph MyGroup["My Group"]
 A --> B
end

Quick Color Pattern Reference

Copy-paste Templates:

<!-- Start Node (Dark Theme) -->
style Start fill:#2C3E50,color:#ECF0F1,stroke:#34495E,stroke-width:3px

<!-- Success Node -->
style Success fill:#27AE60,color:#ECF0F1,stroke:#229954,stroke-width:2px

<!-- Error Node -->
style Error fill:#C0392B,color:#ECF0F1,stroke:#A93226,stroke-width:2px

<!-- Decision Node -->
style Decision fill:#E67E22,color:#ECF0F1,stroke:#D35400,stroke-width:2px

<!-- Database/Cache -->
style DB fill:#34495E,color:#ECF0F1,stroke:#2C3E50,stroke-width:2px

<!-- Processing -->
style Process fill:#8E44AD,color:#ECF0F1,stroke:#7D3C98,stroke-width:2px

<!-- Info/Gateway -->
style Info fill:#3498DB,color:#ECF0F1,stroke:#2980B9,stroke-width:2px

Visual Indicators Guide

Sử dụng emoji để tăng khả năng đọc:

Emoji	Ý nghĩa	Sử dụng trong
	Start/Launch	Node bắt đầu
	Success	Node thành công
	Error/Failed	Node lỗi
	Warning	Decision nodes quan trọng
	Security/Auth	Authentication steps
	Database/Storage	Data nodes
	Processing	Processing nodes
ℹ	Information	Info nodes
	Sync/Update	Sync operations
	API/Network	External calls

Ví dụ sử dụng:

flowchart TD
 Start(["🚀 Bắt đầu"]) --> Auth{"🔐 Xác thực?"}
 Auth -->|"Không"| Error["❌ Lỗi"]
 Auth -->|"Có"| Process["⚙️ Xử lý"]
 Process --> DB[("💾 Database")]
 DB --> Success["✅ Thành công"]

 style Start fill:#2C3E50,color:#ECF0F1,stroke:#34495E,stroke-width:3px
 style Success fill:#27AE60,color:#ECF0F1,stroke:#229954,stroke-width:2px
 style Error fill:#C0392B,color:#ECF0F1,stroke:#A93226,stroke-width:2px
 style Auth fill:#E67E22,color:#ECF0F1,stroke:#D35400,stroke-width:2px
 style Process fill:#8E44AD,color:#ECF0F1,stroke:#7D3C98,stroke-width:2px
 style DB fill:#34495E,color:#ECF0F1,stroke:#2C3E50,stroke-width:2px

Troubleshooting Checklist

Khi sơ đồ không render:

Kiểm tra cú pháp: Có xuống dòng sau flowchart TD?
Kiểm tra arrow: Sử dụng --> không phải ->
Kiểm tra Node ID: Không có ID trùng lặp?
Kiểm tra Style: Có dấu phẩy giữa các thuộc tính?
Kiểm tra Subgraph: Sử dụng format subgraph ID["Label"]?
Kiểm tra Color: Hex code có dấu # phía trước?
Kiểm tra Special Characters: Tránh ký tự đặc biệt trong label

Diagram Selection Matrix

Chọn loại sơ đồ dựa trên mục đích:

flowchart TD
 Start{Bạn cần<br/>visualize gì?}

 Start -->|Quy trình| Flow[Flowchart ]
 Start -->|API/Giao tiếp| Seq[Sequence ]
 Start -->|Code Structure| Class[Class Diagram ]
 Start -->|Kiến trúc| Graph[Graph ]
 Start -->|Database| ER[ER Diagram ]
 Start -->|Timeline| Gantt[Gantt Chart ]
 Start -->|System Context| C4[C4 Diagram ]

 style Start fill:#E67E22,color:#ECF0F1,stroke:#D35400,stroke-width:2px
 style Flow fill:#3498DB,color:#ECF0F1,stroke:#2980B9,stroke-width:2px
 style Seq fill:#3498DB,color:#ECF0F1,stroke:#2980B9,stroke-width:2px
 style Class fill:#3498DB,color:#ECF0F1,stroke:#2980B9,stroke-width:2px
 style Graph fill:#3498DB,color:#ECF0F1,stroke:#2980B9,stroke-width:2px
 style ER fill:#3498DB,color:#ECF0F1,stroke:#2980B9,stroke-width:2px
 style Gantt fill:#3498DB,color:#ECF0F1,stroke:#2980B9,stroke-width:2px
 style C4 fill:#3498DB,color:#ECF0F1,stroke:#2980B9,stroke-width:2px

Tài nguyên

Mermaid Official Documentation - Tài liệu chính thức
Mermaid Live Editor - Test sơ đồ online
Mermaid CheatSheet - Tham chiếu nhanh

Tác giả: VelikHo (hongochai10@icloud.com)

24 KiB Raw Permalink Blame History Unescape Escape

Hướng dẫn Sơ đồ Mermaid

Tổng quan

Tham chiếu Nhanh

1. Sơ đồ Luồng (Flowcharts)

Khi nào sử dụng

Basic Flowchart

Advanced Flowchart with Subgraphs

2. Sơ đồ Tuần tự (Sequence Diagrams)

Khi nào sử dụng

Basic Sequence Diagram

Advanced with Alt/Opt/Loop

3. Sơ đồ Class (Class Diagrams)

Khi nào sử dụng

Basic Class Diagram

4. Sơ đồ Graph (Graph Diagrams)

Khi nào sử dụng

System Architecture

Data Flow

5. Sơ đồ ER (ER Diagrams)

Khi nào sử dụng

Database Schema

6. Biểu đồ Gantt (Gantt Charts)

Khi nào sử dụng

Project Timeline

7. Sơ đồ C4 (C4 Diagrams)

Khi nào sử dụng

System Context

Bảng màu Tối (Dark Color Palette)

Tham chiếu Bảng màu Đầy đủ

Bảng Màu Chi tiết

Checklist Áp dụng Màu

Ví dụ Áp dụng Đầy đủ

Cú pháp Style

Thực hành Tốt nhất

Cạm bẫy Thường gặp

Too Complex

Simplified with Subgraphs

Kiểm tra Sơ đồ

Quick Tips

Lỗi Mermaid Thường gặp

1. Lỗi Cú pháp

2. Lỗi Node ID

3. Lỗi Style

4. Lỗi Subgraph

Quick Color Pattern Reference

Visual Indicators Guide

Troubleshooting Checklist

Diagram Selection Matrix

Tài nguyên

24 KiB

Raw Permalink Blame History