funifier-mcp 0.2.26 → 0.2.28

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

@@ -1,58 +1,1111 @@
-# Scheduler (Scheduler)
+# `scheduler`
 
 **Acesso Studio:** `/studio/scheduler`
-**API Endpoint:** `/v3/scheduler`
+**API Endpoint:** `/v3/scheduler` (gamificação) · `/v3/system/scheduler/*` (system) · `/v3/util/cron/status` (status agregado)
+**Coleção MongoDB:** `scheduler` (configurações por gamificação) · `scheduler_log` (logs de execução) · `scheduler` no banco do sistema (índice de totais por apiKey)
 
-## O que é
+---
 
-Execução de códigos JAVA em datas e horários agendados (expressões CRON). Permite agendar tarefas e automações para rodar em horários ou intervalos pré-definidos.
+## 1. Visão Geral
 
-## Quando usar
+O módulo `scheduler` executa rotinas em horários determinados por expressões cron Quartz. Cada gamificação tem suas próprias configurações de scheduler armazenadas em MongoDB e os jobs são instalados em um único `Scheduler` Quartz (StdScheduler) mantido na JVM pelo `SchedulerSystem` (singleton system-level).
 
-- Para gerar relatórios automatizados (ex: toda sexta às 10h)
-- Para debitar pontos de jogadores inativos
-- Para enviar lembretes automáticos de metas
-- Para campanhas temporais com início/fim automático
+O scheduler opera em dois modos mutuamente exclusivos:
 
-## Script Runtime Environment (Wrapper Class)
+- **Script mode** — executa um bloco Groovy arbitrário dentro de uma sandbox (`SecureASTCustomizer` + `TriggerExpressionChecker`). Selecionado quando os campos `entity`, `event` e `item` **não** estão todos preenchidos.
+- **Entity mode** — despacha para um `SchedulerCallback` registrado por entidade na `ManagerFactory`. Selecionado quando `entity` E `event` E `item` estão preenchidos simultaneamente. O `script` é ignorado neste modo.
 
-O script do scheduler **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).
+O Quartz `Scheduler` é compartilhado pelo processo. Ele hospeda três tipos de job:
 
-### Regras
+- `FunifierJob` — schedulers de gamificação (group = `apiKey`)
+- `ReportSchedulerJob` — relatórios system-level (group = `report._id`)
+- `ServerPingJob` — ping do servidor para o servidor central (group = `server._id`)
 
-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. **Método principal:** `void execute()` (sem parâmetros)
-5. **Timeout padrão de 10 segundos** — pode ser customizado via campo `timeout` (em **segundos**) na API: `POST /v3/scheduler` com `{"_id": "scheduler_id", "timeout": 30}`. Este campo não aparece no Studio.
-6. Scripts rodam em **Groovy** — cuidado com `$` em GStrings
-7. Use apenas **ASCII em comentários**
+Não há persistência de estado do Quartz: o MongoDB é a fonte de verdade. Em cada `contextInitialized` o Quartz é repovoado a partir do banco. Reiniciar o processo perde os contadores de limite diário (`SchedulerStatistics` é em memória).
 
-> 📖 Ver `public.md` → **Script Runtime Environment** para a lista completa de imports e bibliotecas disponíveis.
+Integrações principais:
 
-## Checklist de Configuração no Studio
+- **LastMile** (`LastMileManager`) — único callback registrado para `entity = last_mile`. Cria/remove scheduler entity-bound automaticamente.
+- **Bonus** (`BonusManager`) — código de criação de scheduler está totalmente comentado; apenas o cleanup no `delete` continua ativo.
+- **App** (`AppManager.funifierCreateScheduler`) — instala schedulers a partir de templates ao publicar um app.
+- **GameManager.delete** — chama `getSchedulerManager().deleteAll()` em cascata ao excluir uma gamificação.
+- **ReportManager / ServerManager** — usam o Quartz compartilhado via `SystemFactory.getSchedulerManager().getQuartzScheduler()`, mas com jobs e coleções próprios (não passam pela coleção `scheduler`).
+- **StatisticManager** — gerencia o limite diário (`GamificationLimits.dailySchedulerExecutions`, default 100).
 
-- [ ] Definir nome e descrição do scheduler
-- [ ] Definir expressão CRON
-- [ ] Escrever script Java
-- [ ] Testar em ambiente de homologação
+---
 
-## API Endpoints
+## 2. Arquitetura e Fluxos
 
-### Listar Schedulers
-**Método:** GET
-**Endpoint:** `/v3/scheduler`
+### 2.1 Inicialização do servidor — `SchedulerSystem`
 
-### Criar Scheduler
-**Método:** POST
-**Endpoint:** `/v3/scheduler`
+Construtor (executado quando `SystemFactory` é instanciado):
 
-### Deletar Scheduler
-**Método:** DELETE
-**Endpoint:** `/v3/scheduler/:id`
+```
+new StdSchedulerFactory().getScheduler()
+quartzScheduler.startDelayed(10)   // delay de 10 segundos
+```
 
-## Validações e Testes
+A inicialização em si dos jobs ocorre em `Configuration.contextInitialized` (web listener / boot do JBoss), que chama `SystemFactory.getInstance().getSchedulerManager().contextInitialized()`:
 
