funifier-mcp 0.2.26 → 0.2.28

package/datasource-funifier-docs/knowledge/guides/java-managers.md

@@ -1,181 +1,233 @@
 # Java Managers — Referência
 
-Os managers são a forma principal de interagir com a plataforma Funifier dentro de **triggers**, **schedulers** e **public endpoints**. Todos estão disponíveis através do objeto `manager` (instância de `ManagerFactory`).
+## 1. Visão Geral
 
----
+### 1.1 O que é este documento
 
-## Como Aceder
+Este documento cataloga os managers da plataforma Funifier — métodos, retornos e quando usar — para operar sobre as entidades em código server-side (triggers, schedulers e public endpoints). Os managers são acessados via o objeto global `manager` (instância de `ManagerFactory`).
 
-```java
-// Dentro de triggers, schedulers e public endpoints:
-manager.getPlayerManager().findById("john");
-manager.getActionManager().track(actionLog);
-manager.getJongoConnection().getCollection("player");
-```
+### 1.2 Quando consultar
+
+- Consulte ao precisar de um **método** para criar/buscar/atualizar uma entidade em código.
+- Consulte ao precisar **registrar uma ação** (`track`/`trackSynchonous`) ou **conceder uma conquista** (`addAchievement`).
+- Consulte ao precisar **creditar/debitar/transferir pontos**, **processar compra**, **executar sorteio/competição**, etc.
+
+### 1.3 Quando NÃO consultar
+
+- **NÃO** consulte para os **campos/tipos** das entidades retornadas — use `datasource-funifier-docs/knowledge/guides/java-entities.md`.
+- **NÃO** consulte para **acesso direto ao banco** (Jongo find/save/aggregate) — use `datasource-funifier-docs/knowledge/guides/database-access.md`.
+- **NÃO** consulte para **bibliotecas utilitárias** (JsonUtil, Guid, DateUtil) — use `java-libraries.md`.
+
+### 1.4 Índice de decisão
+
+| Problema / Situação | Manager | Seção |
+|---|---|---|
+| CRUD de jogador, roles, contagem | PlayerManager | §2 |
+| Registrar ação / contar logs | ActionManager | §3 |
+| Conceder/somar conquistas, status do jogador | AchievementManager | §4 |
+| Loja: comprar, estornar, validar | CatalogManager | §5 |
+| Desafios | ChallengeManager | §6 |
+| Níveis | LevelManager | §7 |
+| Equipes, vínculo de membros | TeamManager | §8 |
+| Pontos: creditar/debitar/transferir | PointManager | §9 |
+| Sorteios | LotteryManager | §10 |
+| Competições | CompetitionManager | §11 |
+| Caixas surpresa | MysteryBoxManager | §12 |
+| Perguntas / Quiz | QuestionManager / QuizManager | §13 |
+| Rankings | LeaderBoardManager | §14 |
+| Notificações | NotificationManager | §15 |
+| Trocas entre jogadores | SwapManager | §16 |
+| Acesso direto ao MongoDB | `getJongoConnection()` | §17 |
+
+### 1.5 Restrições globais críticas
+
+> ⚠️ **Todos os managers são acessíveis nos três runtimes.** `manager.get*Manager()` funciona em Trigger, Scheduler **e** Public Endpoint (`patterns.md` §1.5). Por isso a linha "Disponível em" é omitida nas seções abaixo — é sempre "Todos". O que é bloqueado no Public Endpoint são bibliotecas externas (`Unirest`, `BCrypt`), não os managers.
+
+> ⚠️ **`PlayerManager` não tem `update`/`save`.** `insert(player)` é upsert e é o único ponto de escrita (`patterns.md` §10). Consequência de procurar `pm.save`/`pm.update`: método inexistente. → Use `insert`.
+
+> ⚠️ **`track` ≠ `addLog`.** `track`/`trackSynchonous` processam as regras de gamificação (geram conquistas); `addLog` apenas insere o documento de log **sem** processar regras. Consequência de errar: ou conquistas não são geradas (`addLog`), ou são geradas quando não deviam (`track`). → Escolha pelo efeito desejado (§3).
+
+> ⚠️ **Nunca chame `track`/`trackSynchonous` para a mesma ação que disparou o trigger.** Consequência: loop infinito. → Filtre por `entity.actionId` antes ou use outra ação (`trigger-examples.md` Exemplo 7).
+
+### 1.6 Documentos relacionados
+
+> 📄 `datasource-funifier-docs/knowledge/guides/java-entities.md` — campos/tipos das entidades retornadas
+> 📄 `datasource-funifier-docs/knowledge/guides/database-access.md` — Jongo e `/v3/database`
+> 📄 `datasource-funifier-docs/knowledge/guides/trigger-examples.md` — exemplos de produção que combinam managers
 
 ---
 
-## PlayerManager
+## 2. PlayerManager
 
-Gestão de jogadores (CRUD, busca, atributos, roles).
+Quando usar: criar/buscar/remover jogadores, gerir roles, contar cadastros.
+Não usar quando: precisar dos campos do Player → `java-entities.md` §2.
+Depende de: `Player`, `Principal`.
 
