# Hướng Dẫn Bắt Đầu

> **Lưu ý**: Hướng dẫn này giả định bạn đang cài đặt trên macOS hoặc Linux. Người dùng Windows nên sử dụng WSL2.

## Mục lục

1. [Yêu cầu tiên quyết](#yêu-cầu-tiên-quyết)
2. [Tổng quan Kiến trúc](#tổng-quan-kiến-trúc)
3. [Cấu trúc Dự án](#cấu-trúc-dự-án)
4. [Cài đặt & Thiết lập](#cài-đặt--thiết-lập)
5. [Quy trình Phát triển](#quy-trình-phát-triển)
6. [Các Lệnh Thường dùng](#các-lệnh-thường-dùng)
7. [Xử lý Sự cố](#xử-lý-sự-cố)

## Yêu cầu tiên quyết

Trước khi bắt đầu, đảm bảo bạn đã cài đặt:

* **Node.js**: v20.0.0 trở lên (khuyến nghị v22+ hoặc v25+)
 ```bash
 node -v
 # v25.2.1
 ```
* **PNPM**: v8.15.0 trở lên (sử dụng pnpm workspaces)
 ```bash
 pnpm -v
 # 8.15.0
 ```
* **Docker & Docker Compose**: v24.0.0 trở lên cho infrastructure cục bộ
 ```bash
 docker -v
 # Docker version 29.1.3, build f52814d
 ```
* **Git**: Để quản lý version
* **Tài khoản Neon**: Serverless PostgreSQL (https://neon.tech)

## Tổng quan Kiến trúc

GoodGo Platform sử dụng kiến trúc microservices với layer infrastructure chia sẻ.

```mermaid
graph TD
 Client[Client Apps] --> Traefik[Traefik Gateway]

 Traefik --> IAM[IAM Service]
 Traefik --> Template[Template Service]

 IAM --> DB[(Neon PostgreSQL)]
 IAM --> Redis[(Redis Cache)]
 IAM --> Kafka[Kafka Events]

 style Client fill:#7F8C8D,color:#fff
 style Traefik fill:#2980B9,color:#fff
 style IAM fill:#27AE60,color:#fff
 style Template fill:#E67E22,color:#fff
 style DB fill:#8E44AD,color:#fff
 style Redis fill:#F39C12,color:#fff
 style Kafka fill:#3498DB,color:#fff
```

### Color Palette / Bảng màu

```mermaid
graph LR
 A["Primary #2980B9"] --> B["Data/Cache #F39C12"]
 B --> C["Success #27AE60"]
 C --> D["Warning #E67E22"]
 D --> E["Error #C0392B"]
 E --> F["Processing #8E44AD"]
 F --> G["Info #3498DB"]
 G --> H["Neutral #7F8C8D"]

 style A fill:#2980B9,color:#fff
 style B fill:#F39C12,color:#fff
 style C fill:#27AE60,color:#fff
 style D fill:#E67E22,color:#fff
 style E fill:#C0392B,color:#fff
 style F fill:#8E44AD,color:#fff
 style G fill:#3498DB,color:#fff
 style H fill:#7F8C8D,color:#fff
```

## Cấu trúc Dự án

Repository tuân theo cấu trúc monorepo:

```
Base/
 apps/ # Ứng dụng Frontend
 app-admin/ # Admin dashboard application
 app-client/ # Client mobile application (Flutter)
 web-client/ # Next.js web application
 web-docs/ # Documentation website (Next.js)
 services/ # Backend microservices
 iam-service/ # Service xác thực & phân quyền
 _template/ # Template cho service mới
 packages/ # Thư viện chia sẻ (Shared libraries)
 auth-sdk/ # Authentication SDK
 config/ # Shared configuration utilities
 http-client/ # Client HTTP nội bộ
 logger/ # Structured logging (@goodgo/logger)
 tracing/ # OpenTelemetry tracing
 types/ # TypeScript types chia sẻ
 infra/ # Cấu hình Infrastructure
 databases/ # Scripts thiết lập Database
 docker/ # Docker configurations
 observability/ # Prometheus, Grafana, Loki configs
 secrets/ # Secrets management templates
 traefik/ # Cấu hình API Gateway
 deployments/ # Cấu hình Deploy
 local/ # Docker Compose cho dev
 staging/ # Staging environment configs
 production/ # Production Kubernetes manifests
 scripts/ # Automation scripts
 build/ # Build scripts
 db/ # Database utilities
 deploy/ # Deployment scripts
 dev/ # Development helpers
 observability/ # Monitoring setup scripts
 setup/ # Initial setup scripts
 utils/ # Utility scripts
 docs/ # Tài liệu
 en/ # English documentation
 vi/ # Vietnamese documentation
```

## Cài đặt & Thiết lập

### 1. Clone Repository

```bash
git clone <repository-url>
cd Base
```

### 2. Cấu hình Môi trường

Mỗi service và infrastructure cục bộ cần biến môi trường. Chúng tôi cung cấp templates sẵn.

```bash
# Khởi tạo setup dự án (copy .env.example sang .env)
./scripts/setup/init-project.sh
```

### 3. Thiết lập Neon Database

Dự án sử dụng Neon (Serverless PostgreSQL) cho mọi môi trường.

1. Tạo project tại [neon.tech](https://neon.tech).
2. Tạo branch tên `dev` (hoặc `main`).
3. Lấy Connection String từ dashboard.
4. Cập nhật file `deployments/local/.env.local`:

```env
DATABASE_URL="postgres://user:pass@ep-xyz.region.neon.tech/neondb"
```

### 4. Khởi động Infrastructure

Khởi động các dịch vụ hỗ trợ (Redis, Traefik, Observability) bằng Docker Compose.

```bash
cd deployments/local
docker-compose up -d
# Expected output: Containers for traefik, redis, kafka created
```

### 5. Cài đặt Dependencies

```bash
pnpm install
```

### 6. Setup Database Schema

Đẩy Prisma schema lên Neon database.

```bash
# Chạy migration cho IAM service
pnpm --filter @goodgo/iam-service prisma migrate dev
```

### 7. Khởi động Services

Chạy tất cả backend services ở chế độ development.

```bash
pnpm dev
# hoặc chạy service cụ thể
pnpm --filter @goodgo/iam-service dev
```

## Quy trình Phát triển

### Tạo Service Mới

1. Copy từ template:
 ```bash
 cp -r services/_template services/my-new-service
 ```
2. Cập nhật tên trong `package.json`.
3. Thêm logic trong `src/modules/`.
4. Đăng ký trong `deployments/local/docker-compose.yml`.

### Thực hiện Thay đổi

1. Tạo branch mới: `feature/my-feature`.
2. Implement thay đổi.
3. Chạy tests: `pnpm test`.
4. Commit với conventional commits: `feat(iam): add login endpoint`.

## Các Lệnh Thường dùng

| Lệnh | Mô tả |
| :--- | :--- |
| `pnpm install` | Cài đặt dependencies |
| `pnpm dev` | Chạy tất cả services (dev mode) |
| `pnpm build` | Build tất cả packages và services |
| `pnpm test` | Chạy unit tests |
| `pnpm lint` | Kiểm tra lỗi cú pháp (Lint) |
| `docker-compose up -d` | Bật local infra |
| `docker-compose down` | Tắt local infra |

## Xử lý Sự cố

### Xung đột Port (Port Conflicts)

**Lỗi**: `Bind for 0.0.0.0:80 failed: port is already allocated`

**Giải pháp**: Kiểm tra process nào đang dùng port 80 (thường là web server khác) và tắt nó, hoặc đổi port Traefik trong `docker-compose.yml`.

```bash
lsof -i :80
kill -9 <PID>
```

### Lỗi Kết nối Database

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

**Giải pháp**:
1. Kiểm tra kết nối internet (Neon là cloud DB).
2. Kiểm tra `DATABASE_URL` trong `deployments/local/.env.local`.
3. Đảm bảo IP của bạn được allow trong Neon dashboard.

### Gateway Không Tìm Thấy Service

**Lỗi**: `404 Not Found` từ api.localhost

**Giải pháp**:
1. Kiểm tra service có đang chạy không.
2. Kiểm tra Traefik dashboard tại http://localhost:8080.
3. Kiểm tra labels `PathPrefix` trong `docker-compose.yml`.

## Bước Tiếp Theo

* [Hướng dẫn Development](development.md) - Chi tiết chuẩn code và quy trình
* [Tài liệu API](../api/openapi/) - Khám phá các API endpoints
* [Kiến trúc Hệ thống](../architecture/system-design.md) - Hiểu về thiết kế hệ thống