# 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
    ```bash
    node -v
    # v20.10.0
    ```
*   **PNPM**: v8.0.0 trở lên (sử dụng pnpm workspaces)
    ```bash
    pnpm -v
    # 8.12.0
    ```
*   **Docker & Docker Compose**: Cho infrastructure cục bộ
    ```bash
    docker -v
    # Docker version 24.0.0
    ```
*   **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 Traefik fill:#e1f5ff
    style DB fill:#f0e1ff
    style Redis fill:#fff4e1
```

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

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

```
Base/
├── apps/                 # Ứng dụng Frontend
│   ├── web-client/       # Next.js web application
│   └── mobile-client/    # Flutter mobile application
├── 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)
│   ├── logger/           # Structured logging
│   ├── types/            # TypeScript types chia sẻ
│   └── http-client/      # Client HTTP nội bộ
├── infra/                # Cấu hình Infrastructure
│   ├── traefik/          # Cấu hình API Gateway
│   └── databases/        # Scripts thiết lập Database
├── deployments/          # Cấu hình Deploy
│   ├── local/            # Docker Compose cho dev
│   └── k8s/              # Kubernetes manifests
└── docs/                 # Tài liệu
```

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