goodgo-platform/docs/dev-environment.md

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

# 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

# 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

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

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

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

# 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

redis-cli -p 6379 ping

Typesense

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

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