pos-system/services/_template_nodejs/README.md

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

Option 1: Local Development / Phát triển Cục bộ

1. Clone & Install dependencies:

   pnpm install
   

2. Start infrastructure with Docker:

   For local development, start the platform infrastructure from deployments/local/: Để phát triển local, khởi động hạ tầng nền tảng từ deployments/local/:

   # Navigate to deployments directory
   cd deployments/local
   
   # Start platform services (PostgreSQL, Redis, Traefik, etc.)
   docker-compose up -d redis
   
   # Return to service directory
   cd ../../services/_template
   

   Note: For full platform deployment with all services, see "Adding This Service to the Platform" section below. Lưu ý: Để triển khai nền tảng đầy đủ với tất cả services, xem phần "Thêm Service Vào Nền Tảng" bên dưới.

3. Setup database:

   pnpm prisma migrate dev
   pnpm prisma db seed
   

4. Start development server:

   pnpm dev
   

5. Environment Setup / Thiết lập môi trường:

   Environment variables are managed at the platform level, not per-service: Biến môi trường được quản lý ở cấp độ nền tảng, không phải mỗi service:

   # EN: Setup shared environment variables (from deployments/local/)
   # VI: Thiết lập biến môi trường chung (từ deployments/local/)
   cd deployments/local
   cp env.local.example .env.local
   # Edit .env.local with your values (JWT_SECRET, DATABASE_URL, etc.)
   

   Environment Variables / Biến Môi trường:

   Shared Variables (in deployments/local/.env.local):

   • JWT_SECRET, JWT_REFRESH_SECRET - Must be same across all services
   • REDIS_HOST, REDIS_PORT - Shared Redis instance
   • CORS_ORIGIN - Allowed origins for all services
   • NODE_ENV, LOG_LEVEL - Common configuration

   Service-Specific Variables (in docker-compose.yml):

   • PORT - Unique port for each service
   • DATABASE_URL - Service's database connection
   • SERVICE_NAME - Service identifier

   Key Environment Variables / Biến Môi Trường Chính:

   Variable / Biến	Description / Mô tả	Default / Mặc định	Required / Bắt buộc
   PORT	Server port / Cổng server	5000	No / Không
   NODE_ENV	Environment mode / Chế độ môi trường	development	No / Không
   API_VERSION	API version prefix / Tiền tố phiên bản API	v1	No / Không
   CORS_ORIGIN	Allowed CORS origins (comma-separated) / Origins CORS được phép	http://localhost:3000	No / Không
   SERVICE_NAME	Service identifier / Mã định danh service	microservice-template	No / Không
   DATABASE_URL	PostgreSQL connection string / Chuỗi kết nối PostgreSQL	-	Yes / Có
   REDIS_URL	Redis connection URL / URL kết nối Redis	redis://localhost:6379	No / Không
   JWT_SECRET	JWT secret key for token signing and verification / Khóa bí mật JWT để ký và xác minh token	-	Yes / Có
   TRACING_ENABLED	Enable Jaeger tracing / Bật tracing Jaeger	false	No / Không
   JAEGER_ENDPOINT	Jaeger collector endpoint / Endpoint collector Jaeger	-	No / Không

   Environment Configuration Priority / Ưu tiên Cấu hình Môi trường:

   1. Docker Compose environment (in deployments/local/docker-compose.yml) - Highest priority
   2. Shared .env.local (in deployments/local/.env.local) - Platform-level shared configs
   3. System environment variables - OS-level environment

6. Database Setup / Thiết lập Database:

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

   • PostgreSQL database running / Database PostgreSQL đang chạy
   • DATABASE_URL configured in .env / DATABASE_URL đã được cấu hình trong .env

   Database Workflow / Quy trình Database:

   # EN: Generate Prisma client / Tạo Prisma client
   pnpm prisma:generate
   
   # EN: Create and run initial migration / Tạo và chạy migration ban đầu
   pnpm prisma:migrate
   
   # EN: (Optional) Seed database with initial data / (Tùy chọn) Seed database với dữ liệu ban đầu
   pnpm prisma:seed
   

   Development Workflow / Quy trình Phát triển:

   # EN: After schema changes, regenerate client / Sau khi thay đổi schema, tạo lại client
   pnpm prisma:generate
   
   # EN: Create new migration for schema changes / Tạo migration mới cho thay đổi schema
   pnpm prisma:migrate dev --name your-migration-name
   
   # EN: View database in Prisma Studio / Xem database trong Prisma Studio
   pnpm prisma:studio
   

   Production Deployment / Triển khai Production:

   # EN: Deploy migrations to production / Triển khai migrations lên production
   pnpm prisma:migrate deploy
   
   # EN: Reset database (CAUTION: destroys all data) / Reset database (CẨN THẬN: xóa tất cả dữ liệu)
   pnpm prisma:migrate reset
   

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

   pnpm dev
   

