# Nền tảng Microservices GoodGo

[![English](https://img.shields.io/badge/Language-English-blue.svg)](README.md) [![Tiếng Việt](https://img.shields.io/badge/Ngôn%20ngữ-Tiếng%20Việt-red.svg)](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