# Tài Liệu Cursor Skills

Comprehensive documentation for all Cursor AI skills used in the GoodGo Microservices Platform  
> Tài liệu đầy đủ cho tất cả Cursor AI skills được sử dụng trong GoodGo Microservices Platform

## Tổng Quan

Cursor Skills are specialized knowledge modules that guide AI assistants in following project-specific patterns, standards, and best practices. This directory contains detailed documentation for each skill, including when to use them, key concepts, common patterns, and real-world examples from the codebase.

Cursor Skills là các module kiến thức chuyên biệt hướng dẫn AI assistants tuân theo các patterns, tiêu chuẩn và best practices cụ thể của dự án. Thư mục này chứa tài liệu chi tiết cho từng skill, bao gồm khi nào sử dụng, khái niệm chính, các pattern thường dùng, và ví dụ thực tế từ codebase.

Mỗi tài liệu skill bao gồm **Mermaid diagrams** để minh họa trực quan các workflows, kiến trúc, patterns, và mối quan hệ giúp dễ hiểu các khái niệm phức tạp hơn.

## Các Skills Có Sẵn

GoodGo platform bao gồm **26 Cursor Skills** được tổ chức theo danh mục:

### API & Data Layer

#### [API Design](./api-design.md)
RESTful API design standards for GoodGo microservices. Use when creating new API endpoints, designing DTOs, implementing controllers, writing OpenAPI documentation, or standardizing API responses.

Tiêu chuẩn thiết kế RESTful API cho GoodGo microservices. Sử dụng khi tạo API endpoints mới, thiết kế DTOs, implement controllers, viết OpenAPI documentation, hoặc chuẩn hóa API responses.

#### [Database & Prisma](./database-prisma.md)
Prisma ORM and database patterns for GoodGo microservices. Use when working with databases, creating Prisma schemas, writing migrations, implementing repositories, or optimizing queries.

Prisma ORM và database patterns cho GoodGo microservices. Sử dụng khi làm việc với databases, tạo Prisma schemas, viết migrations, implement repositories, hoặc optimize queries.

#### [Error Handling Patterns](./error-handling-patterns.md)
Error handling patterns and conventions for GoodGo microservices. Use when implementing error handling, creating custom error classes, handling exceptions, standardizing error responses, or debugging error scenarios.

Các patterns và conventions về error handling cho GoodGo microservices. Sử dụng khi implement error handling, tạo custom error classes, xử lý exceptions, chuẩn hóa error responses, hoặc debug error scenarios.

#### [Repository Pattern](./repository-pattern.md)
Repository pattern implementation and best practices for GoodGo microservices. Use when implementing data access layers, extending BaseRepository, writing database queries, handling transactions, or optimizing database operations.

Implementation và best practices về repository pattern cho GoodGo microservices. Sử dụng khi implement data access layers, mở rộng BaseRepository, viết database queries, xử lý transactions, hoặc optimize database operations.

#### [Caching Patterns](./caching-patterns.md)
Caching strategies and patterns for GoodGo microservices including multi-layer cache, Redis caching, cache key naming, TTL strategies, cache invalidation, and cache-aside patterns.

Các strategies và patterns về caching cho GoodGo microservices bao gồm multi-layer cache, Redis caching, cache key naming, TTL strategies, cache invalidation, và cache-aside patterns.

### Code Quality & Testing

#### [Testing Patterns](./testing-patterns.md)
Testing best practices for GoodGo microservices. Use when writing unit tests, integration tests, E2E tests, setting up Jest, mocking dependencies, or debugging test failures.

Best practices về testing cho GoodGo microservices. Sử dụng khi viết unit tests, integration tests, E2E tests, setup Jest, mocking dependencies, hoặc debug test failures.

#### [Code Comments](./comment-code.md)
Add bilingual code comments in Vietnamese and English for better documentation. Use when adding comments to code, documenting functions/classes, or when user requests Vietnamese/English documentation.

Thêm code comments song ngữ bằng tiếng Việt và tiếng Anh để tài liệu tốt hơn. Sử dụng khi thêm comments vào code, document functions/classes, hoặc khi user yêu cầu tài liệu tiếng Việt/Anh.

#### [Middleware Patterns](./middleware-patterns.md)
Express middleware patterns and best practices for GoodGo microservices. Use when creating custom middleware, organizing middleware chains, handling request/response transformation, or implementing cross-cutting concerns.

Các patterns và best practices về Express middleware cho GoodGo microservices. Sử dụng khi tạo custom middleware, tổ chức middleware chains, xử lý request/response transformation, hoặc implement cross-cutting concerns.