8. Build & Start Production / Build và Chạy Production:

   pnpm build
   pnpm start
   

Adding This Service to the Platform / Thêm Service Vào Nền Tảng

This template represents a single microservice. To deploy it as part of the GoodGo microservices platform: Template này đại diện cho một microservice đơn lẻ. Để triển khai nó như một phần của nền tảng microservices GoodGo:

1. Register in Platform Compose File / Đăng Ký Trong Platform Compose File

Add your service to deployments/local/docker-compose.yml: Thêm service của bạn vào deployments/local/docker-compose.yml:

services:
  your-service:
    build:
      context: ../..
      dockerfile: services/your-service/Dockerfile
    container_name: your-service-local
    environment:
      - NODE_ENV=development
      - PORT=5002
      - DATABASE_URL=${DATABASE_URL}
      - REDIS_HOST=redis
      - REDIS_PORT=6379
      - JWT_SECRET=${JWT_SECRET}
      - SERVICE_NAME=your-service
      - API_VERSION=v1
      - CORS_ORIGIN=http://localhost:3000,http://localhost:3001
    depends_on:
      redis:
        condition: service_healthy
    networks:
      - microservices-network
    labels:
      # Enable Traefik service discovery
      - "traefik.enable=true"
      # Define routing rule (path-based routing)
      - "traefik.http.routers.your-service.rule=PathPrefix(`/api/v1/your-service`)"
      # Specify the service port
      - "traefik.http.services.your-service.loadbalancer.server.port=5002"
      # Health check configuration
      - "traefik.http.services.your-service.loadbalancer.healthcheck.path=/health/live"
      - "traefik.http.services.your-service.loadbalancer.healthcheck.interval=10s"

2. Start the Platform / Khởi Động Nền Tảng

# Navigate to deployments directory
cd deployments/local

# Start all services including your new service
docker-compose up -d

# View logs for your service
docker-compose logs -f your-service

3. Access Your Service / Truy Cập Service Của Bạn

Once deployed, your service is accessible through Traefik: Sau khi triển khai, service của bạn có thể truy cập qua Traefik:

• API: http://localhost/api/v1/your-service
• Health Check: http://localhost/api/v1/your-service/health
• API Documentation: http://localhost/api/v1/your-service/api-docs
• Traefik Dashboard: http://localhost:8080 (view all registered services)

4. Traefik Configuration / Cấu Hình Traefik

Traefik is configured at the platform level in infra/traefik/: Traefik được cấu hình ở cấp độ nền tảng trong infra/traefik/:

• Static Config: infra/traefik/traefik.yml - Entry points, providers, dashboard
• Dynamic Config: infra/traefik/dynamic/ - Middlewares, routes, services
• Service Discovery: Automatic via Docker labels (no manual route configuration needed)

For advanced routing or middleware, add to infra/traefik/dynamic/routes.yml: Để định tuyến nâng cao hoặc middleware, thêm vào infra/traefik/dynamic/routes.yml:

http:
  routers:
    your-service:
      rule: "PathPrefix(`/api/v1/your-service`)"
      service: your-service
      middlewares:
        - secure-headers
        - cors
        - compress

Observability / Khả năng quan sát

When deployed via the platform (deployments/local/docker-compose.yml), your service exposes: Khi triển khai qua nền tảng (deployments/local/docker-compose.yml), service của bạn expose:

• Metrics: http://localhost/api/v1/your-service/metrics (Prometheus format via Traefik)
• Health Checks:
  • Liveness: http://localhost/api/v1/your-service/health/live
  • Readiness: http://localhost/api/v1/your-service/health/ready
• API Documentation: http://localhost/api/v1/your-service/api-docs (Swagger UI via Traefik)
• Tracing: Jaeger integration (when TRACING_ENABLED=true)
• Correlation IDs: Automatic request tracing with x-correlation-id headers
• Structured Logging: Request/response logging with correlation context

Note: For local development (without platform), replace /api/v1/your-service with http://localhost:5000. Lưu ý: Để phát triển local (không dùng platform), thay /api/v1/your-service bằng http://localhost:5000.

