Tratamento de payloads extensos gerados por editores de texto

Contexto e Declaração do Problema

A Amplimed utiliza editores de texto (como Tiny Editor) em diversos pontos do sistema para permitir a criação de conteúdos HTML livres, como textos clínicos, observações, descrições e campos personalizados.

Em produção, foram identificados cenários em que usuários inserem conteúdos HTML muito extensos, resultando em falhas no processamento das requisições HTTP responsáveis pelo salvamento desses dados.

O erro mais recorrente observado é: PayloadTooLargeError: request entity too large

Esse tipo de erro ocorre durante o processamento da requisição, antes da aplicação conseguir aplicar qualquer validação de regra de negócio, indicando que o payload enviado ultrapassa limites aceitos pela API responsável pela rota.

O problema não é isolado em um único fluxo funcional, mas sim estrutural, pois o mesmo padrão de editor é reutilizado em múltiplas áreas do sistema.

Pergunta central:

Como devemos tratar payloads extensos gerados por editores de texto de forma consistente, segura e escalável em todo o sistema?

Mapeamento dos Problemas Relacionados a esta ADR

Os seguintes pontos do sistema já apresentaram ou estão sujeitos a este problema:

Este mapeamento deverá ser expandido conforme outros fluxos com editores de texto forem identificados ou apresentarem comportamento semelhante.

Direcionadores da Decisão

  • Estabilidade do sistema: evitar falhas em produção causadas por payloads excessivamente grandes.
  • Padronização: garantir tratamento consistente para todos os fluxos que utilizam editores de texto.
  • Manutenibilidade: evitar soluções pontuais por fluxo ou serviço.
  • Experiência do usuário: permitir retorno previsível e tratável em caso de conteúdo fora do padrão.
  • Aderência arquitetural: alinhar a solução com a stack principal de backend da Amplimed.

Opções Consideradas

  • Opção 1: Aumentar o limite máximo de payload aceito pelas APIs atuais
  • Opção 2: Implementar validação e limitação explícita do tamanho do conteúdo no backend atual
  • Opção 3: Validar e limitar o tamanho do conteúdo apenas no frontend (editor)
  • Opção 4: Refatorar a rota para Laravel e validar o payload de acordo com a capacidade suportada pelo backend

Decisão

Opção escolhida: Opção 4 – Refatorar a rota para Laravel e validar o payload de acordo com a capacidade suportada pelo backend.

A decisão foi tomada considerando a necessidade de uma solução estrutural e reutilizável, aplicável a todos os fluxos que utilizam editores de texto.

Ao centralizar esse tipo de salvamento em rotas Laravel, é possível:

  • Aplicar validações explícitas e previsíveis
  • Controlar o tamanho do payload de forma alinhada à capacidade real do backend
  • Evitar limitações técnicas impostas por serviços intermediários
  • Garantir maior consistência entre diferentes áreas do sistema

Essa abordagem reduz a dependência de ajustes pontuais e cria uma base sólida para evolução futura.

Consequências

Positivas

  • Tratamento padronizado para todos os fluxos com editores de texto
  • Redução significativa de erros como PayloadTooLargeError
  • Maior previsibilidade operacional
  • Centralização da regra de validação no backend principal

Negativas

  • Necessidade de refatoração de rotas existentes
  • Maior esforço inicial de implementação
  • Dependência de alinhamento entre times de backend e frontend

Neutras

  • O comportamento funcional permanece inalterado para conteúdos dentro dos limites definidos
  • Nenhum impacto imediato para usuários que não utilizam conteúdos extensos

Confirmação e Validação

A aderência a este ADR será validada por meio de:

  • Revisões de arquitetura garantindo que fluxos com editores utilizem a abordagem definida
  • Validações em pull requests envolvendo rotas de salvamento de conteúdo
  • Testes automatizados cobrindo diferentes tamanhos de payload
  • Monitoramento de erros relacionados a tamanho de requisição
  • Atualização contínua do mapeamento de fluxos afetados

Prós e Contras das Opções

Opção 1 – Aumentar limites de payload

  • Positivo: solução rápida
  • Neutro: não exige refatoração imediata
  • Negativo: risco de abuso, impacto de performance e ausência de controle fino

Opção 2 – Validação no backend atual

  • Positivo: melhora controle sem grandes mudanças
  • Neutro: resolve apenas parte do problema
  • Negativo: mantém limitações estruturais existentes

Opção 3 – Validação apenas no frontend

  • Positivo: melhora experiência do usuário
  • Neutro: reduz erros acidentais
  • Negativo: não garante proteção do backend

Opção 4 – Refatorar rota para Laravel (opção escolhida)

  • Positivo: solução estrutural, reutilizável e alinhada à arquitetura
  • Neutro: exige padronização de fluxos
  • Negativo: maior esforço inicial de implementação