funifier-mcp 0.1.0 → 0.2.3

package/datasource-funifier-docs/knowledge/guides/triggers-guide.md

@@ -0,0 +1,271 @@
+# Triggers Funifier
+
+Triggers são códigos JAVA executados dentro do FUNIFIER ENGINE quando um evento específico acontece na gamificação. Oferecem flexibilidade para manipular informações em tempo real, permitindo mudar o comportamento padrão das técnicas de jogos e funcionalidades da plataforma.
+
+**Acesso Studio:** `/studio/trigger`
+**API Endpoint:** `/v3/trigger`
+
+## Configuração de uma Trigger
+
+Uma trigger é composta de três informações essenciais:
+1. **Evento** (`event`): quando a trigger deve ser executada
+2. **Entidade** (`entity`): que tipo de objeto está vinculado ao evento
+3. **Script** (`script`): código Java a ser executado
+
+```json
+{
+  "name": "Make the player's name uppercase",
+  "_id": "DTv7uHc",
+  "description": "Before creating the player, change the letters of the name to uppercase",
+  "entity": "player",
+  "event": "before_create",
+  "script": "void trigger(event, entity, player, database){ entity.name = entity.name.toUpperCase(); }"
+}
+```
+
+## Eventos e Entidades
+
+### Eventos
+
+| Evento | Quando é acionado |
+|--------|-------------------|
+| `before_create` | Antes de criar no banco |
+| `after_create` | Depois de criar no banco |
+| `before_update` | Antes de atualizar |
+| `after_delete` | Depois de deletar |
+| `before_win` | Antes de conquistar |
+| `after_win` | Depois de conquistar |
+
+### Combinações Comuns
+
+| Evento | Entidade | Quando é acionado | Tipo do entity |
+|--------|----------|-------------------|----------------|
+| `before_create` | `player` | Antes de cadastrar jogador | Player |
+| `after_create` | `player` | Depois de cadastrar jogador | Player |
+| `before_update` | `player` | Antes de alterar jogador | Player |
+| `after_delete` | `player` | Depois de remover jogador | Player |
+| `after_create` | `challenge` | Depois de criar desafio | Challenge |
+| `after_win` | `challenge` | Depois de completar desafio | Achievement |
+| `before_create` | `action` | Antes de criar ação | Action |
+| `before_win` | `action` | Antes de registrar action log | ActionLog |
+| `after_win` | `level` | Depois de subir de nível | Achievement |
+| `after_win` | `catalog_item` | Depois de comprar item | Achievement |
+| `after_win` | `lottery` | Depois de ser sorteado | Achievement |
+| `after_win` | `mystery_box` | Depois de ganhar prêmio surpresa | Achievement |
+| `after_win` | `competition` | Depois de vencer competição | Achievement |
+| `after_create` | `question_log` | Depois de responder pergunta | QuestionLog |
+| `before_create` | `achievement` | Antes de registrar recompensa | Achievement |
+| `before_create` | `<custom>__c` | Antes de criar objeto customizado | HashMap |
+
+## Parâmetros do Script
+
+```java
+void trigger(event, entity, player, database) {
+    // event: String com o evento (ex: "before_create")
+    // entity: Objeto sendo manipulado (Player, ActionLog, Achievement, etc.)
+    // player: String com o ID do jogador
+    // database: Objeto para acessar o banco de dados
+}
+```
+
+## Tipos de Objetos (entity)
+
+### Player
+```json
+{"_id": "john", "name": "John Travolta", "email": "john@funifier.com", "image": {"small": {"url": "..."}, "medium": {"url": "..."}, "original": {"url": "..."}}, "teams": ["sales"], "extra": {"country": "USA", "department": "IT"}}
+```
+
+### ActionLog
+```json
+{"_id": "64a5d92", "actionId": "sell", "userId": "john", "time": {"$date": "2023-07-05T20:57:33.303Z"}, "attributes": {"product": "book", "price": 120}}
+```
+
+### Achievement
+```json
+{"_id": "64a5d2", "player": "john", "total": 25.0, "type": 0, "item": "xp", "time": {"$date": "2023-07-05T20:57:33.303Z"}}
+```
+Tipos: `TYPE_POINT=0`, `TYPE_CHALLENGE=1`, `TYPE_VIRTUAL_GOOD=2`, `TYPE_LEVEL=3`
+
+### Challenge
+```json
+{"challenge": "Watch Video", "active": true, "_id": "DTo8dS3", "rules": [{"actionId": "watch_video", "operator": 5, "total": 0}], "points": [{"total": 10.0, "category": "xp", "operation": 0}]}
+```
+
+### Action
+```json
+{"_id": "sell", "action": "Sell", "attributes": [{"name": "product", "type": "String"}, {"name": "price", "type": "Number"}], "active": true}
+```
+
+## Managers Disponíveis
+
+### PlayerManager
+```java
+Player p = manager.getPlayerManager().findById("john");
+manager.getPlayerManager().insert(player);
+manager.getPlayerManager().delete("john");
+```
+
+### ActionManager
+```java
+Action a = manager.getActionManager().findActionById("sell");
+manager.getActionManager().track(actionLog);
+List<Achievement> results = manager.getActionManager().trackSynchronous(actionLog);
+```
+
+### CatalogManager
+```java
+CatalogItem item = manager.getCatalogManager().findItemById("DTj7lVn");
+manager.getCatalogManager().purchase(achievement, true);
+manager.getCatalogManager().undoPurchase("id");
+```
+
+### LotteryManager
+```java
+Lottery l = manager.getLotteryManager().find("DTj0x5z");
+manager.getLotteryManager().insertTicket(ticket);
+manager.getLotteryManager().execute("DTj0x5z");
+```
+
+### AchievementManager
+```java
+Achievement a = new Achievement();
+a.player = "john"; a.total = 10; a.type = 0; a.item = "xp";
+a.time = new Date(); a._id = Guid.newShortGuid();
+manager.getAchievementManager().addAchievement(a);
+```
+
+### Acesso ao Banco de Dados (Jongo)
+```java
+// Salvar
+manager.getJongoConnection().getCollection("email__c").save(payload);
+
+// Buscar
+Object result = manager.getJongoConnection().getCollection("player").findOne("{_id: 'john'}").as(Object.class);
+
+// Deletar
+manager.getJongoConnection().getCollection("car__c").remove("{_id: 'car001'}");
+```
+
+## Exemplos de Código
+
+### Exemplo 1: Duplicar pontos para jogadores de TI
+
+```java
+/* "event": "before_create", "entity": "achievement" */
+void trigger(event, entity, player, database) {
+    if(entity.type == Achievement.TYPE_POINT) {
+        Player currentPlayer = manager.getPlayerManager().findById(player);
+        if("IT".equals(currentPlayer.extra.department)) {
+            entity.total = entity.total * 2;
+        }
+    }
+}
+```
+
+### Exemplo 2: Dar ponto para todos os amigos
+
+```java
+/* "event": "before_create", "entity": "achievement" */
+void trigger(event, entity, player, database) {
+    if(entity.type == Achievement.TYPE_POINT && entity.total >= 100) {
+        Player p = manager.getPlayerManager().findById(player);
+        for(String friend : p.friends) {
+            Achievement a = new Achievement();
+            a.player = friend; a.total = 1; a.type = 0;
+            a.item = entity.item; a.time = new Date();
+            a._id = Guid.newShortGuid();
+            manager.getAchievementManager().addAchievement(a);
+        }
+    }
+}
+```
+
+### Exemplo 3: Enviar email de boas-vindas
+
+```java
+/* "event": "after_create", "entity": "player" */
+void trigger(event, entity, player, database) {
+    long total = manager.getPlayerManager().findTotal();
+    Email email = EmailBuilder
+        .startingBlank()
+        .from("Company", "your@company.com")
+        .to(entity.getName(), entity.email)
+        .withSubject("Welcome!")
+        .withPlainText("Welcome " + entity.name + ", you are member number " + total)
+        .buildEmail();
+    MailerBuilder.withSMTPServer("host", 587, "login", "password")
+        .buildMailer().sendMail(email);
+}
+```
+
+### Exemplo 4: Requisição HTTP com Unirest
+
+```java
+/* "event": "after_win", "entity": "catalog_item" */
+void trigger(event, entity, player, database) {
+    Player buyer = manager.getPlayerManager().findById(entity.player);
+    CatalogItem item = manager.getCatalogManager().findItemById(entity.item);
+    HashMap zap = new HashMap();
+    zap.put("purchase", entity);
+    zap.put("buyer", buyer);
+    zap.put("item", item);
+    HttpResponse<String> response = Unirest.post("https://hooks.zapier.com/hooks/catch/80/b6/")
+        .header("Content-Type", "application/json")
+        .body(JsonUtil.toJson(zap))
+        .asString();
+}
+```
+
+### Exemplo 5: Criar código de convite
+
+```java
+/* "event": "before_create", "entity": "player" */
+void trigger(event, entity, player, database) {
+    String code = Guid.shortTimeMillis();
+    entity.extra.put("code", code);
+}
+```
+
+### Exemplo 6: Consultar objeto no banco
+
+```java
+/* "event": "before_win", "entity": "action" */
+void trigger(event, entity, player, database) {
+    String id = entity.attributes.product;
+    Object product = database.getCollection("product__c").findOne("{_id:#}", id).as(Object.class);
+    entity.attributes.put("price", product.price);
+}
+```
+
+### Exemplo 7: Executar aggregate no banco
+
+```java
+/* "event": "before_win", "entity": "action" */
+void trigger(event, entity, player, database) {
+    org.jongo.MongoCollection collection = database.getCollection("achievement");
+    List<Object> highest = Arrays.asList(
+        collection.aggregate("{\"$match\": {\"type\": 0, \"item\": \"xp\"}}")
+        .and("{\"$group\": {\"_id\": \"$player\", \"total\": {\"$sum\": \"$total\"}}}")
+        .and("{\"$sort\": {\"total\": -1}}")
+        .and("{\"$limit\":1}")
+        .as(Object.class));
+    if(highest != null && highest.size() > 0) {
+        Object highestPointsPlayer = highest.get(0);
+        entity.attributes.put("highest", highestPointsPlayer.total);
+    }
+}
+```
+
+## Bibliotecas Disponíveis
+
+- **org.simplejavamail** - Envio de emails
+- **com.mashape.unirest** - Requisições HTTP
+- **org.jongo** - Acesso ao MongoDB
+- **JsonUtil** - Conversão JSON
+- **Guid** - Geração de IDs únicos
+- **DateUtil** - Cálculos e expressões de data
+
+> **Referência completa:** Para detalhes de todos os managers, entidades e bibliotecas disponíveis em Java, consulte:
+> - `guides/java-managers.md` — Todos os managers e seus métodos
+> - `guides/java-entities.md` — Entidades, campos e coleções MongoDB
+> - `guides/java-libraries.md` — JsonUtil, Guid, DateUtil, Unirest, EmailBuilder, Jongo