Metrics / Metrics

The service exposes comprehensive Prometheus metrics:

• Request Duration: http_request_duration_seconds (histogram)
• Request Count: http_requests_total (counter)
• Active Requests: http_active_requests (gauge)
• Request Errors: http_request_errors_total (counter)
• Payload Sizes: Request/response payload size histograms
• Default Metrics: Memory, CPU, event loop lag

Correlation IDs / Correlation IDs

Every request gets a correlation ID for tracing across services:

• Header: x-correlation-id (propagated from upstream or auto-generated)
• Request ID: x-request-id (unique per request)
• Logging: All logs include correlation context
• Metrics: Request metrics tagged with correlation ID

Health Checks / Health Checks

• Liveness (/health/live): Basic service availability
• Readiness (/health/ready): Service ready to handle requests (includes DB connectivity)
• Metrics: Health check results are tracked in Prometheus metrics

Logging / Logging

Structured logging with multiple levels:

• Request/Response: Automatic logging with correlation IDs
• Errors: Detailed error logging with stack traces
• Business Logic: Custom logging with context
• Performance: Request duration and resource usage

API Documentation / Tài liệu API

• Swagger UI: Interactive API documentation at /api-docs
• OpenAPI 3.0: Complete API specification
• Request/Response Examples: Real examples for all endpoints
• Authentication: JWT Bearer token examples

Authentication / Xác thực

The service uses JWT (JSON Web Tokens) for authentication. Include the token in the Authorization header as Bearer <token>.

API Documentation / Tài liệu API

Authentication Endpoints / Endpoints Xác thực

Get Current User Info / Lấy Thông tin Người dùng Hiện tại

GET /auth/me
Authorization: Bearer <your-jwt-token>

Feature Management / Quản lý Feature

Base URL: http://localhost/api/v1/features

Create Feature / Tạo Feature

POST /api/v1/features
Authorization: Bearer <admin-jwt-token>
Content-Type: application/json

{
  "name": "example-feature",
  "title": "Example Feature",
  "description": "An example feature for demonstration",
  "config": {
    "enabled": true,
    "priority": 1
  },
  "tags": ["example", "demo"]
}

Required Role: admin

Get All Features / Lấy Tất cả Features

GET /api/v1/features

Get Feature by ID / Lấy Feature theo ID

GET /api/v1/features/{id}

Update Feature / Cập nhật Feature

PUT /api/v1/features/{id}
Content-Type: application/json

{
  "title": "Updated Title",
  "enabled": false
}

Delete Feature / Xóa Feature

DELETE /api/v1/features/{id}

Toggle Feature Status / Chuyển đổi Trạng thái Feature

PATCH /api/v1/features/{id}/toggle

Response Format / Định dạng Response

All API responses follow this structure / Tất cả responses API tuân theo cấu trúc này:

{
  "success": true,
  "data": { ... },
  "message": "Operation completed / Hoạt động hoàn thành",
  "timestamp": "2024-01-01T00:00:00.000Z"
}

Error responses / Responses lỗi:

{
  "success": false,
  "error": {
    "code": "FEATURE_001",
    "message": "Error description / Mô tả lỗi"
  },
  "timestamp": "2024-01-01T00:00:00.000Z"
}

Troubleshooting / Khắc phục sự cố

Common Issues / Vấn đề thường gặp

Database Connection Issues / Vấn đề kết nối Database

Problem: Error: P1001: Can't reach database server

# EN: Check if PostgreSQL is running (from deployments/local/)
# VI: Kiểm tra PostgreSQL có đang chạy (từ deployments/local/)
cd deployments/local
docker-compose ps

# EN: Check database logs
# VI: Kiểm tra logs database
docker-compose logs postgres

# EN: Restart database service
# VI: Khởi động lại database service
docker-compose restart postgres

Problem: Error: P2002: Unique constraint failed

// EN: This usually means you're trying to create a duplicate record
// VI: Điều này thường có nghĩa là bạn đang cố tạo record trùng lặp
// EN: Check your seed data or migration scripts
// VI: Kiểm tra seed data hoặc migration scripts

Authentication Issues / Vấn đề Authentication

Problem: 401 Unauthorized

# EN: Check JWT token format
# VI: Kiểm tra định dạng JWT token
curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost/auth/me

# EN: Verify JWT secret in environment
# VI: Xác minh JWT secret trong environment
echo $JWT_SECRET

# EN: Check token expiration
# VI: Kiểm tra token hết hạn
# EN: Use https://jwt.io to decode your token

