funifier-mcp 0.1.0 → 0.2.3

package/datasource-funifier-docs/knowledge/guides/aggregates.md

@@ -0,0 +1,152 @@
+# Aggregates Funifier
+
+A plataforma Funifier utiliza o MongoDB como banco de dados, permitindo consultas avançadas por meio de **aggregates**. Esta funcionalidade é fundamental para extrair relatórios, gerar indicadores personalizados e construir dashboards.
+
+## Como Executar
+
+**Método:** POST
+**Endpoint:** `/v3/database/{collection}/aggregate`
+**Body:** Pipeline JSON com comandos aggregate
+
+## Principais Coleções
+
+### player
+Jogadores da gamificação.
+```json
+{"_id": "john", "name": "John Travolta", "email": "john@funifier.com", "teams": ["sales"], "extra": {"country": "USA", "department": "IT"}, "created": {"$date": "2023-07-05T20:57:25.776Z"}}
+```
+
+### action
+Configurações dos tipos de ações.
+```json
+{"_id": "sell", "action": "Sell", "attributes": [{"name": "product", "type": "String"}, {"name": "price", "type": "Number"}], "active": true}
+```
+
+### action_log
+Ações executadas pelos jogadores. Campo `userId` → `player._id`. Campo `actionId` → `action._id`.
+```json
+{"_id": "64a5d92", "actionId": "sell", "userId": "john", "time": {"$date": "2023-07-05T20:57:33.303Z"}, "attributes": {"product": "book", "price": 120}}
+```
+
+### achievement
+Conquistas dos jogadores. Campo `type`: 0=Point, 1=Challenge, 2=Virtual Good, 3=Level. Campo `player` → `player._id`.
+```json
+{"_id": "64a5d2", "player": "john", "total": 25.0, "type": 0, "item": "xp", "time": {"$date": "2023-07-05T20:57:33.303Z"}}
+```
+
+### challenge
+Desafios da gamificação.
+```json
+{"challenge": "Watch Video", "active": true, "_id": "DTo8dS3", "rules": [{"actionId": "watch_video", "operator": 5, "total": 0}], "points": [{"total": 10.0, "category": "xp", "operation": 0}]}
+```
+
+### point_category
+Tipos de pontos.
+```json
+{"_id": "xp", "category": "Experience Points", "shortName": "XP", "extra": {}}
+```
+
+### catalog_item
+Itens da loja virtual.
+```json
+{"_id": "prd1", "catalogId": "gifts", "name": "T-shirt", "amount": 100, "active": true, "requires": [{"total": 15, "type": 0, "item": "coin", "operation": 1}]}
+```
+
+## Expressões de Data (Funifier Syntax)
+
+Formato: `[sinal][quantidade][unidade][ajuste opcional]`
+
+| Expressão | Significado |
+|-----------|------------|
+| `-0d` | Agora |
+| `-0d-` | Início do dia atual (00:00:00) |
+| `-0d+` | Fim do dia atual (23:59:59) |
+| `-1d` | Exatamente um dia atrás |
+| `-1d-` | Início do dia anterior (00:00:00) |
+| `-1d+` | Fim do dia anterior (23:59:59) |
+| `-0w-` | Início da semana atual |
+| `-0w+` | Fim da semana atual |
+| `-1w` | Exatamente uma semana atrás |
+| `-0M-` | Início do mês atual |
+| `-0M+` | Fim do mês atual |
+| `-1M` | Exatamente um mês atrás |
+| `-1M-` | Início do mês anterior |
+| `-0y-` | Início do ano atual |
+| `-0y+` | Fim do ano atual |
+
+**Unidades:** `m`=minuto, `h`=hora, `d`=dia, `w`=semana, `M`=mês, `y`=ano
+
+**Uso em filtros:**
+```json
+{"$date": "-0M-"}
+```
+
+## Operadores Suportados
+
+`$match`, `$group`, `$sort`, `$limit`, `$lookup`, `$project`, `$unwind`, `$addFields`, `$count`
+
+## Exemplos Práticos
+
+### Exemplo 1: Top 10 jogadores com mais pontos XP no mês atual
+
+```json
+// POST /v3/database/achievement/aggregate
+[
+  {"$match": {"type": 0, "item": "xp", "time": {"$gte": {"$date": "-0M-"}, "$lte": {"$date": "-0M+"}}}},
+  {"$group": {"_id": "$player", "total": {"$sum": "$total"}}},
+  {"$sort": {"total": -1}},
+  {"$lookup": {"from": "player", "localField": "_id", "foreignField": "_id", "as": "p"}},
+  {"$unwind": "$p"},
+  {"$project": {"_id": 1, "player": "$p.name", "total": 1}},
+  {"$limit": 10}
+]
+```
+
+### Exemplo 2: Quantos jogadores distintos completaram um desafio
+
+```json
+// POST /v3/database/achievement/aggregate
+[
+  {"$match": {"type": 1, "item": "DTo8dS3"}},
+  {"$group": {"_id": "$player", "challenge": {"$first": "$item"}}},
+  {"$group": {"_id": "$challenge", "total_players": {"$sum": 1}}},
+  {"$lookup": {"from": "challenge", "localField": "_id", "foreignField": "_id", "as": "c"}},
+  {"$project": {"_id": 1, "total_players": 1, "challenge_name": {"$first": "$c.challenge"}}}
+]
+```
+
+### Exemplo 3: Média de pontos XP por jogador em um mês específico
+
+```json
+// POST /v3/database/achievement/aggregate
+[
+  {"$match": {"type": 0, "item": "xp", "time": {"$gte": {"$date": "2023-08-01T00:00:00.000Z"}, "$lte": {"$date": "2023-08-31T23:59:59.999Z"}}}},
+  {"$group": {"_id": "$player", "averageXP": {"$avg": "$total"}}}
+]
+```
+
+### Exemplo 4: Top 3 itens mais vendidos na loja virtual este ano
+
+```json
+// POST /v3/database/achievement/aggregate
+[
+  {"$match": {"type": 2, "time": {"$gte": {"$date": "-0y-"}, "$lte": {"$date": "-0y+"}}}},
+  {"$group": {"_id": "$item", "totalSold": {"$sum": "$total"}}},
+  {"$lookup": {"from": "catalog_item", "localField": "_id", "foreignField": "_id", "as": "ci"}},
+  {"$project": {"_id": 1, "catalogItemName": {"$first": "$ci.name"}, "totalSold": 1}},
+  {"$sort": {"totalSold": -1}},
+  {"$limit": 3}
+]
+```
+
+### Exemplo 5: Jogadores que executaram ações ontem
+
+```json
+// POST /v3/database/action_log/aggregate
+[
+  {"$match": {"time": {"$gte": {"$date": "-1d-"}, "$lte": {"$date": "-1d+"}}}},
+  {"$group": {"_id": "$userId"}},
+  {"$lookup": {"from": "player", "localField": "_id", "foreignField": "_id", "as": "p"}},
+  {"$project": {"_id": 1, "playerName": {"$first": "$p.name"}}}
+]
+```

