funifier-mcp 0.2.26 → 0.2.27

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

@@ -1,189 +1,931 @@
-# Trigger (Trigger)
+# `trigger`
 
 **Acesso Studio:** `/studio/trigger`
 **API Endpoint:** `/v3/trigger`
+**Coleção MongoDB:** `trigger` (definições) + `trigger_log` (logs de execução)
 
-## O que é
+---
 
-Execução automática de códigos JAVA quando eventos específicos acontecem na gamificação. Permite programar ações customizadas disparadas por eventos, como o cadastro de um jogador ou a realização de uma compra. As triggers dão liberdade para alterar o comportamento padrão dos módulos, integrar com sistemas externos ou implementar automações em tempo real.
+## 1. Visão Geral
 
-## Quando usar
+O módulo `trigger` é o motor de **execução de scripts Groovy** acionados por eventos do ciclo de vida das entidades da plataforma. Cada documento `trigger` armazena um script Groovy que será compilado, cacheado em memória e executado quando uma combinação `(entity, event)` for disparada por algum outro manager do serviço.
 
-- Para enviar emails automáticos (ex: boas-vindas)
-- Para integrar com APIs externas (Zapier, CRM, etc.)
-- Para alterar pontuação com regras especiais
-- Para executar lógica de negócio personalizada
-- **Importante:** usar apenas quando as configurações padrão não atendem
+Papel arquitetural:
 
-## Checklist de Configuração no Studio
+- Único ponto de extensibilidade server-side da plataforma — permite estender qualquer comportamento da gamificação sem recompilar o serviço.
+- Compila o script com `GroovyClassLoader` configurado por `SecureASTCustomizer` + `TriggerExpressionChecker` (sandbox parcial — ver seção 8).
+- Mantém cache de classes compiladas indexado por `trigger.id` (`TriggerManager.compiled`), invalidado por `trigger.updated`.
+- Executa cada disparo em uma thread dedicada (`Executors.newSingleThreadExecutor()`), com timeout duro por trigger.
+- É chamado de forma síncrona — `TriggerManager.execute(...)` é uma chamada bloqueante que aguarda todos os triggers daquela combinação `(entity, event)` rodarem antes de retornar ao manager chamador.
 
-- [ ] Definir nome e descrição da trigger
-- [ ] Definir entidade observada (player, challenge, action, achievement, etc.)
-- [ ] Definir evento (before_create, after_create, before_win, after_win, etc.)
-- [ ] Escrever script Java com método `void trigger(event, entity, player, database)`
-- [ ] Testar trigger em ambiente de homologação
+Quem dispara o módulo (encontrado no código — `getTriggerManager().execute(...)`):
 
-## Eventos Disponíveis
+- `ActionManager.trackSynchonous` — `(action, before_win)` e `(action, after_win)` em volta do `addLog`.
+- `AchievementManager.fireAction` — `(point_category, before/after_win)`, `(challenge, before/after_win)`, `(<collection>, before/after_win)` em torno de cada Achievement persistido.
+- `AchievementManager.evaluateLevelUp` — `(level, before/after_win)` no instante do level up.
+- `CharacterStarManager.evaluateLevelUp` — `(character_star_stats_level, before/after_win)`.
+- `DatabaseManager.bulkInsert` — `(<collection>, before_bulk)`, `(<collection>, before_create)`, `(<collection>, after_create)` por item, `(<collection>, after_bulk)` no final.
+- `DatabaseRest.insert/update/delete` — `(<collection>, before_create|after_create|before_update|after_update|before_delete|after_delete)`.
+- `CatalogManager.purchase` / `PurchaseManager.buy` — `(catalog_item, before_purchase_validation)`, `(catalog_item, before_win)`, `(catalog_item, after_win)`.
+- `SwapManager.*` — `(swap, before/after_create|delete|win)`, `(swap, before_acquire_validation)`, `(swap_counter_offer, ...)`.
+- `MysteryBoxManager.execute` — `(mystery_box, before_win)`, `(mystery_box, before_lose)`, `(mystery_box, before_win_reward)`, `(mystery_box, after_win|after_lose)`.
+- `LotteryManager.execute` — `(lottery_ticket, before/after_win)`.
+- `CompetitionManager.execute/insert/insertJoin` — `(competition, ...)`.
+- `CrowningManager.calculateLeaderBoardV3/calculateCrown` — `(crown, ...)`.
+- `QuizManager.insert/start/finish`, `QuestionManager.insert/insertLog` — eventos `before/after_create|update`.
+- `FolderManager.insertLog/deleteLog` / `FolderRest.progress` — `(folder_log, before/after_create|delete)` e `("folder_progress", after_create)`.
+- `PlayerManager.insert/delete`, `PlayerRest.changePassword(Request)` — `(player, before/after_create|delete)` e `(password_change, ...)`.
+- `BackupManager.asyncExecute`, `CompactManager.asyncExecute`, `BetManager.delete`, `CsvManager.insertBulkSync(Helper)`, `UploadRest.uploadFile`, `CrmManager.*` — disparam eventos próprios sobre suas coleções.
 
-| Prefixo | Sufixo | Descrição |
-|---------|--------|-----------|
-| before_ | create | Antes de criar |
-| after_ | create | Depois de criar |
-| before_ | update | Antes de atualizar |
-| after_ | delete | Depois de deletar |
-| before_ | win | Antes de conquistar |
-| after_ | win | Depois de conquistar |
+Total: **29 arquivos** invocando `manager.getTriggerManager().execute(...)`, **146 sites de chamada** no `src/main/java` (sem testes).
 
-## Entidades Disponíveis
+Relação com outros módulos:
 
-- `player`, `action`, `challenge`, `achievement`, `level`, `catalog_item`, `lottery`, `mystery_box`, `competition`, `question_log`, `<custom>__c`
+- **Statistic / GamificationLimits** — antes de cada execução, `SystemFactory.getInstance().getStatisticManager(apiKey).newTriggerExecution(trigger.id)` é chamado. Se o limite diário (`GamificationLimits.dailyTriggerExecutions`) for excedido, a execução é silenciosamente bloqueada (apenas um `System.out.println` de erro).
+- **TriggerExpressionChecker** — bloqueia uso de `.execute`, `.getDB`, `.getMongo`, `.dropDatabase` e dos tipos `System`, `ProcessBuilder`, `File`, `GroovyShell`, `GroovyObject` no AST.
+- **GameDao** — wrapper fino sobre Jongo que é injetado como `database` em todo script.
 
-## API Endpoints
+---
 
-### Listar Triggers
-**Método:** GET
-**Endpoint:** `/v3/trigger`
+## 2. Arquitetura e Fluxos
 
-### Criar Trigger
-**Método:** POST
-**Endpoint:** `/v3/trigger`
+### 2.1 Classes envolvidas
 