Port Already in Use / Port đã được sử dụng

Problem: Error: listen EADDRINUSE: address already in use

# EN: Find process using the port
# VI: Tìm process đang sử dụng port
lsof -i :5000

# EN: Kill the process
# VI: Kill process
kill -9 <PID>

# EN: Or change port in .env
# VI: Hoặc thay đổi port trong .env
PORT=5001

Docker Issues / Vấn đề Docker

Problem: ERROR: Couldn't connect to Docker daemon

# EN: Start Docker service
# VI: Khởi động Docker service
sudo systemctl start docker

# EN: Add user to docker group (Linux)
# VI: Thêm user vào docker group (Linux)
sudo usermod -aG docker $USER

Problem: Container won't start

# EN: Check container logs (from deployments/local/)
# VI: Kiểm tra logs container (từ deployments/local/)
cd deployments/local
docker-compose logs your-service

# EN: Check container health
# VI: Kiểm tra health container
docker-compose ps

# EN: Rebuild without cache
# VI: Rebuild không dùng cache
docker-compose build --no-cache your-service
docker-compose up -d your-service

Test Failures / Test thất bại

Problem: Tests fail with database connection

# EN: Ensure test database is running
# VI: Đảm bảo test database đang chạy
docker-compose -f docker-compose.test.yml up -d

# EN: Run tests with verbose output
# VI: Chạy tests với output verbose
pnpm test -- --verbose

# EN: Reset test database
# VI: Reset test database
docker-compose -f docker-compose.test.yml down -v

Debug Mode / Chế độ Debug

# EN: Enable debug logging (local development)
# VI: Bật debug logging (phát triển local)
DEBUG=* pnpm dev

# EN: Check application health (via platform)
# VI: Kiểm tra health ứng dụng (qua platform)
curl http://localhost/api/v1/your-service/health/ready

# EN: View application logs (from deployments/local/)
# VI: Xem logs ứng dụng (từ deployments/local/)
cd deployments/local
docker-compose logs -f your-service

# EN: Monitor metrics (via platform)
# VI: Monitor metrics (qua platform)
curl http://localhost/api/v1/your-service/metrics

Performance Issues / Vấn đề Performance

Slow Requests:

• Check database query performance
• Review middleware chain efficiency
• Monitor Redis cache hit rates
• Check for memory leaks

High Memory Usage:

# EN: Check memory usage
# VI: Kiểm tra memory usage
docker stats

# EN: Monitor with Prometheus metrics
# VI: Monitor với Prometheus metrics
curl http://localhost/metrics | grep heap

Docker / Docker

Docker Image / Docker Image

This template includes a production-ready Dockerfile with: Template này bao gồm Dockerfile production-ready với:

# Multi-stage build for optimized image size
FROM node:20-alpine AS base
# ... dependency installation
FROM base AS builder
# ... build stage
FROM node:20-alpine AS runner
# ... production runtime

Build the image:

docker build -t your-service:latest .

Docker Compose for Testing / Docker Compose Cho Testing

• docker-compose.test.yml: Isolated test environment with test database and Redis

Run tests in Docker:

docker-compose -f docker-compose.test.yml up -d
DATABASE_URL=postgresql://postgres:test_password@localhost:5433/microservice_test pnpm test
docker-compose -f docker-compose.test.yml down -v

Production Deployment / Triển khai Production

For production deployment, services are orchestrated via: Để triển khai production, các service được điều phối qua:

• Local/Dev: deployments/local/docker-compose.yml
• Staging: deployments/staging/kubernetes/ (Kubernetes manifests)
• Production: deployments/production/kubernetes/ (Kubernetes manifests)

Build production image:

docker build -t your-service:v1.0.0 .
docker tag your-service:v1.0.0 registry.example.com/your-service:v1.0.0
docker push registry.example.com/your-service:v1.0.0

Docker Image Features / Tính năng Docker Image

• Multi-stage Build: Optimized for small production images
• Security: Non-root user, minimal attack surface
• Health Checks: Built-in health check endpoints
• Signal Handling: Proper signal handling with dumb-init
• Layer Caching: Efficient Docker layer caching

Environment Variables for Docker / Biến môi trường cho Docker

When running in Docker, ensure these environment variables are set:

# EN: Database connection
# VI: Kết nối database
DATABASE_URL=postgresql://postgres:password@postgres:5432/microservice_template

# EN: Redis connection
# VI: Kết nối Redis
REDIS_URL=redis://redis:6379

