pos-system/microservices/.agent/skills/dotnet-microservice-workflow/references/checklist.md

Checklist: .NET Microservice Development

Checklist chi tiết cho từng giai đoạn phát triển .NET Microservices.

---

Pre-Development Checklist

Trước khi bắt đầu code, hãy đảm bảo:

• Đã hiểu rõ yêu cầu nghiệp vụ (business requirements)
• Đã xác định được Bounded Context
• Đã xác định các Aggregates và mối quan hệ
• Đã quyết định service sẽ own database riêng
• Đã review các skills liên quan:
  • Domain-Driven Design
  • Repository Pattern
  • CQRS MediatR
  • API Design

---

Phase 1: Domain Layer Checklist

1.1 Project Setup

• Tạo project ServiceName.Domain
• Thêm folder structure:

  ServiceName.Domain/
  ├── AggregatesModel/
  │   └── {Aggregate}Aggregate/
  ├── Events/
  ├── Exceptions/
  └── SeedWork/
  

1.2 Base Classes (trong SeedWork/)

• Entity.cs - Base class cho entities
  • Id property với protected set
  • Domain events collection
  • Equality by Id
• ValueObject.cs - Base class cho value objects
  • Immutable
  • Equality by all properties
• IAggregateRoot.cs - Marker interface
• IDomainEvent.cs - Interface cho domain events

1.3 Domain Exceptions (trong Exceptions/)

• DomainException.cs - Base exception cho domain violations

1.4 Aggregate Design

• Xác định Aggregate Root
• Properties với private set
• Collections dùng backing fields + IReadOnlyCollection<T>
• Business methods thay vì public setters
• Domain events trong aggregate methods

1.5 Value Objects

• Immutable (chỉ có constructor, không có setters)
• Override GetEqualityComponents()
• Examples: Address, Money, Email, etc.

1.6 Domain Events

• Implement IDomainEvent
• Đặt trong folder Events/
• Raise trong aggregate methods

1.7 Repository Interface

• Đặt trong folder AggregatesModel/{Aggregate}Aggregate/
• Chỉ cho Aggregate Root
• Include IUnitOfWork UnitOfWork { get; }

Phase 1 Validation

// ✅ Kiểm tra domain model đúng chuẩn:
// 1. Không có public setters
// 2. Collections là IReadOnlyCollection<T>
// 3. Business logic trong aggregate methods
// 4. Domain events được raise khi state change

---

Phase 2: Infrastructure Layer Checklist

2.1 Project Setup

• Tạo project ServiceName.Infrastructure
• Thêm folder structure:

  ServiceName.Infrastructure/
  ├── Data/
  │   ├── Configurations/
  │   └── ApplicationDbContext.cs
  ├── Repositories/
  └── Services/
  

2.2 NuGet Packages

• Microsoft.EntityFrameworkCore
• Npgsql.EntityFrameworkCore.PostgreSQL hoặc provider khác
• Dapper (cho queries)

2.3 DbContext

• Implement IUnitOfWork
• Register tất cả aggregate roots
• Apply configurations từ assembly

public class ApplicationDbContext : DbContext, IUnitOfWork
{
    public DbSet<Order> Orders => Set<Order>();
    
    protected override void OnModelCreating(ModelBuilder builder)
    {
        builder.ApplyConfigurationsFromAssembly(typeof(ApplicationDbContext).Assembly);
    }
}

2.4 Entity Configurations

• Một file configuration per aggregate root
• Sử dụng Fluent API, KHÔNG dùng Data Annotations
• Configure owned entities (Value Objects)
• Configure navigation properties với UsePropertyAccessMode

2.5 Repository Implementation

• Implement interface từ Domain layer
• Expose IUnitOfWork từ DbContext
• KHÔNG gọi SaveChangesAsync trong repository

2.6 Database Migrations

• Tạo initial migration
• Test migration script

# Tạo migration
dotnet ef migrations add InitialCreate --project src/ServiceName.Infrastructure

# Apply migration
dotnet ef database update --project src/ServiceName.Infrastructure

Phase 2 Validation

// ✅ Kiểm tra infrastructure đúng chuẩn:
// 1. Domain không reference Infrastructure
// 2. Không có Data Annotations trên Domain entities
// 3. SaveChangesAsync chỉ được gọi từ Handler
// 4. Repository chỉ cho Aggregate Root

---

Phase 3: Application Layer Checklist

3.1 Project Setup

