funifier-mcp 0.1.0 → 0.2.0

package/datasource-funifier-docs/knowledge/modules/auth.md

@@ -0,0 +1,104 @@
+# Auth (Autenticação)
+
+**Acesso Studio:** `/studio/auth`
+**API Endpoint:** `/v3/auth`
+
+## O que é
+
+Gerenciamento de autenticação e critérios básicos de segurança. Permite configurar como será o processo de login dos jogadores, definindo exigência de senha, auto-criação de usuários, geração de tokens de acesso (incluindo tempo de expiração e revalidação). Também permite criar rotinas personalizadas de autenticação (Auth Module) para SSO, validação externa e logs de login.
+
+## Quando usar
+
+- Para configurar login de jogadores
+- Para gerar tokens de acesso
+- Para implementar SSO com sistemas corporativos
+- Para criar validações customizadas de autenticação
+
+## Checklist de Configuração no Studio
+
+- [ ] Definir se senha é obrigatória
+- [ ] Configurar auto-criação de usuários
+- [ ] Definir tempo de expiração do token
+- [ ] Configurar módulo de autenticação customizado (se necessário)
+
+## API Endpoints
+
+### Autenticar Jogador
+**Método:** POST
+**Endpoint:** `/v3/auth/token`
+
+**Exemplo de Body:**
+```json
+{
+  "apiKey": "YOUR_API_KEY",
+  "grant_type": "password",
+  "username": "tom",
+  "password": "123"
+}
+```
+
+**Exemplo de Resposta:**
+```json
+{
+  "access_token": "eyJhbGciOiJIUzUxMiIsImNhbGciOiJHWklQIn0...",
+  "token_type": "Bearer",
+  "expires_in": 1695751444626
+}
+```
+
+### Listar Módulos de Autenticação
+**Método:** GET
+**Endpoint:** `/v3/auth/module`
+
+### Criar Módulo de Autenticação
+**Método:** POST
+**Endpoint:** `/v3/auth/module`
+
+## Roles e Permissões (Scopes)
+
+As permissões do token de jogador são controladas por **Roles** configuradas em `Studio > Security > Roles`. Cada Role define:
+
+- **Role:** nome da role (ex: `player`) — atribuída automaticamente ao jogador no login
+- **Timeout:** tempo de expiração do token (ex: `1d` = 1 dia)
+- **Scope:** lista de permissões separadas por vírgula
+
+### Scopes disponíveis
+
+| Scope | Descrição |
+|-------|-----------|
+| `read_all` | Leitura em todos os endpoints |
+| `write_all` | Escrita em todos os endpoints |
+| `delete_all` | Exclusão em todos os endpoints |
+| `write_player` | Escrita no endpoint `/v3/player` |
+| `write_actionlog` | Escrita no endpoint `/v3/action_log` |
+| `write_upload` | Escrita no endpoint `/v3/upload` |
+| `write_database_<collection>` | Escrita em uma coleção específica do database (ex: `write_database_task__c`) |
+| `delete_database_<collection>` | Exclusão em uma coleção específica do database |
+| `database` | **⚠️ OBRIGATÓRIO** para acessar o endpoint `/v3/database` — sem esta palavra no scope, o endpoint retorna dados vazios silenciosamente (sem erro) |
+
+### ⚠️ Nota importante sobre o endpoint Database
+
+O endpoint `/v3/database` exige que a palavra **`database`** esteja presente no scope da role, **independentemente** de `write_all` ou `read_all` já estarem configurados. Sem ela, as operações de escrita retornam `201` mas **não persistem os dados**, e as operações de leitura retornam **corpo vazio** — tudo sem mensagem de erro.
+
+### Exemplo de scope completo para apps com database
+
+```
+read_all, write_all, delete_all, database
+```
+
+### Configuração no Studio
+
+1. Acesse `Studio > Security`
+2. Na seção **Roles**, clique no botão `+` para criar uma nova role
+3. Defina: Role = `player`, Timeout = `1d`, Scope = `read_all, write_all, delete_all, database`
+4. Clique em **Salvar**
+5. O jogador precisa **fazer login novamente** para obter um token com as novas permissões
+
+## Validações e Testes
+
+- [ ] Login retorna token válido
+- [ ] Token expira no tempo configurado
+- [ ] Jogador inválido recebe erro apropriado
+- [ ] SSO funciona (se configurado)
+- [ ] Role "player" está configurada com scope adequado
+- [ ] Token do jogador tem permissão para os endpoints necessários

