feat(docs): Bổ sung các sơ đồ Mermaid mới, giải thích chi tiết và cập nhật kiểu dáng trong hướng dẫn.

docs/en/guides/mermaid.md

@@ -25,10 +25,10 @@
 ### When to Use / Khi nào sử dụng
 
 **EN**: Use flowcharts for:
-- Step-by-step guides and workflows
-- Decision trees and conditional logic
-- Process flows with multiple branches
-- Troubleshooting procedures
+- Step-by-step guides and workflows (e.g., **"Onboarding process"**)
+- Decision trees and conditional logic (e.g., **"Discount calculation"**)
+- Process flows with multiple branches (e.g., **"Order fulfillment"**)
+- Troubleshooting procedures (e.g., **"Login issue diagnosis"**)
 
 **VI**: Sử dụng flowcharts cho:
 - Hướng dẫn từng bước và quy trình
@@ -54,6 +54,8 @@ flowchart TD
     style Error fill:#f8d7da
 ```
 
+**Explanation**: A basic flowchart starting with an input, followed by a validation check. If valid, it proceeds to processing and returns a result; otherwise, it shows an error and ends.
+
 **Code**:
 ````markdown
 ```mermaid
@@ -94,6 +96,8 @@ flowchart LR
     style Processing fill:#f0e1ff
 ```
 
+**Explanation**: A flowchart featuring an authorization check and a dedicated **Subgraph** for detailed request processing steps.
+
 ---
 
 ## 2. Sequence Diagrams / Sơ đồ Tuần tự
@@ -101,10 +105,10 @@ flowchart LR
 ### When to Use / Khi nào sử dụng
 
 **EN**: Use sequence diagrams for:
-- API communication flows
-- Authentication/authorization flows
-- Service-to-service interactions
-- Request/response cycles
+- API communication flows (e.g., **"New order creation API"**)
+- Authentication/authorization flows (e.g., **"OAuth2 login flow"**)
+- Service-to-service interactions (e.g., **"Microservices sync/async calls"**)
+- Request/response cycles (e.g., **"Checkout process"**)
 
 **VI**: Sử dụng sequence diagrams cho:
 - Luồng giao tiếp API
@@ -130,6 +134,8 @@ sequenceDiagram
     API-->>Client: 200 OK {token}
 ```
 
+**Explanation**: A login sequence illustrating the interaction between the Client, API, Service Layer, and Database, including password verification.
+
 **Code**:
 ````markdown
 ```mermaid
@@ -173,6 +179,8 @@ sequenceDiagram
     end
 ```
 
+**Explanation**: A data retrieval sequence using **Alt/Else** blocks to handle both Cache Hit and Cache Miss scenarios.
+
 ---
 
 ## 3. Class Diagrams / Sơ đồ Class
@@ -180,10 +188,10 @@ sequenceDiagram
 ### When to Use / Khi nào sử dụng
 
 **EN**: Use class diagrams for:
-- Design patterns and code structure
-- Object-oriented architecture
-- Inheritance and relationships
-- Module dependencies
+- Design patterns and code structure (e.g., **"Singleton Pattern for Logger"**)
+- Object-oriented architecture (e.g., **"Domain-Driven Design (DDD) models"**)
+- Inheritance and relationships (e.g., **"Repository base and concrete classes"**)
+- Module dependencies (e.g., **"Service layer dependencies"**)
 
 **VI**: Sử dụng class diagrams cho:
 - Design patterns và cấu trúc code
@@ -219,6 +227,8 @@ classDiagram
     BaseRepository <|-- FeatureRepository
 ```
 
+**Explanation**: A class diagram showing inheritance relationships between a generic `BaseRepository` and specific repository implementations.
+
 ---
 
 ## 4. Graph Diagrams / Sơ đồ Graph
@@ -226,10 +236,10 @@ classDiagram
 ### When to Use / Khi nào sử dụng
 
 **EN**: Use graph diagrams for:
-- System architecture overview
-- Component relationships
-- Data flow diagrams
-- Dependency graphs
+- System architecture overview (e.g., **"Microservices Architecture"**)
+- Component relationships (e.g., **"Service-to-database mapping"**)
+- Data flow diagrams (e.g., **"Request processing pipeline"**)
+- Dependency graphs (e.g., **"Package to package dependencies"**)
 
 **VI**: Sử dụng graph diagrams cho:
 - Tổng quan kiến trúc hệ thống
@@ -250,15 +260,18 @@ graph TD
     IAM --> DB
     User --> DB
     
-    Auth --> Cache[(Redis)]
-    IAM --> Cache
     User --> Cache
     
-    style Gateway fill:#e1f5ff
-    style DB fill:#f0e1ff
-    style Cache fill:#fff4e1
+    style Gateway fill:#2980b9,stroke:#333,stroke-width:2px,color:#fff
+    style Auth fill:#8e44ad,stroke:#333,stroke-width:2px,color:#fff
+    style IAM fill:#8e44ad,stroke:#333,stroke-width:2px,color:#fff
+    style User fill:#8e44ad,stroke:#333,stroke-width:2px,color:#fff
+    style DB fill:#f39c12,stroke:#333,stroke-width:2px,color:#fff
+    style Cache fill:#f39c12,stroke:#333,stroke-width:2px,color:#fff
 ```
 