#### [Service Layer Patterns](./service-layer-patterns.md)
Service layer organization and patterns for GoodGo microservices. Use when implementing business logic, organizing service classes, using dependency injection, composing services, or separating concerns between controllers and repositories.

Tổ chức và các patterns của service layer cho GoodGo microservices. Sử dụng khi implement business logic, tổ chức service classes, sử dụng dependency injection, kết hợp services, hoặc tách biệt concerns giữa controllers và repositories.

### Infrastructure & Operations

#### [Kubernetes Deployment](./deployment-kubernetes.md)
Kubernetes deployment patterns for GoodGo microservices. Use when deploying to staging/production, creating K8s manifests, configuring HPA, setting up ingress, or troubleshooting K8s deployments.

Kubernetes deployment patterns cho GoodGo microservices. Sử dụng khi deploy lên staging/production, tạo K8s manifests, config HPA, setup ingress, hoặc troubleshoot K8s deployments.

#### [Event-Driven Architecture](./event-driven-architecture.md)
Event-driven architecture patterns with Apache Kafka for GoodGo microservices. Use when implementing async communication, event publishing/consuming, event sourcing, CQRS, or integrating event streams with HTTP endpoints.

Các patterns kiến trúc hướng sự kiện với Apache Kafka cho GoodGo microservices. Sử dụng khi implement giao tiếp bất đồng bộ, publish/consume events, event sourcing, CQRS, hoặc tích hợp event streams với HTTP endpoints.

#### [Inter-Service Communication](./inter-service-communication.md)
Inter-service communication patterns for GoodGo microservices including gRPC, GraphQL, service-to-service authentication, protocol selection, and client patterns. Use when implementing service-to-service calls, choosing communication protocols, or building service clients.

Các patterns giao tiếp giữa services cho GoodGo microservices bao gồm gRPC, GraphQL, service-to-service authentication, lựa chọn protocol, và client patterns. Sử dụng khi implement service-to-service calls, chọn communication protocols, hoặc xây dựng service clients.

#### [Data Consistency Patterns](./data-consistency-patterns.md)
Data consistency patterns for distributed microservices including Saga patterns, distributed transactions, eventual consistency, compensation, and idempotency. Use when handling distributed transactions, implementing eventual consistency, or managing data synchronization across services.

Các patterns nhất quán dữ liệu cho distributed microservices bao gồm Saga patterns, distributed transactions, eventual consistency, compensation, và idempotency. Sử dụng khi xử lý distributed transactions, implement eventual consistency, hoặc quản lý đồng bộ dữ liệu giữa các services.

#### [API Gateway Advanced](./api-gateway-advanced.md)
Advanced API Gateway patterns for GoodGo microservices including API composition, request/response transformation, service mesh integration, advanced routing, and gateway-level resilience. Use when implementing API aggregation, service composition, or advanced gateway features.

Các patterns API Gateway nâng cao cho GoodGo microservices bao gồm API composition, request/response transformation, tích hợp service mesh, routing nâng cao, và resilience ở gateway level. Sử dụng khi implement API aggregation, service composition, hoặc các tính năng gateway nâng cao.

#### [Configuration Management](./configuration-management.md)
Configuration management patterns for GoodGo microservices including feature flags, dynamic configuration reloading, environment-specific configurations, and secrets management. Use when implementing feature toggles, managing configuration, or handling environment variables.

Các patterns quản lý cấu hình cho GoodGo microservices bao gồm feature flags, dynamic configuration reloading, environment-specific configurations, và secrets management. Sử dụng khi implement feature toggles, quản lý configuration, hoặc xử lý environment variables.

#### [Performance Optimization](./performance-optimization.md)
Performance optimization patterns for GoodGo microservices including database query optimization, memory leak detection, profiling, connection pooling, and caching strategies. Use when optimizing performance, profiling applications, or detecting performance bottlenecks.

Các patterns tối ưu hiệu suất cho GoodGo microservices bao gồm tối ưu database queries, phát hiện memory leaks, profiling, connection pooling, và caching strategies. Sử dụng khi tối ưu hiệu suất, profiling ứng dụng, hoặc phát hiện performance bottlenecks.

#### [Observability & Monitoring](./observability-monitoring.md)
Observability and monitoring patterns for GoodGo microservices. Use when adding metrics, implementing logging, setting up tracing, creating health checks, or debugging production issues.

Observability và monitoring patterns cho GoodGo microservices. Sử dụng khi thêm metrics, implement logging, setup tracing, tạo health checks, hoặc debug production issues.

