# Hướng Dẫn Local Development

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

## Workflow / Quy Trình

```mermaid
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

```bash
# 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:

```bash
# 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).

```bash
# 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.

```bash
# 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`**:

```properties
# 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.

```bash
# 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)**:
 ```bash
 # 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**:
 ```bash
 # 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.

```bash
# 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.

```bash
# 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

```bash
# 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**:
```bash
# 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**:
```bash
# 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](kubernetes-local.md) - Triển khai lên K8s Local.
- [Project Architecture](../../docs/vi/ARCHITECTURE.vi.md) - Tổng quan kiến trúc hệ thống.