padrao-referencias-firestore

Convenção de nomenclatura

1. <colecao>_ref = coleção de referência (modelo/base)
2. <colecao> = coleção com dado real de uso operacional

Exemplos:

• class_ref -> referência
• classes -> dados reais
• church_ref -> referência
• churchs -> dados reais

---

Regra geral

• Coleções *_ref não são fonte de operação diária.
• Coleções sem sufixo _ref são usadas pela aplicação em produção (dados reais).

---

Escopo 1: Plataforma (/platform/data_ref)

Caminho base:

• /platform/data_ref

Finalidade:

• armazenar apenas modelos de referência globais da plataforma;
• não armazenar dados operacionais de tenant/igreja.

Regra:

• tudo dentro de /platform/data_ref existe para servir de base e padronização para os tenants.

---

Escopo 2: Ministério (/platform/ministrys/{ministryId}/data)

Caminho base:

• /platform/ministrys/{ministryId}/data

Finalidade:

• armazenar coleções reais do ministério (uso direto da operação do tenant).

Regra principal:

• as coleções operacionais do ministério não usam _ref.

Exemplos:

• churchs
• classes
• users
• messages
• ebds

---

Referências internas do ministério

Um ministério pode ter coleções *_ref em seu próprio data quando precisar manter referências para suas igrejas.

Exemplo de uso válido:

• /platform/ministrys/{ministryId}/data/class_ref

Quando usar:

• referência específica do tenant;
• modelo que será replicado/derivado para as igrejas daquele ministério.

Quando não usar:

• para dado operacional diário;
• para informação que deve existir apenas como coleção real.

---

Relação entre plataforma e ministério

1. Plataforma define base em /platform/data_ref.
2. Ministério usa coleções reais em /platform/ministrys/{ministryId}/data.
3. Ministério pode manter *_ref local apenas como referência para suas igrejas.

---

Relação com classes de domínio

Para alinhar banco e código, adotar mapeamento 1:1 entre tipo de coleção e tipo de classe:

1. Coleção *_ref -> classe de domínio *Ref.
2. Coleção sem _ref -> classe operacional (sem sufixo).

Exemplos:

• church_ref -> ChurchRef
• class_ref -> ClassGroupRef
• ebd_ref -> EbdRef
• ebds -> EbdSession

Decisão oficial:

• docs/architecture/adrs/adr-0025-padrao-de-classes-de-referencia-no-dominio.md

Detalhamento técnico:

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

---

Regras de construção futura

Ao criar nova estrutura:

1. Definir se é referência ou dado real.
2. Se referência global, criar em /platform/data_ref/<colecao>_ref.
3. Se operacional do tenant, criar em /platform/ministrys/{ministryId}/data/<colecao>.
4. Se referência interna do tenant para igrejas, criar em /platform/ministrys/{ministryId}/data/<colecao>_ref.
5. Evitar duplicar sem necessidade (referência e operacional com mesmo conteúdo permanente).

Checklist obrigatório por feature:

1. Existe coleção *_ref para este objeto?
2. Se sim, a classe *Ref foi criada/atualizada no domínio?
3. Existe classe operacional separada para dado real?
4. Mapeadores Firestore foram implementados só em infrastructure?
5. Foi evitado acoplamento de regra de negócio na presentation?

---

Checklist rápido

• O nome da coleção segue a convenção _ref?
• A coleção está no escopo correto (plataforma vs ministério)?
• É modelo (referência) ou uso real (operação)?
• Está claro quem consome essa coleção (plataforma, ministério, igreja)?

---

Observação

Este padrão baliza a evolução do modelo de dados. Qualquer exceção deve ser registrada em ADR ou documento técnico de decisão.