feat: Add GeographicRestrictionMiddleware (Sprint 1 Dia 1)

**Implementação**: Middleware de restrição geográfica para MVP piloto

**Arquivos Criados**:
- src/Shared/Middleware/GeographicRestrictionMiddleware.cs
- src/Shared/Configuration/GeographicRestrictionOptions.cs
- src/Bootstrapper/MeAjudaAi.ApiService/appsettings.Staging.json

**Features**:
✅ Construtor primário (C# 12)
✅ Bloqueia acesso baseado em cidade/estado
✅ HTTP 451 (Unavailable For Legal Reasons)
✅ Extração de localização via headers (X-User-Location, X-User-City, X-User-State)
✅ Fail-open quando não detecta localização (TODO: GeoIP obrigatório em Prod)
✅ Skip de health checks, swagger e _framework
✅ Logging estruturado

**Configuration**:
- Development: Enabled = false (permitir tudo)
- Staging: Enabled = true (apenas SP, RJ, MG)
- Production: Enabled = true (apenas cidades piloto)

**Cidades Piloto**: São Paulo, Rio de Janeiro, Belo Horizonte
**Estados Permitidos**: SP, RJ, MG

**Integration**:
- Registrado em ServiceCollectionExtensions
- Adicionado ANTES de UseRouting() no pipeline
- Options pattern com IOptions<GeographicRestrictionOptions>

**Roadmap Updated**:
- Sprint 0: ✅ CONCLUÍDO (21 Nov)
- Sprint 1: 🔄 DIA 1 (22 Nov) - Geographic Restriction
- Coverage baseline: 28.69% → Meta 75-80%

**Next Steps**:
- [ ] Unit tests (Dia 1 Afternoon)
- [ ] Integration tests (Dia 1 Afternoon)
- [ ] Documentação Swagger (Dia 2)
- [ ] GeoIP Service implementation (Sprint 2)

docs/roadmap.md

@@ -7,14 +7,15 @@ Este documento consolida o planejamento estratégico e tático da plataforma MeA
 ## 📊 Sumário Executivo
 
 **Projeto**: MeAjudaAi - Plataforma de Conexão entre Clientes e Prestadores de Serviços  
-**Status Geral**: Fase 1 ✅ | Fase 1.5 🔄 (Sprint 0) | MVP Target: 31/Março/2025  
-**Cobertura de Testes**: 40.51% → Meta 80%+  
+**Status Geral**: Fase 1 ✅ | Sprint 0 ✅ | Sprint 1 🔄 (Dia 1) | MVP Target: 31/Março/2025  
+**Cobertura de Testes**: 28.69% → Meta 75-80% (Sprint 1)  
 **Stack**: .NET 10 LTS + Aspire 13 + PostgreSQL + Blazor WASM + MAUI Hybrid
 
 ### Marcos Principais
 - ✅ **Janeiro 2025**: Fase 1 concluída - 6 módulos core implementados
-- 🔄 **Jan 20 - Feb 2**: Sprint 0 - Migration .NET 10 + Aspire 13
-- ⏳ **Fevereiro 2025**: Sprints 1-2 - Integração + Testes + Hardening
+- ✅ **Jan 20 - 21 Nov**: Sprint 0 - Migration .NET 10 + Aspire 13 (CONCLUÍDO)
+- 🔄 **22 Nov - 2 Dez**: Sprint 1 - Geographic Restriction + Module Integration + Test Coverage (EM ANDAMENTO)
+- ⏳ **Dezembro 2025**: Sprint 2 - Frontend Blazor (Web)
 - ⏳ **Fevereiro-Março 2025**: Sprints 3-5 - Frontend Blazor (Web + Mobile)
 - 🎯 **31 Março 2025**: MVP Launch (Admin Portal + Customer App)
 - 🔮 **Abril 2025+**: Fase 3 - Reviews, Assinaturas, Agendamentos
@@ -27,11 +28,11 @@ Este documento consolida o planejamento estratégico e tático da plataforma MeA
 Todos os 6 módulos core implementados, testados e integrados:
 - Users • Providers • Documents • Search & Discovery • Locations • ServiceCatalogs
 
-**🔄 Fase 1.5: EM ANDAMENTO** (Janeiro-Fevereiro 2025)  
+**🔄 Fase 1.5: EM ANDAMENTO** (Novembro-Dezembro 2025)  
 Fundação técnica para escalabilidade e produção:
-- Migration .NET 10 + Aspire 13 (Sprint 0)
-- Integração de módulos + Restrições geográficas (Sprint 1)
-- Test coverage 80%+ + Health checks + Data seeding (Sprint 2)
+- ✅ Migration .NET 10 + Aspire 13 (Sprint 0 - CONCLUÍDO 21 Nov)
+- 🔄 Geographic Restriction + Module Integration + Test Coverage 75-80% (Sprint 1 - DIA 1)
+- ⏳ Frontend Blazor Admin Portal (Sprint 2)
 
 **⏳ Fase 2: PLANEJADO** (Fevereiro-Março 2025)  
 Frontend Blazor WASM + MAUI Hybrid:
@@ -59,9 +60,9 @@ A implementação segue os princípios arquiteturais definidos em `architecture.
 
 | Sprint | Duração | Período | Objetivo | Status |
 |--------|---------|---------|----------|--------|
-| **Sprint 0** | 1-2 semanas | Jan 20 - Feb 2 | Migration .NET 10 + Aspire 13 | 🔄 EM ANDAMENTO |
-| **Sprint 1** | 1 semana | Feb 3 - Feb 9 | Integração de Módulos + Restrição Geográfica | ⏳ Planejado |
-| **Sprint 2** | 1 semana | Feb 10 - Feb 16 | Test Coverage 80% + Hardening | ⏳ Planejado |
+| **Sprint 0** | 4 semanas | Jan 20 - 21 Nov | Migration .NET 10 + Aspire 13 | ✅ CONCLUÍDO |
+| **Sprint 1** | 10 dias | 22 Nov - 2 Dez | Geographic Restriction + Module Integration + Coverage 75-80% | 🔄 DIA 1 |
+| **Sprint 2** | 2 semanas | 3 Dez - 16 Dez | Blazor Admin Portal (Web) | ⏳ Planejado |
 | **Sprint 3** | 2 semanas | Feb 17 - Mar 2 | Blazor Admin Portal (Web) | ⏳ Planejado |
 | **Sprint 4** | 3 semanas | Mar 3 - Mar 23 | Blazor Customer App (Web + Mobile) | ⏳ Planejado |
 | **Sprint 5** | 1 semana | Mar 24 - Mar 30 | Polishing & Hardening (MVP Final) | ⏳ Planejado |
@@ -88,12 +89,13 @@ Estabelecer as capacidades essenciais da plataforma: registro multi-etapas de pr
 6. ✅ **ServiceCatalogs** - Catálogo hierárquico de serviços
 
 **Conquistas:**
-- 40.51% test coverage (296 testes passando)
+- 28.69% test coverage (93/100 E2E passing, 296 unit tests)
+- ⚠️ Coverage caiu após migration (packages.lock.json + generated code)
 - APIs públicas (IModuleApi) implementadas para todos módulos
 - Integration events funcionais entre módulos
 - Health checks configurados
-- CI/CD pipeline completo no Azure DevOps
-- Documentação arquitetural completa
+- CI/CD pipeline completo no GitHub Actions
+- Documentação arquitetural completa + skipped tests tracker
 
 ### 1.1. ✅ Módulo Users (Concluído)
 **Status**: Implementado e em produção
@@ -710,21 +712,55 @@ gantt
 
 ---
 
-### 📅 Sprint 1: Integração de Módulos + Restrição Geográfica (1 semana)
-
-**Status**: ⏳ PLANEJADO
-
-**Pré-Requisitos (decidir no Sprint 0)**:
-- ✅ **Contratos de Módulos**: Finalizar interfaces IModuleApi para cada módulo
-- ✅ **Cache de Cidades**: Implementar caching da lista AllowedCities para evitar impacto de performance no SearchModule
-- ✅ **Background Workers**: Definir arquitetura (threading, retry logic, poison queue handling) para integration events
-
-**Objetivos**:
-- Implementar regras de negócio reais usando IModuleApi entre módulos
-- Adicionar restrição geográfica (operação apenas em cidades piloto)
-- Melhorar validações e business rules cross-module
-
-**Tarefas**:
+### 📅 Sprint 1: Geographic Restriction + Module Integration + Test Coverage (10 dias)
+
+**Status**: 🔄 DIA 1 - EM ANDAMENTO (22 Nov 2025)  
+**Branch Atual**: `feature/geographic-restriction`  
+**Documentação**: [docs/sprint-1-checklist.md](./sprint-1-checklist.md)
+
+**Contexto**:
+- ✅ Sprint 0 concluído: Migration .NET 10 + Aspire 13 merged (21 Nov)
+- ⚠️ Coverage caiu: 40.51% → 28.69% (packages.lock.json + generated code)
+- 🎯 Meta Sprint 1: 28.69% → 75-80% coverage
+
+**Pré-Requisitos** (✅ DECIDIDO no Sprint 0):
+- ✅ **Contratos de Módulos**: Interfaces IModuleApi definidas para todos módulos
+- ✅ **Cache de Cidades**: Implementar caching da lista AllowedCities para evitar impacto de performance
+- ✅ **Background Workers**: Arquitetura definida (threading, retry logic, poison queue handling)
+- ✅ **8 E2E Tests Skipped**: Documentados em [skipped-tests-tracker.md](./skipped-tests-tracker.md)
+
+**Objetivos Expandidos**:
+- ✅ Implementar middleware de restrição geográfica (compliance legal)
+- ✅ Implementar 4 Module APIs usando IModuleApi entre módulos
+- ✅ Reativar 8 testes E2E skipped (auth refactor + race condition fixes)
+- 🆕 Aumentar coverage: 28.69% → 75-80% (165+ novos unit tests)
+
+**Estrutura (3 Branches)**:
+
+#### Branch 1: `feature/geographic-restriction` (Dias 1-2) 🔄 DIA 1
+- [ ] GeographicRestrictionMiddleware (validação cidade/estado)
+- [ ] GeographicRestrictionOptions (configuration)
+- [ ] Feature toggle (Development: disabled, Production: enabled)
+- [ ] Unit tests + Integration tests
+- [ ] Documentação + Swagger examples
+- **Target**: 28.69% → 30% coverage
+
+#### Branch 2: `feature/module-integration` (Dias 3-7)
+- [ ] **Dia 3**: Refactor ConfigurableTestAuthenticationHandler (reativa 5 AUTH tests)
+- [ ] **Dia 3**: Fix race conditions (reativa 3 INFRA tests)
+- [ ] **Dia 4**: IDocumentsModuleApi implementation
+- [ ] **Dia 5**: IServiceCatalogsModuleApi + ISearchModuleApi
+- [ ] **Dia 6**: ILocationModuleApi + Integration events
+- [ ] **Dia 7**: Documentação + Code review
+- **Target**: 30% → 35% coverage, 93/100 → 98/100 E2E tests
+
+#### 🆕 Branch 3: `test/increase-coverage` (Dias 8-10)
+- [ ] **Dia 8**: Shared.Tests (ValueObjects + Extensions + Results) → +7% coverage
+- [ ] **Dia 9**: Domain Entities (Provider + User + ServiceCategory) → +19% coverage
+- [ ] **Dia 10**: Critical Handlers (Create + Update + Search) → +18% coverage
+- **Target**: 35% → 75-80% coverage (+165 unit tests)
+
+**Tarefas Detalhadas**:
 
 #### 1. Integração Providers ↔ Documents
 - [ ] Providers: Validar `HasVerifiedDocuments` antes de aprovar prestador

src/Bootstrapper/MeAjudaAi.ApiService/Extensions/ServiceCollectionExtensions.cs

@@ -3,6 +3,8 @@
 using MeAjudaAi.ApiService.Middlewares;
 using MeAjudaAi.ApiService.Options;
 using MeAjudaAi.Shared.Authorization.Middleware;
+using MeAjudaAi.Shared.Configuration;
+using MeAjudaAi.Shared.Middleware;
 using Microsoft.AspNetCore.Authentication;
 using Microsoft.Extensions.Options;
 
@@ -54,6 +56,10 @@ public static IServiceCollection AddApiServices(
         services.AddCorsPolicy(configuration, environment);
         services.AddMemoryCache();
 
+        // Configurar Geographic Restriction
+        services.Configure<GeographicRestrictionOptions>(
+            configuration.GetSection("GeographicRestriction"));
+
         // Adiciona autenticação segura baseada no ambiente
         // Configuração de autenticação baseada no ambiente
         if (!isTestEnvironment)
@@ -91,6 +97,9 @@ public static IApplicationBuilder UseApiServices(
         app.UseResponseCompression();
         app.UseResponseCaching();
 
+        // Geographic Restriction ANTES de qualquer roteamento
+        app.UseMiddleware<GeographicRestrictionMiddleware>();
+
         // Middleware de arquivos estáticos com cache
         app.UseMiddleware<StaticFilesMiddleware>();
         app.UseStaticFiles();

src/Shared/Configuration/GeographicRestrictionOptions.cs

@@ -0,0 +1,34 @@
+namespace MeAjudaAi.Shared.Configuration;
+
+/// <summary>
+/// Opções de configuração para restrição geográfica.
+/// Permite limitar acesso da plataforma a cidades/estados específicos (MVP piloto).
+/// </summary>
+public class GeographicRestrictionOptions
+{
+    /// <summary>
+    /// Habilita/desabilita a restrição geográfica.
+    /// Development: false (permitir tudo)
+    /// Production: true (apenas cidades piloto)
+    /// </summary>
+    public bool Enabled { get; set; }
+
+    /// <summary>
+    /// Lista de estados permitidos (siglas de 2 letras, ex: "SP", "RJ").
+    /// Se vazio, validação de estado é ignorada.
+    /// </summary>
+    public List<string> AllowedStates { get; set; } = [];
+
+    /// <summary>
+    /// Lista de cidades permitidas (nomes completos, ex: "São Paulo").
+    /// Validação case-insensitive.
+    /// </summary>
+    public List<string> AllowedCities { get; set; } = [];
+
+    /// <summary>
+    /// Mensagem exibida quando acesso é bloqueado.
+    /// Placeholder {allowedRegions} será substituído pelas regiões permitidas.
+    /// </summary>
+    public string BlockedMessage { get; set; } =
+        "Serviço indisponível na sua região. Disponível apenas em: {allowedRegions}";
+}

src/Shared/Middleware/GeographicRestrictionMiddleware.cs

@@ -0,0 +1,150 @@
+using Microsoft.AspNetCore.Http;
+using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Options;
+using System.Text.Json;
+using MeAjudaAi.Shared.Configuration;
+
+namespace MeAjudaAi.Shared.Middleware;
+
+/// <summary>
+/// Middleware para restringir acesso baseado em localização geográfica.
+/// Bloqueia requisições de cidades/estados não permitidos (compliance legal).
+/// </summary>
+public class GeographicRestrictionMiddleware(
+    RequestDelegate next,
+    ILogger<GeographicRestrictionMiddleware> logger,
+    IOptions<GeographicRestrictionOptions> options)
+{
+    private readonly GeographicRestrictionOptions _options = options.Value;
+
+    public async Task InvokeAsync(HttpContext context)
+    {
+        // Skip se desabilitado (ex: Development)
+        if (!_options.Enabled)
+        {
+            await next(context);
+            return;
+        }
+
+        // Skip health checks e endpoints internos
+        var path = context.Request.Path.Value ?? string.Empty;
+        if (path.StartsWith("/health", StringComparison.OrdinalIgnoreCase) ||
+            path.StartsWith("/swagger", StringComparison.OrdinalIgnoreCase) ||
+            path.StartsWith("/_framework", StringComparison.OrdinalIgnoreCase))
+        {
+            await next(context);
+            return;
+        }
+
+        // Extrair localização do header X-User-Location ou IP
+        var (city, state) = ExtractLocation(context);
+
+        // Validar se cidade/estado está permitido
+        if (!IsLocationAllowed(city, state))
+        {
+            logger.LogWarning(
+                "Geographic restriction: Request blocked from {City}/{State}. IP: {IpAddress}",
+                city ?? "Unknown",
+                state ?? "Unknown",
+                context.Connection.RemoteIpAddress);
+
+            context.Response.StatusCode = 451; // Unavailable For Legal Reasons
+            context.Response.ContentType = "application/json";
+
+            var allowedRegions = GetAllowedRegionsDescription();
+            var errorResponse = new
+            {
+                error = "geographic_restriction",
+                message = string.Format(_options.BlockedMessage, allowedRegions),
+                allowedCities = _options.AllowedCities,
+                allowedStates = _options.AllowedStates,
+                yourLocation = new { city, state }
+            };
+
+            await context.Response.WriteAsync(
+                JsonSerializer.Serialize(errorResponse, new JsonSerializerOptions
+                {
+                    PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
+                    WriteIndented = true
+                }));
+
+            return;
+        }
+
+        // Localização permitida - continuar pipeline
+        await next(context);
+    }
+
+    private (string? City, string? State) ExtractLocation(HttpContext context)
+    {
+        // Prioridade 1: Header X-User-Location (formato: "City|State")
+        if (context.Request.Headers.TryGetValue("X-User-Location", out var locationHeader))
+        {
+            var parts = locationHeader.ToString().Split('|');
+            if (parts.Length == 2)
+            {
+                return (parts[0].Trim(), parts[1].Trim());
+            }
+        }
+
+        // Prioridade 2: Header X-User-City e X-User-State (separados)
+        var city = context.Request.Headers.TryGetValue("X-User-City", out var cityHeader)
+            ? cityHeader.ToString().Trim()
+            : null;
+
+        var state = context.Request.Headers.TryGetValue("X-User-State", out var stateHeader)
+            ? stateHeader.ToString().Trim()
+            : null;
+
+        if (!string.IsNullOrEmpty(city) || !string.IsNullOrEmpty(state))
+        {
+            return (city, state);
+        }
+
+        // TODO Sprint 2: Implementar GeoIP lookup baseado em IP
+        // var ip = context.Connection.RemoteIpAddress;
+        // return await _geoIpService.GetLocationFromIpAsync(ip);
+
+        return (null, null);
+    }
+
+    private bool IsLocationAllowed(string? city, string? state)
+    {
+        // Se não conseguiu detectar localização, permitir (fail-open)
+        // Produção deve ter GeoIP obrigatório
+        if (string.IsNullOrEmpty(city) && string.IsNullOrEmpty(state))
+        {
+            logger.LogWarning("Geographic restriction: Could not determine user location, allowing access (fail-open)");
+            return true;
+        }
+
+        // Validar cidade (case-insensitive)
+        if (!string.IsNullOrEmpty(city) &&
+            _options.AllowedCities.Any(c => c.Equals(city, StringComparison.OrdinalIgnoreCase)))
+        {
+            return true;
+        }
+
+        // Validar estado (case-insensitive, sigla de 2 letras)
+        if (!string.IsNullOrEmpty(state) &&
+            _options.AllowedStates.Any(s => s.Equals(state, StringComparison.OrdinalIgnoreCase)))
+        {
+            return true;
+        }
+
+        return false;
+    }
+
+    private string GetAllowedRegionsDescription()
+    {
+        var cities = _options.AllowedCities.Any()
+            ? string.Join(", ", _options.AllowedCities)
+            : "N/A";
+
+        var states = _options.AllowedStates.Any()
+            ? string.Join(", ", _options.AllowedStates)
+            : "N/A";
+
+        return $"Cidades: {cities} | Estados: {states}";
+    }
+}