funifier-mcp 0.2.0 → 0.2.3

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

@@ -1,152 +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"}}}
-]
-```
+# 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

@@ -1,132 +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`)
+# 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`)