# EN: JWT secret (change in production!)
# VI: JWT secret (thay đổi trong production!)
JWT_SECRET=your-production-jwt-secret

Testing / Kiểm thử

# EN: Run all tests / Chạy tất cả tests
pnpm test

# EN: Run unit tests only / Chạy chỉ unit tests
pnpm test:unit

# EN: Run E2E tests only / Chạy chỉ E2E tests
pnpm test:e2e

# EN: Run tests with coverage / Chạy tests với coverage
pnpm test:coverage

# EN: Run tests in watch mode / Chạy tests ở chế độ watch
pnpm test:watch

# EN: Run tests in specific file / Chạy tests trong file cụ thể
pnpm test src/modules/feature/__tests__/feature.service.test.ts

# EN: Run tests matching pattern / Chạy tests khớp pattern
pnpm test -- --testNamePattern="authentication"

Test Structure / Cấu trúc Test

src/
├── middlewares/__tests__/          # Middleware unit tests
├── modules/
│   ├── feature/__tests__/          # Feature module tests
│   └── health/__tests__/           # Health module tests
├── __tests__/                      # E2E tests
│   ├── health.e2e.ts              # Health endpoint E2E
│   └── feature.e2e.ts             # Feature endpoint E2E
└── config/__tests__/               # Configuration tests

Writing Tests / Viết Tests

Unit Test Example / Ví dụ Unit Test

import { FeatureService } from '../feature.service';
import { featureRepository } from '../feature.repository';

jest.mock('../feature.repository');

describe('FeatureService', () => {
  let service: FeatureService;

  beforeEach(() => {
    service = new FeatureService();
  });

  it('should create feature successfully', async () => {
    const mockFeature = { id: '1', name: 'test', enabled: true };
    (featureRepository.create as jest.Mock).mockResolvedValue(mockFeature);

    const result = await service.create({ name: 'test' });
    expect(result).toEqual(mockFeature);
  });
});

E2E Test Example / Ví dụ E2E Test

import request from 'supertest';
import express from 'express';
import { createRouter } from '../routes';

describe('Feature Endpoints E2E', () => {
  let app: express.Application;

  beforeAll(() => {
    app = express();
    app.use(express.json());
    app.use(createRouter());
  });

  it('should create feature successfully', async () => {
    const response = await request(app)
      .post('/api/v1/features')
      .send({ name: 'test-feature' })
      .expect(201);

    expect(response.body.success).toBe(true);
  });
});

Creating a New Service / Tạo Service Mới

To create a new microservice from this template / Để tạo microservice mới từ template này:

1. Copy Template / Sao chép Template:

   # EN: Copy template to new service directory / Sao chép template vào thư mục service mới
   cp -r services/_template services/your-service-name
   cd services/your-service-name
   

2. Update Package Configuration / Cập nhật Cấu hình Package:

   # EN: Update package.json name and description / Cập nhật tên và mô tả trong package.json
   # VI: Thay đổi "name", "description", và các thông tin khác
   

3. Configure Environment / Cấu hình Môi trường:

   # EN: Set up shared environment variables at platform level
   # VI: Thiết lập biến môi trường chung ở cấp độ nền tảng
   cd ../../deployments/local
   cp env.local.example .env.local
   
   # EN: Edit .env.local with shared values (JWT_SECRET, DATABASE_URL, etc.)
   # VI: Chỉnh sửa .env.local với các giá trị chung (JWT_SECRET, DATABASE_URL, etc.)
   nano .env.local
   

4. Database Setup / Thiết lập Database:

   # EN: Update Prisma schema with your models / Cập nhật schema Prisma với models của bạn
   # VI: Chỉnh sửa prisma/schema.prisma
   
   # EN: Generate and run migrations / Tạo và chạy migrations
   pnpm prisma:generate
   pnpm prisma:migrate
   

5. Implement Business Logic / Triển khai Logic Kinh doanh:

   • Add your modules in src/modules/
   • Update routes in src/routes/index.ts
   • Add validation schemas and DTOs

6. Testing / Kiểm thử:

   # EN: Add tests for your new functionality / Thêm tests cho chức năng mới
   pnpm test
   

7. Documentation / Tài liệu:

   • Update README.md with service-specific information
   • Update ARCHITECTURE.md if needed
   • Update OpenAPI documentation in route files

Extending the Template / Mở rộng Template

Adding a New Module / Thêm Module Mới

