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.
This commit is contained in:
Ho Ngoc Hai
@@ -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.
|
||||
|
||||
@@ -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ẻ.
|
||||
|
||||
Reference in New Issue
Block a user