-**Exemplo de Body:**
-```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(); }"
+| Classe | Arquivo | Papel |
+|---|---|---|
+| `Trigger` | `engine/integration/trigger/Trigger.java` | Entidade persistida — script + metadata. |
+| `Reference` | `engine/integration/trigger/Reference.java` | Subdocumento (vínculo visual com outros itens da estratégia). |
+| `ObjectStyle` | `engine/integration/trigger/ObjectStyle.java` | Subdocumento (`background`, `visible`) para apresentação no Studio. |
+| `TriggerContext` | `engine/integration/trigger/TriggerContext.java` | Objeto de transporte runtime (`manager`, `origin`, `extra`). |
+| `TriggerDaoMongo` | `engine/integration/trigger/TriggerDaoMongo.java` | DAO Jongo direto (CRUD + `findByEntityAndEvent`). |
+| `TriggerManager` | `engine/integration/trigger/TriggerManager.java` | Orquestrador — mantém os caches `compiled` e `dates`. |
+| `TriggerRunner` | `engine/integration/trigger/TriggerRunner.java` | Compila e roda o script em executor isolado com timeout. |
+| `TriggerExpressionChecker` | `engine/integration/trigger/TriggerExpressionChecker.java` | `SecureASTCustomizer.ExpressionChecker` — bloqueia tokens/classes proibidas. |
+| `TriggerLog` | `engine/integration/trigger/TriggerLog.java` | Documento gravado em `trigger_log` após cada execução. |
+| `GameDao` | `engine/integration/trigger/GameDao.java` | Wrapper sobre Jongo passado ao script como `database`. |
+| `TriggerStatistics` | `engine/stats/TriggerStatistics.java` | Contadores agregados de execução por trigger / dia / hora / mês. |
+| `TriggerDetailStatistics` | `engine/stats/TriggerDetailStatistics.java` | Mesmas estatísticas por `trigger.id`. |
+| `TriggerHtml` | `engine/integration/html/TriggerHtml.java` | **Não é trigger server-side.** Modelo client-side — coleção `trigger_html` — usado pelo SDK web. |
+| `TriggerRest` | `rest/v3/rest/TriggerRest.java` | Endpoints REST `/v3/trigger`. |
+
+### 2.2 Pipeline principal — `TriggerManager.execute(id, o, entity, event, player, context)`
+
+```
+[1]  start = System.currentTimeMillis()
+[2]  runner = new TriggerRunner()
+[3]  Para cada trigger em mongo.findByEntityAndEvent(entity, event):
+       [3.1] limitOk = SystemFactory.getInstance()
+                        .getStatisticManager(manager.getApiKey())
+                        .newTriggerExecution(trigger.id)
+       [3.2] Se limitOk:
+               runner.run(trigger, o, player, manager, context)
+             Senão:
+               System.out.println("Error | ... You have exceeded your trigger daily executions limits")
+               (trigger NÃO executa, NÃO há log gerado, NÃO há exceção propagada)
+       [3.3] Se qualquer Exception subir do runner:
+               e.printStackTrace() — engole o erro, continua para próximo trigger
+[4]  Retorna (int) ms gastos no laço inteiro
+```
+
+Observações críticas:
+
+- O parâmetro `id` é o "id do item que originou o evento" (ex: `action.getActionId()`) — **NÃO é o id da trigger**. Ele não é usado para filtrar quais triggers rodam; serve apenas como dado disponível ao script.
+- `findByEntityAndEvent` é uma query MongoDB direta — **não há cache de triggers ativos** (mas há cache de classes compiladas):
+  ```js
+  db.trigger.find({ entity: <entity>, event: <event> })
+  ```
+- Se ninguém criou um trigger para `(entity, event)`, o laço é um no-op (`O(1)` do MongoDB) e retorna em milissegundos.
+
+### 2.3 Diagrama — Pipeline de avaliação
+
+```mermaid
+flowchart LR
+    A[Caller<br/>ex: ActionManager.trackSynchonous] --> B[TriggerManager.execute<br/>id, o, entity, event, player, ctx]
+    B --> C[mongo.findByEntityAndEvent]
+    C --> D{Para cada<br/>trigger}
+    D --> E[StatisticManager<br/>newTriggerExecution]
+    E -->|limit OK| F[TriggerRunner.run]
+    E -->|excedido| X[System.out.println<br/>silencia]
+    F --> G[Cache de classe<br/>compiled trigger.id]
+    G -->|hit + dates &gt; updated| H[executor.submit<br/>Callable]
+    G -->|miss / stale| I[getScript<br/>compile<br/>cache]
+    I --> H
+    H --> J{future.get<br/>timeout}
+    J -->|OK| K[addLog trigger_log]
+    J -->|TimeoutException| L[exceptions.add<br/>future.cancel<br/>executor.shutdownNow]
+    L --> K
+    D -->|throw qualquer| Y[e.printStackTrace<br/>continua loop]
+```
+
+### 2.4 Sub-pipeline — `TriggerRunner.run(...)`
+
+```
+[1]  start = System.currentTimeMillis()
+[2]  exceptions = []; outputs = []
+[3]  Se trigger.updated == null:
+       manager.getTriggerManager().add(trigger)
+       (efeito colateral: persiste o trigger no mongo só para popular updated;
+        usado pelo modo cluster — qualquer nó que receber um trigger sem updated
+        força um save antes de seguir)
+[4]  lastCompilation = TriggerManager.dates.get(trigger.id)
+[5]  clazz           = TriggerManager.compiled.get(trigger.id)
+[6]  Se clazz != null && lastCompilation > trigger.updated:
+       (cache hit) executor(clazz, ...)
+     Senão:
+       script = getScript(trigger)     # monta imports + wrapper + getScript()
+       clazz  = compile(script)        # GroovyClassLoader com SecureASTCustomizer
+       compiled.put(trigger.id, clazz)
+       dates.put(trigger.id, now)
+       executor(clazz, ...)
+       (se compile falhar → CompilationFailedException é capturada,
+        exceptions.add(e.getMessage()), nenhuma classe é cacheada)
+[7]  ms = elapsed
+[8]  trigger_log.save( new TriggerLog(trigger.id, trigger.id, outputs, exceptions, ms) )
+[9]  Retorna Map { trigger, exceptions, outputs, millis }
+```
+
+### 2.5 Sub-pipeline — `executor(clazz, ...)`
+
+```
+[1] timeout = (trigger.timeout != null && > 0) ? trigger.timeout : 5
+    # default 5 segundos; valor literal no código, sem configuração externa
+[2] executor = Executors.newSingleThreadExecutor()
+[3] GroovyObject obj = clazz.newInstance()
+[4] future = executor.submit(callable):
+      obj.invokeMethod("setContext",   new Object[]{ context })
+      obj.invokeMethod("setManager",   new Object[]{ manager })
+      obj.invokeMethod("trigger",      new Object[]{
+          trigger.getEvent(), o, player, new GameDao(jongo, manager)
+      })
+      obj.invokeMethod("addAllOutput", new Object[]{ outputs })
+[5] future.get(timeout, TimeUnit.SECONDS)
+[6] Catches:
+      MultipleCompilationErrorsException → exceptions.add; future.cancel(true); executor.shutdownNow
+      SecurityException                  → exceptions.add; future.cancel(true); executor.shutdownNow
+      TimeoutException                   → exceptions.add("Timeout after Xs (timeout allowed Ys)");
+                                           exceptions.add(e.getMessage()); future.cancel(true); shutdownNow
+      InterruptedException               → exceptions.add(...)  (NÃO chama future.cancel — bug latente)
+      ExecutionException                 → exceptions.add; future.cancel(true); shutdownNow
+      Exception (catch-all)              → exceptions.add; future.cancel(true); shutdownNow
+```
+
+### 2.6 Sub-pipeline — `getScript(trigger)` — wrapper de imports
+
+`TriggerRunner.getScript` constrói um script que envelopa o `trigger.script` do usuário em uma classe `FunifierTrigger` Groovy com:
+
+1. ~40 imports automáticos (groovyx.net.http, Unirest, Apache HttpClient, Thumbnailator, javamail-simple, todos os domains do Funifier — `Action`, `ActionLog`, `Achievement`, `Lottery`, `Challenge`, `Player`, `Point`, `Team`, `Catalog`, `CatalogItem`, `Notification`, `FunifierMail`, `DateUtil`, `JsonUtil`, `ExcelUtil`, `HttpUtil`, `MustacheUtils`, `ManagerFactory`, `TriggerContext` etc.).
+2. `@TimedInterrupt(value = 200L, unit = TimeUnit.SECONDS)` na classe (limite por thread, distinto do timeout do `future.get`).
+3. Campos `TriggerContext context`, `ManagerFactory manager`, `List output`.
+4. Setters: `setContext(TriggerContext)`, `setManager(ManagerFactory)`.
+5. Override de `println(msg)` → `output.add(msg)` (todos os `println` viram `outputs` no `TriggerLog`).
+6. `addAllOutput(List out)` → `out.addAll(output)`.
+7. O script do usuário (`trigger.getScript()`) — espera uma assinatura `void trigger(event, entity, player, database) { ... }`.
+
+Cabeçalho final efetivo do script:
+
+```groovy
+@TimedInterrupt(value = 200L, unit = TimeUnit.SECONDS)
+class FunifierTrigger {
+    TriggerContext context = null
+    ManagerFactory manager = null
+    List output = new ArrayList()
+    void setContext(TriggerContext c) { context = c }
+    void setManager(ManagerFactory c) { manager = c }
+    void println(msg)               { output.add(msg) }
+    void addAllOutput(List out)     { out.addAll(output) }
+
+    // <<< trigger.script é concatenado aqui >>>
 }
 ```
 
-### Deletar Trigger
-**Método:** DELETE
-**Endpoint:** `/v3/trigger/:id`
+### 2.7 Diagrama — Interação cross-módulo (ActionManager.trackSynchonous)
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant Caller as Caller (REST)
+    participant AM as ActionManager
+    participant TM as TriggerManager
+    participant SM as StatisticManager
+    participant TR as TriggerRunner
+    participant Mongo as Mongo (trigger / trigger_log)
+
+    Caller->>AM: trackSynchonous(actionLog)
+    AM->>AM: ctx = new TriggerContext()<br/>ctx.extra["achievements"] = []
+    AM->>TM: execute(actionId, actionLog, "action", "before_win", userId, ctx)
+    TM->>Mongo: find({entity:"action", event:"before_win"})
+    loop cada trigger
+        TM->>SM: newTriggerExecution(trigger.id)
+        alt limite OK
+            TM->>TR: run(trigger, actionLog, userId, manager, ctx)
+            TR->>TR: compile (ou cache hit)
+            TR->>TR: invokeMethod("trigger", [event,o,player,gameDao])
+            TR->>Mongo: trigger_log.save(...)
+        else excedeu
+            TM->>TM: stdout error (silencia)
+        end
+    end
+    AM->>AM: actionManager.addLog(actionLog)
+    AM->>TM: execute(actionId, actionLog, "action", "after_win", userId, ctx)
+    AM->>AM: result = achievementManager.fireAction(actionLog)
+    AM->>Caller: List<Achievement>
+```
+
+### 2.8 Política de timeouts (dupla — relevante para debug)
+
+| Limite | Onde está | Valor | O que acontece |
+|---|---|---|---|
+| `trigger.timeout` (segundos) | `TriggerRunner.executor` linha 266–269 | default `5`, sobrescrito pelo campo se `> 0` | `future.get` lança `TimeoutException`, exception registrada no `trigger_log`, `executor.shutdownNow` mata a thread. |
+| `@TimedInterrupt(value = 200L, ...)` | `TriggerRunner.getScript` linha 164 | **200 segundos fixo** | Anotação Groovy que injeta checks em loops/métodos. Trava o script se `200s` excederem mesmo dentro de um único método. **Não respeita `trigger.timeout`** — é um limite teto independente. |
+
+Implicação operacional: definir `trigger.timeout = 600` **não vai funcionar**. O `future.get` chega aos `600s` no executor, mas o `@TimedInterrupt` da própria classe Groovy aborta em `200s`. Para todos os efeitos, o teto real é `min(trigger.timeout, 200)`.
+
+### 2.9 Cache de classes compiladas
+
+`TriggerManager` mantém **dois mapas em memória de processo** (não distribuídos):
+
+- `Map<String, Class> compiled` — chave = `trigger.id`, valor = classe Groovy compilada.
+- `Map<String, Date>  dates`    — chave = `trigger.id`, valor = data da última compilação.
+
+Invalidação:
+
+| Evento | Efeito |
+|---|---|
+| `add(trigger)` / `update(trigger)` | Faz `compiled.remove(id)` e `dates.remove(id)` após o save. |
+| `delete(id)` | Idem. |
+| `clear(trigger)` (via `PUT /v3/trigger/compile/{id}`) | Idem. |
+| `PUT /v3/trigger/compile/all` | Itera todos e chama `clear` em cada um. |
+| `TriggerRunner.run` (cache hit) | Reutiliza a classe **apenas se** `dates.get(id).getTime() > trigger.updated.getTime()`. Caso contrário, recompila. |
+
+**Cluster awareness:** o comentário `//cluster:...` no código indica que essa lógica foi feita para um ambiente multi-nó — cada nó tem seu próprio cache, e a comparação `dates > updated` recompila localmente quando um nó vizinho atualizou o trigger no Mongo.
+
+---
+
+## 3. Estrutura dos Objetos
+
+### 3.1 `Trigger` — documento raiz (`trigger`)
+
+| Campo | Tipo | Padrão | Obrigatório | Descrição |
+|---|---|---|---|---|
+| `_id` | String | `Guid.shortTimeMillis()` no `add` se ausente | — | Identificador único. |
+| `name` | String | — | recomendado | Rótulo legível. Usado nos filtros `findAll`. |
+| `description` | String | — | não | Texto livre. **Não é validado/indexado**. |
+| `entity` | String | — | **sim** | Nome da coleção/entidade alvo (ex: `action`, `point_category`, `challenge`, `level`, `lottery_ticket`, `swap`, `mystery_box`, ou qualquer string usada por chamadores customizados como `"deal"`, `"folder_progress"`). |
+| `event` | String | — | **sim** | Tipo de evento (ver enums abaixo + tabela 3.4). |
+| `script` | String | — | **sim** | Código Groovy do corpo. Espera definir `void trigger(event, entity, player, database) { ... }`. |
+| `creation` | Date | `new Date()` no `add` se ausente | — | Timestamp de criação. |
+| `updated` | Date | `new Date()` em todo `add`/`update` | — | Usado para invalidar cache em cluster. Sobrescreve `creation`-like updates. |
+| `timeout` | Long | `null` → cai para `5` segundos no executor | não | Timeout de execução em **segundos**. Teto real efetivo `min(timeout, 200)` por causa do `@TimedInterrupt`. |
+| `techniques` | `List<String>` | `null` | não | Lista de códigos de técnica de jogo (GT...) para metadata no Studio. **Apenas persiste — não é lida pelo runtime.** |
+| `style` | `ObjectStyle` | `null` | não | Atributos visuais (`background`, `visible`). Usado apenas pelo Studio. |
+| `references` | `List<Reference>` | `null` | não | Vínculo visual com outros itens da estratégia (consumido por relatórios do Studio). |
+| `errors` | `String[]` | `null` | — | **Campo legado** — escrito apenas pelo método comentado `SaveTrigger(...)` que não é mais chamado. Permanece no schema (com getter/setter) mas nunca é populado no fluxo atual. |
+| `logs` | `String[]` | `null` | — | **Campo legado** — mesma situação de `errors`. O log moderno vai para a coleção `trigger_log`. |
+
+Configuração de serialização:
+
+- `@JsonIgnoreProperties(ignoreUnknown=true)` — qualquer campo extra enviado no JSON é **silenciosamente descartado**.
+- `@JsonProperty("_id")` no `id` — o JSON da API expõe `_id`.
+- `JsonUtil.toJsonRemoveNullFields` nos endpoints — campos `null` (`description`, `creation`, `errors`, `logs`, `style`, `references`, `techniques`, `timeout`, `updated`) **não aparecem no JSON de resposta**, mesmo que estejam no documento Mongo.
+
+#### Campos legados (aceitos mas sem efeito runtime)
+
+- `Trigger.errors`, `Trigger.logs` — getters/setters existem; apenas o método privado `SaveTrigger(...)` (comentado entre linhas 540–551 de `TriggerRunner.java`) os populava. Hoje, todo log de execução vai para `trigger_log`.
+
+#### Constantes de Entity (em `Trigger.java`)
+
+```java
+ENTITY_ACTION                 = "action"
+ENTITY_PLAYER                 = "player"
+ENTITY_WIN_STATE              = "challenge"
+ENTITY_POINT                  = "point_category"
+ENTITY_LEVEL                  = "level"
+ENTITY_CROWN                  = "crown"
+ENTITY_CATALOG_ITEM           = "catalog_item"
+ENTITY_LOTTERY                = "lottery"
+ENTITY_CHARACTER_STAR_STATS   = "character_star_stats_level"
+ENTITY_UPLOAD                 = "upload"
+ENTITY_MYSTERY_BOX            = "mystery_box"
+
+// Comentadas/removidas (não aceitar como valor canônico):
+// ENTITY_ACTIONLOG   = "action_log"
+// ENTITY_ACHIEVEMENT = "achievement"
+// ENTITY_COMPETITION = "competition"
+```
+
+Importante: o campo `entity` aceita **qualquer string** — não há validação. Strings observadas no código fora dessas constantes:
+
+- `"swap"`, `"swap_counter_offer"` — disparado por `SwapManager`.
+- `"folder_log"`, `"folder_progress"` — `FolderManager` / `FolderRest`.
+- `"quiz"`, `"quiz_log"`, `"question"`, `"question_log"` — `QuizManager`, `QuestionManager`.
+- `"deal"` — `CrmManager` (módulo CRM B2B).
+- `"compact_log"`, `"backup_log"` — `CompactManager`, `BackupManager`.
+- `"password_change"` — `PlayerRest.changePassword`.
+- Qualquer string de coleção passada por `DatabaseRest`/`DatabaseManager` (no `before_create`/`after_create`/`before_update`/`after_update`/`before_delete`/`after_delete`/`before_bulk`/`after_bulk`).
+
+#### Constantes de Event (em `Trigger.java`)
+
+```java
+EVENT_BEFORE_WIN     = "before_win"
+EVENT_AFTER_WIN      = "after_win"
+EVENT_BEFORE_LOSE    = "before_lose"
+EVENT_AFTER_LOSE     = "after_lose"
+EVENT_BEFORE_CREATE  = "before_create"
+EVENT_AFTER_CREATE   = "after_create"
+EVENT_BEFORE_UPDATE  = "before_update"
+EVENT_AFTER_UPDATE   = "after_update"
+EVENT_BEFORE_DELETE  = "before_delete"
+EVENT_AFTER_DELETE   = "after_delete"
+```
+
+Eventos extras NÃO declarados como constante mas usados ad-hoc:
+
+- `"before_bulk"`, `"after_bulk"` — `DatabaseManager.bulkInsert`.
+- `"before_purchase_validation"` — `CatalogManager.purchase`.
+- `"before_acquire_validation"` — `SwapManager.buyerAcquire`.
+- `"before_win_reward"` — `MysteryBoxManager.execute` (dispara antes de cada reward individual de uma caixa).
+- `"after_finish"` — `CompactManager.asyncExecute`.
 