#### [Resilience Patterns](./resilience-patterns.md)
Resilience patterns for GoodGo microservices including circuit breaker, retry strategies, timeout handling, and graceful degradation for improved fault tolerance and system reliability.

Các resilience patterns cho GoodGo microservices bao gồm circuit breaker, retry strategies, timeout handling, và graceful degradation để cải thiện fault tolerance và độ tin cậy hệ thống.

#### [Microservices Development Process](./microservices-development-process.md)
Standard development process for creating and maintaining microservices in GoodGo platform. Use when creating new services, migrating services, refactoring services, or planning service implementations.

Quy trình phát triển chuẩn để tạo và duy trì microservices trong nền tảng GoodGo. Sử dụng khi tạo services mới, migrate services, refactor services, hoặc lập kế hoạch implement services.

#### [CI/CD Advanced Patterns](./cicd-advanced-patterns.md)
Advanced CI/CD patterns for GoodGo microservices including blue-green deployments, canary releases, automated rollback, deployment verification, and progressive delivery. Use when implementing advanced deployment strategies, automated rollbacks, or progressive delivery pipelines.

Các patterns CI/CD nâng cao cho GoodGo microservices bao gồm blue-green deployments, canary releases, automated rollback, deployment verification, và progressive delivery. Sử dụng khi implement các chiến lược deployment nâng cao, automated rollbacks, hoặc progressive delivery pipelines.

#### [Infrastructure as Code](./infrastructure-as-code.md)
Infrastructure as Code patterns for GoodGo platform including Terraform modules, Kubernetes operators, infrastructure testing, GitOps workflows, and multi-environment management. Use when managing infrastructure, implementing GitOps, or creating reusable infrastructure modules.

Các patterns Infrastructure as Code cho nền tảng GoodGo bao gồm Terraform modules, Kubernetes operators, infrastructure testing, GitOps workflows, và multi-environment management. Sử dụng khi quản lý infrastructure, implement GitOps, hoặc tạo các infrastructure modules tái sử dụng.

#### [API Versioning Strategy](./api-versioning-strategy.md)
API versioning strategies for GoodGo microservices including semantic versioning, backward compatibility patterns, API deprecation, version negotiation, and breaking changes handling. Use when versioning APIs, handling breaking changes, or implementing API deprecation strategies.

Các chiến lược versioning API cho GoodGo microservices bao gồm semantic versioning, backward compatibility patterns, API deprecation, version negotiation, và xử lý breaking changes. Sử dụng khi versioning APIs, xử lý breaking changes, hoặc implement API deprecation strategies.

#### [Service Discovery & Registry](./service-discovery-registry.md)
Service discovery and registry patterns for GoodGo microservices including service registry, health check orchestration, load balancing strategies, and service mesh integration. Use when implementing service discovery, managing service health, or integrating with service mesh.

Các patterns service discovery và registry cho GoodGo microservices bao gồm service registry, health check orchestration, load balancing strategies, và tích hợp service mesh. Sử dụng khi implement service discovery, quản lý service health, hoặc tích hợp với service mesh.

### Standards & Security

#### [Project Rules](./project-rules.md)
GoodGo Microservices Platform coding standards and architecture patterns. Use when working with services, apps, packages, or infrastructure.

Tiêu chuẩn coding và architecture patterns của GoodGo Microservices Platform. Sử dụng khi làm việc với services, apps, packages, hoặc infrastructure.

#### [Security](./security.md)
Security best practices and patterns for GoodGo microservices platform. Use when implementing authentication, authorization, data protection, input validation, rate limiting, secrets management, or security testing across all services.

Security best practices và patterns cho GoodGo microservices platform. Sử dụng khi implement authentication, authorization, data protection, input validation, rate limiting, secrets management, hoặc security testing trên tất cả services.

#### [Documentation](./documentation.md)
Guidelines for writing technical documentation in the GoodGo project. Use when creating or updating README files, guides, architecture docs, or API documentation. Ensures bilingual (EN/VI) consistency and proper structure.

Hướng dẫn viết technical documentation trong dự án GoodGo. Sử dụng khi tạo hoặc cập nhật README files, guides, architecture docs, hoặc API documentation. Đảm bảo tính nhất quán song ngữ (EN/VI) và cấu trúc phù hợp.

## Tham Khảo Nhanh

### Theo Use Case

