feat(docs): Revise Vietnamese and English development guides with enhanced structure and clarity

- Updated the introductory notes in both Vietnamese and English development guides for improved clarity. - Reorganized the workflow steps in the Vietnamese documentation to align with the English version. - Added detailed Mermaid diagrams for better visualization of development processes and testing strategies. - Introduced new sections for color palette references and verification checklists to enhance documentation completeness. - Simplified headers and improved formatting for better readability across both language versions.
2026-01-08 15:57:09 +07:00
parent 3f5d9715dc
commit 92d14877e5
3 changed files with 261 additions and 8 deletions
--- a/.agent/workflows/docs-edit-vi-en.md
+++ b/.agent/workflows/docs-edit-vi-en.md
@@ -2,9 +2,24 @@
 description: Workflows chỉnh sửa docs
 ---

-1. Xóa các comment "# EN: ..." trong code blocks
-2. Kiểm tra và sửa các diagram Mermaid (xóa , thay & bằng và)
-3. Áp dụng bảng màu tối chuẩn
-4. Làm cho nội dung thuần Việt hơn với phiên bản vi
-5. Sau khi chỉnh sửa xong phiên bản Việt, hãy cập nhật phiên bản tiếng anh
-
+Bước 1 Xóa EN comments bên VI và xoá VI comments bên EN
+Bước 2 - Làm sạch Code Blocks
+⚠️ Lưu ý: Bản VI xóa # EN:, bản EN xóa # VI
+Bước 3 - Chuẩn hóa Header (MỚI)
+- Hướng dẫn xóa > **Lưu ý**: / > **Note**:
+- Đơn giản hóa header
+Bước 4 - Mermaid
+- Checklist lỗi cú pháp cụ thể
+- Hướng dẫn tạo diagram mới nếu chưa có
+Bước 5 - Color Palette (CHI TIẾT HƠN)
+- Color Palette Reference đầy đủ
+- Checklist áp dụng màu chi tiết
+- Pattern cho từng loại node
+⚠️ Lưu ý: Sử dụng bảng màu tối.
+Bước 8 - Verification (MỚI)
+- Checklist kiểm tra chất lượng
+- Đảm bảo đồng bộ VI-EN
+Quick Tips Section (MỚI)
+- Mermaid Common Issues
+- Color Pattern quick reference
+- Visual indicators (emojis)
--- a/docs/en/guides/development.md
+++ b/docs/en/guides/development.md
@@ -1,6 +1,6 @@
 # Development Guide

-> **Note**: This guide provides comprehensive standards and workflows for contributing to the GoodGo Microservices Platform.
+>Comprehensive standards and workflows for contributing to the GoodGo Microservices Platform

 ## Table of Contents

@@ -80,6 +80,40 @@ async login(dto: LoginDto): Promise<TokenResponse> { ... }
 *   `fix/xyz`: Bug fixes (branch off `develop`).
 *   `hotfix/xyz`: Critical fixes (branch off `main`).

