eca4b84249
BREAKING CHANGE: All shared packages now export ES modules instead of CommonJS - Changed TypeScript compilation target from commonjs to ES2020 - Updated packages/config/tsconfig/node.json module format - Updated packages/types/tsconfig.json with moduleResolution - All packages (@goodgo/types, @goodgo/http-client, @goodgo/logger, @goodgo/auth-sdk, @goodgo/tracing) now output ES modules - Updated README.md and README.vi.md with migration guide Migration required: - Replace any require() statements with import - Clean and rebuild packages after pulling changes Closes: Module format mismatch errors in Next.js build
248 lines
9.0 KiB
Markdown
248 lines
9.0 KiB
Markdown
# Nền tảng Microservices GoodGo
|
|
|
|
[](README.md) [](README.vi.md)
|
|
|
|
Nền tảng microservices cấp doanh nghiệp được xây dựng với các công nghệ hiện đại và thực tiễn tốt nhất.
|
|
|
|
## 🏗️ Kiến trúc
|
|
|
|
Monorepo này tuân theo mô hình kiến trúc microservices với:
|
|
|
|
- **Apps**: Các ứng dụng Frontend (Web + Mobile)
|
|
- **Services**: Các Backend microservices (Node.js/TypeScript)
|
|
- **Packages**: Các thư viện và tiện ích dùng chung
|
|
- **Infrastructure**: Traefik, Observability, Databases
|
|
- **Deployments**: Cấu hình riêng cho từng môi trường
|
|
|
|
## 📁 Cấu trúc Dự án
|
|
|
|
```
|
|
├── apps/ # Ứng dụng Frontend
|
|
│ ├── web-admin/ # Web admin (Next.js)
|
|
│ ├── web-client/ # Web client (Next.js)
|
|
│ ├── app-admin/ # App admin (Flutter)
|
|
│ └── app-client/ # App client (Flutter)
|
|
├── services/ # Backend microservices
|
|
│ ├── iam-service/ # Dịch vụ IAM (Identity & Access Management) (Node.js)
|
|
│ └── _template/ # Template mẫu cho service mới
|
|
├── packages/ # Thư viện dùng chung
|
|
│ ├── auth-sdk/ # Tiện ích xác thực và guards
|
|
│ ├── config/ # Cấu hình chung
|
|
│ ├── http-client/ # API client chuẩn hóa
|
|
│ ├── logger/ # Logging tập trung (Winston)
|
|
│ ├── tracing/ # Cấu hình OpenTelemetry
|
|
│ └── types/ # Các kiểu dữ liệu TypeScript dùng chung
|
|
├── infra/ # Infrastructure as Code
|
|
│ ├── databases/ # Cấu hình Database (PostgreSQL/Neon, Redis)
|
|
│ ├── docker/ # File Docker compose
|
|
│ ├── observability/ # Stack giám sát (Prometheus, Grafana, Loki)
|
|
│ ├── secrets/ # Quản lý bảo mật
|
|
│ └── traefik/ # Cấu hình API Gateway
|
|
├── deployments/ # Cấu hình môi trường
|
|
│ ├── local/ # Thiết lập dev local
|
|
│ ├── staging/ # Môi trường Staging (Kubernetes)
|
|
│ └── production/ # Môi trường Production (Kubernetes)
|
|
├── scripts/ # Script tự động hóa (Song ngữ EN/VI)
|
|
│ ├── build/ # Script build
|
|
│ ├── db/ # Quản lý Database (backup, seed, migrate)
|
|
│ ├── deploy/ # Script deploy
|
|
│ ├── dev/ # Hỗ trợ Development
|
|
│ ├── setup/ # Khởi tạo dự án
|
|
│ └── utils/ # Script tiện ích
|
|
└── docs/ # Tài liệu
|
|
```
|
|
|
|
## ⚠️ Thay Đổi Quan Trọng (Breaking Changes)
|
|
|
|
### v1.0.0 - Di chuyển sang ES Modules (2026-01-07)
|
|
|
|
**BREAKING**: Tất cả shared packages hiện sử dụng ES modules thay vì CommonJS.
|
|
|
|
**Những gì đã thay đổi:**
|
|
- Đích compile của TypeScript đã đổi từ `commonjs` sang `ES2020`
|
|
- Tất cả packages (`@goodgo/types`, `@goodgo/http-client`, `@goodgo/logger`, `@goodgo/auth-sdk`, `@goodgo/tracing`) hiện xuất ra ES modules
|
|
- File `package.json` đã khai báo `"type": "module"`, giờ output TypeScript đã khớp
|
|
|
|
**Cần di chuyển code:**
|
|
Nếu bạn có code hiện tại đang import các packages này:
|
|
|
|
```typescript
|
|
// ✅ Cách này vẫn hoạt động (không cần thay đổi trong hầu hết trường hợp)
|
|
import { UserResponse } from '@goodgo/types';
|
|
import { createHttpClient } from '@goodgo/http-client';
|
|
|
|
// ⚠️ Nếu bạn đang dùng require() (CommonJS), bạn phải cập nhật:
|
|
// ❌ CŨ: const { UserResponse } = require('@goodgo/types');
|
|
// ✅ MỚI: import { UserResponse } from '@goodgo/types';
|
|
```
|
|
|
|
**Hành động cần thiết:**
|
|
1. Pull code mới nhất
|
|
2. Clean và rebuild: `pnpm -r --filter "./packages/*" run clean && pnpm build`
|
|
3. Cập nhật mọi câu lệnh `require()` (CommonJS) thành `import` (ES)
|
|
|
|
**Files đã thay đổi:**
|
|
- `packages/config/tsconfig/node.json` - Đổi `"module": "commonjs"` → `"module": "ES2020"`
|
|
- `packages/types/tsconfig.json` - Thêm `"moduleResolution": "node"`
|
|
|
|
Để biết thông tin chi tiết, xem [Hướng dẫn Di chuyển](docs/vi/guides/module-format-migration.md).
|
|
|
|
## 🚀 Bắt đầu
|
|
|
|
### Yêu cầu tiên quyết
|
|
|
|
- Node.js >= 20.0.0
|
|
- pnpm >= 8.0.0
|
|
- Docker & Docker Compose
|
|
- Tài khoản Neon (https://neon.tech) - cho PostgreSQL database
|
|
|
|
### Khởi tạo nhanh (1 Lệnh duy nhất)
|
|
|
|
Chúng tôi cung cấp script khởi tạo toàn diện để bạn bắt đầu nhanh chóng:
|
|
|
|
```bash
|
|
./scripts/setup/init-project.sh
|
|
```
|
|
|
|
Script này sẽ:
|
|
1. Kiểm tra các yêu cầu tiên quyết
|
|
2. Cài đặt dependencies
|
|
3. Tạo Prisma clients
|
|
4. Tạo các file `.env` cần thiết từ file mẫu
|
|
|
|
### Cài đặt thủ công
|
|
|
|
Nếu bạn muốn thiết lập thủ công:
|
|
|
|
```bash
|
|
# Cài đặt dependencies
|
|
pnpm install
|
|
|
|
# Tạo Prisma clients
|
|
pnpm prisma:generate
|
|
|
|
# Khởi động tất cả services (chế độ development)
|
|
./scripts/dev/start-all.sh
|
|
```
|
|
|
|
### Quy trình Development Local
|
|
|
|
1. **Thiết lập Database**:
|
|
```bash
|
|
./scripts/db/setup-neon.sh
|
|
# Làm theo hướng dẫn để cấu hình Neon URL của bạn
|
|
```
|
|
|
|
2. **Khởi động Infrastructure**:
|
|
```bash
|
|
# Khởi động Redis, Traefik, và Observability stack
|
|
cd deployments/local
|
|
docker-compose up -d
|
|
```
|
|
|
|
3. **Chạy Migrations**:
|
|
```bash
|
|
./scripts/db/migrate.sh iam-service dev
|
|
```
|
|
|
|
4. **Khởi động Services**:
|
|
```bash
|
|
./scripts/dev/start-all.sh
|
|
# Hoặc khởi động service cụ thể:
|
|
# ./scripts/dev/start-service.sh iam-service
|
|
```
|
|
|
|
## 🛠️ Các Script Hỗ trợ
|
|
|
|
Thư mục `scripts/` chứa các script tự động hóa song ngữ (Anh/Việt) giúp đơn giản hóa các tác vụ hàng ngày:
|
|
|
|
| Danh mục | Script | Mô tả |
|
|
|---|---|---|
|
|
| **Setup** | `init-project.sh` | Khởi tạo toàn bộ dự án |
|
|
| | `install-deps.sh` | Cài đặt dependencies |
|
|
| **Dev** | `start-all.sh` | Khởi động hạ tầng và tất cả services |
|
|
| | `start-service.sh` | Khởi động một service cụ thể |
|
|
| | `logs.sh` | Xem log của services hoặc docker containers |
|
|
| | `setup-env.sh` | Hỗ trợ thiết lập biến môi trường |
|
|
| **DB** | `migrate.sh` | Chạy Prisma migrations (dev/deploy) |
|
|
| | `seed.sh` | Seed data ban đầu cho database |
|
|
| | `backup.sh` | Backup database (hỗ trợ Neon) |
|
|
| | `setup-neon.sh` | Wizard cấu hình kết nối Neon DB |
|
|
| **Utils** | `create-service.sh` | Tạo microservice mới từ template |
|
|
| | `cleanup.sh` | Dọn dẹp file build và cache |
|
|
| **Build** | `build-all.sh` | Build toàn bộ monorepo |
|
|
| | `build-service.sh` | Build service cụ thể |
|
|
| **Deploy** | `deploy-staging.sh` | Deploy lên cluster staging |
|
|
| | `deploy-prod.sh` | Deploy lên cluster production |
|
|
|
|
## 🛠️ Công nghệ sử dụng
|
|
|
|
**Frontend:**
|
|
- Web: Next.js 14+ (App Router)
|
|
- Mobile: Flutter 3.x
|
|
- Styling: Tailwind CSS
|
|
- State: Zustand / Provider
|
|
|
|
**Backend:**
|
|
- Runtime: Node.js + TypeScript
|
|
- Framework: Express/NestJS (thông qua service template)
|
|
- ORM: Prisma
|
|
- Database: PostgreSQL (Neon Serverless), Redis (Caching/Queues)
|
|
|
|
**Infrastructure:**
|
|
- Gateway: Traefik
|
|
- Containerization: Docker
|
|
- Orchestration: Kubernetes
|
|
- Observability: Prometheus, Grafana, Loki, OpenTelemetry
|
|
|
|
**DevOps:**
|
|
- Build System: Turborepo
|
|
- Package Manager: PNPM Workspaces
|
|
- CI/CD: GitHub Actions
|
|
|
|
## 🌐 Tiêu chuẩn Code
|
|
|
|
### Comment Song ngữ
|
|
Để hỗ trợ đội ngũ đa dạng, chúng tôi tuân thủ tiêu chuẩn comment song ngữ (Anh & Việt) cho:
|
|
- Scripts
|
|
- Các logic phức tạp
|
|
- Public APIs
|
|
- Các file cấu hình
|
|
|
|
Ví dụ:
|
|
```bash
|
|
# EN: Verify Docker daemon is running
|
|
# VI: Xác minh Docker daemon đang chạy
|
|
```
|
|
|
|
### Quản lý Monorepo
|
|
- Sử dụng **Turborepo** cho quy trình build và caching.
|
|
- **PNPM Workspaces** quản lý dependencies giữa các apps và services.
|
|
|
|
## 📚 Tài liệu
|
|
|
|
- [Tổng quan Kiến trúc](docs/vi/architecture/system-design.md)
|
|
- [Tài liệu API](docs/vi/api/openapi/)
|
|
- [Hướng dẫn Phát triển](docs/vi/guides/development.md)
|
|
- [Hướng dẫn Deployment](docs/vi/guides/deployment.md)
|
|
- [Hướng dẫn Đóng góp](CONTRIBUTING.md)
|
|
|
|
## 🔐 Biến môi trường
|
|
|
|
**Quan trọng**: Không bao giờ commit file `.env`. Hãy sử dụng `.env.example` làm mẫu.
|
|
|
|
- **Dev**: `deployments/local/.env.local` (Dùng chung), `services/*/.env.local` (Riêng cho Service)
|
|
- **Staging/Prod**: Được quản lý qua Kubernetes Secrets
|
|
|
|
## 🤝 Đóng góp
|
|
|
|
Vui lòng đọc file [CONTRIBUTING.md](CONTRIBUTING.md) để biết chi tiết về quy tắc ứng xử và quy trình gửi pull requests của chúng tôi.
|
|
|
|
## 📄 Giấy phép
|
|
|
|
Dự án này được cấp phép theo Giấy phép MIT - xem file [LICENSE](LICENSE) để biết chi tiết.
|
|
|
|
## 👥 Nhóm phát triển
|
|
|
|
Được xây dựng với ❤️ bởi đội ngũ GoodGo
|