package/datasource-funifier-docs/knowledge/index.md

@@ -0,0 +1,121 @@
+# Funifier Knowledge Base — Index
+
+Este ficheiro serve como **router** para localizar o módulo ou guia correto na base de conhecimento Funifier. Cada entrada indica o ficheiro, uma descrição curta e quando usar.
+
+---
+
+## Recursos Fundacionais da Plataforma
+
+A Funifier funciona como um **backend de aplicações**. Independentemente do tipo de projeto (gamificação, app, portal, integração), os módulos abaixo são os recursos base disponíveis para construir qualquer aplicação:
+
+| Recurso | Ficheiro | Para que serve |
+|---------|----------|----------------|
+| **Auth** | `modules/auth.md` | Login de jogadores, geração de tokens JWT, autenticação via API |
+| **Player** | `modules/player.md` | Cadastro e gestão de utilizadores da aplicação |
+| **Database** | `modules/database.md` | CRUD em qualquer coleção, queries MongoDB, aggregates |
+| **Custom Object** | `modules/custom-object.md` | Criar tabelas/coleções próprias (sufixo `__c`) para dados de negócio |
+| **Upload** | `modules/upload.md` | Upload de imagens e ficheiros (avatar, documentos, etc.) |
+| **Trigger** | `modules/trigger.md` | Escrever funções Java que executam no servidor quando eventos acontecem |
+| **Scheduler** | `modules/scheduler.md` | Agendar tarefas automáticas (cron jobs, rotinas periódicas) |
+| **Public Endpoint** | `modules/public.md` | Criar APIs REST customizadas acessíveis sem autenticação |
+| **Webhook** | `modules/webhook.md` | Enviar dados para sistemas externos quando eventos acontecem |
+| **Patterns** | `modules/patterns.md` | Design patterns de implementação (signup, etc.) baseados em experiência real |
+
+> **Nota para o agente:** Estes recursos estão sempre disponíveis. Ao planear qualquer funcionalidade, considere-os como ferramentas que pode combinar livremente — não são exclusivos de gamificação.
+
+---
+
+## Módulos Essenciais (Core)
+
+| Módulo | Ficheiro | Descrição | Quando usar |
+|--------|----------|-----------|-------------|
+| Player | `modules/player.md` | Cadastro e gestão de jogadores | Criar, listar, atualizar ou remover jogadores; gerir campos extra e imagens |
+| Action | `modules/action.md` | Definição de tipos de ações | Criar ações que os jogadores podem executar (ex: vender, assistir vídeo) |
+| Action Log | `modules/action-log.md` | Registro de ações executadas | Registrar (track) que um jogador executou uma ação; consultar histórico |
+| Point | `modules/point.md` | Categorias de pontos | Criar moedas/pontos (XP, coins, estrelas); configurar tipos de pontuação |
+| Achievement | `modules/achievement.md` | Conquistas e recompensas | Consultar pontos ganhos, desafios completados, itens comprados; entender a estrutura de recompensas |
+| Challenge | `modules/challenge.md` | Desafios e missões | Criar desafios com regras de ação e recompensas automáticas |
+| Level | `modules/level.md` | Níveis de progressão | Configurar sistema de níveis baseado em pontos acumulados |
+| Leaderboard | `modules/leaderboard.md` | Rankings e classificações | Criar rankings por pontos, ações ou atributos; rankings por período |
+| Team | `modules/team.md` | Equipes e grupos | Organizar jogadores em equipes; rankings por equipe |
+| Virtual Good | `modules/virtual-good.md` | Loja virtual e catálogo | Criar itens para compra com pontos; gerir catálogo e compras |
+
+## Módulos de Engajamento
+
+| Módulo | Ficheiro | Descrição | Quando usar |
+|--------|----------|-----------|-------------|
+| Lottery | `modules/lottery.md` | Sorteios e rifas | Criar sorteios com tickets; executar sorteios automáticos ou manuais |
+| Competition | `modules/competition.md` | Competições entre jogadores | Criar competições temporárias com rankings e prémios para os melhores |
+| Mystery Box | `modules/mystery.md` | Caixas surpresa | Configurar prémios aleatórios com probabilidades definidas |
+| Swap | `modules/swap.md` | Troca entre jogadores | Permitir que jogadores troquem itens ou pontos entre si |
+| Question | `modules/question.md` | Perguntas e respostas | Criar perguntas com alternativas; registrar respostas dos jogadores |
+| Quiz | `modules/quiz.md` | Questionários completos | Montar questionários agrupando múltiplas perguntas; avaliar desempenho |
+| Crossword | `modules/crossword.md` | Palavras cruzadas | Criar jogos de palavras cruzadas como mecânica de engajamento |
+| Story | `modules/story.md` | Narrativas e storytelling | Criar histórias interativas com cenas e escolhas do jogador |
+| Avatar | `modules/avatar.md` | Avatares personalizáveis | Permitir que jogadores personalizem avatares com itens desbloqueáveis |
+| Last Mile | `modules/lastmile.md` | Incentivo à conclusão | Criar mecânicas que incentivam jogadores a completar tarefas pendentes |
+
+## Módulos Técnicos e Infraestrutura
+
+| Módulo | Ficheiro | Descrição | Quando usar |
+|--------|----------|-----------|-------------|
+| Trigger | `modules/trigger.md` | Código Java em eventos | Executar lógica customizada quando eventos acontecem (before/after create, win, etc.) |
+| Scheduler | `modules/scheduler.md` | Tarefas agendadas | Executar código Java em intervalos regulares (cron jobs) |
+| Webhook | `modules/webhook.md` | Notificações HTTP externas | Enviar dados para sistemas externos quando eventos acontecem na gamificação |
+| Notification | `modules/notification.md` | Notificações push e in-app | Enviar notificações para jogadores via push, email ou in-app |
+| WebSocket | `modules/websocket.md` | Comunicação em tempo real | Receber atualizações em tempo real no frontend via WebSocket |
+| Public Endpoint | `modules/public.md` | APIs públicas customizadas | Criar endpoints REST customizados sem autenticação (para integrações) |
+| Widget | `modules/widget.md` | Componentes visuais embeddáveis | Incorporar leaderboards, perfis e outros componentes em páginas externas |
+| Studio Page | `modules/studio-page.md` | Páginas customizadas no Studio | Criar páginas HTML/JS dentro do painel administrativo |
+| KPI Formulas | `modules/kpi-formulas.md` | Fórmulas e indicadores | Criar campos calculados e KPIs derivados de dados da gamificação |
+
+## Módulos de Dados e Armazenamento
+
+| Módulo | Ficheiro | Descrição | Quando usar |
+|--------|----------|-----------|-------------|
+| Database | `modules/database.md` | Acesso direto ao MongoDB | Operações CRUD em coleções; executar aggregates via API |
+| Custom Object | `modules/custom-object.md` | Coleções customizadas (`__c`) | Criar coleções de dados próprias (ex: `car__c`, `email__c`) |
+| CSV Data | `modules/csv-data.md` | Importação/exportação CSV | Importar jogadores ou dados em massa via CSV; exportar relatórios |
+| Upload | `modules/upload.md` | Upload de ficheiros | Fazer upload de imagens e ficheiros para o repositório Funifier |
+| Static Repo | `modules/static-repo.md` | Repositório de ficheiros estáticos | Hospedar ficheiros estáticos (HTML, CSS, JS, imagens) na plataforma |
+
+## Módulos de Administração
+
+| Módulo | Ficheiro | Descrição | Quando usar |
+|--------|----------|-----------|-------------|
+| Auth | `modules/auth.md` | Autenticação e tokens | Gerar tokens de acesso; configurar API keys; autenticação OAuth |
+| Folder | `modules/folder.md` | Organização em pastas | Organizar módulos (ações, desafios, etc.) em pastas no Studio |
+| Backup | `modules/backup.md` | Backup e restauração | Criar backups da gamificação; restaurar configurações |
+| Compact | `modules/compact.md` | Compactação de dados | Compactar dados históricos para otimizar performance |
+| Staging | `modules/staging.md` | Ambiente de homologação | Testar configurações em ambiente separado antes de produção |
+| Marketplace | `modules/marketplace.md` | Templates de gamificação | Importar templates prontos do marketplace Funifier |
+
+---
+
+## Guias Transversais
+
+| Guia | Ficheiro | Descrição | Quando usar |
+|------|----------|-----------|-------------|
+| Aggregates | `guides/aggregates.md` | Consultas avançadas MongoDB | Criar relatórios, dashboards, rankings customizados; usar expressões de data Funifier |
+| Triggers | `guides/triggers-guide.md` | Guia completo de triggers | Referência de eventos, entidades, managers e exemplos de código Java |
+| Database Access | `guides/database-access.md` | Acesso ao banco de dados | Referência de acesso via API REST e via código Java (Jongo) |
+| Java Managers | `guides/java-managers.md` | Referência de managers Java | Métodos disponíveis em cada manager (PlayerManager, ActionManager, etc.) para uso em triggers, schedulers e public endpoints |
+| Java Entities | `guides/java-entities.md` | Referência de entidades Java | Campos e tipos dos objetos (Player, Achievement, ActionLog, etc.) e mapeamento para coleções MongoDB |
+| Java Libraries | `guides/java-libraries.md` | Bibliotecas e utilitários Java | JsonUtil, Guid, DateUtil, Unirest, EmailBuilder, Jongo — métodos e exemplos de uso |
+
+---
+
+## Como usar este index
+
+1. **Identifique a necessidade** do utilizador (ex: "quero criar um ranking")
+2. **Localize o módulo** na tabela acima (ex: Leaderboard)
+3. **Carregue o ficheiro** correspondente (ex: `modules/leaderboard.md`)
+4. **Siga o checklist** de configuração e use os exemplos de API
+
+Para consultas que envolvem **múltiplos módulos**, carregue cada ficheiro individualmente conforme necessário.
+
+Para **relatórios e queries avançadas**, consulte `guides/aggregates.md`.
+
+Para **lógica customizada com código**, consulte `guides/triggers-guide.md` e `guides/database-access.md`.
+
+Para **referência completa de recursos Java** (managers, entidades, bibliotecas), consulte `guides/java-managers.md`, `guides/java-entities.md` e `guides/java-libraries.md`.

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