package/datasource-funifier-docs/knowledge/guides/database-access.md

@@ -0,0 +1,132 @@
+# Acesso ao Banco de Dados Funifier
+
+A plataforma Funifier oferece duas formas principais de acessar e manipular os dados da gamificação:
+
+1. **Via API REST** — endpoint `/v3/database`
+2. **Via código Java** — objeto `manager` em triggers, schedulers e public endpoints
+
+Ambas utilizam **MongoDB** como banco de dados.
+
+---
+
+## 1. Acesso via API — Endpoint `/v3/database`
+
+### 1.1 Listar Coleções Disponíveis
+
+**Método:** GET
+**Endpoint:** `/v3/database/collections`
+
+**Resposta:**
+```json
+["player", "action_log", "achievement", "challenge", "car__c", "email__c"]
+```
+
+### 1.2 Operações CRUD
+
+| Operação | Método | Endpoint | Descrição |
+|----------|--------|----------|-----------|
+| Create | POST | `/v3/database/:collection` | Cria um novo registro |
+| Read | GET | `/v3/database/:collection` | Lista registros da coleção |
+| Update | PUT | `/v3/database/:collection` | Atualiza registro existente (via `_id`) |
+| Delete | DELETE | `/v3/database/:collection?q=...` | Remove registros com filtro |
+| Bulk Insert | POST | `/v3/database/:collection/bulk` | Cria/atualiza múltiplos registros |
+
+**Exemplo — Criar item na coleção `car__c`:**
+```
+POST /v3/database/car__c
+```
+```json
+{
+  "_id": "car001",
+  "name": "Civic",
+  "brand": "Honda",
+  "price": 50000
+}
+```
+
+### 1.3 Executar Aggregates
+
+**Método:** POST
+**Endpoint:** `/v3/database/:collection/aggregate`
+
+**Body (pipeline JSON):**
+```json
+[
+  { "$match": { "player": "john", "type": 0, "item": "xp" } },
+  { "$group": { "_id": null, "totalXP": { "$sum": "$total" } } }
+]
+```
+
+**Resultado:**
+```json
+[{ "totalXP": 250 }]
+```
+
+**Operadores suportados:** `$match`, `$group`, `$sort`, `$limit`, `$lookup`, `$project`, `$unwind`, `$addFields`, `$count`
+
+### 1.4 Índices
+
+| Operação | Método | Endpoint |
+|----------|--------|----------|
+| Listar | GET | `/v3/database/:collection/index` |
+| Criar | POST | `/v3/database/:collection/index` |
+| Excluir | DELETE | `/v3/database/:collection/index/:index_name` |
+
+**Exemplo — Criar índice:**
+```json
+{ "fuel": 1 }
+```
+
+---
+
+## 2. Acesso via Código Java (Triggers, Schedulers, Public Endpoints)
+
+Módulos que executam código Java têm acesso ao objeto `manager`, que provê conexão direta com o MongoDB através do driver Jongo.
+
+### 2.1 Estrutura de Acesso
+
+```java
+manager.getJongoConnection().getCollection("nome_da_colecao").operacao(...);
+```
+
+### 2.2 Operações
+
+#### Salvar (Insert/Update)
+```java
+manager.getJongoConnection()
+       .getCollection("email__c")
+       .save(payload);
+```
+
+#### Buscar (Find)
+```java
+Object result = manager.getJongoConnection()
+                       .getCollection("player")
+                       .findOne("{_id: 'john'}")
+                       .as(Map.class);
+```
+
+#### Deletar
+```java
+manager.getJongoConnection()
+       .getCollection("car__c")
+       .remove("{_id: 'car001'}");
+```
+
+#### Aggregate
+```java
+Iterable<Map> resultado = manager.getJongoConnection()
+    .getCollection("action_log")
+    .aggregate("[{ $match: { item: 'xp' } }, { $group: { _id: '$player', total: { $sum: '$total' } } }]")
+    .as(Map.class);
+```
+
+---
+
+## 3. Considerações de Segurança e Boas Práticas
+
+- As operações via API devem ser protegidas por **token de autenticação**
+- Endpoints públicos não requerem token — usar com cautela
+- Manipulação direta do banco afeta dados em **tempo real**
+- Sempre testar em **ambiente de homologação** antes de aplicar em produção
+- Coleções customizadas usam sufixo `__c` (ex: `car__c`, `email__c`)

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