package/datasource-funifier-docs/knowledge/modules/avatar.md

@@ -0,0 +1,28 @@
+# Avatar (Avatar)
+
+## O que é
+
+Criação e customização de avatares para os jogadores. Permite aos jogadores criarem avatares personalizados, desbloqueando acessórios e itens de acordo com o desempenho na gamificação ou por compras na loja. Pode ser usado em ambientes 2D ou 3D.
+
+## Quando usar
+
+- Para personalização visual dos jogadores
+- Para criar senso de identidade e pertencimento
+- Para vincular recompensas a itens visuais
+- Para ambientes virtuais com representação do jogador
+
+## Dependências
+
+- **Virtual Good** (opcional): acessórios podem ser vendidos na loja
+
+## Checklist de Configuração
+
+- [ ] Definir tipos de avatar disponíveis
+- [ ] Criar acessórios e itens desbloqueáveis
+- [ ] Vincular itens a desafios ou loja virtual
+
+## Validações e Testes
+
+- [ ] Avatar padrão é exibido para novos jogadores
+- [ ] Acessórios desbloqueados aparecem disponíveis
+- [ ] Personalização do avatar é salva corretamente

package/datasource-funifier-docs/knowledge/modules/backup.md

@@ -0,0 +1,40 @@
+# Backup (Backup)
+
+**Acesso Studio:** `/studio/backup`
+**API Endpoint:** `/v3/backup`
+
+## O que é
+
+Backup e remoção controlada de dados antigos. Permite criar rotinas automáticas de backup de registros importantes, além de remover dados antigos de maneira controlada para manter a performance da plataforma.
+
+## Quando usar
+
+- Para fazer backup de logs antigos antes de atualizações
+- Para remover registros históricos e otimizar consultas
+- Para manter performance em grandes volumes de dados
+
+## Checklist de Configuração no Studio
+
+- [ ] Definir quais coleções serão backupeadas
+- [ ] Configurar frequência do backup
+- [ ] Definir critério de remoção de dados antigos
+
+## API Endpoints
+
+### Listar Backups
+**Método:** GET
+**Endpoint:** `/v3/backup`
+
+### Criar Backup
+**Método:** POST
+**Endpoint:** `/v3/backup`
+
+### Deletar Backup
+**Método:** DELETE
+**Endpoint:** `/v3/backup/:id`
+
+## Validações e Testes
+
+- [ ] Backup é executado com sucesso
+- [ ] Dados antigos são removidos conforme critério
+- [ ] Performance melhora após limpeza

package/datasource-funifier-docs/knowledge/modules/challenge.md

