funifier-mcp 0.2.26 → 0.2.27

package/datasource-funifier-docs/knowledge/modules/notification.md

@@ -1,40 +1,578 @@
-# Notification (Notificação)
+# `notification`
 
+**Acesso Studio:** Não há página de CRUD dedicada no backend. As notificações automáticas são configuradas como arrays `NotificationDefinition[]` **embutidos em outros módulos** (Challenge/Achievement, Competition, Lottery, Lost, Crowning). O envio manual/avulso é feito exclusivamente via API.
 **API Endpoint:** `/v3/notification`
+**Coleção MongoDB:** `notification`
 
-## O que é
+---
 
-Envio de mensagens automáticas e feedback instantâneo aos jogadores. Permite configurar e disparar notificações personalizadas quando eventos importantes acontecem, como a conclusão de um desafio, o ganho de uma competição ou uma compra na loja virtual. Notificações podem ser configuradas diretamente em diferentes módulos (Challenge, Competition, etc.).
+## 1. Visão Geral
 
-## Quando usar
+O módulo `notify` (pacote `com.funifier.engine.notify`) é a **camada de entrega, persistência e leitura** de mensagens dirigidas a jogadores e ao mural público (newsfeed). Ele **não** decide *quando* uma notificação deve ser gerada — essa decisão pertence aos módulos de negócio (Achievement, Competition, Lottery, etc.), que carregam suas próprias listas de `NotificationDefinition` e chamam `NotificationManager.send(...)` quando um evento ocorre.
 
-- Para parabenizar jogadores por conquistas
-- Para informar sobre prêmios ganhos
-- Para enviar lembretes e feedbacks
-- Para comunicar mudanças de nível
+Papéis arquiteturais:
 
