pos-system/services/_template

Service Template / Template Dịch Vụ

EN: Standard template for creating new microservices in the @goodgo ecosystem. VI: Template chuẩn để tạo các microservice mới trong hệ sinh thái @goodgo.

Features / Tính Năng

• Framework: Express.js with TypeScript / Express.js với TypeScript.
• Database: Prisma ORM with PostgreSQL / Prisma ORM với PostgreSQL.
• Validation: Zod for environment & input validation / Zod cho validation biến môi trường và đầu vào.
• Observability / Khả năng quan sát:
  • Metrics: Prometheus metrics at /metrics / Metrics Prometheus tại /metrics.
  • Logging: Common logger with request tracking / Logger chung với theo dõi request.
  • Tracing: OpenTelemetry/Jaeger integration / Tích hợp OpenTelemetry/Jaeger.
• Resilience / Khả năng phục hồi:
  • Graceful shutdown / Đóng ứng dụng an toàn.
  • Rate limiting (Distributed via Redis) / Giới hạn tốc độ request (Phân tán qua Redis).
  • Circuit Breaker / Ngắt mạch.
  • Health checks (liveness/readiness) / Kiểm tra sức khỏe hệ thống.
• Caching: Redis caching strategy / Chiến lược caching với Redis.
• Security / Bảo mật: Helmet & CORS configured / Đã cấu hình Helmet & CORS.

Project Structure / Cấu trúc Dự án

src/
├── config/         # Configuration & Env validation / Cấu hình & Validate biến môi trường
├── middlewares/    # Express middlewares (error, logger, metrics)
├── modules/        # Feature modules (controller, service, repository)
├── routes/         # API route definitions
└── main.ts         # Entry point & App bootstrapping

Getting Started / Bắt đầu

Prerequisites / Yêu cầu tiên quyết

• Node.js >= 20
• pnpm
• Docker (Redis required)

Installation / Cài đặt

1. Clone & Install dependencies:

   pnpm install
   

2. Environment Setup / Thiết lập môi trường: Copy .env.example to .env (create if missing):

   PORT=5000
   NODE_ENV=development
   DATABASE_URL="postgresql://user:password@localhost:5432/dbname"
   REDIS_URL="redis://localhost:6379"
   TRACING_ENABLED=false
   

3. Run Development / Chạy môi trường phát triển:

   pnpm dev
   

4. Build & Start Production:

   pnpm build
   pnpm start
   

Observability / Khả năng quan sát

• Metrics: Visit http://localhost:5000/metrics.
• Health:
  • Liveness: http://localhost:5000/health/live
  • Readiness: http://localhost:5000/health/ready

Development Guidelines / Hướng dẫn Phát triển

Comments / Comment Code

• Use bilingual comments for all public APIs and complex logic.
• Format: EN first, then VI.
• See .cursor/skills/comment-code/SKILL.md for details.

Adding a Module / Thêm Module

1. Create src/modules/<name>/.
2. Implement Controller, Service.
3. Register routes in src/routes/index.ts.