@@ -0,0 +1,46 @@
+# Achievement (Conquista)
+
+**API Endpoint:** `/v3/achievement`
+
+## O que é
+
+Registro das conquistas dos jogadores ao atingirem marcos relevantes. Todas as conquistas — como completar desafios, subir de nível, ganhar pontos ou adquirir itens — são registradas neste módulo. Ele automatiza o reconhecimento dos marcos alcançados, mas permite ajustes manuais.
+
+## Quando usar
+
+- Para consultar conquistas dos jogadores
+- Para criar relatórios de desempenho
+- Para usar em aggregates e dashboards
+- Para triggers que reagem a conquistas
+
+## Estrutura do Objeto
+
+```json
+{
+  "_id": "64a5d2",
+  "player": "john",
+  "total": 25.0,
+  "type": 0,
+  "item": "xp",
+  "time": {"$date": "2023-07-05T20:57:33.303Z"}
+}
+```
+
+**Tipos de Achievement (campo type):**
+- `0` = Point (ponto ganho)
+- `1` = Challenge (desafio completado)
+- `2` = Virtual Good (item comprado)
+- `3` = Level (nível atingido)
+
+## API Endpoints
+
+### Listar Conquistas
+**Método:** GET
+**Endpoint:** `/v3/achievement`
+
+## Validações e Testes
+
+- [ ] Ao completar desafio, achievement tipo 1 é criado
+- [ ] Ao ganhar pontos, achievement tipo 0 é criado
+- [ ] Ao comprar item, achievement tipo 2 é criado
+- [ ] Ao subir de nível, achievement tipo 3 é criado

