funifier-mcp 0.2.26 → 0.2.27

package/datasource-funifier-docs/knowledge/guides/trigger-examples.md

@@ -1,178 +1,96 @@
 # Trigger Examples — Padrões de Produção
 
-Referência prática de eventos, entidades, constantes e exemplos reais para criação de triggers no Funifier.
+## 1. Visão Geral
 
----
-
-## Eventos Oficiais (dropdown do Studio)
-
-| Evento | Quando é acionado |
-|--------|-------------------|
-| `before_win` | Antes de registrar uma conquista (ponto, desafio, item) |
-| `after_win` | Depois de registrar uma conquista |
-| `before_lose` | Antes de remover uma conquista |
-| `after_lose` | Depois de remover uma conquista |
-| `before_create` | Antes de persistir um novo documento |
-| `after_create` | Depois de persistir um novo documento |
-| `before_update` | Antes de atualizar um documento existente |
-| `after_update` | Depois de atualizar um documento |
-| `before_delete` | Antes de deletar um documento |
-| `after_delete` | Depois de deletar um documento |
+### 1.1 O que é este documento
 
----
+Este documento reúne exemplos de produção de triggers Funifier — código Groovy pronto, anotado, para padrões reais (atualizar coleção relacionada, enriquecer conquista, criar achievement, inicializar jogador, normalizar/rejeitar `__c`, processar lote, disparar ação). Os **conceitos** (eventos, entidades, variáveis, regra de persistência) não são repetidos aqui — vivem no guia de triggers.
 
-## Eventos Estendidos (free-text only — não aparecem no dropdown)
+### 1.2 Quando consultar
 
-| Evento | Quando é acionado |
-|--------|-------------------|
-| `before_bulk` | Antes de um insert/update em lote via API |
-| `after_bulk` | Depois de um insert/update em lote via API |
-| `csv_before_bulk` | Antes de processar um import CSV |
-| `csv_after_bulk` | Depois de processar um import CSV |
+- Consulte ao precisar de um **exemplo concreto** para um par evento+entidade.
+- Consulte ao implementar **rejeição de criação** (`after_create` + delete) ou **processamento em lote**.
+- Consulte ao precisar **registrar uma ação** a partir de um trigger (`track`/`trackSynchonous`).
 
-> ⚠ Nesses eventos a variável `entity` recebe uma **List** (não um único documento). Itere com `for (Object item : entity)`.
+### 1.3 Quando NÃO consultar
 
----
+- **NÃO** consulte para entender **eventos, entidades, `context.extra` ou a regra de persistência** — use `datasource-funifier-docs/knowledge/guides/triggers-guide.md`.
+- **NÃO** consulte para **métodos de manager / campos de entidade / bibliotecas** — use `java-managers.md`, `java-entities.md`, `java-libraries.md`.
 
-## Entidades Disponíveis
+### 1.4 Índice de decisão
 
-**Dropdown hardcoded do Studio:**
-`action`, `catalog`, `catalog_item`, `crown`, `leaderboard`, `level`, `player`, `team`, `challenge`, `point_category`, `character_star_stats_level`, `upload`, `mystery_box`, `lottery`
+| Quero… | Exemplo | Seção |
+|---|---|---|
+| Atualizar um documento `__c` quando uma ação ocorre | `action \| before_win` | §3 |
+| Marcar a origem (ação/desafio) de uma conquista | `achievement \| before_create` | §4 |
+| Creditar pontos a outro jogador como efeito de uma ação | `action \| after_win` | §5 |
+| Preencher dados do jogador no cadastro | `player \| after_create` | §6 |
+| Normalizar campos antes de salvar um `__c` | `custom__c \| before_create` | §7 |
+| Validar e rejeitar a criação de um `__c` | `custom__c \| after_create` | §8 |
+| Processar um import/insert em lote | `custom__c \| after_bulk` | §9 |
+| Disparar uma ação de dentro de um trigger | `track` / `trackSynchonous` | §10 |
 