-```java
-// Acesso
-PlayerManager pm = manager.getPlayerManager();
-```
+### Descrição
+
+Gestão de jogadores. Acesso: `manager.getPlayerManager()`.
+
+### Uso
 
 | Método | Retorno | Descrição |
 |--------|---------|-----------|
 | `findById(String id)` | Player | Busca jogador por ID |
 | `findByAlternativeLogin(String login)` | Player | Busca por login alternativo |
-| `findAll()` | Iterable\<Player\> | Lista todos os jogadores |
-| `findRandom(String match, Jongo jongo)` | Player | Jogador aleatório que corresponda ao filtro |
-| `findTotal()` | long | Total de jogadores cadastrados |
-| `findTotalNewUsers(Date start, Date end)` | long | Novos jogadores no período |
-| `insert(Player player)` | void | Cria ou atualiza jogador |
+| `findAll()` | Iterable\<Player\> | Lista todos |
+| `findRandom(String match, Jongo jongo)` | Player | Aleatório que corresponda ao filtro |
+| `findTotal()` | long | Total de jogadores |
+| `findTotalNewUsers(Date start, Date end)` | long | Novos no período |
+| `insert(Player player)` | void | **Cria ou atualiza (upsert) — único ponto de escrita** |
 | `delete(String userId)` | void | Remove jogador e dados relacionados |
-| `reset(String id)` | Player | Remove e recria jogador (zera progresso) |
-| `updateProfileImage(String player, String imageUrl)` | void | Atualiza imagem de perfil |
-| `insertRole(String role, String player)` | Map | Atribui role ao jogador |
-| `removeRole(String role, String player)` | Map | Remove role do jogador |
-| `findPrincipalByUserId(String id)` | Principal | Busca principal por user ID |
-| `findPrincipalByUserOrTeamId(String id)` | Principal | Busca principal por user ou team ID |
-
-**Exemplos:**
+| `reset(String id)` | Player | Remove e recria (zera progresso) |
+| `updateProfileImage(String player, String imageUrl)` | void | Atualiza imagem |
+| `insertRole(String role, String player)` | Map | Atribui role |
+| `removeRole(String role, String player)` | Map | Remove role |
+| `findPrincipalByUserId(String id)` | Principal | Principal por user ID |
+| `findPrincipalByUserOrTeamId(String id)` | Principal | Principal por user ou team ID |
 
 ```java
-// Buscar jogador
+// Buscar
 Player p = manager.getPlayerManager().findById("john");
-String name = p.name;
-String email = p.email;
-Map extra = p.extra; // campos customizados
 
-// Criar jogador
+// Criar/atualizar (read-merge-write — ver patterns.md §10)
 Player newPlayer = new Player();
-newPlayer._id = "maria";
+newPlayer.id = "maria";              // Groovy: .id, não ._id (java-entities.md §1.5)
 newPlayer.name = "Maria Silva";
 newPlayer.email = "maria@email.com";
 newPlayer.extra = new HashMap();
 newPlayer.extra.put("department", "Sales");
 manager.getPlayerManager().insert(newPlayer);
 
-// Contar jogadores
 long total = manager.getPlayerManager().findTotal();
 ```
 
+### Armadilhas conhecidas
+
+- **`pm.save`/`pm.update`** → inexistentes. Correção: `insert` (§1.5).
+- **`pm.find("{}")`** → assinatura inexistente. Correção: `findAll()` (`patterns.md` §10).
+- **`insert` com objeto parcial** → apaga campos. Correção: read-merge-write (`patterns.md` §10).
+
 ---
 
-## ActionManager
+## 3. ActionManager
 
-Registro e gestão de ações executadas pelos jogadores.
+Quando usar: registrar ações de jogadores, contar/consultar logs, gerir definições de ação.
+Não usar quando: precisar dos campos de ActionLog/Action → `java-entities.md` §4–§5.
+Depende de: `ActionLog`, `Action`, `Achievement`.
 
-```java
-ActionManager am = manager.getActionManager();
-```
+### Descrição
+
+Registro e gestão de ações. Acesso: `manager.getActionManager()`.
+
+### Uso
 
 | Método | Retorno | Descrição |
 |--------|---------|-----------|