-## Script Runtime Environment (Wrapper Class)
+### 3.2 `Reference` — subdocumento (`references[]`)
 
-O script da trigger **não é standalone** — ele é inserido dentro de uma classe Java wrapper gerada pelo Funifier, idêntica à do Public Endpoint (ver `public.md` para a lista completa de imports).
+| Campo | Tipo | Padrão | Obrigatório | Descrição |
+|---|---|---|---|---|
+| `_id` | String | — | sim | Id do item referenciado. |
+| `type` | String | — | sim | Tipo/coleção (ex: `Entity.POINT.collection`). |
+| `title` | String | — | sim | Texto exibido no card visual do Studio. |
+| `way` | String | — | sim | `"from"` ou `"to"` (`Reference.WAY_FROM` / `WAY_TO`). |
+| `linkLabel` | String | `""` (via `getLinkLabel()`) | não | Rótulo sobre a seta no diagrama de estratégia do Studio. |
 
-### Regras
+Apenas metadata para o Studio — **não é lida pelo runtime do trigger**.
 
-1. **NÃO use `import`** — todos os imports já estão no wrapper (Unirest, Groovy JSON, Funifier entities/utils, Apache HTTP, Simple Java Mail, etc.)
-2. Se precisar de uma classe não importada, use o nome completo: `com.example.MinhaClasse`
-3. **`manager`** (ManagerFactory) está disponível como campo da classe
-4. **Timeout padrão de 10 segundos** — pode ser customizado via campo `timeout` (em **segundos**) na API: `POST /v3/trigger` com `{"_id": "trigger_id", "timeout": 30}`. Este campo não aparece no Studio.
-5. Scripts rodam em **Groovy** — cuidado com `$` em GStrings (usar `String.valueOf((char)0x24)` para operadores MongoDB)
-6. Use apenas **ASCII em comentários** — UTF-8 especial pode causar parse errors
+### 3.3 `ObjectStyle` — subdocumento (`style`)
 
