funifier-mcp 0.2.25 → 0.2.27

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

@@ -1,52 +1,227 @@
-# Triggers Funifier
+# Triggers Funifier — Guia de Conceitos
 
-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.
+## 1. Visão Geral
 
-**Acesso Studio:** `/studio/trigger`
-**API Endpoint:** `/v3/trigger`
+### 1.1 O que é este documento
 
-## Configuração de uma Trigger
+Este documento descreve os conceitos de triggers Funifier — assinatura do script, variáveis disponíveis, eventos, entidades, regra de persistência e cadeia de conquistas — para escrever código Java/Groovy que executa no Funifier Engine quando um evento acontece. É o hub dos triggers; catálogos de managers/entidades/bibliotecas e exemplos de produção vivem em arquivos próprios.
 
-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
+**Acesso Studio:** `/studio/trigger` · **API:** `/v3/trigger`
+
+### 1.2 Quando consultar
+
+- Consulte ao **criar uma trigger** e precisar entender `event`, `entity`, `script`.
+- Consulte ao precisar saber **quais variáveis** o script recebe (`event`, `entity`, `player`, `database`, `manager`, `context`).
+- Consulte ao escolher o **evento certo** (incl. eventos de bulk/CSV).
+- Consulte ao precisar **rejeitar uma criação** ou entender por que `throw` não cancela.
+- Consulte ao precisar ler a **origem de uma conquista** (`context.extra`).
+
+### 1.3 Quando NÃO consultar
+
+- **NÃO** consulte para os **métodos dos managers** — use `datasource-funifier-docs/knowledge/guides/java-managers.md`.
+- **NÃO** consulte para **campos das entidades** — use `datasource-funifier-docs/knowledge/guides/java-entities.md`.
+- **NÃO** consulte para **bibliotecas** (JsonUtil, Guid, Unirest, Email) — use `datasource-funifier-docs/knowledge/guides/java-libraries.md`.
+- **NÃO** consulte para **exemplos de produção prontos** — use `datasource-funifier-docs/knowledge/guides/trigger-examples.md`.
+
+### 1.4 Índice de decisão
+
+| Problema / Situação | O que fazer | Seção |
+|---|---|---|
+| Montar o documento da trigger | Configuração (event/entity/script) | §2 |
+| Saber o que o script recebe | Assinatura e variáveis implícitas | §3 |
+| Escolher o evento | Eventos oficiais e estendidos | §4 |
+| Escolher a entidade | Entidades disponíveis | §5 |
+| Saber o tipo do `entity` para cada combinação | Combinações Evento × Entidade | §6 |
+| Saber qual ação/conquista originou o evento | `context.extra` (cadeia de conquistas) | §7 |
+| Rejeitar uma criação inválida | Regra de persistência + BusinessException | §8 |
+| Processar import/insert em lote | `entity` como List (bulk) | §9 |
+
+### 1.5 Restrições globais críticas
+
+> ⚠️ **`throw` NÃO cancela a persistência.** O Funifier persiste o documento; lançar exceção não faz rollback (`trigger-examples.md`). Consequência: tentativas de "bloquear" criação com `throw` falham silenciosamente. → `before_create` serve só para **enriquecer** (normalizar, defaults, metadados); para **rejeitar**, use `after_create` + `database.delete(...)` (§8).
+
+> ⚠️ **Em Groovy, acesse o ID com `entity.id`, não `entity._id`.** Consequência: `_id` retorna `null` (`patterns.md` §10). → Use `.id` em código; `_id` só no JSON/documento. Vale para `entity`, `player`, `ActionLog`, `Achievement`.
+
+> ⚠️ **O evento depende do método HTTP que originou a operação.** `PUT` → `before_update`/`after_update`; `POST` → `before_create`/`after_create` (`patterns.md` §1.5, `modules/trigger.md` §3.1). Consequência: a trigger esperada não roda. → Escolha o método no frontend conforme o evento da trigger (ex: Signup usa `PUT` para acionar `before_update`).
+
+> ⚠️ **Nunca dispare `track`/`trackSynchonous` para a mesma ação que acionou a trigger.** Consequência: loop infinito (`java-managers.md` §1.5). → Filtre por `entity.actionId` antes ou use outra ação.
+
+> ⚠️ **Timeout default de trigger: 5s** (configurável via campo `timeout` no `POST /v3/trigger`; não aparece no Studio). O teto independente do `@TimedInterrupt` é 200s. Tabela completa em `patterns.md` §1.5.
+
+### 1.6 Documentos relacionados
+
+> 📄 `datasource-funifier-docs/knowledge/guides/trigger-examples.md` — exemplos de produção (JSON + Groovy)
+> 📄 `datasource-funifier-docs/knowledge/guides/java-managers.md` — métodos de `manager.get*Manager()`
+> 📄 `datasource-funifier-docs/knowledge/guides/java-entities.md` — campos do `entity` por tipo
+> 📄 `datasource-funifier-docs/knowledge/guides/java-libraries.md` — JsonUtil, Guid, DateUtil, Unirest, Email
+> 📄 `datasource-funifier-docs/knowledge/guides/database-access.md` — `database.getCollection(...)`
+> 📄 `datasource-funifier-docs/knowledge/modules/patterns.md` §1.5 — sandbox, timeouts, eventos por método HTTP
+
+---
+
+## 2. Configuração de uma Trigger
+
+Quando usar: ao criar/atualizar o documento da trigger.
+Não usar quando: já tem o documento e precisa só do código → §3.
+Depende de: `Trigger` (entidade — `java-entities.md` §10).
+Disponível em: Trigger.
+
+### Descrição
+
+Uma trigger é um documento com três informações essenciais: **evento** (quando roda), **entidade** (que objeto está vinculado) e **script** (código a executar).
+
+### Uso
 
 ```json
 {
   "name": "Make the player's name uppercase",
   "_id": "DTv7uHc",
-  "description": "Before creating the player, change the letters of the name to uppercase",
+  "description": "Antes de criar o player, deixa o nome em maiúsculas",
   "entity": "player",
   "event": "before_create",
   "script": "void trigger(event, entity, player, database){ entity.name = entity.name.toUpperCase(); }"
 }
 ```
 
