# Môi Trường Phát Triển

## Yêu Cầu Cài Đặt

- **Docker Engine 24+** & Docker Compose v2
- **Node.js 22 LTS**
- **pnpm 10.27+** — cài đặt qua `corepack enable && corepack prepare pnpm@latest --activate`

## Khởi Động Nhanh

```bash
# 1. Sao chép các biến môi trường
cp .env.example .env

# 2. Khởi động tất cả dịch vụ hạ tầng
docker compose up -d

# 3. Kiểm tra tất cả dịch vụ đang hoạt động bình thường
docker compose ps

# 4. Cài đặt các phụ thuộc
pnpm install

# 5. Tạo Prisma client
pnpm db:generate

# 6. Chạy các migration cơ sở dữ liệu
pnpm db:migrate:dev

# 7. Seed dữ liệu vào cơ sở dữ liệu (tuỳ chọn)
pnpm db:seed

# 8. Khởi động API và Web ở chế độ phát triển
pnpm dev
```

API chạy tại `http://localhost:3001/api/v1`, Web tại `http://localhost:3000`.

> **Swagger UI**: `http://localhost:3001/api/v1/docs` — tài liệu API tương tác.

## Các Dịch Vụ Hạ Tầng

| Dịch vụ | Cổng | Mô tả | Bảng điều khiển/UI |
|---------|---------|-------------|--------------|
| PostgreSQL + PostGIS | 5432 | Cơ sở dữ liệu với truy vấn không gian địa lý | — |
| Redis | 6379 | Cache, phiên đăng nhập, hàng đợi | — |
| Typesense | 8108 | Công cụ tìm kiếm toàn văn bản | `http://localhost:8108/health` |
| MinIO | 9000 / 9001 | Lưu trữ đối tượng tương thích S3 | `http://localhost:9001` (console) |
| AI Services | 8000 | FastAPI — AVM + kiểm duyệt nội dung | `http://localhost:8000/health` |
| Prometheus | 9090 | Thu thập số liệu giám sát | `http://localhost:9090` |
| Grafana | 3002 | Bảng điều khiển & giám sát | `http://localhost:3002` |

## Các Lệnh Thông Dụng

### Docker Compose

```bash
# Khởi động các dịch vụ
docker compose up -d

# Xem nhật ký (tất cả hoặc từng dịch vụ cụ thể)
docker compose logs -f
docker compose logs -f postgres

# Dừng các dịch vụ (dữ liệu được giữ nguyên trong volume)
docker compose down

# Dừng và xoá toàn bộ dữ liệu
docker compose down -v

# Khởi động lại một dịch vụ đơn lẻ
docker compose restart redis

# Kiểm tra tình trạng dịch vụ
docker compose ps
```

### Phát Triển

```bash
pnpm dev              # Khởi động tất cả ứng dụng ở chế độ theo dõi
pnpm build            # Build tất cả các gói
pnpm lint             # ESLint trên toàn bộ monorepo
pnpm typecheck        # Kiểm tra kiểu TypeScript
pnpm format           # Định dạng bằng Prettier
pnpm test             # Chạy kiểm thử đơn vị/tích hợp
```

### Cơ Sở Dữ Liệu

```bash
pnpm db:generate      # Tạo lại Prisma client
pnpm db:migrate:dev   # Tạo và áp dụng các migration
pnpm db:seed          # Seed dữ liệu vào cơ sở dữ liệu
pnpm db:studio        # Mở Prisma Studio (trình chỉnh sửa trực quan)
pnpm db:reset         # Đặt lại cơ sở dữ liệu (thao tác phá huỷ dữ liệu)
```

### Kiểm Thử E2E

```bash
pnpm test:e2e         # Chạy tất cả kiểm thử E2E
pnpm test:e2e:api     # Chỉ kiểm thử API
pnpm test:e2e:web     # Chỉ kiểm thử giao diện Web
pnpm test:e2e:report  # Mở báo cáo kiểm thử HTML
```

## Kết Nối Đến Các Dịch Vụ

### PostgreSQL

```bash
# Qua psql
psql postgresql://goodgo:goodgo_secret@localhost:5432/goodgo

# Xác minh PostGIS
psql postgresql://goodgo:goodgo_secret@localhost:5432/goodgo -c "SELECT PostGIS_Version();"
```

### Redis

```bash
redis-cli -p 6379 ping
```

### Typesense

```bash
curl http://localhost:8108/health
```

### MinIO

- **API**: `http://localhost:9000`
- **Console**: `http://localhost:9001` (đăng nhập bằng `MINIO_ACCESS_KEY` / `MINIO_SECRET_KEY` từ file `.env`)

### AI Services

```bash
curl http://localhost:8000/health
```

### Grafana

- **URL**: `http://localhost:3002`
- **Đăng nhập**: `admin` / `admin` (mặc định, có thể cấu hình qua `.env`)

## Xử Lý Sự Cố

- **Xung đột cổng** — Thay đổi cổng trong `.env` (ví dụ: `DB_PORT=5433`)
- **Lỗi quyền truy cập** — Chạy `docker compose down -v` rồi khởi động lại
- **PostGIS không khả dụng** — Đảm bảo đang sử dụng image `postgis/postgis:16-3.4`
- **Prisma client lỗi thời** — Chạy `pnpm db:generate` sau khi kéo các thay đổi schema
- **AI service không khởi động được** — Kiểm tra `docker compose logs ai-services` để xem lỗi phụ thuộc Python
- **Typesense không khoẻ mạnh** — Xác minh `TYPESENSE_API_KEY` khớp trong `.env` và cấu hình Docker