| Tác Vụ | Skills Đề Xuất |
|--------|----------------|
| Tạo API endpoint mới | API Design, Security, Testing Patterns |
| Setup service mới | Project Rules, Database & Prisma, Observability |
| Viết tests | Testing Patterns, Comment Code |
| Deploy lên production | Kubernetes Deployment, Observability, Security |
| Debug production issues | Observability & Monitoring, Security |
| Viết documentation | Documentation, Comment Code |
| Implement authentication | Security, API Design, Database & Prisma |
| Optimize database queries | Database & Prisma, Observability |
| Implement event-driven communication | Event-Driven Architecture, Resilience Patterns |
| Implement service-to-service calls | Inter-Service Communication, Security, Resilience Patterns |
| Handle distributed transactions | Data Consistency Patterns, Event-Driven Architecture |
| Optimize performance | Performance Optimization, Observability & Monitoring |
| Manage feature flags | Configuration Management |
| Deploy with zero downtime | CI/CD Advanced Patterns, Deployment Kubernetes |

### Phụ Thuộc Giữa Các Skills

```
Project Rules (Foundation)
    ├── API Design
    ├── Database & Prisma
    ├── Security
    ├── Microservices Development Process
    └── Testing Patterns
        └── Comment Code

Data Layer
    ├── Repository Pattern
    │   ├── Database & Prisma
    │   └── Error Handling Patterns
    └── Caching Patterns
        └── Repository Pattern

Application Layer
    ├── Service Layer Patterns
    │   ├── Repository Pattern
    │   ├── Caching Patterns
    │   └── Error Handling Patterns
    └── Middleware Patterns
        └── Error Handling Patterns

Infrastructure
    ├── Event-Driven Architecture
    │   ├── Resilience Patterns
    │   ├── Error Handling Patterns
    │   └── Observability & Monitoring
    ├── Inter-Service Communication
    │   ├── API Design
    │   ├── Security
    │   └── Resilience Patterns
    ├── Data Consistency Patterns
    │   ├── Event-Driven Architecture
    │   ├── Database & Prisma
    │   └── Error Handling Patterns
    ├── API Gateway Advanced
    │   ├── Middleware Patterns
    │   ├── Security
    │   └── API Design
    ├── Configuration Management
    │   └── Observability & Monitoring
    ├── Performance Optimization
    │   ├── Database & Prisma
    │   ├── Caching Patterns
    │   └── Observability & Monitoring
    ├── CI/CD Advanced Patterns
    │   ├── Deployment Kubernetes
    │   └── Testing Patterns
    ├── Infrastructure as Code
    │   └── Deployment Kubernetes
    ├── API Versioning Strategy
    │   ├── API Design
    │   └── Middleware Patterns
    ├── Service Discovery & Registry
    │   ├── Deployment Kubernetes
    │   └── Observability & Monitoring
    └── Resilience Patterns
        ├── Error Handling Patterns
        └── Service Layer Patterns

Documentation (Cross-cutting)
    └── All skills
Observability (Cross-cutting)
    └── All services
Kubernetes Deployment (Infrastructure)
    └── All services
```

## Cách Sử Dụng Skills

1. **Khi bắt đầu task mới**: Xem lại các skills liên quan trong thư mục này
2. **Trong quá trình development**: Tham khảo skill documentation để xem patterns và examples
3. **Khi gặp khó khăn**: Kiểm tra skill docs để xem best practices và solutions thường dùng
4. **Khi code review**: Sử dụng skills như checklist để đảm bảo tuân thủ standards

## Tài Liệu Liên Quan

- [Tổng Quan Kiến Trúc](../architecture/system-design.md) - System design patterns
- [Hướng Dẫn Development](../guides/development.md) - Development workflow
- [Hướng Dẫn Deployment](../guides/deployment.md) - Deployment procedures
- [Tài Liệu API](../api/openapi/) - OpenAPI specifications

## Đóng Góp

Khi cập nhật hoặc thêm skills mới:

1. Cập nhật skill source file trong `.cursor/skills/{skill-name}/SKILL.md`
2. Cập nhật documentation tương ứng trong `docs/en/skills/{skill-name}.md`
3. Cập nhật bản dịch tiếng Việt trong `docs/vi/skills/{skill-name}.md`
4. Cập nhật file index này với mọi thay đổi
5. Đảm bảo tính nhất quán song ngữ

## Tài Nguyên

- [Cursor Skills Documentation](https://cursor.sh/docs) - Tài liệu chính thức của Cursor
- [Cursor AI](https://cursor.sh) - Trang chủ Cursor IDE
- Project Skills: `.cursor/skills/` - Source skill files