1. Create Module Structure / Tạo cấu trúc Module:

   mkdir -p src/modules/your-module/{__tests__}
   touch src/modules/your-module/your-module.{controller,service,repository,dto,module}.ts
   touch src/modules/your-module/__tests__/your-module.{service,controller}.test.ts
   

2. Implement Repository / Triển khai Repository:

   // src/modules/your-module/your-module.repository.ts
   import { BaseRepository } from '../common/repository';
   import { prisma } from '../../config/database.config';
   
   export class YourModuleRepository extends BaseRepository<YourEntity, CreateInput, UpdateInput> {
     constructor() {
       super(prisma, 'yourEntity');
     }
   
     async findByCustomField(value: string): Promise<YourEntity[]> {
       return this.prisma.yourEntity.findMany({
         where: { customField: value },
       });
     }
   }
   
   export const yourModuleRepository = new YourModuleRepository();
   

3. Implement Service / Triển khai Service:

   // src/modules/your-module/your-module.service.ts
   import { yourModuleRepository } from './your-module.repository';
   import { CreateYourEntityDto, UpdateYourEntityDto } from './your-module.dto';
   
   export class YourModuleService {
     async create(data: CreateYourEntityDto) {
       // Business logic
       return yourModuleRepository.create(data);
     }
   
     async findAll() {
       return yourModuleRepository.findAll();
     }
   }
   

4. Implement Controller / Triển khai Controller:

   // src/modules/your-module/your-module.controller.ts
   import { Request, Response } from 'express';
   import { asyncHandler } from '../../middlewares/error.middleware';
   import { YourModuleService } from './your-module.service';
   
   export class YourModuleController {
     private service = new YourModuleService();
   
     create = asyncHandler(async (req: Request, res: Response) => {
       const result = await this.service.create(req.body);
       res.status(201).json({
         success: true,
         data: result,
         message: 'Created successfully',
         timestamp: new Date().toISOString(),
       });
     });
   
     findAll = asyncHandler(async (req: Request, res: Response) => {
       const result = await this.service.findAll();
       res.json({
         success: true,
         data: result,
         message: 'Retrieved successfully',
         timestamp: new Date().toISOString(),
       });
     });
   }
   

5. Create Routes / Tạo Routes:

   // src/modules/your-module/your-module.module.ts
   import { Router } from 'express';
   import { YourModuleController } from './your-module.controller';
   import { validateDto } from '../../middlewares/validation.middleware';
   
   export const createYourModuleRouter = (): Router => {
     const router = Router();
     const controller = new YourModuleController();
   
     router.post('/', validateDto(createYourEntitySchema), controller.create);
     router.get('/', controller.findAll);
   
     return router;
   };
   

6. Register Routes / Đăng ký Routes:

   // src/routes/index.ts
   import { createYourModuleRouter } from '../modules/your-module/your-module.module';
   
   router.use('/api/v1/your-entities', createYourModuleRouter());
   

Adding Environment Variables / Thêm Biến Môi trường

1. Update config schema / Cập nhật config schema:

   // src/config/app.config.ts
   const envSchema = z.object({
     // ... existing fields
     YOUR_NEW_VARIABLE: z.string().default('default-value'),
   });
   
   export const appConfig = {
     // ... existing config
     yourNewVariable: config.YOUR_NEW_VARIABLE,
   };
   

2. Update .env files / Cập nhật file .env:

   # .env.example
   YOUR_NEW_VARIABLE=your-default-value
   
   # .env.local.example
   YOUR_NEW_VARIABLE=your-local-value
   

Security Best Practices / Thực tiễn Bảo mật

• Input Validation: Always validate and sanitize user inputs using Zod
• Authentication: Use JWT tokens with reasonable expiration times
• Authorization: Implement proper RBAC for your endpoints
• Rate Limiting: Protect against abuse with distributed rate limiting
• HTTPS: Always use HTTPS in production
• Secrets: Never commit secrets to version control
• Dependencies: Keep dependencies updated and audit regularly

Performance Considerations / Lưu ý Performance

• Database Queries: Use indexes for frequently queried fields
• Caching: Implement Redis caching for expensive operations
• Connection Pooling: Configure appropriate connection pool sizes
• Async Operations: Use proper async/await patterns
• Memory Management: Monitor memory usage and implement cleanup
• Metrics: Monitor performance with built-in Prometheus metrics

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.

Code Style / Phong cách Code

• Follow the established patterns in existing modules
• Use TypeScript strictly with proper type annotations
• Implement proper error handling with custom error classes
• Add comprehensive tests for all new functionality