Sprint 4: Health Checks + Data Seeding

.github/issue-template/efcore-naming-conventions-stable-monitoring.md

@@ -102,7 +102,7 @@ nuget list EFCore.NamingConventions -PreRelease
 1. Atualizar pacote via Dependabot PR
 2. Executar suite completa de testes
 3. Validar migrations existentes
-4. Testar em staging antes de production
+4. Testar localmente antes de production
 
 ## 📝 Notas Adicionais
 

.github/issue-template/npgsql-10-stable-monitoring.md

@@ -50,7 +50,7 @@ Quando Npgsql 10.0.0 stable for lançado:
 - [ ] Executar: `dotnet build`
 - [ ] Executar: `dotnet test`
 - [ ] Executar: `dotnet test --filter "Category=HangfireIntegration"`
-- [ ] Validar em staging
+- [ ] Validar localmente
 - [ ] Atualizar documentação: remover TODOs sobre Npgsql
 - [ ] Fechar Issue #42
 

Directory.Packages.props

@@ -164,6 +164,12 @@
     <PackageVersion Include="Rebus.AzureServiceBus" Version="10.5.1" />
     <PackageVersion Include="Rebus.RabbitMq" Version="10.1.0" />
     <PackageVersion Include="Rebus.ServiceProvider" Version="10.7.0" />
+    <!-- Health Checks -->
+    <PackageVersion Include="AspNetCore.HealthChecks.UI" Version="8.0.2" />
+    <PackageVersion Include="AspNetCore.HealthChecks.UI.Client" Version="8.0.2" />
+    <PackageVersion Include="AspNetCore.HealthChecks.UI.InMemory.Storage" Version="8.0.2" />
+    <PackageVersion Include="AspNetCore.HealthChecks.Npgsql" Version="9.0.0" />
+    <PackageVersion Include="AspNetCore.HealthChecks.Redis" Version="8.0.1" />
     <!-- Background Jobs -->
     <PackageVersion Include="Hangfire.Core" Version="1.8.22" />
     <PackageVersion Include="Hangfire.AspNetCore" Version="1.8.22" />

README.md

@@ -2,7 +2,7 @@
 
 Uma plataforma abrangente de serviços construída com .NET Aspire, projetada para conectar prestadores de serviços com clientes usando arquitetura monólito modular.
 
-<!-- Last updated: October 2, 2025 - Workflow syntax fixes applied -->
+<!-- Last updated: December 14, 2025 - Sprint 4 Health Checks + Data Seeding -->
 
 ## 🎯 Visão Geral
 
@@ -67,7 +67,6 @@ O projeto foi organizado para facilitar navegação e manutenção:
 ```
 📦 MeAjudaAi/
 ├── 📁 api/              # Especificações de API (OpenAPI)
-├── 📁 automation/       # Scripts de automação CI/CD
 ├── 📁 build/           # Scripts de build e Makefile
 ├── 📁 config/          # Configurações de ferramentas
 │   ├── .editorconfig  # Estilo de código
@@ -83,12 +82,15 @@ O projeto foi organizado para facilitar navegação e manutenção:
 │   ├── modules/          # Documentação por módulo
 │   └── testing/          # Guias de testes
 ├── 📁 infrastructure/  # IaC e configurações de infraestrutura
+│   ├── automation/     # Scripts de setup CI/CD
+│   ├── compose/        # Docker Compose configs
+│   ├── database/       # Database init scripts + seeds
+│   └── keycloak/       # Keycloak configuration
 ├── 📁 scripts/         # Scripts de desenvolvimento
 ├── 📁 src/             # Código fonte da aplicação
 ├── 📁 tests/           # Testes automatizados
 └── 📁 tools/           # Ferramentas de desenvolvimento
-    ├── MigrationTool/       # CLI para migrações de banco
-    └── api-collections/     # Gerador de coleções Postman
+    └── api-collections/     # Gerador de coleções Bruno/Postman
 ```
 
 ### Diretórios Principais
@@ -98,11 +100,10 @@ O projeto foi organizado para facilitar navegação e manutenção:
 | `src/` | Código fonte da aplicação | Módulos, APIs, domínios |
 | `tests/` | Testes unitários e integração | xUnit v3, testes por módulo |
 | `docs/` | Documentação técnica | Arquitetura, guias, ADRs |
