Update project documentation and scripts for improved setup and bilingual support

- Enhanced `README.md` with a quick start guide and detailed project structure. - Updated `SETUP_GUIDE.md` by removing it as it was redundant. - Improved `local-development.md` and `development.md` with clearer instructions for database migrations. - Added bilingual comments in various scripts for better understanding and usability. - Updated `.gitignore` to include specific build scripts while ignoring others. - Enhanced `scripts` for database management, including backup and seeding functionalities with bilingual support.
2025-12-27 10:12:46 +07:00
parent 79866e22cf
commit 29c40ea681
23 changed files with 528 additions and 392 deletions
--- a/README.vi.md
+++ b/README.vi.md
@@ -0,0 +1,212 @@
+# 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
+│   ├── auth-service/    # Dịch vụ xác thực (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
+```
+
+## 🚀 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 auth-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 auth-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