-- [ ] Scheduler aparece na lista
-- [ ] Expressão CRON é válida
-- [ ] Script executa no horário configurado
+```
+1. Lê coleção scheduler do banco do sistema:
+     distinct("_id").query({total: {$gt: 0}})  ← retorna lista de apiKeys com schedulers
+2. Para cada apiKey:
+     ManagerFactory.getInstance(apiKey).getJongoConnection().getCollection("scheduler")
+       .find({active: true})
+     → para cada SchedulerConfig:
+        JobDetail = FunifierJob com identidade (scheduler.id, apiKey)
+        CronTrigger com identidade (scheduler.id + "trigger", apiKey)
+                     com timezone aplicado se não vazio
+        quartzScheduler.scheduleJob(job, trigger)
+3. system_report: find({active: true})
+     → ReportSchedulerJob com identidade (report._id, report._id)
+4. system_server: find()
+     → se server.active: ServerPingJob com identidade (server._id, server._id)
+```
+
+> **Atenção operacional:** schedulers de uma gamificação só são recarregados após reboot se houver um documento `{_id: <apiKey>, total: N}` (N > 0) no banco do **sistema**, coleção `scheduler`. Esse documento é mantido por `SchedulerSystem.addTotal(apiKey, count)` chamado dentro de `SchedulerManager.add` / `delete` / `deleteAll` / `deleteAllByEntity*`. Se essa coleção for limpa manualmente, os schedulers da gamificação ficam órfãos no banco e não voltam ao Quartz.
+
+`Configuration.contextDestroyed` chama `quartzScheduler.shutdown(true)`.
+
+### 2.2 Pipeline principal — `FunifierJob → SchedulerRunner.run`
+
+```mermaid
+flowchart LR
+    Q([Quartz fires CronTrigger]) --> FJ[FunifierJob.execute]
+    FJ -->|group=apiKey<br/>name=scheduler.id| MF[ManagerFactory.getInstance]
+    MF --> FB[schedulerManager.findById]
+    FB --> RUN[SchedulerRunner.run]
+    RUN --> SM[StatisticManager.newSchedulerExecution]
+    SM --> LIMIT{limite<br/>diário?}
+    LIMIT -->|excedido| ERR[exception<br/>+log+return]
+    LIMIT -->|ok| MODE{entity+event<br/>+item != null?}
+    MODE -->|sim| ENTITY[runEntity]
+    MODE -->|não| SCRIPT[runScript]
+    ENTITY --> LOG[SchedulerManager.addLog]
+    SCRIPT --> LOG
+    LOG --> R[(scheduler_log)]
+```
+
+Sequência detalhada (números = ordem de execução):
+
+```
+1. FunifierJob.execute(context)
+   - apiKey  = context.getJobDetail().getKey().getGroup()
+   - schedulerId = context.getJobDetail().getKey().getName()
+   - manager = ManagerFactory.getInstance(apiKey)
+   - scheduler = manager.getSchedulerManager().findById(schedulerId)
+   - new SchedulerRunner().run(scheduler, manager)
+
+2. SchedulerRunner.run(scheduler, manager)
+   - start = currentTimeMillis()
+   - sm = SystemFactory.getStatisticManager(apiKey)
+   - limitOk = sm.newSchedulerExecution(scheduler.id)   // incrementa contadores e devolve true/false
+   - if !limitOk:
+        exceptions += "You have exceeded your scheduler daily executions limits"
+        (NÃO chama addLog, NÃO executa script/entity)
+   - else:
+        if (scheduler.entity != null && scheduler.event != null && scheduler.item != null):
+             runEntity(...)
+        else:
+             runScript(...)
+        addLog(new SchedulerLog(id=String(dailyCount), item=scheduler.id, out, err, ms))
+
+3. Retorno
+   - Map { scheduler, exceptions, outputs, millis }
+```
+
+> **Inconsistência confirmada no código:** quando o limite diário é excedido, `addLog` **não** é chamado — não fica rastro em `scheduler_log` dessa execução pulada. Apenas o `System.out.println` é emitido.
+>
+> **Inconsistência confirmada no código:** se `scheduler == null` na chamada `FunifierJob.execute` (ID removido do banco mas job ainda no Quartz), `SchedulerRunner.run` recebe null e lança `NullPointerException` na chamada `sm.newSchedulerExecution(scheduler.id)`. Há um `//TODO excluir a scheduler` em `FunifierJob.java:31` reconhecendo esse caso sem tratamento.
+
+### 2.3 Fluxo `runEntity` (modo entity)
+
+```
+1. callback = manager.getSchedulerCallback(scheduler.entity)
+2. if callback != null:
+       callback.schedulerCallback(scheduler, exceptions, outputs)
+3. else:  // entidade sem callback registrado
+       exceptions += "SchedulerCallback does not exist for entity " + scheduler.entity
+       s = manager.getSchedulerManager().findById(scheduler.id)
+       if s != null:
+           exceptions += "SchedulerConfig " + scheduler.id + " is now disabled"
+           s.active = false
+           manager.getSchedulerManager().add(s)   // re-save com active=false
+           // efeito colateral: deleteJob(scheduler.id) no Quartz; updated atualizado
+```
+
+Callbacks resolvidos por `ManagerFactory.getSchedulerCallback(entity)`:
+
+| `entity` recebido | Callback retornado | Origem |
+|-------------------|--------------------|--------|
+| `last_mile` (= `Entity.LAST_MILE.collection`) | `LastMileManager` | Ativo |
+| `bonus` (= `Entity.BONUS.collection`) | — | **Bloco comentado em `ManagerFactory.java:240-243`**; retorna `null` |
+| qualquer outro | `null` | Falha-aberto: auto-desabilita o scheduler |
+
+### 2.4 Fluxo `runScript` — cache de classes compiladas
+
+```mermaid
+flowchart LR
+    A[runScript] --> B{scheduler.updated<br/>== null?}
+    B -->|sim| C[add scheduler<br/>seta updated=now]
+    B -->|não| D[lê lastCompilation<br/>de dates map]
+    C --> D
+    D --> E{clazz cached<br/>E<br/>lastCompilation > scheduler.updated?}
+    E -->|sim| F[executor com clazz cached]
+    E -->|não| G[getScript + compile]
+    G --> H[compiled.put + dates.put now]
+    H --> F
+```
+
+Pseudocódigo:
+
+```
+runScript(scheduler, manager, exceptions, outputs):
+    if scheduler.updated == null:
+        manager.getSchedulerManager().add(scheduler)   // upsert + seta updated
+    lastCompilation = manager.getSchedulerManager().dates.get(scheduler.id)
+    clazz = manager.getSchedulerManager().compiled.get(scheduler.id)
+    if clazz != null AND lastCompilation != null AND lastCompilation > scheduler.updated:
+        executor(clazz, scheduler, manager, exceptions, outputs)
+    else:
+        script = getScript(scheduler)        // gera wrapper Groovy + imports
+        try:
+            clazz = compile(script)          // SecureASTCustomizer + GroovyClassLoader
+            manager.getSchedulerManager().compiled.put(scheduler.id, clazz)
+            manager.getSchedulerManager().dates.put(scheduler.id, now)
+            executor(...)
+        catch CompilationFailedException:
+            exceptions += e.getMessage()
+```
+
+`compiled` e `dates` são `Map<String, Class>` e `Map<String, Date>` em `SchedulerManager` (instância por gamificação, em memória JVM). Em cluster multi-node cada JVM mantém o seu cache; o campo `updated` no documento serve como sinal cross-node: salvar em outro nó incrementa `updated`, o que invalida o cache local na próxima execução.
+
+### 2.5 Geração do wrapper Groovy — `SchedulerRunner.getScript`
+
+O wrapper inclui imports e infraestrutura padrão. Pseudocódigo da string montada:
+
+```groovy
+import groovyx.net.http.* 
+import groovy.json.* 
+import groovy.transform.TimedInterrupt 
+import com.mashape.unirest.http.*       // Unirest
+import com.funifier.engine.action.Action, ActionLog
+import com.funifier.engine.achievement.Achievement
+import com.funifier.engine.lottery.Lottery, LotteryTicket
+import com.funifier.engine.challenge.Challenge, ChallengeRule, ChallengeRuleFilter, Requirement, RewardPoint
+import com.funifier.engine.constant.Operator, TimeScale
+import com.funifier.engine.guid.Guid
+import com.funifier.engine.level.Level
+import com.funifier.engine.notify.Item, Notification, NotificationDefinition
+import com.funifier.engine.player.Player
+import com.funifier.engine.point.Point
+import com.funifier.engine.team.Team
+import com.funifier.engine.mail.FunifierMail
+import com.funifier.engine.util.DateUtil, JsonUtil, ExcelUtil, HttpUtil, HttpClientFunifier, MustacheUtils
+import com.funifier.engine.integration.trigger.GameDao
+import com.funifier.controller.ManagerFactory
+
+@TimedInterrupt(value = 2000L, unit = TimeUnit.SECONDS)
+class FunifierScheduler {
+    <SCRIPT DO USUÁRIO>            // colado literalmente
+
+    ManagerFactory manager = null
+    void setManager(ManagerFactory c) { manager = c }
+
+    GameDao database = null
+    void setDatabase(GameDao c) { database = c }
+
+    List output = new ArrayList()
+    void println(msg) { output.add(msg) }
+    void addAllOutput(List out) { out.addAll(output) }
+}
+```
+
+> **`@TimedInterrupt(value=2000L)`** é um teto absoluto de **2000 segundos** aplicado pelo Groovy. O timeout operacional via `scheduler.timeout` (default 30s) é menor e atua via `Future.cancel(true)` no executor.
+
+### 2.6 Compilação — `SchedulerRunner.compile`
+
+```
+CompilerConfiguration conf
+SecureASTCustomizer customizer
+customizer.addExpressionCheckers(new TriggerExpressionChecker())   // blacklist
+customizer.setTokensWhitelist([ EQUAL, PLUS, MINUS, MULTIPLY, DIVIDE, MOD, POWER,
+                                PLUS_PLUS, PLUS_EQUAL, MINUS_MINUS,
+                                COMPARE_EQUAL, COMPARE_NOT_EQUAL,
+                                COMPARE_LESS_THAN, COMPARE_LESS_THAN_EQUAL,
+                                COMPARE_GREATER_THAN, COMPARE_GREATER_THAN_EQUAL,
+                                LOGICAL_OR, LOGICAL_OR_EQUAL,
+                                LOGICAL_AND, LOGICAL_AND_EQUAL,
+                                LEFT_SQUARE_BRACKET, RIGHT_SQUARE_BRACKET ])
+conf.addCompilationCustomizers(customizer)
+new GroovyClassLoader(Thread.currentThread().getContextClassLoader(), conf).parseClass(script)
+```
+
+A whitelist de tokens exclui operadores comuns como `<<`, `>>`, `&`, `|`, `^`, `?:`, `?.`, `..`, etc. Isso restringe drasticamente as construções permitidas — qualquer uso desses operadores no script causa `SecurityException`.
+
+### 2.7 Execução isolada — `SchedulerRunner.executor`
+
+```
+timeout = (scheduler.timeout != null && scheduler.timeout > 0) ? scheduler.timeout : 30
+ExecutorService executor = Executors.newSingleThreadExecutor()    // NOVO executor por execução
+future = executor.submit(Callable {
+    GroovyObject obj = clazz.newInstance()
+    obj.invokeMethod("setManager",     [manager])
+    obj.invokeMethod("setDatabase",    [new GameDao(jongo, manager)])
+    obj.invokeMethod("execute",        [scheduler])               // contrato do usuário
+    obj.invokeMethod("addAllOutput",   [outputs])
+    return scheduler.id
+})
+
+try future.get(timeout, TimeUnit.SECONDS)
+catch TimeoutException, InterruptedException, ExecutionException, SecurityException,
+      MultipleCompilationErrorsException, Exception:
+    exceptions += "Timeout after N seconds (timeout allowed " + timeout + " seconds)"   // se Timeout/Interrupted
+    exceptions += e.getMessage()
+    future.cancel(true)
+    executor.shutdownNow()
+```
+
+> **Bug latente:** se `clazz.newInstance()` lançar exception **antes** do `executor.submit`, `future` continua `null` e o `catch` chamará `future.cancel(true)` → `NullPointerException` que será capturado pelo último `catch (Exception)`.
+
+> **Bug latente:** `executor` (ExecutorService) é instanciado por execução mas o `executor.shutdownNow()` só roda quando há exception. No caminho feliz nada chama `shutdown`/`shutdownNow`, então a thread fica em "core size = 0" e expira sozinha — não há vazamento de threads, mas há criação repetitiva de pools.
+
+### 2.8 `SchedulerManager.add` — criar ou atualizar
+
+```
+add(scheduler):
+    if scheduler.id == null:        scheduler.id = Guid.newShortGuid()
+    if scheduler.creation == null:  scheduler.creation = new Date()
+    scheduler.updated = new Date()                              // SEMPRE atualizado
+
+    compile(scheduler):                                          // valida script + cron
+        runner = new SchedulerRunner()
+        script = runner.getScript(scheduler)
+        runner.compile(script)                                  // CompilationFailedException
+        new CronExpression(scheduler.cron)                      // ParseException
+
+    jongo.getCollection("scheduler").save(scheduler)            // upsert por _id
+    quartzScheduler.deleteJob(jobKey(scheduler.id, apiKey))     // SEMPRE deleta job antigo
+
+    if scheduler.active:
+        job = newJob(FunifierJob.class).withIdentity(scheduler.id, apiKey)
+        cron = scheduler.timezone non-empty
+               ? cronSchedule(scheduler.cron).inTimeZone(scheduler.timezone)
+               : cronSchedule(scheduler.cron)                   // timezone padrão da JVM
+        trigger = newTrigger().withIdentity(scheduler.id + "trigger", apiKey).withSchedule(cron)
+        quartzScheduler.scheduleJob(job, trigger)
+
+    SystemFactory.getSchedulerManager().addTotal(apiKey, c.count())  // ÍNDICE de totais
+    compiled.remove(scheduler.id)                                    // invalida cache local
+    // OBS: dates NÃO é removido aqui — apenas em delete()
+```
+
+> **Compilação dupla observada:** `SchedulerRest.insert` chama `manager.compile(scheduler)` E em seguida `manager.add(scheduler)` (que recompila internamente). Não é um bug funcional, apenas trabalho duplicado.
+
+### 2.9 Diagrama de interação entre módulos
+
+```mermaid
+sequenceDiagram
+    participant Boot as Configuration<br/>contextInitialized
+    participant Sys as SchedulerSystem
+    participant Quartz as Quartz Scheduler
+    participant Mgr as SchedulerManager<br/>(per apiKey)
+    participant Run as SchedulerRunner
+
+    Boot->>Sys: contextInitialized()
+    Sys->>Sys: lê scheduler<br/>{total:{$gt:0}}
+    loop cada apiKey
+        Sys->>Mgr: ManagerFactory.getInstance(apiKey)
+        Mgr->>Quartz: scheduleJob(FunifierJob, CronTrigger)
+    end
+    Sys->>Quartz: scheduleJob(ReportSchedulerJob)
+    Sys->>Quartz: scheduleJob(ServerPingJob)
+
+    Note over Quartz: ... cron dispara ...
+
+    Quartz->>Run: FunifierJob.execute(context)
+    Run->>Mgr: findById(scheduler.id)
+    Run->>Run: StatisticManager.newSchedulerExecution
+    alt entity+event+item preenchidos
+        Run->>Mgr: getSchedulerCallback(entity)
+        Mgr-->>Run: LastMileManager (ou null)
+        Run->>Mgr: callback.schedulerCallback
+    else script mode
+        Run->>Run: getScript + compile (com cache)
+        Run->>Run: executor.submit(invokeMethod)
+    end
+    Run->>Mgr: addLog(SchedulerLog)
+```
+
+### 2.10 Integração automática LastMile → Scheduler
+
+```mermaid
+flowchart LR
+    A([POST /v3/last_mile]) --> B[LastMileManager.insert]
+    B --> C[deleteAllByEntityItemEvent<br/>last_mile, id, notify]
+    C --> Q1[(remove jobs antigos<br/>do Quartz)]
+    B --> D{lastmile.scheduler<br/>!= null?}
+    D -->|sim| E[clone scheduler do payload<br/>FORÇA: id=lastmile.id,<br/>active=true,<br/>timezone=securityManager.find.timezone,<br/>name=lastmile.title,<br/>entity=last_mile, event=notify,<br/>item=lastmile.id,<br/>script=&quot;&quot;]
+    E --> F[schedulerManager.add]
+    F --> Q2[(scheduleJob no Quartz)]
+    D -->|não| G[c.save lastmile]
+    F --> G
+```
+
+`LastMileManager.insert` **sobrescreve** os seguintes campos do scheduler vindo do cliente, ignorando os valores enviados:
+
+- `scheduler.id ← lastmile.id`
+- `scheduler.active ← true`
+- `scheduler.timezone ← securityManager.find().getTimeZone()` (timezone da gamificação)
+- `scheduler.name ← lastmile.title`
+- `scheduler.entity ← "last_mile"`
+- `scheduler.event ← "notify"`
+- `scheduler.item ← lastmile.id`
+- `scheduler.script ← ""` (string vazia)
+
+`SchedulerConfig.clone()` copia apenas: `id, name, cron, script, creation, active, timezone, extra, entity, event, item`. Os campos `time, timeout, updated, techniques, style, references` são **silenciosamente descartados** no clone — passar qualquer um deles no payload `lastmile.scheduler` é inerte. Em seguida `LastMileManager.insert` sobrescreve `id, active, timezone, name, entity, event, item, script`. Resultado: do payload original sobrevivem apenas `cron`, `extra` e `creation`. O `event` enviado pelo cliente é descartado em favor de `"notify"`.
+
+`LastMileManager.delete` chama `deleteAllByEntityItem(Entity.LAST_MILE.collection, id)` — apaga TODOS os schedulers daquele lastmile, independente de `event`.
+
+`BonusManager.delete` igualmente chama `deleteAllByEntityItem(Entity.BONUS.collection, id)` — cleanup vestigial; já não há código que crie esses schedulers (o bloco em `BonusManager.insert:44-67` está totalmente comentado).
+
+---
+
+## 3. Estrutura dos Objetos
+
+### 3.1 `SchedulerConfig` — documento principal (coleção `scheduler` da gamificação)
+
+`@JsonIgnoreProperties(ignoreUnknown=true)` — campos desconhecidos no payload são **silenciosamente descartados** pelo Jackson.
+
+| Campo | Tipo | Padrão | Obrigatório | Descrição |
+|-------|------|--------|-------------|-----------|
+| `_id` | String | `Guid.newShortGuid()` no `add` se null | — | Identificador único na gamificação |
+| `name` | String | — | não | Nome descritivo |
+| `cron` | String | — | **sim** | Expressão cron Quartz (6 campos). Validada por `new CronExpression(...)` |
+| `script` | String | — | condicional | Código Groovy. Ignorado em modo entity. Obrigatório em modo script |
+| `creation` | Date | `new Date()` no `add` se null | — | Data de criação |
+| `active` | boolean | `false` | não | Quando `false`, documento existe mas job não é instalado no Quartz |
+| `timezone` | String | — | não | Timezone IANA (ex: `America/Sao_Paulo`). Se null ou vazio, usa timezone padrão da JVM |
+| `extra` | `Map<String,Object>` | `{}` | não | Dados arbitrários acessíveis em `scheduler.extra` no script |
+| `entity` | String | — | condicional | Nome da coleção da entidade dona do callback (ex: `last_mile`). Ativa modo entity quando E `event` E `item` também preenchidos |
+| `event` | String | — | condicional | Evento dentro da entidade (ex: `notify`) |
+| `item` | String | — | condicional | ID do item específico (passado em `scheduler.item` ao callback) |
+| `time` | Date | — | — | Horário de referência da execução. Persistido mas só preenchido pelo endpoint `/execute/{id}?time=...`; em execuções Quartz normais chega `null` |
+| `timeout` | Long | `30` | não | Timeout do script em **segundos**. Se null ou `<= 0`, usa 30 |
+| `updated` | Date | `new Date()` em todo `add()` | — | Timestamp do último save; usado como sinal de invalidação de cache cross-node |
+| `techniques` | `List<String>` | `[]` | não | Códigos de técnicas de jogo associadas (GT codes) |
+| `style` | `ObjectStyle` | null | não | Atributos visuais para o Studio: `{background: String, visible: Boolean}` |
+| `references` | `List<Reference>` | null | não | Relacionamentos com outros componentes da estratégia (gamification graph) |
+
+#### Campos computados (não persistem como tais)
+
+- **Modo de operação** — derivado de `(entity, event, item)`. Os três precisam estar simultaneamente não-null (`!= null`) para acionar `runEntity`. Qualquer um null cai em `runScript`. Não há validação prévia: um scheduler com `entity = "bonus"` e os outros campos é aceito pelo POST e só falha na execução (auto-desabilita).
+
+#### Campos silenciosamente sobrescritos no save
+
+- `_id` recebe ShortGuid se null.
+- `creation` recebe `new Date()` se null.
+- `updated` recebe `new Date()` em **toda** chamada `add()`, sobrescrevendo o valor do payload.
+
+#### Diferença schema vs runtime
+
+- `time` é persistido no MongoDB e pode ser definido via payload no POST, mas no fluxo Quartz normal nunca é lido — o `SchedulerRunner.run` não popula `scheduler.time` antes da execução. Único caminho operacional: `GET /v3/scheduler/execute/{id}?time=...` faz `scheduler.time = date` antes de chamar `run`. Salvar `time` num POST regular é portanto inerte na cron normal.
+- `style` e `references` existem para o Studio e nunca são lidos pelo `SchedulerRunner`.
+- `techniques` é uma lista de códigos GT mas não há lógica de execução dentro do módulo scheduler que processe esse campo — é metadado para a UI.
+
+#### Enums e constantes referenciados
+
+- `Entity.SCHEDULER.collection = "scheduler"`
+- `Entity.SCHEDULER_LOG.collection = "scheduler_log"`
+- `Entity.LAST_MILE.collection = "last_mile"` (valor aceito como `entity`)
+- `Entity.BONUS.collection = "bonus"` (valor aceito como `entity` mas sem callback registrado)
+- `LastMileManager.EVENT_NOTIFY = "notify"`
+- `GamificationLimits.DEFAULT_DAILY_SCHEDULER_EXECUTIONS_LIMIT = 100`
+- `Reference.WAY_FROM = "from"`, `Reference.WAY_TO = "to"`
+
+### 3.2 `SchedulerLog` — documento de log (coleção `scheduler_log`)
+
+`@JsonIgnoreProperties(ignoreUnknown=true)`.
+
+| Campo | Tipo | Padrão | Descrição |
+|-------|------|--------|-----------|
+| `_id` | String | `String.valueOf(sm.getSchedulerStatistics().dailySchedulerExecutions)` | **Não é UUID** — é o valor inteiro do contador diário em memória, convertido para string. Após reinício do servidor o contador reinicia em 1 — IDs colidem entre dias/restarts e o `c.save()` faz upsert por `_id` (sobrescreve log anterior com o mesmo número). |
+| `item` | String | — | ID do scheduler que foi executado |
+| `time` | Date | `new Date()` no construtor | Momento do registro |
+| `out` | `List<String>` | `null` quando lista vazia | Outputs de `println()` durante execução. Construtor faz: `out = (out != null && out.size() > 0) ? out : null` |
+| `err` | `List<String>` | `null` quando lista vazia | Mensagens de exceção. Mesma regra de `out` |
+| `ms` | long | — | Tempo total de `SchedulerRunner.run` em milissegundos |
+
+> Como `out` e `err` são gravados como `null` quando vazios (não como `[]`), para filtrar execuções com erros use `q={err:{$ne:null}}`.
+
+### 3.3 `Reference` — subentidade de relacionamento
+
+Compartilhada com `Trigger`. Documenta como o scheduler se relaciona com outros componentes (consumo de pontos, vínculo a achievement, etc).
+
+| Campo | Tipo | Descrição |
+|-------|------|-----------|
+| `way` | String | `"from"` ou `"to"`; sentido da seta no grafo do Studio |
+| `linkLabel` | String | Texto sobre a seta |
+| `_id` | String | ID do componente referenciado |
+| `type` | String | Coleção do componente (ex: `Entity.POINT.collection`) |
+| `title` | String | Título descritivo |
+
+### 3.4 `ObjectStyle` — subentidade de visual
+
+| Campo | Tipo | Descrição |
+|-------|------|-----------|
+| `background` | String | Cor de fundo / asset visual no Studio |
+| `visible` | Boolean | Visibilidade na UI |
+
+### 3.5 `SchedulerStatistics` — estado em memória (não persistido autonomamente)
+
+Mantido por `StatisticManager` (um por gamificação). Persistido apenas como parte de `STATISTIC_LOG` (coleção do sistema).
+
+| Campo | Tipo | Descrição |
+|-------|------|-----------|
+| `lastSchedulerExecution` | Date | Última execução registrada |
+| `hourlySchedulerExecutions` | long | Contador na hora corrente. Reset ao mudar `HOUR_OF_DAY` |
+| `dailySchedulerExecutions` | long | Contador no dia corrente. Reset ao mudar `DAY_OF_YEAR` |
+| `monthlySchedulerExecutions` | long | Contador no mês corrente. Reset ao mudar `MONTH` |
+| `dailySchedulerExecutionsLimit` | long | Cópia de `GamificationLimits.dailySchedulerExecutions` (default 100) |
+| `triggers` | `Map<String, SchedulerDetailStatistics>` | Contadores por scheduler.id |
+
+> O comparador no `newSchedulerExecution` usa `<=`: incrementa o contador primeiro, depois testa `dailySchedulerExecutions <= dailySchedulerExecutionsLimit`. Com limite 100, a 100ª chamada incrementa para 100, passa no teste (`100 <= 100`) e retorna `true`; a 101ª retorna `false`. Permite exatamente `limit` execuções por dia.
+
+---
+
+## 4. Endpoints
+
+### `GET /v3/scheduler`
+
+Listagem com filtros via aggregate pipeline (não `find` direto).
+
+| Aspecto | Detalhe |
+|---------|---------|
+| Finalidade | Listar configurações de scheduler da gamificação |
+| Autenticação | Bearer token |
+| Implementação | `MongoCollection.aggregate(...)` com `$match` + `$sort` + `$limit` |
+| Resposta | Array JSON com campos null removidos (`JsonUtil.toJsonRemoveNullFields`) |
+
+**Query params:**
+
+| Param | Tipo | Descrição |
+|-------|------|-----------|
+| `id` | String | Filtra `_id` exato |
+| `q` | String | Cláusula MongoDB **raw injetada** no `$match` |
+| `published_min` | String | Lower bound aplicado em `creation`. RFC3339 ou keyword (`-1d`, `-30m`, `-1w`, `y/M/d/h/m/s/w`) |
+| `published_max` | String | Upper bound em `creation` |
+| `orderby` | String | Campo de `$sort` (também injetado raw) |
+| `reverse` | String→boolean | `"true"` → `-1` (DESC); senão `1` (ASC) |
+| `max_results` | String→int | Default `100` quando `<= 0` |
+
+**Comportamento real:**
+
+- `q` é concatenado literalmente: `query.append(", " + q)` — qualquer operador MongoDB válido funciona, inclusive `$where`. Não há sanitização. **Surface de injeção.**
+- `orderby` também é concatenado literalmente em `{$sort: {<orderby>: #}}`. Não há lista permitida.
+- Parsing de `published_min`/`published_max` tenta primeiro `parseZonedDateToLocalDate` (RFC3339) e cai em `fromKeyword` se null.
+- O `findAll(id, q, ...)` aceita id no path do match, mas a rota também aceita id como query param; se ambos forem usados o id do query param prevalece.
+
+---
+
+### `GET /v3/scheduler/log`
+
+Logs de execução com paginação.
+
+| Aspecto | Detalhe |
+|---------|---------|
+| Finalidade | Listar `SchedulerLog` com paginação por `Range` header |
+| Implementação | `PaginationUtil.getPageResult(aggregate, range, 0, 100)` |
+
+**Query params:**
+
+| Param | Tipo | Descrição |
+|-------|------|-----------|
+| `item` | String | Filtra logs de um scheduler específico (`log.item == schedulerId`) |
+| `q` | String | Cláusula MongoDB raw (mesmo padrão de injeção do `GET /v3/scheduler`) |
+| `published_min` | String | Lower bound aplicado em `time` (não `creation`) |
+| `published_max` | String | Upper bound em `time` |
+| `orderby` | String | Campo de ordenação raw |
+| `reverse` | String→boolean | DESC quando `true` |
+| `max_results` | String→int | Default `100` |
+
+**Header:**
+
+| Header | Descrição |
+|--------|-----------|
+| `Range` | Formato `items=A-B`, ex `items=0-99` |
+
+**Resposta:** payload paginado padrão da Funifier (`PaginationUtil`). Resposta contém o campo `Content-Range` apropriado quando o handler é `Callback.paginatedCallback`.
+
+---
+
+### `GET /v3/scheduler/{id}`
+
+Retorna `SchedulerConfig` por `_id`. Campos null removidos. Sem 404 explícito: se `findById` retornar null, a resposta é vazia / JSON `{}`.
+
+---
+
+### `GET /v3/scheduler/execute/{id}`
+
+Execução manual para debug.
+
+| Aspecto | Detalhe |
+|---------|---------|
+| Finalidade | Disparar o scheduler imediatamente, fora da agenda Quartz |
+| Efeito colateral | Consome quota diária; grava `scheduler_log` |
+| Diferença vs. cron | Não respeita `active=false` — executa mesmo desativado |
+
+**Query params:**
+
+| Param | Tipo | Descrição |
+|-------|------|-----------|
+| `time` | String | Sobrescreve `scheduler.time` antes da execução. Aceita RFC3339, keyword (`-1d`), ou epoch millis (`Long.parseLong`). Tentativas em cascata; se todas falharem, `scheduler.time` mantém o valor original (não é sobrescrito) |
+
+**Resposta:** `{ scheduler, exceptions, outputs, millis }` com null removidos.
+
+> Se `scheduler == null` (id inexistente), `scheduler.time = date` lança `NullPointerException` antes mesmo da chamada do `run`.
+
+---
+
+### `GET /v3/scheduler/next/{id}`
+
+Retorna as **próximas 10 datas** de execução após uma referência.
+
+**Query params:**
+
+| Param | Tipo | Descrição |
+|-------|------|-----------|
+| `reference` | String | Data de referência. RFC3339, keyword, ou `null`. Se null, usa `new Date()` |
+
+**Comportamento real:** `nextExecutionTimesAfter` faz um loop fixo de 10 iterações chamando `CronExpression.getNextValidTimeAfter`. Se em alguma iteração retornar `null` (sem próxima ocorrência), o loop quebra e retorna a lista parcial. Datas vêm formatadas via `DateUtil.formatDateToZonedDate`.
+
+---
+
+### `POST /v3/scheduler`
+
+Criar ou atualizar um scheduler.
+
+| Aspecto | Detalhe |
+|---------|---------|
+| Finalidade | Upsert por `_id` |
+| Full replace ou patch | **Full replace** — `Jongo.save()` substitui o documento |
+| Validação | Compila script Groovy **+** valida cron antes de salvar |
+| HTTP status | **Sempre `201 Created`**, inclusive em erro de compilação |
+| Content-Type | `application/json` |
+
+**Resposta sucesso:**
+
+```json
+{ "scheduler": { ... }, "status": "OK" }
+```
+
+**Resposta erro de compilação ou cron inválido:**
+
+```json
+{ "scheduler": { ... }, "status": "ERROR", "message": "<mensagem>" }
+```
+
+**Comportamento real:**
+
+1. `manager.compile(scheduler)` valida script + cron. Se falhar com `CompilationFailedException` ou `ParseException`, retorna `status: ERROR` no body com HTTP 201.
+2. **Não captura** `SchedulerException` (de operações Quartz) — esta sobe pela stack e produz HTTP 500.
+3. `manager.add(scheduler)` recompila o script (compilação dupla) e:
+   - Gera `_id` ShortGuid se não fornecido
+   - Seta `creation = now` se null
+   - Seta `updated = now` (sempre)
+   - Upsert no MongoDB
+   - Remove job antigo do Quartz e recria se `active=true`
+   - Invalida `compiled[scheduler.id]`
+   - Atualiza índice de totais do sistema
+
+**Exemplo:**
+
+```json
+POST /v3/scheduler
+{
+  "active": true,
+  "name": "Notificação diária",
+  "cron": "0 0/20 * * * ?",
+  "timezone": "America/Sao_Paulo",
+  "script": "void execute(scheduler){ println 'every 20 minutes for ' + scheduler.extra.company; }",
+  "extra": { "company": "funifier" }
+}
+```
+
+---
+
+### `DELETE /v3/scheduler/{id}`
+
+Remove documento + job Quartz + entradas de `compiled` E `dates` + atualiza índice de totais.
+
+Resposta: `204 No Content`. Não há verificação se o ID existe — `c.remove()` é idempotente.
+
+---
+
+### `PUT /v3/scheduler/compile/{id}`
+
+Limpa **apenas** o cache `compiled` (não `dates`).
+
+| Path | Efeito |
+|------|--------|
+| `/compile/all` | Itera `findAll()` e chama `manager.clear()` em cada — remove cada `compiled[id]` |
+| `/compile/<id>` | `findById(id)` e se não-null chama `clear()` |
+
+> A próxima execução ainda comparará `dates[id] > scheduler.updated`. Como `clear()` não toca em `dates`, se `dates[id]` permanecer maior que `updated`, o teste `clazz != null && lastCompilation > updated` falha (clazz é null), forçando recompilação — comportamento desejado. Mas o `dates` permanece "sujo": após recompilar, `dates.put(id, now)` sobrescreve.
+
+Resposta: `200 OK` com `{ "_id": "<id>" }`.
+
+---
+
+### `GET /v3/system/scheduler/status` (system-only)
+
+Expõe `SchedulerSystem.getStatus()`. Retorna estado agregado:
+
+```json
+{
+  "isStarted": true,
+  "jobGroupNames": [ "<apikey>", "<reportId>", "<serverId>" ],
+  "triggerGroupNames": [ "..." ],
+  "pausedTriggers": [],
+  "metadata": { ... },
+  "schedulers": [
+    { "_id": "<schedulerId>trigger", "next": "...", "prev": "..." }
+  ],
+  "references": [
+    "report_<reportId>",
+    "gamification_<apikey>_sheduler_<schedulerId>"
+  ]
+}
+```
+
+> **Typo no payload de produção:** `"gamification_<apikey>_sheduler_<id>"` — "sheduler" sem 'c'. Está hardcoded em `SchedulerSystem.getStatus:153`.
+
+---
+
+### `GET /v3/system/scheduler/jobs` (system-only)
+
+Expõe `SchedulerSystem.getAllJobKeys()`. Itera todos os jobs do Quartz, resolve cada `group` na coleção `game` (campo `_id == group`) para anexar nome da gamificação, apiKey e nome do scheduler. Retorna lista de:
+
+```json
+[
+  {
+    "groupName": "<apikey ou reportId ou serverId>",
+    "jobName": "<schedulerId>",
+    "gamification": "<game.name>",
+    "account": "<game.accountId>",
+    "schedulerName": "<scheduler.name ou 'SCHEDULER DONT EXIST'>",
+    "nextExecution": "Mon Jan 01 09:00:00 UTC 2025",
+    "isActive": "Yes"
+  }
+]
+```
+
+> Se o job está no Quartz mas foi removido do MongoDB, `schedulerName` aparece como `"SCHEDULER DONT EXIST"`. Útil para detectar drift.
+
+---
+
+### `GET /v3/util/cron/status` (gamificação, com Bearer)
+
+Alias acessível para o mesmo `SchedulerSystem.getStatus()` — duplicação intencional para acesso por consumidores de gamificação.
+
+---
+
+## 5. Regras de Negócio
+
+**Modo de operação derivado, não declarado.** Não há campo `mode` — é uma derivação implícita: `(entity != null && event != null && item != null)` → entity; senão → script. Schedulers parcialmente preenchidos (ex. `entity` mas sem `event`) caem em script silenciosamente.
+
+**Modo entity ignora `script`.** No fluxo `runEntity` o campo `script` nunca é avaliado. O `LastMileManager.insert` aproveita isso para gravar `script = ""` (vazio) em schedulers entity-bound — economiza memória mas confunde quem inspeciona a coleção.
+
+**Validação dupla no upsert.** `SchedulerRest.insert` chama `compile()` e depois `add()` (que recompila internamente). Em fluxos via `AppManager.funifierCreateScheduler`, `LastMileManager.insert` ou outros caminhos internos, apenas `add()` é chamado — também valida.
+
+**Auto-disable silencioso por callback ausente.** Se `entity` for uma string para a qual `ManagerFactory.getSchedulerCallback` retorna null, o scheduler é re-salvo com `active=false` na primeira execução. **A primeira execução consome quota** mas executa um `runEntity` no-op que termina com exception. O usuário não é notificado fora do `err` do log.
+
+**Limite diário.** `dailySchedulerExecutionsLimit` vem de `GamificationLimits` (coleção `gamification_limits` no banco do sistema). Default `100/dia`. Limite só bloqueia execuções de schedulers — não bloqueia o agendamento. Se atingido, `runEntity`/`runScript` nem é chamado, mas o log também não é gravado.
+
+**Contadores em memória.** `SchedulerStatistics` reinicia ao detectar mudança de hora/dia/mês na próxima execução (não no relógio). Reiniciar o processo zera os contadores antes do banco persistir (apenas `STATISTIC_LOG` é gravado periodicamente em outros caminhos — verificar com [statistic_log]).
+
+**Upsert por `_id`.** Tanto `add()` quanto `c.save()` fazem upsert. Reusar `_id` em um POST substitui o documento inteiro — não é PATCH.
+
+**Cron Quartz, não Unix.** 6 campos (`seg min hor dia mês dia-semana`). Diferenças relevantes vs cron Unix:
+- Dia-da-semana usa códigos `MON–SUN` ou números 1–7 (1=Domingo no Quartz).
+- `?` é obrigatório em um dos campos `dia` ou `dia-semana` (não pode-se especificar ambos).
+- Suporta `/` para incremento, `L` para "last", `W` para weekday, `#` para "nth day-of-week".
+
+**Timezone.** Se `scheduler.timezone` é `null` ou string vazia, o cron usa o timezone padrão da JVM. Em containers/produção isso é normalmente UTC — o que muda o instante de disparo vs. o esperado pelo usuário do Studio.
+
+**Identidade Quartz.** Jobs de gamificação têm `JobKey(scheduler.id, apiKey)`. Triggers têm `TriggerKey(scheduler.id + "trigger", apiKey)`. Não há risco de colisão entre gamificações; há risco de colisão com schedulers system se um `apiKey` coincidir com `server._id` ou `report._id` (improvável na prática).
+
+**Cluster.** O Quartz é local (`StdSchedulerFactory.getScheduler()` sem `quartz.properties` para JDBC store). Em múltiplos nós, **cada nó executa o cron independentemente** — o scheduler vai disparar N vezes em uma topologia de N nós. O campo `updated` apenas serve para sincronização do cache de compilação.
+
+---
+
+## 6. Comportamentos Automáticos
+
+| Comportamento | Trigger | Impacto | Persistência |
+|---------------|---------|---------|--------------|
+| Auto `_id` via ShortGuid | `add()` sem `_id` | Gera identificador | MongoDB |
+| Auto `creation` | `add()` sem `creation` | Seta `new Date()` | MongoDB |
+| Auto `updated` | Toda chamada `add()` | Sobrescreve `updated` com `new Date()` | MongoDB + invalida cache cross-node |
+| Recompilação e re-agendamento do job | Toda `add()` | `quartzScheduler.deleteJob(...)` SEMPRE; `scheduleJob` apenas se `active=true` | Memória Quartz |
+| Atualização do índice de totais | `add()`, `delete()`, `deleteAll()`, `deleteAllByEntity*` | `{_id: apiKey, total: count}` na coleção `scheduler` do sistema | MongoDB sistema |
+| Invalidação de `compiled` | `add()` e `delete()` | Remove entrada da `Map<String, Class>` | Memória JVM |
+| Invalidação de `dates` | `delete()` apenas | Remove entrada da `Map<String, Date>` | Memória JVM |
+| Auto-disable por callback ausente | Execução em modo entity quando `getSchedulerCallback(entity) == null` | Re-save com `active=false` + job removido do Quartz | MongoDB + Quartz |
+| Cascade delete no game | `GameManager.delete(apiKey)` | `schedulerManager.deleteAll()` | MongoDB + Quartz + sistema |
+| Cascade no LastMile.insert | `LastMileManager.insert(lastmile)` | `deleteAllByEntityItemEvent("last_mile", id, "notify")` + `add(scheduler clonado e sobrescrito)` | MongoDB + Quartz |
+| Cascade no LastMile.delete | `LastMileManager.delete(id)` | `deleteAllByEntityItem("last_mile", id)` (qualquer `event`) | MongoDB + Quartz |
+| Cleanup vestigial no Bonus.delete | `BonusManager.delete(id)` | `deleteAllByEntityItem("bonus", id)` — limpa schedulers que o `insert` não mais cria | MongoDB + Quartz |
+| Instalação a partir de app template | `AppManager.funifierCreateScheduler(payload)` | Desserializa JSON em `SchedulerConfig` e chama `add()` | MongoDB + Quartz |
+| Boot bootstrap | `Configuration.contextInitialized` → `SchedulerSystem.contextInitialized` | Recarrega todos schedulers ativos no Quartz | Quartz (memória) |
+| Shutdown | `Configuration.contextDestroyed` → `quartzScheduler.shutdown(true)` | Para todos os jobs aguardando finalização | — |
+
+### 6.1 Fluxo de cascade ao deletar uma gamificação
+
+```mermaid
+flowchart LR
+    A([DELETE game]) --> B[GameManager.delete]
+    B --> C[schedulerManager.deleteAll]
+    C --> D[(loop SchedulerConfigs)]
+    D --> E[quartz.deleteJob<br/>por scheduler]
+    D --> F[c.drop scheduler collection]
+    F --> G[SystemFactory.deleteTotal apiKey]
+    G --> H[(remove de scheduler<br/>do sistema)]
+```
+
+---
+
+## 7. Suportado vs NÃO Suportado
+
+### ✅ Suportado
+
+- Criar/atualizar/deletar scheduler via REST (`POST`, `DELETE`).
+- Listar com filtros via aggregate pipeline (`q`, `published_min/max`, `orderby`, `reverse`, `max_results`).
+- Listar logs com paginação por header `Range`.
+- Execução manual via `/v3/scheduler/execute/{id}` com sobrescrita opcional de `time`.
+- Cálculo das próximas 10 datas via `/v3/scheduler/next/{id}`.
+- Limpeza manual de cache de compilação via `/v3/scheduler/compile/{id|all}`.
+- Timezone IANA por scheduler.
+- Timeout configurável por scheduler (em segundos, default 30).
+- Sandbox Groovy via `SecureASTCustomizer` (blacklist + tokens whitelist).
+- Limite diário por gamificação (default 100/dia, configurável em `gamification_limits`).
+- Cache de classes Groovy compiladas com invalidação por `updated`.
+- Modo entity para `last_mile` (único callback ativo).
+- Status agregado do Quartz via `/v3/util/cron/status` e `/v3/system/scheduler/status`.
+- Listagem completa dos JobKeys do Quartz via `/v3/system/scheduler/jobs`.
+- Instalação programática via `AppManager.funifierCreateScheduler` (a partir de templates de app).
+- Cascade automático em `LastMileManager.insert/delete` e `GameManager.delete`.
+
+### ❌ NÃO Suportado
+
+- **PATCH parcial**: `POST` substitui o documento inteiro. Não há endpoint de update parcial.
+- **Modo entity para `bonus`**: o bloco em `ManagerFactory.getSchedulerCallback` está totalmente comentado (linhas 240-243). Qualquer scheduler com `entity = "bonus"` é auto-desabilitado na primeira execução. O método `schedulerCallback` em `BonusManager.java:354-359` também está dentro de bloco comentado.
+- **Modo entity para qualquer entidade fora `last_mile`**: o dispatcher tem só uma entrada ativa.
+- **Retry em falha**: execuções com exception ou timeout não são re-tentadas; aguardam o próximo disparo cron.
+- **Persistência dos contadores de limite**: `SchedulerStatistics` é em memória; restart zera. O snapshot vai parar em `STATISTIC_LOG` apenas em outros caminhos do `StatisticManager`.
+- **HTTP non-201 em erro de validação**: o `POST` sempre retorna `201 Created` mesmo com `status: "ERROR"` no body. Falhas de compilação Groovy e parse de cron NÃO produzem `400 Bad Request`.
+- **Idempotência do `SchedulerLog._id`**: o `_id` é o contador diário em memória como string (`"1"`, `"2"`, ...). Após restart o contador reinicia; o `save()` faz upsert — logs com mesmo `_id` se sobrescrevem entre dias/restarts.
+- **404 quando scheduler não existe**: `GET /v3/scheduler/{id}` para id inexistente retorna body vazio (JSON `{}`) com HTTP 200, não `404`. `GET /v3/scheduler/execute/{id}` lança `NullPointerException` (HTTP 500) — o `null` do `findById` não é tratado.
+- **Validação de combinação `entity` + `event` + `item`**: aceita combinações parciais que caem silenciosamente em script mode.
+- **Lock cluster-wide**: em múltiplos nós, cada nó executa o cron independentemente. Não há leader election — para evitar duplicação use lógica no script.
+- **Cron Unix (5 campos)**: apenas Quartz (6 campos). Expressões Unix-style são rejeitadas no `new CronExpression(...)`.
+- **Tokens excluídos da whitelist do sandbox**: `<<`, `>>`, `&`, `|`, `^`, `?:`, `?.`, `..` causam erro de compilação. Operações de bit, navegação null-safe e ranges (`1..10`) não estão liberadas.
+- **`@TimedInterrupt` configurável**: o teto absoluto de 2000 segundos no wrapper é hardcoded em `SchedulerRunner.getScript:200`.
+- **Snapshot de `time` por execução cron**: `scheduler.time` só é preenchido pelo endpoint `/execute` — em execuções Quartz é `null`. Para usar o horário corrente no script, use `new Date()` diretamente.
+- **Pausar / despausar via REST**: não há endpoint. Setar `active=false` via POST + re-salvar é o caminho.
+- **Limpeza orfan do Quartz**: se o documento for removido do MongoDB diretamente (via Database REST `/v3/database/scheduler`), o job no Quartz permanece até reboot ou intervenção manual.
+
+---
+
+## 8. Segurança e Permissões
+
+### Autenticação
+
+Todas as rotas de `/v3/scheduler/*` usam `@BeanParam AuthBean` → Bearer token. O `apiKey` derivado do token é usado para:
+
+- Buscar o `ManagerFactory` da gamificação (`FrontController.getInstance(apiKey).getManagerFactory()`).
+- Identidade do job Quartz: `JobKey(scheduler.id, apiKey)` — isolamento por gamificação.
+- Conexão MongoDB já namespaced em `manager.getJongoConnection()`.
+
+As rotas `/v3/system/scheduler/*` não exigem `AuthBean` por código no `SchedulerRest` (system-side), mas dependem da configuração do servidor (geralmente atrás de filtro de IP/role).
+
+### Sandbox Groovy
+
+Duas camadas:
+
+**1. `TriggerExpressionChecker` — blacklist (compartilhado com Trigger):**
+
+Classes proibidas (match em `expression.getType().getName()`):
+- `java.lang.System`
+- `java.lang.ProcessBuilder`
+- `java.io.File`
+- `groovy.lang.GroovyShell`
+- `groovy.lang.GroovyObject`
+
+Expressões proibidas (match por **substring** em `expression.getText()`):
+- `.execute`
+- `.getDB`
+- `.getMongo`
+- `.dropDatabase`
+
+**2. Whitelist de tokens** (apenas operadores listados são permitidos):
+
+`=`, `+`, `-`, `*`, `/`, `%`, `**`, `++`, `+=`, `--`, `==`, `!=`, `<`, `<=`, `>`, `>=`, `||`, `||=`, `&&`, `&&=`, `[`, `]`
+
+### Limitações conhecidas do sandbox
+
+- **Match por substring**, não por AST semântico: uma expressão que evite literalmente `.execute` (ex.: indireção via reflexão ou `eval`) pode passar pelo filtro. Concatenação de strings (`'.exec' + 'ute'`) não é resolvida em tempo de compilação por este checker.
+- **Apenas tipos diretos** são bloqueados — referências por string e reflexão geral (`Class.forName`) não são impedidas por essa lista.
+- O `GroovyClassLoader` usa `Thread.currentThread().getContextClassLoader()` — scripts compilam contra todo o classpath da aplicação. Qualquer classe Funifier ou de terceiros disponível em runtime é acessível desde que não passe pelos filtros acima.
+- O `executor.shutdownNow()` envia `Thread.interrupt()`, mas em loops Groovy puros sem checagem de `Thread.interrupted()`, a thread pode continuar até o `@TimedInterrupt` (2000s).
+
+### Superfícies de injeção
+
+- **`q` em `GET /v3/scheduler`** — concatenado raw no `$match`. Operadores como `$where` (JavaScript eval no Mongo) podem ser usados para exfiltrar dados ou consumir recursos.
+- **`q` em `GET /v3/scheduler/log`** — mesmo padrão.
+- **`orderby` em ambos** — concatenado raw em `{$sort: {<orderby>: #}}`. Não permite escrita mas permite enumerar campos.
+- **`script` no `POST`** — sandbox protege contra acesso direto a APIs perigosas, mas todo o classpath fica acessível.
+
+### Isolamento por tenant
+
+- Conexão MongoDB e `JobKey` por `apiKey` garantem isolamento horizontal.
+- `compiled`/`dates` são por `SchedulerManager` (uma instância por `ManagerFactory`, ou seja, por gamificação).
+
+---
+
+## 9. Observabilidade e Troubleshooting
+
+### Diagnóstico rápido
+
+```
+# Existência e estado:
+GET /v3/scheduler/<id>
+
+# Quartz vê o job? (lista próximas datas):
+GET /v3/scheduler/next/<id>?reference=-0d
+
+# Estado agregado do Quartz para esta gamificação:
+GET /v3/util/cron/status
+  → checar references["gamification_<apikey>_sheduler_<id>"]
+  → checar schedulers[].next != null
+
+# Executar manualmente para reproduzir:
+GET /v3/scheduler/execute/<id>
+  → inspecionar response.exceptions e response.outputs
+```
+
+### Consultas úteis a logs
+
+```
+# Últimas 10 execuções:
+GET /v3/scheduler/log?item=<id>&orderby=time&reverse=true&max_results=10
+
+# Execuções com erro:
+GET /v3/scheduler/log?item=<id>&q={"err":{$ne:null}}&orderby=time&reverse=true
+
+# Execuções no último dia:
+GET /v3/scheduler/log?item=<id>&published_min=-1d&orderby=time&reverse=true
+
+# Execuções lentas (>5s):
+GET /v3/scheduler/log?item=<id>&q={"ms":{$gte:5000}}&orderby=ms&reverse=true
+```
+
+### Erros comuns e causas
+
+| Sintoma | Causa provável | Verificação |
+|---------|----------------|-------------|
+| Scheduler não executa após criar | `active=false`, cron inválida apesar do POST aceitar, ou exception silenciosa no `scheduleJob` | `GET /v3/scheduler/<id>` (active?); `GET /v3/scheduler/next/<id>` (lista vazia indica não-agendado) |
+| Scheduler parou após N execuções | Limite diário atingido | Comparar com `dailySchedulerExecutions` em `getSchedulerStatistics()` (não exposto em REST — usar log: `q={"err":{$ne:null}}`) |
+| Scheduler executa em horário errado | `timezone` null ou JVM em UTC | Conferir campo `timezone`; usar `/next/{id}` para validar |
+| `POST` retornou `status: OK` mas job não roda | `active=false` no payload OU `scheduleJob` falhou silenciosamente após `c.save` | Sempre passar `"active": true` quando quiser execução; verificar `/next/{id}` |
+| Scheduler some após reboot | Documento `{_id: apiKey, total: N}` ausente em `scheduler` do sistema | Inserir manualmente (`{_id: <apiKey>, total: <count>}`) ou refazer um POST que reativa o índice via `addTotal` |
+| `runEntity` falha com `SchedulerCallback does not exist` | `entity` referencia coleção sem callback (`bonus`, custom, typo) | Mover para `script` ou usar `entity: "last_mile"` |
+| HTTP 500 em `/v3/scheduler/execute/<id>` | `findById` retornou null (ID inexistente) | Verificar com `GET /v3/scheduler/<id>` antes de executar |
+| Script executa código antigo | Cache de `compiled` desatualizado vs `updated` em outro nó | `PUT /v3/scheduler/compile/<id>` em todos os nós; alternativamente `POST` para forçar `updated = now` |
+| Compilação falha com mensagem `Token X is not allowed` | Uso de operador fora da whitelist (`<<`, `?.`, `..`, etc.) | Reescrever sem o operador |
+| Compilação falha com `Type X is not authorized` | Uso direto de `System`, `File`, `ProcessBuilder`, `GroovyShell`, `GroovyObject` | Usar APIs do `manager`/`database` |
+| Logs com `_id` duplicado entre dias | Contador `dailySchedulerExecutions` reiniciou após reboot | Usar `time` + `item` para identificar; aceitar como limitação |
+
+### Verificar drift Quartz vs MongoDB (system-only)
+
+```
+GET /v3/system/scheduler/jobs
+  → procurar entradas com schedulerName = "SCHEDULER DONT EXIST"
+  → indica job no Quartz sem documento no banco (drift)
+```
+
+---
+
+## 10. Exemplos Práticos
+
+### Exemplo mínimo funcional
+
+```json
+POST /v3/scheduler
+{
+  "active": true,
+  "name": "Hello daily",
+  "cron": "0 0 9 * * ?",
+  "timezone": "America/Sao_Paulo",
+  "script": "void execute(scheduler){ println 'ran at ' + new Date() }"
+}
+```
+
+### Exemplo avançado com `extra`, `timeout` e uso de `manager`/`database`
+
+```json
+POST /v3/scheduler
+{
+  "_id": "debit_inactive_xp",
+  "active": true,
+  "name": "Debitar XP de inativos (30 dias)",
+  "cron": "0 0 2 * * ?",
+  "timezone": "America/Sao_Paulo",
+  "timeout": 120,
+  "extra": {
+    "diasInatividade": 30,
+    "pontoTipo": "xp",
+    "pontosDebitar": 10
+  },
+  "script": "void execute(scheduler){\n  def dias = scheduler.extra.diasInatividade\n  def pontos = scheduler.extra.pontosDebitar\n  def tipo = scheduler.extra.pontoTipo\n  def ref = DateUtil.addDays(new Date(), -dias)\n  def players = database.find('player', '{\"lastAction\":{\"$lt\":#}}', ref)\n  for(def p : players){\n    manager.getPointManager().add(p._id, tipo, -pontos, null)\n  }\n  println 'processed ' + players.size() + ' players'\n}"
+}
+```
+
+### Debug com tempo simulado
+
+```
+# Simular execução como se fosse 2024-12-31 23:59 BRT
+GET /v3/scheduler/execute/debit_inactive_xp?time=2024-12-31T23:59:00-03:00
+
+# Resposta:
+{
+  "scheduler": { "_id": "debit_inactive_xp", "time": "2024-12-31T23:59:00-03:00", ... },
+  "exceptions": [],
+  "outputs": ["processed 42 players"],
+  "millis": 1834
+}
+```
+
+### Listar próximas execuções a partir de uma data
+
+```
+GET /v3/scheduler/next/debit_inactive_xp?reference=2025-01-01T00:00:00-03:00
+→
+[
+  "2025-01-02T02:00:00-03:00",
+  "2025-01-03T02:00:00-03:00",
+  "2025-01-04T02:00:00-03:00",
+  "..."
+]
+```
+
+### Forçar recompilação após mudança em cluster
+
+```
+PUT /v3/scheduler/compile/debit_inactive_xp
+```
+
+### Anti-pattern: script sem assinatura `void execute(scheduler)`
+
+```groovy
+// ERRADO — o executor faz invokeMethod("execute", [scheduler]) literalmente.
+// Sem este método exato, GroovyObject lança MissingMethodException.
+println 'hello'
+
+// CORRETO
+void execute(scheduler){ println 'hello' }
+```
+
+### Anti-pattern: declarar `import` no script
+
+```groovy
+// ERRADO — getScript() já injeta imports padrão antes da class FunifierScheduler.
+// imports adicionais dentro da class causam CompilationFailedException.
+import com.funifier.engine.player.Player
+void execute(scheduler){ ... }
+
+// CORRETO — classes Funifier comuns (Player, Achievement, Lottery, Action, etc.)
+// já estão importadas pelo wrapper. Use diretamente.
+void execute(scheduler){
+  Player p = manager.getPlayerManager().findById("playerId")
+}
+```
+
+### Anti-pattern: scheduler entity com entidade não suportada
+
+```json
+// ERRADO — primeira execução vai gravar exception + setar active=false
+{
+  "active": true,
+  "cron": "0 0 9 * * ?",
+  "entity": "bonus",
+  "event": "notify",
+  "item": "bonus_id_123"
+}
+// Erro registrado: "SchedulerCallback does not exist for entity bonus"
+// Estado pós-execução: active=false (persistido) + job removido do Quartz
+```
+
+### Anti-pattern: cron Unix (5 campos)
+
+```
+// ERRADO — Quartz precisa de 6 campos
+"cron": "0 9 * * *"
+
+// CORRETO — Quartz com campo de segundos e `?` em um dos dia/dia-semana
+"cron": "0 0 9 * * ?"
+```
+
+### Anti-pattern: depender de `scheduler.time` em execução cron
+
+```groovy
+// ERRADO — scheduler.time é null em execuções Quartz normais
+void execute(scheduler){
+  def ref = scheduler.time     // null
+  // ...
+}
+
+// CORRETO — use new Date() ou scheduler.extra.referenceTime
+void execute(scheduler){
+  def ref = new Date()
+  // ...
+}
+```
+
+### Anti-pattern: usar operador fora da whitelist
+
+```groovy
+// ERRADO — operadores ?., ..,  ?:, << não estão na whitelist
+void execute(scheduler){
+  def name = scheduler?.extra?.user?.name        // ?. bloqueado
+  for(int i in 1..10) { ... }                    // .. bloqueado
+}
+
+// CORRETO — usar checagem null explícita e for clássico
+void execute(scheduler){
+  def name = (scheduler != null && scheduler.extra != null && scheduler.extra.user != null) ? scheduler.extra.user.name : null
+  for(int i = 1; i <= 10; i++) { ... }
+}
+```
+
+---
+
+## Checklist de Configuração
+
+- [ ] `active: true` definido (default é `false` — o documento é salvo mas o job NÃO é agendado)
+- [ ] `cron` é Quartz com 6 campos (`seg min hor dia mês diasem`) e usa `?` em um dos campos `dia`/`dia-semana`
+- [ ] `timezone` IANA preenchido — não confiar no default da JVM (geralmente UTC em containers)
+- [ ] **Script mode**: `script` contém exatamente `void execute(scheduler){ ... }` (assinatura literal)
+- [ ] **Script mode**: nenhum `import` no script (já injetados pelo wrapper)
+- [ ] **Script mode**: nenhum dos operadores fora da whitelist (`<<`, `>>`, `&`, `|`, `^`, `?:`, `?.`, `..`)
+- [ ] **Entity mode**: três campos preenchidos (`entity`, `event`, `item`) e `entity` referencia uma coleção COM callback registrado em `ManagerFactory.getSchedulerCallback`
+- [ ] **Entity mode**: para `last_mile`, sempre criado pelo `LastMileManager.insert` — não criar manualmente (ele sobrescreve campos)
+- [ ] `timeout` ajustado se a operação puder demorar mais de 30s
+- [ ] Validar POST: ler o `status` no body — HTTP é sempre 201, mesmo em erro de compilação
+- [ ] Após criar, validar via `GET /v3/scheduler/next/<id>` que retorna lista não-vazia
+- [ ] Armadilha: scheduler com `entity` definido mas sem callback é **auto-desabilitado na primeira execução**, consumindo quota
+- [ ] Armadilha: scheduler somem após restart se o índice `{_id: apiKey, total: N}` da coleção `scheduler` do sistema for limpo
+- [ ] Armadilha: `c.save()` no POST é full-replace — preserve campos que não quiser perder
+- [ ] Armadilha: parâmetros `q` e `orderby` nos GET são concatenados raw no MongoDB; trate-os como confiáveis apenas com produtores também confiáveis
+- [ ] Armadilha: em cluster multi-node, cada nó executa o cron — dedupe na lógica do script
+- [ ] Armadilha: `SchedulerLog._id` é um contador diário em memória; após restart pode haver upsert sobre logs antigos