Skip to main content

ADR-0014 — Gateway Único de Operações de Usuário com Handlers por Ação

Status​

Proposto

Contexto​

Os ADRs atuais ja definem principios essenciais para identidade e seguranca no EBDbe:

  • Multitenancy por dominio e validacao de escopo no backend (ADR-0012)
  • Perfil de usuario, ciclo de vida e transicoes de status (ADR-0013)
  • Backend como autoridade e proibicao de bypass de escopo

Entretanto, ainda nao ha formalizacao da estrategia de exposicao de operacoes de usuario no backend quanto a:

  1. Padrao de entrada para operacoes CRUD e transicoes de status
  2. Forma de roteamento de acoes sem concentrar logica de negocio em um bloco unico
  3. Pipeline obrigatorio de seguranca por requisicao
  4. Contratos minimos de request/response, auditoria e erro

Sem essa formalizacao, ha risco de evolucao para uma "funcao monolitica" (God Function), com aumento de complexidade, risco de regressao de autorizacao e menor auditabilidade.

Decisão​

O sistema adotará um Gateway Único de Operações de Usuário na borda de Functions, com handlers por ação internamente, preservando Clean Architecture.

1. Entrada unica, execucao segmentada​

  • Havera um endpoint/gateway unico para operacoes de usuario.
  • O gateway apenas orquestra validacoes e despacho.
  • Cada acao sera executada por seu respectivo handler/use case dedicado.
  • E vedado concentrar regras de dominio de multiplas acoes em um unico bloco condicional extenso.

2. Contrato de requisicao (request contract)​

Toda requisicao deve incluir, no minimo:

  • version (ex.: v1)
  • action (whitelist estrita, sem acao dinamica)
  • payload (schema especifico por acao)
  • meta.request_id (idempotencia e rastreabilidade)
  • meta.target_ministry_id (obrigatorio em contexto cross-tenant)
  • meta.reason (obrigatorio para acoes sensiveis/destrutivas)

Acoes permitidas devem ser explicitamente mapeadas (exemplos): USER_CREATE, USER_GET, USER_UPDATE, USER_DELETE, USER_CHANGE_STATUS, USER_LIST.

3. Pipeline obrigatorio por requisicao​

A ordem de execucao no gateway e mandatoria:

  1. Autenticar solicitante (actor_user_id, claims)
  2. Resolver tenant por dominio/host
  3. Validar coerencia de escopo (actor, alvo, tenant)
  4. Autorizar acao por papel + escopo
  5. Validar payload por schema da acao
  6. Executar use case correspondente
  7. Registrar auditoria
  8. Retornar resposta padronizada

Nenhuma acao de usuario deve executar fora desse pipeline.

4. Autorizacao e escopo​

  • Toda decisao de autorizacao e do backend.
  • Operacoes no tenant ministerial exigem aderencia de ministry_id.
  • Operacoes cross-tenant exigem PLATFORM_ADMIN + target_ministry_id explicito.
  • Divergencia entre dominio resolvido e escopo autorizado deve negar a requisicao (FORBIDDEN_SCOPE_MISMATCH).

5. Regras de status e ciclo de vida​

  • Alteracoes de status devem respeitar integralmente a matriz de transicoes do ADR-0013.
  • DELETED permanece estado terminal.
  • Transicoes sensiveis exigem justificativa (reason) e trilha auditavel.

6. Padrao de resposta e erro​

A resposta deve seguir envelope padronizado com:

  • ok
  • action
  • data
  • audit (metadados de execucao relevantes)
  • error padronizado (code, message, details)

Esse padrao e obrigatorio para consistencia entre frontend, observabilidade e suporte operacional.

7. Observabilidade, idempotencia e resiliencia​

  • Logs estruturados por acao (action, actor, target, tenant, result, request_id)
  • Idempotencia para operacoes sensiveis via request_id
  • Auditoria obrigatoria para alteracoes de status e acoes cross-tenant
  • Rate limit por ator/contexto para reduzir abuso

Regras Arquiteturais Derivadas​

  1. Gateway unico nao implica dominio acoplado; logica de negocio permanece em use cases/servicos de dominio.
  2. Toda acao de usuario deve ter schema de entrada e politica de autorizacao proprios.
  3. Firestore permanece restrito a camada de infrastructure.
  4. Nenhuma operacao de usuario pode bypassar validacao de tenant e escopo.
  5. Toda operacao sensivel/destrutiva deve exigir justificativa operacional e auditoria.

Integracao com ADRs existentes​

  • ADR-0012: aplica resolucao de tenant por dominio e regras cross-tenant com PLATFORM_ADMIN.
  • ADR-0013: aplica modelo de perfil e matriz de transicao de status.
  • ADR-0003: mantem RBAC por acao e escopo hierarquico.
  • ADR-0006: reforca minimizacao de dados e tratamento de dados pessoais.
  • ADR-0010: mantem requisitos de seguranca de autenticacao/sessao para acoes administrativas.

Consequencias​

  • O backend ganha um padrao unico de entrada e governanca de seguranca por operacao.
  • A manutencao evolui por acao (handlers/use cases), com menor risco de regressao.
  • A autorizacao fica mais auditavel e testavel por matriz de acao/perfil/escopo.
  • O custo inicial de modelagem aumenta (schemas, politicas e testes por acao).
  • Mudancas no catalogo de acoes ou no contrato exigirao revisao deste ADR ou ADR complementar.
Last updated on