TDD — API de Mensagens (coleção dedicada)

Status

Proposto

Contexto

Mensagens em coleção dedicada conforme ADR-0023 e Data Model Mensagens. Entregas instantâneas via listener ativo após login.

---

Listener em tempo real (cliente)

Requisito: Mensagens devem ser comunicadas instantaneamente ao usuário final. Um listener (ou mecanismo equivalente) deve estar ativo logo após o login.

Contrato do listener

• Mecanismo: Firestore onSnapshot em query da coleção platform/ministrys/{ministryId}/data/messages filtrada por receiverId == email (usuário logado) e deletedAt == null
• Quando iniciar: Imediatamente após o perfil ser carregado com sucesso (usuário logado)
• Quando encerrar: No logout ou ao desmontar a sessão
• Ordenação sugerida: priority ASC (URGENT primeiro), emittedAt DESC (mais recentes primeiro)
• Filtros opcionais: deletedAt == null (excluir mensagens soft-deleted pelo receptor)
• Regras de segurança Firestore: Apenas o receiverId pode ler suas mensagens; validação de escopo (ministryId) conforme tenant

Fluxo no frontend

1. Usuário faz login → perfil carregado
2. Serviço de mensagens inicia listener na query de mensagens do usuário
3. Novas mensagens chegam em tempo real → UI atualiza
4. Usuário faz logout → listener é cancelado

---

Ações do receptor (gateway)

As ações do receptor (marcar como lida, excluir, ignorar) podem ser expostas via userGatewayHttp ou endpoint dedicado.

Ações via gateway (sugestão)

Action	Payload	Efeito
USER_MESSAGE_MARK_READ	{ messageId: string }	readStatus = READ
USER_MESSAGE_DELETE	{ messageId: string }	deletedAt = now (soft delete)
USER_MESSAGE_IGNORE	{ messageId: string }	readStatus = IGNORED

Validação: Apenas o receiverId pode executar essas ações na própria mensagem.

---

Inserção de mensagens (backend)

Mensagens são inseridas no Firestore pelo backend quando:

• Sistema envia notificação (ex.: "Sua solicitação foi aprovada")
• Usuário envia mensagem a outro (chat; a definir)
• Eventos automáticos (ex.: aviso EBD em 30 min)

Responsabilidade: Backend é autoridade para inserção; valida emissor, destinatário e escopo antes de gravar.

---

Payload de mensagem (resposta / listener)

Objeto retornado pelo listener ou pela ação USER_MESSAGES_LIST (se mantida para compatibilidade):

{
  "id": "string",
  "receiverId": "string",
  "emitterId": "string",
  "emitterName": "string?",
  "emitterEmail": "string?",
  "emittedAt": "string (ISO 8601)",
  "title": "string",
  "body": "string?",
  "type": "SYSTEM|PERSONAL|GROUP",
  "readStatus": "UNREAD|READ|IGNORED",
  "priority": "NORMAL",
  "ministryId": "string",
  "unitId": "string?",
  "deletedAt": "string? (ISO 8601)"
}

---

Comandos de debug (alternativa a function para CRUD manual)

Para desenvolvimento e operações manuais na coleção platform/messages, use o console de debug (Home → Ajuda → Debug). Isso evita criar uma Cloud Function apenas para setup ou testes.

Script com comandos prontos: scripts/DEBUG-COMANDOS-MENSAGENS.md (na raiz do repositório)

• Ler coleção ou documento: op: "read", path: "platform/messages"
• Inserir mensagem de teste: op: "write", path: "platform/messages/msg_XXX", data: { ... }
• Atualizar (marcar lida, excluir, ignorar): op: "write", mode: "merge", data: { readStatus|deletedAt }

Backend: platformDebugFirestoreHttp (POST). Referência: TDD Firestore Command.

Produção: A inserção pelo sistema (ex.: notificação ao aprovar) continua no backend; o comando é complementar.

---

Integração com perfil

• Durante migração, o perfil pode continuar expondo messages agregadas (via USER_GET) para compatibilidade com ProfileDialog
• A aba Mensagens da Home e futuras telas devem consumir o listener da coleção dedicada como fonte primária
• Referência: TDD Mensagens e Preferências (estado atual)

---

Referências

Tipo	Documento
ADR	ADR-0023 — Coleção Dedicada de Mensagens
Data Model	Data Model Mensagens
PRD	PRD-0002 — Página inicial