Skip to content
EBDbe

ADR-0025 — Padrão de classes de referência no domínio

Status

Section titled “Status”

Aprovado

Contexto

Section titled “Contexto”

O projeto adotou convenção de dados de referência no Firestore (*_ref) para separar:

  • modelo/base reutilizável;
  • dado operacional real.

Ainda faltava uma decisão arquitetural explícita para o código (frontend/backend) sobre quando criar classes de referência e como relacionar essas classes com coleções *_ref.

Sem essa definição, o time tende a:

  • duplicar modelos sem necessidade;
  • misturar objeto de referência com objeto operacional;
  • criar acoplamento entre UI e estrutura de persistência.

Decisão

Section titled “Decisão”

O EBDbe passa a adotar o seguinte padrão:

1) Classe de referência

Section titled “1) Classe de referência”

Quando o dado for modelo/base, criar classe de referência no domínio com sufixo:

  • *Ref (ex.: ChurchRef, ClassGroupRef, MaterialRef)

2) Classe operacional (dado real)

Section titled “2) Classe operacional (dado real)”

Quando o dado representar operação real da aplicação, manter classe sem sufixo:

  • User, EbdSession, Lesson, etc.

3) Regra de mapeamento Firestore

Section titled “3) Regra de mapeamento Firestore”
  • Coleção *_ref mapeia para classe *Ref.
  • Coleção sem _ref mapeia para classe operacional.

Exemplos:

  • church_ref -> ChurchRef
  • churchs -> Church (ou equivalente operacional)
  • class_ref -> ClassGroupRef
  • ebds -> EbdSession

4) Quando criar classe *Ref

Section titled “4) Quando criar classe *Ref”

Criar classe de referência quando houver pelo menos 1 critério:

  1. O mesmo modelo é reutilizado por múltiplos tenants/unidades.
  2. O objeto é usado como catálogo/base de seleção e não como operação diária.
  3. Há processo de sincronização/replicação (*_ref -> coleção real).
  4. É necessário versionar ou governar modelo-base sem alterar histórico operacional.

5) Quando não criar classe *Ref

Section titled “5) Quando não criar classe *Ref”

Não criar quando:

  • o dado é exclusivamente operacional;
  • não existe coleção *_ref;
  • o custo de manter dois modelos supera o benefício.

6) Limite de camadas (ADR-0007)

Section titled “6) Limite de camadas (ADR-0007)”
  • domain: define classes (*Ref e operacionais), sem Firebase/Flutter.
  • infrastructure: faz mapeamento Firestore <-> classes.
  • application: orquestra uso das referências.
  • presentation: consome DTO/viewmodel, sem regra crítica.

Consequências

Section titled “Consequências”

Positivas

Section titled “Positivas”
  • consistência entre modelagem de BD e classes de domínio;
  • menor ambiguidade entre referência e dado real;
  • base para automação de migração/sincronização.

Custos

Section titled “Custos”
  • manutenção adicional de modelos *Ref;
  • necessidade de checklist de decisão ao introduzir novas entidades.

Matriz inicial (alvo)

Section titled “Matriz inicial (alvo)”

Objetos priorizados para este padrão:

  1. User
  2. Ministry
  3. Church
  4. PlatformConfig
  5. ClassGroup
  6. Material (material didático/revista)
  7. Ebd
  8. EbdSession

A matriz detalhada de aplicação está no TDD:

  • docs/architecture/tdd/data-model/tdd-objetos-de-referencia.md

Referências

Section titled “Referências”
  • ADR-0005 — Modelo de Domínio Conceitual
  • ADR-0007 — Padrão de organização de código
  • ADR-0012 — Multitenancy por domínio
  • docs/architecture/data-model/padrao-referencias-firestore.md