Skip to main content

ADR-0015 — Fracionamento Modular de Codigo na Camada de Apresentacao

Status​

Proposto

Contexto​

O projeto EBDbe ja adota Clean Architecture (ADR-0007), backend como autoridade e validacao de escopo no backend (ADRs 0003, 0012, 0013). Entretanto, existem arquivos na camada de apresentacao com centenas ou milhares de linhas, concentrando multiplas responsabilidades em um unico ponto.

Esse cenario aumenta:

  • acoplamento entre UI, estado e integracoes
  • risco de regressao em alteracoes simples
  • custo de manutencao e revisao de PR
  • dificuldade para testes e onboarding tecnico

Em alguns pontos, a camada presentation tambem passa a conhecer detalhes concretos de infrastructure, reduzindo isolamento arquitetural.

Decisao​

O sistema adotara um padrao formal de fracionamento modular por responsabilidade na camada de apresentacao, com criterios objetivos de extracao, limites orientativos e fluxo de migracao incremental.

1. Principio de corte: responsabilidade, nao tamanho isolado​

O fracionamento deve ocorrer por contexto funcional coeso, priorizando:

  • responsabilidade unica por arquivo/classe
  • alta coesao interna
  • baixo acoplamento com detalhes externos
  • legibilidade do fluxo principal da tela

Tamanho de arquivo e sinal, nao criterio unico.

2. Fronteiras arquiteturais obrigatorias​

Na camada presentation:

  1. Nao importar implementacoes concretas de infrastructure.
  2. Dependencias devem ocorrer via application ou interfaces de domain.
  3. Regra de negocio critica permanece fora da UI.
  4. Backend continua autoridade para RBAC, escopo e decisoes finais.

3. Organizacao recomendada por modulo de tela​

Para telas complexas, adotar estrutura por modulo:

  • pages/<feature>/<feature>_page.dart (orquestracao da pagina)
  • pages/<feature>/widgets/... (secoes visuais da pagina)
  • pages/<feature>/dialogs/... (dialogos especificos)
  • pages/<feature>/controllers/... (estado e acoes de UI)
  • pages/<feature>/mappers|formatters|view_models/... (transformacoes de apresentacao)

Utilitarios compartilhaveis devem migrar para shared/.

4. Criterios de extracao obrigatoria (gatilhos)​

A extracao passa a ser mandatoria quando houver um ou mais gatilhos:

  • arquivo com multiplos contextos independentes (ex.: pagina + dialogo + editor interno)
  • widget principal com fluxo de leitura comprometido
  • State concentrando estado, transformacao e persistencia de multiplos subfluxos
  • duplicacao de parsing/formatacao/renderizacao em blocos distintos
  • necessidade recorrente de alteracao em regioes nao relacionadas do mesmo arquivo

5. Limites orientativos (governanca de manutencao)​

Nao sao limites rigidos de compilacao, mas metas de qualidade:

  • arquivo de UI container: preferencialmente ate ~300 linhas
  • arquivo de componente visual: preferencialmente ate ~200 linhas
  • arquivo acima de ~500 linhas exige justificativa tecnica no PR
  • metodos extensos devem ser extraidos em funcoes nomeadas por intencao

Excecoes sao permitidas com justificativa explicita no PR.

6. Estrategia de migracao​

Refatoracoes devem ser incrementais e seguras:

  1. Extrair primeiro componentes visuais puros.
  2. Extrair dialogos e subfluxos independentes.
  3. Extrair transformacoes e utilitarios de apresentacao.
  4. Introduzir controller local quando o estado ficar complexo.
  5. So depois ajustar fronteiras de dependencia para abstracoes.

Regra: refatorar sem alterar comportamento funcional no mesmo passo.

7. Conteúdo de abas (tabs)​

O conteúdo de cada aba deve ser implementado como componente em arquivo separado (widget importável), não como part of do arquivo principal.

  • Cada aba corresponde a um widget em arquivo próprio (ex.: home_tab_inicio.dart, home_tab_acoes.dart, home_tab_mensagens.dart).
  • A página orquestradora importa e usa esses widgets.
  • Evita uso de part of para conteúdo de tabs; favorece componentes autônomos e testáveis.

Regras Arquiteturais Derivadas​

  1. presentation nao depende diretamente de concretos de infrastructure.
  2. Modulos de tela devem ser organizados por responsabilidade funcional.
  3. Funcoes de transformacao de UI (format/parsing/view mapping) devem ser isolaveis e testaveis.
  4. Refatoracao estrutural deve preservar backend como autoridade de escopo e autorizacao.
  5. Toda excecao de modularizacao deve ser documentada em PR.
  6. Conteúdo de abas (tabs) deve ser extraído em componentes em arquivos separados; não usar part of para conteúdo de tabs.

Integracao com ADRs existentes​

  • ADR-0007: reforca separacao de camadas e organizacao estrutural.
  • ADR-0003: mantem RBAC e escopo no backend.
  • ADR-0012: preserva validacao tenant-aware no backend.
  • ADR-0013: mantem coerencia de perfil e ciclo de vida sem deslocar regra para UI.
  • ADR-0009: melhora consistencia de UX ao organizar fluxos complexos de interface.

Consequencias​

  • Melhor legibilidade, manutencao e previsibilidade de evolucao.
  • PRs menores e com revisao mais objetiva.
  • Menor risco de regressao em telas complexas.
  • Aumento inicial de esforco em refatoracao incremental.
  • Necessidade de disciplina continua de modularizacao em novas entregas.
Last updated on