+**Explanation**: A high-level view of the system architecture showing how the Gateway routes requests to different services, all connected to a shared Database and Cache.
+
 ### Data Flow
 
 ```mermaid
@@ -270,14 +283,15 @@ graph LR
     Repository --> Prisma[Prisma ORM]
     Prisma --> DB[(Database)]
     
-    Service --> Cache[Cache Service]
     Cache --> Redis[(Redis)]
     
-    style Validation fill:#d4edda
-    style Service fill:#e1f5ff
-    style Cache fill:#fff4e1
+    style Validation fill:#27ae60,stroke:#333,stroke-width:2px,color:#fff
+    style Service fill:#2980b9,stroke:#333,stroke-width:2px,color:#fff
+    style Cache fill:#f39c12,stroke:#333,stroke-width:2px,color:#fff
 ```
 
+**Explanation**: A detailed data flow showing Input going through Validation -> Controller -> Service -> Repository -> ORM -> DB, while also interacting with the Cache.
+
 ---
 
 ## 5. ER Diagrams / Sơ đồ ER
@@ -285,10 +299,10 @@ graph LR
 ### When to Use / Khi nào sử dụng
 
 **EN**: Use ER diagrams for:
-- Database schema documentation
-- Entity relationships
-- Data modeling
-- Prisma schema visualization
+- Database schema documentation (e.g., **"User and IAM tables"**)
+- Entity relationships (e.g., **"One-to-many between User and Sessions"**)
+- Data modeling (e.g., **"Designing new feature entities"**)
+- Prisma schema visualization (e.g., **"Mapping code entities to DB tables"**)
 
 **VI**: Sử dụng ER diagrams cho:
 - Tài liệu schema database
@@ -341,6 +355,8 @@ erDiagram
     }
 ```
 
+**Explanation**: An Entity-Relationship diagram illustrating a typical IAM schema with Users, Sessions, Roles, and Permissions.
+
 ---
 
 ## 6. Gantt Charts / Biểu đồ Gantt
@@ -429,14 +445,16 @@ graph LR
     D --> E["Error<br/>#f8d7da"]
     E --> F["Info<br/>#f0e1ff"]
     
-    style A fill:#e1f5ff
-    style B fill:#fff4e1
-    style C fill:#d4edda
-    style D fill:#fff3cd
-    style E fill:#f8d7da
-    style F fill:#f0e1ff
+    style A fill:#2980B9,color:#fff
+    style B fill:#F39C12,color:#fff
+    style C fill:#27AE60,color:#fff
+    style D fill:#E67E22,color:#fff
+    style E fill:#C0392B,color:#fff
+    style F fill:#8E44AD,color:#fff
 ```
 
+**Explanation**: The recommended color palette for consistent diagram styling within the project.
+
 ### Style Syntax
 
 ```markdown
@@ -519,11 +537,21 @@ graph TD
 # Install mermaid-cli
 npm install -g @mermaid-js/mermaid-cli
 
-# Test render
+# Test render (SVG)
 mmdc -i your-doc.md -o test-output.svg
 
-# Check for errors
-echo $?  # Should be 0 if successful
+# Render high-quality PNG with black background
+mmdc -i your-doc.md -o test-output.png -b black -t dark -s 3
+
+# Render ALL diagrams in a markdown file
+mmdc -i your-doc.md
+
+# Parameter Explanations:
+# -i: Input file (.md or .mmd)
+# -o: Output file (format based on extension .svg, .png, .pdf)
+# -b: Background color (hex code or color names like black, white, transparent)
+# -t: Theme (default, forest, dark, neutral)
+# -s: Scale (increase resolution, e.g., 3 for sharper images)
 ```
 
 ---

docs/vi/guides/mermaid.md

@@ -31,10 +31,10 @@
 - Troubleshooting procedures
 
 **VI**: Sử dụng flowcharts cho:
-- Hướng dẫn từng bước và quy trình
-- Cây quyết định và logic điều kiện
-- Luồng quy trình với nhiều nhánh
-- Thủ tục khắc phục sự cố
+- 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
 
@@ -48,11 +48,14 @@ flowchart TD
     Output --> End([End])
     Error --> End
     
-    style Start fill:#e1f5ff
-    style End fill:#d4edda
-    style Check fill:#fff3cd
-    style Error fill:#f8d7da
+    style Start fill:#2980b9,stroke:#333,stroke-width:2px,color:#fff
+    style End fill:#27ae60,stroke:#333,stroke-width:2px,color:#fff
+    style Check fill:#f39c12,stroke:#333,stroke-width:2px,color:#fff
+    style Error fill:#c0392b,stroke:#333,stroke-width:2px,color:#fff
 ```
+    
+**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
@@ -66,10 +69,10 @@ flowchart TD
     Output --> End([End])
     Error --> End
     
-    style Start fill:#e1f5ff
-    style End fill:#d4edda
-    style Check fill:#fff3cd
-    style Error fill:#f8d7da
+    style Start fill:#2980b9,stroke:#333,stroke-width:2px,color:#fff
+    style End fill:#27ae60,stroke:#333,stroke-width:2px,color:#fff
+    style Check fill:#f39c12,stroke:#333,stroke-width:2px,color:#fff
+    style Error fill:#c0392b,stroke:#333,stroke-width:2px,color:#fff
 ```
 ````
 