package/datasource-funifier-docs/knowledge/modules/action-log.md

@@ -0,0 +1,88 @@
+# Action Log (Registro de Ação)
+
+**API Endpoint:** `/v3/action/log`
+
+## O que é
+
+Registro detalhado de todas as ações executadas pelos jogadores. Armazena cada ação realizada, com detalhes como quem executou, qual ação foi feita e quando ocorreu. Esse registro alimenta todos os outros módulos da plataforma.
+
+## Quando usar
+
+- Para registrar que um jogador executou uma ação
+- Para alimentar desafios, rankings e recompensas
+- Para importar ações em lote de sistemas externos
+- Para rastrear comportamento dos jogadores
+
+## Dependências
+
+- **Action**: a ação referenciada deve existir
+- **Player**: o jogador referenciado deve existir
+
+## API Endpoints
+
+### Listar ActionLogs
+**Método:** GET
+**Endpoint:** `/v3/action/log`
+
+**Exemplo de Resposta:**
+```json
+[
+  {
+    "_id": "6509e4e28325771ffaa4506e",
+    "actionId": "sell",
+    "userId": "jerry",
+    "time": 1695147234712,
+    "attributes": {
+      "product": "bike",
+      "price": 1200
+    }
+  }
+]
+```
+
+### Registrar ActionLog
+**Método:** POST
+**Endpoint:** `/v3/action/log`
+
+**Exemplo de Body:**
+```json
+{
+  "actionId": "sell",
+  "userId": "jerry",
+  "attributes": {
+    "product": "bike",
+    "price": 1200
+  }
+}
+```
+
+### Registrar Múltiplos ActionLogs
+**Método:** POST
+**Endpoint:** `/v3/action/log/bulk`
+
+**Exemplo de Body:**
+```json
+[
+  {
+    "actionId": "sell",
+    "userId": "jerry",
+    "attributes": { "product": "bike", "price": 1200 }
+  },
+  {
+    "actionId": "sell",
+    "userId": "tom",
+    "attributes": { "product": "book", "price": 25 }
+  }
+]
+```
+
+### Excluir ActionLog
+**Método:** DELETE
+**Endpoint:** `/v3/action/log/:id`
+
+## Validações e Testes
+
+- [ ] ActionLog aparece na lista com dados corretos
+- [ ] Ao registrar action log, desafios relacionados progridem
+- [ ] Bulk insert registra múltiplas ações corretamente
+- [ ] Atributos são armazenados conforme definido na ação

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

