Files

Ho Ngoc Hai 510e2306cd feat(docs): Update getting started and local development guides with new prerequisites and improved flow

- Enhanced Node.js and PNPM version recommendations in the getting started guide.
- Added a color palette section with Mermaid diagrams for better visual representation.
- Improved the workflow steps in the local development guide for clarity and consistency.
- Updated Vietnamese documentation to reflect changes in the English version.
- Refactored database migration and seeding scripts for better error handling and user feedback.

2026-01-08 15:37:25 +07:00

8.2 KiB

Raw Blame History

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.

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+)
```
node -v
# v25.2.1
```
PNPM: v8.15.0 trở lên (sử dụng pnpm workspaces)
```
pnpm -v
# 8.15.0
```
Docker & Docker Compose: v24.0.0 trở lên cho infrastructure cục bộ
```
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ẻ.

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

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

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.

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

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

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.

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

5. Cài đặt Dependencies

pnpm install

6. Setup Database Schema

Đẩy Prisma schema lên Neon database.

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

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

Copy từ template:

cp -r services/_template services/my-new-service

Cập nhật tên trong package.json.
Thêm logic trong src/modules/.
Đăng ký trong deployments/local/docker-compose.yml.

Thực hiện Thay đổi

Tạo branch mới: feature/my-feature.
Implement thay đổi.
Chạy tests: pnpm test.
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.

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:

Kiểm tra kết nối internet (Neon là cloud DB).
Kiểm tra DATABASE_URL trong deployments/local/.env.local.
Đả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