funifier-mcp 0.1.0 → 0.2.3

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

@@ -0,0 +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.