-| `infrastructure/` | Infraestrutura como código | Bicep, Docker, Kubernetes |
+| `infrastructure/` | Infraestrutura como código | Bicep, Docker, database, CI/CD automation |
 | `scripts/` | Scripts de desenvolvimento | Exportar API, testes, deploy |
 | `build/` | Build e automação | Makefile, scripts de CI |
 | `config/` | Configurações de ferramentas | Linting, segurança, cobertura |
-| `automation/` | Setup de CI/CD | Scripts de configuração |
 
 ## 🚀 Início Rápido
 

automation/README.md

@@ -22,7 +22,7 @@ Configures basic continuous integration:
 ### Full CI/CD Setup (`setup-cicd.ps1`)
 Configures complete continuous integration and deployment:
 - Everything from CI-only setup
-- Automated deployment to staging/production
+- Automated deployment to production
 - Infrastructure provisioning
 - Release management workflows
 

docs/api-automation.md

@@ -139,7 +139,7 @@ cd tools/api-collections
 - ✅ Aguarda API ficar pronta
 - ✅ Gera `api-spec.json`
 - ✅ Gera Postman Collections
-- ✅ Cria Environments (dev/staging/prod)
+- ✅ Cria Environments (dev/prod)
 - ✅ Para a API
 
 ### Opção 2: Node.js apenas (só spec + collections)
@@ -158,7 +158,7 @@ node generate-postman-collections.js
 **Vantagens:**
 - ✅ Gera api-spec.json
 - ✅ Gera Postman Collections
-- ✅ Cria environments (dev/staging/prod)
+- ✅ Cria environments (dev/prod)
 - ✅ Testes automáticos incluídos
 
 ## 🔧 Configuração Inicial

docs/api-reference.md

@@ -8,7 +8,7 @@ A API MeAjudaAi segue os padrões REST e está documentada usando OpenAPI 3.0. T
 
 - **Arquivo versionado**: `api/api-spec.json` (na raiz do repositório)
 - **Swagger UI (Desenvolvimento)**: `http://localhost:5001/swagger`
-- **Swagger UI (Staging)**: `https://meajudaai-staging.azurewebsites.net/swagger`
+
 - **Download runtime**: `/swagger/v1/swagger.json`
 
 ## Endpoints Principais
@@ -127,7 +127,7 @@ X-Correlation-ID: <uuid>  # Opcional mas recomendado para rastreamento
 ## Rate Limiting
 
 - **Desenvolvimento**: Sem limite
-- **Staging**: 100 req/min por IP
+
 - **Production**: 60 req/min por usuário autenticado
 
 Headers de resposta:

docs/architecture.md

@@ -2153,7 +2153,7 @@ npm run validate
 src/Shared/API.Collections/Generated/
 ├── MeAjudaAi-API-Collection.json           # Collection principal
 ├── MeAjudaAi-development-Environment.json  # Ambiente desenvolvimento
