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

Hướng Dẫn Phát Triển Local (Local Development)

Hướng dẫn phát triển cục bộ

Thời gian thiết lập: 15-30 phút

Workflow / Quy Trình

graph TD
    Start([Bắt đầu / Start]) --> Prerequisites["1. Yêu cầu Hệ thống - Prerequisites"]
    Prerequisites --> Clone["2. Clone và Install"]
    Clone --> Env["3. Cấu hình Environment - Shared và Service-Specific"]
    Env --> DB["4. Setup Database - Migrate và Seed"]
    DB --> Run["5. Chạy Dự án - Native/Docker/Hybrid"]
    Run --> Dev["6. Development Loop - Watch Mode"]
    Dev --> Test["7. Testing và Verify"]
    Test --> End([Hoàn tất / Complete])

    subgraph "Các Chế độ Chạy / Run Modes"
        Run --> Mode1["Cách 1: Native - Nhanh nhất"]
        Run --> Mode2["Cách 2: Hybrid - Linh hoạt"]
        Run --> Mode3["Cách 3: Full Docker - Production-like"]
    end

    style Start fill:#27AE60,color:#fff,stroke:#27AE60,stroke-width:2px
    style End fill:#27AE60,color:#fff,stroke:#27AE60,stroke-width:2px
    style Prerequisites fill:#7F8C8D,color:#fff
    style Clone fill:#7F8C8D,color:#fff
    style Env fill:#E67E22,color:#fff
    style DB fill:#E67E22,color:#fff
    style Run fill:#2980B9,color:#fff
    style Dev fill:#2980B9,color:#fff
    style Test fill:#3498DB,color:#fff
    style Mode1 fill:#8E44AD,color:#fff
    style Mode2 fill:#8E44AD,color:#fff
    style Mode3 fill:#8E44AD,color:#fff

Tổng Quan / Overview

Hướng dẫn này cung cấp quy trình chi tiết để thiết lập môi trường phát triển (development environment) cho hệ sinh thái GoodGo Microservices. Bạn sẽ học cách chạy các service, thiết lập cơ sở dữ liệu và quy trình làm việc hiệu quả với hot-reload.

1. Yêu Cầu Hệ Thống / Prerequisites

Trước khi bắt đầu, đảm bảo máy của bạn đã cài đặt các công cụ sau:

• Node.js: Phiên bản LTS mới nhất (v20+).
• PNPM: Package manager chính của dự án (npm install -g pnpm).
• Docker Desktop: Cần thiết để chạy các dịch vụ hạ tầng (Redis, Database local).
• Git: Để quản lý mã nguồn.
• Neon Account (Tùy chọn): Nếu sử dụng Neon Database trên cloud (khuyên dùng cho dev).

2. Cài Đặt Ban Đầu / Initial Setup

2.1 Clone và Cài Đặt Dependencies

# VI: Clone repository về máy
git clone <repository-url>
cd Base

# VI: Cài đặt các thư viện phụ thuộc bằng pnpm
pnpm install

2.2 Script Khởi Tạo Nhanh (Khuyến nghị)

Dự án có script tự động hóa các bước khởi tạo cơ bản:

# VI: Chạy script khởi tạo
./scripts/setup/init-project.sh

Script này sẽ:

• Cài đặt dependencies.
• Copy các file môi trường mẫu (.env.example -> .env).
• Tạo Prisma client.

3. Cấu Hình Environment / Environment Configuration

Dự án sử dụng chiến lược Hybrid Environment để tối ưu hóa việc quản lý cấu hình:

3.1 Shared Configuration (Cấu hình chung)

File: deployments/local/.env.local Chứa các biến dùng chung cho toàn bộ hệ thống (JWT, Redis, Logging).

# VI: Tạo file môi trường chung từ file mẫu
cp deployments/local/env.local.example deployments/local/.env.local

3.2 Service-Specific Configuration (Cấu hình riêng)

Mỗi service (ví dụ iam-service) cần file .env.local riêng chứa thông tin đặc thù như Database URL và Port.