@@ -0,0 +1,80 @@
+# Action (Ação)
+
+**Acesso Studio:** `/studio/action`
+**API Endpoint:** `/v3/action`
+
+## O que é
+
+Cadastro das diferentes ações que os jogadores podem realizar na gamificação. Permite criar e configurar todas as ações possíveis dentro da experiência gamificada, como "vender", "comprar", "comentar", "compartilhar", entre outras. As ações são a base da estratégia de engajamento, pois definem o que é possível fazer na gamificação e servem para disparar regras e recompensas. É possível adicionar atributos extras a cada ação, por exemplo, "produto" e "valor" na ação de venda.
+
+## Quando usar
+
+- Em todo projeto de gamificação (obrigatório)
+- Para definir os comportamentos que serão rastreados
+- Para criar a base de eventos que disparam desafios e recompensas
+
+## Checklist de Configuração no Studio
+
+- [ ] Definir o _id da ação (letras minúsculas, sem espaços ou acentos)
+- [ ] Definir o nome amigável da ação (inicial maiúscula)
+- [ ] Definir atributos extras se necessário (name + type: String, Number ou Boolean)
+- [ ] Ativar a ação (active: true)
+- [ ] Boas práticas: criar ações genéricas e usar atributos para detalhar contexto
+
+## API Endpoints
+
+### Listar Ações
+**Método:** GET
+**Endpoint:** `/v3/action`
+**Descrição:** Retorna a lista de ações configuradas na gamificação.
+
+**Exemplo de Resposta:**
+```json
+[
+  {
+    "action": "Sell",
+    "attributes": [
+      { "name": "product", "type": "String" },
+      { "name": "price", "type": "Number" }
+    ],
+    "active": true,
+    "_id": "sell"
+  }
+]
+```
+
+### Criar Ação
+**Método:** POST
+**Endpoint:** `/v3/action`
+**Descrição:** Cria uma nova ação com nome, atributos e status de ativação.
+
+**Exemplo de Body:**
+```json
+{
+  "_id": "sell",
+  "active": true,
+  "action": "Sell",
+  "attributes": [
+    { "name": "product", "type": "String" },
+    { "name": "price", "type": "Number" }
+  ]
+}
+```
+
+### Excluir Ação
+**Método:** DELETE
+**Endpoint:** `/v3/action/:id`
+**Descrição:** Remove uma ação da gamificação.
+
+## Boas Práticas
+
+- Crie ações genéricas como "comprar", "vender", "responder", "visitar"
+- Use os atributos para detalhar o contexto da ação (ex: produto, local, valor)
+- Evite criar uma ação diferente para cada variação. Exemplo errado: "comprar sapato", "comprar camisa". Exemplo certo: ação "comprar" com atributo "produto"
+
+## Validações e Testes
+
+- [ ] Ação aparece na lista GET /v3/action
+- [ ] Ação tem _id único e sem caracteres especiais
+- [ ] Atributos estão com tipos corretos (String, Number, Boolean)
+- [ ] Ação está ativa (active: true)