-├── MeAjudaAi-staging-Environment.json      # Ambiente staging
+
 ├── MeAjudaAi-production-Environment.json   # Ambiente produção
 └── README.md                               # Instruções de uso
 ```
@@ -2171,7 +2171,7 @@ options.OperationFilter<ApiVersionOperationFilter>();
 
 - **🔒 Segurança JWT**: Configuração automática de Bearer tokens
 - **📊 Schemas Reutilizáveis**: Componentes comuns (paginação, erros)
-- **🌍 Multi-ambiente**: URLs para dev/staging/production
+- **🌍 Multi-ambiente**: URLs para dev/production
 
 ### **Boas Práticas para Collections**
 
@@ -2211,7 +2211,7 @@ options.OperationFilter<ApiVersionOperationFilter>();
 - ✅ **Funciona offline** (não precisa rodar aplicação)
 - ✅ **Health checks incluídos** (/health, /health/ready, /health/live)  
 - ✅ **Schemas com exemplos** realistas
-- ✅ **Múltiplos ambientes** (dev, staging, production)
+- ✅ **Múltiplos ambientes** (dev, production)
 - ⚠️ **Arquivo não versionado** (incluído no .gitignore)
 
 #### **Importar em Clientes de API**

docs/ci-cd.md

@@ -1335,7 +1335,7 @@ POSTGRES_DB: ${{ secrets.POSTGRES_DB || 'meajudaai_test' }}
 - [ ] **Matrix strategy**: Testar em Ubuntu + Windows
 - [ ] **Reusable workflows**: Extrair jobs comuns
 - [ ] **Composite actions**: Consolidar setup steps
-- [ ] **GitHub Environments**: Separar dev/staging/prod
+- [ ] **GitHub Environments**: Separar dev/prod
 
 ### Observabilidade
 - [ ] **Badges no README**: Coverage, build status, dependencies

docs/database.md

@@ -370,7 +370,7 @@ else
 |---|---|---|
 | **Desenvolvimento** | `EnableSchemaIsolation: false` | Usa usuário admin padrão |
 | **Teste** | `EnableSchemaIsolation: false` | TestContainers com um único usuário |
-| **Staging** | `EnableSchemaIsolation: true` | Usuário `users_role` dedicado |
+
 | **Produção** | `EnableSchemaIsolation: true` | Máxima segurança para Users |
 
 ### 🛡️ Estrutura de Segurança

docs/deployment-environments.md

@@ -32,11 +32,11 @@ Este documento descreve os diferentes ambientes de deploy disponíveis para a pl
 
 **ANTES de fazer deploy em QUALQUER ambiente**, garanta que TODAS as validações críticas de compatibilidade passem.
 
-Para procedimentos detalhados de validação de compatibilidade Hangfire + Npgsql 10.x, consulte a documentação de infraestrutura e execute testes em staging.
+Para procedimentos detalhados de validação de compatibilidade Hangfire + Npgsql 10.x, consulte a documentação de infraestrutura e execute testes localmente.
 
 **Checklist Rápido**:
-- [ ] ⚠️ **CRÍTICO**: Smoke tests em staging com execução de jobs Hangfire (Npgsql 10.x NÃO VALIDADO)
-- [ ] Verificação manual do dashboard Hangfire em staging
+- [ ] ⚠️ **CRÍTICO**: Smoke tests locais com execução de jobs Hangfire (Npgsql 10.x NÃO VALIDADO)
+- [ ] Verificação manual do dashboard Hangfire localmente
 - [ ] Monitoramento de health check configurado (HealthChecks.Hangfire)
 - [ ] Monitoramento configurado (alertas, dashboards)
 - [ ] Procedimento de rollback testado

docs/development.md

@@ -459,7 +459,7 @@ public class TestAuthenticationHandler : AuthenticationHandler<TestAuthenticatio
       "SkipPermissionValidation": false,
       "EnableCodeCoverage": true
     },
-    "Staging": {
+    "Production": {
       "UseInMemoryDatabase": false,
       "UseTestAuthentication": false,
       "SkipPermissionValidation": false

docs/future-external-services.md

@@ -0,0 +1,184 @@
+# External Services - Roadmap de Integração
+
+Este documento lista serviços externos que serão integrados no futuro. Não implemente health checks para estes serviços agora - documente apenas quando a integração for desenvolvida.
+
+## 📋 Status Atual
+
+### ✅ Implementados (com Health Checks)
+
+1. **Keycloak**
+   - **Propósito**: Autenticação e autorização (OAuth2/OIDC)
+   - **Health Check**: `ExternalServicesHealthCheck` - verifica `/realms/meajudaai`
+   - **Tags**: `ready`, `external`
+   - **Documentação**: [docs/authentication-and-authorization.md](authentication-and-authorization.md)
+
+2. **IBGE API**
+   - **Propósito**: Validação de localização geográfica (estados, municípios)
+   - **Health Check**: `ExternalServicesHealthCheck` - verifica `/api/v1/localidades/estados/MG`
+   - **Tags**: `ready`, `external`
+   - **Endpoint**: `https://servicodados.ibge.gov.br/api/v1/localidades`
+   - **Módulo**: `Locations`
+   - **Cliente**: `IbgeClient.cs`
+
+3. **Redis**
+   - **Propósito**: Cache distribuído
+   - **Health Check**: `AddRedis()` - health check nativo do AspNetCore.HealthChecks.Redis
+   - **Tags**: `ready`, `cache`
+   - **Documentação**: Configurado via Aspire
+
+## 🔮 Serviços Futuros (NÃO Implementados)
+
+### Sprint 5-6: OCR e Validação de Documentos
+
+#### Azure Document Intelligence (OCR)
+- **Propósito**: Extração de texto de documentos escaneados/fotos
+- **Quando Implementar**: Quando módulo Documents estiver processando uploads de imagens
+- **Health Check Futuro**: 
+  - Endpoint: `POST /formrecognizer/documentModels/{modelId}:analyze`
+  - Verificar autenticação e quota disponível
+  - Tags: `ready`, `external`, `ocr`
+- **Pacote**: `Azure.AI.DocumentIntelligence 1.0.0` (já instalado)
+- **Configuração Necessária**:
+  - `Azure:DocumentIntelligence:Endpoint`
+  - `Azure:DocumentIntelligence:ApiKey`
+- **Critérios para Health Check**:
+  - [ ] Módulo Documents aceita uploads de imagens
+  - [ ] OCR implementado em `DocumentVerificationJob.cs`
+  - [ ] Azure Document Intelligence configurado em ambiente
+
+#### Azure Blob Storage
+- **Propósito**: Armazenamento de documentos e fotos
+- **Quando Implementar**: Quando uploads de documentos forem habilitados
+- **Health Check Futuro**:
+  - Verificar conectividade com container
+  - Validar permissões de leitura/escrita
+  - Tags: `ready`, `external`, `storage`
+- **Pacote**: `Azure.Storage.Blobs 12.26.0` (já instalado)
+- **Configuração Necessária**:
+  - `Azure:Storage:ConnectionString`
+  - `Azure:Storage:ContainerName`
+
+### Sprint 7-8: Validação de Prestadores
+
+#### API Receita Federal (CNPJ/CPF)
+- **Propósito**: Validação de documentos de prestadores (background checks)
+- **Quando Implementar**: Quando verificação de prestadores for automatizada
+- **Health Check Futuro**:
+  - Endpoint público ou API privada (a definir)
+  - Validar quota e rate limits
+  - Tags: `ready`, `external`, `validation`
+- **Observações**:
+  - API pública da Receita pode ter rate limits agressivos
+  - Considerar alternativas: Serviços terceiros (ex: BrasilAPI, ReceitaWS)
+  - Implementar cache agressivo para consultas de CNPJ/CPF
+
+#### BrasilAPI (Alternativa Receita Federal)
+- **Propósito**: Validação de CNPJ, CEP, bancos
+- **Quando Implementar**: Como alternativa à API da Receita
+- **Health Check Futuro**:
+  - Endpoint: `https://brasilapi.com.br/api/status`
+  - Tags: `ready`, `external`, `validation`
+- **Vantagens**:
+  - API pública gratuita
+  - Rate limits mais generosos
+  - Múltiplos endpoints úteis (CNPJ, CEP, bancos)
+
+### Sprint 9-10: Pagamentos (Futuro Distante)
+
+#### Gateway de Pagamento (Ex: PagSeguro, Mercado Pago)
+- **Propósito**: Processar doações e pagamentos (se aplicável)
+- **Quando Implementar**: Quando modelo de monetização for definido
+- **Health Check Futuro**:
+  - Verificar autenticação com gateway
+  - Validar saldo e permissões
+  - Tags: `ready`, `external`, `payment`
+- **Observações**:
+  - Aguardar decisão de modelo de negócio
+  - Pode nunca ser implementado se plataforma for 100% gratuita
+
+### Sprint 11+: Notificações
+
+#### SendGrid / AWS SES (Email)
+- **Propósito**: Envio de emails transacionais (confirmação, notificações)
+- **Quando Implementar**: Quando notificações por email forem necessárias
+- **Health Check Futuro**:
+  - Verificar autenticação e quota
+  - Tags: `ready`, `external`, `email`
+
+#### Twilio / AWS SNS (SMS)
+- **Propósito**: Envio de SMS para notificações críticas
+- **Quando Implementar**: Quando notificações por SMS forem necessárias
+- **Health Check Futuro**:
+  - Verificar autenticação e saldo
+  - Tags: `ready`, `external`, `sms`
+
+## 🎯 Decisões de Implementação
+
+### Quando Adicionar Health Check para Novo Serviço Externo
+
+✅ **ADICIONE Health Check se:**
+- Serviço é crítico para funcionalidade principal da aplicação
+- Falha do serviço impacta experiência do usuário
+- Serviço é usado de forma síncrona (ex: validação em tempo real)
+- Serviço está configurado em ambiente de produção
+
+❌ **NÃO ADICIONE Health Check se:**
+- Serviço é opcional ou experimental
+- Serviço ainda não está configurado/implementado
+- Serviço é usado apenas em jobs assíncronos (Hangfire já monitora)
+- Falha do serviço não impacta disponibilidade da aplicação
+
+### Template para Implementação Futura
+
+Quando implementar health check para novo serviço:
+
+```csharp
+// Em ExternalServicesHealthCheck.cs
+
+// Verificar [Nome do Serviço]
+try
+{
+    var serviceUrl = configuration["[ServiceConfig:Url]"];
+    if (!string.IsNullOrEmpty(serviceUrl))
+    {
+        var stopwatch = System.Diagnostics.Stopwatch.StartNew();
+        using var response = await httpClient.GetAsync($"{serviceUrl}/[health-endpoint]", cancellationToken);
+        stopwatch.Stop();
+
+        results["[service_name]"] = new
+        {
+            status = response.IsSuccessStatusCode ? "healthy" : "unhealthy",
+            response_time_ms = stopwatch.ElapsedMilliseconds,
+            endpoint = "[health-endpoint]"
+        };
+
+        if (!response.IsSuccessStatusCode)
+            allHealthy = false;
+    }
+}
+catch (Exception ex)
+{
+    results["[service_name]"] = new { status = "unhealthy", error = ex.Message };
+    allHealthy = false;
+}
+```
+
+### Checklist para Nova Integração
+
+Antes de adicionar health check para novo serviço externo:
+
+- [ ] Serviço está implementado e funcional no código
+- [ ] Configuração do serviço existe em `appsettings.json`
+- [ ] Cliente HTTP ou SDK está configurado no DI container
+- [ ] Serviço está disponível em ambiente de desenvolvimento
+- [ ] Endpoint de health check do serviço foi identificado
+- [ ] Timeout apropriado está configurado (padrão: 5s)
+- [ ] Testes unitários foram criados para o health check
+- [ ] Documentação foi atualizada neste arquivo
+
+## 📚 Referências
+
+- [ASP.NET Core Health Checks](https://learn.microsoft.com/en-us/aspnet/core/host-and-deploy/health-checks)
+- [AspNetCore.Diagnostics.HealthChecks](https://github.com/Xabaril/AspNetCore.Diagnostics.HealthChecks)
+- [Health UI Dashboard](http://localhost:5193/health-ui) (Development)
+- [Roadmap Geral](roadmap.md)

docs/infrastructure.md

@@ -182,7 +182,7 @@ O arquivo `infrastructure/keycloak/realms/meajudaai-realm.json` contém:
 
 #### Usuários de Teste (Desenvolvimento Local)
 
-> ⚠️ **AVISO DE SEGURANÇA**: As credenciais abaixo são EXCLUSIVAMENTE para desenvolvimento local. NUNCA utilize essas credenciais em ambientes compartilhados, staging ou produção.
+> ⚠️ **AVISO DE SEGURANÇA**: As credenciais abaixo são EXCLUSIVAMENTE para desenvolvimento local. NUNCA utilize essas credenciais em produção.
 
 - **admin** / admin123 (admin, super-admin) - **DEV ONLY**
 - **customer1** / customer123 (customer) - **DEV ONLY**

docs/messaging.md

@@ -67,7 +67,7 @@ public class EnvironmentBasedMessageBusFactory : IMessageBusFactory
         }
         else
         {
-            // STAGING/OUTROS: NoOp por segurança
+            // OUTROS: NoOp por segurança
             return _serviceProvider.GetRequiredService<NoOpMessageBus>();
         }
     }