pos-system/docs/vi/guides/mermaid.md

# 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

```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
```

**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**:
````markdown
```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

```mermaid
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

```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}
```

**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**:
````markdown
```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

```mermaid
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

```mermaid
%%{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

```mermaid
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

```mermaid
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

```mermaid
%%{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

```mermaid
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

```mermaid
%%{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:

```mermaid
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):**
```markdown
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):**
```markdown
style Decision fill:#E67E22,color:#ECF0F1,stroke:#D35400,stroke-width:2px
```

**Error Nodes (Lỗi):**
```markdown
style Error fill:#C0392B,color:#ECF0F1,stroke:#A93226,stroke-width:2px
```

**Processing Nodes (Xử lý):**
```markdown
style Process fill:#8E44AD,color:#ECF0F1,stroke:#7D3C98,stroke-width:2px
```

**Data/Storage Nodes (Dữ liệu/Lưu trữ):**
```markdown
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):**
```markdown
style Gateway fill:#3498DB,color:#ECF0F1,stroke:#2980B9,stroke-width:3px
```

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

```mermaid
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

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

**Template Mẫu:**
```markdown
style NodeName fill:#2C3E50,color:#ECF0F1,stroke:#34495E,stroke-width:2px
```

---

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

1. **Giữ đơn giản**: Đừng làm phức tạp sơ đồ quá mức
2. **Sử dụng Styling nhất quán**: Áp dụng bảng màu tối nhất quán
3. **Thêm Chú giải**: Giải thích ký hiệu và màu sắc khi cần
4. **Giới hạn Độ phức tạp**: Chia thành nhiều sơ đồ nếu quá phức tạp
5. **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

```mermaid
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

```mermaid
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:

```bash
# 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
```markdown
 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
```markdown
 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
```markdown
 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
```markdown
 SAI:
subgraph "My Group"
A --> B
end

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

### Quick Color Pattern Reference

**Copy-paste Templates:**

```markdown
<!-- 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:**

```mermaid
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:**

```mermaid
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](https://mermaid.js.org/) - Tài liệu chính thức
- [Mermaid Live Editor](https://mermaid.live/) - Test sơ đồ online
- [Mermaid CheatSheet](https://jojozhuang.github.io/tutorial/mermaid-cheat-sheet/) - Tham chiếu nhanh

---

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