-## Eventos e Entidades
+O campo `timeout` (segundos) só é configurável via API (`patterns.md` §1.5).
+
+### Armadilhas conhecidas
+
+- **Atualizar a trigger via `POST` parcial** → o `script` pode ser apagado (full replace; `patterns.md` §1.5). Correção: reenviar o documento completo.
+
+---
 
-### Eventos
+## 3. Assinatura do Script e Variáveis Implícitas
+
+Quando usar: ao escrever o corpo do script.
+Não usar quando: —
+Depende de: `manager` (managers), `context` (cadeia de conquistas §7), `database` (Jongo).
+Disponível em: Trigger.
+
+### Descrição
+
+O script define a função `trigger` com quatro parâmetros. Além deles, o runtime expõe variáveis **implícitas** (não declaradas na assinatura): `manager`, `context` e `println`.
+
+### Uso
+
+```java
+void trigger(event, entity, player, database) {
+    // PARÂMETROS:
+    // event    — String do evento (ex: "before_create")
+    // entity   — objeto manipulado (Player, ActionLog, Achievement, HashMap de __c…)
+    // player   — String com o ID do jogador
+    // database — conexão Jongo (database.getCollection(...) — ver database-access.md)
+
+    // IMPLÍCITOS (não na assinatura):
+    // manager  — ManagerFactory: manager.getPlayerManager()… (java-managers.md)
+    // context  — contexto da execução; context.extra traz a origem (§7)
+    // println  — log para o trigger_log
+}
+```
+
+Exemplo mínimo (enriquecimento):
+```groovy
+void trigger(event, entity, player, database) {
+    entity.name = entity.name.toUpperCase();   // mutação persiste (before_create)
+    println("normalizado: " + entity.id);      // .id, não ._id (§1.5)
+}
+```
+
+### Armadilhas conhecidas
+
+- **Esperar `manager`/`context` na assinatura** → são implícitos; use-os direto.
+- **Usar `entity._id`** → `null` em Groovy. Correção: `entity.id` (§1.5).
+
+---
+
+## 4. Eventos
+
+Quando usar: ao definir `event` na trigger.
+Não usar quando: —
+Depende de: método HTTP da operação (§1.5).
+Disponível em: Trigger.
+
+### Descrição
+
+Eventos definem **quando** a trigger roda. Os oficiais aparecem no dropdown do Studio; os estendidos só por texto livre.
+
+### Uso
+
+**Oficiais (dropdown):**
 
 | 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 |