-> 📖 Ver `public.md` → **Script Runtime Environment** para a lista completa de imports e bibliotecas disponíveis.
+| Campo | Tipo | Padrão | Obrigatório | Descrição |
+|---|---|---|---|---|
+| `background` | String | — | não | Cor de fundo no Studio. |
+| `visible` | Boolean | `null` | não | Se `false`, o item é ocultado nas visualizações do Studio. |
 
-## Parâmetros do Script
+### 3.4 `TriggerLog` — documento de log (`trigger_log`)
 
-- `event` (String): evento acionado
-- `entity` (Object): objeto sendo manipulado (Player, ActionLog, Achievement, etc.)
-- `player` (String): ID do jogador
-- `database` (Object): utilitário para acessar o banco de dados
+Gerado em **toda** execução pelo `TriggerRunner.run`, inclusive em caso de falha de compilação ou timeout (carrega o erro em `err`).
 
-### ⚠️ CRITICAL: `entity` Type Depends on the Trigger Entity
+| Campo | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `_id` | String | `Guid.newShortGuid()` no `addLog` se ausente | Id do log. |
+| `item` | String | — | **No fluxo atual = `trigger.id`** (o `TriggerLog` é construído como `new TriggerLog(trigger.id, trigger.id, ...)`). O nome do campo sugere "id do item disparado" mas hoje duplica o `trigger.id`. |
+| `time` | Date | `new Date()` no construtor + `new Date()` no `addLog` se null | Quando o log foi registrado. |
+| `out` | `List<String>` | `null` se vazio | Captura de todos os `println` do script. **Se a lista chegar vazia (`size == 0`), é gravada como `null`** (linha 37 de `TriggerLog.java`). |
+| `err` | `List<String>` | `null` se vazio | Stack messages das exceções (compilação, timeout, security, etc.). Mesma regra de `out`: vazio → `null`. |
+| `ms` | long | — | Tempo total de execução em milissegundos (medido do início do `run` até depois do `addLog`). |
 
-O tipo do parâmetro `entity` varia conforme a entidade da trigger:
+### 3.5 Subentidade — `TriggerContext` (runtime, não persistido)
 
-| Trigger Entity | Tipo de `entity` | Como acessar campos |
+Não é persistido no Mongo. É construído ad-hoc pelo manager chamador e injetado no script via `setContext`.
+
+| Campo | Tipo | Uso |
+|---|---|---|
+| `manager` | `ManagerFactory` | Acesso a todos os managers da plataforma para o tenant. |
+| `origin` | Object | Convenção: a entidade que originou a cadeia de eventos (ex: o `ActionLog` original quando o evento atual é um `point_category.after_win` derivado). |
+| `extra` | `Map<String, Object>` | Bag de dados arbitrários. Chaves observadas no código: `"achievements"` (lista mutável em que o script pode adicionar Achievements), `"parentActionLog"`, `"deal"`, `"level"`. |
+
+### 3.6 `TriggerStatistics` / `TriggerDetailStatistics` (estatísticas in-memory)
+
+Não são persistidos por trigger. Vivem dentro do `StatisticManager` por `apiKey` e são serializados periodicamente como `Entity.STATISTIC_LOG`.
+
+| Campo | Tipo | Descrição |
 |---|---|---|
-| `player` | `com.funifier.engine.player.Player` (objeto Java) | `entity.id`, `entity.name`, `entity.email`, `entity.extra` |
-| `<custom>__c` | `java.util.Map` (documento MongoDB) | `entity.get("campo")`, `entity.put("campo", valor)` |
-| `action` | `com.funifier.engine.action.ActionLog` | `entity.userId`, `entity.actionId`, `entity.attributes` |
-| `achievement` | `com.funifier.engine.achievement.Achievement` | `entity.achievementId`, `entity.userId` |
+| `lastTriggerExecution` | Date | Última execução de qualquer trigger. |
+| `hourlyTriggerExecutions` | long | Contador da hora atual (reset ao trocar de hora). |
+| `dailyTriggerExecutions` | long | Contador do dia atual (reset ao trocar de dia do ano). |
+| `monthlyTriggerExecutions` | long | Contador do mês atual (reset ao trocar de mês). |
+| `dailyTriggerExecutionsLimit` | long | Limite diário (`@JsonIgnore` — não vaza pelo JSON). Carregado de `GamificationLimits.dailyTriggerExecutions`. |
+| `triggers` | `Map<String, TriggerDetailStatistics>` | Detalhe por `trigger.id`. |
+
+Lógica de reset (linha 57–78 de `TriggerStatistics.java`): compara hora/dia/mês atuais com os armazenados — quando muda, o contador é **resetado para 1** (não 0). Logo, no primeiro tick de cada dia o contador começa em 1.
 
-**Erros comuns:**
-- ❌ `entity.get("_id")` em trigger de `player` → `MissingMethodException: No signature of method: Player.get()`
-- ✅ `entity.id` em trigger de `player`
-- ❌ `entity.id` em trigger de `signup__c` → campo não existe no Map
-- ✅ `entity.get("_id")` em trigger de `signup__c`
+Decisão de bloqueio (linha 92–98):
 
-**Player fields (via `PlayerManager.java`):**
+```java
+if (dailyTriggerExecutions <= dailyTriggerExecutionsLimit) return true;
+else return false;
 ```
-entity.id        → String (_id do player)
-entity.name      → String
-entity.email     → String
-entity.password  → String (hash BCrypt)
-entity.extra     → Map<String, Object> (campos customizados)
-entity.image     → Image object
-entity.business  → boolean
-entity.developer → boolean
+
+Observação: o teste é `<=`, então o limite é **inclusivo** — quando `daily == limit`, ainda passa; bloqueia a partir de `daily > limit`.
+
+### 3.7 `TriggerHtml` — **NÃO faz parte do runtime de Trigger**
+
+Apesar do nome, `TriggerHtml` (coleção `trigger_html`) é um modelo client-side de eventos DOM do SDK web. Está em `engine/integration/html/TriggerHtml.java` e é gerenciado pelo `ActionDaoMongo` (não pelo `TriggerManager`). Existe documentação separada — não confundir.
+
+### 3.8 Técnicas de jogo (`techniques`)
+
+Apenas armazenamento — o array de códigos GT (ex: `["GT001", "GT042"]`) é persistido e devolvido pela API mas **não influencia o runtime**. Usado pelo Studio para taggear visualmente os triggers em relatórios de cobertura de técnicas.
+
+### 3.9 Ciclo de vida do `Trigger` no cache
+
+```mermaid
+stateDiagram-v2
+    [*] --> Persistido: add(trigger)<br/>updated = now
+    Persistido --> Compilado: TriggerRunner.run<br/>compile + cache
+    Compilado --> Compilado: run reutiliza cache<br/>dates &gt; updated
+    Compilado --> Persistido: trigger.updated alterado<br/>(outro nó editou)
+    Compilado --> Invalidado: update(trigger)<br/>delete(trigger)<br/>clear(trigger)
+    Invalidado --> Compilado: próxima run recompila
+    Persistido --> [*]: delete(id)
 ```
 
