pos-system/docs/vi/guides/development.md

Hướng Dẫn Development

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

1. Cấu Trúc Dự Án
2. Tiêu Chuẩn Code
3. Quy Trình Git
4. Phát Triển Backend
5. Chiến Lược Testing
6. Quy Trình Database
7. Triển Khai Kubernetes

---

Cấu Trúc Dự Án

Chúng tôi tuân theo cấu trúc monorepo quản lý bởi PNPM Workspaces.

Base/
├── apps/                 # Ứng dụng Frontend
│   ├── web-client/       # Next.js 14+ (App Router)
│   └── mobile-client/    # Flutter
├── services/             # Backend microservices
│   ├── _template/        # Template cho service mới
│   ├── iam-service/      # Identity & Access Management
│   └── ...
├── packages/             # Thư viện chia sẻ
│   ├── logger/           # Structured logging (Winston)
│   ├── types/            # DTOs & Interfaces chia sẻ
│   ├── http-client/      # Internal Service Client
│   └── tracing/          # Cấu hình OpenTelemetry
├── infra/                # Infrastructure-as-Code
│   ├── traefik/          # API Gateway
│   └── databases/        # Scripts thiết lập Database
└── docs/                 # Tài liệu (EN & VI)

---

Tiêu Chuẩn Code

Quy ước Đặt tên

• Files: kebab-case.ts (ví dụ: user.controller.ts, app.config.ts)
• Classes: PascalCase (ví dụ: UserController, AuthService)
• Functions/Variables: camelCase (ví dụ: getUserById, isValid)
• Constants: UPPER_SNAKE_CASE (ví dụ: MAX_RETRIES, DEFAULT_TIMEOUT)
• Interfaces: PascalCase (ví dụ: User, CreateUserDto) - Không dùng tiền tố 'I'

Bilingual Comments (Bình luận Song ngữ)

Đối với logic cốt lõi và public APIs, giả định cả lập trình viên quốc tế và Việt Nam đều đọc code.

/**
 * EN: Validates user credentials and returns a token
 * VI: Xác thực thông tin người dùng và trả về token
 */
async login(dto: LoginDto): Promise<TokenResponse> { ... }

TypeScript Usage

• Strict Mode: Được bật trong tsconfig.json. Không cho phép any (dùng unknown nếu cần).
• DTOs: Sử dụng Zod để runtime validation và type inference.
• Return Types: Khai báo rõ ràng kiểu trả về cho tất cả public methods.

---

Quy Trình Git

Chiến lược Nhánh (Branching Strategy)

• main: Code production-ready.
• develop: Nhánh integration cho release tiếp theo.
• feature/xyz: Tính năng mới (tách từ develop).
• fix/xyz: Sửa lỗi (tách từ develop).
• hotfix/xyz: Sửa lỗi nghiêm trọng (tách từ main).

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:

feat(iam): add multi-factor authentication
fix(db): correct unique constraint on email
docs(guide): update development setup
style: format code with prettier
refactor: simplify auth middleware
test: add unit tests for user service
chore: update dependencies

---

Phát Triển Backend

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:#1e3a2e,color:#4ade80,stroke:#4ade80,stroke-width:3px
    style Done fill:#1e3a2e,color:#4ade80,stroke:#4ade80,stroke-width:3px
    style DTO fill:#1e293b,color:#60a5fa
    style Repo fill:#1e293b,color:#3b82f6
    style Service fill:#2e1a47,color:#a78bfa
    style Controller fill:#2d1b0e,color:#fb923c
    style Route fill:#1e293b,color:#3b82f6
    style Middleware fill:#1e293b,color:#60a5fa
    style Test fill:#1e3a2e,color:#4ade80
    style ErrorCheck fill:#2d1b0e,color:#fb923c
    style ThrowError fill:#3f1a1a,color:#f87171
    style ErrorHandler fill:#3f1a1a,color:#f87171
    style Response fill:#27272a,color:#a1a1aa
    style Success fill:#1e3a2e,color:#4ade80

Tạo API Endpoint Mới