-## Checklist de Configuração
+- **Persistir** cada notificação na coleção `notification` (uma única coleção para mensagens privadas e de newsfeed, diferenciadas pelo campo `definition.scope`).
+- **Renderizar** o texto da mensagem com Mustache no momento do envio (`{{player.name}}`, `{{item.name}}`, etc.).
+- **Disparar push mobile** para notificações privadas, via AWS SNS → APNS/GCM.
+- **Servir leituras** de dois modos: leitura não-destrutiva (agregação com janela temporal) e leitura destrutiva legada (consome-e-apaga).
+
+Problemas que resolve: feedback assíncrono ao jogador (conquistas, prêmios, mudanças de nível), mural de novidades da gamificação (newsfeed) e broadcast manual de mensagens para um segmento de jogadores.
+
+Relação com outros módulos: é um **destino** chamado por managers de negócio. Não chama nenhum módulo de regra de volta — apenas `MobileManagerV3` (push) e `MustacheUtils` (render).
+
+---
+
+## 2. Arquitetura e Fluxos
+
+### 2.1 Classes envolvidas
+
+| Classe | Papel |
+| --- | --- |
+| `com.funifier.engine.notify.Notification` | Entidade/POJO principal — documento raiz da coleção `notification` |
+| `com.funifier.engine.notify.NotificationDefinition` | Sub-entidade: `event`, `type`, `scope`, `content`, `tag`. Implementa `Cloneable`. É também a forma usada para *configurar* notificações dentro de outros módulos |
+| `com.funifier.engine.notify.Item` | Sub-entidade que descreve o `player` e o `item` da notificação |
+| `com.funifier.engine.notify.NotificationManager` | Manager: `send`, push, leitura (`findAll`, `receive`), `deleteByPlayer`, `totalUnreadPrivateMessages` |
+| `com.funifier.engine.notify.NotificationDaoMongo` | DAO Jongo/Mongo. Constante `COLLECTION = "notification"` |
+| `com.funifier.engine.notify.NotificationBuilder` | Builder fluente (uso interno/legado — não exposto na API REST) |
+| `com.funifier.rest.v3.rest.NotificationRest` | Controller REST v3 — `@Path("v3/notification")` |
+| `com.funifier.engine.notify.news.NewsManager` | Wrapper de newsfeed. Em grande parte **código morto** (ver §7) |
+| `com.funifier.engine.notify.news.NewsContainer` | Buffer em memória (`LinkedList` com limite). **Totalmente comentado/morto** |
+| `com.funifier.engine.mobile.MobileManagerV3` | `sendPushNotification` — fan-out de push por device do jogador |
+| `com.funifier.engine.integration.mobile.push.Message` | Payload de push. Título fixo `"Funifier Notification"` |
+| `com.funifier.engine.util.MustacheUtils` | Render do `content` via `com.github.mustachejava` |
+
+### 2.2 Pipeline principal — `NotificationManager.send(Notification n)`
+
+Fluxo síncrono, sem transação:
+
+1. **[Guarda]** `send` só prossegue se `n != null && (n.getPlayer() != null || n.getDefinition().getScope() == SCOPE_NEWSFEED)`. Caso contrário a notificação é **descartada silenciosamente** (sem erro, sem log). Ou seja: uma notificação `private` sem `player` é jogada fora.
+2. **[Render]** `n.getDefinition().setContent(MustacheUtils.parse(content, n))` — o template é renderizado tendo o **próprio objeto `Notification` como contexto raiz**. Se o template lançar exceção, `MustacheUtils.parse` imprime stacktrace e **retorna `null`** → o `content` vira literalmente `null` (ver §7).
+3. **[Timestamp]** `n.timestamp` recebe `ZonedDateTime.now()` no formato `ISO_OFFSET_DATE_TIME` (ex.: `2026-05-20T10:29:35.733-03:00`). O campo `time` (Date) **não** é alterado aqui.
+4. **[Persistência]** `mongo.add(n, jongo)` → se `n.id == null` gera `Guid.newShortGuid()`, depois `collection.save(n)`. `save` é **upsert por `_id`** — ver §4 (POST com `_id` existente sobrescreve).
+5. **[Push]** Se `n.getPlayer() != null`, chama `sendPushNotification(n)` → `MobileManagerV3.sendPushNotification`:
+   - monta `Message(notification)` + `apiKey`;
+   - `findAllDevicesByPlayer(player.id)` → query `{player:#}` na coleção `mobile_device`;
+   - para **cada** device: `awsManager.sendNotification(device, message)` (AWS SNS → APNS/GCM).
+   - Notificações `newsfeed` (sem `player`) **nunca** geram push.
+
+#### Fluxo de envio — `send()`
+
+```mermaid
+flowchart TD
+    A["send(n)"] --> B{"n != null E<br/>(player != null OU scope == NEWSFEED)?"}
+    B -- Não --> Z["Descarte silencioso<br/>(sem erro/log)"]
+    B -- Sim --> C["content = MustacheUtils.parse(content, n)"]
+    C --> D["timestamp = now (ISO_OFFSET_DATE_TIME)"]
+    D --> E["mongo.add(n): gera _id se null + collection.save (UPSERT)"]
+    E --> F{"player != null?"}
+    F -- Não --> G["Fim (apenas persistido)"]
+    F -- Sim --> H["sendPushNotification(n)"]
+    H --> I["findAllDevicesByPlayer(player.id)"]
+    I --> J["para cada device: awsManager.sendNotification(device, message)"]
+```
+
+### 2.3 Interações entre módulos (vista de chamadas)
+
+Os módulos de negócio guardam um array `notifications: NotificationDefinition[]` na própria entidade. Quando ocorre o evento (tipicamente `EVENT_WIN`), eles filtram as definições aplicáveis com `NotificationDefinition.getNotificationsByEvent(...)`, constroem um `Notification(player, item, definition, time)` e chamam `send`.
+
+```mermaid
+sequenceDiagram
+    participant M as Módulo de negócio<br/>(Achievement/Competition/Lottery/...)
+    participant ND as NotificationDefinition
+    participant NM as NotificationManager
+    participant MU as MustacheUtils
+    participant DB as Mongo (notification)
+    participant MB as MobileManagerV3
+    participant AWS as AwsManager (SNS)
+
+    M->>ND: getNotificationsByEvent(EVENT_WIN, def[])
+    ND-->>M: List<NotificationDefinition>
+    M->>NM: send(new Notification(player, item, def, time))
+    NM->>MU: parse(content, notification)
+    MU-->>NM: content renderizado (ou null em erro)
+    NM->>DB: save(notification) [upsert por _id]
+    alt player != null
+        NM->>MB: sendPushNotification(notification)
+        MB->>AWS: sendNotification(device, message) por device
+    end
+```
+
+| Origem (caller de `getNotificationManager().send`) | Quando dispara |
+| --- | --- |
+| `AchievementManager` | Conquista/desafio completado, level-up (constrói `new Notification(player, item, def, new Date())`) |
+| `CompetitionManager` | `EVENT_WIN` — vencedor de competição (`def.clone()`) |
+| `LotteryManager` | `EVENT_WIN` — ganhador de loteria (`def.clone()`) |
+| `LostManager` | `EVENT_WIN` configurado em `lost.notifications` |
+| `CrowningManager` | Mudança de líder em leaderboard (líder atual e anterior) |
+| `CharacterStarManager` | Subiu nível de Character Star |
+| `CatalogManager` | Eventos de catálogo |
+| `LastMileManager` / `BonusManager` | Last Mile / bônus (`send`) |
+| `MSOfficeRest` | Integração legada: **envia** (`send(new Notification(userId, msg))` → privada, `EVENT_WIN`/`TYPE_TEXT` via construtor de 2 args) **e lê** via `receive` (consome‑e‑apaga) |
+
+> Todas as origens acima foram confirmadas chamando `getNotificationManager().send(...)` (exceto a leitura adicional de `MSOfficeRest.receive`).
+
+> Observação: `getNotificationsByEvent` **ignora explicitamente** definições com `scope == SCOPE_CUSTOM (99)` (comentário no código: *"ignora escopo customizado, pois este método antigo é usado em toda a plataforma"*). Logo, notificações com scope custom configuradas em módulos **não são entregues** por esse caminho automático.
+
+### 2.4 Caminhos de leitura
+
+Há **dois** caminhos distintos, com semânticas opostas:
+
+- **Não-destrutivo (REST v3):** `GET /v3/notification` → `NotificationManager.findAll(...)` (agregação Mongo). Não apaga nada (salvo `delete=true`, ver §4).
+- **Destrutivo / consome-e-apaga (legado):** `NotificationManager.receive(userId)` / `receiveNotification(userId)` → `NotificationDaoMongo.findAllByPlayer` retorna as privadas do jogador **e em seguida apaga todas** (`deleteByPlayer`). Usado apenas por `FrontController.receive` (sessão legada) e `MSOfficeRest`. **Não** está em `/v3/notification`.
+
+---
+
+## 3. Estrutura dos Objetos
+
+### 3.1 `Notification` — documento raiz (coleção `notification`)
+
+`@JsonIgnoreProperties(ignoreUnknown=true)` — campos extras enviados no POST são **silenciosamente ignorados** (ver §4).
+
+| Campo | Tipo | Padrão | Obrigatório | Descrição |
+| --- | --- | --- | --- | --- |
+| `_id` | String | `Guid.newShortGuid()` se ausente | Não (auto) | SHORT GUID interno do Funifier (mapeado por `@JsonProperty("_id")`). Não é ObjectId |
+| `player` | `Item` | — | Condicional | Destinatário. **Obrigatório para `private`** (sem ele a notificação é descartada). Ausente em `newsfeed` |
+| `item` | `Item` | — | Não | Objeto de contexto (challenge, action, level, etc.) referenciado pela mensagem |
+| `definition` | `NotificationDefinition` | — | **Sim** | Define `event`, `type`, `scope`, `content`, `tag` |
+| `time` | Date | `new Date()` no POST se ausente | Não (auto) | Timestamp lógico. Usado nos filtros temporais de `findAll` |
+| `timestamp` | String | preenchido em `send()` | Não (auto) | Data ISO‑8601 com offset, gravada no envio. **Variável "automaticamente populada pelo Funifier"** (comentário no código) |
+
+#### Campos computados / não persistidos
+
+- Nenhum campo é puramente computado. `timestamp` é derivado do relógio no `send()` e **é** persistido.
+
+#### Campos aceitos e silenciosamente ignorados
+
+- Qualquer propriedade fora de `_id, player, item, definition, time, timestamp` no corpo do POST é descartada por `@JsonIgnoreProperties(ignoreUnknown=true)`. Não existe campo `read`, `seen`, `userId` ou `read_at` no modelo — enviá-los não faz nada.
+
+### 3.2 `NotificationDefinition` — sub-entidade
+
+`@JsonIgnoreProperties(ignoreUnknown=true)`, `implements Cloneable`.
+
+| Campo | Tipo | Padrão | Obrigatório | Descrição |
+| --- | --- | --- | --- | --- |
+| `event` | int | 0 | Não | Evento que originou a notificação (ver enum) |
+| `type` | int | 0 | Não | Tipo de mídia (ver enum). **Apenas armazenado** — o backend não trata `type` de forma diferenciada |
+| `scope` | int | 0 | Sim (significativo) | `0` private, `1` newsfeed, `99` custom. Define roteamento e persistência |
+| `content` | String | — | **Sim** | Texto da mensagem. Suporta template Mustache (renderizado no `send`) |
+| `tag` | String | — | Não | Rótulo livre para filtro. **Sem null-check** em `getNotifications`/`getRandomNotification` (ver §7) |
+
+#### Enum `event` (`NotificationDefinition.EVENT_*`)
+
+| Valor | Constante | Significado operacional |
+| --- | --- | --- |
+| `0` | `EVENT_WIN` | Ganho/conquista. **Único evento usado pelos disparadores automáticos** via `getNotificationsByEvent(EVENT_WIN, ...)` |
+| `1` | `EVENT_CREATE` | Criação |
+| `2` | `EVENT_CHANGE` | Alteração |
+| `3` | `EVENT_LOSE` | Perda |
+| `4` | `EVENT_REMOVE` | Remoção |
+| `99` | `EVENT_CUSTOM` | **Comentado no código** — não implementado |
+
+#### Enum `type` (`NotificationDefinition.TYPE_*`)
+
+| Valor | Constante | Significado |
+| --- | --- | --- |
+| `0` | `TYPE_TEXT` | Texto |
+| `1` | `TYPE_VIDEO` | Vídeo. Armazenado, mas **sem comportamento de backend** (renderização é responsabilidade do cliente) |
+
+#### Enum `scope` (`NotificationDefinition.SCOPE_*`)
+
+| Valor | Constante | Comportamento |
+| --- | --- | --- |
+| `0` | `SCOPE_PRIVATE` | Mensagem dirigida a um `player`. Gera push. Contabilizada em `totalUnread`. Apagável por jogador |
+| `1` | `SCOPE_NEWSFEED` | Mensagem pública no mural. Sem push. Nunca apagada por `deleteByPlayer` |
+| `99` | `SCOPE_CUSTOM` | Aceito e persistido, mas **excluído** dos disparadores automáticos (`getNotificationsByEvent`) e o mapeamento de `scope` no `GET` nunca produz `99`. Só entregável via `POST /v3/notification` direto |
+
+### 3.3 `Item` — sub-entidade (`player` e `item`)
+
+| Campo | Tipo | Padrão | Obrigatório | Descrição |
+| --- | --- | --- | --- | --- |
+| `id` | String | — | Não | Identificador do jogador ou do item de contexto |
+| `name` | String | — | Não | Nome de exibição |
+| `image` | `Image` | — | Não | Imagem associada |
+| `type` | String | — | Não | Tipo (ver constantes abaixo) |
+| `title` | String | — | Não | Título alternativo. Populado apenas pelo construtor `Item(image, title, content, type)`, **não** usado nos disparadores automáticos |
+| `content` | String | — | Não | Conteúdo alternativo. Mesma observação de `title` |
+
+#### Constantes `Item.TYPE_*`
+
+`player`, `team`, `challenge`, `action`, `level`, `stuff`, `news_feed`, `lottery`, `lost`, `competition`.
+
+### 3.4 Variáveis Mustache disponíveis em `content`
+
+Como o `send()` chama `MustacheUtils.parse(content, notification)`, o **contexto raiz do template é o objeto `Notification`**. Estão acessíveis (entre outros):
+
+- `{{player.id}}`, `{{player.name}}`, `{{player.type}}`
+- `{{item.id}}`, `{{item.name}}`, `{{item.type}}`, `{{item.title}}`, `{{item.content}}`
+- `{{definition.content}}`, `{{definition.tag}}`, `{{definition.event}}`, `{{definition.scope}}`
+- `{{timestamp}}`
+
+> No `POST /v3/notification/send` (modo `private`) o `content` passa por um render adicional **antes** do `send()`, com contexto `{ "player": Player }` — ver §4. Isso significa **dois passes de Mustache** nesse fluxo.
+
+### 3.5 Ciclo de vida de uma notificação privada
+
+```mermaid
+stateDiagram-v2
+    [*] --> Persistida: send() / POST
+    Persistida --> Push: player != null → SNS
+    Push --> Disponivel: aguardando leitura
+    Persistida --> Disponivel
+    Disponivel --> Lida_NaoDestrutiva: GET /v3/notification (continua existindo)
+    Lida_NaoDestrutiva --> Disponivel
+    Disponivel --> Consumida: GET ?delete=true&scope=private OU receive() legado
+    Consumida --> [*]: removida da coleção
+```
+
+---
+
+## 4. Endpoints
+
+Todos sob `@Path("v3/notification")`, `Produces application/json; charset=UTF-8`. Autenticação por Bearer token (`AuthBean`); a `apiKey` extraída do token define o tenant (ver §8).
+
+---
+
+**`GET /v3/notification`** — `findAllLog`
+
+| Aspecto | Detalhe |
+| --- | --- |
+| Finalidade | Consultar notificações (privadas ou de newsfeed) via agregação |
+| Autenticação | Bearer token |
+| Tipo de leitura | **Não-destrutiva** (exceto `delete=true`) |
+
+**Query params:**
+
+| Param | Tipo | Descrição |
+| --- | --- | --- |
+| `player` | String | Id do jogador. `"me"` é resolvido para o jogador do token |
+| `scope` | String | `"private"` → scope `0`. **Qualquer outro valor não-vazio → newsfeed (`1`)**, inclusive typos |
+| `tag` | String | Filtra por `definition.tag` |
+| `delete` | String("true"/"false") | Se `true` **e** `player` informado **e** `scope == "private"`, apaga as privadas do jogador **após** retornar |
+| `fields` | String | Lista separada por vírgula → `$project` na agregação |
+| `published_min` | String | Limite inferior de `time` (RFC 3339 ou keyword tipo `-1d`, `-30m`). **Se omitido, assume `agora − 1 hora`** |
+| `published_max` | String | Limite superior de `time` |
+| `max_results` | String(int) | Máximo de resultados. `<= 0` ou inválido → **`10`** |
+
+**Comportamento real:**
+
+- A agregação sempre inicia com `{ $match : { _id: {$exists:true} ...} }` e ordena por `{$sort : {time : -1}}`.
+- **Armadilha do `published_min`:** sem ele, só retorna a **última 1 hora**. Notificações mais antigas "somem" da resposta sem aviso.
+- O parâmetro `delete=true` é a única forma de "marcar como lida" via REST — ele **apaga** os registros privados do jogador.
+
+```json
+[
+  {
+    "player": { "id": "ricardo@funifier.com", "name": "Ricardo", "type": "player" },
+    "item": { "id": "578052b75a73038c5f3d0e77", "name": "Visit", "type": "action" },
+    "definition": { "event": 0, "type": 0, "scope": 1, "content": "Ricardo visited us" },
+    "timestamp": "2026-05-20T10:29:35.733-03:00"
+  }
+]
+```
+
+---
+
+**`GET /v3/notification/totalUnread`** — `totalUnread`
+
+| Aspecto | Detalhe |
+| --- | --- |
+| Finalidade | Contar notificações **privadas** (interpretadas como "não lidas") |
+| Autenticação | Bearer token |
+
+**Query params:** `player` (`"me"` resolvido pelo token), `published_min`, `published_max`.
+
+**Comportamento real:** executa `count` em `{ definition.scope: 0 [, player.id: ...] [, time: {$gte/$lte ...}] }`. "Não lida" = simplesmente uma privada que ainda existe na coleção (não há flag de leitura). Diferente do `GET`, **não** aplica a janela default de 1 hora.
+
+```json
+{ "total": 7 }
+```
+
+---
+
+**`POST /v3/notification`** — `insert`
+
+| Aspecto | Detalhe |
+| --- | --- |
+| Finalidade | Criar/enviar **uma** notificação avulsa |
+| Autenticação | Bearer token |
+| Full replace ou patch | **Upsert por `_id`** — POST com `_id` existente **sobrescreve** o documento inteiro (não retorna 409) |
 