+```mermaid
+gitGraph
+    commit id: "Initial"
+    branch develop
+    checkout develop
+    commit id: "Setup"
+    
+    branch feature/login
+    checkout feature/login
+    commit id: "Add login form"
+    commit id: "Add validation"
+    checkout develop
+    merge feature/login
+    
+    branch feature/dashboard
+    checkout feature/dashboard
+    commit id: "Create dashboard"
+    checkout develop
+    
+    checkout main
+    merge develop tag: "v1.0.0"
+    
+    checkout develop
+    merge feature/dashboard
+    
+    checkout main
+    branch hotfix/security
+    commit id: "Fix security issue"
+    checkout main
+    merge hotfix/security tag: "v1.0.1"
+    checkout develop
+    merge hotfix/security
+```
+
 ### Commit Messages

 We follow [Conventional Commits](https://www.conventionalcommits.org/):
@@ -98,6 +132,39 @@ chore: update dependencies

 ## Backend Development

+```mermaid
+graph TD
+    Start([Start Creating New API]) --> DTO[1. Define DTO - Zod Schema]
+    DTO --> Repo[2. Create Repository Method]
+    Repo --> Service[3. Create Service Method - Business Logic]
+    Service --> Controller[4. Create Controller - HTTP Handler]
+    Controller --> Route[5. Register Route - Express Router]
+    Route --> Middleware[6. Add Middlewares]
+    Middleware --> Test[7. Write Tests]
+    Test --> Done([API Complete])
+    
+    Service --> ErrorCheck{Has Error?}
+    ErrorCheck -->|Yes| ThrowError[Throw HttpError]
+    ThrowError --> ErrorHandler[Global Error Handler]
+    ErrorHandler --> Response[Error Response]
+    ErrorCheck -->|No| Success[Success Response]
+    
+    style Start fill:#27AE60,color:#fff,stroke:#27AE60,stroke-width:2px
+    style Done fill:#27AE60,color:#fff,stroke:#27AE60,stroke-width:2px
+    style DTO fill:#3498DB,color:#fff
+    style Repo fill:#2980B9,color:#fff
+    style Service fill:#8E44AD,color:#fff
+    style Controller fill:#E67E22, color:#fff
+    style Route fill:#2980B9,color:#fff
+    style Middleware fill:#3498DB,color:#fff
+    style Test fill:#27AE60,color:#fff
+    style ErrorCheck fill:#E67E22,color:#fff
+    style ThrowError fill:#C0392B,color:#fff
+    style ErrorHandler fill:#C0392B,color:#fff
+    style Response fill:#7F8C8D,color:#fff
+    style Success fill:#27AE60,color:#fff
+```
+
 ### Creating a New API Endpoint

 1.  **Define DTO** (`modules/user/user.dto.ts`):
@@ -138,6 +205,58 @@ if (!user) {

 ## Testing Strategy

+```mermaid
+graph TB
+    subgraph "Testing Pyramid - Bottom to Top"
+        Unit[Unit Tests - Most, Fastest]
+        Integration[Integration Tests - Medium]
+        E2E[E2E Tests - Least, Slowest]
+    end
+    
+    Code[Code Changes] --> CheckLint{Lint Pass?}
+    CheckLint -->|No| FixLint[Fix Linting Errors]
+    FixLint --> CheckLint
+    CheckLint -->|Yes| RunUnit[Run Unit Tests]
+    
+    RunUnit --> UnitPass{Unit Tests Pass?}
+    UnitPass -->|No| FixUnit[Fix Unit Tests]
+    FixUnit --> RunUnit
+    UnitPass -->|Yes| RunIntegration[Run Integration Tests]
+    
+    RunIntegration --> IntPass{Integration Pass?}
+    IntPass -->|No| FixIntegration[Fix Integration]
+    FixIntegration --> RunIntegration
+    IntPass -->|Yes| RunE2E[Run E2E Tests]
+    
+    RunE2E --> E2EPass{E2E Pass?}
+    E2EPass -->|No| FixE2E[Fix E2E]
+    FixE2E --> RunE2E
+    E2EPass -->|Yes| Coverage{Coverage > 70%?}
+    
+    Coverage -->|No| AddTests[Add More Tests]
+    AddTests --> RunUnit
+    Coverage -->|Yes| ReadyMerge[Ready to Merge]
+    
+    style Unit fill:#27AE60,color:#fff
+    style Integration fill:#3498DB,color:#fff
+    style E2E fill:#8E44AD,color:#fff
+    style Code fill:#2980B9,color:#fff
+    style CheckLint fill:#E67E22,color:#fff
+    style UnitPass fill:#27AE60,color:#fff
+    style IntPass fill:#3498DB,color:#fff
+    style E2EPass fill:#8E44AD,color:#fff
+    style Coverage fill:#F39C12,color:#fff
+    style RunUnit fill:#27AE60,color:#fff
+    style RunIntegration fill:#3498DB,color:#fff
+    style RunE2E fill:#8E44AD,color:#fff
+    style ReadyMerge fill:#27AE60,color:#fff,stroke:#27AE60,stroke-width:2px
+    style FixLint fill:#C0392B,color:#fff
+    style FixUnit fill:#C0392B,color:#fff
+    style FixIntegration fill:#C0392B,color:#fff
+    style FixE2E fill:#C0392B,color:#fff
+    style AddTests fill:#F39C12,color:#fff
+```
+
 ### Unit Tests (`*.test.ts`)

 *   **Scope**: Individual classes/functions.
--- a/docs/vi/guides/development.md
+++ b/docs/vi/guides/development.md
@@ -1,6 +1,6 @@
 # Hướng Dẫn Development

-> **Lưu ý**: Hướng dẫn này cung cấp các tiêu chuẩn và quy trình toàn diện để đóng góp vào GoodGo Microservices Platform.
+>Hướng dẫn toàn diện về tiêu chuẩn và quy trình đóng góp vào GoodGo Microservices Platform

 ## Mục lục

@@ -80,6 +80,40 @@ async login(dto: LoginDto): Promise<TokenResponse> { ... }
 *   `fix/xyz`: Sửa lỗi (tách từ `develop`).
 *   `hotfix/xyz`: Sửa lỗi nghiêm trọng (tách từ `main`).

+```mermaid
+gitGraph
+    commit id: "Initial"
+    branch develop
+    checkout develop
+    commit id: "Setup"
+    
+    branch feature/login
+    checkout feature/login
+    commit id: "Add login form"
+    commit id: "Add validation"
+    checkout develop
+    merge feature/login
+    
+    branch feature/dashboard
+    checkout feature/dashboard
+    commit id: "Create dashboard"
+    checkout develop
+    
+    checkout main
+    merge develop tag: "v1.0.0"
+    
+    checkout develop
+    merge feature/dashboard
+    
+    checkout main
+    branch hotfix/security
+    commit id: "Fix security issue"
+    checkout main
+    merge hotfix/security tag: "v1.0.1"
+    checkout develop
+    merge hotfix/security
+```
+
 ### Commit Messages

 Chúng tôi tuân theo [Conventional Commits](https://www.conventionalcommits.org/):
@@ -98,6 +132,39 @@ chore: update dependencies

 ## Phát Triển Backend

+```mermaid
+graph TD
+    Start([Bắt đầu tạo API mới]) --> DTO[1. Định nghĩa DTO - Zod Schema]
+    DTO --> Repo[2. Tạo Repository Method]
+    Repo --> Service[3. Tạo Service Method - Business Logic]
+    Service --> Controller[4. Tạo Controller - HTTP Handler]
+    Controller --> Route[5. Đăng ký Route - Express Router]
+    Route --> Middleware[6. Thêm Middlewares]
+    Middleware --> Test[7. Viết Tests]
+    Test --> Done([API hoàn thành])
+    
+    Service --> ErrorCheck{Có lỗi?}
+    ErrorCheck -->|Có| ThrowError[Throw HttpError]
+    ThrowError --> ErrorHandler[Global Error Handler]
+    ErrorHandler --> Response[Error Response]
+    ErrorCheck -->|Không| Success[Success Response]
+    
+    style Start fill:#27AE60,color:#fff,stroke:#27AE60,stroke-width:2px
+    style Done fill:#27AE60,color:#fff,stroke:#27AE60,stroke-width:2px
+    style DTO fill:#3498DB,color:#fff
+    style Repo fill:#2980B9,color:#fff
+    style Service fill:#8E44AD,color:#fff
+    style Controller fill:#E67E22,color:#fff
+    style Route fill:#2980B9,color:#fff
+    style Middleware fill:#3498DB,color:#fff
+    style Test fill:#27AE60,color:#fff
+    style ErrorCheck fill:#E67E22,color:#fff
+    style ThrowError fill:#C0392B,color:#fff
+    style ErrorHandler fill:#C0392B,color:#fff
+    style Response fill:#7F8C8D,color:#fff
+    style Success fill:#27AE60,color:#fff
+```
+
 ### Tạo API Endpoint Mới

 1.  **Định nghĩa DTO** (`modules/user/user.dto.ts`):
@@ -138,6 +205,58 @@ if (!user) {

 ## Chiến Lược Testing

+```mermaid
+graph TB
+    subgraph "Testing Pyramid - Từ dưới lên"
+        Unit[Unit Tests - Nhiều nhất, Nhanh nhất]
+        Integration[Integration Tests - Trung bình]
+        E2E[E2E Tests - Ít nhất, Chậm nhất]
+    end
+    
+    Code[Code Changes] --> CheckLint{Lint Pass?}
+    CheckLint -->|Không| FixLint[Fix Linting Errors]
+    FixLint --> CheckLint
+    CheckLint -->|Có| RunUnit[Run Unit Tests]
+    
+    RunUnit --> UnitPass{Unit Tests Pass?}
+    UnitPass -->|Không| FixUnit[Fix Unit Tests]
+    FixUnit --> RunUnit
+    UnitPass -->|Có| RunIntegration[Run Integration Tests]
+    
+    RunIntegration --> IntPass{Integration Pass?}
+    IntPass -->|Không| FixIntegration[Fix Integration]
+    FixIntegration --> RunIntegration
+    IntPass -->|Có| RunE2E[Run E2E Tests]
+    
+    RunE2E --> E2EPass{E2E Pass?}
+    E2EPass -->|Không| FixE2E[Fix E2E]
+    FixE2E --> RunE2E
+    E2EPass -->|Có| Coverage{Coverage > 70%?}
+    
+    Coverage -->|Không| AddTests[Add More Tests]
+    AddTests --> RunUnit
+    Coverage -->|Có| ReadyMerge[Ready to Merge]
+    
+    style Unit fill:#27AE60,color:#fff
+    style Integration fill:#3498DB,color:#fff
+    style E2E fill:#8E44AD,color:#fff
+    style Code fill:#2980B9,color:#fff
+    style CheckLint fill:#E67E22,color:#fff
+    style UnitPass fill:#27AE60,color:#fff
+    style IntPass fill:#3498DB,color:#fff
+    style E2EPass fill:#8E44AD,color:#fff
+    style Coverage fill:#F39C12,color:#fff
+    style RunUnit fill:#27AE60,color:#fff
+    style RunIntegration fill:#3498DB,color:#fff
+    style RunE2E fill:#8E44AD,color:#fff
+    style ReadyMerge fill:#27AE60,color:#fff,stroke:#27AE60,stroke-width:2px
+    style FixLint fill:#C0392B,color:#fff
+    style FixUnit fill:#C0392B,color:#fff
+    style FixIntegration fill:#C0392B,color:#fff
+    style FixE2E fill:#C0392B,color:#fff
+    style AddTests fill:#F39C12,color:#fff
+```
+
 ### Unit Tests (`*.test.ts`)

 *   **Phạm vi**: Các class/function đơn lẻ.