admin/pos-system

Fork 0

Files

Ho Ngoc Hai 76d75c753b Migrate

2026-05-23 18:37:02 +07:00

7.1 KiB

Raw Permalink 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.

Mục lục

Yêu cầu tiên quyết
Tổng quan Kiến trúc
Cấu trúc Dự án
Cài đặt & Thiết lập
Quy trình Phát triển
Các Lệnh Thường dùng
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 (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