-**Entidades dinâmicas** (carregadas via `/v3/database/collections`):
-`achievement` e todas as coleções customizadas (`__c`) do projeto aparecem aqui.
-Excluídas: `action_log`, `challenge_progress`, `player_status`, `security`, `technique_field`, `join_log`.
+### 1.5 Restrições globais críticas
 
-**Free-text**: o formulário do Studio permite digitar qualquer nome de entidade/evento não listado.
+Todas herdadas de `triggers-guide.md` §1.5 — releia antes de copiar qualquer exemplo. As mais relevantes aqui:
 
----
+> ⚠️ **`throw` não cancela persistência** → rejeição é em `after_create` + `database.delete` (§8, e `triggers-guide.md` §8).
+> ⚠️ **Em Groovy use `.id`, não `._id`** → todos os exemplos abaixo seguem essa regra.
+> ⚠️ **Nunca `track` a mesma ação que disparou o trigger** → loop infinito; filtre por `entity.actionId` no início (§10).
 
-## Constantes de Achievement
+### 1.6 Documentos relacionados
 
-| Constante Java | Valor int | Descrição |
-|----------------|-----------|-----------|
-| `Achievement.TYPE_POINT` | `0` | Ponto acumulado |
-| `Achievement.TYPE_CHALLENGE` | `1` | Desafio completado |
-| `Achievement.TYPE_VIRTUAL_GOOD` | `2` | Item de catálogo comprado |
-| `Achievement.TYPE_LEVEL` | `3` | Nível alcançado |
-| `Achievement.TYPE_LOTTERY` | `5` | Loteria |
-| `Achievement.TYPE_COMPETITION` | `9` | Competição |
+> 📄 `datasource-funifier-docs/knowledge/guides/triggers-guide.md` — conceitos (eventos, entidades, `context.extra`, persistência)
+> 📄 `datasource-funifier-docs/knowledge/guides/java-managers.md` — `track`, `addAchievement`, `getJongoConnection`
+> 📄 `datasource-funifier-docs/knowledge/guides/database-access.md` — `findOne`/`save`/`count`/`delete`
 
 ---
 
-## Campos das Entidades Java nos Triggers
-
-### ActionLog (`entity` em triggers de `action`)
-```java
-entity.actionId    // String — ID da ação (ex: "complete_task")
-entity.userId      // String — ID do jogador que executou
-entity.attributes  // Map<String, Object> — atributos da ação
-entity.time        // Date — momento da execução
-entity.id          // String — alias para entity._id
-entity._id         // String — ID do registro de log
-```
-
-### Player (`entity` em triggers de `player`)
-```java
-entity._id / entity.id   // String — ID do jogador
-entity.name              // String
-entity.email             // String
-entity.extra             // Map<String, Object> — campos customizados
-entity.teams             // List<String> — IDs das equipes
-entity.image             // ImageSet — getOriginal().getUrl(), getMedium(), getSmall()
-```
+## 2. Formato do Documento de Trigger
 
-### Achievement (`entity` em triggers de `achievement` / `point_category`)
-```java
-entity._id / entity.id   // String
-entity.player            // String — ID do jogador
-entity.total             // double — quantidade
-entity.type              // int — ver tabela de constantes acima
-entity.item              // String — ID do ponto/desafio/item
-entity.time              // Date
-entity.extra             // Map<String, Object>
-```
-
----
+Quando usar: ao deployar qualquer exemplo abaixo via API.
+Não usar quando: criando a trigger pelo Studio (cole só o script no campo).
+Depende de: `Trigger` (`java-entities.md` §10).
+Disponível em: Trigger.
 
-## context.extra — Campos Disponíveis
+### Descrição
 
-Disponível nos eventos `before_win`, `before_create`, `after_create` quando a trigger é acionada por uma cadeia de conquistas:
+Os exemplos abaixo mostram o **script Groovy** legível. Para deployar via `POST /v3/trigger`, envolva o script (como string JSON-escapada) neste envelope:
 
