pos-system/README.vi.md

Nền tảng Microservices GoodGo

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:

// ✅ 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.

🚀 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:

./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:

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

   ./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:

   # Khởi động Redis, Traefik, và Observability stack
   cd deployments/local
   docker-compose up -d
   

3. Chạy Migrations:

   ./scripts/db/migrate.sh iam-service dev
   

4. Khởi động Services:

   ./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ụ:

# 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
• Tài liệu API
• Hướng dẫn Phát triển
• Hướng dẫn Deployment
• Hướng dẫn Đóng góp

🔐 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 để 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 để biết chi tiết.

👥 Nhóm phát triển

Được xây dựng với ❤️ bởi đội ngũ GoodGo