-| `track(ActionLog action)` | void | Registra ação (assíncrono) |
-| `trackSynchonous(ActionLog action)` | List\<Achievement\> | Registra ação e retorna conquistas (síncrono) |
-| `trackWithRestrictions(ActionLog log, String async)` | Map | Registra com validações ("sync" ou "async") |
-| `findActionById(String id)` | Action | Busca definição de ação |
-| `findActionByIdOrName(String idOrName)` | Action | Busca por ID ou nome |
-| `findAllActions()` | Iterable\<Action\> | Lista todas as ações |
-| `addAction(Action action)` | void | Cria definição de ação |
-| `updateAction(Action action)` | void | Atualiza definição de ação |
-| `deleteAction(String id)` | void | Remove definição de ação |
-| `findActionLogById(String id)` | ActionLog | Busca log de ação por ID |
-| `deleteActionLog(String id)` | void | Remove log de ação |
-| `addLog(ActionLog action)` | void | Insere log diretamente (sem processar regras) |
+| `track(ActionLog action)` | void | Registra e **processa regras** (assíncrono) |
+| `trackSynchonous(ActionLog action)` | List\<Achievement\> | Registra, processa regras e **retorna conquistas** (síncrono) |
+| `trackWithRestrictions(ActionLog log, String async)` | Map | Registra com validações (`"sync"`/`"async"`) |
+| `addLog(ActionLog action)` | void | Insere o log **sem processar regras** (não gera conquistas) |
+| `findActionById(String id)` | Action | Definição da ação |
+| `findActionByIdOrName(String idOrName)` | Action | Por ID ou nome |
+| `findAllActions()` | Iterable\<Action\> | Lista definições |
+| `addAction(Action action)` | void | Cria definição |
+| `updateAction(Action action)` | void | Atualiza definição |
+| `deleteAction(String id)` | void | Remove definição |
+| `findActionLogById(String id)` | ActionLog | Log por ID |
+| `deleteActionLog(String id)` | void | Remove log |
 | `countActionLogsRegisteredByUser(String userId, String typeId)` | long | Conta logs do jogador |
 | `countActionLogsRegisteredBetweenDatesByUser(String userId, String typeId, Date start, Date end)` | long | Conta logs no período |
 | `findLatestActionLogDateRegisteredByUser(String userId, String typeId)` | Date | Data do último log |
 
-**Exemplos:**
+**`track` vs `trackSynchonous` vs `addLog`:**
+- `track` — dispara e não bloqueia; conquistas processadas em background. Use quando não precisa do resultado.
+- `trackSynchonous` — bloqueia e retorna as conquistas geradas. Use quando precisa saber o que foi concedido.
+- `addLog` — só grava o log; **nenhuma** regra roda. Use para registrar histórico sem efeito de gamificação.
 
 ```java
-// Registrar ação (assíncrono — mais rápido)
 ActionLog log = new ActionLog();
-log._id = Guid.newShortGuid();
+log.id = Guid.newShortGuid();        // Groovy: .id
 log.actionId = "sell";
 log.userId = "john";
 log.time = new Date();
 log.attributes = new HashMap();
-log.attributes.put("product", "book");
 log.attributes.put("price", 120);
-manager.getActionManager().track(log);
 
-// Registrar ação (síncrono — retorna conquistas)
-List<Achievement> results = manager.getActionManager().trackSynchonous(log);
-
-// Contar ações de um jogador
-long total = manager.getActionManager().countActionLogsRegisteredByUser("john", "sell");
+manager.getActionManager().track(log);                              // async
+List<Achievement> earned = manager.getActionManager().trackSynchonous(log); // sync
 ```
 
+### Armadilhas conhecidas
+
+- **`track` para a mesma ação que disparou o trigger** → loop infinito (§1.5).
+- **Esperar conquistas do `track`** → ele retorna `void`. Correção: `trackSynchonous`.
+- **`addLog` esperando que conquistas sejam geradas** → não processa regras. Correção: `track`.
+
 ---
 
-## AchievementManager
+## 4. AchievementManager
 
-Gestão de conquistas (pontos, desafios completados, compras, níveis).
+Quando usar: conceder conquistas manualmente, somar pontos/recompensas, consultar status/nível.
+Não usar quando: precisar das constantes `TYPE_*` → `java-entities.md` §3.
+Depende de: `Achievement`, `PlayerStatus`, `Level`, `Requirement`, `Jongo`.
 
-```java
-AchievementManager achm = manager.getAchievementManager();
-```
+### Descrição
+
+Gestão de conquistas. Acesso: `manager.getAchievementManager()`.
+
+### Uso
 
 | Método | Retorno | Descrição |
 |--------|---------|-----------|
 | `addAchievement(Achievement achievement)` | void | Adiciona conquista manualmente |
 | `deleteAchievement(String id)` | void | Remove conquista |
-| `findAchievement(String id, Jongo jongo)` | Achievement | Busca conquista por ID |
+| `findAchievement(String id, Jongo jongo)` | Achievement | Conquista por ID |
 | `findPlayerStatus(String player)` | PlayerStatus | Status completo do jogador |
 | `updatePlayerStatus(String player, Jongo jongo)` | List\<Achievement\> | Recalcula status |
 | `sumTotalRewards(String player, int type, String item, Jongo jongo)` | long | Soma recompensas |
 | `sumTotalPoints(String player, Jongo jongo)` | double | Soma total de pontos |
-| `findLatestLevelAchieved(String player, Jongo jongo)` | Level | Nível atual do jogador |
-| `evaluateRequirements(Requirement[] all, String player)` | boolean | Verifica se cumpre requisitos |
+| `findLatestLevelAchieved(String player, Jongo jongo)` | Level | Nível atual |
+| `evaluateRequirements(Requirement[] all, String player)` | boolean | Verifica requisitos |
 | `deductRequirements(Requirement[] all, String player)` | void | Deduz requisitos (pontos, etc.) |
 | `fireAction(ActionLog trigger)` | List\<Achievement\> | Processa ação e concede conquistas |
 
