Skip to content

Áreas por rota

1. Introdução

Nesta opção, mantemos a mesma aplicação (um único projeto e, normalmente, um único deploy), porém a API é organizada em áreas por rota, separando claramente o acesso por público:

  • /cliente/*
  • /corretor/*
  • /superapp/*
  • /partners/*
  • /webhooks/*
  • /ia/*

A ideia é reduzir o risco de “mistura” entre públicos e permitir políticas específicas por área (permissão, rate limit, logs, contratos), sem precisar criar novos serviços agora.

2. Visão estratégica

2.1. O que esta opção resolve

  • Organiza a superfície pública por público: cada consumidor acessa uma “faixa” de rotas própria, evitando o cenário de “tudo no mesmo lugar”.
  • Reduz risco de endpoint comum cair no público errado: a própria estrutura de rotas e módulos força separação.
  • Facilita governança e documentação: fica natural manter documentação por público (cliente, corretor, superapp, parceiros, webhooks).
  • Permite implantação incremental: dá para migrar e endurecer segurança área por área sem precisar refatorar tudo de uma vez.

2.2. O que esta opção não resolve sozinha

  • Ainda é um mesmo bolo: um bug crítico, uma falha de configuração ou um problema de deploy pode afetar todas as áreas.
  • Rota não protege sozinha: a autorização real ainda precisa existir (vínculo do recurso, permissões, regras por consumidor). Se a aplicação “confia demais” na rota, o risco continua.
  • Risco de duplicação: se não houver padrão, pode acontecer duplicação de controller/DTO/contratos entre áreas

3. Visão de negócio

3.1. Benefícios

  • Clareza de contrato por público: portal do cliente, portal do corretor e superapp podem ter endpoints semelhantes, mas com contratos e restrições bem posicionados.
  • Evolução controlada: o negócio consegue evoluir funcionalidades do superapp sem “puxar junto” mudanças desnecessárias do portal, por exemplo.
  • Parceiros com contrato separado: /partners/* permite criar um conjunto controlado de operações (subset) sem expor o que é interno.
  • Webhooks tratados como exceção: /webhooks/* é naturalmente o lugar de endpoints públicos e com validações específicas, ao invés de espalhar AllowAnonymous na API toda.

3.2. Pontos de atenção para o negócio

  • É necessário definir, por área:
    • quais funcionalidades entram (e quais não entram),
    • quais dados podem ser retornados,
    • qual nível de limite e auditoria será aplicado.
  • A separação por rota não pode virar só “organização estética”. Ela precisa vir acompanhada de regras de autorização e vínculo para garantir que cada público só acesse o que deve.

4. Fluxo de funcionamento

%%{init:{   "theme":"neutral",   "fontSize":22,   "flowchart":{"curve":"basis","htmlLabels":true,"nodeSpacing":50,"rankSpacing":70} }}%% flowchart TB   A["Consumidor faz requisicao"]:::ui_input --> B["API Unica com Areas<br/>rotas separadas por publico"]:::ui_input   B --> C{Selecionar area pela rota}:::decision   C -- Cliente --> D["Area Cliente<br/>cliente endpoints"]:::ui_input   C -- Corretor --> E["Area Corretor<br/>corretor endpoints"]:::ui_input   C -- Superapp --> F["Area Superapp<br/>app endpoints"]:::ui_input   C -- Parceiros --> G["Area Parceiros<br/>public api"]:::ui_input   C -- Webhooks --> H["Area Webhooks<br/>integracoes externas"]:::ui_input   C -- IA --> I1["Area IA<br/>agentes automacoes"]:::ui_input   D --> J["Politicas da area<br/>token cors limites"]:::ui_input   E --> J   F --> J   I1 --> J   G --> K["Politicas parceiros<br/>chave quota limites"]:::ui_input   H --> L["Politicas webhooks<br/>assinatura idempotencia"]:::ui_input     J --> M{Autenticacao ok}:::decision   M -- Nao --> N["Negar acesso<br/>401 ou 403"]:::ui_button   M -- Sim --> O["Autorizacao por vinculo<br/>dados do solicitante"]:::ui_input   O --> P{Vinculo permitido}:::decision   P -- Nao --> N   P -- Sim --> Q["Chamar modulos de dominio compartilhados<br/>contratos cobranca documentos"]:::endpoint_post   Q --> R["Registrar auditoria por area<br/>logs e metricas"]:::ui_input   R --> S["Resposta para consumidor<br/>contrato da area"]:::endpoint_get   K --> T{Chave e quota ok}:::decision   T -- Nao --> N   T -- Sim --> U["Autorizacao do parceiro<br/>escopos do contrato"]:::ui_input   U --> V["Operacoes permitidas para parceiro<br/>somente subset"]:::endpoint_post   V --> R   L --> W{Webhook valido}:::decision   W -- Nao --> N   W -- Sim --> X["Normalizar evento e roteamento interno<br/>sem expor dominio"]:::endpoint_post   X --> R   classDef endpoint_get     fill:#e0f2fe,stroke:#0284c7,color:#0f172a,stroke-width:1px;   classDef endpoint_post    fill:#dcfce7,stroke:#16a34a,color:#052e16,stroke-width:1px;   classDef endpoint_put     fill:#fef9c3,stroke:#a16207,color:#3b2f0b,stroke-width:1px;   classDef endpoint_delete  fill:#fee2e2,stroke:#ef4444,color:#7f1d1d,stroke-width:1px;   classDef ui_input   fill:#eef2ff,stroke:#6366f1,color:#111827,stroke-width:1px;   classDef ui_button  fill:#ede9fe,stroke:#7c3aed,color:#1f2937,stroke-width:1px;   classDef decision   fill:#fff7ed,stroke:#f59e0b,color:#78350f,stroke-width:1px;

5. Manutenção e longo prazo

5.1. Manutenção do código

  • Melhor organização do monólito: a separação por rotas tende a incentivar separação por módulos/pacotes (ex.: Cliente, Corretor, Superapp, Partners, Webhooks).
  • Menos risco de “misturar público”: o desenvolvedor naturalmente escolhe “onde colocar” o endpoint conforme o público-alvo.
  • Disciplina necessária para evitar duplicação:
    • Controllers por área podem crescer e duplicar lógica se não houver módulos compartilhados bem definidos.
    • DTOs podem se multiplicar se cada área inventar um “contrato” diferente sem padrão.

Boas práticas para manter sustentável:

  • Módulos de domínio compartilhados (contratação, documentos, financeiro) com serviços reutilizáveis.
  • “Camada de política” por área (autorização, limites, validações) padronizada, evitando lógica repetida em controller.
  • Testes focados em: “endpoint está na área certa?” + “permissão e vínculo continuam valendo?”.

5.2. Escalabilidade

  • Escala horizontal do mesmo deploy (aumento de réplicas), porém com uma vantagem:
    • é mais fácil aplicar políticas diferenciadas por rota (ex.: limitar /partners/* e /webhooks/* mais agressivamente).
  • Rate limit e quotas por área:
    • /partners/*: quotas e limites por parceiro.
    • /webhooks/*: limites fortes, idempotência e validação.
    • /superapp/*: limites por usuário/device.
  • Observabilidade por área:
    • métricas, logs e alarmes por rota/área facilitam detectar problemas e abusos (ex.: pico em webhooks sem derrubar o resto).

6. Adaptação ao legado do PASI

Esta opção é especialmente útil no contexto atual do PASI (onde há grande superfície pública e fragilidades de autenticação), porque permite organizar e endurecer sem explodir a topologia.

6.1. Caminho de adaptação recomendado

  1. Criar as áreas e mover rotas
    • Mapear endpoints existentes e realocar para:
      • /cliente/*, /corretor/*, /superapp/*, /partners/*, /webhooks/*.
  2. Tratar webhooks como exceção
    • Confinar tudo que for “público por natureza” em /webhooks/*.
    • Aplicar assinatura, validação e idempotência nessa área, evitando AllowAnonymous espalhado.
  3. Endurecer autenticação por área
    • Cliente/corretor/superapp exigem token e políticas de CORS por área.
    • Parceiros exigem chave/token com quotas e escopos limitados.
  4. Padronizar autorização por vínculo em todas as áreas
    • Independente de rota, toda operação que acessa dados sensíveis deve validar vínculo (cliente só vê seu dado, corretor só vê sua carteira, parceiro só vê seu escopo).
  5. Documentação e governança por público
    • Publicar documentação separada por área, evitando que “o parceiro veja endpoints internos” por engano.

6.2. Por que esta opção é boa para transição

  • Permite migrar área por área, com entregas claras e comunicáveis para a diretoria:
    • primeiro /webhooks/* (reduz superfície pública rapidamente),
    • depois /partners/* (contrato controlado),
    • depois /superapp/* (lançamento),
    • e por fim /cliente/* e /corretor/* (consolidação).
  • Mantém baixo custo operacional (um deploy), enquanto melhora governança e organização.

7. Principais prós e contras

7.1. Prós

  • Organiza e reduz risco de “endpoint comum” cair no público errado.
  • Facilita documentação e governança por público.
  • Dá para implantar em etapas (migrar área por área) sem criar novos serviços.

7.2. Contras

  • Ainda é um mesmo deploy; um bug pode afetar tudo.
  • Ainda precisa de disciplina na autorização real (rota sozinha não protege).
  • Pode duplicar controller/DTO se não houver padrão.

8. Quando esta opção faz sentido

  • Quando você quer segmentar já, melhorar governança e segurança, sem criar novos serviços agora.
  • Quando há múltiplos consumidores com necessidades diferentes, mas o time quer manter a operação simples no curto prazo.
  • Quando a estratégia é evoluir em fases, reduzindo risco e organizando contratos antes de uma separação mais profunda.