+| `before_win` / `after_win` | Antes/depois de registrar uma conquista |
+| `before_lose` / `after_lose` | Antes/depois de remover uma conquista |
+| `before_create` / `after_create` | Antes/depois de persistir um novo documento |
+| `before_update` / `after_update` | Antes/depois de atualizar |
+| `before_delete` / `after_delete` | Antes/depois de deletar |
+
+**Estendidos (free-text — não aparecem no dropdown):**
+
+| Evento | Quando é acionado |
+|--------|-------------------|
+| `before_bulk` / `after_bulk` | Antes/depois de insert/update em lote via API |
+| `csv_before_bulk` / `csv_after_bulk` | Antes/depois de processar um import CSV |
+
+> Nos eventos de bulk/CSV, `entity` é uma **List**, não um único documento (§9).
+
+### Armadilhas conhecidas
+
+- **`before_create` esperando bloquear via `throw`** → não cancela (§1.5/§8).
+- **`POST` esperando acionar `before_update`** → `POST` dispara `before_create` (§1.5).
+
+---
+
+## 5. Entidades
+
+Quando usar: ao definir `entity` na trigger.
+Não usar quando: —
+Depende de: `java-entities.md` (tipos resultantes).
+Disponível em: Trigger.
+
+### Descrição
+
+A entidade vincula a trigger a um tipo de objeto. O Studio oferece um dropdown fixo + entidades dinâmicas; texto livre aceita qualquer nome.
+
+### Uso
+
+**Dropdown hardcoded:** `action`, `catalog`, `catalog_item`, `crown`, `leaderboard`, `level`, `player`, `team`, `challenge`, `point_category`, `character_star_stats_level`, `upload`, `mystery_box`, `lottery`
 
-### Combinações Comuns
+**Dinâmicas** (via `/v3/database/collections`): `achievement` e todas as coleções `__c` do projeto.
 
-| Evento | Entidade | Quando é acionado | Tipo do entity |
-|--------|----------|-------------------|----------------|
+**Excluídas** (não aparecem; acesse por código): `action_log`, `challenge_progress`, `player_status`, `security`, `technique_field`, `join_log`.
+
+**Free-text:** o formulário aceita qualquer nome de entidade/evento não listado.
+
+### Armadilhas conhecidas
+
+- **Procurar `action_log` no dropdown** → não aparece (é excluída). Para reagir a logs, use `entity: action` com evento `before_win`/`after_win`.
+
+---
+
+## 6. Combinações Evento × Entidade
+
+Quando usar: para saber o **tipo do `entity`** numa dada combinação.
+Não usar quando: precisar dos campos desse tipo → `java-entities.md`.
+Depende de: §4, §5, `java-entities.md`.
+Disponível em: Trigger.
+
+### Descrição
+
+Cada combinação evento+entidade entrega um `entity` de tipo específico. Os mais usados:
+
+### Uso
+
+| Evento | Entidade | Quando | 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_create` | `action` | Antes de criar definição de 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 |
@@ -57,215 +232,122 @@ Uma trigger é composta de três informações essenciais:
 | `before_create` | `achievement` | Antes de registrar recompensa | Achievement |
 | `before_create` | `<custom>__c` | Antes de criar objeto customizado | HashMap |
 
-## Parâmetros do Script
+### Armadilhas conhecidas
 
-```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
-}
-```
+- **Assumir que `before_win action` entrega um Action** → entrega um **ActionLog** (o registro de execução), não a definição.
+- **Tratar `__c` como POJO** → é `HashMap`; use `entity.get("campo")` (`java-entities.md` §12).
 
-## 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"}}
-```
+## 7. context.extra — Cadeia de Conquistas
 
-### ActionLog
-```json
-{"_id": "64a5d92", "actionId": "sell", "userId": "john", "time": {"$date": "2023-07-05T20:57:33.303Z"}, "attributes": {"product": "book", "price": 120}}
-```
+Quando usar: ao precisar saber qual ação/conquista originou o evento atual.
+Não usar quando: o evento não vem de uma cadeia (`context.extra` pode ser `null`).
+Depende de: `Achievement`, `ActionLog` (`java-entities.md`).
+Disponível em: Trigger (eventos `before_win`, `before_create`, `after_create`).
 
