pos-system/docs/vi/skills/project-rules.md

Quy Tắc Dự Án

GoodGo Microservices Platform coding standards and architecture patterns. Use when working with services, apps, packages, or infrastructure.

Tiêu chuẩn mã hóa và mẫu kiến trúc của GoodGo Microservices Platform. Sử dụng khi làm việc với services, apps, packages, hoặc infrastructure.

Tổng Quan

The Project Rules skill provides comprehensive guidelines for the GoodGo Microservices Platform architecture, coding standards, naming conventions, workflows, and best practices. This skill ensures consistency across all services, packages, and applications in the monorepo.

Skill Project Rules cung cấp hướng dẫn toàn diện về kiến trúc GoodGo Microservices Platform, tiêu chuẩn mã hóa, quy ước đặt tên, quy trình làm việc và thực hành tốt nhất. Skill này đảm bảo tính nhất quán trên tất cả services, packages và applications trong monorepo.

Khi Nào Sử Dụng

Use this skill when:

• Creating a new service or package
• Setting up project structure
• Following naming conventions
• Understanding deployment patterns
• Working with dependencies
• Configuring Docker containers
• Setting up CI/CD workflows
• Understanding the monorepo structure

Sử dụng skill này khi:

• Tạo service hoặc package mới
• Thiết lập cấu trúc dự án
• Tuân theo quy ước đặt tên
• Hiểu các mẫu triển khai
• Làm việc với dependencies
• Cấu hình Docker containers
• Thiết lập CI/CD workflows
• Hiểu cấu trúc monorepo

Khái Niệm Chính

Kiến Trúc

The platform follows a microservices architecture with:

• Apps: Next.js (web) + Flutter (mobile)
• Services: Node.js/TypeScript microservices (Express)
• Packages: Shared libraries (logger, types, http-client, auth-sdk, tracing)
• Infrastructure: Traefik (API Gateway), Redis, Neon PostgreSQL, Observability
• Deployments: Local (Docker Compose), Staging/Production (Kubernetes)

Nền tảng tuân theo kiến trúc microservices với:

• Apps: Next.js (web) + Flutter (mobile)
• Services: Node.js/TypeScript microservices (Express)
• Packages: Thư viện dùng chung (logger, types, http-client, auth-sdk, tracing)
• Infrastructure: Traefik (API Gateway), Redis, Neon PostgreSQL, Observability
• Deployments: Local (Docker Compose), Staging/Production (Kubernetes)

Công Nghệ

Frontend:

• Next.js 14+ (App Router), TypeScript, Tailwind CSS, Zustand
• Flutter 3.x with Provider pattern
• Use @goodgo/types and @goodgo/http-client

Backend:

• Node.js 20+, TypeScript 5+, Express
• Prisma ORM + Neon PostgreSQL
• Zod validation, @goodgo/logger, @goodgo/tracing, @goodgo/auth-sdk

Infrastructure:

• Traefik (path-based routing), Redis (cache), Prometheus + Grafana + Loki

Các Pattern Thường Dùng

Cấu Trúc Service

Standard service structure:

services/[service-name]/
├── src/
│   ├── config/          # Configuration files
│   ├── modules/         # Feature modules
│   ├── middlewares/     # Express middlewares
│   ├── repositories/    # Data access layer
│   ├── routes/          # Route definitions
│   └── main.ts         # Entry point
├── prisma/             # Database schema
├── Dockerfile          # Container definition
└── package.json        # Dependencies

Cấu trúc service chuẩn:

services/[service-name]/
├── src/
│   ├── config/          # File cấu hình
│   ├── modules/         # Module tính năng
│   ├── middlewares/     # Express middlewares
│   ├── repositories/    # Lớp truy cập dữ liệu
│   ├── routes/          # Định nghĩa routes
│   └── main.ts         # Điểm vào
├── prisma/             # Database schema
├── Dockerfile          # Định nghĩa container
└── package.json        # Dependencies

Pattern Module

Controller → Service → Repository pattern:

// DTO with Zod
export const CreateFeatureDto = z.object({
  name: z.string().min(1),
  email: z.string().email()
});
export type CreateFeatureDto = z.infer<typeof CreateFeatureDto>;

// Controller
export class FeatureController {
  constructor(private service: FeatureService) {}
  async create(req: Request, res: Response, next: NextFunction) {
    try {
      const dto = CreateFeatureDto.parse(req.body);
      const result = await this.service.create(dto);
      res.json({ success: true, data: result });
    } catch (error) { next(error); }
  }
}

// Service
export class FeatureService {
  constructor(private repository: FeatureRepository) {}
  async create(dto: CreateFeatureDto) {
    return this.repository.create(dto);
  }
}

// Repository
export class FeatureRepository extends BaseRepository<Feature> {
  async create(data: CreateFeatureDto) {
    return this.prisma.feature.create({ data });
  }
}

Pattern Controller → Service → Repository:

// DTO với Zod
export const CreateFeatureDto = z.object({
  name: z.string().min(1),
  email: z.string().email()
});
export type CreateFeatureDto = z.infer<typeof CreateFeatureDto>;

// Controller
export class FeatureController {
  constructor(private service: FeatureService) {}
  async create(req: Request, res: Response, next: NextFunction) {
    try {
      const dto = CreateFeatureDto.parse(req.body);
      const result = await this.service.create(dto);
      res.json({ success: true, data: result });
    } catch (error) { next(error); }
  }
}

// Service
export class FeatureService {
  constructor(private repository: FeatureRepository) {}
  async create(dto: CreateFeatureDto) {
    return this.repository.create(dto);
  }
}

