Servidor de Comunicação

Bem-vindo à documentação do Servidor de Comunicação! Este guia completo irá te ajudar a entender a arquitetura, os fluxos e como utilizar a nossa API para enviar notificações push para dispositivos móveis.

✨ Introdução

O Servidor de Comunicação é uma aplicação Node.js com Express, projetada para ser o backend central no gerenciamento e envio de notificações push. Ele utiliza o Firebase Cloud Messaging (FCM) para a comunicação com os dispositivos e o MongoDB para armazenar de forma persistente os dados dos dispositivos e o histórico de notificações.

Principais Funcionalidades

✅ Autenticação de Dispositivos: Garante que apenas dispositivos autorizados possam receber notificações.
✅ Envio de Notificações: Suporte para envio de mensagens para um único dispositivo ou em massa para múltiplos dispositivos.
✅ Persistência de Dados: Utiliza o MongoDB para armazenar informações cruciais.
✅ Validação de Dados: Assegura a integridade dos dados com o Zod.
✅ Histórico e Métricas: Permite a consulta de notificações enviadas e estatísticas de uso.

🏁 Começando

Siga os passos abaixo para configurar e executar o projeto em seu ambiente de desenvolvimento local.

Pré-requisitos

Node.js (versão 22 ou superior)
MongoDB (instalado e rodando localmente)
Git

Passos para Instalação

Clone o Repositório:

git clone <URL_DO_REPOSITORIO>
cd communication-server

Instale as Dependências:
```
npm install
```

Configure as Variáveis de Ambiente:

Crie um arquivo .env na raiz do projeto. Você pode copiar o exemplo abaixo:

# Porta em que o servidor irá rodar
PORT=3000

# String de conexão para o seu banco de dados MongoDB local
MONGODB_URI=mongodb://localhost:27017/communication-server

Credenciais do Firebase:

Adicione o seu arquivo de credenciais do Firebase Admin SDK (vidya-communication-firebase-adminsdk-fbsvc-a34f1b1e1a.json) na raiz do projeto.

ATENÇÃO
O arquivo de credenciais do Firebase é sensível e não deve ser enviado para o repositório Git. Certifique-se de que ele está no seu arquivo .gitignore.
Execute o Servidor:

Para iniciar o servidor em modo de desenvolvimento (com hot-reload):
```
npm run dev
```
Para iniciar em modo de produção:
```
npm start
```

Ao final, você verá uma mensagem indicando que o servidor está rodando!

📂 Estrutura do Projeto

O projeto é organizado da seguinte forma para garantir a manutenibilidade e escalabilidade:

/communication-server
├─── src/
│   ├─── database-config.js  # Configuração da conexão com o MongoDB
│   ├─── firebase-config.js  # Inicialização do Firebase Admin SDK
│   ├─── server.js           # Arquivo principal com as rotas e middlewares
│   ├─── models/             # Schemas do Mongoose para o banco de dados
│   └─── schemas/            # Validações de dados de entrada com Zod
├─── .env                    # Arquivo com as variáveis de ambiente
├─── package.json
└─── ...

Fluxo de Autenticação de Dispositivo

O aplicativo móvel, ao ser iniciado, envia os dados do dispositivo para o endpoint POST /deviceAuth.
O servidor verifica se o dispositivo já existe no MongoDB.
Se for um novo dispositivo, ele é cadastrado. Se já existir, suas informações (como o token do FCM) são atualizadas.
O servidor retorna uma resposta de sucesso, e o dispositivo está pronto para receber notificações.

Fluxo de Envio de Notificação

Um sistema externo (ou o próprio backend) faz uma requisição para o endpoint POST /send_message.
A requisição contém os critérios para encontrar os dispositivos (como CLIENT_ID e PRODUCT_ID) e a mensagem a ser enviada.
O servidor busca no MongoDB todos os dispositivos que atendem aos critérios.
Com os tokens dos dispositivos em mãos, o servidor utiliza o FCM para enviar a notificação.
Um registro do envio é salvo no histórico de notificações.

📖 Referência da API

Todos os endpoints são protegidos por Autenticação Básica (Basic Auth).

Autenticação

POST /deviceAuth - Autentica um dispositivo

