funifier-mcp 0.2.0 → 0.2.4

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

@@ -1,509 +1,509 @@
-# 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`).
-
----
-
-## Como Aceder
-
-```java
-// Dentro de triggers, schedulers e public endpoints:
-manager.getPlayerManager().findById("john");
-manager.getActionManager().track(actionLog);
-manager.getJongoConnection().getCollection("player");
-```
-
----
-
-## PlayerManager
-
-Gestão de jogadores (CRUD, busca, atributos, roles).
-
-```java
-// Acesso
-PlayerManager pm = manager.getPlayerManager();
-```
-
-| 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 |
-| `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:**
-
-```java
-// Buscar jogador
-Player p = manager.getPlayerManager().findById("john");
-String name = p.name;
-String email = p.email;
-Map extra = p.extra; // campos customizados
-
-// Criar jogador
-Player newPlayer = new Player();
-newPlayer._id = "maria";
-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();
-```
-
----
-
-## ActionManager
-
-Registro e gestão de ações executadas pelos jogadores.
-
-```java
-ActionManager am = manager.getActionManager();
-```
-
-| 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) |
-| `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:**
-
-```java
-// Registrar ação (assíncrono — mais rápido)
-ActionLog log = new ActionLog();
-log._id = Guid.newShortGuid();
-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");
-```
-
----
-
-## AchievementManager
-
-Gestão de conquistas (pontos, desafios completados, compras, níveis).
-
-```java
-AchievementManager achm = manager.getAchievementManager();
-```
-
-| 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 |
-| `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 |
-| `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.player = "john";
-a.total = 50;
-a.type = Achievement.TYPE_POINT; // 0
-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);
-```
-
----
-
-## CatalogManager
-
-Gestão da loja virtual (catálogos, itens, compras).
-
-```java
-CatalogManager cm = manager.getCatalogManager();
-```
-
-| Método | Retorno | Descrição |
-|--------|---------|-----------|
-| `findItemById(String id)` | CatalogItem | Busca item por ID |
-| `findAllItems()` | Iterable\<CatalogItem\> | Lista todos os itens |
-| `findAllItemsByCatalogId(String catalogId)` | Iterable\<CatalogItem\> | Itens de um catálogo |
-| `addItem(CatalogItem item)` | void | Adiciona item |
-| `updateItem(CatalogItem item)` | void | Atualiza item |
-| `deleteItem(String id)` | void | Remove item |
-| `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:**
-
-```java
-// Comprar item para jogador
-Achievement purchase = new Achievement();
-purchase._id = Guid.newShortGuid();
-purchase.player = "john";
-purchase.item = "DTj7lVn"; // ID do item
-purchase.total = 1;
-purchase.type = Achievement.TYPE_VIRTUAL_GOOD; // 2
-purchase.time = new Date();
-manager.getCatalogManager().purchase(purchase, true);
-
-// Estornar compra
-manager.getCatalogManager().undoPurchase("achievement_id");
-```
-
----
-
-## ChallengeManager
-
-Gestão de desafios e missões.
-
-```java
-ChallengeManager chm = manager.getChallengeManager();
-```
-
-| 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 |
-| `describe(Challenge challenge, String lang)` | String | Descrição em linguagem natural |
-
----
-
-## LevelManager
-
-Gestão de níveis de progressão.
-
-```java
-LevelManager lm = manager.getLevelManager();
-```
-
-| Método | Retorno | Descrição |
-|--------|---------|-----------|
-| `findById(String id)` | Level | Busca nível por ID |
-| `findAll()` | Iterable\<Level\> | Lista todos os níveis |
-| `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 |
-
----
-
-## TeamManager
-
-Gestão de equipes e grupos.
-
-```java
-TeamManager tm = manager.getTeamManager();
-```
-
-| 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 |
-| `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 |
-| `findByUserId(String userId)` | Iterable\<Team\> | Equipes do jogador |
-
----
-
-## PointManager
-
-Gestão de categorias de pontos e operações de crédito/débito.
-
-```java
-PointManager ptm = manager.getPointManager();
-```
-
-| Método | Retorno | Descrição |
-|--------|---------|-----------|
-| `findById(String id)` | PointCategory | Busca 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 |
-| `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");
-```
-
----
-
-## LotteryManager
-
-Gestão de sorteios e rifas.
-
-```java
-LotteryManager lotm = manager.getLotteryManager();
-```
-
-| 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 |
-| `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 |
-| `checkRestrictions(String lottery, String player)` | List\<String\> | Verifica restrições |
-
----
-
-## CompetitionManager
-
-Gestão de competições entre jogadores.
-
-```java
-CompetitionManager comp = manager.getCompetitionManager();
-```
-
-| 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 |
-| `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 |
-| `findLeaders(String id, String range)` | Map | Ranking da competição |
-
----
-
-## MysteryBoxManager
-
-Gestão de caixas surpresa.
-
-```java
-MysteryBoxManager mb = manager.getMysteryBoxManager();
-```
-
-| 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 |
-| `execute(String id, String player)` | MysteryResult | Abre caixa para jogador |
-| `undoExecute(String achievementId)` | void | Estorna abertura |
-
----
-
-## QuestionManager
-
-Gestão de perguntas e respostas.
-
-```java
-QuestionManager qm = manager.getQuestionManager();
-```
-
-| 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 |
-
----
-
-## QuizManager
-
-Gestão de questionários completos.
-
-```java
-QuizManager quizm = manager.getQuizManager();
-```
-
-| 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 |
-| `startLog(QuizLog log)` | Map | Inicia tentativa |
-| `finishLog(String id, String async)` | Map | Finaliza e calcula pontuação |
-| `deleteLog(String id)` | void | Remove tentativa |
-
----
-
-## LeaderBoardManager
-
-Gestão de rankings e classificações.
-
-```java
-LeaderBoardManager lb = manager.getLeaderBoardManager();
-```
-
-| 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 |
-
----
-
-## NotificationManager
-
-Envio de notificações para jogadores.
-
-```java
-NotificationManager nm = manager.getNotificationManager();
-```
-
-| 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 |
-| `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.player = "john";
-n.title = "Parabéns!";
-n.message = "Você completou o desafio!";
-n.time = new Date();
-manager.getNotificationManager().send(n);
-```
-
----
-
-## SwapManager
-
-Gestão de trocas entre jogadores.
-
-```java
-SwapManager sm = manager.getSwapManager();
-```
-
-| 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 |
-| `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)
-
-Além dos managers, é possível acessar o MongoDB diretamente via Jongo.
-
-```java
-// Obter conexão
-Jongo jongo = manager.getJongoConnection();
-
-// Salvar documento
-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.
+# 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`).
+
+---
+
+## Como Aceder
+
+```java
+// Dentro de triggers, schedulers e public endpoints:
+manager.getPlayerManager().findById("john");
+manager.getActionManager().track(actionLog);
+manager.getJongoConnection().getCollection("player");
+```
+
+---
+
+## PlayerManager
+
+Gestão de jogadores (CRUD, busca, atributos, roles).
+
+```java
+// Acesso
+PlayerManager pm = manager.getPlayerManager();
+```
+
+| 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 |
+| `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:**
+
+```java
+// Buscar jogador
+Player p = manager.getPlayerManager().findById("john");
+String name = p.name;
+String email = p.email;
+Map extra = p.extra; // campos customizados
+
+// Criar jogador
+Player newPlayer = new Player();
+newPlayer._id = "maria";
+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();
+```
+
+---
+
+## ActionManager
+
+Registro e gestão de ações executadas pelos jogadores.
+
+```java
+ActionManager am = manager.getActionManager();
+```
+
+| 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) |
+| `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:**
+
+```java
+// Registrar ação (assíncrono — mais rápido)
+ActionLog log = new ActionLog();
+log._id = Guid.newShortGuid();
+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");
+```
+
+---
+
+## AchievementManager
+
+Gestão de conquistas (pontos, desafios completados, compras, níveis).
+
+```java
+AchievementManager achm = manager.getAchievementManager();
+```
+
+| 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 |
+| `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 |
+| `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.player = "john";
+a.total = 50;
+a.type = Achievement.TYPE_POINT; // 0
+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);
+```
+
+---
+
+## CatalogManager
+
+Gestão da loja virtual (catálogos, itens, compras).
+
+```java
+CatalogManager cm = manager.getCatalogManager();
+```
+
+| Método | Retorno | Descrição |
+|--------|---------|-----------|
+| `findItemById(String id)` | CatalogItem | Busca item por ID |
+| `findAllItems()` | Iterable\<CatalogItem\> | Lista todos os itens |
+| `findAllItemsByCatalogId(String catalogId)` | Iterable\<CatalogItem\> | Itens de um catálogo |
+| `addItem(CatalogItem item)` | void | Adiciona item |
+| `updateItem(CatalogItem item)` | void | Atualiza item |
+| `deleteItem(String id)` | void | Remove item |
+| `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:**
+
+```java
+// Comprar item para jogador
+Achievement purchase = new Achievement();
+purchase._id = Guid.newShortGuid();
+purchase.player = "john";
+purchase.item = "DTj7lVn"; // ID do item
+purchase.total = 1;
+purchase.type = Achievement.TYPE_VIRTUAL_GOOD; // 2
+purchase.time = new Date();
+manager.getCatalogManager().purchase(purchase, true);
+
+// Estornar compra
+manager.getCatalogManager().undoPurchase("achievement_id");
+```
+
+---
+
+## ChallengeManager
+
+Gestão de desafios e missões.
+
+```java
+ChallengeManager chm = manager.getChallengeManager();
+```
+
+| 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 |
+| `describe(Challenge challenge, String lang)` | String | Descrição em linguagem natural |
+
+---
+
+## LevelManager
+
+Gestão de níveis de progressão.
+
+```java
+LevelManager lm = manager.getLevelManager();
+```
+
+| Método | Retorno | Descrição |
+|--------|---------|-----------|
+| `findById(String id)` | Level | Busca nível por ID |
+| `findAll()` | Iterable\<Level\> | Lista todos os níveis |
+| `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 |
+
+---
+
+## TeamManager
+
+Gestão de equipes e grupos.
+
+```java
+TeamManager tm = manager.getTeamManager();
+```
+
+| 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 |
+| `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 |
+| `findByUserId(String userId)` | Iterable\<Team\> | Equipes do jogador |
+
+---
+
+## PointManager
+
+Gestão de categorias de pontos e operações de crédito/débito.
+
+```java
+PointManager ptm = manager.getPointManager();
+```
+
+| Método | Retorno | Descrição |
+|--------|---------|-----------|
+| `findById(String id)` | PointCategory | Busca 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 |
+| `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");
+```
+
+---
+
+## LotteryManager
+
+Gestão de sorteios e rifas.
+
+```java
+LotteryManager lotm = manager.getLotteryManager();
+```
+
+| 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 |
+| `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 |
+| `checkRestrictions(String lottery, String player)` | List\<String\> | Verifica restrições |
+
+---
+
+## CompetitionManager
+
+Gestão de competições entre jogadores.
+
+```java
+CompetitionManager comp = manager.getCompetitionManager();
+```
+
+| 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 |
+| `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 |
+| `findLeaders(String id, String range)` | Map | Ranking da competição |
+
+---
+
+## MysteryBoxManager
+
+Gestão de caixas surpresa.
+
+```java
+MysteryBoxManager mb = manager.getMysteryBoxManager();
+```
+
+| 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 |
+| `execute(String id, String player)` | MysteryResult | Abre caixa para jogador |
+| `undoExecute(String achievementId)` | void | Estorna abertura |
+
+---
+
+## QuestionManager
+
+Gestão de perguntas e respostas.
+
+```java
+QuestionManager qm = manager.getQuestionManager();
+```
+
+| 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 |
+
+---
+
+## QuizManager
+
+Gestão de questionários completos.
+
+```java
+QuizManager quizm = manager.getQuizManager();
+```
+
+| 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 |
+| `startLog(QuizLog log)` | Map | Inicia tentativa |
+| `finishLog(String id, String async)` | Map | Finaliza e calcula pontuação |
+| `deleteLog(String id)` | void | Remove tentativa |
+
+---
+
+## LeaderBoardManager
+
+Gestão de rankings e classificações.
+
+```java
+LeaderBoardManager lb = manager.getLeaderBoardManager();
+```
+
+| 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 |
+
+---
+
+## NotificationManager
+
+Envio de notificações para jogadores.
+
+```java
+NotificationManager nm = manager.getNotificationManager();
+```
+
+| 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 |
+| `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.player = "john";
+n.title = "Parabéns!";
+n.message = "Você completou o desafio!";
+n.time = new Date();
+manager.getNotificationManager().send(n);
+```
+
+---
+
+## SwapManager
+
+Gestão de trocas entre jogadores.
+
+```java
+SwapManager sm = manager.getSwapManager();
+```
+
+| 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 |
+| `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)
+
+Além dos managers, é possível acessar o MongoDB diretamente via Jongo.
+
+```java
+// Obter conexão
+Jongo jongo = manager.getJongoConnection();
+
+// Salvar documento
+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.