// Repository
export class FeatureRepository extends BaseRepository<Feature> {
  async create(data: CreateFeatureDto) {
    return this.prisma.feature.create({ data });
  }
}

Pattern Phản Hồi API

Standardized API responses:

// Success response
{
  success: true,
  data: any,
  timestamp: string
}

// Error response
{
  success: false,
  error: {
    code: string,
    message: string,
    details?: any
  },
  timestamp: string
}

Phản hồi API chuẩn hóa:

// Phản hồi thành công
{
  success: true,
  data: any,
  timestamp: string
}

// Phản hồi lỗi
{
  success: false,
  error: {
    code: string,
    message: string,
    details?: any
  },
  timestamp: string
}

Thực Hành Tốt Nhất

Quy Ước Đặt Tên

• Services/Packages: kebab-case (e.g., iam-service, http-client)
• Files: kebab-case.type.ts (e.g., user.controller.ts)
• Components: PascalCase.tsx (React), snake_case.dart (Flutter)
• Classes: PascalCase
• Functions: camelCase
• Constants: UPPER_SNAKE_CASE
• Package Names: @goodgo/package-name

VI:

• Services/Packages: kebab-case (ví dụ: iam-service, http-client)
• Files: kebab-case.type.ts (ví dụ: user.controller.ts)
• Components: PascalCase.tsx (React), snake_case.dart (Flutter)
• Classes: PascalCase
• Functions: camelCase
• Constants: UPPER_SNAKE_CASE
• Package Names: @goodgo/package-name

Tiêu Chuẩn TypeScript

• Strict mode enabled
• No any type (use unknown instead)
• Zod for runtime validation
• Export shared types from @goodgo/types

VI:

• Bật strict mode
• Không dùng type any (dùng unknown thay thế)
• Zod cho runtime validation
• Export shared types từ @goodgo/types

Ghi Log

Use @goodgo/logger:

import { logger } from '@goodgo/logger';
logger.info('Message', { context });
logger.error('Error', { error, context });

Sử dụng @goodgo/logger:

import { logger } from '@goodgo/logger';
logger.info('Message', { context });
logger.error('Error', { error, context });

Biến Môi Trường

• Use .env.example template
• Never commit .env files
• Validate with Zod at startup
• Document all variables in README

VI:

• Sử dụng template .env.example
• Không bao giờ commit file .env
• Validate với Zod khi khởi động
• Tài liệu hóa tất cả biến trong README

Ví Dụ Từ Dự Án

Template Service

See services/_template/ for a complete service template with:

• Standard structure
• Middleware setup
• Error handling
• Health checks
• Swagger documentation

Xem services/_template/ để có template service hoàn chỉnh với:

• Cấu trúc chuẩn
• Thiết lập middleware
• Xử lý lỗi
• Health checks
• Tài liệu Swagger

Cấu Hình Traefik

Services are registered in deployments/local/docker-compose.yml:

services:
  my-service:
    build:
      context: ../..
      dockerfile: services/my-service/Dockerfile
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.my-service.rule=PathPrefix(`/api/v1/my-service`)"
      - "traefik.http.services.my-service.loadbalancer.server.port=5002"
      - "traefik.http.services.my-service.loadbalancer.healthcheck.path=/health/live"

Services được đăng ký trong deployments/local/docker-compose.yml:

services:
  my-service:
    build:
      context: ../..
      dockerfile: services/my-service/Dockerfile
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.my-service.rule=PathPrefix(`/api/v1/my-service`)"
      - "traefik.http.services.my-service.loadbalancer.server.port=5002"
      - "traefik.http.services.my-service.loadbalancer.healthcheck.path=/health/live"

Ví Dụ Service Thực Tế

• services/iam-service/ - Identity and Access Management service (RBAC, OIDC, MFA, Identity, Access, Governance)
• packages/logger/ - Shared logging package
• packages/types/ - Shared TypeScript types

VI:

• services/iam-service/ - Service quản lý danh tính và quyền truy cập (RBAC, OIDC, MFA, Identity, Access, Governance)
• packages/logger/ - Package logging dùng chung
• packages/types/ - TypeScript types dùng chung

Tham Khảo Nhanh

Tạo Service Mới

# 1. Copy template
cp -r services/_template services/my-service

# 2. Update package.json name
# Change to: "@goodgo/my-service"

# 3. Add to docker-compose.yml
# Add service configuration with Traefik labels

# 4. Configure Prisma schema
cd services/my-service
pnpm prisma migrate dev

# 5. Add health check endpoint
# Already included in template

Làm Việc Với Dependencies

# Add external package
pnpm --filter @goodgo/service-name add package-name

# Add workspace package
pnpm --filter @goodgo/service-name add @goodgo/logger

# Add dev dependency
pnpm --filter @goodgo/service-name add -D @types/pkg

Lệnh Database

# Run migrations
pnpm --filter @goodgo/service-name prisma migrate dev

# Generate Prisma client
pnpm --filter @goodgo/service-name prisma generate

# Seed database
pnpm --filter @goodgo/service-name prisma db seed

Skills Liên Quan

• API Design - RESTful API design standards
• Database Prisma - Prisma ORM patterns
• Security - Security best practices
• Testing Patterns - Testing guidelines
• Documentation - Documentation writing guidelines

Tài Nguyên

• Architecture Docs
• API Specs
• Development Guide
• Deployment Guide
• Contributing Guide

VI:

• Tài Liệu Kiến Trúc
• Spec API
• Hướng Dẫn Phát Triển
• Hướng Dẫn Triển Khai
• Hướng Dẫn Đóng Góp