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.

2026-01-08 00:21:46 +07:00
parent 3f83ee6566
commit 95a1754e97
17 changed files with 154 additions and 86 deletions
--- a/docs/en/guides/mermaid.md
+++ b/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)
 ```

 ---