-```java
-context.extra.parentAchievement         // Achievement que gerou este evento
-context.extra.parentAchievement.id      // String
-context.extra.parentAchievement.type    // int (usar constantes acima)
-context.extra.parentAchievement.item    // String
-context.extra.parentAchievement.player  // String
-context.extra.parentAchievement.total   // double
+### Uso
 
-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)
+```json
+{
+  "name": "Nome descritivo",
+  "entity": "<entidade>",
+  "event": "<evento>",
+  "active": true,
+  "script": "void trigger(event, entity, player, database) { /* … código … */ }"
+}
 ```
 
----
+### Armadilhas conhecidas
 
-## ⚠ Regra Crítica: Triggers NÃO impedem persistência via throw
-
-O Funifier **sempre salva o documento** antes de executar o trigger. Não é possível usar `throw` para cancelar a persistência.
-
-**Padrão correto para rejeitar uma criação:**
-1. Use `after_create` (não `before_create`)
-2. Valide no trigger; se inválido:
-   ```java
-   database.delete(entity._id, "collection__c");
-   entity.clear();
-   entity.put("message", "Motivo da rejeição");
-   return;
-   ```
-3. Para lógica complexa, use uma `BusinessException` interna para centralizar o cleanup:
-   ```java
-   // A exceção é capturada dentro do próprio trigger — não propaga para a plataforma
-   try {
-       if (condicaoInvalida) throw new BusinessException("Motivo");
-       // ... mais validações ...
-   } catch (BusinessException e) {
-       database.delete(entity._id, "collection__c");
-       entity.clear();
-       entity.put("message", e.getMessage());
-   }
-   
-   public class BusinessException extends Exception {
-       private String message;
-       public BusinessException(String message) { super(message); this.message = message; }
-       public String getMessage() { return this.message; }
-   }
-   ```
-
-**`before_create` é para enriquecimento apenas:** normalizar strings, preencher defaults, adicionar metadados.
+- **Atualizar a trigger com `POST` parcial** → o `script` é apagado (full replace; `patterns.md` §1.5). Correção: reenviar o documento completo.
 
 ---
 
-## Exemplos Anotados
+## 3. `action | before_win` — Atualizar Coleção Relacionada
 
-### Exemplo 1 — `action | before_win`: Atualizar coleção relacionada
+Quando usar: ler atributos de uma ActionLog e atualizar um documento em coleção `__c`.
+Não usar quando: o efeito é conceder pontos/conquista → §5.
+Depende de: `database`/`getJongoConnection` (`database-access.md`), `JsonUtil` (`java-libraries.md`).
+Disponível em: Trigger.
 
-Padrão: ler atributos da ActionLog, atualizar um documento em coleção customizada.
+### Descrição
 
-```json
-{
-  "name": "Update Task Status on Action Win",
-  "entity": "action",
-  "event": "before_win",
-  "active": true,
-  "script": "void trigger(event, entity, player, database) {\n    if (!entity.actionId.equals(\"complete_task\")) return;\n\n    String taskId = String.valueOf(entity.attributes.get(\"taskId\"));\n    if (taskId == null || taskId.equals(\"null\")) return;\n\n    HashMap<String, Object> task = manager.getJongoConnection()\n        .getCollection(\"task__c\")\n        .findOne(\"{_id:#}\", taskId).as(HashMap.class);\n\n    if (task != null) {\n        task.put(\"status\", \"done\");\n        task.put(\"completedAt\", new Date());\n        manager.getJongoConnection().getCollection(\"task__c\").save(task);\n        entity.attributes.put(\"status\", \"processed\");\n        println(\"task updated: \" + JsonUtil.toJson(task));\n    }\n}\n"
-}
-```
+Ação `complete_task` marca a task correspondente como concluída em `task__c`.
+
+### Uso
 
 ```groovy
 void trigger(event, entity, player, database) {
-    if (!entity.actionId.equals("complete_task")) return;
+    if (!entity.actionId.equals("complete_task")) return;   // filtra a ação alvo
 
     String taskId = String.valueOf(entity.attributes.get("taskId"));
     if (taskId == null || taskId.equals("null")) return;
@@ -191,28 +109,32 @@ void trigger(event, entity, player, database) {
 }
 ```
 
+### Armadilhas conhecidas
+
+- **Não filtrar `entity.actionId`** → roda para toda ação. Correção: `return` cedo se não for a ação alvo.
+- **`get("taskId")` ausente** → `"null"` (String). Correção: comparar com `"null"` após `String.valueOf`.
+
 ---
 
-### Exemplo 2 — `achievement | before_create`: Enriquecer com origem
+## 4. `achievement | before_create` — Enriquecer com Origem
 
-Padrão: ler `context.extra` para saber qual action log ou achievement gerou este registro.
+Quando usar: marcar de qual ação/desafio uma conquista de ponto se originou.
+Não usar quando: não precisa da origem → não leia `context.extra`.
+Depende de: `context.extra` (`triggers-guide.md` §7), constantes `TYPE_*` (`java-entities.md` §3).
+Disponível em: Trigger.
 
-```json
-{
-  "name": "Tag Achievement with Origin",
-  "entity": "achievement",
-  "event": "before_create",
-  "active": true,
-  "script": "void trigger(event, entity, player, database) {\n    if (entity.type != Achievement.TYPE_POINT) return;\n\n    if (entity.extra == null) entity.extra = new HashMap<>();\n    if (context.extra == null) return;\n\n    if (context.extra.parentAchievement != null &&\n        context.extra.parentAchievement.type == Achievement.TYPE_CHALLENGE) {\n        entity.extra.put(\"originChallenge\", context.extra.parentAchievement.id);\n    }\n\n    if (context.extra.parentActionLog != null) {\n        entity.extra.put(\"originAction\", context.extra.parentActionLog.id);\n        entity.extra.put(\"originActionId\", context.extra.parentActionLog.actionId);\n    }\n\n    println(\"entity: \" + JsonUtil.toJson(entity));\n}\n"
-}
-```
+### Descrição
+
+Ao criar um Achievement de ponto, grava no `extra` o desafio/ação que o gerou, lendo `context.extra`.
+
+### Uso
 
 ```groovy
 void trigger(event, entity, player, database) {
     if (entity.type != Achievement.TYPE_POINT) return;
 
     if (entity.extra == null) entity.extra = new HashMap<>();
-    if (context.extra == null) return;
+    if (context.extra == null) return;                       // sem cadeia → nada a marcar
 
     if (context.extra.parentAchievement != null &&
         context.extra.parentAchievement.type == Achievement.TYPE_CHALLENGE) {
@@ -228,21 +150,24 @@ void trigger(event, entity, player, database) {
 }
 ```
 
+### Armadilhas conhecidas
+
+- **Acessar `context.extra.*` sem checar null** → NPE. Correção: `if (context.extra == null) return;` e checar cada campo.
+
 ---
 
-### Exemplo 3 — `action | after_win`: Criar Achievement programaticamente
+## 5. `action | after_win` — Criar Achievement Programaticamente
 
-Padrão: creditar pontos para outro jogador como efeito colateral de uma ação.
+Quando usar: creditar pontos a outro jogador como efeito colateral de uma ação.
+Não usar quando: o crédito é para o próprio jogador da ação → as regras da ação já o fazem.
+Depende de: `AchievementManager.addAchievement` (`java-managers.md` §4), `Guid` (`java-libraries.md` §3).
+Disponível em: Trigger.
 
-```json
-{
-  "name": "Credit Referrer Points on Invite Accept",
-  "entity": "action",
-  "event": "after_win",
-  "active": true,
-  "script": "void trigger(event, entity, player, database) {\n    if (!entity.actionId.equals(\"accept_invite\")) return;\n\n    String referrerId = String.valueOf(entity.attributes.get(\"referrer\"));\n    if (referrerId == null || referrerId.equals(\"null\")) return;\n\n    Achievement credit = new Achievement();\n    credit.id = Guid.newShortGuid();\n    credit.type = Achievement.TYPE_POINT;\n    credit.player = referrerId;\n    credit.item = \"xp\";\n    credit.total = 50;\n    credit.time = new Date();\n    credit.extra = new HashMap();\n    credit.extra.put(\"origin\", entity.id);\n    credit.extra.put(\"originAction\", entity.actionId);\n\n    manager.getAchievementManager().addAchievement(credit);\n    println(\"credited: \" + JsonUtil.toJson(credit));\n}\n"
-}
-```
+### Descrição
+
+Ao aceitar um convite (`accept_invite`), credita 50 XP ao indicador (`referrer`).
+
+### Uso
 
 ```groovy
 void trigger(event, entity, player, database) {
@@ -252,7 +177,7 @@ void trigger(event, entity, player, database) {
     if (referrerId == null || referrerId.equals("null")) return;
 
     Achievement credit = new Achievement();
-    credit.id = Guid.newShortGuid();
+    credit.id = Guid.newShortGuid();           // .id, não ._id
     credit.type = Achievement.TYPE_POINT;
     credit.player = referrerId;
     credit.item = "xp";
@@ -267,21 +192,25 @@ void trigger(event, entity, player, database) {
 }
 ```
 
+### Armadilhas conhecidas
+
+- **`credit._id`** → não atribui em Groovy. Correção: `credit.id` (`triggers-guide.md` §1.5).
+- **Creditar sem filtrar a ação** → crédito indevido em qualquer ação. Correção: `return` cedo.
+
 ---
 
-### Exemplo 4 — `player | after_create`: Inicializar dados do jogador
+## 6. `player | after_create` — Inicializar Dados do Jogador
 
-Padrão: ao criar um jogador, buscar dados relacionados em coleção customizada e preencher `extra`.
+Quando usar: ao criar um jogador, buscar dados relacionados em `__c` e preencher `extra`.
+Não usar quando: os dados já vêm no payload de cadastro.
+Depende de: `PlayerManager` (`java-managers.md` §2), `getJongoConnection` (`database-access.md`).
+Disponível em: Trigger.
 
-```json
-{
-  "name": "Initialize Player from Employee Data",
-  "entity": "player",
-  "event": "after_create",
-  "active": true,
-  "script": "void trigger(event, entity, player, database) {\n    println(\"new player: \" + JsonUtil.toJson(entity));\n\n    HashMap<String, Object> employee = manager.getJongoConnection()\n        .getCollection(\"employee__c\")\n        .findOne(\"{email:#}\", entity.email).as(HashMap.class);\n\n    if (employee == null) return;\n\n    Player p = manager.getPlayerManager().findById(entity._id);\n    if (p == null) return;\n\n    if (p.extra == null) p.extra = new HashMap();\n    p.extra.put(\"department\", employee.get(\"department\"));\n    p.extra.put(\"role\", employee.get(\"role\"));\n    p.extra.put(\"employeeId\", employee.get(\"_id\"));\n\n    manager.getPlayerManager().insert(p);\n    println(\"player initialized: \" + p._id);\n}\n"
-}
-```
+### Descrição
+
+Ao cadastrar o jogador, busca o funcionário correspondente em `employee__c` (por email) e copia `department`/`role` para `player.extra`.
+
+### Uso
 
 ```groovy
 void trigger(event, entity, player, database) {
@@ -293,34 +222,40 @@ void trigger(event, entity, player, database) {
 
     if (employee == null) return;
 
-    Player p = manager.getPlayerManager().findById(entity._id);
+    Player p = manager.getPlayerManager().findById(entity.id);   // .id, não ._id
     if (p == null) return;
 
     if (p.extra == null) p.extra = new HashMap();
     p.extra.put("department", employee.get("department"));
     p.extra.put("role", employee.get("role"));
-    p.extra.put("employeeId", employee.get("_id"));
+    p.extra.put("employeeId", employee.get("_id"));              // _id é chave do HashMap (__c), não propriedade
 
-    manager.getPlayerManager().insert(p);
-    println("player initialized: " + p._id);
+    manager.getPlayerManager().insert(p);                        // insert = upsert (java-managers.md §2)
+    println("player initialized: " + p.id);
 }
 ```
 
+> Nota: em `__c` (HashMap) a chave é literalmente `"_id"` (`employee.get("_id")`); a regra `.id` vale só para POJOs em Groovy (`triggers-guide.md` §1.5).
+
+### Armadilhas conhecidas
+
+- **`pm.save(p)`** → inexistente. Correção: `insert` (`java-managers.md` §2).
+- **`entity._id`** → `null`. Correção: `entity.id`.
+
 ---
 
-### Exemplo 5a — `custom__c | before_create`: Normalizar campos antes de persistir
+## 7. `custom__c | before_create` — Normalizar Campos
 
-Padrão: `before_create` **não rejeita** — apenas enriquece/normaliza o `entity` antes de salvar.
+Quando usar: enriquecer/normalizar um documento `__c` antes de salvar.
+Não usar quando: precisa **rejeitar** o documento → §8 (`before_create` não rejeita).
+Depende de: —
+Disponível em: Trigger.
 
-```json
-{
-  "name": "Normalize Employee Fields",
-  "entity": "employee__c",
-  "event": "before_create",
-  "active": true,
-  "script": "void trigger(event, entity, player, database) {\n    entity.put(\"email\", normalizeEmail(entity.get(\"email\")));\n    entity.put(\"name\", normalizeName(entity.get(\"name\")));\n    entity.put(\"employeeId\", extractNumeric(entity.get(\"employeeId\")));\n}\n\nString normalizeEmail(Object value) {\n    if (value == null) return \"\";\n    String s = String.valueOf(value).replaceAll(\"\\\\s\", \"\");\n    return s.equals(\"null\") ? \"\" : s.toLowerCase();\n}\n\nString normalizeName(Object value) {\n    if (value == null) return \"\";\n    String s = String.valueOf(value).trim();\n    return s.equals(\"null\") ? \"\" : s;\n}\n\nString extractNumeric(Object value) {\n    if (value == null) return \"\";\n    try {\n        return String.valueOf(Long.parseLong(String.valueOf(value).replaceAll(\"\\\\s\", \"\")));\n    } catch (NumberFormatException e) {\n        return \"\";\n    }\n}\n"
-}
-```
+### Descrição
+
+`before_create` **não rejeita** (`triggers-guide.md` §8) — apenas normaliza email/nome/ID antes de persistir. Métodos auxiliares extraídos para clareza.
+
+### Uso
 
 ```groovy
 void trigger(event, entity, player, database) {
@@ -351,21 +286,24 @@ String extractNumeric(Object value) {
 }
 ```
 
+### Armadilhas conhecidas
+
+- **Esperar que `before_create` rejeite valores inválidos** → não rejeita; o documento salva. Correção: validar/rejeitar em `after_create` (§8).
+
 ---
 
-### Exemplo 5b — `custom__c | after_create`: Validar e rejeitar criação
+## 8. `custom__c | after_create` — Validar e Rejeitar
 
-Padrão: document já foi salvo — se inválido, deletar e retornar erro no `entity`.
+Quando usar: validar um documento `__c` recém-criado e rejeitá-lo se inválido.
+Não usar quando: só precisa normalizar → §7.
+Depende de: regra de persistência + `BusinessException` (`triggers-guide.md` §8), `getJongoConnection` (`database-access.md`).
+Disponível em: Trigger.
 
-```json
-{
-  "name": "Validate Order on Create",
-  "entity": "order__c",
-  "event": "after_create",
-  "active": true,
-  "script": "void trigger(event, entity, player, database) {\n    try {\n        if (player == null || player.isEmpty()) {\n            throw new BusinessException(\"Player obrigatório.\");\n        }\n\n        HashMap<String, Object> schedule = manager.getJongoConnection()\n            .getCollection(\"schedule__c\")\n            .findOne(\"{status:#}\", \"open\").as(HashMap.class);\n\n        if (schedule == null) {\n            throw new BusinessException(\"Nenhuma janela de cadastro aberta.\");\n        }\n\n        long existing = manager.getJongoConnection().getCollection(\"order__c\")\n            .count('{\"_id\":{\"$ne\":#},\"owner\":#,\"status\":{\"$ne\":\"cancelled\"}}',\n                entity._id, player);\n\n        if (existing >= 3) {\n            throw new BusinessException(\"Limite de cadastros atingido nesta janela.\");\n        }\n\n    } catch (BusinessException e) {\n        database.delete(entity._id, \"order__c\");\n        entity.clear();\n        entity.put(\"message\", e.getMessage());\n        println(\"rejected: \" + e.getMessage());\n        return;\n    }\n}\n\npublic class BusinessException extends Exception {\n    private String message;\n    public BusinessException(String msg) { super(msg); this.message = msg; }\n    public String getMessage() { return this.message; }\n}\n"
-}
-```
+### Descrição
+
+O documento já foi salvo (`triggers-guide.md` §1.5). Se inválido, deleta e devolve a mensagem no `entity`. `BusinessException` centraliza o cleanup das múltiplas validações.
+
+### Uso
 
 ```groovy
 void trigger(event, entity, player, database) {
@@ -384,14 +322,14 @@ void trigger(event, entity, player, database) {
 
         long existing = manager.getJongoConnection().getCollection("order__c")
             .count('{"_id":{"$ne":#},"owner":#,"status":{"$ne":"cancelled"}}',
-                entity._id, player);
+                entity.id, player);
 
         if (existing >= 3) {
             throw new BusinessException("Limite de cadastros atingido nesta janela.");
         }
 
     } catch (BusinessException e) {
-        database.delete(entity._id, "order__c");
+        database.delete(entity.id, "order__c");   // documento já salvo → deletar
         entity.clear();
         entity.put("message", e.getMessage());
         println("rejected: " + e.getMessage());
@@ -406,26 +344,29 @@ public class BusinessException extends Exception {
 }
 ```
 
+### Armadilhas conhecidas
+
+- **Usar `before_create` aqui** → `throw` não impede o save (`triggers-guide.md` §8). Correção: `after_create` + delete.
+- **Esquecer `entity.clear()`** → o documento rejeitado mantém os dados. Correção: limpar e devolver só `message`.
+
 ---
 
-### Exemplo 6 — `custom__c | after_bulk`: Processar import em lote
+## 9. `custom__c | after_bulk` — Processar Lote
 
-Padrão: `entity` é uma **List** — itere e processe cada item.
+Quando usar: processar cada item de um import/insert em lote.
+Não usar quando: o evento é de documento único → `entity` não é List (`triggers-guide.md` §9).
+Depende de: evento estendido `after_bulk` (`triggers-guide.md` §4, §9).
+Disponível em: Trigger.
 
-```json
-{
-  "name": "Process Imported Records",
-  "entity": "import__c",
-  "event": "after_bulk",
-  "active": true,
-  "script": "void trigger(event, entity, player, database) {\n    if (entity == null || entity.isEmpty()) return;\n\n    println(\"bulk size: \" + entity.size());\n\n    for (Object raw : entity) {\n        HashMap<String, Object> item = (HashMap<String, Object>) raw;\n        if (item == null) continue;\n\n        String employeeId = String.valueOf(item.get(\"employeeId\"));\n        if (employeeId == null || employeeId.equals(\"null\")) continue;\n\n        HashMap<String, Object> employee = manager.getJongoConnection()\n            .getCollection(\"employee__c\")\n            .findOne(\"{_id:#}\", employeeId).as(HashMap.class);\n\n        if (employee != null) {\n            item.put(\"department\", employee.get(\"department\"));\n            item.put(\"processed\", true);\n            manager.getJongoConnection().getCollection(\"import__c\").save(item);\n        }\n    }\n\n    println(\"bulk processed: \" + entity.size() + \" records\");\n}\n"
-}
-```
+### Descrição
+
+Em `after_bulk`, `entity` é uma **List**. Para cada item, busca o funcionário em `employee__c` e enriquece.
+
+### Uso
 
 ```groovy
 void trigger(event, entity, player, database) {
     if (entity == null || entity.isEmpty()) return;
-
     println("bulk size: " + entity.size());
 
     for (Object raw : entity) {
@@ -445,36 +386,38 @@ void trigger(event, entity, player, database) {
             manager.getJongoConnection().getCollection("import__c").save(item);
         }
     }
-
     println("bulk processed: " + entity.size() + " records");
 }
 ```
 
+### Armadilhas conhecidas
+
+- **Tratar `entity` como documento único** → `ClassCastException`. Correção: iterar a List (`triggers-guide.md` §9).
+
 ---
 
-### Exemplo 7 — Registrar uma ação programaticamente (`ActionManager.track`)
+## 10. Registrar Ação Programaticamente (`track` / `trackSynchonous`)
 
-Padrão: criar e disparar um ActionLog de dentro de um trigger, acionando as regras de gamificação normalmente.
+Quando usar: disparar uma ActionLog de dentro de um trigger, acionando as regras normalmente.
+Não usar quando: a ação a registrar é a **mesma** que disparou o trigger → loop infinito.
+Depende de: `ActionManager.track`/`trackSynchonous` (`java-managers.md` §3).
+Disponível em: Trigger.
 
-```json
-{
-  "name": "Track Secondary Action on Win",
-  "entity": "action",
-  "event": "after_win",
-  "active": true,
-  "script": "void trigger(event, entity, player, database) {\n    if (!entity.actionId.equals(\"complete_task\")) return;\n\n    ActionLog log = new ActionLog();\n    log.id = Guid.newShortGuid();\n    log.userId = entity.userId;\n    log.actionId = \"task_completed_by_team\";\n    log.time = new Date();\n    log.attributes = new HashMap();\n    log.attributes.put(\"taskId\", entity.attributes.get(\"taskId\"));\n    log.attributes.put(\"origin\", entity.id);\n    manager.getActionManager().track(log);\n    println(\"tracked async: \" + JsonUtil.toJson(log));\n}\n"
-}
-```
+### Descrição
+
+`track` é assíncrono (não bloqueia); `trackSynchonous` bloqueia e retorna as conquistas geradas. Escolha pela necessidade de saber o resultado.
+
+### Uso
 
+**Assíncrono** (dispara e segue):
 ```groovy
 void trigger(event, entity, player, database) {
-    if (!entity.actionId.equals("complete_task")) return;
+    if (!entity.actionId.equals("complete_task")) return;   // evita loop (§1.5)
 
-    // Async: dispara e não bloqueia — conquistas processadas em background
     ActionLog log = new ActionLog();
-    log.id = Guid.newShortGuid();   // .id, não ._id
+    log.id = Guid.newShortGuid();              // .id, não ._id
     log.userId = entity.userId;
-    log.actionId = "task_completed_by_team";
+    log.actionId = "task_completed_by_team";   // ação DIFERENTE da que disparou
     log.time = new Date();
     log.attributes = new HashMap();
     log.attributes.put("taskId", entity.attributes.get("taskId"));
@@ -484,11 +427,10 @@ void trigger(event, entity, player, database) {
 }
 ```
 
-Variante síncrona — use quando precisar saber quais conquistas foram geradas:
-
+**Síncrono** (precisa saber quais conquistas foram geradas):
 ```groovy
 void trigger(event, entity, player, database) {
-    // Add action filter: if (!entity.actionId.equals("your_action")) return;
+    // if (!entity.actionId.equals("your_action")) return;   // filtre para evitar loop
 
     ActionLog log = new ActionLog();
     log.id = Guid.newShortGuid();
@@ -497,7 +439,6 @@ void trigger(event, entity, player, database) {
     log.time = new Date();
     log.attributes = new HashMap();
 
-    // trackSynchonous bloqueia e retorna as conquistas geradas
     List<Achievement> earned = manager.getActionManager().trackSynchonous(log);
     if (earned != null) {
         println("earned: " + earned.size() + " achievements");
@@ -508,4 +449,7 @@ void trigger(event, entity, player, database) {
 }
 ```
 
-> ⚠ Nunca chame `track` ou `trackSynchonous` dentro de um trigger `before_win` / `after_win` para a **mesma entidade/ação** que disparou o trigger — causa loop infinito. Use uma action diferente ou verifique com `entity.actionId` antes.
+### Armadilhas conhecidas
+
+- **`track`/`trackSynchonous` da mesma ação que disparou** → loop infinito (§1.5). Correção: ação diferente ou filtro por `entity.actionId`.
+- **Esperar conquistas do `track`** → retorna `void`. Correção: `trackSynchonous` (`java-managers.md` §3).