-**Fonte:** `PlayerManager.delete()` chama `TriggerRunner.run()` com `new Object[] { event, playerObject, playerId, gameDao }` — logo `entity` é o objeto `Player` completo, não um Map.
+---
 
-## Verificando Logs de Trigger (Studio)
+## 4. Endpoints
 
-Para ver se uma trigger executou com sucesso ou com erro:
+### 4.1 `GET /v3/trigger` — listar com filtros
 
-1. Acessar **Studio** → menu lateral → **Triggers**
-2. Na lista de triggers, cada uma tem um botão **🔥 Logs** na coluna OPERAÇÕES
-3. Clicar em **Logs** abre um modal com:
-   - **Log Id**: identificador da trigger
-   - **Executou em**: data/hora da última execução
-   - **Tempo de resposta**: tempo de execução em ms
-   - **Erros**: se houve erro, mostra a exception completa em vermelho
-4. Se não houver seção "Erros", a trigger executou com sucesso
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Listar/filtrar triggers via aggregation. |
+| Autenticação | Bearer token. |
+| Tipo | Read. |
 
-**Dica:** Após alterar uma trigger via API (`POST /v3/trigger`), teste-a e verifique o log no Studio para confirmar que não há erros de compilação ou runtime.
+**Query params:**
 
-## Utilitários Disponíveis no Contexto
+| Param | Tipo | Descrição |
+|---|---|---|
+| `id` | String | Filtro exato por `_id`. |
+| `name` | String | Filtro `$regex` case-insensitive (`{$regex: <name>, $options: 'i'}`). |
+| `entity` | String | Filtro exato. |
+| `event` | String | Filtro exato. |
+| `script` | String | Filtro `$regex` case-insensitive no corpo do script. |
+| `q` | String | **Fragmento bruto** de query Mongo, concatenado no `$match` (ex: `q=tags:{$all:["x"]}`). Sem sanitização — ver seção 8. |
+| `fields` | String CSV | Projeção (`{$project:{a:1,b:1}}`). |
+| `orderby` | String | Campo de ordenação. |
+| `reverse` | boolean (string) | `true` → `-1`, qualquer outro valor → `1`. |
+| `max_results` | int (string) | Limite. Se `<= 0` → default **`100`**. |
+
+**Comportamento real:**
+
+- `max_results` é sempre clamped para `100` quando `<= 0` (linha 149 do `TriggerManager.findAllTriggers`).
+- Argumentos vazios/`null` são ignorados sem warning.
+- `name` e `script` aceitam **regex livre** (não há escape de metacaracteres).
+- `q` é literalmente concatenado dentro de `{ $match: { ..., <q> } }` — **injeção de query Mongo é possível**.
+
+**Exemplo:**
+
+```http
+GET /v3/trigger?entity=action&event=after_win&max_results=50
+Authorization: Bearer eyJ...
+```
 
-| Classe/Método | Descrição |
+```json
+[
+  {
+    "_id": "5f3a1b...",
+    "name": "Notificar Slack após sell",
+    "entity": "action",
+    "event": "after_win",
+    "script": "void trigger(event, entity, player, database){ ... }",
+    "creation": "2024-08-01T13:21:09Z",
+    "updated":  "2024-08-12T17:02:55Z",
+    "timeout":  10
+  }
+]
+```
+
+### 4.2 `GET /v3/trigger/{id}` — buscar por id
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Retorna um único trigger por `_id`. |
+| Autenticação | Bearer token. |
+| Comportamento se não encontrado | `findById` retorna `null`; resposta é `"null"` literal (após `toJsonRemoveNullFields`). **Não retorna 404.** |
+
+### 4.3 `POST /v3/trigger/execute/{id}?player=<player>` — debug execution
+
+| Aspecto | Detalhe |
 |---|---|
-| `Guid.newShortGuid()` | Gera um ID curto único (7 chars, ex: `FnwjKEY`) |
-| `Guid.newGuid()` | Gera um GUID completo |
-| `newShortGuid()` | ❌ **NÃO FUNCIONA** — precisa do prefixo `Guid.` |
-| `com.funifier.engine.util.BCrypt.hashpw(pwd, BCrypt.gensalt())` | Hash de senha BCrypt |
-| `new Date().getTime()` | Timestamp atual em milissegundos |
-| `manager` | ManagerFactory — acesso a todos os managers |
+| Finalidade | Executar um trigger isolado para debug. |
+| Autenticação | Bearer token. |
+| Body | JSON livre (`Map<String, Object>`) — passado como `o` ao script. |
+| Tipo | Execução side-effectful. |
 
-> ⚠️ `System.currentTimeMillis()` é BLOQUEADO pelo SecureASTCustomizer. Usar `new Date().getTime()`.
+**Comportamento real:**
 
-## Managers Disponíveis
+- **Não chama `TriggerManager.execute`** — instancia um `new TriggerRunner()` e chama `run(trigger, o, player, manager, null)` diretamente.
+- **NÃO valida `dailyTriggerExecutionsLimit`** (pula `StatisticManager.newTriggerExecution`).
+- `context` é `null` — qualquer script que faça `context.extra.put(...)` lança NPE.
+- Body é passado ao script como o objeto `o` da assinatura `trigger(event, entity, player, database)`.
 
-- `manager.getPlayerManager()` - findById, insert, delete
-- `manager.getActionManager()` - findActionById, track, trackSynchonous
-- `manager.getCatalogManager()` - findItemById, purchase, undoPurchase
-- `manager.getLotteryManager()` - find, insertTicket, execute
-- `manager.getAchievementManager()` - addAchievement
-- `manager.getJongoConnection()` - acesso direto ao MongoDB
+**Resposta:**
 
-## Envio de Email
+```json
+{
+  "trigger": { ... documento completo ... },
+  "exceptions": [],
+  "outputs": ["valor que veio do println do script"],
+  "millis": 47
+}
+```
 
-As triggers podem enviar emails usando o servidor SMTP configurado na gamificação. As classes do Simple Java Mail e utilitários Funifier já estão disponíveis no contexto (não precisa importar).
+Se a trigger não existir, o endpoint passa `null` para `TriggerRunner.run` que faz NPE em `trigger.updated` — retorna 500.
 
-### Classes disponíveis
-- `EmailBuilder` / `MailerBuilder` — Simple Java Mail (construir e enviar)
-- `com.funifier.engine.mail.MailContext` — config SMTP da gamificação
-- `com.funifier.controller.Configuration` — acesso à configuração atual
-- `com.funifier.engine.util.MustacheUtils` — parse de templates com variáveis `{{campo}}`
+### 4.4 `POST /v3/trigger` — criar/atualizar
 