@@ -0,0 +1,373 @@
+# Java Entities — Referência
+
+As entidades são os objetos Java (POJOs) que representam os dados armazenados no MongoDB. Cada entidade mapeia para uma coleção no banco de dados.
+
+---
+
+## Entidades Principais
+
+### Player
+
+**Coleção MongoDB:** `player`
+**Classe:** `com.funifier.engine.player.Player`
+
+```java
+// Campos principais
+String _id;          // ID do jogador (ex: "john")
+String name;         // Nome do jogador
+String email;        // Email
+String password;     // Senha (hash)
+Map<String, Object> extra;  // Campos customizados (ex: department, country)
+List<String> teams;  // IDs das equipes
+List<String> friends; // IDs dos amigos
+ImageSet image;      // Imagens (small, medium, original)
+Date created;        // Data de cadastro
+```
+
+```json
+{"_id": "john", "name": "John Travolta", "email": "john@funifier.com", "teams": ["sales"], "extra": {"country": "USA", "department": "IT"}, "image": {"small": {"url": "..."}, "medium": {"url": "..."}, "original": {"url": "..."}}}
+```
+
+---
+
+### Achievement
+
+**Coleção MongoDB:** `achievement`
+**Classe:** `com.funifier.engine.achievement.Achievement`
+
+Representa qualquer conquista do jogador: pontos ganhos, desafios completados, itens comprados, níveis alcançados.
+
+```java
+// Campos principais
+String _id;       // ID da conquista
+String player;    // ID do jogador
+double total;     // Quantidade (pontos, unidades)
+int type;         // Tipo (0=Point, 1=Challenge, 2=VirtualGood, 3=Level)
+String item;      // ID do item (point_category, challenge, catalog_item, level)
+Date time;        // Data da conquista
+
+// Constantes de tipo
+static final int TYPE_POINT = 0;
+static final int TYPE_CHALLENGE = 1;
+static final int TYPE_VIRTUAL_GOOD = 2;
+static final int TYPE_LEVEL = 3;
+```
+
+```json
+{"_id": "64a5d2", "player": "john", "total": 25.0, "type": 0, "item": "xp", "time": {"$date": "2023-07-05T20:57:33.303Z"}}
+```
+
+---
+
+### ActionLog
+
+**Coleção MongoDB:** `action_log`
+**Classe:** `com.funifier.engine.action.ActionLog`
+
+Registo de uma ação executada por um jogador.
+
+```java
+// Campos principais
+String _id;       // ID do log
+String actionId;  // ID da ação (ex: "sell")
+String userId;    // ID do jogador (ex: "john")
+Date time;        // Data da execução
+Map<String, Object> attributes; // Atributos da ação (ex: product, price)
+```
+
+```json
+{"_id": "64a5d92", "actionId": "sell", "userId": "john", "time": {"$date": "2023-07-05T20:57:33.303Z"}, "attributes": {"product": "book", "price": 120}}
+```
+
+---
+
+### Action
+
+**Coleção MongoDB:** `action`
+**Classe:** `com.funifier.engine.action.Action`
+
+Definição de um tipo de ação.
+
+```java
+// Campos principais
+String _id;       // ID da ação (ex: "sell")
+String action;    // Nome da ação (ex: "Sell")
+boolean active;   // Se está ativa
+List<ActionAttribute> attributes; // Definição dos atributos (name, type)
+```
+
+```json
+{"_id": "sell", "action": "Sell", "attributes": [{"name": "product", "type": "String"}, {"name": "price", "type": "Number"}], "active": true}
+```
+
+---
+
+### Challenge
+
+**Coleção MongoDB:** `challenge`
+**Classe:** `com.funifier.engine.challenge.Challenge`
+
+Definição de um desafio.
+
+```java
+// Campos principais
+String _id;          // ID do desafio
+String challenge;    // Nome do desafio
+boolean active;      // Se está ativo
+List<Rule> rules;    // Regras (ação, operador, total)
+List<Reward> points; // Recompensas (pontos, operação)
+```
+
+```json
+{"_id": "DTo8dS3", "challenge": "Watch Video", "active": true, "rules": [{"actionId": "watch_video", "operator": 5, "total": 0}], "points": [{"total": 10.0, "category": "xp", "operation": 0}]}
+```
+
+---
+
+### CatalogItem
+
+**Coleção MongoDB:** `catalog_item`
+**Classe:** `com.funifier.engine.catalog.CatalogItem`
+
+Item da loja virtual.
+
+```java
+// Campos principais
+String _id;           // ID do item
+String catalogId;     // ID do catálogo
+String name;          // Nome do item
+int amount;           // Quantidade disponível
+boolean active;       // Se está ativo
+Requirement[] requires; // Requisitos para compra (pontos necessários)
+```
+
+```json
+{"_id": "prd1", "catalogId": "gifts", "name": "T-shirt", "amount": 100, "active": true, "requires": [{"total": 15, "type": 0, "item": "coin", "operation": 1}]}
+```
+
+---
+
+### Team
+
+**Coleção MongoDB:** `team`
+**Classe:** `com.funifier.engine.team.Team`
+
+```java
+String _id;     // ID da equipe
+String name;    // Nome da equipe
+```
+
+---
+
+### Level
+
+**Coleção MongoDB:** `level`
+**Classe:** `com.funifier.engine.level.Level`
+
+```java
+String _id;     // ID do nível
+String level;   // Nome do nível
+int position;   // Posição (ordem)
+```
+
+---
+
+### PointCategory
+
+**Coleção MongoDB:** `point_category`
+**Classe:** `com.funifier.engine.point.PointCategory`
+
+```java
+String _id;       // ID da categoria (ex: "xp")
+String category;  // Nome (ex: "Experience Points")
+String shortName; // Abreviação (ex: "XP")
+Map extra;        // Campos extras
+```
+
+---
+
+### Lottery
+
+**Coleção MongoDB:** `lottery`
+**Classe:** `com.funifier.engine.lottery.Lottery`
+
+```java
+String _id;     // ID do sorteio
+String title;   // Título
+boolean active; // Se está ativo
+```
+
+---
+
+### LotteryTicket
+
+**Coleção MongoDB:** `lottery_ticket`
+**Classe:** `com.funifier.engine.lottery.LotteryTicket`
+
+```java
+String _id;      // ID do ticket
+String lottery;  // ID do sorteio
+String player;   // ID do jogador
+```
+
+---
+
+### MysteryBox
+
+**Coleção MongoDB:** `mystery_box`
+**Classe:** `com.funifier.engine.mystery.MysteryBox`
+
+```java
+String _id;     // ID da caixa
+String title;   // Título
+boolean active; // Se está ativa
+```
+
+---
+
+### Competition
+
+**Coleção MongoDB:** `competition`
+**Classe:** `com.funifier.engine.competition.Competition`
+
+```java
+String _id;     // ID da competição
+boolean active; // Se está ativa
+```
+
+---
+
+### Question
+
+**Coleção MongoDB:** `question`
+**Classe:** `com.funifier.engine.question.Question`
+
+```java
+String _id;      // ID da pergunta
+String question; // Texto da pergunta
+```
+
+---
+
+### QuestionLog
+
+**Coleção MongoDB:** `question_log`
+**Classe:** `com.funifier.engine.question.QuestionLog`
+
+```java
+String _id;      // ID do log
+String player;   // ID do jogador
+String question; // ID da pergunta
+```
+
+---
+
+### Quiz / QuizLog
+
+**Coleções:** `quiz` / `quiz_log`
+
+---
+
+### Notification
+
+**Coleção MongoDB:** `notification`
+**Classe:** `com.funifier.engine.notify.Notification`
+
+```java
+String _id;     // ID da notificação
+String player;  // ID do jogador destino
+String title;   // Título
+String message; // Mensagem
+Date time;      // Data
+```
+
+---
+
+### Swap
+
+**Coleção MongoDB:** `swap`
+**Classe:** `com.funifier.engine.swap.Swap`
+
+---
+
+### Trigger
+
+**Coleção MongoDB:** `trigger`
+**Classe:** `com.funifier.engine.integration.trigger.Trigger`
+
+```java
+String _id;      // ID da trigger
+String name;     // Nome
+String entity;   // Entidade (ex: "player", "achievement")
+String event;    // Evento (ex: "before_create", "after_win")
+String script;   // Código Java
+```
+
+---
+
+### SchedulerConfig
+
+**Coleção MongoDB:** `scheduler`
+**Classe:** `com.funifier.engine.integration.scheduler.SchedulerConfig`
+
+---
+
+### PublicEndpoint
+
+**Coleção MongoDB:** `public_endpoint`
+**Classe:** `com.funifier.engine.pub.PublicEndpoint`
+
+---
+
+### Webhook
+
+**Coleção MongoDB:** `webhook`
+**Classe:** `com.funifier.engine.webhook.Webhook`
+
+---
+
+## Mapeamento Completo Entidade → Coleção
+
+| Entidade | Coleção MongoDB | Classe Java |
+|----------|----------------|-------------|
+| PLAYER | `player` | Player |
+| PLAYER_STATUS | `player_status` | PlayerStatus |
+| TEAM | `team` | Team |
+| TEAM_PLAYER | `team_player` | TeamLink |
+| ACHIEVEMENT | `achievement` | Achievement |
+| CHALLENGE | `challenge` | Challenge |
+| ACTION_LOG | `action_log` | ActionLog |
+| ACTION | `action` | Action |
+| CATALOG | `catalog` | Catalog |
+| CATALOG_ITEM | `catalog_item` | CatalogItem |
+| PURCHASE | `purchase` | Purchase |
+| POINT_CATEGORY | `point_category` | PointCategory |
+| LEVEL | `level` | Level |
+| LEVEL_CONFIG | `level_config` | LevelConfig |
+| LEADERBOARD | `leaderboard` | LeaderBoard_V2 |
+| LEADER | `leader` | Leader |
+| LOTTERY | `lottery` | Lottery |
+| LOTTERY_TICKET | `lottery_ticket` | LotteryTicket |
+| MYSTERY_BOX | `mystery_box` | MysteryBox |
+| MYSTERY_BOX_LOG | `mystery_box_log` | MysteryBoxLog |
+| NOTIFICATION | `notification` | Notification |
+| QUESTION | `question` | Question |
+| QUESTION_LOG | `question_log` | QuestionLog |
+| QUIZ | `quiz` | Quiz |
+| QUIZ_LOG | `quiz_log` | QuizLog |
+| COMPETITION | `competition` | Competition |
+| COMPETITION_JOIN | `competition_join` | CompetitionJoin |
+| SWAP | `swap` | Swap |
+| FOLDER | `folder` | Folder |
+| TRIGGER | `trigger` | Trigger |
+| TRIGGER_LOG | `trigger_log` | TriggerLog |
+| SCHEDULER | `scheduler` | SchedulerConfig |
+| SCHEDULER_LOG | `scheduler_log` | SchedulerLog |
+| PUBLIC_ENDPOINT | `public_endpoint` | PublicEndpoint |
+| WEBHOOK | `webhook` | Webhook |
+| WEBSOCKET | `websocket` | WebSocket |
+| STUDIO_PAGE | `studio_page` | StudioPage |
+| BACKUP | `backup` | Backup |
+| COMPACT | `compact` | Compact |
+
+> **Nota:** Coleções customizadas (Custom Objects) usam o sufixo `__c` (ex: `car__c`, `email__c`) e são acessadas como `HashMap`.