ADR-0023 — Coleção Dedicada de Mensagens
Status
Proposto
Contexto
Atualmente as mensagens do sistema estão incorporadas ao perfil do usuário (campo messages no documento platform/users/{uid}). O PRD-0002 e o ADR-0011 (Estratégia de Comunicações) indicam a necessidade de um subsistema de mensagens com:
- Dados do emissor e data de envio
- Status de leitura pelo destinatário
- Prioridade (0 a 5)
- Ações do receptor (excluir, marcar como lida, ignorar)
- Entrega instantânea ao usuário final: mensagens devem ser comunicadas em tempo real (ou quase) após o login
Para entregar mensagens instantaneamente, é necessário manter um listener (ex.: Firestore onSnapshot) ou mecanismo equivalente (WebSocket, push) rodando logo após o usuário estar logado, em vez de depender apenas de polling ou da carga do perfil.
Decisão
O sistema adotará uma coleção dedicada para mensagens, separada do documento de perfil, com suporte a entrega em tempo real.
1. Coleção Dedicada
- Caminho sugerido:
platform/messages/{messageId}ouplatform/ministries/{ministryId}/messages/{messageId}conforme escopo tenant - Documento: um documento por mensagem
- Backend: autoridade para inserção, validação de escopo e permissões
- Referência: ADR-0013 Perfil e Ciclo de Vida, ADR-0011 Estratégia de Comunicações
2. Entrega Instantânea
As mensagens devem ser entregues ao usuário final instantaneamente (tempo real ou o mais próximo possível). Para isso:
- O cliente (frontend) deve manter um listener ativo na coleção/query de mensagens do usuário logo após o login (quando o perfil estiver carregado)
- Mecanismo preferencial: Firestore
onSnapshotem query filtrada porreceiverId == uid(e escopo tenant quando aplicável) - Alternativas: WebSocket dedicado ou FCM para push; o listener em tempo real na sessão ativa continua preferível para entrega imediata na UI
- O listener deve ser iniciado assim que o usuário estiver autenticado e o perfil carregado; encerrado no logout
3. Integração com Perfil
- O perfil do usuário (
UserProfile) pode referenciar mensagens ou continuar expondo uma visão agregada para compatibilidade; a fonte de verdade para novas mensagens passa a ser a coleção dedicada - O campo
messagesno documento de perfil pode ser mantido temporariamente para migração ou deprecado conforme evolução
Consequências
- Necessidade de índices Firestore para queries por
receiverId,emittedAt,readStatus - Custo adicional de listeners ativos por usuário logado
- Implementação do serviço de mensagens no frontend (listener + ações do receptor)
- Migração de mensagens existentes (se aplicável) ou coexistência durante transição
Referências
| Tipo | Documento |
|---|---|
| ADR | ADR-0011 — Estratégia de Comunicações, ADR-0013 — Perfil e Ciclo de Vida |
| PRD | PRD-0002 — Página inicial |
| Data Model | Data Model Mensagens |
| TDD | TDD API Mensagens |