-### Exemplo básico
-```java
-Email email = EmailBuilder.startingBlank()
-    .from("App", "noreply@funifier.com")
-    .to(nome, emailDestinatario)
-    .withSubject("Assunto")
-    .withHTMLText("<h1>Olá</h1>")
-    .buildEmail();
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Criar/sobrescrever trigger. |
+| Autenticação | Bearer token. |
+| Full replace ou patch | **Full replace.** O `_id`, se informado, sobrescreve o documento existente (Jongo `save`). Não é patch. |
+
+**Comportamento real (`TriggerRest.insert`):**
+
+1. Se o body for `null`, devolve `201 Created` com `{}` — não erro.
+2. Chama `TriggerManager.compile(trigger)` — só valida sintaxe + AST (não roda).
+3. Se `CompilationFailedException` / `InstantiationException` / `IllegalAccessException`:
+   ```json
+   { "trigger": { ... }, "status": "ERROR", "message": "<msg>" }
+   ```
+   **HTTP status continua 201 Created** mesmo com erro de compilação.
+4. Se OK, chama `TriggerManager.add(trigger)`:
+   - Preenche `_id` se vazio (`Guid.shortTimeMillis()`).
+   - Preenche `creation` se null.
+   - **Sempre sobrescreve `updated = new Date()`**.
+   - `c.save(trigger)` — UPSERT por `_id`.
+   - Invalida cache local: `compiled.remove(id)` + `dates.remove(id)`.
+5. Retorna `{ "trigger": <persisted>, "status": "OK" }` com HTTP 201.
+
+**Exemplo:**
 
-com.funifier.engine.mail.MailContext ctx = com.funifier.controller.Configuration.getCurrentConfiguration().getMailContext();
-MailerBuilder.withSMTPServer(ctx.hostName, ctx.smtpPort, ctx.authUser, ctx.authPassword)
-    .buildMailer()
-    .sendMail(email);
+```json
+POST /v3/trigger
+Authorization: Bearer eyJ...
+Content-Type: application/json
+
+{
+  "name": "After Register Action Log",
+  "entity": "action",
+  "event": "after_win",
+  "timeout": 10,
+  "script": "void trigger(event, entity, player, database) {\n  println 'event:' + event + ', player:' + player\n}"
+}
 ```
 
-> 📖 Para o pattern completo com templates editáveis e Mustache, ver `patterns.md` → **Email Template Pattern**
+### 4.5 `DELETE /v3/trigger/{id}`
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Remover trigger + invalidar cache. |
+| Autenticação | Bearer token. |
+| Resposta | `204 No Content`. |
+
+**Comportamento real:** `mongo.remove({_id:#})` + `compiled.remove(id)` + `dates.remove(id)`. Se o id não existir, é no-op silencioso (Mongo não retorna erro).
+
+### 4.6 `PUT /v3/trigger/compile/{id}` — invalidar cache
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Forçar recompilação **na próxima execução**. |
+| Autenticação | Bearer token. |
+| Valor especial `id` | `"all"` itera todos os triggers e chama `clear` em cada um. |
+
+**Comportamento real:** apesar do nome, **não compila nada agora** — apenas remove o `id` dos mapas `compiled` e `dates`. A próxima execução real é que vai recompilar.
 
-## Validações e Testes
+**Resposta:**
+
+```json
+{ "_id": "all" }
+```
+
+ou
+
+```json
+{ "_id": "5f3a1b..." }
+```
+
+Se o id passado não existir, `findById` retorna `null`, o trecho `if(trigger != null)` é falso e o endpoint ainda devolve `200 OK` com `_id` ecoado. **Não retorna 404.**
+
+### 4.7 Endpoints inexistentes (esperados em REST convencional, ausentes aqui)
+
+- Não há `PUT /v3/trigger/{id}` para update — usar `POST` com `_id` no body.
+- Não há `GET /v3/trigger/{id}/logs` — para ver logs, consultar a coleção `trigger_log` via `/v3/database/trigger_log`.
+- Não há paginação cursor-based — apenas `max_results` clamped a 100 por default.
+
+---
+
+## 5. Regras de Negócio
+
+- **`(entity, event)` é a chave de roteamento.** Não há regra adicional de tenant filter — todos os triggers daquela combinação rodam.
+- **Ordem de execução não é determinística.** `findByEntityAndEvent` itera o cursor Mongo na ordem natural (geralmente ordem de inserção em RocksDB/WiredTiger, mas não garantida).
+- **Isolamento por tenant é via `apiKey`.** Cada `ManagerFactory` tem sua própria conexão Mongo (banco do tenant) → `findByEntityAndEvent` só vê triggers daquele tenant.
+- **Limite diário (`dailyTriggerExecutionsLimit`)**:
+  - Vem de `GamificationLimits.dailyTriggerExecutions` (coleção `game_limits`).
+  - Se `0`, **bloqueia tudo** (porque `1 <= 0` é falso).
+  - Quando excedido, a execução é **silenciosamente pulada** — `System.out.println` de erro no stdout do servidor; nenhum `trigger_log` é gravado.
+  - Contagem é **in-memory**: se o serviço reinicia, o contador zera.
+- **`before_*` e `after_*` rodam em volta da mutação principal**, **na mesma thread chamadora**. Logo, um `before_create` lento atrasa o `insert` HTTP. Um `before_create` que joga exception é **engolido** (`e.printStackTrace`) e a operação continua — não é uma forma de cancelar a operação.
+- **Não há rollback transacional** entre o script e o save do entity. Se o `after_create` falha, o documento já está persistido.
+- **`script` recebido na API é compilado mas não é checado para a assinatura `trigger(event, entity, player, database)`.** Se faltar essa função, o `invokeMethod("trigger", ...)` lança `MissingMethodException` apenas em runtime, registrada em `trigger_log.err`.
+- **Triggers customizadas podem disparar outros eventos**: se um script chama `manager.getActionManager().trackSynchonous(...)`, isso dispara novas triggers — **risco de loop infinito**, limitado apenas pelos timeouts e pelo `dailyTriggerExecutionsLimit`.
+- **`techniques`, `style`, `references` são apenas metadados de Studio** — runtime ignora.
+
+---
+
+## 6. Comportamentos Automáticos
+
+| Comportamento | Trigger (gatilho) | Impacto | Persistência |
+|---|---|---|---|
+| Atribuição de `_id` | `add(trigger)` sem `_id` | Gera `Guid.shortTimeMillis()`. | Sim — gravado. |
+| Atribuição de `creation` | `add(trigger)` sem `creation` | `new Date()`. | Sim. |
+| Atualização de `updated` | Todo `add`/`update` | Sobrescreve com `new Date()`. | Sim. Não respeita valor enviado pelo cliente. |
+| Auto-save no primeiro run | `TriggerRunner.run` quando `trigger.updated == null` | Persiste o trigger no Mongo. | Sim — efeito colateral. |
+| Invalidação de cache | `add` / `update` / `delete` / `clear` | `compiled.remove(id)` + `dates.remove(id)` apenas no processo local. | Não — só memória. |
+| Recompilação por staleness | `run` detecta `trigger.updated > dates.get(id)` | Recompila e re-cacheia. | Não. |
+| Log de execução | Toda chamada de `TriggerRunner.run` (independente de sucesso) | Insert em `trigger_log` com `out`, `err`, `ms`. | Sim, sempre. |
+| Estatística | Toda chamada de `TriggerManager.execute` antes do run | Incremento de contadores em memória + decisão de limite. | Não direto — `StatisticManager` flushea em ciclos próprios. |
+| Println capturado | Toda chamada de `println` no script | Adiciona a `output` (lista interna). | Sim, vai para `trigger_log.out`. |
+| Wrapping de classes | Toda execução, antes da compilação | Adiciona ~40 imports + classe `FunifierTrigger` + setters. | Não — só em memória. |
+| Reset diário/horário/mensal | `newTriggerExecution` em qualquer execução | Quando o `Calendar.HOUR_OF_DAY` / `DAY_OF_YEAR` / `MONTH` muda, o contador correspondente vira `1`. | Não diretamente. |
+
+### 6.1 Diagrama — Behaviors encadeados em `POST /v3/trigger`
+
+```mermaid
+flowchart LR
+    A[POST /v3/trigger] --> B[TriggerRest.insert]
+    B --> C[manager.compile<br/>valida AST]
+    C -->|fail| F[status=ERROR<br/>HTTP 201 retorna]
+    C -->|OK| D[manager.add]
+    D --> E1[_id := Guid.shortTimeMillis<br/>se vazio]
+    D --> E2[creation := now<br/>se null]
+    D --> E3[updated := now<br/>sempre]
+    D --> E4[c.save trigger<br/>UPSERT por _id]
+    D --> E5[compiled.remove id<br/>dates.remove id]
+    E5 --> G[HTTP 201 + status=OK]
+```
+
+---
+
+## 7. Suportado vs NÃO Suportado
+
+### ✅ Suportado
+
+- CRUD básico via `/v3/trigger` (criar, listar, buscar, deletar).
+- Listagem com `$regex` em `name`/`script` e `$match` livre via `q`.
+- Compilação `SecureASTCustomizer` com whitelist de tokens (operadores aritméticos, comparações, lógicos, `[`/`]`).
+- Bloqueio de classes perigosas (`System`, `ProcessBuilder`, `File`, `GroovyShell`, `GroovyObject`) e expressões (`.execute`, `.getDB`, `.getMongo`, `.dropDatabase`) via `TriggerExpressionChecker`.
+- Cache local de classes Groovy compiladas (per processo, invalidado por update/delete).
+- Timeout configurável por trigger (efetivo até 200s).
+- Endpoint de execução para debug (`POST /v3/trigger/execute/{id}`).
+- Endpoint para forçar invalidação de cache (`PUT /v3/trigger/compile/{id}`, `compile/all`).
+- Captura de `println` em `trigger_log.out`.
+- Captura de exceções em `trigger_log.err`.
+- Disparo via 29 managers/REST distintos, em todos os eventos `before_*` / `after_*` documentados em 3.1.
+- `TriggerContext.extra["achievements"]` como canal de "saída" do script para o manager chamador (especialmente `AchievementManager`).
+- Estatísticas in-memory de execução por hora/dia/mês (`TriggerStatistics`).
+- Limite diário aplicado por tenant (`GamificationLimits.dailyTriggerExecutions`).
+
+### ❌ NÃO Suportado / Comportamento limitado
+
+- **Sem `PUT /v3/trigger/{id}`** — atualização é feita via `POST` com `_id` no body (mesmo endpoint do create). O endpoint `PUT /v3/trigger/compile/{id}` não é um PUT de update, é apenas invalidação de cache.
+- **404 não é retornado** para id inexistente em `GET /v3/trigger/{id}` nem `PUT /v3/trigger/compile/{id}`.
+- **HTTP status não reflete erro de compilação** — `POST /v3/trigger` devolve `201 Created` mesmo quando `compile` falha (o erro vem no body `status: "ERROR"`).
+- **Sem rollback transacional** — se um `after_create` falha, a entidade já foi criada.
+- **`techniques`, `style`, `references` não influenciam runtime** — são apenas metadata de Studio. Aceitos no schema, ignorados pelo `TriggerRunner`.
+- **`errors` e `logs` em `Trigger` são campos legados** — o método `SaveTrigger` que os populava está comentado. Nunca são preenchidos no fluxo atual.
+- **Sem cancelamento via exceção** — `throw` dentro de um `before_create` script é capturado pelo `executor` (`exceptions.add`), logado, e a operação principal **continua mesmo assim**.
+- **Sem broadcast de invalidação de cache em cluster** — cada nó decide por si baseado em `trigger.updated` vs. `dates`. Há janela de inconsistência: enquanto o nó B não recebe nenhum evento que dispare o trigger, ele continua com a classe antiga.
+- **`@TimedInterrupt(value = 200L, ...)` é fixo no código** (linha 164 de `TriggerRunner.getScript`). Não há como configurar via `trigger.timeout` para passar de 200s.
+- **`InterruptedException` no executor não chama `future.cancel(true)`** (linhas 308–314 de `TriggerRunner`) — possível leak de thread.
+- **`TriggerManager.execute` engole TODA exception** — `catch(Exception)` com `e.printStackTrace()`, sem propagar nem registrar em log persistente. Bugs em managers chamadores são invisíveis.
+- **Limite diário usa contador in-memory** — restart do serviço zera. Não há quota persistida.
+- **Limite é shared entre todos os triggers do tenant** — não há quota por `trigger.id`. Quando o teto é atingido, **nenhum** trigger executa até o próximo reset de dia.
+- **Sem audit log nativo** — operações em `/v3/trigger` não passam pelo `AuditManager` (diferente de `/v3/database`).
+- **Sem filtro de tenant nas estatísticas detalhadas** quando comparado via `triggers` map — funciona porque `StatisticManager` é por `apiKey`, mas o `triggers` map cresce sem bound (todo `trigger.id` que executou pelo menos uma vez nunca é removido em memória).
+- **`Trigger.entity` e `Trigger.event` aceitam qualquer string** — não há enum-enforcement. Triggers escritos para `event="after_win"` errado (ex: `"afterwin"`) **nunca disparam** e não há aviso.
+- **`POST /v3/trigger/execute/{id}` ignora limite diário** — útil para debug, perigoso em prod.
+- **Limit `dailyTriggerExecutionsLimit` é inclusivo** (`<=`) — quando o uso bate exatamente no limite ainda executa; bloqueia só do próximo em diante.
+
+---
+
+## 8. Segurança e Permissões
+
+### 8.1 Autenticação
+
+- Todos os endpoints exigem Bearer token (`@BeanParam AuthBean authBean` → `FrontController.getInstance(authBean.getApiKey())`).
+- **Não há filtro de role/permission no `TriggerRest`** — qualquer principal autenticado com `apiKey` válido cria/lê/deleta/executa triggers daquele tenant.
+- Isolamento multi-tenant é via `apiKey` → `ManagerFactory` próprio → `Jongo` próprio → coleção `trigger` do banco daquele tenant.
+
+### 8.2 Sandbox de scripts
+
+- `SecureASTCustomizer` com `TriggerExpressionChecker.isAuthorized(...)`:
+  - Bloqueia tipos: `System`, `ProcessBuilder`, `File`, `GroovyShell`, `GroovyObject` (lista hard-coded em `TriggerExpressionChecker`).
+  - Bloqueia substrings em `.getText()`: `.execute`, `.getDB`, `.getMongo`, `.dropDatabase`.
+  - Whitelist de tokens (linhas 222–247 de `TriggerRunner.compile`): `=, +, -, *, /, %, **, ++, +=, --, ==, !=, <, <=, >, >=, ||, ||=, &&, &&=, [, ]`. **Note que `==` aparece duplicado** (linhas 234 e 238).
+
+### 8.3 Brechas conhecidas no sandbox
+
+- **`.execute` é bloqueado por busca de substring**, não por análise semântica. Strings em métodos como `executeAggregate`, `executeQuery` (ex: chamadas do `Jongo`) também são bloqueadas — falso positivo.
+- O `getText()` do AST verifica a **representação textual da expressão**, não o tipo resolvido. Variáveis dinâmicas (`def x = "exec" + "ute"; obj[x]()`) podem contornar.
+- O bloqueio é **AST-time** — só pega o que aparece no código fonte. Reflection via classes permitidas (ex: `ManagerFactory.class.getDeclaredMethods()`) é livre.
+- Outras configurações de hardening do `SecureASTCustomizer` (`receiversBlackList`, `importsBlacklist`, `methodDefinitionAllowed`, `closuresAllowed`) **não estão configuradas**, então closures, definições de método e imports adicionais são permitidos.
+- Já há imports automáticos a `ManagerFactory` e a todas as classes de domínio — scripts têm **acesso completo ao runtime do tenant**, incluindo Players, Achievements, Catalog, etc.
+
+### 8.4 Injeção em queries
+
+- `GET /v3/trigger?q=<raw>` injeta `<raw>` literalmente no `$match` do aggregate. O aggregate é fixado em `db.trigger.aggregate([...])` da coleção `trigger`, mas pode ser usado para **enumeração de scripts** (ex: regex em `script` para procurar credenciais hardcoded).
+- `name` e `script` são `$regex` sem escape — possível DoS por regex catastrófico.
+
+### 8.5 Outras superfícies
+
+- `TriggerExpressionChecker` é instanciado a cada `compile` — não há cache do customizer (impacto desprezível).
+- Scripts têm acesso ao `ManagerFactory`, então podem chamar `manager.getPlayerManager().findAll()` etc. Não há controle interno de what-can-a-script-do.
+
+---
+
+## 9. Observabilidade e Troubleshooting
+
+### 9.1 Como verificar se um trigger executou
+
+```bash
+# Buscar logs por trigger.id (item == trigger.id no fluxo atual)
+GET /v3/database/trigger_log?q={"item":"<TRIGGER_ID>"}&orderby=time&reverse=true&max_results=20
+```
+
+Cada log tem `out` (println), `err` (exceções) e `ms` (latência).
+
+### 9.2 Trigger não dispara
+
+Checklist (em ordem):
+
+1. **`entity` e `event` batem com o ponto de chamada?** Conferir nos sites em `getTriggerManager().execute(<id>, <obj>, <entity>, <event>, <player>, <ctx>)`. Strings divergentes (`"action"` vs `"actions"`) silenciam.
+2. **Limite diário não está estourado?**
+   ```bash
+   GET /v3/limits
+   # Ver "trigger.max" e o atual consumido.
+   ```
+3. **`trigger.updated` é mais recente que o último `clear` no cluster?** Se você editou o trigger em um nó mas outro nó tem o cache antigo, dispare `PUT /v3/trigger/compile/all`.
+4. **Compilação falhou?** O `POST /v3/trigger` retorna `status:"ERROR"` no body se sim. Reler o response. Observação: o fluxo do `POST /v3/trigger` é `compile → add`; se `compile` falha, `add` **não é chamado** — o script com erro **não** é persistido.
+5. **`script` define `void trigger(event, entity, player, database)`?** Se não, `MissingMethodException` aparece em `trigger_log.err` na primeira execução.
+
+### 9.3 Trigger demora demais / atinge timeout
+
+- O log gravado terá `err: ["Timeout after Xs (timeout allowed Ys)", "<message>"]`.
+- Se o script faz I/O remoto (`Unirest`, `HttpClientFunifier`), aumentar `trigger.timeout` até 200. Acima disso, o `@TimedInterrupt` mata mesmo assim.
+
+### 9.4 Queries úteis
+
+```js
+// Triggers ativos em (entity, event)
+db.trigger.find({ entity: "action", event: "after_win" })
+
+// Triggers com timeout customizado
+db.trigger.find({ timeout: { $exists: true, $gt: 0 } })
+
+// Últimas execuções com erro
+db.trigger_log.find({ err: { $ne: null } }).sort({ time: -1 }).limit(20)
+
+// p95 de execução por trigger (aggregate)
+db.trigger_log.aggregate([
+  { $group: { _id: "$item", count: { $sum: 1 }, avg_ms: { $avg: "$ms" }, max_ms: { $max: "$ms" } } },
+  { $sort: { avg_ms: -1 } }
+])
+
+// Tamanho do trigger_log (atenção: pode crescer indefinidamente)
+db.trigger_log.count()
+```
+
+### 9.5 Erros comuns
+
+| Sintoma | Causa provável | Onde olhar |
+|---|---|---|
+| Script "não roda" mas POST OK | Limite diário estourado | `GET /v3/limits` |
+| Funciona em dev, falha em prod | Cache local de outro nó | `PUT /v3/trigger/compile/all` |
+| `MissingMethodException: trigger()` | Script sem a função `trigger(event, entity, player, database)` | `trigger_log.err` |
+| `SecurityException` | AST bloqueou — `.execute`, `System`, ou token não-whitelisted | `trigger_log.err` |
+| `TimeoutException` | Script passou de `trigger.timeout` ou de 200s (`@TimedInterrupt`) | `trigger_log.err` |
+| Operação principal não foi cancelada apesar de exception no `before_*` | É by design — exceptions são engolidas | seção 5 |
+| Coleção `trigger_log` cresceu muito | Não há TTL nativo no log | Criar índice TTL manualmente em `time` |
+
+### 9.6 Diagnóstico via REST
+
+```bash
+# Detalhe atual de um trigger
+GET /v3/trigger/<id>
+
+# Listar últimos triggers criados
+GET /v3/trigger?orderby=creation&reverse=true&max_results=10
+
+# Stats de execução (in-memory por instância)
+GET /v3/limits
+```
+
+---
+
+## 10. Exemplos Práticos
+
+### 10.1 Mínimo funcional — log de evento
+
+```json
+POST /v3/trigger
+{
+  "name": "Log after_win action",
+  "entity": "action",
+  "event": "after_win",
+  "script": "void trigger(event, entity, player, database) {\n  println 'event=' + event + ' player=' + player + ' actionId=' + entity.getActionId()\n}"
+}
+```
+
+Resultado esperado: cada `trackSynchonous(action)` deixa uma linha em `trigger_log.out`.
+
+### 10.2 Avançado — atribuir Achievement extra de bônus de fim de semana
+
+```json
+POST /v3/trigger
+{
+  "name": "Bônus de fim de semana",
+  "entity": "action",
+  "event": "before_win",
+  "timeout": 10,
+  "techniques": ["GT001"],
+  "references": [
+    { "_id": "weekend_bonus", "type": "action", "title": "Sell weekend", "way": "from" }
+  ],
+  "script": "void trigger(event, entity, player, database) {\n  def cal = java.util.Calendar.getInstance()\n  cal.setTime(entity.getTime())\n  def dow = cal.get(java.util.Calendar.DAY_OF_WEEK)\n  if (dow == java.util.Calendar.SATURDAY || dow == java.util.Calendar.SUNDAY) {\n    def bonus = new com.funifier.engine.achievement.Achievement(\n      com.funifier.engine.guid.Guid.newShortGuid(),\n      player,\n      50.0,\n      com.funifier.engine.achievement.Achievement.TYPE_POINT,\n      'xp',\n      new java.util.Date()\n    )\n    // Empurra para a lista que o AchievementManager devolverá ao caller\n    if (context != null && context.extra != null && context.extra['achievements'] != null) {\n      context.extra['achievements'].add(bonus)\n    }\n    println 'weekend bonus +50 xp'\n  }\n}"
+}
+```
+
+Pontos a observar:
+
+- Usa `context.extra['achievements']` (canal estabelecido por `ActionManager.trackSynchonous`).
+- O Achievement é entregue ao caller via lista mutável no `TriggerContext.extra` — o `ActionManager` ao retornar adiciona ela ao resultado final.
+- `techniques` e `references` ficam apenas como metadata.
+
+### 10.3 Debug com `/execute`
+
+```http
+POST /v3/trigger/execute/<id>?player=test@user.com
+Authorization: Bearer eyJ...
+Content-Type: application/json
+
+{ "actionId": "sell", "userId": "test@user.com", "attributes": { "value": 200 } }
+```
+
+Resposta:
+
+```json
+{
+  "trigger": { ... },
+  "exceptions": [],
+  "outputs": ["weekend bonus +50 xp"],
+  "millis": 19
+}
+```
+
+Observação: este endpoint **não respeita `dailyTriggerExecutionsLimit`** e passa `context = null`. Scripts que dependem de `context.extra` lançarão NPE — testar isso é parte do debug.
+
+### 10.4 Anti-pattern — exception como cancelamento
+
+❌ **Não fazer:**
+
+```groovy
+// Tentativa de impedir o save de um action_log
+void trigger(event, entity, player, database) {
+  if (entity.getAttributes() == null) {
+    throw new RuntimeException("attributes obrigatórios")
+  }
+}
+```
+
+Por quê: `TriggerManager.execute` faz `catch(Exception)` com `e.printStackTrace()` e segue. A action é gravada de qualquer jeito; o erro vai para o stdout do servidor (e em `trigger_log.err`), mas o caller não é notificado.
+
+✅ **Em vez disso:** se você precisa veto, mover a validação para os checks no próprio `ActionManager` ou usar um `before_purchase_validation`/`before_acquire_validation` que o caller específico realmente respeite (não os `before_create`/`before_win` genéricos).
+
+### 10.5 Anti-pattern — recompilação custosa em loop
+
+❌ **Não fazer:**
+
+```groovy
+void trigger(event, entity, player, database) {
+  // Atualiza este próprio trigger a cada execução
+  def t = database.getCollection('trigger').findOne('{_id:#}', '<this trigger id>').as(com.funifier.engine.integration.trigger.Trigger.class)
+  t.updated = new Date()
+  manager.getTriggerManager().add(t)
+}
+```
 
-- [ ] Trigger aparece na lista GET /v3/trigger
-- [ ] Evento é disparado corretamente
-- [ ] Script executa sem erros
-- [ ] Testar em staging antes de produção
+Por quê: alterar `updated` invalida o cache local. Próxima execução fará `compile` (~10–50ms). Em alta-volume, isso vira o gargalo.
+
+---
+
+## Checklist de Configuração
+
+- [ ] `entity` e `event` correspondem a uma combinação **realmente disparada** por algum manager — consultar seção 1 (lista de chamadores) e seção 3.1 (eventos extras ad-hoc).
+- [ ] `script` define `void trigger(event, entity, player, database) { ... }`.
+- [ ] `script` **não** usa `System.*`, `ProcessBuilder`, `File`, `GroovyShell`, `GroovyObject`, nem chama `.execute`/`.getDB`/`.getMongo`/`.dropDatabase` — senão `SecurityException` no AST.
+- [ ] Se o script faz I/O remoto (HTTP, e-mail), setar `timeout` explícito (até **200 segundos** — acima disso o `@TimedInterrupt` mata mesmo).
+- [ ] `GamificationLimits.dailyTriggerExecutions` do tenant comporta o volume esperado — limite zero bloqueia tudo silenciosamente.
+- [ ] Após criar/atualizar via API em ambiente cluster: chamar `PUT /v3/trigger/compile/all` em cada nó (ou aguardar que `TriggerRunner` recompile sozinho via comparação `dates < updated`).
+- [ ] **Armadilha (silencioso):** se você usar `entity:"action_log"` ou `entity:"achievement"`, **nenhum trigger dispara** — essas entidades foram comentadas em `Trigger.java` e os managers usam `Trigger.ENTITY_ACTION` (`"action"`) para o evento de gravação do `ActionLog`, e disparam por `Entity.POINT_CATEGORY.collection` / `Entity.CHALLENGE.collection` para Achievements (não pelo nome `"achievement"`).
+- [ ] **Armadilha (legacy):** `Trigger.errors` e `Trigger.logs` no schema **não são populados** no runtime atual — consultar `trigger_log` em vez disso.
+- [ ] **Armadilha (timeout duplo):** se um script demora mais de 200s independentemente do `timeout` configurado, é o `@TimedInterrupt` em `TriggerRunner.getScript` — não há configuração externa para mudar isso.
+- [ ] **Armadilha (cancelamento):** lançar exceção em `before_create`/`before_win` **não cancela** a operação principal — o caller engole e segue.
+- [ ] **Armadilha (debug ≠ produção):** `POST /v3/trigger/execute/{id}` passa `context = null` e ignora o limite diário. Scripts validados nesse endpoint podem quebrar em prod por NPE em `context.extra` ou por hit no limite.
+- [ ] **Armadilha (sem 404):** `GET /v3/trigger/{id}` de um id inexistente retorna `null` com HTTP 200, não 404.
+- [ ] **Armadilha (HTTP 201 com erro):** `POST /v3/trigger` retorna `201 Created` mesmo quando `status: "ERROR"` no body — sempre checar `status` antes de assumir sucesso.
+- [ ] `Trigger.techniques`, `Trigger.style`, `Trigger.references` são apenas Studio metadata — não usar para lógica de runtime.