-**Tipos de Achievement:**
-```java
-Achievement.TYPE_POINT = 0;        // Pontos
-Achievement.TYPE_CHALLENGE = 1;    // Desafio completado
-Achievement.TYPE_VIRTUAL_GOOD = 2; // Item comprado
-Achievement.TYPE_LEVEL = 3;        // Nível alcançado
-```
-
-**Exemplos:**
-
 ```java
-// Dar pontos manualmente
 Achievement a = new Achievement();
-a._id = Guid.newShortGuid();
+a.id = Guid.newShortGuid();          // Groovy: .id
 a.player = "john";
 a.total = 50;
-a.type = Achievement.TYPE_POINT; // 0
+a.type = Achievement.TYPE_POINT;     // ver java-entities.md §3
 a.item = "xp";
 a.time = new Date();
 manager.getAchievementManager().addAchievement(a);
 
-// Consultar saldo de pontos
 Jongo jongo = manager.getJongoConnection();
 long xp = manager.getAchievementManager().sumTotalRewards("john", 0, "xp", jongo);
 ```
 
+### Armadilhas conhecidas
+
+- **`addAchievement` sem `id`/`time`** → registro inconsistente. Correção: setar ambos (`java-entities.md` §3).
+
 ---
 
-## CatalogManager
+## 5. CatalogManager
 
-Gestão da loja virtual (catálogos, itens, compras).
+Quando usar: processar compras, validar requisitos, gerir itens da loja.
+Não usar quando: precisar dos campos de CatalogItem → `java-entities.md` §7.
+Depende de: `CatalogItem`, `Achievement`, `Requirement`, `Principal`, `Jongo`.
 
-```java
-CatalogManager cm = manager.getCatalogManager();
-```
+### Descrição
+
+Gestão da loja virtual. Acesso: `manager.getCatalogManager()`.
+
+### Uso
 
 | Método | Retorno | Descrição |
 |--------|---------|-----------|
-| `findItemById(String id)` | CatalogItem | Busca item por ID |
-| `findAllItems()` | Iterable\<CatalogItem\> | Lista todos os itens |
+| `findItemById(String id)` | CatalogItem | Item por ID |
+| `findAllItems()` | Iterable\<CatalogItem\> | Lista todos |
 | `findAllItemsByCatalogId(String catalogId)` | Iterable\<CatalogItem\> | Itens de um catálogo |
 | `addItem(CatalogItem item)` | void | Adiciona item |
 | `updateItem(CatalogItem item)` | void | Atualiza item |
@@ -183,265 +235,301 @@ CatalogManager cm = manager.getCatalogManager();
 | `purchase(Achievement purchase, boolean async)` | Map | Processa compra |
 | `undoPurchase(String id)` | void | Estorna compra |
 | `findMissingRequirements(String player, String item)` | List\<Requirement\> | Requisitos faltantes |
-| `findValidRandom(String player, String q)` | CatalogItem | Item aleatório válido para o jogador |
-| `isValid(CatalogItem item, int total, String player, Principal principal, Jongo jongo)` | boolean | Valida se jogador pode comprar |
-
-**Exemplos:**
+| `findValidRandom(String player, String q)` | CatalogItem | Item aleatório válido |
+| `isValid(CatalogItem item, int total, String player, Principal principal, Jongo jongo)` | boolean | Valida se pode comprar |
 
 ```java
-// Comprar item para jogador
 Achievement purchase = new Achievement();
-purchase._id = Guid.newShortGuid();
+purchase.id = Guid.newShortGuid();
 purchase.player = "john";
-purchase.item = "DTj7lVn"; // ID do item
+purchase.item = "DTj7lVn";
 purchase.total = 1;
-purchase.type = Achievement.TYPE_VIRTUAL_GOOD; // 2
+purchase.type = Achievement.TYPE_VIRTUAL_GOOD;   // 2
 purchase.time = new Date();
 manager.getCatalogManager().purchase(purchase, true);
-
-// Estornar compra
-manager.getCatalogManager().undoPurchase("achievement_id");
 ```
 
+### Armadilhas conhecidas
+
+- **Comprar sem validar requisitos** → compra inválida pode passar. Correção: `isValid`/`findMissingRequirements` antes.
+
 ---
 
-## ChallengeManager
+## 6. ChallengeManager
 
-Gestão de desafios e missões.
+Quando usar: CRUD de desafios, descrição em linguagem natural.
+Não usar quando: precisar dos campos de Challenge → `java-entities.md` §6.
+Depende de: `Challenge`.
 
-```java
-ChallengeManager chm = manager.getChallengeManager();
-```
+### Descrição
+
+Gestão de desafios e missões. Acesso: `manager.getChallengeManager()`.
+
+### Uso
 
 | Método | Retorno | Descrição |
 |--------|---------|-----------|