# VI: Tạo file môi trường riêng cho service
cp services/iam-service/env.local.example services/iam-service/.env.local

Nội dung quan trọng cần chú ý trong services/iam-service/.env.local:

# Database URL (Sử dụng Neon Tech hoặc Local Postgres)
DATABASE_URL=postgresql://user:password@host:5432/db_name?sslmode=require

# Port của Service (Mỗi service phải khác nhau)
PORT=5001

# Tên Service
SERVICE_NAME=iam-service

# Redis Host (localhost cho Native Dev, redis cho Docker Dev)
REDIS_HOST=localhost

4. Setup Database

Sau khi cấu hình DATABASE_URL, bạn cần đồng bộ schema và tạo dữ liệu mẫu.

# VI: Chạy migration cho iam-service
./scripts/db/migrate.sh iam-service dev

# VI: Tạo dữ liệu mẫu (tùy chọn)
./scripts/db/seed.sh iam-service

5. Các Chế Độ Chạy / Run Modes

Bạn có thể chạy dự án theo 3 cách tùy thuộc vào nhu cầu:

Cách 1: Native Development (Khuyên dùng cho Backend Dev)

Chạy trực tiếp trên máy host. Tốc độ cao nhất, hot-reload nhanh nhất.

1. Khởi động Hạ tầng (Infrastructure):

   # VI: Khởi động Redis và Traefik chạy ngầm bằng Docker
   cd deployments/local
   docker-compose up -d redis traefik
   cd ../..
   

2. Chạy Service:

   # VI: Chạy iam-service ở chế độ watch
   pnpm --filter @goodgo/iam-service dev
   

Cách 2: Hybrid Development (Linh hoạt)

Dùng khi bạn cần chạy nhiều service phụ trợ trong Docker, nhưng muốn dev trực tiếp 1 service chính.

# VI: Chạy các service phụ thuộc trong Docker
docker-compose -f deployments/local/docker-compose.yml up -d user-service payment-service

# VI: Chạy service bạn đang làm việc trực tiếp trên máy
pnpm --filter @goodgo/iam-service dev

Cách 3: Full Docker (Mô phỏng Production)

Chạy toàn bộ hệ thống trong Docker. Tốt cho việc kiểm tra tích hợp (Integration Test) nhưng không có hot-reload.

# VI: Chạy tất cả bằng Docker Compose
cd deployments/local
docker-compose up -d

6. Access & Verification / Truy Cập & Kiểm Tra

Sau khi khởi động, bạn có thể truy cập các điểm cuối sau:

Service	URL	Mô tả
API Gateway	http://localhost/api/v1	Cổng truy cập chính qua Traefik
IAM Service	http://localhost:5001	Truy cập trực tiếp service
Health Check	http://localhost:5001/health	Kiểm tra trạng thái service
Metrics	http://localhost:5001/metrics	Prometheus metrics
API Docs	http://localhost:5001/api-docs	Swagger UI

Kiểm tra Health Check

# VI: Kiểm tra liveness
curl http://localhost:5001/health/live

# VI: Kiểm tra readiness
curl http://localhost:5001/health/ready

7. Troubleshooting / Xử Lý Sự Cố

Port Already In Use

Lỗi: Error: listen EADDRINUSE: address already in use :::5001

Giải pháp:

# VI: Tìm process đang chiếm port 5001
lsof -i :5001

# VI: Tắt process đó
kill -9 <PID>

Database Connection Error

Lỗi: P1001: Can't reach database server

Giải pháp:

• Kiểm tra lại biến DATABASE_URL.
• Nếu dùng Docker Postgres local, đảm bảo container đang chạy (docker ps).
• Nếu dùng Neon, kiểm tra kết nối internet.

Module Not Found

Lỗi: Không tìm thấy các package nội bộ (ví dụ @goodgo/logger).

Giải pháp:

# VI: Cài lại dependencies và build lại packages
pnpm install
pnpm build

Tài Liệu Tham Khảo / References

• Kubernetes Guide - Triển khai lên K8s Local.
• Project Architecture - Tổng quan kiến trúc hệ thống.