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

Usuário faz login → perfil carregado
Serviço de mensagens inicia listener na query de mensagens do usuário
Novas mensagens chegam em tempo real → UI atualiza
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