• Commands trong ServiceName.API/Application/Commands/
• Queries trong ServiceName.API/Application/Queries/
• Validators trong ServiceName.API/Application/Validators/
• Behaviors trong ServiceName.API/Application/Behaviors/

3.2 NuGet Packages

• MediatR
• FluentValidation
• FluentValidation.DependencyInjectionExtensions
• Dapper (đã có từ Infrastructure)

3.3 Commands

• Tạo Command record với IRequest<TResult>
• Tạo CommandHandler với IRequestHandler<TCommand, TResult>
• Logic chỉ orchestration: load aggregate, call domain method, save

3.4 Queries

• Tạo Query record với IRequest<TResult>
• Tạo QueryHandler với Dapper
• Return lightweight DTOs, không Domain entities

3.5 Validators

• Tạo validator cho mỗi Command
• Sử dụng FluentValidation rules
• Input validation, KHÔNG phải business rules

3.6 Pipeline Behaviors

• LoggingBehavior - Log request/response
• ValidationBehavior - Run validators
• (Optional) TransactionBehavior - Wrap in transaction

3.7 DI Registration (trong Program.cs)

builder.Services.AddMediatR(cfg =>
{
    cfg.RegisterServicesFromAssembly(typeof(Program).Assembly);
    cfg.AddBehavior(typeof(IPipelineBehavior<,>), typeof(LoggingBehavior<,>));
    cfg.AddBehavior(typeof(IPipelineBehavior<,>), typeof(ValidationBehavior<,>));
});

builder.Services.AddValidatorsFromAssembly(typeof(Program).Assembly);

Phase 3 Validation

// ✅ Kiểm tra application layer đúng chuẩn:
// 1. Business logic trong Domain, KHÔNG trong Handler
// 2. Queries dùng Dapper, KHÔNG dùng EF Core
// 3. Validators là input validation, KHÔNG phải business rules
// 4. Pipeline behaviors được register đúng thứ tự

---

Phase 4: API Layer Checklist

4.1 Project Setup

• Controllers trong ServiceName.API/Controllers/
• DTOs trong ServiceName.API/DTOs/ hoặc Application/DTOs/

4.2 NuGet Packages

• Swashbuckle.AspNetCore
• AspNetCore.HealthChecks.UI.Client
• AspNetCore.HealthChecks.NpgSql (hoặc provider khác)
• Microsoft.Extensions.Http.Polly

4.3 Controllers

• Slim controllers: chỉ nhận request, gọi MediatR
• [ApiController] attribute
• [ApiVersion] attribute
• [Route("api/v{version:apiVersion}/...")]
• [SwaggerOperation] và [SwaggerResponse] attributes
• Return ApiResponse<T> wrapper

4.4 Health Checks

• Register health checks cho DB, Redis, RabbitMQ
• Map endpoint /hc hoặc /health

builder.Services.AddHealthChecks()
    .AddNpgSql(connectionString, name: "postgresql");

app.MapHealthChecks("/hc");

4.5 Resilience (Polly)

• Configure retry policy với exponential backoff
• Configure circuit breaker
• Apply cho tất cả HTTP clients

4.6 OpenAPI/Swagger

• Configure Swagger UI
• Add XML documentation
• Configure API versioning

4.7 Error Handling

• Global exception handler middleware
• Map domain exceptions to HTTP status codes
• Standardized error response format

4.8 DI Registration Complete

• MediatR + Behaviors
• Validators
• Repositories
• DbContext
• Dapper connection
• HTTP clients với Polly
• Health checks

Phase 4 Validation

// ✅ Kiểm tra API layer đúng chuẩn:
// 1. Controllers slim, chỉ gọi MediatR
// 2. Health checks hoạt động
// 3. API versioning đúng
// 4. Error responses nhất quán
// 5. OpenAPI documentation đầy đủ

---

Post-Development Checklist

Testing

• Unit tests cho Domain layer
• Unit tests cho Handlers (mock repositories)
• Integration tests với TestServer
• Test health check endpoints

Documentation

• README.md với setup instructions
• API documentation qua Swagger
• Architecture decision records (nếu cần)

Deployment

• Dockerfile hoạt động
• docker-compose.yml cho local dev
• Health check endpoint cho K8s probes

---

Quick Summary

Phase	Focus	Key Deliverables
1	Domain	Aggregates, Entities, VOs, Events
2	Infrastructure	DbContext, Configs, Repositories
3	Application	Commands, Queries, Handlers, Validators
4	API	Controllers, Health, Resilience, Docs