@@ -0,0 +1,91 @@
+# Challenge (Desafio)
+
+**Acesso Studio:** `/studio/challenge`
+**API Endpoint:** `/v3/challenge`
+
+## O que é
+
+Configuração de desafios a serem completados por jogadores ou equipes. Permite criar desafios personalizados, definindo ações que o jogador precisa realizar e recompensas que receberá. Os desafios podem variar de simples tarefas a missões complexas compostas por múltiplas ações ou etapas.
+
+## Quando usar
+
+- Em quase todo projeto de gamificação
+- Para definir missões e objetivos para jogadores
+- Para vincular ações a recompensas (pontos, itens, etc.)
+- Para criar progressão e senso de conquista
+
+## Dependências
+
+- **Point**: tipos de ponto devem existir antes de criar challenges que os recompensam
+- **Action**: ações devem existir antes de criar challenges que as referenciam
+
+## Checklist de Configuração no Studio
+
+- [ ] Definir título e descrição do desafio
+- [ ] Definir regras (rules): qual ação, quantas vezes, filtros por atributo
+- [ ] Definir recompensas (points): tipo de ponto e quantidade
+- [ ] Definir frequência (uma vez, diário, semanal, ilimitado)
+- [ ] Definir desbloqueio (quando fica disponível)
+- [ ] Configurar notificações de conclusão
+- [ ] Vincular técnicas de jogo (techniques)
+
+## API Endpoints
+
+### Listar Desafios
+**Método:** GET
+**Endpoint:** `/v3/challenge`
+
+**Exemplo de Resposta:**
+```json
+[
+  {
+    "challenge": "Sell 10 books",
+    "description": "Sell 10 books to earn 25 xp and 5 coins",
+    "rules": [
+      {
+        "actionId": "sell",
+        "filters": [
+          { "value": "book", "operator": 1, "param": "product" }
+        ],
+        "total": 10
+      }
+    ],
+    "points": [
+      { "total": 25, "category": "xp" },
+      { "total": 5, "category": "coin" }
+    ],
+    "_id": "DTkhJHV"
+  }
+]
+```
+
+### Criar Desafio
+**Método:** POST
+**Endpoint:** `/v3/challenge`
+
+**Exemplo de Body:**
+```json
+{
+  "challenge": "Watch Video",
+  "description": "Complete this challenge by watching a video, and earn 10 xp",
+  "rules": [
+    { "actionId": "watch_video", "operator": 5, "total": 0 }
+  ],
+  "points": [
+    { "total": 10.0, "category": "xp", "operation": 0 }
+  ],
+  "techniques": ["GT35"]
+}
+```
+
+### Excluir Desafio
+**Método:** DELETE
+**Endpoint:** `/v3/challenge/:id`
+
+## Validações e Testes
+
+- [ ] Desafio aparece na lista GET /v3/challenge
+- [ ] Ações referenciadas nas rules existem (GET /v3/action)
+- [ ] Pontos referenciados nas recompensas existem (GET /v3/point)
+- [ ] Ao registrar ação (POST /v3/action/log), o desafio progride corretamente
+- [ ] Ao completar o desafio, jogador recebe os pontos definidos

package/datasource-funifier-docs/knowledge/modules/compact.md

@@ -0,0 +1,40 @@
+# Compact (Compactação)
+
+**Acesso Studio:** `/studio/compact`
+**API Endpoint:** `/v3/compact`
+
+## O que é
+
+Compactação e otimização do armazenamento de dados. Configura rotinas para agrupar registros e reduzir o espaço ocupado por dados históricos, como achievements ou logs, melhorando o tempo de resposta das consultas e a performance geral.
+
+## Quando usar
+
+- Para compactar registros de achievements acumulados
+- Para otimizar coleções de acesso rápido
+- Para reduzir volume de dados históricos
+
+## Checklist de Configuração no Studio
+
+- [ ] Definir coleções a compactar
+- [ ] Configurar critérios de agrupamento
+- [ ] Testar impacto na performance
+
+## API Endpoints
+
+### Listar Compactações
+**Método:** GET
+**Endpoint:** `/v3/compact`
+
+### Criar Compactação
+**Método:** POST
+**Endpoint:** `/v3/compact`
+
+### Deletar Compactação
+**Método:** DELETE
+**Endpoint:** `/v3/compact/:id`
+
+## Validações e Testes
+
+- [ ] Compactação é executada sem perda de dados
+- [ ] Volume de dados é reduzido
+- [ ] Consultas mantêm resultados corretos após compactação

package/datasource-funifier-docs/knowledge/modules/competition.md