1. Định nghĩa DTO (modules/user/user.dto.ts):

   export const CreateUserDto = z.object({
     email: z.string().email(),
     name: z.string().min(2),
   });
   export type CreateUserDto = z.infer<typeof CreateUserDto>;
   

2. Tạo Service Method (modules/user/user.service.ts):

   • Implement business logic.
   • Sử dụng BaseRepository.
   • Throw HttpError (ví dụ: NotFound, BadRequest).

3. Tạo Controller (modules/user/user.controller.ts):

   • Parse body với DTO: const dto = CreateUserDto.parse(req.body).
   • Gọi service.
   • Trả về success response: res.json({ success: true, data: result }).

4. Đăng ký Route (modules/user/index.ts):

   • Thêm vào Express router cùng middlewares.

Xử lý Lỗi (Error Handling)

Luôn sử dụng các class lỗi tùy chỉnh từ core/errors:

import { NotFoundError, ConflictError } from '../../core/errors';

if (!user) {
  throw new NotFoundError('User not found');
}

---

Chiến Lược Testing

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:#1e3a2e,color:#4ade80
    style Integration fill:#1e293b,color:#60a5fa
    style E2E fill:#2e1a47,color:#a78bfa
    style Code fill:#1e293b,color:#3b82f6
    style CheckLint fill:#2d1b0e,color:#fb923c
    style UnitPass fill:#1e3a2e,color:#4ade80
    style IntPass fill:#1e293b,color:#60a5fa
    style E2EPass fill:#2e1a47,color:#a78bfa
    style Coverage fill:#2d1b0e,color:#fbbf24
    style RunUnit fill:#1e3a2e,color:#4ade80
    style RunIntegration fill:#1e293b,color:#60a5fa
    style RunE2E fill:#2e1a47,color:#a78bfa
    style ReadyMerge fill:#1e3a2e,color:#4ade80,stroke:#4ade80,stroke-width:3px
    style FixLint fill:#3f1a1a,color:#f87171
    style FixUnit fill:#3f1a1a,color:#f87171
    style FixIntegration fill:#3f1a1a,color:#f87171
    style FixE2E fill:#3f1a1a,color:#f87171
    style AddTests fill:#2d1b0e,color:#fbbf24

Unit Tests (*.test.ts)

• Phạm vi: Các class/function đơn lẻ.
• Mocking: Mock tất cả dependencies bên ngoài (DB, services khác) dùng jest-mock-extended.
• Vị trí: Đặt cùng thư mục với file source.
• Chạy: pnpm test

E2E Tests (tests/**/*.e2e.ts)

• Phạm vi: Full API flows (Controller -> Service -> DB).
• Database: Sử dụng test database riêng biệt (Dockerized).
• Chạy: pnpm test:e2e

Linting & Formatting

• Lint: pnpm lint (ESLint)
• Format: pnpm format (Prettier)
• Typecheck: pnpm typecheck (TSC)

---

Quy Trình Database

Chúng tôi sử dụng Prisma với Neon PostgreSQL.

Migrations

1. Sửa prisma/schema.prisma.
2. Tạo migration (Dev):

   ./scripts/db/migrate.sh iam-service dev --name add_user_profile
   

3. Áp dụng cho Production (CI/CD):

   ./scripts/db/migrate.sh iam-service deploy
   

Seed Data

Nạp dữ liệu mẫu vào database:

./scripts/db/seed.sh iam-service

Xem Dữ liệu Trực quan

Sử dụng Prisma Studio:

pnpm --filter @goodgo/iam-service prisma studio

---

Triển Khai Kubernetes

Để test Kubernetes cục bộ (Docker Desktop / Minikube):

# 1. Build images
docker build -t goodgo/iam-service:latest -f services/iam-service/Dockerfile .

# 2. Deploy
cd deployments/local/kubernetes
./deploy.sh

# 3. Xác minh
kubectl get pods -n iam-local
kubectl logs -f -l app=iam-service -n iam-local

Xem Hướng Dẫn Kubernetes để biết chi tiết.