-### 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}]}
-```
+### Descrição
 
-### Action
-```json
-{"_id": "sell", "action": "Sell", "attributes": [{"name": "product", "type": "String"}, {"name": "price", "type": "Number"}], "active": true}
-```
+Quando uma conquista é gerada por uma cadeia (uma ação dispara um desafio, que concede pontos…), `context.extra` expõe a origem. Disponível nos eventos acima quando há cadeia.
 
-## Managers Disponíveis
+### Uso
 
-### PlayerManager
 ```java
-Player p = manager.getPlayerManager().findById("john");
-manager.getPlayerManager().insert(player);
-manager.getPlayerManager().delete("john");
+context.extra.parentAchievement          // Achievement que gerou este evento
+context.extra.parentAchievement.id        // String
+context.extra.parentAchievement.type      // int (constantes em java-entities.md §3)
+context.extra.parentAchievement.item      // String
+context.extra.parentAchievement.player    // String
+context.extra.parentAchievement.total     // double
+
+context.extra.parentActionLog            // ActionLog que originou a cadeia
+context.extra.parentActionLog.id          // String
+context.extra.parentActionLog.actionId    // String
+context.extra.parentActionLog.userId      // String
+context.extra.parentActionLog.attributes  // Map
+
+context.extra.originActionLog            // ActionLog raiz (ponta da cadeia)
 ```
 
-### ActionManager
-```java
-Action a = manager.getActionManager().findActionById("sell");
-manager.getActionManager().track(actionLog);
-List<Achievement> results = manager.getActionManager().trackSynchonous(actionLog);
-```
+Exemplo de uso em `trigger-examples.md` (Exemplo 2 — taggear conquista com origem).
 
-### CatalogManager
-```java
-CatalogItem item = manager.getCatalogManager().findItemById("DTj7lVn");
-manager.getCatalogManager().purchase(achievement, true);
-manager.getCatalogManager().undoPurchase("id");
-```
+### Armadilhas conhecidas
 
-### LotteryManager
-```java
-Lottery l = manager.getLotteryManager().find("DTj0x5z");
-manager.getLotteryManager().insertTicket(ticket);
-manager.getLotteryManager().execute("DTj0x5z");
-```
+- **Acessar `context.extra.parentAchievement` sem checar null** → NPE. Correção: `if (context.extra == null) return;` e checar cada campo.
 
-### 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);
+## 8. Regra de Persistência e Rejeição de Criação
 
-// Buscar
-Object result = manager.getJongoConnection().getCollection("player").findOne("{_id: 'john'}").as(Object.class);
+Quando usar: ao precisar validar e **rejeitar** uma criação inválida.
+Não usar quando: só precisa enriquecer/normalizar → use `before_create` (mutação direta).
+Depende de: `database.delete(...)`, BusinessException (definida no próprio script).
+Disponível em: Trigger.
 
-// Deletar
-manager.getJongoConnection().getCollection("car__c").remove("{_id: 'car001'}");
-```
+### Descrição
 
-## Exemplos de Código
+O Funifier persiste o documento; `throw` não cancela (§1.5). Portanto: `before_create` enriquece; **rejeição** se faz em `after_create`, deletando o documento já salvo e devolvendo a mensagem no `entity`.
 
-### Exemplo 1: Duplicar pontos para jogadores de TI
+### Uso
 
-```java
-/* "event": "before_create", "entity": "achievement" */
+```groovy
 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;
-        }
+    try {
+        if (condicaoInvalida) throw new BusinessException("Motivo da rejeição");
+        // ... mais validações ...
+    } catch (BusinessException e) {
+        // a exceção é capturada DENTRO do trigger — não propaga para a plataforma
+        database.delete(entity.id, "collection__c");
+        entity.clear();
+        entity.put("message", e.getMessage());
+        return;
     }
 }
-```
 
-### 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);
-        }
-    }
+public class BusinessException extends Exception {
+    private String message;
+    public BusinessException(String msg) { super(msg); this.message = msg; }
+    public String getMessage() { return this.message; }
 }
 ```
 
