funifier-mcp 0.2.26 → 0.2.28

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

@@ -1,45 +1,584 @@
-# LastMile (Última Milha)
+# `lastmile`
 
 **Acesso Studio:** `/studio/lastmile`
-**API Endpoint:** `/v3/lastmile`
+**API Endpoint:** `/v3/lastmile` (mensagens) · `/v3/bonus` (motor de cálculo acoplado)
+**Coleção MongoDB:** `last_mile` · `bonus`
 
-## O que é
+> Engenharia reversa do pacote `com.funifier.engine.lastmile` em `funifier-service`
+> (`LastMile`, `LastMileManager`, `LastMileRest`, `LastMileLog`, `Bonus`, `BonusManager`, `BonusRest`, `BonusRule`, `BonusReward`, `Progress`).
+> Esta documentação descreve o comportamento **real do código** — divergências em relação ao schema e comportamentos silenciosos estão explicitados.
 
-Envio de mensagens motivacionais quando o jogador está próximo de uma meta. Permite configurar mensagens automáticas para engajar e lembrar os jogadores sobre metas e desafios que estão prestes a serem concluídos, aumentando a taxa de finalização.
+---
 
-## Quando usar
+## 1. Visão Geral
 
-- Para lembrar jogadores que estão perto de completar desafios
-- Para aumentar taxa de conclusão de metas
-- Para enviar mensagens motivacionais personalizadas
-- Para engajar jogadores que estão a 80-90% de uma meta
+**LastMile (Last Mile Drive / "última milha")** entrega mensagens de incentivo a jogadores cujo progresso está dentro de uma **faixa percentual semi-aberta `[start, ends)`** de uma meta. A mensagem funciona como um "coach": _"faltam 2 vendas para você atingir 100% e ganhar o bônus X"_.
 
-## Dependências
+O pacote `lastmile` contém **dois motores acoplados**, persistidos em coleções distintas e expostos por REST distintos:
 
-- **Challenge**: desafios devem existir para monitorar progresso
+| Motor | Coleção | REST | Papel |
+|-------|---------|------|-------|
+| `LastMile` | `last_mile` | `/v3/lastmile` | Define a mensagem, a faixa de disparo, o alvo e o agendamento |
+| `Bonus` | `bonus` | `/v3/bonus` | Calcula progresso e recompensas do jogador; **é quem produz o texto** das mensagens lastmile do tipo bônus |
 
-## Checklist de Configuração no Studio
+LastMile **não é autossuficiente** no modo principal (`type = TYPE_BONUS`): a mensagem só é gerada por dentro de `BonusManager.calculate()`, que mede o progresso real do jogador. Por isso ambos os motores estão documentados aqui.
 
-- [ ] Definir condição de disparo (% de progresso)
-- [ ] Definir mensagem motivacional
-- [ ] Vincular ao desafio ou meta específica
+**Dependências de runtime (via `ManagerFactory`):**
 
-## API Endpoints
+- `CrowningManager.calculatePlayerLeaderHelper` — calcula o resultado real do jogador por período/operação.
+- `SchedulerManager` / `SchedulerRunner` — agenda e dispara a geração das mensagens (coleção `scheduler`).
+- `NotificationManager` — entrega as mensagens como notificações privadas (coleção `notification`).
+- `MustacheUtils` + Groovy (`GroovyClassLoader` + `SecureASTCustomizer`) — interpolação e preparação de variáveis da mensagem.
+- `exp4j` (`ExpressionBuilder`) — avalia fórmulas de `goal` e `total`.
+- `GameTechniqueManager` — atribui o código de técnica `GT53` ao LastMile.
 
-### Listar LastMile
-**Método:** GET
-**Endpoint:** `/v3/lastmile`
+---
 
-### Criar LastMile
-**Método:** POST
-**Endpoint:** `/v3/lastmile`
+## 2. Arquitetura e Fluxos
 
-### Deletar LastMile
-**Método:** DELETE
-**Endpoint:** `/v3/lastmile/:id`
+### 2.1 Dois caminhos de geração (divergência runtime importante)
 
-## Validações e Testes
+Existem **dois caminhos distintos** que produzem mensagens lastmile, e eles têm efeitos colaterais diferentes:
 
