docs: Add comprehensive Agent Skills documentation in English and Vietnamese
- Introduced new documentation for Agent Skills, detailing best practices, code patterns, common pitfalls, and quick references across various categories such as Architecture, Data Access, Security, Error Handling, Testing, Infrastructure, Communication, and Documentation. - The documentation is structured to facilitate easy navigation and understanding, supporting developers in implementing consistent patterns on the GoodGo Platform. - Both English and Vietnamese versions are provided to ensure accessibility for a wider audience.
This commit is contained in:
Ho Ngoc Hai
219
docs/en/skills/api-design.md
Normal file
219
docs/en/skills/api-design.md
Normal file
@@ -0,0 +1,219 @@
|
||||
# RESTful API Design Standards
|
||||
|
||||
> **Skill**: `api-design`
|
||||
> **Compatibility**: .NET 10+, ASP.NET Core, MediatR, Swashbuckle, Asp.Versioning
|
||||
|
||||
## Overview
|
||||
|
||||
This skill provides standards for designing consistent, maintainable RESTful APIs across GoodGo microservices. It covers MediatR integration, response wrappers, OpenAPI documentation, and versioning strategies.
|
||||
|
||||
## When to Use
|
||||
|
||||
Apply this skill when:
|
||||
- Creating new API endpoints
|
||||
- Designing request/response DTOs
|
||||
- Implementing controllers with MediatR
|
||||
- Writing OpenAPI/Swagger documentation
|
||||
- Standardizing error responses
|
||||
- Implementing pagination and filtering
|
||||
|
||||
## Key Concepts
|
||||
|
||||
### Clean Architecture Layers
|
||||
|
||||
```
|
||||
src/
|
||||
├── ServiceName.API/ # Controllers, DTOs, Middleware
|
||||
│ ├── Controllers/ # API Controllers
|
||||
│ └── Application/ # Commands, Queries, Handlers
|
||||
├── ServiceName.Domain/ # Entities, Aggregates, Interfaces
|
||||
└── ServiceName.Infrastructure/ # Repositories, External Services
|
||||
```
|
||||
|
||||
### Standard API Response
|
||||
|
||||
All endpoints use a consistent response wrapper:
|
||||
|
||||
```csharp
|
||||
public class ApiResponse<T>
|
||||
{
|
||||
public bool Success { get; set; }
|
||||
public T? Data { get; set; }
|
||||
public string? Error { get; set; }
|
||||
public PaginationInfo? Pagination { get; set; }
|
||||
}
|
||||
```
|
||||
|
||||
**Success response:**
|
||||
```json
|
||||
{ "success": true, "data": {...}, "pagination": {...} }
|
||||
```
|
||||
|
||||
**Error response:**
|
||||
```json
|
||||
{ "success": false, "error": "Error message" }
|
||||
```
|
||||
|
||||
### URL Structure
|
||||
|
||||
```
|
||||
/api/v{version}/{resource}/{id?}/{sub-resource?}
|
||||
|
||||
GET /api/v1/files # List files
|
||||
POST /api/v1/files # Create file
|
||||
GET /api/v1/files/{id} # Get file by ID
|
||||
PUT /api/v1/files/{id} # Update file
|
||||
DELETE /api/v1/files/{id} # Delete file
|
||||
GET /api/v1/files/{id}/versions # Get file versions
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. Create Controller with MediatR
|
||||
|
||||
```csharp
|
||||
[ApiController]
|
||||
[ApiVersion("1.0")]
|
||||
[Route("api/v{version:apiVersion}/files")]
|
||||
[SwaggerTag("File Management - Upload, download, and manage files")]
|
||||
public class FilesController : ControllerBase
|
||||
{
|
||||
private readonly IMediator _mediator;
|
||||
|
||||
public FilesController(IMediator mediator) => _mediator = mediator;
|
||||
|
||||
[HttpGet("{fileId:guid}")]
|
||||
[Authorize]
|
||||
[SwaggerOperation(Summary = "Get file by ID")]
|
||||
[SwaggerResponse(200, "File retrieved successfully")]
|
||||
[SwaggerResponse(404, "File not found")]
|
||||
public async Task<ActionResult<ApiResponse<FileDto>>> GetFile(
|
||||
Guid fileId,
|
||||
CancellationToken ct = default)
|
||||
{
|
||||
var result = await _mediator.Send(new GetFileQuery(fileId), ct);
|
||||
|
||||
return result == null
|
||||
? NotFound(new ApiResponse<FileDto> { Success = false, Error = "File not found" })
|
||||
: Ok(new ApiResponse<FileDto> { Success = true, Data = result });
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Use Record DTOs
|
||||
|
||||
```csharp
|
||||
public record FileDto(
|
||||
Guid Id,
|
||||
string UserId,
|
||||
string FileName,
|
||||
string ContentType,
|
||||
long FileSizeBytes,
|
||||
string AccessLevel,
|
||||
DateTime UploadedAt);
|
||||
```
|
||||
|
||||
### 3. Implement Pagination
|
||||
|
||||
```csharp
|
||||
[HttpGet]
|
||||
public async Task<ActionResult<ApiResponse<UserFilesResult>>> GetFiles(
|
||||
[FromQuery] int skip = 0,
|
||||
[FromQuery] int take = 20,
|
||||
CancellationToken ct = default)
|
||||
{
|
||||
var result = await _mediator.Send(new GetUserFilesQuery(skip, take), ct);
|
||||
|
||||
return Ok(new ApiResponse<UserFilesResult>
|
||||
{
|
||||
Success = true,
|
||||
Data = result,
|
||||
Pagination = new PaginationInfo(
|
||||
Page: skip / take + 1,
|
||||
Limit: take,
|
||||
Total: result.TotalCount,
|
||||
TotalPages: (int)Math.Ceiling(result.TotalCount / (double)take))
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
## HTTP Methods & Status Codes
|
||||
|
||||
| Method | Action | Success | Error Codes |
|
||||
|--------|--------|---------|-------------|
|
||||
| **GET** | Retrieve | 200 | 404 |
|
||||
| **POST** | Create | 200/201 | 400, 409 |
|
||||
| **PUT** | Full update | 200 | 400, 404 |
|
||||
| **PATCH** | Partial update | 200 | 400, 404 |
|
||||
| **DELETE** | Remove | 200/204 | 404 |
|
||||
|
||||
## Common Error Codes
|
||||
|
||||
| Code | Meaning | When to Use |
|
||||
|------|---------|-------------|
|
||||
| 400 | Bad Request | Validation errors |
|
||||
| 401 | Unauthorized | Missing/invalid token |
|
||||
| 403 | Forbidden | No permission |
|
||||
| 404 | Not Found | Resource doesn't exist |
|
||||
| 409 | Conflict | Duplicate resource |
|
||||
| 422 | Unprocessable | Business rule violation |
|
||||
| 429 | Too Many Requests | Rate limited |
|
||||
|
||||
## Common Mistakes to Avoid
|
||||
|
||||
### ❌ Inconsistent Response Format
|
||||
```csharp
|
||||
// BAD: Returning raw data
|
||||
return Ok(result);
|
||||
```
|
||||
|
||||
### ✅ Use Response Wrapper
|
||||
```csharp
|
||||
// GOOD: Using ApiResponse wrapper
|
||||
return Ok(new ApiResponse<FileDto> { Success = true, Data = result });
|
||||
```
|
||||
|
||||
### ❌ Missing API Versioning
|
||||
```csharp
|
||||
// BAD: No versioning
|
||||
[Route("api/files")]
|
||||
```
|
||||
|
||||
### ✅ Include Version
|
||||
```csharp
|
||||
// GOOD: With API versioning
|
||||
[ApiVersion("1.0")]
|
||||
[Route("api/v{version:apiVersion}/files")]
|
||||
```
|
||||
|
||||
### ❌ Single Language Comments
|
||||
```csharp
|
||||
// BAD: English only
|
||||
/// <summary>Get file by ID.</summary>
|
||||
```
|
||||
|
||||
### ✅ Bilingual Documentation
|
||||
```csharp
|
||||
// GOOD: EN/VI bilingual
|
||||
/// <summary>
|
||||
/// EN: Get file by ID.
|
||||
/// VI: Lấy thông tin file theo ID.
|
||||
/// </summary>
|
||||
```
|
||||
|
||||
## Related Skills
|
||||
|
||||
- [CQRS & MediatR](./cqrs-mediatr.md) - Command/Query patterns
|
||||
- [Error Handling](./error-handling-patterns.md) - Exception handling
|
||||
- [Testing Patterns](./testing-patterns.md) - API testing
|
||||
- [Security](./security.md) - Authentication & authorization
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- **Full Skill Reference**: [`.agent/skills/api-design/SKILL.md`](../../.agent/skills/api-design/SKILL.md)
|
||||
- **Code Examples**: [`.agent/skills/api-design/references/REFERENCE.md`](../../.agent/skills/api-design/references/REFERENCE.md)
|
||||
- **Project Rules**: [Project Standards](./project-rules.md)
|
||||
|
||||
---
|
||||
|
||||
**Vietnamese Version**: [Tiêu Chuẩn Thiết Kế RESTful API](../../vi/skills/api-design.md)
|
||||
35
docs/en/skills/comment-code.md
Normal file
35
docs/en/skills/comment-code.md
Normal file
@@ -0,0 +1,35 @@
|
||||
# Bilingual code comments in Vietnamese and English
|
||||
|
||||
> **Skill**: `comment-code`
|
||||
> **Compatibility**:
|
||||
|
||||
## Overview
|
||||
|
||||
Bilingual code comments in Vietnamese and English. Use for documenting functions, classes, or adding EN/VI documentation.
|
||||
|
||||
## When to Use
|
||||
|
||||
Use this skill when:
|
||||
- Adding comments to new code / Thêm chú thích cho code mới
|
||||
- Documenting existing code / Viết tài liệu cho code hiện có
|
||||
- Creating JSDoc/TSDoc documentation / Tạo JSDoc/TSDoc
|
||||
- Writing function/class descriptions / Viết mô tả hàm/lớp
|
||||
- Explaining complex logic / Giải thích logic phức tạp
|
||||
- Adding inline comments / Thêm chú thích inline
|
||||
|
||||
## Quick Reference
|
||||
|
||||
For detailed patterns, code examples, and best practices, refer to the full skill documentation.
|
||||
|
||||
## Related Skills
|
||||
|
||||
See [Skills Index](./index.md) for related skills.
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- **Full Skill Documentation**: [`...agent/skills/comment-code/SKILL.md`](../../.agent/skills/comment-code/SKILL.md)
|
||||
- **Code Examples**: [`...agent/skills/comment-code/references/REFERENCE.md`](../../.agent/skills/comment-code/references/REFERENCE.md)
|
||||
|
||||
---
|
||||
|
||||
**Vietnamese Version**: [Tài liệu tiếng Việt](../../vi/skills/comment-code.md)
|
||||
254
docs/en/skills/cqrs-mediatr.md
Normal file
254
docs/en/skills/cqrs-mediatr.md
Normal file
@@ -0,0 +1,254 @@
|
||||
# CQRS & MediatR Patterns
|
||||
|
||||
> **Skill**: `cqrs-mediatr`
|
||||
> **Compatibility**: .NET 10+, MediatR 12+, FluentValidation
|
||||
|
||||
## Overview
|
||||
|
||||
CQRS (Command Query Responsibility Segregation) separates read and write operations for better scalability and maintainability. MediatR provides the infrastructure for implementing CQRS patterns with pipeline behaviors.
|
||||
|
||||
## When to Use
|
||||
|
||||
- Separating read/write operations
|
||||
- Creating Commands and Queries
|
||||
- Implementing MediatR handlers
|
||||
- Adding cross-cutting concerns via Pipeline Behaviors
|
||||
- Ensuring idempotency
|
||||
|
||||
## CQRS Overview
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────┐
|
||||
│ API Controller │
|
||||
└────────┬─────────────────┬───────────┘
|
||||
│ │
|
||||
┌─────▼─────┐ ┌─────▼─────┐
|
||||
│ Commands │ │ Queries │
|
||||
│ (Write) │ │ (Read) │
|
||||
└─────┬─────┘ └─────┬─────┘
|
||||
│ │
|
||||
┌─────▼─────┐ ┌─────▼─────┐
|
||||
│ Handler │ │ Handler │
|
||||
└─────┬─────┘ └─────┬─────┘
|
||||
│ │
|
||||
┌─────▼─────┐ ┌─────▼─────┐
|
||||
│ EF Core │ │ Dapper │
|
||||
└───────────┘ └───────────┘
|
||||
```
|
||||
|
||||
| Aspect | Command | Query |
|
||||
|--------|---------|-------|
|
||||
| **Purpose** | Modify state | Read data |
|
||||
| **Returns** | Result/void | Data/DTO |
|
||||
| **ORM** | EF Core | Dapper/Raw SQL |
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. Define Command
|
||||
|
||||
```csharp
|
||||
public record CreateOrderCommand(
|
||||
string UserId,
|
||||
Address ShippingAddress,
|
||||
List<OrderItemDto> Items) : IRequest<OrderResult>;
|
||||
|
||||
public record OrderResult(Guid OrderId);
|
||||
```
|
||||
|
||||
### 2. Create Handler
|
||||
|
||||
```csharp
|
||||
public class CreateOrderCommandHandler
|
||||
: IRequestHandler<CreateOrderCommand, OrderResult>
|
||||
{
|
||||
private readonly IOrderRepository _repository;
|
||||
|
||||
public async Task<OrderResult> Handle(
|
||||
CreateOrderCommand request,
|
||||
CancellationToken ct)
|
||||
{
|
||||
var order = new Order(request.UserId, request.ShippingAddress);
|
||||
|
||||
foreach (var item in request.Items)
|
||||
order.AddItem(item.ProductId, item.Quantity, item.UnitPrice);
|
||||
|
||||
await _repository.AddAsync(order, ct);
|
||||
await _repository.UnitOfWork.SaveChangesAsync(ct);
|
||||
|
||||
return new OrderResult(order.Id);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Query with Dapper
|
||||
|
||||
```csharp
|
||||
public record GetUserOrdersQuery(
|
||||
string UserId,
|
||||
int Skip = 0,
|
||||
int Take = 20) : IRequest<PagedResult<OrderSummaryDto>>;
|
||||
|
||||
public class GetUserOrdersQueryHandler
|
||||
: IRequestHandler<GetUserOrdersQuery, PagedResult<OrderSummaryDto>>
|
||||
{
|
||||
private readonly IDbConnection _connection;
|
||||
|
||||
public async Task<PagedResult<OrderSummaryDto>> Handle(
|
||||
GetUserOrdersQuery request,
|
||||
CancellationToken ct)
|
||||
{
|
||||
const string sql = @"
|
||||
SELECT Id, Status, TotalAmount, CreatedAt
|
||||
FROM Orders
|
||||
WHERE UserId = @UserId
|
||||
ORDER BY CreatedAt DESC
|
||||
OFFSET @Skip ROWS FETCH NEXT @Take ROWS ONLY";
|
||||
|
||||
var orders = await _connection.QueryAsync<OrderSummaryDto>(
|
||||
sql, new { request.UserId, request.Skip, request.Take });
|
||||
|
||||
var total = await _connection.ExecuteScalarAsync<int>(
|
||||
"SELECT COUNT(*) FROM Orders WHERE UserId = @UserId",
|
||||
new { request.UserId });
|
||||
|
||||
return new PagedResult<OrderSummaryDto>(orders.ToList(), total);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 4. Use in Controller
|
||||
|
||||
```csharp
|
||||
[ApiController]
|
||||
[Route("api/v{version:apiVersion}/orders")]
|
||||
public class OrdersController : ControllerBase
|
||||
{
|
||||
private readonly IMediator _mediator;
|
||||
|
||||
[HttpPost]
|
||||
public async Task<ActionResult<ApiResponse<OrderResult>>> CreateOrder(
|
||||
CreateOrderRequest request,
|
||||
CancellationToken ct)
|
||||
{
|
||||
var command = new CreateOrderCommand(
|
||||
GetUserId(), request.ShippingAddress, request.Items);
|
||||
|
||||
var result = await _mediator.Send(command, ct);
|
||||
|
||||
return CreatedAtAction(nameof(GetOrder),
|
||||
new { orderId = result.OrderId },
|
||||
ApiResponse<OrderResult>.Ok(result));
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Pipeline Behaviors
|
||||
|
||||
### Validation Behavior
|
||||
|
||||
```csharp
|
||||
public class ValidationBehavior<TRequest, TResponse>
|
||||
: IPipelineBehavior<TRequest, TResponse>
|
||||
where TRequest : IRequest<TResponse>
|
||||
{
|
||||
private readonly IEnumerable<IValidator<TRequest>> _validators;
|
||||
|
||||
public async Task<TResponse> Handle(
|
||||
TRequest request,
|
||||
RequestHandlerDelegate<TResponse> next,
|
||||
CancellationToken ct)
|
||||
{
|
||||
if (!_validators.Any())
|
||||
return await next();
|
||||
|
||||
var context = new ValidationContext<TRequest>(request);
|
||||
var failures = (await Task.WhenAll(
|
||||
_validators.Select(v => v.ValidateAsync(context, ct))))
|
||||
.SelectMany(r => r.Errors)
|
||||
.Where(f => f != null)
|
||||
.ToList();
|
||||
|
||||
if (failures.Count != 0)
|
||||
throw new ValidationException(failures);
|
||||
|
||||
return await next();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Logging Behavior
|
||||
|
||||
```csharp
|
||||
public class LoggingBehavior<TRequest, TResponse>
|
||||
: IPipelineBehavior<TRequest, TResponse>
|
||||
{
|
||||
private readonly ILogger _logger;
|
||||
|
||||
public async Task<TResponse> Handle(
|
||||
TRequest request,
|
||||
RequestHandlerDelegate<TResponse> next,
|
||||
CancellationToken ct)
|
||||
{
|
||||
var requestName = typeof(TRequest).Name;
|
||||
_logger.LogInformation("Handling {RequestName}", requestName);
|
||||
|
||||
var stopwatch = Stopwatch.StartNew();
|
||||
var response = await next();
|
||||
stopwatch.Stop();
|
||||
|
||||
_logger.LogInformation(
|
||||
"Handled {RequestName} in {ElapsedMs}ms",
|
||||
requestName, stopwatch.ElapsedMilliseconds);
|
||||
|
||||
return response;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Register Behaviors
|
||||
|
||||
```csharp
|
||||
builder.Services.AddMediatR(cfg =>
|
||||
{
|
||||
cfg.RegisterServicesFromAssembly(typeof(Program).Assembly);
|
||||
cfg.AddBehavior(typeof(IPipelineBehavior<,>), typeof(LoggingBehavior<,>));
|
||||
cfg.AddBehavior(typeof(IPipelineBehavior<,>), typeof(ValidationBehavior<,>));
|
||||
});
|
||||
```
|
||||
|
||||
## Common Mistakes
|
||||
|
||||
### ❌ Using EF Core for Simple Reads
|
||||
|
||||
```csharp
|
||||
// BAD: Heavy EF Core for queries
|
||||
return await _context.Orders
|
||||
.Include(o => o.OrderItems)
|
||||
.Where(o => o.UserId == userId)
|
||||
.ToListAsync();
|
||||
```
|
||||
|
||||
### ✅ Use Dapper for Optimized Reads
|
||||
|
||||
```csharp
|
||||
// GOOD: Lightweight Dapper query
|
||||
return await _connection.QueryAsync<OrderDto>(
|
||||
"SELECT Id, Status, TotalAmount FROM Orders WHERE UserId = @UserId",
|
||||
new { userId });
|
||||
```
|
||||
|
||||
## Related Skills
|
||||
|
||||
- [API Design](./api-design.md) - Controller patterns
|
||||
- [Repository Pattern](./repository-pattern.md) - Data access
|
||||
- [Error Handling](./error-handling-patterns.md) - Validation errors
|
||||
- [Testing Patterns](././testing-patterns.md) - Handler testing
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- **Full Skill**: [`.agent/skills/cqrs-mediatr/SKILL.md`](../../.agent/skills/cqrs-mediatr/SKILL.md)
|
||||
- **Examples**: [`.agent/skills/cqrs-mediatr/references/REFERENCE.md`](../../.agent/skills/cqrs-mediatr/references/REFERENCE.md)
|
||||
|
||||
---
|
||||
|
||||
**Vietnamese Version**: [Mẫu CQRS & MediatR](../../vi/skills/cqrs-mediatr.md)
|
||||
35
docs/en/skills/deployment-kubernetes.md
Normal file
35
docs/en/skills/deployment-kubernetes.md
Normal file
@@ -0,0 +1,35 @@
|
||||
# Kubernetes deployment patterns
|
||||
|
||||
> **Skill**: `deployment-kubernetes`
|
||||
> **Compatibility**: Kubernetes 1.28+, Helm 3+
|
||||
|
||||
## Overview
|
||||
|
||||
Kubernetes deployment patterns. Use for Pods, Services, Ingress, Helm Charts, ConfigMaps, Secrets, và health probes.
|
||||
|
||||
## When to Use
|
||||
|
||||
Use this skill when:
|
||||
- Deploying services to Kubernetes / Triển khai services lên Kubernetes
|
||||
- Creating Helm charts / Tạo Helm charts
|
||||
- Configuring Ingress routing / Cấu hình Ingress routing
|
||||
- Managing secrets and configs / Quản lý secrets và configs
|
||||
- Setting up health probes / Cài đặt health probes
|
||||
- Scaling applications / Scale ứng dụng
|
||||
|
||||
## Quick Reference
|
||||
|
||||
For detailed patterns, code examples, and best practices, refer to the full skill documentation.
|
||||
|
||||
## Related Skills
|
||||
|
||||
See [Skills Index](./index.md) for related skills.
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- **Full Skill Documentation**: [`...agent/skills/deployment-kubernetes/SKILL.md`](../../.agent/skills/deployment-kubernetes/SKILL.md)
|
||||
- **Code Examples**: [`...agent/skills/deployment-kubernetes/references/REFERENCE.md`](../../.agent/skills/deployment-kubernetes/references/REFERENCE.md)
|
||||
|
||||
---
|
||||
|
||||
**Vietnamese Version**: [Tài liệu tiếng Việt](../../vi/skills/deployment-kubernetes.md)
|
||||
35
docs/en/skills/docker-traefik.md
Normal file
35
docs/en/skills/docker-traefik.md
Normal file
@@ -0,0 +1,35 @@
|
||||
# Docker containerization và Traefik reverse proxy
|
||||
|
||||
> **Skill**: `docker-traefik`
|
||||
> **Compatibility**: Docker 24+, Docker Compose v2+, Traefik v3+
|
||||
|
||||
## Overview
|
||||
|
||||
Docker containerization và Traefik reverse proxy. Use for Dockerfile, docker-compose, routing rules, SSL termination, và load balancing.
|
||||
|
||||
## When to Use
|
||||
|
||||
Use this skill when:
|
||||
- Creating Dockerfiles for .NET services / Tạo Dockerfiles cho services .NET
|
||||
- Configuring docker-compose for local dev / Cấu hình docker-compose cho dev local
|
||||
- Setting up Traefik routing / Cài đặt Traefik routing
|
||||
- Configuring SSL/TLS termination / Cấu hình SSL/TLS termination
|
||||
- Implementing load balancing / Triển khai load balancing
|
||||
- Managing service discovery / Quản lý service discovery
|
||||
|
||||
## Quick Reference
|
||||
|
||||
For detailed patterns, code examples, and best practices, refer to the full skill documentation.
|
||||
|
||||
## Related Skills
|
||||
|
||||
See [Skills Index](./index.md) for related skills.
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- **Full Skill Documentation**: [`...agent/skills/docker-traefik/SKILL.md`](../../.agent/skills/docker-traefik/SKILL.md)
|
||||
- **Code Examples**: [`...agent/skills/docker-traefik/references/REFERENCE.md`](../../.agent/skills/docker-traefik/references/REFERENCE.md)
|
||||
|
||||
---
|
||||
|
||||
**Vietnamese Version**: [Tài liệu tiếng Việt](../../vi/skills/docker-traefik.md)
|
||||
35
docs/en/skills/documentation.md
Normal file
35
docs/en/skills/documentation.md
Normal file
@@ -0,0 +1,35 @@
|
||||
# Documentation guidelines for GoodGo project
|
||||
|
||||
> **Skill**: `documentation`
|
||||
> **Compatibility**:
|
||||
|
||||
## Overview
|
||||
|
||||
Documentation guidelines for GoodGo project. Use for README, guides, architecture docs, or API docs. Ensures bilingual EN/VI consistency.
|
||||
|
||||
## When to Use
|
||||
|
||||
Use this skill when:
|
||||
- Creating README files for services/packages / Tạo README cho services/packages
|
||||
- Writing user guides and tutorials / Viết hướng dẫn sử dụng
|
||||
- Documenting system architecture / Viết tài liệu kiến trúc hệ thống
|
||||
- Creating API documentation / Tạo tài liệu API
|
||||
- Writing operational runbooks / Viết runbooks vận hành
|
||||
- Maintaining bilingual documentation / Duy trì tài liệu song ngữ EN/VI
|
||||
|
||||
## Quick Reference
|
||||
|
||||
For detailed patterns, code examples, and best practices, refer to the full skill documentation.
|
||||
|
||||
## Related Skills
|
||||
|
||||
See [Skills Index](./index.md) for related skills.
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- **Full Skill Documentation**: [`...agent/skills/documentation/SKILL.md`](../../.agent/skills/documentation/SKILL.md)
|
||||
- **Code Examples**: [`...agent/skills/documentation/references/REFERENCE.md`](../../.agent/skills/documentation/references/REFERENCE.md)
|
||||
|
||||
---
|
||||
|
||||
**Vietnamese Version**: [Tài liệu tiếng Việt](../../vi/skills/documentation.md)
|
||||
34
docs/en/skills/domain-driven-design.md
Normal file
34
docs/en/skills/domain-driven-design.md
Normal file
@@ -0,0 +1,34 @@
|
||||
# DDD patterns cho complex business logic
|
||||
|
||||
> **Skill**: `domain-driven-design`
|
||||
> **Compatibility**: .NET 8+, EF Core 8+
|
||||
|
||||
## Overview
|
||||
|
||||
DDD patterns cho complex business logic. Use for Aggregates, Value Objects, Entities, Domain Events, và Rich Domain Model.
|
||||
|
||||
## When to Use
|
||||
|
||||
Use this skill when:
|
||||
- Modeling complex business domains / Mô hình hóa domain phức tạp
|
||||
- Designing aggregates and entities / Thiết kế aggregates và entities
|
||||
- Implementing business rules in domain / Triển khai business rules trong domain
|
||||
- Creating value objects / Tạo value objects
|
||||
- Raising domain events / Raise domain events
|
||||
|
||||
## Quick Reference
|
||||
|
||||
For detailed patterns, code examples, and best practices, refer to the full skill documentation.
|
||||
|
||||
## Related Skills
|
||||
|
||||
See [Skills Index](./index.md) for related skills.
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- **Full Skill Documentation**: [`...agent/skills/domain-driven-design/SKILL.md`](../../.agent/skills/domain-driven-design/SKILL.md)
|
||||
- **Code Examples**: [`...agent/skills/domain-driven-design/references/REFERENCE.md`](../../.agent/skills/domain-driven-design/references/REFERENCE.md)
|
||||
|
||||
---
|
||||
|
||||
**Vietnamese Version**: [Tài liệu tiếng Việt](../../vi/skills/domain-driven-design.md)
|
||||
35
docs/en/skills/error-handling-patterns.md
Normal file
35
docs/en/skills/error-handling-patterns.md
Normal file
@@ -0,0 +1,35 @@
|
||||
# Global error handling, domain exceptions, và Result pattern
|
||||
|
||||
> **Skill**: `error-handling-patterns`
|
||||
> **Compatibility**: .NET 10+, Polly, FluentValidation, Microsoft.Extensions.Diagnostics.HealthChecks
|
||||
|
||||
## Overview
|
||||
|
||||
Global error handling, domain exceptions, và Result pattern. Use for exception middleware, validation errors, Polly resiliency, và health checks.
|
||||
|
||||
## When to Use
|
||||
|
||||
Use this skill when:
|
||||
- Implementing global exception handling / Triển khai xử lý exception toàn cục
|
||||
- Creating domain exceptions / Tạo domain exceptions
|
||||
- Setting up retry policies with Polly / Cài đặt retry policies với Polly
|
||||
- Implementing Circuit Breaker pattern / Triển khai Circuit Breaker
|
||||
- Configuring health checks / Cấu hình health checks
|
||||
- Handling validation errors / Xử lý validation errors
|
||||
|
||||
## Quick Reference
|
||||
|
||||
For detailed patterns, code examples, and best practices, refer to the full skill documentation.
|
||||
|
||||
## Related Skills
|
||||
|
||||
See [Skills Index](./index.md) for related skills.
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- **Full Skill Documentation**: [`...agent/skills/error-handling-patterns/SKILL.md`](../../.agent/skills/error-handling-patterns/SKILL.md)
|
||||
- **Code Examples**: [`...agent/skills/error-handling-patterns/references/REFERENCE.md`](../../.agent/skills/error-handling-patterns/references/REFERENCE.md)
|
||||
|
||||
---
|
||||
|
||||
**Vietnamese Version**: [Tài liệu tiếng Việt](../../vi/skills/error-handling-patterns.md)
|
||||
@@ -0,0 +1,129 @@
|
||||
# Agent Skills Documentation
|
||||
|
||||
Welcome to the GoodGo Platform Agent Skills documentation. These skills are specialized guides that help you implement consistent, production-ready patterns across the platform.
|
||||
|
||||
## What Are Agent Skills?
|
||||
|
||||
Agent Skills are structured knowledge modules that provide:
|
||||
- **Best practices** for specific technical domains
|
||||
- **Code patterns** with real examples from the platform
|
||||
- **Common pitfalls** to avoid
|
||||
- **Quick references** for rapid development
|
||||
|
||||
Each skill is designed to be actionable and immediately applicable to your work.
|
||||
|
||||
## Skills by Category
|
||||
|
||||
### 🏗️ Architecture & Design
|
||||
|
||||
Master the architectural patterns that power GoodGo's microservices.
|
||||
|
||||
- **[RESTful API Design](./api-design.md)** - Standards for consistent, maintainable APIs with MediatR integration
|
||||
- **[CQRS & MediatR](./cqrs-mediatr.md)** - Separate read/write operations with pipeline behaviors
|
||||
- **[Domain-Driven Design](./domain-driven-design.md)** - Rich domain models, aggregates, and domain events
|
||||
|
||||
### 💾 Data Access
|
||||
|
||||
Efficient and scalable data access patterns.
|
||||
|
||||
- **[Repository Pattern](./repository-pattern.md)** - Entity Framework Core repositories and Unit of Work
|
||||
- **[Redis Caching](./redis-caching.md)** - Distributed caching strategies with invalidation patterns
|
||||
|
||||
### 🔐 Security & Authentication
|
||||
|
||||
Protect your services and users.
|
||||
|
||||
- **[Security Patterns](./security.md)** - Authentication, authorization, and data protection with Duende IdentityServer
|
||||
|
||||
### ⚡ Error Handling & Resilience
|
||||
|
||||
Build robust, fault-tolerant services.
|
||||
|
||||
- **[Error Handling Patterns](./error-handling-patterns.md)** - Global exception handling, Result pattern, and Polly resilience
|
||||
|
||||
### 🧪 Testing
|
||||
|
||||
Ensure quality through comprehensive testing.
|
||||
|
||||
- **[Testing Patterns](./testing-patterns.md)** - Unit, integration, and functional tests with xUnit and Testcontainers
|
||||
|
||||
### 🚀 Infrastructure & Deployment
|
||||
|
||||
Deploy and monitor production services.
|
||||
|
||||
- **[Docker & Traefik](./docker-traefik.md)** - Containerization and reverse proxy configuration
|
||||
- **[Kubernetes Deployment](./deployment-kubernetes.md)** - Pods, Services, Ingress, and Helm Charts
|
||||
- **[Observability](./observability.md)** - Monitoring with Prometheus, Grafana, and distributed tracing
|
||||
|
||||
### 🔄 Communication
|
||||
|
||||
Enable seamless inter-service communication.
|
||||
|
||||
- **[Inter-Service Communication](./inter-service-communication.md)** - Event Bus (RabbitMQ), HTTP clients with Polly, and gRPC
|
||||
|
||||
### 📝 Documentation & Development
|
||||
|
||||
Maintain quality documentation and code standards.
|
||||
|
||||
- **[Documentation Guidelines](./documentation.md)** - Bilingual documentation standards (EN/VI)
|
||||
- **[Code Commenting](./comment-code.md)** - Bilingual code comments and XML documentation
|
||||
- **[Skill Authoring](./skill-authoring.md)** - How to create and maintain Agent Skills
|
||||
- **[Project Rules](./project-rules.md)** - Platform-wide coding standards and architecture
|
||||
|
||||
## How to Use Skills
|
||||
|
||||
### 1. Find the Right Skill
|
||||
|
||||
Browse by category above or search for specific patterns you need to implement.
|
||||
|
||||
### 2. Understand the Context
|
||||
|
||||
Each skill starts with a "When to Use" section that helps you determine if it's applicable to your current task.
|
||||
|
||||
### 3. Learn the Patterns
|
||||
|
||||
Study the code examples and diagrams. All examples are based on real production code from the GoodGo platform.
|
||||
|
||||
### 4. Avoid Common Mistakes
|
||||
|
||||
Review the "Common Mistakes" section to save time and avoid known pitfalls.
|
||||
|
||||
### 5. Reference Quickly
|
||||
|
||||
Use the "Quick Reference" section for rapid lookups during development.
|
||||
|
||||
## Skill Development
|
||||
|
||||
Skills are living documents that evolve with the platform. If you discover better patterns or want to contribute:
|
||||
|
||||
1. Review the [Skill Authoring](./skill-authoring.md) guide
|
||||
2. Follow the established structure and bilingual format
|
||||
3. Include real examples from the codebase
|
||||
4. Submit for review
|
||||
|
||||
## Quick Links
|
||||
|
||||
### By Technology Stack
|
||||
|
||||
- **.NET / C#**: [API Design](./api-design.md), [CQRS](./cqrs-mediatr.md), [Repository](./repository-pattern.md), [Testing](./testing-patterns.md)
|
||||
- **Infrastructure**: [Docker](./docker-traefik.md), [Kubernetes](./deployment-kubernetes.md), [Observability](./observability.md)
|
||||
- **Security**: [Security Patterns](./security.md), [Error Handling](./error-handling-patterns.md)
|
||||
- **Documentation**: [Docs Guidelines](./documentation.md), [Code Comments](./comment-code.md)
|
||||
|
||||
### By Use Case
|
||||
|
||||
- **Starting a new service**: [Project Rules](./project-rules.md) → [API Design](./api-design.md) → [CQRS](./cqrs-mediatr.md) → [Repository](./repository-pattern.md)
|
||||
- **Adding authentication**: [Security Patterns](./security.md)
|
||||
- **Improving performance**: [Redis Caching](./redis-caching.md)
|
||||
- **Deploying to production**: [Docker](./docker-traefik.md) → [Kubernetes](./deployment-kubernetes.md) → [Observability](./observability.md)
|
||||
- **Writing tests**: [Testing Patterns](./testing-patterns.md)
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [Architecture Documentation](../architecture/system-design.md) - Overall system design
|
||||
- [Development Guides](../guides/getting-started.md) - Getting started with local development
|
||||
- [API Specifications](../api/openapi/) - OpenAPI documentation
|
||||
|
||||
---
|
||||
|
||||
**Note**: All skills follow bilingual documentation standards (English/Vietnamese). Vietnamese versions are available in [`docs/vi/skills/`](../../vi/skills/index.md).
|
||||
|
||||
33
docs/en/skills/inter-service-communication.md
Normal file
33
docs/en/skills/inter-service-communication.md
Normal file
@@ -0,0 +1,33 @@
|
||||
# Giao tiếp liên dịch vụ
|
||||
|
||||
> **Skill**: `inter-service-communication`
|
||||
> **Compatibility**: .NET 8+, MassTransit, RabbitMQ, Polly, gRPC
|
||||
|
||||
## Overview
|
||||
|
||||
Giao tiếp liên dịch vụ. Use for Event Bus (RabbitMQ), Integration Events, HTTP Client với Polly, và gRPC patterns.
|
||||
|
||||
## When to Use
|
||||
|
||||
Use this skill when:
|
||||
- Publishing domain events to other services / Publish domain events đến services khác
|
||||
- Consuming integration events / Consume integration events
|
||||
- Making HTTP calls to other services / Gọi HTTP đến services khác
|
||||
- Implementing resilient communication / Triển khai giao tiếp có khả năng phục hồi
|
||||
|
||||
## Quick Reference
|
||||
|
||||
For detailed patterns, code examples, and best practices, refer to the full skill documentation.
|
||||
|
||||
## Related Skills
|
||||
|
||||
See [Skills Index](./index.md) for related skills.
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- **Full Skill Documentation**: [`...agent/skills/inter-service-communication/SKILL.md`](../../.agent/skills/inter-service-communication/SKILL.md)
|
||||
- **Code Examples**: [`...agent/skills/inter-service-communication/references/REFERENCE.md`](../../.agent/skills/inter-service-communication/references/REFERENCE.md)
|
||||
|
||||
---
|
||||
|
||||
**Vietnamese Version**: [Tài liệu tiếng Việt](../../vi/skills/inter-service-communication.md)
|
||||
34
docs/en/skills/observability.md
Normal file
34
docs/en/skills/observability.md
Normal file
@@ -0,0 +1,34 @@
|
||||
# Monitoring, logging, và tracing patterns
|
||||
|
||||
> **Skill**: `observability`
|
||||
> **Compatibility**: .NET 10+, Serilog, OpenTelemetry, Prometheus, Grafana
|
||||
|
||||
## Overview
|
||||
|
||||
Monitoring, logging, và tracing patterns. Use for Prometheus metrics, Grafana dashboards, Loki logging, và distributed tracing.
|
||||
|
||||
## When to Use
|
||||
|
||||
Use this skill when:
|
||||
- Implementing health checks / Triển khai health checks
|
||||
- Configuring structured logging / Cấu hình structured logging
|
||||
- Setting up Prometheus metrics / Cài đặt Prometheus metrics
|
||||
- Implementing distributed tracing / Triển khai distributed tracing
|
||||
- Creating Grafana dashboards / Tạo Grafana dashboards
|
||||
|
||||
## Quick Reference
|
||||
|
||||
For detailed patterns, code examples, and best practices, refer to the full skill documentation.
|
||||
|
||||
## Related Skills
|
||||
|
||||
See [Skills Index](./index.md) for related skills.
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- **Full Skill Documentation**: [`...agent/skills/observability/SKILL.md`](../../.agent/skills/observability/SKILL.md)
|
||||
- **Code Examples**: [`...agent/skills/observability/references/REFERENCE.md`](../../.agent/skills/observability/references/REFERENCE.md)
|
||||
|
||||
---
|
||||
|
||||
**Vietnamese Version**: [Tài liệu tiếng Việt](../../vi/skills/observability.md)
|
||||
34
docs/en/skills/project-rules.md
Normal file
34
docs/en/skills/project-rules.md
Normal file
@@ -0,0 +1,34 @@
|
||||
# GoodGo Platform coding standards and architecture
|
||||
|
||||
> **Skill**: `project-rules`
|
||||
> **Compatibility**: .NET 10+, ASP.NET Core, MediatR, Entity Framework Core
|
||||
|
||||
## Overview
|
||||
|
||||
GoodGo Platform coding standards and architecture. Use when working with services, apps, packages, or infrastructure.
|
||||
|
||||
## When to Use
|
||||
|
||||
Use this skill when:
|
||||
- Creating new .NET services / Tạo services .NET mới
|
||||
- Working with project structure / Làm việc với cấu trúc dự án
|
||||
- Following naming conventions / Tuân thủ quy tắc đặt tên
|
||||
- Deploying services with Docker/Traefik / Triển khai với Docker/Traefik
|
||||
- Understanding tech stack / Hiểu tech stack của dự án
|
||||
|
||||
## Quick Reference
|
||||
|
||||
For detailed patterns, code examples, and best practices, refer to the full skill documentation.
|
||||
|
||||
## Related Skills
|
||||
|
||||
See [Skills Index](./index.md) for related skills.
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- **Full Skill Documentation**: [`...agent/skills/project-rules/SKILL.md`](../../.agent/skills/project-rules/SKILL.md)
|
||||
- **Code Examples**: [`...agent/skills/project-rules/references/REFERENCE.md`](../../.agent/skills/project-rules/references/REFERENCE.md)
|
||||
|
||||
---
|
||||
|
||||
**Vietnamese Version**: [Tài liệu tiếng Việt](../../vi/skills/project-rules.md)
|
||||
34
docs/en/skills/redis-caching.md
Normal file
34
docs/en/skills/redis-caching.md
Normal file
@@ -0,0 +1,34 @@
|
||||
# Redis caching patterns cho distributed systems
|
||||
|
||||
> **Skill**: `redis-caching`
|
||||
> **Compatibility**: .NET 8+, StackExchange.Redis, Microsoft.Extensions.Caching.StackExchangeRedis
|
||||
|
||||
## Overview
|
||||
|
||||
Redis caching patterns cho distributed systems. Use for cache-aside, session storage, rate limiting, và distributed locks.
|
||||
|
||||
## When to Use
|
||||
|
||||
Use this skill when:
|
||||
- Implementing distributed cache / Triển khai distributed cache
|
||||
- Caching API responses / Caching responses API
|
||||
- Managing user sessions / Quản lý user sessions
|
||||
- Implementing rate limiting / Triển khai rate limiting
|
||||
- Using Redis as primary store (e.g., shopping cart) / Dùng Redis làm store chính
|
||||
|
||||
## Quick Reference
|
||||
|
||||
For detailed patterns, code examples, and best practices, refer to the full skill documentation.
|
||||
|
||||
## Related Skills
|
||||
|
||||
See [Skills Index](./index.md) for related skills.
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- **Full Skill Documentation**: [`...agent/skills/redis-caching/SKILL.md`](../../.agent/skills/redis-caching/SKILL.md)
|
||||
- **Code Examples**: [`...agent/skills/redis-caching/references/REFERENCE.md`](../../.agent/skills/redis-caching/references/REFERENCE.md)
|
||||
|
||||
---
|
||||
|
||||
**Vietnamese Version**: [Tài liệu tiếng Việt](../../vi/skills/redis-caching.md)
|
||||
35
docs/en/skills/repository-pattern.md
Normal file
35
docs/en/skills/repository-pattern.md
Normal file
@@ -0,0 +1,35 @@
|
||||
# Entity Framework Core repository và data access patterns
|
||||
|
||||
> **Skill**: `repository-pattern`
|
||||
> **Compatibility**: .NET 10+, Entity Framework Core 8+, Dapper
|
||||
|
||||
## Overview
|
||||
|
||||
Entity Framework Core repository và data access patterns. Use for DbContext, repositories, migrations, aggregate roots, Unit of Work, và CQRS queries.
|
||||
|
||||
## When to Use
|
||||
|
||||
Use this skill when:
|
||||
- Creating new repositories for aggregates / Tạo repositories mới cho aggregates
|
||||
- Implementing data access with EF Core / Triển khai data access với EF Core
|
||||
- Setting up Unit of Work pattern / Cài đặt Unit of Work pattern
|
||||
- Separating read/write operations (CQRS) / Phân tách read/write (CQRS)
|
||||
- Creating database migrations / Tạo database migrations
|
||||
- Optimizing query performance / Tối ưu hiệu năng query
|
||||
|
||||
## Quick Reference
|
||||
|
||||
For detailed patterns, code examples, and best practices, refer to the full skill documentation.
|
||||
|
||||
## Related Skills
|
||||
|
||||
See [Skills Index](./index.md) for related skills.
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- **Full Skill Documentation**: [`...agent/skills/repository-pattern/SKILL.md`](../../.agent/skills/repository-pattern/SKILL.md)
|
||||
- **Code Examples**: [`...agent/skills/repository-pattern/references/REFERENCE.md`](../../.agent/skills/repository-pattern/references/REFERENCE.md)
|
||||
|
||||
---
|
||||
|
||||
**Vietnamese Version**: [Tài liệu tiếng Việt](../../vi/skills/repository-pattern.md)
|
||||
36
docs/en/skills/security.md
Normal file
36
docs/en/skills/security.md
Normal file
@@ -0,0 +1,36 @@
|
||||
# Security patterns for GoodGo platform
|
||||
|
||||
> **Skill**: `security`
|
||||
> **Compatibility**: .NET 10+, ASP.NET Core Identity, Duende IdentityServer
|
||||
|
||||
## Overview
|
||||
|
||||
Security patterns for GoodGo platform. Use for authentication, authorization, data protection, input validation, rate limiting, or secrets management.
|
||||
|
||||
## When to Use
|
||||
|
||||
Use this skill when:
|
||||
- Implementing authentication (JWT, OAuth2, OIDC) / Triển khai authentication
|
||||
- Setting up authorization (RBAC, policies) / Cài đặt authorization
|
||||
- Protecting sensitive data / Bảo vệ dữ liệu nhạy cảm
|
||||
- Validating user inputs / Xác thực input từ user
|
||||
- Implementing 2FA / Triển khai xác thực 2 yếu tố
|
||||
- Managing secrets / Quản lý secrets
|
||||
- Auditing security events / Ghi log sự kiện bảo mật
|
||||
|
||||
## Quick Reference
|
||||
|
||||
For detailed patterns, code examples, and best practices, refer to the full skill documentation.
|
||||
|
||||
## Related Skills
|
||||
|
||||
See [Skills Index](./index.md) for related skills.
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- **Full Skill Documentation**: [`...agent/skills/security/SKILL.md`](../../.agent/skills/security/SKILL.md)
|
||||
- **Code Examples**: [`...agent/skills/security/references/REFERENCE.md`](../../.agent/skills/security/references/REFERENCE.md)
|
||||
|
||||
---
|
||||
|
||||
**Vietnamese Version**: [Tài liệu tiếng Việt](../../vi/skills/security.md)
|
||||
31
docs/en/skills/skill-authoring.md
Normal file
31
docs/en/skills/skill-authoring.md
Normal file
@@ -0,0 +1,31 @@
|
||||
# Phương pháp viết Agent Skills chuyên nghiệp
|
||||
|
||||
> **Skill**: `skill-authoring`
|
||||
> **Compatibility**: Antigravity, Claude Code, hoặc các agent khác hỗ trợ Agent Skills spec
|
||||
|
||||
## Overview
|
||||
|
||||
Phương pháp viết Agent Skills chuyên nghiệp. Sử dụng khi tạo mới, cập nhật, hoặc review Agent Skills theo chuẩn AgentSkills.io và best practices của dự án GoodGo.
|
||||
|
||||
## When to Use
|
||||
|
||||
Use this skill when:
|
||||
- Condition 1
|
||||
- Condition 2
|
||||
|
||||
## Quick Reference
|
||||
|
||||
For detailed patterns, code examples, and best practices, refer to the full skill documentation.
|
||||
|
||||
## Related Skills
|
||||
|
||||
See [Skills Index](./index.md) for related skills.
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- **Full Skill Documentation**: [`...agent/skills/skill-authoring/SKILL.md`](../../.agent/skills/skill-authoring/SKILL.md)
|
||||
- **Code Examples**: [`...agent/skills/skill-authoring/references/REFERENCE.md`](../../.agent/skills/skill-authoring/references/REFERENCE.md)
|
||||
|
||||
---
|
||||
|
||||
**Vietnamese Version**: [Tài liệu tiếng Việt](../../vi/skills/skill-authoring.md)
|
||||
34
docs/en/skills/testing-patterns.md
Normal file
34
docs/en/skills/testing-patterns.md
Normal file
@@ -0,0 +1,34 @@
|
||||
# Unit/Integration testing patterns cho
|
||||
|
||||
> **Skill**: `testing-patterns`
|
||||
> **Compatibility**: .NET 10+, xUnit, NSubstitute, Testcontainers, Microsoft.AspNetCore.TestHost
|
||||
|
||||
## Overview
|
||||
|
||||
Unit/Integration testing patterns cho .NET microservices. Use for xUnit, NSubstitute, Testcontainers, và testing MediatR handlers.
|
||||
|
||||
## When to Use
|
||||
|
||||
Use this skill when:
|
||||
- Writing unit tests for handlers / Viết unit tests cho handlers
|
||||
- Testing controllers with mocked dependencies / Test controllers với dependencies giả lập
|
||||
- Creating integration tests with database / Tạo integration tests với database
|
||||
- Setting up functional tests with TestServer / Cài đặt functional tests với TestServer
|
||||
- Mocking services với NSubstitute / Giả lập services với NSubstitute
|
||||
|
||||
## Quick Reference
|
||||
|
||||
For detailed patterns, code examples, and best practices, refer to the full skill documentation.
|
||||
|
||||
## Related Skills
|
||||
|
||||
See [Skills Index](./index.md) for related skills.
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- **Full Skill Documentation**: [`...agent/skills/testing-patterns/SKILL.md`](../../.agent/skills/testing-patterns/SKILL.md)
|
||||
- **Code Examples**: [`...agent/skills/testing-patterns/references/REFERENCE.md`](../../.agent/skills/testing-patterns/references/REFERENCE.md)
|
||||
|
||||
---
|
||||
|
||||
**Vietnamese Version**: [Tài liệu tiếng Việt](../../vi/skills/testing-patterns.md)
|
||||
219
docs/vi/skills/api-design.md
Normal file
219
docs/vi/skills/api-design.md
Normal file
@@ -0,0 +1,219 @@
|
||||
# Tiêu Chuẩn Thiết Kế RESTful API
|
||||
|
||||
> **Skill**: `api-design`
|
||||
> **Compatibility**: .NET 10+, ASP.NET Core, MediatR, Swashbuckle, Asp.Versioning
|
||||
|
||||
## Tổng Quan
|
||||
|
||||
Skill này cung cấp tiêu chuẩn thiết kế RESTful APIs nhất quán, dễ bảo trì cho GoodGo microservices. Bao gồm tích hợp MediatR, response wrappers, OpenAPI documentation, và chiến lược versioning.
|
||||
|
||||
## Khi Nào Sử Dụng
|
||||
|
||||
Áp dụng skill này khi:
|
||||
- Tạo API endpoints mới
|
||||
- Thiết kế request/response DTOs
|
||||
- Triển khai controllers với MediatR
|
||||
- Viết tài liệu OpenAPI/Swagger
|
||||
- Chuẩn hóa error responses
|
||||
- Triển khai pagination và filtering
|
||||
|
||||
## Khái Niệm Cốt Lõi
|
||||
|
||||
### Các Tầng Clean Architecture
|
||||
|
||||
```
|
||||
src/
|
||||
├── ServiceName.API/ # Controllers, DTOs, Middleware
|
||||
│ ├── Controllers/ # API Controllers
|
||||
│ └── Application/ # Commands, Queries, Handlers
|
||||
├── ServiceName.Domain/ # Entities, Aggregates, Interfaces
|
||||
└── ServiceName.Infrastructure/ # Repositories, External Services
|
||||
```
|
||||
|
||||
### Response API Chuẩn
|
||||
|
||||
Tất cả endpoints sử dụng response wrapper nhất quán:
|
||||
|
||||
```csharp
|
||||
public class ApiResponse<T>
|
||||
{
|
||||
public bool Success { get; set; }
|
||||
public T? Data { get; set; }
|
||||
public string? Error { get; set; }
|
||||
public PaginationInfo? Pagination { get; set; }
|
||||
}
|
||||
```
|
||||
|
||||
**Success response:**
|
||||
```json
|
||||
{ "success": true, "data": {...}, "pagination": {...} }
|
||||
```
|
||||
|
||||
**Error response:**
|
||||
```json
|
||||
{ "success": false, "error": "Error message" }
|
||||
```
|
||||
|
||||
### Cấu Trúc URL
|
||||
|
||||
```
|
||||
/api/v{version}/{resource}/{id?}/{sub-resource?}
|
||||
|
||||
GET /api/v1/files # Liệt kê files
|
||||
POST /api/v1/files # Tạo file
|
||||
GET /api/v1/files/{id} # Lấy file theo ID
|
||||
PUT /api/v1/files/{id} # Cập nhật file
|
||||
DELETE /api/v1/files/{id} # Xóa file
|
||||
GET /api/v1/files/{id}/versions # Lấy versions của file
|
||||
```
|
||||
|
||||
## Bắt Đầu Nhanh
|
||||
|
||||
### 1. Tạo Controller với MediatR
|
||||
|
||||
```csharp
|
||||
[ApiController]
|
||||
[ApiVersion("1.0")]
|
||||
[Route("api/v{version:apiVersion}/files")]
|
||||
[SwaggerTag("File Management - Upload, download, and manage files")]
|
||||
public class FilesController : ControllerBase
|
||||
{
|
||||
private readonly IMediator _mediator;
|
||||
|
||||
public FilesController(IMediator mediator) => _mediator = mediator;
|
||||
|
||||
[HttpGet("{fileId:guid}")]
|
||||
[Authorize]
|
||||
[SwaggerOperation(Summary = "Get file by ID")]
|
||||
[SwaggerResponse(200, "File retrieved successfully")]
|
||||
[SwaggerResponse(404, "File not found")]
|
||||
public async Task<ActionResult<ApiResponse<FileDto>>> GetFile(
|
||||
Guid fileId,
|
||||
CancellationToken ct = default)
|
||||
{
|
||||
var result = await _mediator.Send(new GetFileQuery(fileId), ct);
|
||||
|
||||
return result == null
|
||||
? NotFound(new ApiResponse<FileDto> { Success = false, Error = "File not found" })
|
||||
: Ok(new ApiResponse<FileDto> { Success = true, Data = result });
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Sử Dụng Record DTOs
|
||||
|
||||
```csharp
|
||||
public record FileDto(
|
||||
Guid Id,
|
||||
string UserId,
|
||||
string FileName,
|
||||
string ContentType,
|
||||
long FileSizeBytes,
|
||||
string AccessLevel,
|
||||
DateTime UploadedAt);
|
||||
```
|
||||
|
||||
### 3. Triển Khai Pagination
|
||||
|
||||
```csharp
|
||||
[HttpGet]
|
||||
public async Task<ActionResult<ApiResponse<UserFilesResult>>> GetFiles(
|
||||
[FromQuery] int skip = 0,
|
||||
[FromQuery] int take = 20,
|
||||
CancellationToken ct = default)
|
||||
{
|
||||
var result = await _mediator.Send(new GetUserFilesQuery(skip, take), ct);
|
||||
|
||||
return Ok(new ApiResponse<UserFilesResult>
|
||||
{
|
||||
Success = true,
|
||||
Data = result,
|
||||
Pagination = new PaginationInfo(
|
||||
Page: skip / take + 1,
|
||||
Limit: take,
|
||||
Total: result.TotalCount,
|
||||
TotalPages: (int)Math.Ceiling(result.TotalCount / (double)take))
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
## HTTP Methods & Status Codes
|
||||
|
||||
| Method | Hành Động | Success | Error Codes |
|
||||
|--------|-----------|---------|-------------|
|
||||
| **GET** | Lấy dữ liệu | 200 | 404 |
|
||||
| **POST** | Tạo mới | 200/201 | 400, 409 |
|
||||
| **PUT** | Cập nhật toàn bộ | 200 | 400, 404 |
|
||||
| **PATCH** | Cập nhật một phần | 200 | 400, 404 |
|
||||
| **DELETE** | Xóa | 200/204 | 404 |
|
||||
|
||||
## Mã Lỗi Phổ Biến
|
||||
|
||||
| Code | Ý Nghĩa | Khi Nào Dùng |
|
||||
|------|---------|--------------|
|
||||
| 400 | Bad Request | Lỗi validation |
|
||||
| 401 | Unauthorized | Thiếu/sai token |
|
||||
| 403 | Forbidden | Không có quyền |
|
||||
| 404 | Not Found | Resource không tồn tại |
|
||||
| 409 | Conflict | Resource trùng lặp |
|
||||
| 422 | Unprocessable | Vi phạm business rule |
|
||||
| 429 | Too Many Requests | Bị rate limit |
|
||||
|
||||
## Lỗi Thường Gặp Cần Tránh
|
||||
|
||||
### ❌ Response Format Không Nhất Quán
|
||||
```csharp
|
||||
// SAI: Trả về raw data
|
||||
return Ok(result);
|
||||
```
|
||||
|
||||
### ✅ Dùng Response Wrapper
|
||||
```csharp
|
||||
// ĐÚNG: Dùng ApiResponse wrapper
|
||||
return Ok(new ApiResponse<FileDto> { Success = true, Data = result });
|
||||
```
|
||||
|
||||
### ❌ Thiếu API Versioning
|
||||
```csharp
|
||||
// SAI: Không có versioning
|
||||
[Route("api/files")]
|
||||
```
|
||||
|
||||
### ✅ Có Version
|
||||
```csharp
|
||||
// ĐÚNG: Với API versioning
|
||||
[ApiVersion("1.0")]
|
||||
[Route("api/v{version:apiVersion}/files")]
|
||||
```
|
||||
|
||||
### ❌ Comment Một Ngôn Ngữ
|
||||
```csharp
|
||||
// SAI: Chỉ tiếng Anh
|
||||
/// <summary>Get file by ID.</summary>
|
||||
```
|
||||
|
||||
### ✅ Tài Liệu Song Ngữ
|
||||
```csharp
|
||||
// ĐÚNG: Song ngữ EN/VI
|
||||
/// <summary>
|
||||
/// EN: Get file by ID.
|
||||
/// VI: Lấy thông tin file theo ID.
|
||||
/// </summary>
|
||||
```
|
||||
|
||||
## Skills Liên Quan
|
||||
|
||||
- [CQRS & MediatR](./cqrs-mediatr.md) - Mẫu Command/Query
|
||||
- [Xử Lý Lỗi](./error-handling-patterns.md) - Exception handling
|
||||
- [Mẫu Testing](./testing-patterns.md) - API testing
|
||||
- [Bảo Mật](./security.md) - Authentication & authorization
|
||||
|
||||
## Tài Nguyên Bổ Sung
|
||||
|
||||
- **Tài Liệu Skill Đầy Đủ**: [`.agent/skills/api-design/SKILL.md`](../../.agent/skills/api-design/SKILL.md)
|
||||
- **Ví Dụ Code**: [`.agent/skills/api-design/references/REFERENCE.md`](../../.agent/skills/api-design/references/REFERENCE.md)
|
||||
- **Quy Tắc Dự Án**: [Tiêu Chuẩn Dự Án](./project-rules.md)
|
||||
|
||||
---
|
||||
|
||||
**English Version**: [RESTful API Design Standards](../../en/skills/api-design.md)
|
||||
35
docs/vi/skills/comment-code.md
Normal file
35
docs/vi/skills/comment-code.md
Normal file
@@ -0,0 +1,35 @@
|
||||
# Bilingual code comments in Vietnamese and English
|
||||
|
||||
> **Skill**: `comment-code`
|
||||
> **Compatibility**:
|
||||
|
||||
## Tổng Quan
|
||||
|
||||
Bilingual code comments in Vietnamese and English. Use for documenting functions, classes, or adding EN/VI documentation.
|
||||
|
||||
## Khi Nào Sử Dụng
|
||||
|
||||
Use this skill when:
|
||||
- Adding comments to new code / Thêm chú thích cho code mới
|
||||
- Documenting existing code / Viết tài liệu cho code hiện có
|
||||
- Creating JSDoc/TSDoc documentation / Tạo JSDoc/TSDoc
|
||||
- Writing function/class descriptions / Viết mô tả hàm/lớp
|
||||
- Explaining complex logic / Giải thích logic phức tạp
|
||||
- Adding inline comments / Thêm chú thích inline
|
||||
|
||||
## Tham Chiếu Nhanh
|
||||
|
||||
Để biết chi tiết về patterns, code examples, và best practices, xem tài liệu skill đầy đủ.
|
||||
|
||||
## Skills Liên Quan
|
||||
|
||||
Xem [Danh Mục Skills](./index.md) để tìm skills liên quan.
|
||||
|
||||
## Tài Nguyên Bổ Sung
|
||||
|
||||
- **Tài Liệu Skill Đầy Đủ**: [`.agent/skills/comment-code/SKILL.md`](../../.agent/skills/comment-code/SKILL.md)
|
||||
- **Ví Dụ Code**: [`.agent/skills/comment-code/references/REFERENCE.md`](../../.agent/skills/comment-code/references/REFERENCE.md)
|
||||
|
||||
---
|
||||
|
||||
**English Version**: [English Documentation](../../en/skills/comment-code.md)
|
||||
254
docs/vi/skills/cqrs-mediatr.md
Normal file
254
docs/vi/skills/cqrs-mediatr.md
Normal file
@@ -0,0 +1,254 @@
|
||||
# Mẫu CQRS & MediatR
|
||||
|
||||
> **Skill**: `cqrs-mediatr`
|
||||
> **Compatibility**: .NET 10+, MediatR 12+, FluentValidation
|
||||
|
||||
## Tổng Quan
|
||||
|
||||
CQRS (Command Query Responsibility Segregation) tách biệt các operations đọc và ghi để cải thiện khả năng mở rộng và bảo trì. MediatR cung cấp cơ sở hạ tầng để triển khai các mẫu CQRS với pipeline behaviors.
|
||||
|
||||
## Khi Nào Sử Dụng
|
||||
|
||||
- Tách biệt operations đọc/ghi
|
||||
- Tạo Commands và Queries
|
||||
- Triển khai MediatR handlers
|
||||
- Thêm cross-cutting concerns qua Pipeline Behaviors
|
||||
- Đảm bảo tính idempotency
|
||||
|
||||
## Tổng Quan CQRS
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────┐
|
||||
│ API Controller │
|
||||
└────────┬─────────────────┬───────────┘
|
||||
│ │
|
||||
┌─────▼─────┐ ┌─────▼─────┐
|
||||
│ Commands │ │ Queries │
|
||||
│ (Ghi) │ │ (Đọc) │
|
||||
└─────┬─────┘ └─────┬─────┘
|
||||
│ │
|
||||
┌─────▼─────┐ ┌─────▼─────┐
|
||||
│ Handler │ │ Handler │
|
||||
└─────┬─────┘ └─────┬─────┘
|
||||
│ │
|
||||
┌─────▼─────┐ ┌─────▼─────┐
|
||||
│ EF Core │ │ Dapper │
|
||||
└───────────┘ └───────────┘
|
||||
```
|
||||
|
||||
| Khía Cạnh | Command | Query |
|
||||
|-----------|---------|-------|
|
||||
| **Mục đích** | Thay đổi trạng thái | Đọc dữ liệu |
|
||||
| **Trả về** | Result/void | Data/DTO |
|
||||
| **ORM** | EF Core | Dapper/Raw SQL |
|
||||
|
||||
## Bắt Đầu Nhanh
|
||||
|
||||
### 1. Định Nghĩa Command
|
||||
|
||||
```csharp
|
||||
public record CreateOrderCommand(
|
||||
string UserId,
|
||||
Address ShippingAddress,
|
||||
List<OrderItemDto> Items) : IRequest<OrderResult>;
|
||||
|
||||
public record OrderResult(Guid OrderId);
|
||||
```
|
||||
|
||||
### 2. Tạo Handler
|
||||
|
||||
```csharp
|
||||
public class CreateOrderCommandHandler
|
||||
: IRequestHandler<CreateOrderCommand, OrderResult>
|
||||
{
|
||||
private readonly IOrderRepository _repository;
|
||||
|
||||
public async Task<OrderResult> Handle(
|
||||
CreateOrderCommand request,
|
||||
CancellationToken ct)
|
||||
{
|
||||
var order = new Order(request.UserId, request.ShippingAddress);
|
||||
|
||||
foreach (var item in request.Items)
|
||||
order.AddItem(item.ProductId, item.Quantity, item.UnitPrice);
|
||||
|
||||
await _repository.AddAsync(order, ct);
|
||||
await _repository.UnitOfWork.SaveChangesAsync(ct);
|
||||
|
||||
return new OrderResult(order.Id);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Query với Dapper
|
||||
|
||||
```csharp
|
||||
public record GetUserOrdersQuery(
|
||||
string UserId,
|
||||
int Skip = 0,
|
||||
int Take = 20) : IRequest<PagedResult<OrderSummaryDto>>;
|
||||
|
||||
public class GetUserOrdersQueryHandler
|
||||
: IRequestHandler<GetUserOrdersQuery, PagedResult<OrderSummaryDto>>
|
||||
{
|
||||
private readonly IDbConnection _connection;
|
||||
|
||||
public async Task<PagedResult<OrderSummaryDto>> Handle(
|
||||
GetUserOrdersQuery request,
|
||||
CancellationToken ct)
|
||||
{
|
||||
const string sql = @"
|
||||
SELECT Id, Status, TotalAmount, CreatedAt
|
||||
FROM Orders
|
||||
WHERE UserId = @UserId
|
||||
ORDER BY CreatedAt DESC
|
||||
OFFSET @Skip ROWS FETCH NEXT @Take ROWS ONLY";
|
||||
|
||||
var orders = await _connection.QueryAsync<OrderSummaryDto>(
|
||||
sql, new { request.UserId, request.Skip, request.Take });
|
||||
|
||||
var total = await _connection.ExecuteScalarAsync<int>(
|
||||
"SELECT COUNT(*) FROM Orders WHERE UserId = @UserId",
|
||||
new { request.UserId });
|
||||
|
||||
return new PagedResult<OrderSummaryDto>(orders.ToList(), total);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 4. Sử Dụng trong Controller
|
||||
|
||||
```csharp
|
||||
[ApiController]
|
||||
[Route("api/v{version:apiVersion}/orders")]
|
||||
public class OrdersController : ControllerBase
|
||||
{
|
||||
private readonly IMediator _mediator;
|
||||
|
||||
[HttpPost]
|
||||
public async Task<ActionResult<ApiResponse<OrderResult>>> CreateOrder(
|
||||
CreateOrderRequest request,
|
||||
CancellationToken ct)
|
||||
{
|
||||
var command = new CreateOrderCommand(
|
||||
GetUserId(), request.ShippingAddress, request.Items);
|
||||
|
||||
var result = await _mediator.Send(command, ct);
|
||||
|
||||
return CreatedAtAction(nameof(GetOrder),
|
||||
new { orderId = result.OrderId },
|
||||
ApiResponse<OrderResult>.Ok(result));
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Pipeline Behaviors
|
||||
|
||||
### Validation Behavior
|
||||
|
||||
```csharp
|
||||
public class ValidationBehavior<TRequest, TResponse>
|
||||
: IPipelineBehavior<TRequest, TResponse>
|
||||
where TRequest : IRequest<TResponse>
|
||||
{
|
||||
private readonly IEnumerable<IValidator<TRequest>> _validators;
|
||||
|
||||
public async Task<TResponse> Handle(
|
||||
TRequest request,
|
||||
RequestHandlerDelegate<TResponse> next,
|
||||
CancellationToken ct)
|
||||
{
|
||||
if (!_validators.Any())
|
||||
return await next();
|
||||
|
||||
var context = new ValidationContext<TRequest>(request);
|
||||
var failures = (await Task.WhenAll(
|
||||
_validators.Select(v => v.ValidateAsync(context, ct))))
|
||||
.SelectMany(r => r.Errors)
|
||||
.Where(f => f != null)
|
||||
.ToList();
|
||||
|
||||
if (failures.Count != 0)
|
||||
throw new ValidationException(failures);
|
||||
|
||||
return await next();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Logging Behavior
|
||||
|
||||
```csharp
|
||||
public class LoggingBehavior<TRequest, TResponse>
|
||||
: IPipelineBehavior<TRequest, TResponse>
|
||||
{
|
||||
private readonly ILogger _logger;
|
||||
|
||||
public async Task<TResponse> Handle(
|
||||
TRequest request,
|
||||
RequestHandlerDelegate<TResponse> next,
|
||||
CancellationToken ct)
|
||||
{
|
||||
var requestName = typeof(TRequest).Name;
|
||||
_logger.LogInformation("Đang xử lý {RequestName}", requestName);
|
||||
|
||||
var stopwatch = Stopwatch.StartNew();
|
||||
var response = await next();
|
||||
stopwatch.Stop();
|
||||
|
||||
_logger.LogInformation(
|
||||
"Đã xử lý {RequestName} trong {ElapsedMs}ms",
|
||||
requestName, stopwatch.ElapsedMilliseconds);
|
||||
|
||||
return response;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Đăng Ký Behaviors
|
||||
|
||||
```csharp
|
||||
builder.Services.AddMediatR(cfg =>
|
||||
{
|
||||
cfg.RegisterServicesFromAssembly(typeof(Program).Assembly);
|
||||
cfg.AddBehavior(typeof(IPipelineBehavior<,>), typeof(LoggingBehavior<,>));
|
||||
cfg.AddBehavior(typeof(IPipelineBehavior<,>), typeof(ValidationBehavior<,>));
|
||||
});
|
||||
```
|
||||
|
||||
## Lỗi Thường Gặp
|
||||
|
||||
### ❌ Dùng EF Core Cho Queries Đơn Giản
|
||||
|
||||
```csharp
|
||||
// SAI: EF Core nặng cho queries
|
||||
return await _context.Orders
|
||||
.Include(o => o.OrderItems)
|
||||
.Where(o => o.UserId == userId)
|
||||
.ToListAsync();
|
||||
```
|
||||
|
||||
### ✅ Dùng Dapper Cho Đọc Tối Ưu
|
||||
|
||||
```csharp
|
||||
// ĐÚNG: Dapper query nhẹ
|
||||
return await _connection.QueryAsync<OrderDto>(
|
||||
"SELECT Id, Status, TotalAmount FROM Orders WHERE UserId = @UserId",
|
||||
new { userId });
|
||||
```
|
||||
|
||||
## Skills Liên Quan
|
||||
|
||||
- [Thiết Kế API](./api-design.md) - Mẫu controller
|
||||
- [Repository Pattern](./repository-pattern.md) - Truy xuất dữ liệu
|
||||
- [Xử Lý Lỗi](./error-handling-patterns.md) - Validation errors
|
||||
- [Mẫu Testing](./testing-patterns.md) - Handler testing
|
||||
|
||||
## Tài Nguyên Bổ Sung
|
||||
|
||||
- **Tài Liệu Skill Đầy Đủ**: [`.agent/skills/cqrs-mediatr/SKILL.md`](../../.agent/skills/cqrs-mediatr/SKILL.md)
|
||||
- **Ví Dụ**: [`.agent/skills/cqrs-mediatr/references/REFERENCE.md`](../../.agent/skills/cqrs-mediatr/references/REFERENCE.md)
|
||||
|
||||
---
|
||||
|
||||
**English Version**: [CQRS & MediatR Patterns](../../en/skills/cqrs-mediatr.md)
|
||||
35
docs/vi/skills/deployment-kubernetes.md
Normal file
35
docs/vi/skills/deployment-kubernetes.md
Normal file
@@ -0,0 +1,35 @@
|
||||
# Kubernetes deployment patterns
|
||||
|
||||
> **Skill**: `deployment-kubernetes`
|
||||
> **Compatibility**: Kubernetes 1.28+, Helm 3+
|
||||
|
||||
## Tổng Quan
|
||||
|
||||
Kubernetes deployment patterns. Use for Pods, Services, Ingress, Helm Charts, ConfigMaps, Secrets, và health probes.
|
||||
|
||||
## Khi Nào Sử Dụng
|
||||
|
||||
Use this skill when:
|
||||
- Deploying services to Kubernetes / Triển khai services lên Kubernetes
|
||||
- Creating Helm charts / Tạo Helm charts
|
||||
- Configuring Ingress routing / Cấu hình Ingress routing
|
||||
- Managing secrets and configs / Quản lý secrets và configs
|
||||
- Setting up health probes / Cài đặt health probes
|
||||
- Scaling applications / Scale ứng dụng
|
||||
|
||||
## Tham Chiếu Nhanh
|
||||
|
||||
Để biết chi tiết về patterns, code examples, và best practices, xem tài liệu skill đầy đủ.
|
||||
|
||||
## Skills Liên Quan
|
||||
|
||||
Xem [Danh Mục Skills](./index.md) để tìm skills liên quan.
|
||||
|
||||
## Tài Nguyên Bổ Sung
|
||||
|
||||
- **Tài Liệu Skill Đầy Đủ**: [`.agent/skills/deployment-kubernetes/SKILL.md`](../../.agent/skills/deployment-kubernetes/SKILL.md)
|
||||
- **Ví Dụ Code**: [`.agent/skills/deployment-kubernetes/references/REFERENCE.md`](../../.agent/skills/deployment-kubernetes/references/REFERENCE.md)
|
||||
|
||||
---
|
||||
|
||||
**English Version**: [English Documentation](../../en/skills/deployment-kubernetes.md)
|
||||
35
docs/vi/skills/docker-traefik.md
Normal file
35
docs/vi/skills/docker-traefik.md
Normal file
@@ -0,0 +1,35 @@
|
||||
# Docker containerization và Traefik reverse proxy
|
||||
|
||||
> **Skill**: `docker-traefik`
|
||||
> **Compatibility**: Docker 24+, Docker Compose v2+, Traefik v3+
|
||||
|
||||
## Tổng Quan
|
||||
|
||||
Docker containerization và Traefik reverse proxy. Use for Dockerfile, docker-compose, routing rules, SSL termination, và load balancing.
|
||||
|
||||
## Khi Nào Sử Dụng
|
||||
|
||||
Use this skill when:
|
||||
- Creating Dockerfiles for .NET services / Tạo Dockerfiles cho services .NET
|
||||
- Configuring docker-compose for local dev / Cấu hình docker-compose cho dev local
|
||||
- Setting up Traefik routing / Cài đặt Traefik routing
|
||||
- Configuring SSL/TLS termination / Cấu hình SSL/TLS termination
|
||||
- Implementing load balancing / Triển khai load balancing
|
||||
- Managing service discovery / Quản lý service discovery
|
||||
|
||||
## Tham Chiếu Nhanh
|
||||
|
||||
Để biết chi tiết về patterns, code examples, và best practices, xem tài liệu skill đầy đủ.
|
||||
|
||||
## Skills Liên Quan
|
||||
|
||||
Xem [Danh Mục Skills](./index.md) để tìm skills liên quan.
|
||||
|
||||
## Tài Nguyên Bổ Sung
|
||||
|
||||
- **Tài Liệu Skill Đầy Đủ**: [`.agent/skills/docker-traefik/SKILL.md`](../../.agent/skills/docker-traefik/SKILL.md)
|
||||
- **Ví Dụ Code**: [`.agent/skills/docker-traefik/references/REFERENCE.md`](../../.agent/skills/docker-traefik/references/REFERENCE.md)
|
||||
|
||||
---
|
||||
|
||||
**English Version**: [English Documentation](../../en/skills/docker-traefik.md)
|
||||
35
docs/vi/skills/documentation.md
Normal file
35
docs/vi/skills/documentation.md
Normal file
@@ -0,0 +1,35 @@
|
||||
# Documentation guidelines for GoodGo project
|
||||
|
||||
> **Skill**: `documentation`
|
||||
> **Compatibility**:
|
||||
|
||||
## Tổng Quan
|
||||
|
||||
Documentation guidelines for GoodGo project. Use for README, guides, architecture docs, or API docs. Ensures bilingual EN/VI consistency.
|
||||
|
||||
## Khi Nào Sử Dụng
|
||||
|
||||
Use this skill when:
|
||||
- Creating README files for services/packages / Tạo README cho services/packages
|
||||
- Writing user guides and tutorials / Viết hướng dẫn sử dụng
|
||||
- Documenting system architecture / Viết tài liệu kiến trúc hệ thống
|
||||
- Creating API documentation / Tạo tài liệu API
|
||||
- Writing operational runbooks / Viết runbooks vận hành
|
||||
- Maintaining bilingual documentation / Duy trì tài liệu song ngữ EN/VI
|
||||
|
||||
## Tham Chiếu Nhanh
|
||||
|
||||
Để biết chi tiết về patterns, code examples, và best practices, xem tài liệu skill đầy đủ.
|
||||
|
||||
## Skills Liên Quan
|
||||
|
||||
Xem [Danh Mục Skills](./index.md) để tìm skills liên quan.
|
||||
|
||||
## Tài Nguyên Bổ Sung
|
||||
|
||||
- **Tài Liệu Skill Đầy Đủ**: [`.agent/skills/documentation/SKILL.md`](../../.agent/skills/documentation/SKILL.md)
|
||||
- **Ví Dụ Code**: [`.agent/skills/documentation/references/REFERENCE.md`](../../.agent/skills/documentation/references/REFERENCE.md)
|
||||
|
||||
---
|
||||
|
||||
**English Version**: [English Documentation](../../en/skills/documentation.md)
|
||||
34
docs/vi/skills/domain-driven-design.md
Normal file
34
docs/vi/skills/domain-driven-design.md
Normal file
@@ -0,0 +1,34 @@
|
||||
# DDD patterns cho complex business logic
|
||||
|
||||
> **Skill**: `domain-driven-design`
|
||||
> **Compatibility**: .NET 8+, EF Core 8+
|
||||
|
||||
## Tổng Quan
|
||||
|
||||
DDD patterns cho complex business logic. Use for Aggregates, Value Objects, Entities, Domain Events, và Rich Domain Model.
|
||||
|
||||
## Khi Nào Sử Dụng
|
||||
|
||||
Use this skill when:
|
||||
- Modeling complex business domains / Mô hình hóa domain phức tạp
|
||||
- Designing aggregates and entities / Thiết kế aggregates và entities
|
||||
- Implementing business rules in domain / Triển khai business rules trong domain
|
||||
- Creating value objects / Tạo value objects
|
||||
- Raising domain events / Raise domain events
|
||||
|
||||
## Tham Chiếu Nhanh
|
||||
|
||||
Để biết chi tiết về patterns, code examples, và best practices, xem tài liệu skill đầy đủ.
|
||||
|
||||
## Skills Liên Quan
|
||||
|
||||
Xem [Danh Mục Skills](./index.md) để tìm skills liên quan.
|
||||
|
||||
## Tài Nguyên Bổ Sung
|
||||
|
||||
- **Tài Liệu Skill Đầy Đủ**: [`.agent/skills/domain-driven-design/SKILL.md`](../../.agent/skills/domain-driven-design/SKILL.md)
|
||||
- **Ví Dụ Code**: [`.agent/skills/domain-driven-design/references/REFERENCE.md`](../../.agent/skills/domain-driven-design/references/REFERENCE.md)
|
||||
|
||||
---
|
||||
|
||||
**English Version**: [English Documentation](../../en/skills/domain-driven-design.md)
|
||||
35
docs/vi/skills/error-handling-patterns.md
Normal file
35
docs/vi/skills/error-handling-patterns.md
Normal file
@@ -0,0 +1,35 @@
|
||||
# Global error handling, domain exceptions, và Result pattern
|
||||
|
||||
> **Skill**: `error-handling-patterns`
|
||||
> **Compatibility**: .NET 10+, Polly, FluentValidation, Microsoft.Extensions.Diagnostics.HealthChecks
|
||||
|
||||
## Tổng Quan
|
||||
|
||||
Global error handling, domain exceptions, và Result pattern. Use for exception middleware, validation errors, Polly resiliency, và health checks.
|
||||
|
||||
## Khi Nào Sử Dụng
|
||||
|
||||
Use this skill when:
|
||||
- Implementing global exception handling / Triển khai xử lý exception toàn cục
|
||||
- Creating domain exceptions / Tạo domain exceptions
|
||||
- Setting up retry policies with Polly / Cài đặt retry policies với Polly
|
||||
- Implementing Circuit Breaker pattern / Triển khai Circuit Breaker
|
||||
- Configuring health checks / Cấu hình health checks
|
||||
- Handling validation errors / Xử lý validation errors
|
||||
|
||||
## Tham Chiếu Nhanh
|
||||
|
||||
Để biết chi tiết về patterns, code examples, và best practices, xem tài liệu skill đầy đủ.
|
||||
|
||||
## Skills Liên Quan
|
||||
|
||||
Xem [Danh Mục Skills](./index.md) để tìm skills liên quan.
|
||||
|
||||
## Tài Nguyên Bổ Sung
|
||||
|
||||
- **Tài Liệu Skill Đầy Đủ**: [`.agent/skills/error-handling-patterns/SKILL.md`](../../.agent/skills/error-handling-patterns/SKILL.md)
|
||||
- **Ví Dụ Code**: [`.agent/skills/error-handling-patterns/references/REFERENCE.md`](../../.agent/skills/error-handling-patterns/references/REFERENCE.md)
|
||||
|
||||
---
|
||||
|
||||
**English Version**: [English Documentation](../../en/skills/error-handling-patterns.md)
|
||||
@@ -0,0 +1,129 @@
|
||||
# Tài Liệu Agent Skills
|
||||
|
||||
Chào mừng đến với tài liệu Agent Skills của GoodGo Platform. Đây là các hướng dẫn chuyên biệt giúp bạn triển khai các mẫu thiết kế nhất quán, sẵn sàng cho production.
|
||||
|
||||
## Agent Skills Là Gì?
|
||||
|
||||
Agent Skills là các module kiến thức có cấu trúc cung cấp:
|
||||
- **Best practices** cho các lĩnh vực kỹ thuật cụ thể
|
||||
- **Code patterns** với ví dụ thực tế từ platform
|
||||
- **Lỗi thường gặp** cần tránh
|
||||
- **Tham chiếu nhanh** cho phát triển nhanh
|
||||
|
||||
Mỗi skill được thiết kế để có thể áp dụng ngay vào công việc của bạn.
|
||||
|
||||
## Skills Theo Danh Mục
|
||||
|
||||
### 🏗️ Kiến Trúc & Thiết Kế
|
||||
|
||||
Làm chủ các mẫu kiến trúc của GoodGo microservices.
|
||||
|
||||
- **[Thiết Kế RESTful API](./api-design.md)** - Tiêu chuẩn cho APIs nhất quán, dễ bảo trì với MediatR
|
||||
- **[CQRS & MediatR](./cqrs-mediatr.md)** - Tách biệt operations đọc/ghi với pipeline behaviors
|
||||
- **[Domain-Driven Design](./domain-driven-design.md)** - Rich domain models, aggregates, và domain events
|
||||
|
||||
### 💾 Truy Xuất Dữ Liệu
|
||||
|
||||
Các mẫu truy xuất dữ liệu hiệu quả và mở rộng.
|
||||
|
||||
- **[Repository Pattern](./repository-pattern.md)** - Entity Framework Core repositories và Unit of Work
|
||||
- **[Redis Caching](./redis-caching.md)** - Chiến lược caching phân tán với invalidation patterns
|
||||
|
||||
### 🔐 Bảo Mật & Xác Thực
|
||||
|
||||
Bảo vệ services và người dùng.
|
||||
|
||||
- **[Mẫu Bảo Mật](./security.md)** - Authentication, authorization, và data protection với Duende IdentityServer
|
||||
|
||||
### ⚡ Xử Lý Lỗi & Khả Năng Phục Hồi
|
||||
|
||||
Xây dựng services mạnh mẽ, chịu lỗi tốt.
|
||||
|
||||
- **[Mẫu Xử Lý Lỗi](./error-handling-patterns.md)** - Global exception handling, Result pattern, và Polly resilience
|
||||
|
||||
### 🧪 Kiểm Thử
|
||||
|
||||
Đảm bảo chất lượng qua testing toàn diện.
|
||||
|
||||
- **[Mẫu Testing](./testing-patterns.md)** - Unit, integration, và functional tests với xUnit và Testcontainers
|
||||
|
||||
### 🚀 Hạ Tầng & Triển Khai
|
||||
|
||||
Triển khai và giám sát production services.
|
||||
|
||||
- **[Docker & Traefik](./docker-traefik.md)** - Containerization và reverse proxy configuration
|
||||
- **[Triển Khai Kubernetes](./deployment-kubernetes.md)** - Pods, Services, Ingress, và Helm Charts
|
||||
- **[Observability](./observability.md)** - Monitoring với Prometheus, Grafana, và distributed tracing
|
||||
|
||||
### 🔄 Giao Tiếp
|
||||
|
||||
Kết nối liên dịch vụ mượt mà.
|
||||
|
||||
- **[Giao Tiếp Liên Dịch Vụ](./inter-service-communication.md)** - Event Bus (RabbitMQ), HTTP clients với Polly, và gRPC
|
||||
|
||||
### 📝 Tài Liệu & Phát Triển
|
||||
|
||||
Duy trì tài liệu và coding standards chất lượng.
|
||||
|
||||
- **[Hướng Dẫn Viết Tài Liệu](./documentation.md)** - Tiêu chuẩn tài liệu song ngữ (EN/VI)
|
||||
- **[Quy Chuẩn Comment Code](./comment-code.md)** - Comments song ngữ và XML documentation
|
||||
- **[Viết Agent Skills](./skill-authoring.md)** - Cách tạo và duy trì Agent Skills
|
||||
- **[Quy Tắc Dự Án](./project-rules.md)** - Coding standards và kiến trúc toàn platform
|
||||
|
||||
## Cách Sử Dụng Skills
|
||||
|
||||
### 1. Tìm Skill Phù Hợp
|
||||
|
||||
Duyệt theo danh mục ở trên hoặc tìm kiếm các pattern cụ thể bạn cần triển khai.
|
||||
|
||||
### 2. Hiểu Ngữ Cảnh
|
||||
|
||||
Mỗi skill bắt đầu với phần "When to Use" (Khi Nào Sử Dụng) giúp bạn xác định xem có áp dụng được không.
|
||||
|
||||
### 3. Học Các Mẫu
|
||||
|
||||
Nghiên cứu code examples và diagrams. Tất cả ví dụ đều dựa trên code production thực tế từ GoodGo platform.
|
||||
|
||||
### 4. Tránh Lỗi Thường Gặp
|
||||
|
||||
Xem phần "Common Mistakes" để tiết kiệm thời gian và tránh các lỗi đã biết.
|
||||
|
||||
### 5. Tham Chiếu Nhanh
|
||||
|
||||
Sử dụng phần "Quick Reference" để tra cứu nhanh trong quá trình phát triển.
|
||||
|
||||
## Phát Triển Skills
|
||||
|
||||
Skills là tài liệu sống phát triển cùng platform. Nếu bạn phát hiện patterns tốt hơn hoặc muốn đóng góp:
|
||||
|
||||
1. Xem hướng dẫn [Viết Agent Skills](./skill-authoring.md)
|
||||
2. Tuân theo cấu trúc và format song ngữ đã thiết lập
|
||||
3. Bao gồm ví dụ thực tế từ codebase
|
||||
4. Submit để review
|
||||
|
||||
## Liên Kết Nhanh
|
||||
|
||||
### Theo Stack Công Nghệ
|
||||
|
||||
- **.NET / C#**: [API Design](./api-design.md), [CQRS](./cqrs-mediatr.md), [Repository](./repository-pattern.md), [Testing](./testing-patterns.md)
|
||||
- **Infrastructure**: [Docker](./docker-traefik.md), [Kubernetes](./deployment-kubernetes.md), [Observability](./observability.md)
|
||||
- **Security**: [Security Patterns](./security.md), [Error Handling](./error-handling-patterns.md)
|
||||
- **Documentation**: [Docs Guidelines](./documentation.md), [Code Comments](./comment-code.md)
|
||||
|
||||
### Theo Use Case
|
||||
|
||||
- **Bắt đầu service mới**: [Project Rules](./project-rules.md) → [API Design](./api-design.md) → [CQRS](./cqrs-mediatr.md) → [Repository](./repository-pattern.md)
|
||||
- **Thêm authentication**: [Security Patterns](./security.md)
|
||||
- **Cải thiện performance**: [Redis Caching](./redis-caching.md)
|
||||
- **Deploy lên production**: [Docker](./docker-traefik.md) → [Kubernetes](./deployment-kubernetes.md) → [Observability](./observability.md)
|
||||
- **Viết tests**: [Testing Patterns](./testing-patterns.md)
|
||||
|
||||
## Tài Nguyên Bổ Sung
|
||||
|
||||
- [Tài Liệu Kiến Trúc](../architecture/system-design.md) - Overall system design
|
||||
- [Hướng Dẫn Phát Triển](../guides/getting-started.md) - Bắt đầu với local development
|
||||
- [API Specifications](../api/openapi/) - Tài liệu OpenAPI
|
||||
|
||||
---
|
||||
|
||||
**Lưu ý**: Tất cả skills tuân theo tiêu chuẩn tài liệu song ngữ (English/Vietnamese). Phiên bản tiếng Anh có sẵn tại [`docs/en/skills/`](../../en/skills/index.md).
|
||||
|
||||
33
docs/vi/skills/inter-service-communication.md
Normal file
33
docs/vi/skills/inter-service-communication.md
Normal file
@@ -0,0 +1,33 @@
|
||||
# Giao tiếp liên dịch vụ
|
||||
|
||||
> **Skill**: `inter-service-communication`
|
||||
> **Compatibility**: .NET 8+, MassTransit, RabbitMQ, Polly, gRPC
|
||||
|
||||
## Tổng Quan
|
||||
|
||||
Giao tiếp liên dịch vụ. Use for Event Bus (RabbitMQ), Integration Events, HTTP Client với Polly, và gRPC patterns.
|
||||
|
||||
## Khi Nào Sử Dụng
|
||||
|
||||
Use this skill when:
|
||||
- Publishing domain events to other services / Publish domain events đến services khác
|
||||
- Consuming integration events / Consume integration events
|
||||
- Making HTTP calls to other services / Gọi HTTP đến services khác
|
||||
- Implementing resilient communication / Triển khai giao tiếp có khả năng phục hồi
|
||||
|
||||
## Tham Chiếu Nhanh
|
||||
|
||||
Để biết chi tiết về patterns, code examples, và best practices, xem tài liệu skill đầy đủ.
|
||||
|
||||
## Skills Liên Quan
|
||||
|
||||
Xem [Danh Mục Skills](./index.md) để tìm skills liên quan.
|
||||
|
||||
## Tài Nguyên Bổ Sung
|
||||
|
||||
- **Tài Liệu Skill Đầy Đủ**: [`.agent/skills/inter-service-communication/SKILL.md`](../../.agent/skills/inter-service-communication/SKILL.md)
|
||||
- **Ví Dụ Code**: [`.agent/skills/inter-service-communication/references/REFERENCE.md`](../../.agent/skills/inter-service-communication/references/REFERENCE.md)
|
||||
|
||||
---
|
||||
|
||||
**English Version**: [English Documentation](../../en/skills/inter-service-communication.md)
|
||||
34
docs/vi/skills/observability.md
Normal file
34
docs/vi/skills/observability.md
Normal file
@@ -0,0 +1,34 @@
|
||||
# Monitoring, logging, và tracing patterns
|
||||
|
||||
> **Skill**: `observability`
|
||||
> **Compatibility**: .NET 10+, Serilog, OpenTelemetry, Prometheus, Grafana
|
||||
|
||||
## Tổng Quan
|
||||
|
||||
Monitoring, logging, và tracing patterns. Use for Prometheus metrics, Grafana dashboards, Loki logging, và distributed tracing.
|
||||
|
||||
## Khi Nào Sử Dụng
|
||||
|
||||
Use this skill when:
|
||||
- Implementing health checks / Triển khai health checks
|
||||
- Configuring structured logging / Cấu hình structured logging
|
||||
- Setting up Prometheus metrics / Cài đặt Prometheus metrics
|
||||
- Implementing distributed tracing / Triển khai distributed tracing
|
||||
- Creating Grafana dashboards / Tạo Grafana dashboards
|
||||
|
||||
## Tham Chiếu Nhanh
|
||||
|
||||
Để biết chi tiết về patterns, code examples, và best practices, xem tài liệu skill đầy đủ.
|
||||
|
||||
## Skills Liên Quan
|
||||
|
||||
Xem [Danh Mục Skills](./index.md) để tìm skills liên quan.
|
||||
|
||||
## Tài Nguyên Bổ Sung
|
||||
|
||||
- **Tài Liệu Skill Đầy Đủ**: [`.agent/skills/observability/SKILL.md`](../../.agent/skills/observability/SKILL.md)
|
||||
- **Ví Dụ Code**: [`.agent/skills/observability/references/REFERENCE.md`](../../.agent/skills/observability/references/REFERENCE.md)
|
||||
|
||||
---
|
||||
|
||||
**English Version**: [English Documentation](../../en/skills/observability.md)
|
||||
34
docs/vi/skills/project-rules.md
Normal file
34
docs/vi/skills/project-rules.md
Normal file
@@ -0,0 +1,34 @@
|
||||
# GoodGo Platform coding standards and architecture
|
||||
|
||||
> **Skill**: `project-rules`
|
||||
> **Compatibility**: .NET 10+, ASP.NET Core, MediatR, Entity Framework Core
|
||||
|
||||
## Tổng Quan
|
||||
|
||||
GoodGo Platform coding standards and architecture. Use when working with services, apps, packages, or infrastructure.
|
||||
|
||||
## Khi Nào Sử Dụng
|
||||
|
||||
Use this skill when:
|
||||
- Creating new .NET services / Tạo services .NET mới
|
||||
- Working with project structure / Làm việc với cấu trúc dự án
|
||||
- Following naming conventions / Tuân thủ quy tắc đặt tên
|
||||
- Deploying services with Docker/Traefik / Triển khai với Docker/Traefik
|
||||
- Understanding tech stack / Hiểu tech stack của dự án
|
||||
|
||||
## Tham Chiếu Nhanh
|
||||
|
||||
Để biết chi tiết về patterns, code examples, và best practices, xem tài liệu skill đầy đủ.
|
||||
|
||||
## Skills Liên Quan
|
||||
|
||||
Xem [Danh Mục Skills](./index.md) để tìm skills liên quan.
|
||||
|
||||
## Tài Nguyên Bổ Sung
|
||||
|
||||
- **Tài Liệu Skill Đầy Đủ**: [`.agent/skills/project-rules/SKILL.md`](../../.agent/skills/project-rules/SKILL.md)
|
||||
- **Ví Dụ Code**: [`.agent/skills/project-rules/references/REFERENCE.md`](../../.agent/skills/project-rules/references/REFERENCE.md)
|
||||
|
||||
---
|
||||
|
||||
**English Version**: [English Documentation](../../en/skills/project-rules.md)
|
||||
34
docs/vi/skills/redis-caching.md
Normal file
34
docs/vi/skills/redis-caching.md
Normal file
@@ -0,0 +1,34 @@
|
||||
# Redis caching patterns cho distributed systems
|
||||
|
||||
> **Skill**: `redis-caching`
|
||||
> **Compatibility**: .NET 8+, StackExchange.Redis, Microsoft.Extensions.Caching.StackExchangeRedis
|
||||
|
||||
## Tổng Quan
|
||||
|
||||
Redis caching patterns cho distributed systems. Use for cache-aside, session storage, rate limiting, và distributed locks.
|
||||
|
||||
## Khi Nào Sử Dụng
|
||||
|
||||
Use this skill when:
|
||||
- Implementing distributed cache / Triển khai distributed cache
|
||||
- Caching API responses / Caching responses API
|
||||
- Managing user sessions / Quản lý user sessions
|
||||
- Implementing rate limiting / Triển khai rate limiting
|
||||
- Using Redis as primary store (e.g., shopping cart) / Dùng Redis làm store chính
|
||||
|
||||
## Tham Chiếu Nhanh
|
||||
|
||||
Để biết chi tiết về patterns, code examples, và best practices, xem tài liệu skill đầy đủ.
|
||||
|
||||
## Skills Liên Quan
|
||||
|
||||
Xem [Danh Mục Skills](./index.md) để tìm skills liên quan.
|
||||
|
||||
## Tài Nguyên Bổ Sung
|
||||
|
||||
- **Tài Liệu Skill Đầy Đủ**: [`.agent/skills/redis-caching/SKILL.md`](../../.agent/skills/redis-caching/SKILL.md)
|
||||
- **Ví Dụ Code**: [`.agent/skills/redis-caching/references/REFERENCE.md`](../../.agent/skills/redis-caching/references/REFERENCE.md)
|
||||
|
||||
---
|
||||
|
||||
**English Version**: [English Documentation](../../en/skills/redis-caching.md)
|
||||
35
docs/vi/skills/repository-pattern.md
Normal file
35
docs/vi/skills/repository-pattern.md
Normal file
@@ -0,0 +1,35 @@
|
||||
# Entity Framework Core repository và data access patterns
|
||||
|
||||
> **Skill**: `repository-pattern`
|
||||
> **Compatibility**: .NET 10+, Entity Framework Core 8+, Dapper
|
||||
|
||||
## Tổng Quan
|
||||
|
||||
Entity Framework Core repository và data access patterns. Use for DbContext, repositories, migrations, aggregate roots, Unit of Work, và CQRS queries.
|
||||
|
||||
## Khi Nào Sử Dụng
|
||||
|
||||
Use this skill when:
|
||||
- Creating new repositories for aggregates / Tạo repositories mới cho aggregates
|
||||
- Implementing data access with EF Core / Triển khai data access với EF Core
|
||||
- Setting up Unit of Work pattern / Cài đặt Unit of Work pattern
|
||||
- Separating read/write operations (CQRS) / Phân tách read/write (CQRS)
|
||||
- Creating database migrations / Tạo database migrations
|
||||
- Optimizing query performance / Tối ưu hiệu năng query
|
||||
|
||||
## Tham Chiếu Nhanh
|
||||
|
||||
Để biết chi tiết về patterns, code examples, và best practices, xem tài liệu skill đầy đủ.
|
||||
|
||||
## Skills Liên Quan
|
||||
|
||||
Xem [Danh Mục Skills](./index.md) để tìm skills liên quan.
|
||||
|
||||
## Tài Nguyên Bổ Sung
|
||||
|
||||
- **Tài Liệu Skill Đầy Đủ**: [`.agent/skills/repository-pattern/SKILL.md`](../../.agent/skills/repository-pattern/SKILL.md)
|
||||
- **Ví Dụ Code**: [`.agent/skills/repository-pattern/references/REFERENCE.md`](../../.agent/skills/repository-pattern/references/REFERENCE.md)
|
||||
|
||||
---
|
||||
|
||||
**English Version**: [English Documentation](../../en/skills/repository-pattern.md)
|
||||
36
docs/vi/skills/security.md
Normal file
36
docs/vi/skills/security.md
Normal file
@@ -0,0 +1,36 @@
|
||||
# Security patterns for GoodGo platform
|
||||
|
||||
> **Skill**: `security`
|
||||
> **Compatibility**: .NET 10+, ASP.NET Core Identity, Duende IdentityServer
|
||||
|
||||
## Tổng Quan
|
||||
|
||||
Security patterns for GoodGo platform. Use for authentication, authorization, data protection, input validation, rate limiting, or secrets management.
|
||||
|
||||
## Khi Nào Sử Dụng
|
||||
|
||||
Use this skill when:
|
||||
- Implementing authentication (JWT, OAuth2, OIDC) / Triển khai authentication
|
||||
- Setting up authorization (RBAC, policies) / Cài đặt authorization
|
||||
- Protecting sensitive data / Bảo vệ dữ liệu nhạy cảm
|
||||
- Validating user inputs / Xác thực input từ user
|
||||
- Implementing 2FA / Triển khai xác thực 2 yếu tố
|
||||
- Managing secrets / Quản lý secrets
|
||||
- Auditing security events / Ghi log sự kiện bảo mật
|
||||
|
||||
## Tham Chiếu Nhanh
|
||||
|
||||
Để biết chi tiết về patterns, code examples, và best practices, xem tài liệu skill đầy đủ.
|
||||
|
||||
## Skills Liên Quan
|
||||
|
||||
Xem [Danh Mục Skills](./index.md) để tìm skills liên quan.
|
||||
|
||||
## Tài Nguyên Bổ Sung
|
||||
|
||||
- **Tài Liệu Skill Đầy Đủ**: [`.agent/skills/security/SKILL.md`](../../.agent/skills/security/SKILL.md)
|
||||
- **Ví Dụ Code**: [`.agent/skills/security/references/REFERENCE.md`](../../.agent/skills/security/references/REFERENCE.md)
|
||||
|
||||
---
|
||||
|
||||
**English Version**: [English Documentation](../../en/skills/security.md)
|
||||
31
docs/vi/skills/skill-authoring.md
Normal file
31
docs/vi/skills/skill-authoring.md
Normal file
@@ -0,0 +1,31 @@
|
||||
# Phương pháp viết Agent Skills chuyên nghiệp
|
||||
|
||||
> **Skill**: `skill-authoring`
|
||||
> **Compatibility**: Antigravity, Claude Code, hoặc các agent khác hỗ trợ Agent Skills spec
|
||||
|
||||
## Tổng Quan
|
||||
|
||||
Phương pháp viết Agent Skills chuyên nghiệp. Sử dụng khi tạo mới, cập nhật, hoặc review Agent Skills theo chuẩn AgentSkills.io và best practices của dự án GoodGo.
|
||||
|
||||
## Khi Nào Sử Dụng
|
||||
|
||||
Use this skill when:
|
||||
- Condition 1
|
||||
- Condition 2
|
||||
|
||||
## Tham Chiếu Nhanh
|
||||
|
||||
Để biết chi tiết về patterns, code examples, và best practices, xem tài liệu skill đầy đủ.
|
||||
|
||||
## Skills Liên Quan
|
||||
|
||||
Xem [Danh Mục Skills](./index.md) để tìm skills liên quan.
|
||||
|
||||
## Tài Nguyên Bổ Sung
|
||||
|
||||
- **Tài Liệu Skill Đầy Đủ**: [`.agent/skills/skill-authoring/SKILL.md`](../../.agent/skills/skill-authoring/SKILL.md)
|
||||
- **Ví Dụ Code**: [`.agent/skills/skill-authoring/references/REFERENCE.md`](../../.agent/skills/skill-authoring/references/REFERENCE.md)
|
||||
|
||||
---
|
||||
|
||||
**English Version**: [English Documentation](../../en/skills/skill-authoring.md)
|
||||
34
docs/vi/skills/testing-patterns.md
Normal file
34
docs/vi/skills/testing-patterns.md
Normal file
@@ -0,0 +1,34 @@
|
||||
# Unit/Integration testing patterns cho
|
||||
|
||||
> **Skill**: `testing-patterns`
|
||||
> **Compatibility**: .NET 10+, xUnit, NSubstitute, Testcontainers, Microsoft.AspNetCore.TestHost
|
||||
|
||||
## Tổng Quan
|
||||
|
||||
Unit/Integration testing patterns cho .NET microservices. Use for xUnit, NSubstitute, Testcontainers, và testing MediatR handlers.
|
||||
|
||||
## Khi Nào Sử Dụng
|
||||
|
||||
Use this skill when:
|
||||
- Writing unit tests for handlers / Viết unit tests cho handlers
|
||||
- Testing controllers with mocked dependencies / Test controllers với dependencies giả lập
|
||||
- Creating integration tests with database / Tạo integration tests với database
|
||||
- Setting up functional tests with TestServer / Cài đặt functional tests với TestServer
|
||||
- Mocking services với NSubstitute / Giả lập services với NSubstitute
|
||||
|
||||
## Tham Chiếu Nhanh
|
||||
|
||||
Để biết chi tiết về patterns, code examples, và best practices, xem tài liệu skill đầy đủ.
|
||||
|
||||
## Skills Liên Quan
|
||||
|
||||
Xem [Danh Mục Skills](./index.md) để tìm skills liên quan.
|
||||
|
||||
## Tài Nguyên Bổ Sung
|
||||
|
||||
- **Tài Liệu Skill Đầy Đủ**: [`.agent/skills/testing-patterns/SKILL.md`](../../.agent/skills/testing-patterns/SKILL.md)
|
||||
- **Ví Dụ Code**: [`.agent/skills/testing-patterns/references/REFERENCE.md`](../../.agent/skills/testing-patterns/references/REFERENCE.md)
|
||||
|
||||
---
|
||||
|
||||
**English Version**: [English Documentation](../../en/skills/testing-patterns.md)
|
||||
Reference in New Issue
Block a user