-### Exemplo 3: Enviar email de boas-vindas
+`BusinessException` centraliza o cleanup quando há múltiplas validações. Para uma validação simples, o `database.delete` + `entity.clear()` + `entity.put("message", ...)` direto basta.
 
-```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);
-}
-```
+### Armadilhas conhecidas
 
-### Exemplo 4: Requisição HTTP com Unirest
+- **Usar `before_create` + `throw` para rejeitar** → o documento persiste mesmo assim. Correção: `after_create` + delete (`trigger-examples.md` Exemplo 5b).
+- **Esquecer `entity.clear()`** → o documento rejeitado retém dados (sensíveis, no caso de signup). Correção: limpar e devolver só `message`.
 
-```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
+## 9. `entity` como List (Eventos de Bulk)
 
-```java
-/* "event": "before_create", "entity": "player" */
-void trigger(event, entity, player, database) {
-    String code = Guid.shortTimeMillis();
-    entity.extra.put("code", code);
-}
-```
+Quando usar: ao reagir a `before_bulk`/`after_bulk`/`csv_*` (§4).
+Não usar quando: o evento é de documento único (`entity` é um objeto).
+Depende de: §4 (eventos estendidos).
+Disponível em: Trigger.
 
-### Exemplo 6: Consultar objeto no banco
+### Descrição
 
-```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);
-}
-```
+Nos eventos de lote, `entity` é uma **List** de documentos, não um único. Itere e processe cada item.
 
-### Exemplo 7: Executar aggregate no banco
+### Uso
 
-```java
-/* "event": "before_win", "entity": "action" */
+```groovy
 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);
+    if (entity == null || entity.isEmpty()) return;
+    for (Object raw : entity) {
+        HashMap<String, Object> item = (HashMap<String, Object>) raw;
+        if (item == null) continue;
+        // processar item...
     }
+    println("bulk processado: " + entity.size());
 }
 ```
 
-## Bibliotecas Disponíveis
+Exemplo completo em `trigger-examples.md` (Exemplo 6).
 
-- **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
+### Armadilhas conhecidas
 
-> **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
+- **Tratar `entity` como documento único em evento de bulk** → `ClassCastException`. Correção: iterar a List.
+- **`entity.size()` em evento não-bulk** → `entity` não é List. Correção: usar List só nos eventos de §4.

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

@@ -11,6 +11,7 @@ A Funifier funciona como um **backend de aplicações**. Independentemente do ti
 | Recurso | Ficheiro | Para que serve |
 |---------|----------|----------------|
 | **Auth** | `modules/auth.md` | Login de jogadores, geração de tokens JWT, autenticação via API |
+| **Security** | `modules/security.md` | Configuração do documento de segurança — apps com app_secret, roles de jogador, escopos, pipeline de autorização e emissão de tokens Bearer |
 | **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 |
@@ -84,7 +85,8 @@ A Funifier funciona como um **backend de aplicações**. Independentemente do ti
 | 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 |
+| Security | `modules/security.md` | Configuração de segurança | Configurar apps (app_secret, scope, whitelist) e roles de jogador; entender escopos hierárquicos, pipeline de autorização e emissão de tokens; diagnóstico de erros 401 |
+| Folder | `modules/folder.md` | Trilhas e cursos | Criar trilhas de aprendizagem e cursos; organizar conteúdos em hierarquia com monitoramento de progresso do jogador |
 | 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 |
@@ -98,6 +100,7 @@ A Funifier funciona como um **backend de aplicações**. Independentemente do ti
 |------|----------|-----------|-------------|
 | 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 |
+| Trigger Examples | `guides/trigger-examples.md` | Exemplos de produção de triggers | Código Groovy pronto para padrões reais: atualizar coleção relacionada, criar achievement, inicializar jogador, normalizar/rejeitar `__c`, processar lote, registrar ação via `track` |
 | 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 |
@@ -116,6 +119,6 @@ Para consultas que envolvem **múltiplos módulos**, carregue cada ficheiro indi
 
 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 **lógica customizada com código**, consulte `guides/triggers-guide.md` (conceitos e referência de eventos) e `guides/trigger-examples.md` (exemplos Groovy prontos), além de `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`.