Descrição: Registra ou atualiza as informações de um dispositivo móvel.

Corpo da Requisição: application/json

Campo	Tipo	Descrição
`CLIENT_ID`	`string`	ID do cliente (ex: URL do sistema)
`USER_ID`	`number`	ID do usuário no sistema
`PRODUCT_ID`	`number`	ID do produto ou aplicação
`DEVICE_ID`	`string`	ID único do dispositivo
`FIREBASE_TOKEN`	`string`	Token do Firebase Cloud Messaging
`PLATFORM`	`string`	Plataforma do dispositivo (`android`, `ios`, `web`)

Exemplo de Requisição:

{
  "CLIENT_ID": "http://desenv2.force.vidyacode.com.b",
  "USER_ID": 123,
  "PRODUCT_ID": 1,
  "DEVICE_ID": "abcdef123456",
  "FIREBASE_TOKEN": "token_super_secreto",
  "PLATFORM": "android"
}

Exemplo de Resposta (Sucesso 201):

{
  "message": "New device authenticated",
  "device": { ... },
  "timestamp": "2025-09-19T15:00:00.000Z"
}

Mensagens

POST /send_message - Envia uma mensagem

Descrição: Envia uma notificação para um ou mais dispositivos.

Corpo da Requisição: application/json

Campo	Tipo	Descrição
`CLIENT_ID`	`string`	ID do cliente
`USER_ID`	`number`	(Opcional) Se informado, envia apenas para este usuário. Senão, para todos.
`PRODUCT_ID`	`number`	ID do produto
`TITLE`	`string`	Título da notificação
`MESSAGE`	`string`	Corpo da mensagem

Exemplo de Requisição:

{
  "CLIENT_ID": "http://desenv2.force.vidyacode.com.b",
  "PRODUCT_ID": 1,
  "USER_ID": null,
  "TITLE": "Promoção Imperdível!",
  "MESSAGE": "Clique aqui e confira os nossos descontos."
}

Exemplo de Resposta (Sucesso 200):

{
  "message": "Message sent successfully",
  "summary": {
    "totalDevicesFound": 5,
    "devicesWithTokens": 5,
    "successCount": 5,
    "failureCount": 0
  },
  ...
}

Gerenciamento

GET /listDevices - Lista os dispositivos

Descrição: Retorna uma lista de dispositivos autenticados.

Parâmetros de Query:

Parâmetro	Tipo	Descrição
`CLIENT_ID`	`string`	(Obrigatório) ID do cliente
`PRODUCT_ID`	`number`	(Opcional) ID do produto
`USER_ID`	`number`	(Opcional) ID do usuário

Exemplo de Resposta (Sucesso 200):

{
  "count": 10,
  "devices": [ ... ],
  "timestamp": "2025-09-19T15:05:00.000Z"
}

GET /notifications/history - Histórico de notificações

Descrição: Retorna o histórico de notificações enviadas.

Parâmetros de Query:

Parâmetro	Tipo	Descrição
`userId`	`string`	(Opcional) Filtra por ID do usuário
`type`	`string`	(Opcional) Filtra por tipo de envio
`page`	`number`	(Opcional) Página para paginação
`limit`	`number`	(Opcional) Limite de itens por página

🚀 Deploy

Para fazer o deploy da aplicação em um servidor Linux na AWS (EC2), siga os passos detalhados na seção "Criando um Servidor na Nuvem (AWS) com Linux" da nossa conversa anterior.

Lembre-se de configurar as variáveis de ambiente no servidor de produção e utilizar um gerenciador de processos como o pm2 para manter a aplicação rodando de forma estável.

# Instalar o pm2 globalmente
npm install pm2 -g

# Iniciar a aplicação com o pm2
pm2 start src/server.js --name "communication-server"

Esperamos que esta documentação seja útil! Se tiver qualquer dúvida, não hesite em perguntar.

✨ Introdução​

Principais Funcionalidades​

🏁 Começando​

Pré-requisitos​

Passos para Instalação​

📂 Estrutura do Projeto​

Fluxo de Autenticação de Dispositivo​

Fluxo de Envio de Notificação​

📖 Referência da API​

Autenticação​

Mensagens​

Gerenciamento​

🚀 Deploy​