-- [ ] Definir mensagem da notificação
-- [ ] Vincular ao módulo que dispara a notificação (challenge, competition, etc.)
-- [ ] Definir tipo de notificação (push, in-app, email)
+**Comportamento real:**
 
-## API Endpoints
+- Se `time == null` → `new Date()`. Se `id == null` → `Guid.newShortGuid()`.
+- Chama `send()` (toda a §2.2 se aplica: guarda, Mustache, timestamp, push).
+- Campos desconhecidos no corpo são ignorados (`@JsonIgnoreProperties`).
+- Retorna `201 CREATED` com o objeto (sem campos nulos).
 
-### Listar Notificações
-**Método:** GET
-**Endpoint:** `/v3/notification`
+```json
+POST /v3/notification
+{
+  "player": { "id": "ricardo@funifier.com", "name": "Ricardo", "type": "player" },
+  "item":   { "id": "578052b75a73038c5f3d0e77", "name": "Visit", "type": "action" },
+  "definition": { "event": 0, "type": 0, "scope": 0, "content": "Olá {{player.name}}!" }
+}
+```
 
-### Criar Notificação
-**Método:** POST
-**Endpoint:** `/v3/notification`
+---
 
-### Deletar Notificação
-**Método:** DELETE
-**Endpoint:** `/v3/notification/:id`
+**`POST /v3/notification/send`** — `send` (broadcast)
 