-| `findById(String id)` | Challenge | Busca desafio por ID |
-| `findAll()` | Iterable\<Challenge\> | Lista todos os desafios |
-| `add(Challenge challenge)` | void | Cria desafio |
-| `update(Challenge challenge)` | void | Atualiza desafio |
-| `delete(String id)` | void | Remove desafio |
+| `findById(String id)` | Challenge | Desafio por ID |
+| `findAll()` | Iterable\<Challenge\> | Lista todos |
+| `add(Challenge challenge)` | void | Cria |
+| `update(Challenge challenge)` | void | Atualiza |
+| `delete(String id)` | void | Remove |
 | `describe(Challenge challenge, String lang)` | String | Descrição em linguagem natural |
 
+### Armadilhas conhecidas
+
+- **Editar regras via `/v3/database/challenge`** → use o manager (`java-entities.md` §6).
+
 ---
 
-## LevelManager
+## 7. LevelManager
 
-Gestão de níveis de progressão.
+Quando usar: CRUD de níveis, cálculo de nível atual/próximo por pontos.
+Não usar quando: precisar dos campos de Level → `java-entities.md` §8.
+Depende de: `Level`, `LevelConfig`.
 
-```java
-LevelManager lm = manager.getLevelManager();
-```
+### Descrição
+
+Gestão de níveis de progressão. Acesso: `manager.getLevelManager()`.
+
+### Uso
 
 | Método | Retorno | Descrição |
 |--------|---------|-----------|
-| `findById(String id)` | Level | Busca nível por ID |
-| `findAll()` | Iterable\<Level\> | Lista todos os níveis |
+| `findById(String id)` | Level | Nível por ID |
+| `findAll()` | Iterable\<Level\> | Lista todos |
 | `findConfig()` | LevelConfig | Configuração de níveis |
 | `findCurrentByPoints(int points)` | Level | Nível atual para X pontos |
 | `findNextByPoints(int points)` | Level | Próximo nível para X pontos |
-| `add(Level level)` | void | Cria nível |
-| `update(Level level)` | void | Atualiza nível |
-| `delete(String id)` | void | Remove nível |
+| `add(Level level)` | void | Cria |
+| `update(Level level)` | void | Atualiza |
+| `delete(String id)` | void | Remove |
 
 ---
 
-## TeamManager
+## 8. TeamManager
 
-Gestão de equipes e grupos.
+Quando usar: CRUD de equipes, vincular/remover membros, consultar associações.
+Não usar quando: precisar dos campos de Team → `java-entities.md` §8.
+Depende de: `Team`.
 
-```java
-TeamManager tm = manager.getTeamManager();
-```
+### Descrição
+
+Gestão de equipes e grupos. Acesso: `manager.getTeamManager()`.
+
+### Uso
 
 | Método | Retorno | Descrição |
 |--------|---------|-----------|
-| `findById(String id)` | Team | Busca equipe por ID |
-| `findAll()` | Iterable\<Team\> | Lista todas as equipes |
-| `add(Team team)` | void | Cria equipe |
-| `update(Team team)` | void | Atualiza equipe |
-| `delete(String id)` | void | Remove equipe |
-| `linkUser(Team team, String userId)` | void | Vincula jogador à equipe |
-| `removeUsers(String[] userIds, String teamId)` | void | Remove jogadores da equipe |
+| `findById(String id)` | Team | Equipe por ID |
+| `findAll()` | Iterable\<Team\> | Lista todas |
+| `add(Team team)` | void | Cria |
+| `update(Team team)` | void | Atualiza |
+| `delete(String id)` | void | Remove |
+| `linkUser(Team team, String userId)` | void | Vincula jogador |
+| `removeUsers(String[] userIds, String teamId)` | void | Remove jogadores |
 | `findUserIdsByTeamId(String teamId)` | List\<String\> | IDs dos membros |
 | `findTeamIdsByUserId(String userId)` | List\<String\> | Equipes do jogador |
-| `isUserOfTeam(String userId, String teamId)` | boolean | Verifica se é membro |
+| `isUserOfTeam(String userId, String teamId)` | boolean | Verifica membro |
 | `findByUserId(String userId)` | Iterable\<Team\> | Equipes do jogador |
 
+### Armadilhas conhecidas
+
+- **Escrever `player.teams` direto** → use `linkUser` (mantém os índices de associação).
+
 ---
 
-## PointManager
+## 9. PointManager
 
-Gestão de categorias de pontos e operações de crédito/débito.
+Quando usar: creditar/debitar/transferir pontos, CRUD de categorias.
+Não usar quando: precisar dos campos de PointCategory → `java-entities.md` §8.
+Depende de: `PointCategory`, `Point`.
 
-```java
-PointManager ptm = manager.getPointManager();
-```
+### Descrição
+
+Gestão de categorias de pontos e operações de crédito/débito. Acesso: `manager.getPointManager()`.
+
+### Uso
 
 | Método | Retorno | Descrição |
 |--------|---------|-----------|
-| `findById(String id)` | PointCategory | Busca categoria por ID |
+| `findById(String id)` | PointCategory | Categoria por ID |
 | `findAll()` | Iterable\<PointCategory\> | Lista categorias |
