215 lines
6.1 KiB
Markdown
215 lines
6.1 KiB
Markdown
# 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
|