📚 Pré-requisitos Teóricos: este projeto aplica conceitos ensinados no Capítulo 18 — Injeção de Dependência e Logging da Especialização em Sistemas com C#. Recomendado revisar antes de iniciar.

🎯 Clean Architecture & CQRS com MediatR em .NET 8

v1.0 — Clean Architecture, CQRS, MediatR, FluentValidation, Domain-Driven Design

Série Prática C# & .NET 8 — Projeto Especializado

➡️ Projeto: 🎯 Clean Architecture & CQRS com MediatR em .NET 8

Subpasta Canônica: api-aspnet/

🏛️ Visão Geral & Arquitetura Visual

O projeto Clean Architecture & CQRS com MediatR em .NET 8 estabelece uma arquitetura corporativa avançada baseada no princípio da separação de responsabilidades de comando e consulta (CQRS). A solução divide o fluxo entre Commands (mutações de estado) e Queries (leituras otimizadas), utilizando a biblioteca MediatR para desacoplar controllers da camada de aplicação, com pipeline behaviors para validação automática de dados via FluentValidation e logging de diagnóstico.

Arquitetura do Projeto 🎯 Clean Architecture & CQRS com MediatR em .NET 8

📁 Estrutura de Pastas Anti-Colisão

Os artefatos em C# / .NET 8, projetos csproj e controladores estão organizados na subpasta canônica api-aspnet/:

catalogo_projetos/sistemas_csharp_03_cleanarch_cqrs/
├── assets/
│   └── arquitetura_csharp_03.svg
├── api-aspnet/
│   ├── Program.cs
│   ├── README.md
│   └── ...
└── index.md

🧑‍💼 Engenharia de Software & Especificação Formal

1. Histórias de Usuário (User Stories)

ID	Persona	Narrativa da Funcionalidade	Critério de Aceitação Principal	Prioridade
US-01	Arquiteto de Software	Quero desacoplar completamente os controladores da lógica de negócios	Controllers apenas despacham commands e queries via `IMediator.Send()`.	Alta
US-02	Desenvolvedor Backend	Quero validação automática de commands antes da execução do handler	Pipeline behavior interceptando commands com FluentValidation.	Alta
US-03	Desenvolvedor Backend	Quero separação formal entre operações de escrita e de leitura (CQRS)	Queries retornando DTOs leves sem tracking e Commands encapsulando regras de negócio.	Alta
US-04	Engenheiro de Confiabilidade	Quero logging padronizado de tempo de execução de cada comando	Logging behavior medindo duração de cada requisição.	Média
US-05	Engenheiro de QA	Quero testes unitários isolados para cada CommandHandler	Testes de handlers mockando apenas interfaces de repositório.	Média

2. Requisitos do Sistema

Requisitos Funcionais (RF)

RF-01: Estruturar o projeto nas camadas: Domain, Application, Infrastructure e WebApi.
RF-02: Implementar CriarPedidoCommand e respectivo CriarPedidoCommandHandler.
RF-03: Implementar ObterPedidoPorIdQuery e seu query handler.
RF-04: Adicionar pipeline behavior de validação utilizando FluentValidation.
RF-05: Configurar endpoints REST acionando o pipeline MediatR.

Requisitos Não-Funcionais (RNF)

RNF-01 (Princípio da Responsabilidade Única): Cada comando e consulta possui handler exclusivo e isolado.
RNF-02 (Testabilidade): Camada de domínio e aplicação 100% testável sem dependência de banco de dados.
RNF-03 (Manutenibilidade): Facilidade de adição de novos casos de uso sem alterar código existente.
RNF-04 (Conformidade .NET 8): Adoção de padrões idiomáticos de injeção de dependência e C# 12.
RNF-05 (Resiliência a Erros): Erros de validação convertidos automaticamente em respostas HTTP 400 uniformes.

3. Diagrama de Casos de Uso

flowchart TD
    Client[(fa:fa-desktop Clientes da API)]
    Pipeline[(fa:fa-filter Pipeline MediatR Behaviors)]
    Domain[(fa:fa-shield-halved Domínio e Repositórios)]

    subgraph AppCleanArch ["🎯 Clean Architecture CQRS (api-aspnet)"]
        UC01["Receber Comando / Consulta"]
        UC02["Validar via Pipeline Behavior"]
        UC03["Despachar para Handler Específico"]
        UC04["Executar Regra de Domínio"]
        UC05["Retornar DTO de Resposta"]
    end

    Client --> UC01
    UC01 --> Pipeline
    Pipeline --> UC02
    UC02 --> UC03
    UC03 --> Domain
    Domain --> UC04
    UC04 --> UC05
    UC05 --> Client

4. Matriz de Rastreabilidade (RTM)

ID Requisito	História de Usuário	Artefato de Código	Teste de Aceitação
RF-01	US-01	`api-aspnet/src/`	Estrutura de diretórios Clean Architecture
RF-02	US-03	`api-aspnet/src/`	Command e CommandHandler
RF-03	US-03	`api-aspnet/src/`	Query e QueryHandler
RF-04	US-02	`api-aspnet/src/`	Pipeline Behavior de Validação
RF-05	US-01, US-05	`api-aspnet/src/`	Controllers e suíte de testes

🛠️ Implementação Guiada

ℹ️ O trecho de código que ficava aqui não correspondia ao código do projeto e foi retirado. Consulte os arquivos em api-aspnet.

🚀 Como Executar no Laboratório

1. Navegue até a subpasta do projeto

cd catalogo_projetos/sistemas_csharp_03_cleanarch_cqrs/api-aspnet

2. Execute via .NET CLI

dotnet run

🏁 Matriz de Checkpoints de Conclusão

Checkpoint	Meta Técnica	Critério de Aceite	Status
CP-01	Estrutura Clean Architecture	Camadas desacopladas seguindo Dependency Inversion	`PASS ✅`
CP-02	Padrão CQRS com MediatR	Separação de comandos e consultas funcional	`PASS ✅`
CP-03	Pipeline Behaviors	Interceptação de requisições para validação e logs	`PASS ✅`
CP-04	Handlers Independentes	Execução isolada de casos de uso	`PASS ✅`
CP-05	Testes Unitários de Handlers	Cobertura de testes sobre regras de aplicação	`PASS ✅`