-- [ ] Configuração de LastMile aparece na lista
-- [ ] Mensagem é disparada ao atingir % configurado
-- [ ] Jogador recebe notificação corretamente
+| Caminho | Disparado por | Envia notificação? | Saída |
+|---------|---------------|--------------------|-------|
+| **Cron** | `SchedulerRunner` → `LastMileManager.schedulerCallback()` | **Sim** (`NotificationManager.send`) | Notificações privadas por jogador |
+| **Inline** | `BonusManager.calculate()` (endpoints `/v3/bonus/.../calculate*`) | **Não** | Apenas `lastmiles[]` no corpo da resposta |
+
+> O caminho inline (cálculo via API de bônus) **nunca envia notificações** — ele apenas devolve as mensagens calculadas no JSON. O envio é exclusivo do caminho cron.
+
+### 2.2 Pipeline principal — cron / `type = TYPE_BONUS`
+
+```
+[Criação]   LastMileRest.insert()          → LastMileManager.insert()
+            └─ gera _id (Guid.newShortGuid) se ausente
+            └─ deleteAllByEntityItemEvent("last_mile", id, "notify")  // limpa scheduler antigo
+            └─ se lastmile.scheduler != null:
+                 clona SchedulerConfig (active=true, timezone, entity="last_mile",
+                 event="notify", item=id, script="") → SchedulerManager.add()
+            └─ collection("last_mile").save(lastmile)
+            └─ compiled.remove(id)          // invalida cache do script Groovy (nó local)
+
+[Disparo]   SchedulerRunner.run()
+            └─ StatisticManager.newSchedulerExecution(id)   // checa limite diário do tenant
+            └─ runEntity()                                  // pois entity/event/item != null
+
+[Dispatch]  ManagerFactory.getSchedulerCallback("last_mile") → LastMileManager
+            └─ se callback == null → adiciona exceção e DESATIVA o scheduler (active=false)
+
+[Callback]  LastMileManager.schedulerCallback()
+            └─ lastmile = find(item)
+            └─ if type == 8  (TYPE_BONUS)  → generateLastmileDriveNotificationsForBonus()
+            └─ if type == 99 (TYPE_CUSTOM) → generateLastmileDriveNotificationsForCustom()
+            └─ (qualquer outro type → NADA acontece, silenciosamente)
+
+[Alvo]      findPlayersToLastMile(lastmile)
+            └─ se lastmile.to vazio/null → retorna LISTA VAZIA (ver §5 / §7)
+            └─ senão: distinct("_id") em player com filtro raw { _id:{$exists:true}, <to> }
+
+[Cálculo]   para cada player:
+            └─ BonusManager.calculate(bonus, player, params{player,global}, mile=lastmile)
+            └─ result.get("lastmiles") → List<LastMileLog>
+
+[Mensagem]  generateMessage(lastmile, params)
+            └─ se lastmile.script != "" → runScript() (Groovy seguro, timeout 5s)
+            └─ MustacheUtils.parse(lastmile.message, params)
+
+[Notifica]  para cada LastMileLog:
+            └─ NotificationDefinition(EVENT_WIN=0, TYPE_TEXT=0, SCOPE_PRIVATE=0, message)
+            └─ NotificationManager.send(notification)   // efeito colateral persistente
+```
+
+### Fluxo de geração — `firelastmile` (cron, TYPE_BONUS)
+
+```mermaid
+flowchart LR
+    A[POST /v3/lastmile] --> B[LastMileManager.insert]
+    B --> C{scheduler != null?}
+    C -- sim --> D[SchedulerManager.add\nentity=last_mile event=notify]
+    C -- não --> E[apenas save em last_mile]
+    D --> F[SchedulerRunner.run]
+    F --> G{limite diário ok?}
+    G -- não --> Z[exceção: limite excedido]
+    G -- sim --> H[getSchedulerCallback last_mile]
+    H --> I[schedulerCallback]
+    I --> J{type}
+    J -- 8 BONUS --> K[generateForBonus]
+    J -- 99 CUSTOM --> L[generateForCustom]
+    J -- outro --> X[nada]
+    K --> M[findPlayersToLastMile]
+    M --> N{to vazio?}
+    N -- sim --> Y[0 jogadores - silencioso]
+    N -- não --> O[BonusManager.calculate por player]
+    O --> P[generateMessage mustache+groovy]
+    P --> Q[NotificationManager.send]
+```
+
+### 2.3 Pipeline — cron / `type = TYPE_CUSTOM`
+
+Só funciona se **`entity`** e **`aggregate`** estiverem preenchidos (método `generateLastmileDriveNotificationsForCustom`):
+
+1. `findPlayersToLastMile(lastmile)` — obtém ids dos jogadores (mesma regra do `to`).
+2. Substitui o token literal `FUNIFIER_PLAYER_IDS` no `aggregate` pela lista de ids serializada.
+3. Executa o pipeline de agregação na coleção indicada por `lastmile.entity`, materializando cada documento como um `Progress`.
+4. Para cada `Progress`: `percent = progress.getPercentCompleted()`. Se `start <= percent < ends` e há mensagem → `NotificationManager.send`.
+
+> No modo custom o `Progress` vem **direto da agregação que o usuário escreve** — o engine não calcula progresso; ele confia no shape devolvido pelo pipeline.
+
+### 2.4 Algoritmo de recompensa e gap — `BonusManager.calculate()`
+
+```
+percent = pro.getPercentCompleted()          // ver §3.6 (média dos micro-progressos)
+
+para cada reward r em bonus.rewards:
+    total = exp4j( mustache(r.total, params) )
+    se   r.start <= percent < r.ends:
+        cria Achievement(type=r.type, item=r.item, total=(long)total, player)  // NÃO PERSISTE
+    senão se percent < r.start:               // jogador ainda não atingiu a faixa
+        p = clona Progress e reposiciona meta para r.start (moveGoalToSpecificPercentualPosition)
+        params["progress"] = p; params["reward"] = r; params["reward_total"] = total
+        para cada lastmile vinculado (findAllByItem(TYPE_BONUS, bonusId)):
+            se lastmile.start <= percent < lastmile.ends:
+                gera LastMileLog( message = generateMessage(lastmile, params),
+                                  image = lastmile.image, priority = lastmile.priority )
+    // se percent >= r.ends → faixa já ultrapassada → reward IGNORADA (sem achievement, sem lastmile)
+
+retorna { achievements, progress, progress_rewards, lastmiles }
+```
+
+Pontos não óbvios:
+
+- **`calculate` não premia.** Os `Achievement` montados são devolvidos no JSON, mas **nunca persistidos** (não há chamada a `AchievementManager.add/insert/save`). A premiação real ocorre em outro fluxo (triggers/achievement). É uma API de **preview/cálculo**.
+- A mensagem lastmile só nasce quando o jogador está **abaixo** da faixa de recompensa (`percent < r.start`) — é o "ainda falta" que o reward representa.
+- Toda a execução está dentro de `try { } catch (Exception)` que devolve `{ "error": <mensagem> }` — **qualquer falha é engolida** (ver §9).
+
+### 2.5 Interação entre módulos (cron vs inline)
+
+```mermaid
+sequenceDiagram
+    participant Cron as SchedulerRunner
+    participant LM as LastMileManager
+    participant BM as BonusManager
+    participant NM as NotificationManager
+    participant API as BonusRest
+
+    Note over Cron,NM: Caminho CRON (notifica)
+    Cron->>LM: schedulerCallback(scheduler)
+    LM->>BM: calculate(bonus, player, mile=lastmile)
+    BM-->>LM: result.lastmiles[]
+    LM->>NM: send(notification)  // efeito colateral
+
+    Note over API,BM: Caminho INLINE (não notifica)
+    API->>BM: calculate(bonus, player)  // GET /v3/bonus/:id/calculate
+    BM->>BM: findAllByItem(TYPE_BONUS, bonusId)
+    BM-->>API: { achievements, progress, lastmiles[] }  // só JSON
+```
+
+---
+
+## 3. Estrutura dos Objetos
+
+### 3.1 `LastMile` — documento raiz (coleção `last_mile`)
+
+| Campo | Tipo | Padrão | Obrigatório | Descrição |
+|-------|------|--------|-------------|-----------|
+| `_id` | String | `Guid.newShortGuid()` se ausente | — | Id curto gerado no insert |
+| `title` | String | — | recomendado | Usado como `name` do scheduler |
+| `type` | int | `0` | sim (lógico) | Tipo do objeto monitorado (ver enum abaixo). Só `8` e `99` têm tratamento |
+| `item` | String | — | sim p/ `type=8` | Id do `bonus` monitorado |
+| `start` | double | `0.0` | sim | Limite inferior da faixa de progresso (inclusivo) |
+| `ends` | double | `0.0` | sim | Limite superior da faixa de progresso (exclusivo) |
+| `priority` | double | `0.0` | não | Prioridade da mensagem (copiada para o `LastMileLog`) |
+| `message` | String | — | sim | Template Mustache (`{{player.name}}`, `{{progress.gap}}`, `{{reward.title}}`…) |
+| `image` | String | — | não | URL de imagem (copiada para o `LastMileLog`) |
+| `script` | String | — | não | Script Groovy `void prepare(lastmile, params){…}` para preparar variáveis |
+| `to` | String | — | **crítico p/ cron** | Filtro Mongo **raw** aplicado a `player` (ex.: `extra.role:'asven',active:true`). **Vazio = nenhum jogador** |
+| `scheduler` | `SchedulerConfig` | `null` | não | Agenda a geração automática. Sem ele, não há disparo cron |
+| `entity` | String | `null` | sim p/ `type=99` | Coleção onde o `aggregate` roda (somente custom) |
+| `aggregate` | String | `null` | sim p/ `type=99` | Pipeline de agregação JSON; usa o token `FUNIFIER_PLAYER_IDS` |
+| `techniques` | `List<String>` | `null` | não | Auto-preenchido com `["GT53"]` (ver §3.8). Ignorado na lógica de lastmile |
+
+**Enum `type`** (`Achievement.TYPE_*`) — apenas dois são tratados no `schedulerCallback`:
+
+| Valor | Constante | Tratamento no LastMile |
+|-------|-----------|------------------------|
+| `8` | `TYPE_BONUS` | ✅ `generateLastmileDriveNotificationsForBonus` |
+| `99` | `TYPE_CUSTOM` | ✅ `generateLastmileDriveNotificationsForCustom` |
+| `0,1,2,3,4,5,6,7,9,50` | POINT, CHALLENGE, CATALOG_ITEM, LEVEL, CROWN, LOTTERY, MYSTERY_BOX, CHARACTER_STAR_STAT, COMPETITION, LOTTERY_TICKET | ❌ Aceitos no schema, mas o callback **não faz nada** |
+
+**Campos aceitos e silenciosamente ignorados:**
+- `techniques` — não influencia geração de mensagem; serve apenas para catalogação de técnicas (`GT53`).
+- Qualquer campo desconhecido — a classe é anotada com `@JsonIgnoreProperties(ignoreUnknown=true)`: campos extras enviados no POST são descartados sem erro.
+
+### 3.2 `SchedulerConfig` — subentidade `scheduler` (coleção `scheduler`)
+
+Campos efetivamente usados pelo LastMile no `insert` (os demais são herdados do módulo de scheduler):
+
+| Campo | Tipo | Comportamento no LastMile |
+|-------|------|---------------------------|
+| `cron` | String | Expressão cron de agendamento (informada pelo cliente) |
+| `id` | String | **Sobrescrito** com `lastmile.id` |
+| `name` | String | **Sobrescrito** com `lastmile.title` |
+| `active` | boolean | **Forçado** para `true` |
+| `timezone` | String | **Sobrescrito** com o timezone da organização (`SecurityManager.find().getTimeZone()`) |
+| `entity` | String | **Forçado** para `"last_mile"` |
+| `event` | String | **Forçado** para `"notify"` |
+| `item` | String | **Forçado** para `lastmile.id` |
+| `script` | String | **Forçado** para `""` (a lógica vem do callback, não do script genérico) |
+| `timeout` | Long | Timeout em segundos da execução (default 30 no runner genérico) |
+
+> Mesmo que o cliente envie valores em `id`, `name`, `active`, `entity`, `event`, `item`, `script`, eles são **substituídos** dentro de `LastMileManager.insert()`. Só `cron` (e demais campos de agendamento) são respeitados.
+
+### 3.3 `Bonus` — documento raiz (coleção `bonus`)
+
+| Campo | Tipo | Padrão | Obrigatório | Descrição |
+|-------|------|--------|-------------|-----------|
+| `_id` | String | `Guid.newShortGuid()` se vazio | — | Id curto |
+| `title` | String | — | recomendado | Título do bônus |
+| `description` | String | — | não | Descrição |
+| `tags` | `List<String>` | `[]` | não | Filtrável em `findAll` (`tags: {$all: […]}`) |
+| `rules` | `List<BonusRule>` | `[]` | sim | Metas que compõem o progresso |
+| `rewards` | `List<BonusReward>` | `[]` | sim | Faixas de recompensa por percentual |
+| `principals` | `List<String>` | `[]` | não | Ids de player/team para os quais o bônus existe (com expansão de times) |
+| `extra` | `Map` | `{}` | não | Campos adicionais livres |
+| `to` | String | — | não | Filtro Mongo **raw** adicional sobre `player` |
+
+**Campo removido/legado:** `scheduler` existe apenas **comentado** no código-fonte do `Bonus` — **o bônus não possui campo de agendamento ativo**. Agendamento só existe no `LastMile` (ver §7).
+
+### 3.4 `BonusRule` — subentidade (meta)
+
+| Campo | Tipo | Descrição |
+|-------|------|-----------|
+| `id` | String | Identificador da regra (para correlacionar no progress) |
+| `goal` | String | Meta: número, variável Mustache (`{{player.extra.meta}}`) ou fórmula — avaliada por `exp4j` |
+| `operation` | `Operation` | Como calcular o resultado real do jogador |
+| `period` | `Period` | Janela de tempo do cálculo |
+
+**`Operation.type`:** `1` COUNT_ACTIONS · `2` SUM_ATTRIBUTE · `3` SUM_ACHIEVEMENTS · `4` AVG_ATTRIBUTE · `10` PREPARED_KPI. Campos: `achievement_type` (`-1` = NONE), `item`, `filters[{param, operator, value}]`, `sort`, `sub`.
+
+**`Period.type`:** `0` `TYPE_VARIABLE` (usa `timeAmount` + `timeScale`, ex.: última semana) · `1` `TYPE_FIXED` (usa `startDate`/`endDate`). Alternativamente `expression` (string `"inicio;fim"` com palavras-chave de data) tem precedência quando preenchida.
+
+### 3.5 `BonusReward` — subentidade (faixa de recompensa)
+
+| Campo | Tipo | Descrição |
+|-------|------|-----------|
+| `title` | String | Título da faixa (ex.: "Faixa 100%") |
+| `start` | double | Percentual inicial da faixa (inclusivo) |
+| `ends` | double | Percentual final da faixa (exclusivo) |
+| `type` | int | Tipo de achievement gerado (`Achievement.TYPE_*`, ex.: `0` = ponto) |
+| `item` | String | Item do achievement (ex.: `reais`) |
+| `total` | String | Valor: número, variável Mustache ou fórmula — avaliado por `exp4j`; convertido para `long` |
+
+### 3.6 `Progress` — objeto computado (não é coleção própria)
+
+Objeto de transporte/medição. Usado (a) no resultado de `calculate`, (b) como classe-alvo da agregação no modo custom. Seus principais valores são **calculados via getters**, não persistidos:
+
+| Getter | Lógica |
+|--------|--------|
+| `getGoal()` | Sem `micro` → `goal`; 1 micro → goal do micro; N micros → **soma** |
+| `getDone()` | Idem, **soma** dos micros |
+| `getGap()` | `goal > done ? goal-done : 0`; N micros → **soma** dos gaps |
+| `getPercentCompleted()` | Sem micro → `(done/goal)*100`; N micros → **média aritmética** dos percentuais |
+| `getStart()` / `getEnd()` | Menor data entre os micros |
+| `getTime()` | Mapa `{ unit:"DAYS", spent, total }` (dias decorridos vs total) |
+
+Campos persistíveis/serializados: `_id`, `type`, `item`, `player`, `goal`, `done`, `operation`, `start`, `now`, `end`, `extra`, `micro[]`.
+`moveGoalToSpecificPercentualPosition(percent, propagate)` recalcula `goal = percent*(goal/100)` e propaga aos micros.
+
+### 3.7 `LastMileLog` — objeto de transporte (não é coleção própria)
+
+Gerado em memória dentro de `calculate`; vira notificação ou item de `lastmiles[]`. **Não há coleção `last_mile_log`.**
+
+| Campo | Tipo | Descrição |
+|-------|------|-----------|
+| `_id` | String | (não setado no fluxo atual) |
+| `player` | String | Jogador alvo (preenchido só no caminho legado comentado) |
+| `message` | String | Mensagem já interpolada |
+| `priority` | double | Copiado de `lastmile.priority` |
+| `image` | String | Copiado de `lastmile.image` |
+
+### 3.8 Técnicas de jogo (`techniques`)
+
+| Código | Significado | Atribuição |
+|--------|-------------|------------|
+| `GT53` | Last Mile | `GameTechniqueManager.autoConfigureMissingTechniqueFields()` adiciona `GT53` a todo `last_mile` cujo `techniques` esteja ausente ou vazio (`$size:0`) e salva o campo de técnica `(_id="last_mile", field="techniques", title="title")` |
+
+> **`Bonus` não recebe código GT** — não está no auto-configure de técnicas. O bônus não é catalogado como técnica de jogo independente.
+
+---
+
+## 4. Endpoints
+
+Autenticação: **OAuth 2.0 (`client_credentials`) / Bearer token** em todos os endpoints (conforme anotações apiDoc). Multi-tenant resolvido por `apiKey` (`FrontController.getInstance(apiKey)`).
+
+### 4.1 LastMile (`/v3/lastmile`)
+
+**`GET /v3/lastmile/{id}`** — `LastMileManager.find(id)`. Retorna o documento (JSON com nulls).
+
+**`GET /v3/lastmile`** — `findAll()`. Retorna **todos** os documentos `last_mile` (sem filtros de query).
+
+**`POST /v3/lastmile`** — `insert(lastmile)`.
+
+| Aspecto | Detalhe |
+|---------|---------|
+| Finalidade | Criar **ou substituir** uma configuração de lastmile |
+| Full replace ou patch | **Full replace** (`MongoCollection.save`) — enviar `_id` existente sobrescreve o documento inteiro. **Não há PATCH** |
+| Efeitos colaterais | (Re)cria scheduler `last_mile/notify`; remove scheduler antigo do item; invalida cache Groovy local |
+| Resposta | `201 Created` com o objeto (`toJsonRemoveNullFields`) |
+
+**`DELETE /v3/lastmile/{id}`** — `delete(id)`. Remove o documento, remove **todos** os schedulers do item (`deleteAllByEntityItem`) e limpa o cache Groovy local. Resposta `200`.
+
+### 4.2 Bonus (`/v3/bonus`)
+
+**`GET /v3/bonus/{id}`** — `find(id)`.
+
+**`GET /v3/bonus`** — `findAll(...)` via pipeline de agregação. Query params:
+
+| Param | Tipo | Descrição |
+|-------|------|-----------|
+| `id` | String | Filtra por `_id` |
+| `title` | String | Regex case-insensitive sobre `title` |
+| `tags` | String | CSV → `tags: {$all: [...]}` |
+| `to` | String | Player/Team id (ou `me`) — retorna bônus visíveis ao principal (campo `principals`) |
+| `q` | String | Critério Mongo **raw** adicional (ex.: `extra.field:"x"`) |
+| `fields` | String | CSV → projeção `$project` |
+| `orderby` | String | Campo de ordenação (`_id`, `title`, `tags`) |
+| `reverse` | boolean | `true` → ordem descendente |
+| `max_results` | int | Limite (default **100** se ≤ 0) |
+
+**`POST /v3/bonus`** — `insert(bonus)`. **Full replace** (`save`). Gera `_id` se vazio. `201`.
+
+**`DELETE /v3/bonus/{id}`** — `delete(id)`. Remove o bônus e (defensivamente) schedulers do item. `200`.
+
+**`GET /v3/bonus/{id}/calculate`** — `calculate(id, player, time, simulate)`. Preview do progresso/recompensas de **um jogador**. Params: `player` (ou `me`), `time` (referência temporal), `simulate` (substitui o resultado real — ver §5). **Não persiste, não notifica.**
+
+**`GET /v3/bonus/{id}/calculateToAllPlayers`** — itera `findPlayersToBonus(id)` e calcula para todos. **Sem anotação apiDoc** (endpoint operacional). **Não persiste, não notifica.**
+
+**`PUT /v3/bonus/calculateAll`** — corpo = lista de ids de bônus; calcula todos para um `player`; devolve `result`, `total` (somatório de achievements por item), `size`, `millis`.
+
+**`PUT /v3/bonus/simulateAll`** — corpo = mapa `{ bonusId: valorSimulado }`; simula cada bônus com o valor informado.
+
+---
+
+## 5. Regras de Negócio
+
+Regras presentes no código que não aparecem no schema:
+
+- **Faixa semi-aberta `[start, ends)`** — a comparação é sempre `percent >= start && percent < ends`. Faixas adjacentes não devem se sobrepor; `ends` é exclusivo.
+- **Targeting assimétrico entre os dois motores:**
+  - `Bonus.findPlayersToBonus` — se `principals` vazio **e** `to` nulo → **todos os jogadores**; senão filtra por `principals` (com expansão de `teams`) e/ou `to`.
+  - `LastMile.findPlayersToLastMile` — se `to` vazio/null → **lista vazia** (o fallback "todos" está **comentado**). Modelos de alvo diferentes no mesmo pacote.
+- **Recompensa só quando jogador está abaixo da faixa** — a mensagem lastmile é gerada apenas no ramo `percent < reward.start`. Se o jogador já está dentro da faixa, ele recebe o achievement (em preview), não a mensagem de incentivo.
+- **Faixa ultrapassada é ignorada** — rewards com `percent >= ends` não geram nada.
+- **Single-rule colapsa o progresso** — se o bônus tem exatamente 1 regra, `pro` vira o próprio micro-progresso; com N regras, percentual é a **média** dos micros (não ponderada).
+- **Modo `simulate`** — quando `simulate` é informado em `calculate`: as `rules` são esvaziadas (`bonus.rules = []`), `pro.done = parseDouble(simulate)` e `pro.goal` = soma dos goals das regras avaliados. **Não há medição real por regra** — o `progress` devolvido reflete o valor simulado, não o resultado do jogador.
+- **`calculate` é preview** — não persiste achievements; premiação real ocorre fora deste fluxo.
+- **Limite diário de execuções de scheduler por tenant** — `StatisticManager.newSchedulerExecution`; ao exceder, a execução é abortada com exceção registrada.
+- **Multi-tenant** — toda operação é resolvida por `apiKey`; coleções e conexões Jongo são isoladas por tenant.
+
+---
+
+## 6. Comportamentos Automáticos
+
+| Comportamento | Trigger | Impacto | Persistência |
+|---------------|---------|---------|--------------|
+| Geração de `_id` curto | `insert` (LastMile/Bonus) sem id | `_id = Guid.newShortGuid()` | Persistido |
+| (Re)criação de scheduler | `LastMile.insert` com `scheduler != null` | Cria `SchedulerConfig` `last_mile/notify`, `active=true` | Persistido (coleção `scheduler`) |
+| Remoção de scheduler antigo | `LastMile.insert` e `delete` | `deleteAll*` schedulers do item | Persistido |
+| Invalidação do cache Groovy | `LastMile.insert`/`delete` | `compiled.remove(id)` | Runtime — **somente nó local** |
+| Atribuição de técnica `GT53` | `autoConfigureMissingTechniqueFields()` | `techniques = ["GT53"]` se vazio | Persistido |
+| Compilação/execução de script | `generateMessage` com `script != ""` | Compila Groovy seguro, cacheia, executa `prepare()` | Cache runtime (5s timeout) |
+| Notificação de incentivo | callback cron (TYPE_BONUS/CUSTOM) | `NotificationManager.send` (EVENT_WIN/TEXT/PRIVATE) | Persistido (coleção `notification`) |
+| Desativação de scheduler órfão | `runEntity` sem callback p/ a entity | `scheduler.active = false` | Persistido |
+
+### Encadeamento de behaviors no `insert`
+
+```mermaid
+flowchart LR
+    I[insert lastmile] --> A[gera _id]
+    A --> B[deleteAllByEntityItemEvent\nlast_mile/notify]
+    B --> C{scheduler != null}
+    C -- sim --> D[clona + força campos\nentity/event/item/active/timezone]
+    D --> E[SchedulerManager.add]
+    C -- não --> F[skip scheduler]
+    E --> G[save last_mile]
+    F --> G
+    G --> H[compiled.remove id\ninvalida cache local]
+```
+
+---
+
+## 7. Suportado vs NÃO Suportado
+
+### ✅ Suportado
+
+- CRUD de `LastMile` (`/v3/lastmile`) e `Bonus` (`/v3/bonus`).
+- Geração de mensagens por **cron** para `type = TYPE_BONUS (8)` e `type = TYPE_CUSTOM (99)`.
+- Cálculo/simulação de bônus (preview) por jogador, em lote e para todos os jogadores.
+- Templates Mustache com variáveis `player`, `global`, `progress`, `reward`, `reward_total` + variáveis criadas via script Groovy.
+- Script Groovy sandboxed (`prepare(lastmile, params)`) com timeout de 5s.
+- Targeting por filtro Mongo (`to`) no LastMile; por `principals`/`to` no Bonus.
+
+### ❌ NÃO Suportado / Comportamento silencioso
+
+- **`Bonus.scheduler` não existe** — o campo está **comentado** na entidade e no `BonusManager.insert`. Bônus **não se auto-agenda**; o agendamento vive apenas no `LastMile`.
+- **`BonusManager` não é `SchedulerCallback`** — `schedulerCallback` e o registro em `getSchedulerCallback` estão **comentados**. Um `SchedulerConfig` com `entity="bonus"` **não tem callback** → o runner o **desativa** (`active=false`).
+- **Tipos diferentes de `8`/`99`** no callback de LastMile → **nada acontece** (sem erro, sem log de negação).
+- **LastMile com `scheduler` mas `to` vazio** → `findPlayersToLastMile` devolve `[]` → cron roda e atinge **zero jogadores**, silenciosamente.
+- **`calculate` não premia** — achievements montados não são persistidos (preview-only).
+- **Caminho inline não notifica** — endpoints de cálculo de bônus só devolvem `lastmiles[]` no JSON; nenhuma notificação é enviada.
+- **Sem PATCH / atualização parcial** — POST com `_id` existente é **full replace** (`save`).
+- **`techniques` ignorado na lógica** — aceito e auto-preenchido, mas não altera comportamento.
+- **Campos desconhecidos descartados** — `@JsonIgnoreProperties(ignoreUnknown=true)` em todas as entidades.
+- **Código legado comentado** (não executado): `BonusManager.calculateOLD`, `BonusManager.schedulerCallback`/`generateLastmileDriveNotificationsForAllPlayers`, `LastMileManager.executeScript`, e o fallback "todos os jogadores" em `findPlayersToLastMile`.
+
+---
+
+## 8. Segurança e Permissões
+
+- **Autenticação:** OAuth 2.0 `client_credentials` / Bearer token (`AuthBean`); isolamento multi-tenant por `apiKey`.
+- **Sandbox Groovy** (em `generateMessage`/`runScript`):
+  - `SecureASTCustomizer` + `TriggerExpressionChecker` + **whitelist de tokens** (apenas operadores aritméticos/lógicos/comparação e colchetes).
+  - Anotação `@TimedInterrupt(5s)` **e** `future.get(5, SECONDS)` em executor single-thread → dupla barreira de timeout; ao estourar, a execução é cancelada e a exceção registrada.
+- **Superfícies de injeção (NoSQL) confirmadas no código:**
+  - `LastMile.to` e `Bonus.to`/`q` são **concatenados crus** na string de query Mongo (`query.append(", " + to)`), sem sanitização. Permite operadores Mongo arbitrários — superfície de injeção. Restrito a usuários autenticados/admin do tenant, mas não validado.
+  - **Modo custom**: `LastMile.aggregate` é um **pipeline JSON arbitrário** executado via `collection(lastmile.entity).aggregate(...)` na coleção informada pelo próprio documento → permite ler/agregar **qualquer coleção do tenant**.
+- **Cache de scripts por nó:** `compiled` é um `HashMap` de instância do `LastMileManager`. A invalidação (`compiled.remove(id)`) ocorre **apenas no nó que processou o save** — em deploy clusterizado, outros nós podem continuar usando o script antigo até recompilar.
+
+---
+
+## 9. Observabilidade e Troubleshooting
+
+### Diagnóstico
+
+- **Log de execução do scheduler:** cada `SchedulerRunner.run` grava um `SchedulerLog` (coleção `scheduler_log`) com `outputs`, `exceptions` e `millis`.
+- **Output de negócio:** o callback adiciona `"lastmile generated for N players"` aos outputs — N=0 indica alvo vazio.
+- **Notificações geradas:** verificáveis na coleção `notification` (`type=0` texto, `scope=0` privado).
+
+### Comandos úteis
+
+```
+GET /v3/lastmile/{id}                       # configuração do lastmile
+GET /v3/lastmile                            # todos os lastmiles
+GET /v3/bonus/{id}                          # configuração do bônus
+GET /v3/bonus/{id}/calculate?player=me      # preview do progresso (sem notificar)
+GET /v3/bonus/{id}/calculate?player=me&simulate=80   # preview forçando done=80
+```
+
+Consultas Mongo de investigação:
+
+```js
+db.last_mile.find({ item: "bonus_seguro_vida" })
+db.bonus.find({ _id: "bonus_seguro_vida" })
+db.scheduler.find({ entity: "last_mile", event: "notify", item: "<lastmileId>" })
+db.scheduler_log.find().sort({ _id: -1 }).limit(5)
+db.notification.find({ "player._id": "<playerId>" }).sort({ time: -1 })
+```
+
+### Erros comuns e causas
+
+| Sintoma | Causa provável |
+|---------|----------------|
+| Nenhuma notificação enviada | `to` vazio (0 jogadores); `type` ≠ 8/99; faixa `[start,ends)` não casa com `percent`; scheduler inativo ou limite diário excedido |
+| `{ "error": "..." }` no `calculate` | Exceção engolida: `goal`/`total` inválido para `exp4j`, regra sem `operation`/`period`, `bonus` inexistente |
+| `SchedulerCallback does not exist for entity X` + scheduler desativado | Scheduler criado com `entity` sem callback (ex.: `bonus`) |
+| Mensagem sem variáveis interpoladas | Variável Mustache ausente em `params`, ou script não preencheu o `params` esperado |
+| Script "não roda" após edição em cluster | Cache `compiled` não invalidado no nó atual (invalidação é local) |
+
+---
+
+## 10. Exemplos Práticos
+
+### 10.1 Mínimo funcional (LastMile sobre bônus)
+
+```json
+POST /v3/lastmile
+{
+  "title": "Incentivo Seguro de Vida 95%",
+  "type": 8,
+  "item": "bonus_seguro_vida",
+  "start": 90,
+  "ends": 100,
+  "to": "active:true",
+  "message": "{{player.name}}, faltam {{progress.gap}} vendas para você bater a meta!"
+}
+```
+
+> Sem `scheduler`, a mensagem só é produzida sob demanda via `GET /v3/bonus/bonus_seguro_vida/calculate` (não notifica). Para envio automático, adicione `scheduler`.
+
+### 10.2 Avançado (cron + script + alvo segmentado)
+
+```json
+POST /v3/lastmile
+{
+  "title": "Coach Seguro Vida",
+  "type": 8,
+  "item": "bonus_seguro_vida",
+  "start": 80,
+  "ends": 100,
+  "priority": 10,
+  "to": "extra.role:'asven',active:true",
+  "image": "https://cdn/coach.png",
+  "message": "{{player.name}}, com mais {{gap}} vendas você alcança a {{reward.title}} e ganha {{reais}} — você tem {{days}} dias (até {{ends}}).",
+  "script": "void prepare(lastmile, params){\n  int gap = new Double(params.progress.gap).intValue();\n  String reais = FormatterUtil.numberCurrency(params.reward_total, \"BRL\", \"BR\", \"¤ #,##0.00\");\n  int days = new Double((params.progress.end.getTime() - new Date().getTime())/(1000*60*60*24)).intValue();\n  params.put(\"gap\", gap);\n  params.put(\"reais\", reais);\n  params.put(\"days\", days);\n  params.put(\"ends\", DateUtil.format(params.progress.end, \"dd/MM/yyyy\"));\n}",
+  "scheduler": { "cron": "0 0 9 * * ?" }
+}
+```
+
+### 10.3 Bônus completo (motor que alimenta o LastMile)
+
+```json
+POST /v3/bonus
+{
+  "_id": "bonus_seguro_vida",
+  "title": "Bônus Seguro Vida",
+  "tags": ["vendas"],
+  "rules": [
+    {
+      "goal": "{{player.extra.meta_mes}}",
+      "operation": { "type": 1, "achievement_type": -1, "item": "vender",
+        "filters": [ { "param": "produto", "operator": 1, "value": "seg_vida" } ],
+        "sort": 0, "sub": false },
+      "period": { "type": 0, "timeAmount": 1, "timeScale": 7 }
+    }
+  ],
+  "rewards": [
+    { "title": "Faixa 100%", "start": 100, "ends": 110, "type": 0, "item": "reais", "total": "0.025 * {{global.teto_rv}}" },
+    { "title": "Faixa 110%", "start": 110, "ends": 1000, "type": 0, "item": "reais", "total": "0.03 * {{global.teto_rv}}" }
+  ],
+  "principals": []
+}
+```
+
+### 10.4 Anti-pattern (o que NÃO fazer)
+
+```json
+// ❌ LastMile com scheduler mas SEM `to`: o cron dispara e atinge ZERO jogadores
+{
+  "title": "Nunca chega a ninguém",
+  "type": 8,
+  "item": "bonus_seguro_vida",
+  "start": 90, "ends": 100,
+  "message": "...",
+  "scheduler": { "cron": "0 0 9 * * ?" }
+}
+```
+
+Outros anti-patterns:
+- **Faixas sobrepostas** entre rewards/lastmiles (`[80,100)` e `[90,110)`) → comportamento ambíguo; mantenha faixas disjuntas e `ends` exclusivo.
+- **Esperar que `calculate` premie** — ele é preview; não cria achievements persistidos.
+- **Criar scheduler com `entity:"bonus"`** — não há callback; será desativado.
+- **`type` ≠ 8/99 esperando notificação** — o callback ignora silenciosamente.
+
+---
+
+## Checklist de Configuração
+
+- [ ] O `bonus` referenciado em `LastMile.item` existe **antes** de criar o LastMile (`type=8`).
+- [ ] `LastMile.to` está preenchido — sem ele, o cron atinge **0 jogadores** (armadilha silenciosa).
+- [ ] `start < ends` e a faixa do LastMile é coerente com as faixas (`reward.start`) do bônus.
+- [ ] As variáveis usadas no `message` existem em `params` (`player`, `global`, `progress`, `reward`) ou são criadas no `script`.
+- [ ] Para `type=99` (custom): `entity` e `aggregate` preenchidos; o `aggregate` usa o token `FUNIFIER_PLAYER_IDS` e devolve documentos no formato `Progress`.
+- [ ] `scheduler.cron` válido — sem `scheduler`, não há disparo automático (apenas cálculo on-demand pelo `/v3/bonus`).
+- [ ] Não criar scheduler com `entity:"bonus"` (sem callback → desativado).
+- [ ] Em cluster: após editar `script`, lembrar que a invalidação de cache é por nó.