@@ -0,0 +1,149 @@
+# Competition (Competição)
+
+**Acesso Studio:** `/studio/competition`
+**API Endpoint:** `/v3/competition`
+
+## O que é
+
+Configuração de disputas diretas entre jogadores ou equipes. Permite criar competições com regras próprias, prêmios para diferentes posições e critérios de apuração customizáveis. Geralmente, o jogador ou equipe precisa se inscrever para participar.
+
+## Quando usar
+
+- Para criar disputas temporais (ex: competição de vendas mensal)
+- Para premiar os melhores colocados em um período
+- Para engajar equipes com competições internas
+
+## Dependências
+
+- **Point** ou **Action**: métrica de avaliação deve existir
+- **Player** ou **Team**: participantes devem existir
+
+## Checklist de Configuração no Studio
+
+- [ ] Definir título e descrição
+- [ ] Definir período de apuração (period.expression)
+- [ ] Definir número máximo de vencedores (maxWinners)
+- [ ] Definir número máximo de participantes (maxPlayers)
+- [ ] Definir critério de ranking (operation: tipo, item, ordenação)
+- [ ] Definir custo de inscrição (requires) se aplicável
+- [ ] Definir recompensas por posição (rewards com position_start/position_ends)
+- [ ] Definir se é competição de equipes (teamCompetition)
+- [ ] Ativar competição (active: true)
+- [ ] Definir execução automática (autoExecute)
+
+## API Endpoints
+
+### Listar Competições
+**Método:** GET
+**Endpoint:** `/v3/competition`
+
+### Criar Competição
+**Método:** POST
+**Endpoint:** `/v3/competition`
+
+**Exemplo de Body:**
+```json
+{
+  "title": "Sales Race",
+  "description": "Leads the competition who has the highest amount of closed sales in the month.",
+  "period": {
+    "expression": "-0M-;+1M+"
+  },
+  "maxWinners": 1,
+  "maxPlayers": 100,
+  "minScore": 0,
+  "operation": {
+    "type": 1,
+    "achievement_type": 0,
+    "item": "sell",
+    "filters": [],
+    "sort": -1,
+    "sub": false
+  },
+  "requires": [
+    {
+      "total": 10,
+      "type": 0,
+      "item": "coin",
+      "operation": 1,
+      "extra": {},
+      "restrict": false,
+      "perPlayer": false
+    }
+  ],
+  "rewards": [
+    {
+      "total": 100,
+      "type": 0,
+      "item": "xp",
+      "operation": 0,
+      "extra": {
+        "position_start": 1,
+        "position_ends": 3
+      },
+      "restrict": false,
+      "perPlayer": false
+    }
+  ],
+  "notifications": [],
+  "active": true,
+  "teamCompetition": false,
+  "autoExecute": true,
+  "extra": {},
+  "techniques": ["GT26"],
+  "_id": "race"
+}
+```
+
+### Deletar Competição
+**Método:** DELETE
+**Endpoint:** `/v3/competition/:id`
+
+### Listar Participações (Joins)
+**Método:** GET
+**Endpoint:** `/v3/competition/join?competition=:id`
+
+### Criar Participação (Join)
+**Método:** POST
+**Endpoint:** `/v3/competition/join`
+
+**Exemplo de Body:**
+```json
+{
+  "competition": "race",
+  "player": "jerry"
+}
+```
+
+### Deletar Participação
+**Método:** DELETE
+**Endpoint:** `/v3/competition/join`
+
+**Exemplo de Body:**
+```json
+{
+  "competition": "race",
+  "player": "tom"
+}
+```
+
+### Listar Líderes da Competição
+**Método:** POST
+**Endpoint:** `/v3/competition/leader/aggregate?id=:id`
+
+### Executar Competição
+**Método:** GET
+**Endpoint:** `/v3/competition/:id/execute`
+**Descrição:** Finaliza a competição, calcula resultados e premia os vencedores.
+
+### Reverter Execução
+**Método:** DELETE
+**Endpoint:** `/v3/competition/:id/execute`
+
+## Validações e Testes
+
+- [ ] Competição aparece na lista GET /v3/competition
+- [ ] Jogador consegue se inscrever (join)
+- [ ] Lista de líderes retorna dados ordenados
+- [ ] Ao executar, vencedores recebem recompensas
+- [ ] Custo de inscrição é debitado corretamente

package/datasource-funifier-docs/knowledge/modules/crossword.md

