Home

PolicyDesk: aprenda backend com um sistema real

Bem-vindo à wiki do PolicyDesk, uma API REST em .NET 10 para gestão de seguros: segurados, apólices e o ciclo de vida de sinistros.

Esta wiki não é um manual de referência. Ela é uma série de artigos, cada um sobre um tema, escritos para que qualquer pessoa consiga trabalhar no projeto ou estudar aquele assunto, mesmo sem conhecer a tecnologia antes. Todo artigo segue o mesmo caminho:

1. O problema: por que aquilo existe.
2. O conceito, explicado do zero, com analogias.
3. Como aparece no PolicyDesk, com o código real.
4. Experimente: exercícios práticos.
5. Resumo e leituras para aprofundar.

---

Por onde começar

Escolha sua trilha

🧭 "Nunca vi o projeto e quero entender o que ele faz"

1. Entendendo o negócio: o que é um seguro, e as regras que o sistema protege.
2. Primeiros passos: coloque o sistema para rodar e faça seu primeiro fluxo completo.
3. Referência da API: como conversar com a API.

🛠️ "Vou trabalhar no código"

1. Primeiros passos
2. Arquitetura: onde fica cada coisa, e por quê.
3. Modelo de domínio: onde moram as regras de negócio.
4. Qualidade e convenções: as regras que o build confere.
5. Estratégia de testes: como testar cada camada.
6. Tutorial: nova funcionalidade: pratique, do teste ao endpoint.

📚 "Quero estudar engenharia de software com um exemplo real"

1. Arquitetura: Clean Architecture sem caixinhas abstratas.
2. Modelo de domínio: entidades ricas, máquinas de estado, validação.
3. Design patterns: 34 padrões, cada um como um mini-artigo.
4. Persistência e banco de dados: ORM, concorrência, upsert e migrations.
5. Tratamento de erros e Observabilidade.
6. CI/CD e deploy: do commit à produção.

🚨 "Preciso investigar um problema"

1. Observabilidade: como seguir uma requisição pelo traceId.
2. Tratamento de erros: o que cada resposta de erro significa.

---

Todos os artigos

Artigo	Do que trata	Você vai aprender
Entendendo o negócio	O domínio de seguros	Segurado, apólice, sinistro, as regras e os ciclos de vida
Primeiros passos	Rodar o projeto	Docker, configuração, fail fast, seu primeiro fluxo com curl
Arquitetura	A organização do código	Regra de dependência, os projetos, o caminho de uma requisição, injeção de dependência
Modelo de domínio	As regras no código	Modelo rico, máquina de estados, DateOnly, o relógio de negócio, validação de CPF e telefone
Persistência e banco de dados	Como os dados são guardados	EF Core, mapeamento, paginação, concorrência otimista, upsert, migrations
Referência da API	Todos os endpoints	HTTP, códigos de status, paginação, exemplos de cada endpoint
Tratamento de erros	Como a API falha	ProblemDetails, exceções de negócio, localização em português e inglês
Observabilidade	Enxergar o sistema por dentro	Logs, traces, métricas, OpenTelemetry, traceId
Design patterns	Os padrões usados	34 padrões, do Repository ao Test Data Builder
Estratégia de testes	Como o código é testado	Pirâmide de testes, dublês, Testcontainers, relógio controlado, cobertura
Qualidade e convenções	As regras do projeto	Analisadores, .editorconfig, nomes, segurança, Dockerfile
CI/CD e deploy	Do commit à produção	GitHub Actions, OIDC, Bicep, Azure App Service
Tutorial: nova funcionalidade	Prática guiada	TDD atravessando todas as camadas
Glossário	Os termos usados	Vocabulário de negócio e técnico, com links

---

O projeto em uma página

flowchart LR
    Client([Cliente HTTP]) -->|JSON| API[PolicyDesk.Api]
    API --> APP[PolicyDesk.Application<br/>casos de uso]
    APP --> DOM[PolicyDesk.Domain<br/>entidades e regras]
    API --> INF[PolicyDesk.Infrastructure<br/>EF Core]
    INF -->|implementa contratos de| DOM
    INF --> DB[(PostgreSQL)]
    API -. OTLP .-> DASH[Aspire Dashboard]
    GHA[GitHub Actions] -. deploy .-> AZ[Azure App Service F1]

Loading

Item	Valor
Plataforma	.NET 10, ASP.NET Core, C# 14
Banco de dados	PostgreSQL 17 (os testes usam o 16, via Testcontainers)
Acesso a dados	Entity Framework Core 10 + Npgsql
Estilo arquitetural	Clean Architecture com domínio rico
Contrato da API	JSON em português, listagens paginadas, datas DateOnly
Formato de erro	ProblemDetails (RFC 9457), mensagens em português (padrão) e inglês
Observabilidade	OpenTelemetry (logs, traces e métricas)
Testes	xUnit, Shouldly, Moq, Bogus, Testcontainers (mais de 460 testes)
CI/CD	GitHub Actions, CodeQL, Dependabot
Hospedagem	Azure App Service F1 + Azure Database for PostgreSQL (Bicep)
Licença	MIT

---

Como estudar com esta wiki

• Leia com o código aberto ao lado. Todo artigo aponta os arquivos reais; abra-os e compare.
• Faça os exercícios. Cada artigo termina com uma seção "Experimente" ou "Para praticar". É ali que o conhecimento fixa.
• Use o depurador. Coloque breakpoints e siga uma requisição pelo sistema; o artigo Arquitetura mostra o caminho.
• Quebre as coisas de propósito. Os testes vão avisar o que quebrou, e por quê.
• Consulte o Glossário sempre que um termo não estiver claro.