From 3f83ee656655ea2407e15a2fc1005bac9538881e Mon Sep 17 00:00:00 2001 From: Ho Ngoc Hai Date: Wed, 7 Jan 2026 23:02:20 +0700 Subject: [PATCH] =?UTF-8?q?feat:=20th=C3=AAm=20h=C6=B0=E1=BB=9Bng=20d?= =?UTF-8?q?=E1=BA=ABn=20s=E1=BB=AD=20d=E1=BB=A5ng=20s=C6=A1=20=C4=91?= =?UTF-8?q?=E1=BB=93=20Mermaid=20b=E1=BA=B1ng=20ti=E1=BA=BFng=20Vi?= =?UTF-8?q?=E1=BB=87t=20v=C3=A0=20ti=E1=BA=BFng=20Anh,=20bao=20g=E1=BB=93m?= =?UTF-8?q?=20c=C3=A1c=20lo=E1=BA=A1i=20s=C6=A1=20=C4=91=E1=BB=93=20nh?= =?UTF-8?q?=C6=B0=20Flowchart,=20Sequence,=20Class,=20Graph=20v=C3=A0=20ER?= =?UTF-8?q?.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/en/guides/mermaid.md | 539 +++++++++++++++++++++++++++++++++++ docs/vi/guides/mermaid.md | 543 ++++++++++++++++++++++++++++++++++++ docs/vi/templates/README.md | 2 +- 3 files changed, 1083 insertions(+), 1 deletion(-) create mode 100644 docs/en/guides/mermaid.md create mode 100644 docs/vi/guides/mermaid.md diff --git a/docs/en/guides/mermaid.md b/docs/en/guides/mermaid.md new file mode 100644 index 00000000..87db8d96 --- /dev/null +++ b/docs/en/guides/mermaid.md @@ -0,0 +1,539 @@ +# Mermaid Diagram Guide / Hướng dẫn Sơ đồ Mermaid + +## Overview / Tổng quan + +**EN**: This guide helps you choose the right Mermaid diagram type for your documentation and provides examples for common use cases. + +**VI**: 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. + +## Quick Reference / Tham chiếu Nhanh + +| Diagram Type / Loại | Use For / Sử dụng cho | Complexity / Độ phức tạp | +|----------------------|------------------------|---------------------------| +| **Flowchart** | Workflows, decision trees / Quy trình, cây quyết định | ⭐⭐ | +| **Sequence Diagram** | API interactions, request flows / Tương tác API, luồng request | ⭐⭐⭐ | +| **Class Diagram** | Code structure, patterns / Cấu trúc code, patterns | ⭐⭐⭐ | +| **Graph** | System architecture, dependencies / Kiến trúc hệ thống, dependencies | ⭐⭐ | +| **ER Diagram** | Database schema / Schema database | ⭐⭐⭐ | +| **Gantt** | Timeline, project schedule / Timeline, lịch trình dự án | ⭐⭐ | +| **C4 Diagram** | System context, containers / Bối cảnh hệ thống, containers | ⭐⭐⭐⭐ | + +--- + +## 1. Flowcharts / Sơ đồ Luồng + +### 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 + +**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ố + +### 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:#e1f5ff + style End fill:#d4edda + style Check fill:#fff3cd + style Error fill:#f8d7da +``` + +**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:#e1f5ff + style End fill:#d4edda + style Check fill:#fff3cd + style Error fill:#f8d7da +``` +```` + +### 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 Processing fill:#f0e1ff +``` + +--- + +## 2. Sequence Diagrams / Sơ đồ Tuần tự + +### 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 + +**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 + +### 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} +``` + +**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 +``` + +--- + +## 3. Class Diagrams / Sơ đồ Class + +### 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 + +**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 + +### Basic Class Diagram + +```mermaid +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 +``` + +--- + +## 4. Graph Diagrams / Sơ đồ Graph + +### When to Use / Khi nào sử dụng + +**EN**: Use graph diagrams for: +- System architecture overview +- Component relationships +- Data flow diagrams +- 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 + +### 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 Gateway fill:#e1f5ff + style DB fill:#f0e1ff + style Cache fill:#fff4e1 +``` + +### 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 Validation fill:#d4edda + style Service fill:#e1f5ff + style Cache fill:#fff4e1 +``` + +--- + +## 5. ER Diagrams / Sơ đồ ER + +### When to Use / Khi nào sử dụng + +**EN**: Use ER diagrams for: +- Database schema documentation +- Entity relationships +- Data modeling +- Prisma schema visualization + +**VI**: 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 +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 + } +``` + +--- + +## 6. Gantt Charts / Biểu đồ Gantt + +### When to Use / Khi nào sử dụng + +**EN**: Use Gantt charts for: +- Project timelines +- Implementation phases +- Migration schedules +- Deployment plans + +**VI**: 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 +``` + +--- + +## 7. C4 Diagrams / Sơ đồ C4 + +### When to Use / Khi nào sử dụng + +**EN**: Use C4 diagrams for: +- System context (highest level) +- Container diagrams (services, databases) +- Component diagrams (modules within services) +- Code diagrams (classes, functions) + +**VI**: 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 +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") +``` + +--- + +## Styling Tips / Mẹo Styling + +### Color Palette / Bảng màu + +```mermaid +graph LR + A["Primary
#e1f5ff"] --> B["Secondary
#fff4e1"] + B --> C["Success
#d4edda"] + C --> D["Warning
#fff3cd"] + D --> E["Error
#f8d7da"] + E --> F["Info
#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 Syntax + +```markdown +style NodeId fill:#colorcode,stroke:#bordercolor,stroke-width:2px +``` + +**Examples**: +```markdown +style Start fill:#e1f5ff +style Error fill:#f8d7da +style Process fill:#d4edda,stroke:#28a745,stroke-width:2px +``` + +--- + +## Best Practices / Best Practices + +### EN: Guidelines + +1. **Keep it Simple**: Don't overcomplicate diagrams +2. **Use Consistent Styling**: Apply color scheme consistently +3. **Add Legends**: Explain symbols and colors when needed +4. **Limit Complexity**: Break into multiple diagrams if too complex +5. **Test Rendering**: Always test diagrams render correctly + +### VI: Hướng dẫn + +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 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 + +--- + +## Common Pitfalls / Lỗi 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 +``` + +### ✅ Simplified with Subgraphs + +```mermaid +graph TD + A[Start] --> B[Process A] + B --> C[Process B] + + subgraph "Detailed Processing" + C --> D[Step 1] + D --> E[Step 2] + end + + E --> F[End] +``` + +--- + +## Testing Diagrams / Test Sơ đồ + +**EN**: Always test your diagrams before committing: + +**VI**: Luôn test sơ đồ trước khi commit: + +```bash +# Install mermaid-cli +npm install -g @mermaid-js/mermaid-cli + +# Test render +mmdc -i your-doc.md -o test-output.svg + +# Check for errors +echo $? # Should be 0 if successful +``` + +--- + +## Resources / Tài nguyên + +- [Mermaid Official Documentation](https://mermaid.js.org/) - Complete reference +- [Mermaid Live Editor](https://mermaid.live/) - Test diagrams online +- [Mermaid CheatSheet](https://jojozhuang.github.io/tutorial/mermaid-cheat-sheet/) - Quick reference + +--- + +**Last Updated**: 2026-01-05 diff --git a/docs/vi/guides/mermaid.md b/docs/vi/guides/mermaid.md new file mode 100644 index 00000000..9fb485fa --- /dev/null +++ b/docs/vi/guides/mermaid.md @@ -0,0 +1,543 @@ +# Mermaid Diagram Guide / Hướng dẫn Sơ đồ Mermaid + +## Overview / Tổng quan + +**EN**: This guide helps you choose the right Mermaid diagram type for your documentation and provides examples for common use cases. + +**VI**: 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. + +## Quick Reference / Tham chiếu Nhanh + +| Diagram Type / Loại | Use For / Sử dụng cho | Complexity / Độ phức tạp | +|----------------------|------------------------|---------------------------| +| **Flowchart** | Workflows, decision trees / Quy trình, cây quyết định | ⭐⭐ | +| **Sequence Diagram** | API interactions, request flows / Tương tác API, luồng request | ⭐⭐⭐ | +| **Class Diagram** | Code structure, patterns / Cấu trúc code, patterns | ⭐⭐⭐ | +| **Graph** | System architecture, dependencies / Kiến trúc hệ thống, dependencies | ⭐⭐ | +| **ER Diagram** | Database schema / Schema database | ⭐⭐⭐ | +| **Gantt** | Timeline, project schedule / Timeline, lịch trình dự án | ⭐⭐ | +| **C4 Diagram** | System context, containers / Bối cảnh hệ thống, containers | ⭐⭐⭐⭐ | + +--- + +## 1. Flowcharts / Sơ đồ Luồng + +### 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 + +**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ố + +### 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:#e1f5ff + style End fill:#d4edda + style Check fill:#fff3cd + style Error fill:#f8d7da +``` + +**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:#e1f5ff + style End fill:#d4edda + style Check fill:#fff3cd + style Error fill:#f8d7da +``` +```` + +### 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 Processing fill:#f0e1ff +``` + +--- + +## 2. Sequence Diagrams / Sơ đồ Tuần tự + +### 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 + +**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 + +### 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} +``` + +**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 +``` + +--- + +## 3. Class Diagrams / Sơ đồ Class + +### 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 + +**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 + +### Basic Class Diagram + +```mermaid +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 +``` + +--- + +## 4. Graph Diagrams / Sơ đồ Graph + +### When to Use / Khi nào sử dụng + +**EN**: Use graph diagrams for: +- System architecture overview +- Component relationships +- Data flow diagrams +- 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 + +### 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 Gateway fill:#e1f5ff + style DB fill:#f0e1ff + style Cache fill:#fff4e1 +``` + +### 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 Validation fill:#d4edda + style Service fill:#e1f5ff + style Cache fill:#fff4e1 +``` + +--- + +## 5. ER Diagrams / Sơ đồ ER + +### When to Use / Khi nào sử dụng + +**EN**: Use ER diagrams for: +- Database schema documentation +- Entity relationships +- Data modeling +- Prisma schema visualization + +**VI**: 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 +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 + } +``` + +--- + +## 6. Gantt Charts / Biểu đồ Gantt + +### When to Use / Khi nào sử dụng + +**EN**: Use Gantt charts for: +- Project timelines +- Implementation phases +- Migration schedules +- Deployment plans + +**VI**: 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 +``` + +--- + +## 7. C4 Diagrams / Sơ đồ C4 + +### When to Use / Khi nào sử dụng + +**EN**: Use C4 diagrams for: +- System context (highest level) +- Container diagrams (services, databases) +- Component diagrams (modules within services) +- Code diagrams (classes, functions) + +**VI**: 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 +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") +``` + +--- + +## Styling Tips / Mẹo Styling + +### Color Palette / Bảng màu + +```mermaid +graph LR + A["Primary
#4A90E2"] --> B["Data/Cache
#F5A623"] + B --> C["Success
#50E3C2"] + C --> D["Warning
#F39C12"] + D --> E["Error
#E74C3C"] + E --> F["Processing
#9013FE"] + F --> G["Info
#7B68EE"] + G --> H["Neutral
#95A5A6"] + + 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 Syntax + +```markdown +style NodeId fill:#colorcode,stroke:#bordercolor,stroke-width:2px +``` + +**Examples**: +```markdown +style Start fill:#e1f5ff +style Error fill:#f8d7da +style Process fill:#d4edda,stroke:#28a745,stroke-width:2px +``` + +--- + +## Best Practices / Thực hành Tốt nhất + +### EN: Guidelines + +1. **Keep it Simple**: Don't overcomplicate diagrams +2. **Use Consistent Styling**: Apply color scheme consistently +3. **Add Legends**: Explain symbols and colors when needed +4. **Limit Complexity**: Break into multiple diagrams if too complex +5. **Test Rendering**: Always test diagrams render correctly + +### VI: Hướng dẫn + +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 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 + +--- + +## 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 +``` + +### ✅ Simplified with Subgraphs + +```mermaid +graph TD + A[Start] --> B[Process A] + B --> C[Process B] + + subgraph "Detailed Processing" + C --> D[Step 1] + D --> E[Step 2] + end + + E --> F[End] +``` + +--- + +## Kiểm tra Sơ đồ + +**EN**: Always test your diagrams before committing: + +**VI**: Luôn test sơ đồ trước khi commit: + +```bash +# Install mermaid-cli +npm install -g @mermaid-js/mermaid-cli + +# Test render +mmdc -i your-doc.md -o test-output.svg + +# Check for errors +echo $? # Should be 0 if successful +``` + +--- + +## Resources / Tài nguyên + +- [Mermaid Official Documentation](https://mermaid.js.org/) - Complete reference +- [Mermaid Live Editor](https://mermaid.live/) - Test diagrams online +- [Mermaid CheatSheet](https://jojozhuang.github.io/tutorial/mermaid-cheat-sheet/) - Quick reference + +--- + +**Tác giả**: VelikHo (hongochai10@icloud.com) diff --git a/docs/vi/templates/README.md b/docs/vi/templates/README.md index a70912e9..f6be32cb 100644 --- a/docs/vi/templates/README.md +++ b/docs/vi/templates/README.md @@ -1,6 +1,6 @@ # Hướng dẫn Sử dụng Templates Tài liệu -> **Mục đích**: Hướng dẫn sử dụng các templates tài liệu để tạo documentation nhất quán cho project GoodGo +> **Mục đích**: Hướng dẫn sử dụng các templates tài liệu để tạo documentation nhất quán cho project ## Templates Có sẵn