-| `add(PointCategory point)` | void | Cria categoria |
-| `update(PointCategory point)` | void | Atualiza categoria |
-| `delete(String id)` | void | Remove categoria |
-| `creditPoints(String categoryId, String userId, int total)` | void | Credita pontos |
-| `debitPoints(String categoryId, String userId, int total)` | void | Debita pontos |
-| `transferPoints(String fromUserId, int total, String categoryId, String toUserId)` | void | Transfere pontos entre jogadores |
+| `add(PointCategory point)` | void | Cria |
+| `update(PointCategory point)` | void | Atualiza |
+| `delete(String id)` | void | Remove |
+| `creditPoints(String categoryId, String userId, int total)` | void | Credita |
+| `debitPoints(String categoryId, String userId, int total)` | void | Debita |
+| `transferPoints(String fromUserId, int total, String categoryId, String toUserId)` | void | Transfere entre jogadores |
 | `findByUserId(String userId)` | Iterable\<Point\> | Pontos do jogador |
 
-**Exemplos:**
-
 ```java
-// Creditar pontos
 manager.getPointManager().creditPoints("xp", "john", 100);
-
-// Transferir pontos entre jogadores
 manager.getPointManager().transferPoints("john", 50, "coins", "maria");
 ```
 
+### Armadilhas conhecidas
+
+- **Confundir crédito de ponto com `addAchievement`** → ambos afetam saldo; `creditPoints` é a via direta para a categoria.
+
 ---
 
-## LotteryManager
+## 10. LotteryManager
 
-Gestão de sorteios e rifas.
+Quando usar: gerir sorteios, adicionar tickets, executar.
+Não usar quando: precisar dos campos de Lottery → `java-entities.md` §9.
+Depende de: `Lottery`, `LotteryTicket`, `Participant`.
 
-```java
-LotteryManager lotm = manager.getLotteryManager();
-```
+### Descrição
+
+Gestão de sorteios e rifas. Acesso: `manager.getLotteryManager()`.
+
+### Uso
 
 | Método | Retorno | Descrição |
 |--------|---------|-----------|
-| `find(String id)` | Lottery | Busca sorteio por ID |
-| `findAll()` | Iterable\<Lottery\> | Lista todos os sorteios |
-| `insert(Lottery lottery)` | void | Cria ou atualiza sorteio |
-| `delete(String id)` | void | Remove sorteio |
-| `insertTicket(LotteryTicket ticket)` | void | Adiciona ticket ao sorteio |
+| `find(String id)` | Lottery | Sorteio por ID |
+| `findAll()` | Iterable\<Lottery\> | Lista todos |
+| `insert(Lottery lottery)` | void | Cria ou atualiza |
+| `delete(String id)` | void | Remove |
+| `insertTicket(LotteryTicket ticket)` | void | Adiciona ticket |
 | `deleteTicket(String id)` | void | Remove ticket |
 | `execute(String id)` | Iterable\<LotteryTicket\> | Executa sorteio |
-| `undoExecute(String id)` | void | Estorna sorteio |
-| `findParticipants(String lottery)` | Iterable\<Participant\> | Participantes do sorteio |
+| `undoExecute(String id)` | void | Estorna |
+| `findParticipants(String lottery)` | Iterable\<Participant\> | Participantes |
 | `checkRestrictions(String lottery, String player)` | List\<String\> | Verifica restrições |
 
 ---
 
-## CompetitionManager
+## 11. CompetitionManager
 
-Gestão de competições entre jogadores.
+Quando usar: gerir competições, inscrever jogadores, executar e premiar.
+Não usar quando: precisar dos campos de Competition → `java-entities.md` §9.
+Depende de: `Competition`, `CompetitionJoin`, `Achievement`.
 
-```java
-CompetitionManager comp = manager.getCompetitionManager();
-```
+### Descrição
+
+Gestão de competições entre jogadores. Acesso: `manager.getCompetitionManager()`.
+
+### Uso
 
 | Método | Retorno | Descrição |
 |--------|---------|-----------|
-| `find(String id)` | Competition | Busca competição por ID |
-| `insert(Competition competition)` | void | Cria ou atualiza competição |
-| `delete(String id)` | void | Remove competição |
+| `find(String id)` | Competition | Competição por ID |
+| `insert(Competition competition)` | void | Cria ou atualiza |
+| `delete(String id)` | void | Remove |
 | `insertJoin(CompetitionJoin join)` | Map | Inscreve jogador |
 | `deleteJoin(CompetitionJoin join)` | void | Remove inscrição |
-| `execute(String id)` | List\<Achievement\> | Executa e premia vencedores |
-| `undoExecute(String id)` | void | Estorna execução |
+| `execute(String id)` | List\<Achievement\> | Executa e premia |
+| `undoExecute(String id)` | void | Estorna |
 | `findLeaders(String id, String range)` | Map | Ranking da competição |
 
 ---
 
-## MysteryBoxManager
+## 12. MysteryBoxManager
 
-Gestão de caixas surpresa.
+Quando usar: gerir e abrir caixas surpresa.
+Não usar quando: precisar dos campos de MysteryBox → `java-entities.md` §9.
+Depende de: `MysteryBox`, `MysteryResult`.
 