-## Validações e Testes
+| Aspecto | Detalhe |
+| --- | --- |
+| Finalidade | Disparar a mesma mensagem para um segmento de jogadores **ou** para o newsfeed |
+| Autenticação | Bearer token |
+| Limite | **Máximo 1000 jogadores** por chamada (`findAllPlayers(..., 1000)`) |
+
+**Corpo:** um `NotificationDefinition` (não um `Notification`).
+
+**Query params:**
+
+| Param | Tipo | Descrição |
+| --- | --- | --- |
+| `to` | String | Critério de query Mongo aplicado à coleção `player` (ex.: `extra.gender:"male"`). **Obrigatório no modo privado**. Query raw — ver §8 |
+| `when` | String | RFC 3339 ou keyword (`+1d`, `+30m`). Default = agora |
+
+**Comportamento real:**
+
+- Validação: `content` vazio → `400` `"You must define a message"`. `to` vazio → `400` `"You must define a to query criteria"`.
+- **Modo newsfeed** (`scope == 1`): cria **uma** notificação sem `player` e envia. Retorna `ids: ["newsfeed"]`.
+- **Modo privado** (qualquer outro scope): itera os players que casam com `to` (até 1000); para cada um faz `content = MustacheUtils.parse(content, {player})` (1º passe) e `send()` re-renderiza (2º passe). Define `player = Item(player.id, player.name, player.image, null)`.
+- **`when` NÃO adia a entrega.** O valor é convertido em Date e gravado em `notification.time`, mas o `send()` persiste e dispara push **imediatamente**. Não há scheduler que leia a coleção `notification` e entregue depois (nenhum encontrado no código). Notificações com `time` futuro aparecem nas leituras de newsfeed de imediato (o `GET` não impõe limite superior de tempo por default).
+
+```json
+{ "to": "extra.gender:\"male\"", "ids": ["a@x.com","b@x.com"], "when": "+1d", "total": 2 }
+```
+
+> **Ausência de DELETE:** **não existe** `DELETE /v3/notification/:id` (nem qualquer `@DELETE`) neste controller. Qualquer documentação que o mencione está incorreta. A remoção só ocorre via `GET ?delete=true&scope=private` (em massa, por jogador) ou pelo caminho legado `receive()`.
+
+---
+
+## 5. Regras de Negócio
+
+Regras presentes no código mas não evidentes no schema:
+
+- **Privada exige `player`.** `send()` descarta silenciosamente uma notificação `private` sem `player`. Newsfeed dispensa `player`.
+- **Render é obrigatório e pode zerar o conteúdo.** Todo `content` passa por Mustache no envio; template inválido → `content == null` (sem erro propagado).
+- **Push só para privadas com `player`.** Newsfeed nunca gera push; privadas geram um push **por device** registrado do jogador.
+- **Janela temporal implícita.** `findAll` sem `published_min` retorna apenas a última 1 hora; `max_results` default 10.
+- **Mapeamento de scope no GET é binário.** Só `"private"` é tratado como privado; tudo mais cai em newsfeed.
+- **`delete=true` é condicional.** Só apaga se `player != null` **e** `scope == "private"`.
+- **Custom scope é ignorado pelos disparadores.** `getNotificationsByEvent` exclui `SCOPE_CUSTOM`.
+- **Multi-tenant por `apiKey`.** Cada gamificação resolve `FrontController.getInstance(apiKey).getManagerFactory()` → conexão Jongo isolada. Notificações nunca cruzam tenants.
+- **Consistência:** sem transação. A persistência ocorre antes do push; falha de push não desfaz a gravação.
+
+---
+
+## 6. Comportamentos Automáticos
+
+| Comportamento | Trigger | Impacto | Persistência |
+| --- | --- | --- | --- |
+| Geração de notificação | `EVENT_WIN` em Achievement/Competition/Lottery/Lost/Crowning/... | Cria `Notification(player, item, def, time)` e chama `send()` | Sim (coleção `notification`) |
+| Render Mustache | Todo `send()` | `content` renderizado contra o `Notification` | Sim (conteúdo final gravado) |
+| Stamp de `timestamp` | Todo `send()` | Grava data ISO no envio | Sim |
+| Push mobile | `send()` com `player != null` | 1 push por device via AWS SNS | Não (transporte) |
+| Consumo destrutivo | `receive()` / `GET ?delete=true&scope=private` | Lê e **apaga** as privadas do jogador | Sim (remoção) |
+| Limpeza no clone de gamificação | `GameManager` com `removeLogs=true` | **Dropa a coleção `notification` inteira** (e a exclui do clone remoto) | Sim (destrutivo) |
+| Cascade na exclusão de player | `PlayerDaoMongo.delete` | Tenta `remove("{userId:#}", userId)` — **mas o campo é `player.id`, não `userId`** → nenhum documento casa | Inefetiva (ver §7) |
+
+#### Fluxo dos disparadores automáticos
+
+```mermaid
+flowchart TD
+    A["Evento de negócio (ex.: desafio completo)"] --> B["getNotificationsByEvent(EVENT_WIN, def[])"]
+    B --> C{"scope == CUSTOM (99)?"}
+    C -- Sim --> X["Ignorado pelo disparador"]
+    C -- Não --> D["new Notification(player, item, def, time)"]
+    D --> E["NotificationManager.send(n)"]
+    E --> F["persiste + push (ver §2.2)"]
+```
+
+---
+
+## 7. Suportado vs NÃO Suportado
+
+### ✅ Suportado
+
+- Persistência de notificações privadas e de newsfeed na coleção `notification`.
+- Render de `content` com Mustache (variáveis em §3.4).
+- Push mobile para privadas (AWS SNS → APNS/GCM), um por device registrado.
+- Leitura paginada/filtrada via `GET /v3/notification` (player, scope, tag, janela temporal, `fields`, `max_results`).
+- Contagem de privadas via `GET /v3/notification/totalUnread`.
+- Criação avulsa (`POST /v3/notification`) e broadcast por segmento ou newsfeed (`POST /v3/notification/send`).
+- Remoção em massa por jogador via `GET ?delete=true&scope=private` e caminho legado `receive()`.
+- Isolamento multi-tenant por `apiKey`.
+
+### ❌ NÃO Suportado
+
+- **`DELETE /v3/notification/:id`** — não existe. Nenhum `@DELETE` no controller.
+- **Agendamento real (`when`)** — o parâmetro não adia entrega; só carimba `time`. Push e persistência são imediatos.
+- **Notificações com `scope == CUSTOM (99)` via disparadores automáticos** — excluídas por `getNotificationsByEvent`. Só entregam por POST direto.
+- **`EVENT_CUSTOM (99)`** — constante comentada, não implementada.
+- **Tratamento diferenciado por `TYPE_VIDEO`** — `type` é apenas armazenado.
+- **Flag de leitura/`read`** — não há campo de "lido". "Não lida" = privada ainda existente.
+- **Cascade de exclusão de notificações ao apagar um player** — `PlayerDaoMongo.delete` usa `remove("{userId:#}", userId)`, mas o documento referencia o jogador por `player.id`. O campo `userId` é **legado** (consta no comentário de schema do método) e **não existe mais** no objeto. Resultado: **notificações órfãs** permanecem após exclusão do jogador.
+- **`NewsContainer`** — buffer em memória totalmente comentado/morto.
+- **`NewsManager.findAllAfterDate`** — não está ligado a nenhuma rota REST; leitura de newsfeed ocorre por `findAll`.
+
+### Delimitação — subpacote `notify/theme/` (fora de escopo deste módulo)
+
+O pacote `com.funifier.engine.notify` contém um subpacote `theme/` (`ThemeNotify`, `ThemeNotifyConfig`, `ThemeGalleryNotify`, `ThemeNotifyConfigManager`, `ThemeNotifyDaoMongo`) que **não tem relação com o sistema de mensagens/notificações** documentado aqui. Trata-se de **theming visual de widgets** (CSS, script, gallery), persistido em coleções próprias — `theme_notify`, `theme_config_notify`, `theme_gallery_notify` — e **nunca toca** a coleção `notification` nem o `NotificationManager`. Está documentado em outro contexto (widgets/temas); citado apenas para que a leitura do pacote não pareça omissa.
+
+### Comportamentos confusos / legado relevante
+
+- **NPE por `tag` nula:** `getNotifications(...)` e `getRandomNotification(...)` fazem `n.tag.indexOf(tag)` sem null-check. Se um filtro `tag` for passado e **qualquer** definição tiver `tag == null`, lança `NullPointerException`.
+- **Mustache silencioso:** falha de template → stacktrace no stdout + `content = null`.
+- **Duplo render:** no `POST /send` privado, `content` é renderizado duas vezes (uma com `{player}`, outra no `send()`).
+- **`send()` em `NotificationManager` tem grande bloco comentado** (V1 de push via SNS/`Device`, observers `setChanged/notifyObservers`, `sendPrivate/sendPublic`) — arquitetura antiga desativada.
+
+---
+
+## 8. Segurança e Permissões
+
+### Autenticação e autorização
+
+- Todas as rotas exigem **Bearer token** (`@BeanParam AuthBean`).
+- `player == "me"` é resolvido para o jogador do token (`authBean.getPlayerFromTokenIfExist()`).
+- A `apiKey` do token determina o tenant: `FrontController.getInstance(authBean.getApiKey())`.
+
+### Isolamento multi-tenant
+
+- Cada gamificação tem sua própria conexão Jongo (`manager.getJongoConnection()`), portanto a coleção `notification` é fisicamente separada por tenant. Não há filtro de `apiKey` dentro das queries — o isolamento é garantido pela conexão.
+
+### Superfícies de injeção
+
+- **`to` em `POST /send` é query Mongo raw** aplicada à coleção `player` (`findAllPlayers(..., to, ...)`). Um valor malicioso pode injetar **operadores** Mongo (ex.: `$where`, seleção ampla) para atingir jogadores não pretendidos. Não há sanitização visível neste caminho.
+- **Template injection:** `content` é renderizado no servidor com Mustache tendo o `Notification` (e, no `/send`, o `Player`) como contexto. Mustache é lógica-less, mas conteúdo controlado externamente pode **vazar campos** do objeto de contexto (`{{player.*}}`). Trate `content` de origem não confiável com cuidado.
+- **Sem rate limit explícito** no envio além do teto de 1000 jogadores por `/send`.
+
+---
+
+## 9. Observabilidade e Troubleshooting
+
+### Diagnóstico básico
+
+- A notificação foi persistida? Consulte a coleção `notification` por `_id` ou `player.id`.
+- O push não chegou? Verifique se há devices em `mobile_device` para `player.id` (`{player: "<id>"}`). Sem device → sem push, sem erro.
+- A mensagem chegou com `null`? Template Mustache inválido (ver stacktrace no log do serviço).
+
+### Queries úteis (mongosh)
+
+```javascript
+// Privadas de um jogador
+db.notification.find({ "definition.scope": 0, "player.id": "ricardo@funifier.com" }).sort({ time: -1 })
+
+// Mural (newsfeed) recente
+db.notification.find({ "definition.scope": 1 }).sort({ time: -1 }).limit(10)
+
+// Contagem de "não lidas" (privadas) de um jogador
+db.notification.count({ "definition.scope": 0, "player.id": "ricardo@funifier.com" })
+
+// Notificações com conteúdo nulo (suspeita de Mustache quebrado)
+db.notification.find({ "definition.content": null })
+
+// Notificações órfãs (jogador já excluído) — checar manualmente, pois a cascade por {userId} não as remove
+db.notification.find({ "definition.scope": 0 }).forEach(n => { /* validar player.id contra a coleção player */ })
+
+// Devices de um jogador (diagnóstico de push)
+db.mobile_device.find({ player: "ricardo@funifier.com" })
+```
+
+### Comandos HTTP úteis
+
+```
+GET  /v3/notification?player=me&scope=private&published_min=-7d&max_results=50
+GET  /v3/notification?scope=newsfeed&published_min=-1d
+GET  /v3/notification/totalUnread?player=me
+POST /v3/notification          (corpo: Notification)
+POST /v3/notification/send?to=extra.dept:"sales"&when=+0m   (corpo: NotificationDefinition)
+```
+
+### Erros comuns e causas
+
+| Sintoma | Causa provável |
+| --- | --- |
+| `GET` retorna vazio mas há dados | `published_min` omitido → janela de **1 hora**. Informe `published_min` |
+| Notificação `private` "não foi criada" | `player` ausente → descartada silenciosamente em `send()` |
+| `content` chega como `null` | Template Mustache inválido (`MustacheUtils.parse` retornou null) |
+| `scope=public` virou newsfeed | Mapeamento aceita só `"private"`; qualquer outro valor → newsfeed |
+| Push não enviado | Nenhum device em `mobile_device` para o `player.id`, ou notificação é newsfeed |
+| `500` ao filtrar por `tag` | Alguma `NotificationDefinition` com `tag == null` (NPE em `indexOf`) |
+| `?delete=true` não apagou | Faltou `player` ou `scope` diferente de `"private"` |
+
+---
+
+## 10. Exemplos Práticos
+
+### 10.1 Exemplo mínimo — mensagem privada para um jogador
+
+```json
+POST /v3/notification
+{
+  "player": { "id": "ricardo@funifier.com", "type": "player" },
+  "definition": { "scope": 0, "content": "Bem-vindo de volta!" }
+}
+```
+
+`scope: 0` (privada) + `player` presente → persiste e dispara push para os devices do jogador.
+
+### 10.2 Exemplo avançado — mensagem privada personalizada com contexto
+
+```json
+POST /v3/notification
+{
+  "player": { "id": "ricardo@funifier.com", "name": "Ricardo", "type": "player" },
+  "item":   { "id": "578052b75a73038c5f3d0e77", "name": "Visit", "type": "action" },
+  "definition": {
+    "event": 0,
+    "type": 0,
+    "scope": 0,
+    "tag": "welcome",
+    "content": "Parabéns {{player.name}}! Você concluiu {{item.name}}."
+  }
+}
+```
+
+O `content` é renderizado para `"Parabéns Ricardo! Você concluiu Visit."` no envio.
+
+### 10.3 Exemplo avançado — broadcast segmentado
+
+```
+POST /v3/notification/send?to=extra.dept:"sales"&when=+0m
+```
+```json
+{ "scope": 0, "content": "Olá {{player.name}}, sua meta foi atualizada." }
+```
+
+Envia para até 1000 jogadores do segmento `extra.dept = "sales"`, renderizando o nome por jogador. Para o mural público, use `"scope": 1` (o `to` é ignorado e gera uma única entrada de newsfeed).
+
+### 10.4 Anti-pattern — usar `when` esperando agendamento
+
+```
+POST /v3/notification/send?to=...&when=+1d   ❌
+```
+
+**Por quê é errado:** `when` **não adia** nada. A notificação é persistida e o push é disparado imediatamente; `when` só define o campo `time` (que pode até ficar no futuro, mas a entrega já aconteceu). Não confie nisso para campanhas agendadas.
+
+### 10.5 Anti-pattern — criar notificação privada sem `player`
+
+```json
+POST /v3/notification
+{ "definition": { "scope": 0, "content": "mensagem" } }   ❌
+```
+
+**Por quê é errado:** sem `player`, a guarda de `send()` **descarta a notificação silenciosamente**. A resposta pode parecer `201`, mas nada é persistido nem entregue. Para mensagem pública use `scope: 1`.
+
+---
+
+## Checklist de Configuração
 
-- [ ] Notificação é disparada ao completar evento
-- [ ] Mensagem chega corretamente ao jogador
-- [ ] Variáveis dinâmicas são substituídas (nome, pontos, etc.)
+- [ ] `definition.content` preenchido (vazio → `400` no `/send`; ignorado no `POST` direto).
+- [ ] Para `scope: 0` (privada): `player.id` presente — senão é descartada silenciosamente.
+- [ ] Para personalizar com Mustache, usar apenas variáveis do contexto `Notification` (§3.4).
+- [ ] Garantir que toda `NotificationDefinition` filtrável tenha `tag` definida (evita NPE em filtros por `tag`).
+- [ ] Em leituras, **sempre** informar `published_min` — caso contrário só vê a última 1 hora.
+- [ ] Não esperar agendamento de `when`: a entrega é imediata.
+- [ ] Não esperar `DELETE /v3/notification/:id`: use `GET ?delete=true&scope=private`.
+- [ ] Para push: confirmar que o jogador tem device registrado em `mobile_device`.
+- [ ] Lembrar que `POST` com `_id` existente **sobrescreve** o documento (upsert).
+- [ ] Notificações de jogadores excluídos ficam órfãs (cascade por `userId` é inefetiva) — limpar manualmente se necessário.