@@ -94,6 +97,9 @@ flowchart LR
     style Processing fill:#f0e1ff
 ```
 
+**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. Sequence Diagrams / Sơ đồ Tuần tự
@@ -107,10 +113,10 @@ flowchart LR
 - Request/response cycles
 
 **VI**: Sử dụng sequence diagrams cho:
-- Luồng giao tiếp API
-- Luồng xác thực/phân quyền
-- Tương tác giữa các service
-- Chu kỳ request/response
+- 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
 
@@ -130,6 +136,9 @@ sequenceDiagram
     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
@@ -173,6 +182,9 @@ sequenceDiagram
     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. Class Diagrams / Sơ đồ Class
@@ -186,10 +198,10 @@ sequenceDiagram
 - Module dependencies
 
 **VI**: Sử dụng class diagrams cho:
-- Design patterns và cấu trúc code
-- Kiến trúc hướng đối tượng
-- Kế thừa và mối quan hệ
-- Dependencies giữa các module
+- 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
 
@@ -219,6 +231,9 @@ classDiagram
     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. Graph Diagrams / Sơ đồ Graph
@@ -232,10 +247,10 @@ classDiagram
 - Dependency graphs
 
 **VI**: Sử dụng graph diagrams cho:
-- Tổng quan kiến trúc hệ thống
-- Mối quan hệ giữa các thành phần
-- Sơ đồ luồng dữ liệu
-- Đồ thị dependencies
+- 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
 
@@ -254,11 +269,14 @@ graph TD
     IAM --> Cache
     User --> Cache
     
-    style Gateway fill:#e1f5ff
-    style DB fill:#f0e1ff
-    style Cache fill:#fff4e1
+    style Gateway fill:#2980b9,stroke:#333,stroke-width:2px,color:#fff
+    style DB fill:#8e44ad,stroke:#333,stroke-width:2px,color:#fff
+    style Cache fill:#f39c12,stroke:#333,stroke-width:2px,color:#fff
 ```
 
+**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
@@ -273,11 +291,14 @@ graph LR
     Service --> Cache[Cache Service]
     Cache --> Redis[(Redis)]
     
-    style Validation fill:#d4edda
-    style Service fill:#e1f5ff
-    style Cache fill:#fff4e1
+    style Validation fill:#27ae60,stroke:#333,stroke-width:2px,color:#fff
+    style Service fill:#2980b9,stroke:#333,stroke-width:2px,color:#fff
+    style Cache fill:#f39c12,stroke:#333,stroke-width:2px,color:#fff
 ```
 
+**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. ER Diagrams / Sơ đồ ER
@@ -341,6 +362,9 @@ erDiagram
     }
 ```
 
+**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. Gantt Charts / Biểu đồ Gantt
@@ -377,6 +401,9 @@ gantt
     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. C4 Diagrams / Sơ đồ C4
@@ -415,6 +442,9 @@ C4Context
     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`.
+
+
 ---
 
 ## Styling Tips / Mẹo Styling
@@ -423,22 +453,22 @@ C4Context
 
 ```mermaid
 graph LR
-    A["Primary<br/>#4A90E2"] --> B["Data/Cache<br/>#F5A623"]
-    B --> C["Success<br/>#50E3C2"]
-    C --> D["Warning<br/>#F39C12"]
-    D --> E["Error<br/>#E74C3C"]
-    E --> F["Processing<br/>#9013FE"]
-    F --> G["Info<br/>#7B68EE"]
-    G --> H["Neutral<br/>#95A5A6"]
+    A["Primary<br/>#2980B9"] --> B["Data/Cache<br/>#F39C12"]
+    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:#4A90E2
-    style B fill:#F5A623
-    style C fill:#50E3C2
-    style D fill:#F39C12
-    style E fill:#E74C3C
-    style F fill:#9013FE
-    style G fill:#7B68EE
-    style H fill:#95A5A6
+    style A fill:#2980B9,color:#fff
+    style B fill:#F39C12,color:#fff
+    style C fill:#27AE60,color:#fff
+    style D fill:#E67E22,color:#fff
+    style E fill:#C0392B,color:#fff
+    style F fill:#8E44AD,color:#fff
+    style G fill:#3498DB,color:#fff
+    style H fill:#7F8C8D,color:#fff
 ```
 
 ### Style Syntax
@@ -523,11 +553,21 @@ graph TD
 # Install mermaid-cli
 npm install -g @mermaid-js/mermaid-cli
 
-# Test render
+# Test render (SVG)
 mmdc -i your-doc.md -o test-output.svg
 
-# Check for errors
-echo $?  # Should be 0 if successful
+# 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)
 ```
 
 ---