-```java
-MysteryBoxManager mb = manager.getMysteryBoxManager();
-```
+### Descrição
+
+Gestão de caixas surpresa. Acesso: `manager.getMysteryBoxManager()`.
+
+### Uso
 
 | Método | Retorno | Descrição |
 |--------|---------|-----------|
-| `find(String id)` | MysteryBox | Busca caixa por ID |
-| `findAll()` | Iterable\<MysteryBox\> | Lista todas as caixas |
-| `insert(MysteryBox mystery)` | void | Cria ou atualiza caixa |
-| `delete(String id)` | void | Remove caixa |
+| `find(String id)` | MysteryBox | Caixa por ID |
+| `findAll()` | Iterable\<MysteryBox\> | Lista todas |
+| `insert(MysteryBox mystery)` | void | Cria ou atualiza |
+| `delete(String id)` | void | Remove |
 | `execute(String id, String player)` | MysteryResult | Abre caixa para jogador |
 | `undoExecute(String achievementId)` | void | Estorna abertura |
 
 ---
 
-## QuestionManager
+## 13. QuestionManager / QuizManager
 
-Gestão de perguntas e respostas.
+Quando usar: gerir perguntas/quizzes e registrar respostas/tentativas.
+Não usar quando: precisar dos campos de Question/Quiz → `java-entities.md` §9.
+Depende de: `Question`, `QuestionLog`, `Quiz`, `QuizLog`.
 
-```java
-QuestionManager qm = manager.getQuestionManager();
-```
+### Descrição
 
-| Método | Retorno | Descrição |
-|--------|---------|-----------|
-| `find(String id)` | Question | Busca pergunta por ID |
-| `insert(Question question)` | List\<String\> | Cria pergunta |
-| `delete(String id)` | void | Remove pergunta |
-| `insertLog(QuestionLog log, String async)` | Map | Registra resposta ("sync"/"async") |
-| `deleteLog(String id)` | void | Remove resposta |
-| `findRandomNotAnsweredForPlayer(String player, String q, String answered_min, String answered_max)` | Question | Pergunta aleatória não respondida |
+Gestão de perguntas (`manager.getQuestionManager()`) e questionários completos (`manager.getQuizManager()`).
 
----
+### Uso
 
-## QuizManager
+**QuestionManager**
 
-Gestão de questionários completos.
+| Método | Retorno | Descrição |
+|--------|---------|-----------|
+| `find(String id)` | Question | Pergunta por ID |
+| `insert(Question question)` | List\<String\> | Cria |
+| `delete(String id)` | void | Remove |
+| `insertLog(QuestionLog log, String async)` | Map | Registra resposta (`"sync"`/`"async"`) |
+| `deleteLog(String id)` | void | Remove resposta |
+| `findRandomNotAnsweredForPlayer(String player, String q, String answered_min, String answered_max)` | Question | Aleatória não respondida |
 
-```java
-QuizManager quizm = manager.getQuizManager();
-```
+**QuizManager**
 
 | Método | Retorno | Descrição |
 |--------|---------|-----------|
-| `find(String id)` | Quiz | Busca quiz por ID |
-| `insert(Quiz quiz)` | void | Cria ou atualiza quiz |
-| `delete(String id)` | void | Remove quiz |
+| `find(String id)` | Quiz | Quiz por ID |
+| `insert(Quiz quiz)` | void | Cria ou atualiza |
+| `delete(String id)` | void | Remove |
 | `startLog(QuizLog log)` | Map | Inicia tentativa |
 | `finishLog(String id, String async)` | Map | Finaliza e calcula pontuação |
 | `deleteLog(String id)` | void | Remove tentativa |
 
 ---
 
-## LeaderBoardManager
+## 14. LeaderBoardManager
 
-Gestão de rankings e classificações.
+Quando usar: CRUD de rankings.
+Não usar quando: precisar de queries de ranking customizadas → `aggregates.md`.
+Depende de: `LeaderBoard_V2`.
 
-```java
-LeaderBoardManager lb = manager.getLeaderBoardManager();
-```
+### Descrição
+
+Gestão de rankings e classificações. Acesso: `manager.getLeaderBoardManager()`.
+
+### Uso
 
 | Método | Retorno | Descrição |
 |--------|---------|-----------|
-| `findById(String id)` | LeaderBoard_V2 | Busca leaderboard por ID |
-| `findAll()` | Iterable\<LeaderBoard_V2\> | Lista todos os leaderboards |
-| `addLeaderboard(LeaderBoard_V2 board)` | void | Cria ou atualiza leaderboard |
-| `delete(String id)` | void | Remove leaderboard |
+| `findById(String id)` | LeaderBoard_V2 | Leaderboard por ID |
+| `findAll()` | Iterable\<LeaderBoard_V2\> | Lista todos |
+| `addLeaderboard(LeaderBoard_V2 board)` | void | Cria ou atualiza |
+| `delete(String id)` | void | Remove |
 
 ---
 
-## NotificationManager
+## 15. NotificationManager
 