@@ -0,0 +1,41 @@
+# Crossword (Palavras Cruzadas)
+
+**Acesso Studio:** `/studio/crossword`
+**API Endpoint:** `/v3/crossword`
+
+## O que é
+
+Configuração de jogos de palavras cruzadas. Permite criar jogos customizados, com dicas, posições e temas específicos para diferentes objetivos educacionais ou promocionais.
+
+## Quando usar
+
+- Para onboarding de funcionários com termos técnicos
+- Para campanhas de marketing temáticas
+- Para jogos educacionais
+- Para engajamento com vocabulário específico
+
+## Checklist de Configuração no Studio
+
+- [ ] Definir título do jogo
+- [ ] Criar palavras com dicas e posições
+- [ ] Configurar tema visual
+
+## API Endpoints
+
+### Listar Crosswords
+**Método:** GET
+**Endpoint:** `/v3/crossword`
+
+### Criar Crossword
+**Método:** POST
+**Endpoint:** `/v3/crossword`
+
+### Deletar Crossword
+**Método:** DELETE
+**Endpoint:** `/v3/crossword/:id`
+
+## Validações e Testes
+
+- [ ] Crossword aparece na lista
+- [ ] Palavras e dicas estão corretas
+- [ ] Jogador consegue interagir com o jogo

package/datasource-funifier-docs/knowledge/modules/csv-data.md

@@ -0,0 +1,30 @@
+# CSV Data (Dados CSV)
+
+**API Endpoint:** `/v3/csv`
+
+## O que é
+
+Importação e exportação de dados no formato CSV. Permite importar ou exportar dados de forma fácil e segura, seja via upload manual ou FTP. Suporta arquivos criptografados para segurança no trânsito das informações.
+
+## Quando usar
+
+- Para importar listas de jogadores em massa
+- Para exportar relatórios de desempenho
+- Para migrar dados de sistemas externos
+- Para importação segura via FTP com criptografia
+
+## API Endpoints
+
+### Importar CSV
+**Método:** POST
+**Endpoint:** `/v3/csv`
+
+### Exportar CSV
+**Método:** GET
+**Endpoint:** `/v3/csv`
+
+## Validações e Testes
+
+- [ ] Importação processa arquivo corretamente
+- [ ] Dados importados aparecem nas coleções corretas
+- [ ] Exportação gera arquivo CSV válido

package/datasource-funifier-docs/knowledge/modules/custom-object.md

@@ -0,0 +1,53 @@
+# Custom Object (Objeto Customizado)
+
+## O que é
+
+Criação de objetos personalizados para necessidades específicas. Permite criar e gerenciar coleções personalizadas no banco de dados (sufixo `__c`), que podem ser acessadas via API, triggers, schedulers e páginas personalizadas. Ideal para quando os módulos padrão não atendem a todos os requisitos do projeto.
+
+## Quando usar
+
+- Para cadastrar entidades específicas do negócio (produtos, imóveis, etc.)
+- Para criar listas customizadas (pontos turísticos, categorias, etc.)
+- Para armazenar dados que não se encaixam nos módulos padrão
+
+## API Endpoints
+
+Objetos customizados são acessados via o módulo Database:
+
+### Listar Objetos
+**Método:** GET
+**Endpoint:** `/v3/database/<nome>__c`
+
+### Criar Objeto
+**Método:** POST
+**Endpoint:** `/v3/database/<nome>__c`
+
+**Exemplo (coleção car__c):**
+```json
+{
+  "_id": "car001",
+  "name": "Civic",
+  "brand": "Honda",
+  "price": 50000
+}
+```
+
+### Atualizar Objeto
+**Método:** PUT
+**Endpoint:** `/v3/database/<nome>__c`
+
+### Excluir Objeto
+**Método:** DELETE
+**Endpoint:** `/v3/database/<nome>__c?q=_id:'car001'`
+
+## Boas Práticas
+
+- Sempre usar sufixo `__c` no nome da coleção
+- Definir `_id` único para cada objeto
+- Criar índices para campos usados em consultas frequentes
+
+## Validações e Testes
+
+- [ ] Coleção customizada aparece em GET /v3/database/collections
+- [ ] CRUD funciona corretamente
+- [ ] Triggers com entity `<nome>__c` funcionam