-Envio de notificações para jogadores.
+Quando usar: enviar notificações in-app/push, consultar não lidas.
+Não usar quando: precisar enviar **email** → `java-libraries.md` §EmailBuilder.
+Depende de: `Notification`.
 
-```java
-NotificationManager nm = manager.getNotificationManager();
-```
+### Descrição
+
+Envio de notificações para jogadores. Acesso: `manager.getNotificationManager()`.
+
+### Uso
 
 | Método | Retorno | Descrição |
 |--------|---------|-----------|
-| `send(Notification notification)` | void | Envia notificação |
-| `sendPrivate(Notification notification)` | void | Envia notificação privada |
-| `sendPublic(Notification notification)` | void | Envia notificação pública |
-| `receiveNotification(String userId)` | List\<Notification\> | Recebe notificações do jogador |
+| `send(Notification notification)` | void | Envia |
+| `sendPrivate(Notification notification)` | void | Envia privada |
+| `sendPublic(Notification notification)` | void | Envia pública |
+| `receiveNotification(String userId)` | List\<Notification\> | Notificações do jogador |
 | `deleteByPlayer(String player)` | void | Remove notificações do jogador |
 | `totalUnreadPrivateMessages(String player, String published_min, String published_max)` | long | Total de não lidas |
 
-**Exemplos:**
-
 ```java
-// Enviar notificação
 Notification n = new Notification();
-n._id = Guid.newShortGuid();
+n.id = Guid.newShortGuid();          // Groovy: .id
 n.player = "john";
 n.title = "Parabéns!";
 n.message = "Você completou o desafio!";
@@ -451,59 +539,49 @@ manager.getNotificationManager().send(n);
 
 ---
 
-## SwapManager
+## 16. SwapManager
 
-Gestão de trocas entre jogadores.
+Quando usar: gerir ofertas de troca entre jogadores.
+Não usar quando: precisar dos campos de Swap → `java-entities.md` §9.
+Depende de: `Swap`, `SwapCounterOffer`.
 
-```java
-SwapManager sm = manager.getSwapManager();
-```
+### Descrição
+
+Gestão de trocas entre jogadores. Acesso: `manager.getSwapManager()`.
+
+### Uso
 
 | Método | Retorno | Descrição |
 |--------|---------|-----------|
-| `find(String id)` | Swap | Busca troca por ID |
-| `insert(Swap swap, String author)` | Map | Cria oferta de troca |
-| `delete(String id)` | Map | Remove troca |
+| `find(String id)` | Swap | Troca por ID |
+| `insert(Swap swap, String author)` | Map | Cria oferta |
+| `delete(String id)` | Map | Remove |
 | `buyerAcquire(String id, String buyer, String author, Map extra)` | Map | Comprador aceita |
 | `sellerReceive(String id)` | Map | Vendedor recebe |
 | `counterOfferInsert(SwapCounterOffer offer, String author)` | Map | Cria contra-oferta |
 
 ---
 
-## Acesso Direto ao Banco (Jongo)
+## 17. Acesso Direto ao Banco (Jongo)
 
-Além dos managers, é possível acessar o MongoDB diretamente via Jongo.
+Quando usar: ler/escrever coleções sem manager dedicado (ex: `__c`), ou queries/aggregates.
+Não usar quando: existir um manager para a operação → seções acima.
+Depende de: `database-access.md`.
+
+### Descrição
+
+`manager.getJongoConnection()` retorna a conexão Jongo para acesso direto ao MongoDB.
+
+### Uso
+
+> Operações completas (find, save, remove, count, aggregate, placeholders `#`) em **`datasource-funifier-docs/knowledge/guides/database-access.md`** (dono único).
 
 ```java
-// Obter conexão
 Jongo jongo = manager.getJongoConnection();
-
-// Salvar documento
+Object p = jongo.getCollection("player").findOne("{_id: #}", "john").as(Map.class);
 jongo.getCollection("email__c").save(documento);
-
-// Buscar documento
-Object result = jongo.getCollection("player")
-    .findOne("{_id: 'john'}").as(Map.class);
-
-// Buscar com parâmetros
-Object result = jongo.getCollection("product__c")
-    .findOne("{_id: #}", productId).as(Object.class);
-
-// Listar com filtro
-Iterable<Map> items = jongo.getCollection("action_log")
-    .find("{userId: #, actionId: #}", "john", "sell")
-    .as(Map.class);
-
-// Deletar
-jongo.getCollection("car__c").remove("{_id: 'car001'}");
-
-// Aggregate
-Iterable<Map> result = jongo.getCollection("achievement")
-    .aggregate("{$match: {type: 0, item: 'xp'}}")
-    .and("{$group: {_id: '$player', total: {$sum: '$total'}}}")
-    .and("{$sort: {total: -1}}")
-    .and("{$limit: 10}")
-    .as(Map.class);
 ```
 
-> **Referência completa:** consulte `guides/database-access.md` para mais detalhes sobre acesso ao banco de dados.
+### Armadilhas conhecidas
+
+- **Usar Jongo onde há manager** → perde validações de domínio. Prefira o manager quando existir.