funifier-mcp 0.2.26 → 0.2.27

package/datasource-funifier-docs/knowledge/modules/kpi-formulas.md

@@ -1,23 +1,418 @@
-# KPI Formulas (Fórmulas de KPI)
+# `kpi-formulas`
 
-## O que é
+**Acesso Studio:** `não confirmado no código backend` — o router da base de conhecimento (`index.md`) cita o módulo como "KPI Formulas / Fórmulas e indicadores", mas não há rota `/studio/...` nem nome "kpi-formulas" no `funifier-service`. O termo é uma abstração de documentação.
+**API Endpoints:**
+- `/v3/prepared/aggregate` — CRUD das fórmulas parametrizadas (`PreparedRest`)
+- `/v3/find/{id}` — **execução** de uma fórmula parametrizada (`FindRest`)
+- `/v3/challenge/prepared` — listagem das fórmulas de KPI usadas em rankings (`ChallengeRest.findAllPrepared`)
+**Coleções MongoDB:** `prepared_aggregate` e `challenge_rule_prepared` (auxiliares: `expire`, `find_cache_<id>__c`)
 
-Configuração de regras e cálculos avançados para avaliar ações dos jogadores. Permite criar fórmulas customizadas para avaliação de desempenho e resultados, indo além das regras padrão dos outros módulos.
+> **Nota de engenharia reversa.** Não existe no `funifier-service` nenhuma classe, coleção ou rota chamada `kpi-formulas`/`KpiFormula`. A documentação anterior (genérica) foi descartada. O que a plataforma realmente implementa sob o conceito de "fórmulas/KPIs derivados de dados" são **dois subsistemas independentes** (`prepared_aggregate` e `challenge_rule_prepared`), ambos baseados em comandos de _aggregate_ do MongoDB salvos no banco. Existe ainda um terceiro artefato — `dashboard.KPI` / coleção `kpi` — que é **código legado morto** (ver §7).
 
-## Quando usar
+---
 
-- Para cálculos avançados de desempenho que os módulos padrão não atendem
-- Para fórmulas considerando múltiplos critérios (quantidade, valor, tempo)
-- Para regras avançadas de rankings
-- **Importante:** usar com critério, apenas quando recursos padrão não atendem
+## 1. Visão Geral
 
-## Checklist de Configuração
+"KPI Formulas" é, no código, uma **família de comandos de agregação MongoDB persistidos** que calculam valores derivados (indicadores, totais, médias, rankings) a partir dos dados da gamificação — sem que a lógica do pipeline fique acoplada à entidade que o consome.
+
+São **dois mecanismos distintos, com coleções, rotas e sintaxe de parâmetros diferentes**:
+
+| Subsistema | Coleção | Entidade | Config (REST) | Execução |
+|---|---|---|---|---|
+| **Prepared Aggregate / Find** | `prepared_aggregate` | `PreparedAggregate` (`com.funifier.engine.find`) | `/v3/prepared/aggregate` | `/v3/find/{id}` |
+| **KPI Rule (ranking)** | `challenge_rule_prepared` | `ChallengeRulePrepared` (`com.funifier.engine.challenge`) | `/v3/database/challenge_rule_prepared` + `GET /v3/challenge/prepared` | embutida nos motores de ranking/desafio |
+
+Papel arquitetural:
+
+- **Prepared Aggregate** (`engine/find`) é o motor genérico de "consultas salvas": uma agregação parametrizável (`$param:`), com expressões de data Funifier (`$date`), pré-script Groovy opcional (sandbox), cache de resultado e encadeamento (`parent`). É configurada em `/v3/prepared/aggregate` e **executada** em `/v3/find/{id}`. É o recurso mais próximo de "criar um campo calculado/KPI a partir de qualquer coleção".
+- **KPI Rule** (`challenge_rule_prepared`) é uma fórmula nomeada e **reutilizável de ranking**: um pipeline que retorna `_id`, `total` e `max` por jogador/equipe. É exatamente o artefato que o próprio código chama de "KPI" (`Operation.TYPE_PREPARED_KPI = 10`). É referenciada por desafios (`ChallengeRule.prepared`), leaderboards (`LeaderBoard_V2.operation`), competições e crownings.
+
+Relação com outros módulos (confirmada no código):
+
+- `challenge` — `AchievementManager.fireAction` copia `entity` + `aggregate` de um `ChallengeRulePrepared` para dentro da `ChallengeRule` quando `rule.prepared` está preenchido (`AchievementManager.java:295-299`).
+- `leaderboard` — `LeaderBoardManager.findLiveLeadersAggregate` usa `TYPE_PREPARED_KPI` para montar o ranking (`LeaderBoardManager.java:332`).
+- `competition` / `crowning` — `CompetitionManager` e `CrowningManager` usam o mesmo `TYPE_PREPARED_KPI` (`CrowningManager.java:712`).
+- `database` / `studio-page` — fórmulas `prepared_aggregate` são tipicamente disparadas pelo frontend/Studio via HTTP em `/v3/find/{id}`.
+
+Problema que resolve: centralizar pipelines de agregação complexos (que de outra forma seriam reescritos em cada leaderboard/desafio/página) em objetos reutilizáveis, parametrizáveis e cacheáveis.
+
+---
+
+## 2. Arquitetura e Fluxos
+
+### 2.1 Classes envolvidas
+
+| Classe | Papel |
+|---|---|
+| `com.funifier.engine.find.PreparedAggregate` | Entidade raiz do subsistema Prepared/Find (coleção `prepared_aggregate`) |
+| `com.funifier.engine.find.PreparedManager` | Compila/cacheia scripts Groovy, salva/exclui, executa o pré-script; **não** executa a agregação Mongo (isso é feito no `FindRest`) |
+| `com.funifier.rest.v3.rest.PreparedRest` | REST de configuração (`/v3/prepared`) |
+| `com.funifier.rest.v3.rest.FindRest` | REST de **execução** (`/v3/find`) — monta e roda o pipeline, com cache e paginação |
+| `com.funifier.engine.util.FunifierMarshaller` | Substitui `$param:xxx` e converte `$date` (keyword → epoch millis) |
+| `com.funifier.engine.challenge.ChallengeRulePrepared` | Entidade raiz da fórmula de KPI de ranking (coleção `challenge_rule_prepared`) |
+| `com.funifier.engine.crowning.Operation` | Define `TYPE_PREPARED_KPI = 10` e o campo `prepared` (id de `ChallengeRulePrepared`) |
+| `LeaderBoardManager` / `CompetitionManager` / `CrowningManager` / `AchievementManager` | Consumidores da KPI Rule |
+| `com.funifier.engine.crowning.Expire` | Controle de expiração de cache do Prepared/Find (coleção `expire`) |
+
+Não há `Repository`/`Dao` dedicado: a manipulação MongoDB é feita via `Jongo` diretamente dentro dos managers/rest.
+
+### 2.2 Pipeline de execução — `prepared_aggregate` (`POST /v3/find/{id}`)
+
+Sequência real (`FindRest.run` → `findLiveAggregate` / `findCachedAggregate`):
+
+1. **[Trigger]** `FindRest.run(id, params, Range, strict)`
+2. **[Contexto]** `authBean.getPlayerFromTokenIfExist()` → `context.player` (jogador do token)
+3. **[Load]** `PreparedManager.find(id)` — se não existir, retorna **401** com `{"message":"prepared aggregate dont exists"}`
+4. **[Parent]** se `obj.parent` preenchido e o parent não tiver outro parent (encadeamento de **um único nível**), o pipeline do parent é gerado primeiro (com ou sem cache) e vira a base
+5. **[Cache?]** se `obj.cache` preenchido → `findCachedAggregate`; senão → `findLiveAggregate`
+6. **[Script]** dentro de `findLiveAggregate`, se `obj.script` existir, roda o pré-script Groovy via `PreparedManager.run(..., "script")` (`context.item = obj`)
+7. **[Parse]** `JsonUtil.fromJson(obj.aggregate, List.class)` → lista de estágios
+8. **[Substituição]** cada estágio passa por `FunifierMarshaller.toStringWithParams(stage, params)` → resolve `$param:xxx` e `$date`
+9. **[Run]** `jongo.getCollection(obj.collection).aggregate(...).options(allowDiskUse(true))` + `.and(...)` para os demais estágios
+10. **[Paginação]** `PaginationUtil.getPageResultThrowsException(a, range, 0, 100)` — **100 por página** por padrão; `?strict=true` usa serialização Gson
+
+```mermaid
+flowchart TD
+    A["POST /v3/find/{id}<br/>+ params (body)"] --> B["PreparedManager.find(id)"]
+    B -->|null| E["401 prepared aggregate dont exists"]
+    B -->|ok| P{"obj.parent?"}
+    P -->|sim| PC["gera aggregate do parent<br/>(1 nível) como base"]
+    P -->|não| C
+    PC --> C{"obj.cache?"}
+    C -->|sim| CACHE["findCachedAggregate<br/>$out find_cache_id__c"]
+    C -->|não| LIVE["findLiveAggregate"]
+    LIVE --> S{"obj.script?"}
+    S -->|sim| GR["PreparedManager.run (Groovy pré-script)"]
+    S -->|não| MAR
+    GR --> MAR["FunifierMarshaller.toStringWithParams<br/>($param: / $date)"]
+    MAR --> AGG["collection.aggregate(...) allowDiskUse"]
+    CACHE --> PAG["PaginationUtil (Range, default 100)"]
+    AGG --> PAG
+    PAG --> R["resposta paginada"]
+```
+
+### 2.3 Pipeline de KPI de ranking — `challenge_rule_prepared` (`TYPE_PREPARED_KPI`)
+
+Quando um leaderboard/competição/crowning tem `operation.type == TYPE_PREPARED_KPI` e `operation.prepared` (id de um `ChallengeRulePrepared`):
+
+1. Carrega `ChallengeRulePrepared` por id na coleção `challenge_rule_prepared`
+2. Substitui **placeholders literais** no `aggregate` via `String.replaceAll`:
+   - `FUNIFIER_PERIOD_START_TIME` → início do período (`currentRange[0].getTime()`)
+   - `FUNIFIER_PERIOD_END_TIME` → fim do período
+   - `FUNIFIER_TRIGGER_TIME` → `new Date().getTime()`
+   - `FUNIFIER_PLAYER_IDS` → JSON dos ids (usado em crowning; **comentado** no leaderboard)
+3. Roda o pipeline sobre `jongo.getCollection(prepared.entity)` — o pipeline deve produzir `_id`, `total`, `max`
+4. O motor de ranking acrescenta seus próprios estágios (lookup de team/player, `$facet` + `$unwind includeArrayIndex` para calcular `position`, ordenação por `total`/`max`)
+
+```mermaid
+sequenceDiagram
+    participant LB as LeaderBoardManager / CrowningManager
+    participant DB as Mongo (challenge_rule_prepared)
+    participant E as Mongo (prepared.entity)
+    LB->>DB: findOne {_id: operation.prepared}
+    DB-->>LB: ChallengeRulePrepared (entity, aggregate)
+    LB->>LB: replaceAll FUNIFIER_PERIOD_START_TIME / END / TRIGGER_TIME / PLAYER_IDS
+    LB->>E: aggregate(pipeline) → {_id, total, max}
+    E-->>LB: resultados por jogador/equipe
+    LB->>LB: + $lookup team/player, $facet position, $sort
+    LB-->>LB: ranking final
+```
+
+### 2.4 Pré-script Groovy (`PreparedManager.run`)
+
+- `getScript(src)` envolve o script do usuário numa classe Groovy `FunifierTrigger` com imports utilitários (Unirest, mail, thumbnailator, entidades Funifier, `ManagerFactory`), `@TimedInterrupt(5s)`, setters `setContext`/`setManager` e `println` redirecionado para uma lista de output.
+- `compile(script)` usa `SecureASTCustomizer` + `TriggerExpressionChecker` + whitelist de tokens (aritméticos, comparação, lógicos, colchetes).
+- `executor(...)` roda num `Executors.newSingleThreadExecutor()` com timeout = `prepared.timeout` (default **5s**), invocando `setContext`, `setManager`, `prepare(aggregate, params)`, `addAllOutput(outputs)`.
+- Classes compiladas ficam em cache (`Map compiled`); recompila apenas se `updated > lastCompilation`.
+
+> Síncrono. A execução da agregação em `/v3/find` é bloqueante; o pré-script Groovy roda em outra thread mas é aguardado (com timeout).
+
+---
+
+## 3. Estrutura dos Objetos
+
+### 3.1 `PreparedAggregate` — coleção `prepared_aggregate`
+
+| Campo | Tipo | Padrão | Obrigatório | Descrição |
+|---|---|---|---|---|
+| `_id` | String | auto (`Guid.shortTimeMillis()`) | — | Gerado no `save` se vazio |
+| `title` | String | — | não | Rótulo |
+| `description` | String | — | não | Descrição |
+| `parent` | String | — | não | `_id` de outro `prepared_aggregate` cujo resultado serve de base (encadeamento de **1 nível**) |
+| `collection` | String | — | sim (se não usa `parent`) | Coleção onde o `aggregate` roda (ex.: `player`, `action_log`) |
+| `aggregate` | String (JSON array) | — | sim | Comando de agregação; aceita `$param:xxx` e `$date` |
+| `script` | String (Groovy) | — | não | Pré-script executado antes de montar o pipeline |
+| `timeout` | Long (segundos) | `5` | não | Timeout do pré-script Groovy |
+| `cache` | String (keyword) | — | não | Liga cache do resultado; expressão de TTL (ex.: `30m`, `+3h`) |
+| `cache_before_find` | String (Groovy) | — | não | Script rodado antes de localizar o cache |
+| `updated` | Date | auto | — | Definido no `save`; usado para invalidar o cache de classe compilada |
+| `extra` | Map | `{}` | não | Campos livres |
+
+Campos comentados/legados no código: `cache_before_save` (declarado e comentado em `PreparedAggregate.java:54`).
+
+### 3.2 `ChallengeRulePrepared` — coleção `challenge_rule_prepared`
+
+| Campo | Tipo | Obrigatório | Descrição |
+|---|---|---|---|
+| `_id` | String | — | Id |
+| `title` | String | não | Rótulo |
+| `description` | String | não | Descrição |
+| `action` | String | não | Ação à qual o comando se aplica (usado na avaliação de desafio) |
+| `entity` | String | sim | Coleção onde o `aggregate` é executado |
+| `aggregate` | String (JSON array) | sim | Pipeline que deve retornar `_id`, `total`, `max`; aceita placeholders `FUNIFIER_*` |
+
+> Diferença crítica de sintaxe: `ChallengeRulePrepared.aggregate` **não** usa `$param:` nem `$date`. Usa substituição literal de string (`FUNIFIER_PERIOD_START_TIME`, `FUNIFIER_PERIOD_END_TIME`, `FUNIFIER_TRIGGER_TIME`, `FUNIFIER_PLAYER_IDS`) feita por quem consome (leaderboard/crowning). Misturar as duas sintaxes não funciona.
+
+### 3.3 `Operation` (crowning) — tipos de fórmula
+
+`com.funifier.engine.crowning.Operation` define o "tipo de fórmula" de um ranking:
+
+| Constante | Valor | Significado |
+|---|---|---|
+| `TYPE_COUNT_ACTIONS` | 1 | Conta action logs |
+| `TYPE_SUM_ATTRIBUTE` | 2 | Soma um atributo de action log |
+| `TYPE_SUM_ACHIEVEMENTS` | 3 | Soma achievements |
+| `TYPE_AVG_ATTRIBUTE` | 4 | Média de atributo |
+| `TYPE_PREPARED_KPI` | 10 | **Usa um `challenge_rule_prepared`** (campo `operation.prepared` = id) |
+
+Campos relevantes de `Operation`: `type`, `achievement_type`, `item`, `attribute`, `filters`, `sort`, `sub`, `subAttribute`, `prepared`.
+
+---
+
+## 4. Endpoints
+
+### `POST /v3/prepared/aggregate`
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Cria **ou atualiza** (upsert por `_id`) um `prepared_aggregate` |
+| Autenticação | Bearer token |
+| Full replace ou patch | **Full replace** (`save` faz `col.save(obj)`) |
+
+**Comportamento real:** valida (compila) `script` e `cache_before_find` antes de salvar; se a compilação falhar retorna `{"status":"ERROR","message":...}` mas ainda com HTTP **201**. **Não valida** o campo `aggregate`. Define `updated = now`, gera `_id` se vazio, e limpa o cache de classe compilada + cache de resultado (`deleteCache`).
+
+```json
+{ "prepared": { "_id": "kpi_vendas", "...": "..." }, "status": "OK" }
+```
 
-- [ ] Definir a fórmula de cálculo
-- [ ] Vincular aos desafios ou rankings relevantes
-- [ ] Testar com dados reais
+### `GET /v3/prepared/aggregate/{id}`
+Retorna o objeto. Sem corpo se não existir (`null`).
 
-## Validações e Testes
+### `DELETE /v3/prepared/aggregate/{id}`
+Remove por id (`204 NO_CONTENT`), limpa caches de classe e de resultado.
+
+### `DELETE /v3/prepared/aggregate?q=<mongo>`
+Remove em massa os que casarem com `{q}` (query Mongo crua). **Engole todas as exceções silenciosamente** (`catch(Exception e){}`) e sempre retorna **200**, mesmo em erro de sintaxe da query.
+
+### `POST /v3/prepared/aggregate/{id}/analyze`
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | **Preview** da substituição de parâmetros + execução do pré-script |
+| **NÃO executa a agregação** | As linhas que rodariam `log.aggregate(...)` estão **comentadas** (`PreparedRest.java:142-143,166,181-183`) |
+
+**Comportamento real:** parseia `aggregate`, roda o pré-script Groovy (se houver) e devolve:
+- `aggregate_step_2`: pipeline parseado (sem params)
+- `aggregate_step_3`: pipeline com `$param:`/`$date` já substituídos
+- `script_exceptions`, `script_outputs`
+Header `X-Response-Time`. Se o objeto não existir → **401** com `{"message":"prepared aggregate dont exists"}`. **O nome "analyze" engana**: para obter dados reais use `/v3/find/{id}`.
+
+### `POST /v3/find/{id}`
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | **Executa** a fórmula e retorna os dados |
+| Body | `HashMap` de params (chave = nome usado em `$param:nome`) |
+| Query params | `strict` (`true` → Gson) |
+| Headers | `Range` (paginação, ex.: `items=0-100`) |
+
+**Comportamento real:** injeta `context.player` (do token), resolve `parent`, aplica cache (`$out`) se `cache` definido, substitui params, roda a agregação em `obj.collection`, pagina (default 100). Objeto inexistente → **401**.
+
+**Path/Query params:**
+
+| Param | Tipo | Descrição |
+|---|---|---|
+| `id` | path | `_id` do `prepared_aggregate` |
+| `strict` | query | `true` força serialização estrita (Gson) |
+| `Range` | header | janela de paginação |
+
+**Exemplo:**
+```bash
+POST /v3/find/kpi_vendas?strict=true
+Range: items=0-50
+{ "player": "ana", "start": "-30d" }
+```
+
+### `GET /v3/find/{id}/params`
+Retorna a lista de nomes de parâmetros (`$param:xxx`) encontrados **apenas** no campo `aggregate` por varredura de string. **Ignora** params usados só no `script`.
+```json
+["player","start"]
+```
+
+### `GET /v3/challenge/prepared`
+Lista todos os `challenge_rule_prepared` (`ChallengeRest.findAllPrepared`). O CRUD individual dessas regras é feito pelo endpoint genérico `/v3/database/challenge_rule_prepared`.
+
+---
+
+## 5. Regras de Negócio
+
+Regras presentes no código e não óbvias pelo schema:
+
+- **Duas sintaxes de parâmetro incompatíveis** (ver §3.2): `prepared_aggregate` usa `$param:xxx` + `$date` (resolvidos por `FunifierMarshaller.toStringWithParams`); `challenge_rule_prepared` usa `FUNIFIER_*` via `String.replaceAll`.
+- **Expressões de data Funifier** (`$date`): em `prepared_aggregate`, qualquer `{"$date":"<keyword>"}` é convertido para epoch millis por `DateUtil.fromKeyword` (ex.: `-5M`, `+3h`, `-30d`). Datas literais ficam inalteradas.
+- **Contrato da KPI de ranking**: o `aggregate` de um `challenge_rule_prepared` **deve** produzir documentos com `_id` (id do jogador/equipe), `total` e `max`. Os motores de ranking dependem disso para `$group`/`$sort`.
+- **Chave de cache inclui os params**: o registro `expire` é localizado por `{extra.item: _id, extra.params: params}` — params diferentes geram caches diferentes.
+- **TTL de cache**: derivado da keyword em `cache`; se ausente/indefinido, default **+3h** (`FindRest.java:142`).
+- **Encadeamento `parent` de 1 nível só**: o parent é processado apenas se ele próprio não tiver `parent` (`FindRest.java:81`).
+- **Timeout do Groovy**: `prepared.timeout` (default 5s) limita o pré-script; estouro vira exceção coletada, não falha HTTP.
+- **Multi-tenant**: tudo opera sobre a conexão Jongo da organização resolvida pela API key (`FrontController.getInstance(authBean.getApiKey())`). Coleções de cache (`find_cache_<id>__c`) são por organização.
+- **`save` valida script mas não o pipeline**: um `aggregate` sintaticamente inválido só falha na execução (`/v3/find`), nunca na criação.
+
+---
+
+## 6. Comportamentos Automáticos
+
+| Comportamento | Trigger | Impacto | Persistência |
+|---|---|---|---|
+| Geração de `_id` | `save` com `_id` vazio | `Guid.shortTimeMillis()` | sim (`prepared_aggregate`) |
+| `updated = now` | todo `save` | invalida cache de classe compilada | sim |
+| Invalidação de cache | `save`/`delete` | remove classe compilada + dropa `find_cache_*__c` + remove `expire` | sim |
+| Materialização de cache | `/v3/find` com `cache` | roda `$out` para `find_cache_<expireId>__c` e cria/atualiza `expire` | sim |
+| **Polling de cache** | após `$out` | espera o cache materializar: **até 30 tentativas × `Thread.sleep(1000)`** (≈30s bloqueantes) | — |
+| Cache de classe Groovy | 1ª execução | compila e guarda em `Map compiled`; reusa enquanto `updated` não mudar | em memória (por nó) |
+| Cópia de `entity`/`aggregate` | `fireAction` com `rule.prepared` | resolve o `challenge_rule_prepared` e injeta na rule | runtime |
+
+```mermaid
+flowchart LR
+    F["/v3/find/{id} (cache on)"] --> X{"expire válido?"}
+    X -->|sim| READ["lê find_cache_id__c"]
+    X -->|não/expirado| OUT["roda pipeline + $out find_cache_id__c"]
+    OUT --> POLL["poll: até 30x sleep 1s<br/>até count > 0"]
+    POLL --> READ
+    READ --> RESP["resposta paginada"]
+```
+
+---
+
+## 7. Suportado vs NÃO Suportado
+
+### ✅ Suportado
+- CRUD de `prepared_aggregate` (`/v3/prepared/aggregate`) com upsert por `_id`.
+- Execução parametrizada com paginação (`/v3/find/{id}`), `$param:` e `$date`.
+- Cache de resultado com TTL por keyword e chave por params.
+- Pré-script Groovy sandboxed (timeout, whitelist de tokens).
+- Encadeamento `parent` (1 nível).
+- Introspecção de parâmetros (`GET /v3/find/{id}/params`).
+- KPI de ranking via `challenge_rule_prepared` + `Operation.TYPE_PREPARED_KPI` em leaderboard/competição/crowning/desafio.
+
+### ❌ NÃO Suportado / armadilhas confirmadas no código
+- **`/v3/prepared/aggregate/{id}/analyze` NÃO executa a agregação** — só faz preview da substituição de params (código de execução comentado).
+- **`GET /v3/find/{id}/params` ignora params do `script`** — só varre o campo `aggregate`.
+- **`DELETE /v3/prepared/aggregate?q=` engole erros** e sempre retorna 200 (falha silenciosa).
+- **Encadeamento `parent` > 1 nível**: ignorado (parent com parent não é processado).
+- **Validação do `aggregate` no save**: inexistente.
+- **Coleção `kpi` / `DashboardManager` / `dashboard.KPI` é LEGADO MORTO**: `calculateKpi`/`calculateSeries`/`addKPI` só são invocados por `DashboardTest.testKpi()`. Nenhuma rota REST os expõe. A coleção `kpi` é referenciada **apenas** em `DashboardManager.java`.
+- **CRUD direto de `kpi` via `/v3/database/kpi` é parcialmente bloqueado**: o nome `kpi` tem 3 caracteres e `DatabaseRest` exige `collection.length() > 3` para `POST`, `PUT`, `GET /{id}` e bulk — logo só `GET` lista, `DELETE` por query, `aggregate`, `drop` e `count` funcionam para `kpi`.
+- **Campo `cache_before_save`**: declarado e **comentado** em `PreparedAggregate.java:54` (script de cache simétrico ao `cache_before_find`, sem implementação ativa).
+
+---
+
+## 8. Segurança e Permissões
+
+- **Autenticação**: Bearer token; a organização é resolvida via `authBean.getApiKey()`.
+- **Isolamento por organização**: todas as operações usam a conexão Jongo da org; coleções de cache `find_cache_*__c` são por org.
+- **Sandbox Groovy**: `SecureASTCustomizer` com whitelist de tokens (sem chamadas arbitrárias livres além do permitido), `TriggerExpressionChecker` customizado e timeout de 5s por `@TimedInterrupt` + executor. Mitiga (mas não elimina) risco de scripts maliciosos.
+- **Superfícies de injeção** (documentadas sem omissão):
+  - `DELETE /v3/prepared/aggregate?q=` injeta `q` cru dentro de `{ ... }` enviado ao Mongo (`find("{" + q + "}")`). Um `q` malformado/abusivo é aceito; erros são silenciados.
+  - O campo `aggregate` é um pipeline cru fornecido pelo cliente, executado em qualquer `collection` informada — quem tem escopo de escrita pode ler qualquer coleção da org via `/v3/find`.
+- **Comportamento inseguro a notar**: a falha silenciosa do delete em massa pode mascarar exclusões parciais ou nenhuma exclusão.
+
+---
+
+## 9. Observabilidade e Troubleshooting
+
+Diagnóstico:
+- **A fórmula existe?** `GET /v3/prepared/aggregate/{id}` (retorna `null` se não).
+- **Quais params ela exige?** `GET /v3/find/{id}/params`.
+- **A substituição está correta?** `POST /v3/prepared/aggregate/{id}/analyze` (veja `aggregate_step_3`) — lembrando que **não** roda a query.
+- **Resultado real:** `POST /v3/find/{id}` com o corpo de params.
+- **KPIs de ranking:** `GET /v3/challenge/prepared` lista as fórmulas; confira se o `aggregate` retorna `_id`, `total`, `max`.
+
+Erros comuns e causas:
+- `401 prepared aggregate dont exists` → id errado ou objeto em outra organização.
+- Resultado vazio mas sem erro → pré-script falhou (veja `script_exceptions` no `analyze`) ou `$param:` não enviado.
+- Dados "presos" / desatualizados → cache ativo; ajuste/remova `cache` ou aguarde o TTL. O cache vive em `find_cache_<id>__c` e o controle em `expire`.
+- Ranking `TYPE_PREPARED_KPI` vazio → `operation.prepared` aponta para id inexistente em `challenge_rule_prepared`, ou o pipeline não emitiu `_id`/`total`/`max`, ou um placeholder `FUNIFIER_*` não foi substituído.
+
+Queries úteis (via `/v3/database`):
+```bash
+GET  /v3/database/prepared_aggregate
+GET  /v3/database/challenge_rule_prepared
+GET  /v3/database/expire?q=extra.item:'kpi_vendas'
+GET  /v3/database/find_cache_<expireId>__c
+```
+
+---
+
+## 10. Exemplos Práticos
+
+### Exemplo mínimo — `prepared_aggregate` (total de logs de uma ação)
+```json
+POST /v3/prepared/aggregate
+{
+  "_id": "total_checkins",
+  "title": "Total de check-ins",
+  "collection": "action_log",
+  "aggregate": "[{\"$match\":{\"actionId\":\"checkin\"}},{\"$count\":\"total\"}]"
+}
+```
+Execução: `POST /v3/find/total_checkins` (corpo `{}`).
+
+### Exemplo avançado — params + `$date` + cache
+```json
+POST /v3/prepared/aggregate
+{
+  "_id": "vendas_jogador",
+  "title": "Vendas por jogador no período",
+  "collection": "action_log",
+  "cache": "30m",
+  "aggregate": "[{\"$match\":{\"actionId\":\"sell\",\"userId\":\"$param:player\",\"time\":{\"$gte\":{\"$date\":\"$param:start\"}}}},{\"$group\":{\"_id\":\"$userId\",\"total\":{\"$sum\":\"$attributes.price\"}}}]"
+}
+```
+Execução:
+```bash
+POST /v3/find/vendas_jogador
+Range: items=0-100
+{ "player": "ana", "start": "-30d" }
+```
+
+### Exemplo — KPI de ranking (`challenge_rule_prepared`)
+```json
+POST /v3/database/challenge_rule_prepared
+{
+  "_id": "kpi_volume_vendas",
+  "title": "Volume de vendas (ranking)",
+  "entity": "action_log",
+  "aggregate": "[{\"$match\":{\"actionId\":\"sell\",\"time\":{\"$gte\":{\"$date\":FUNIFIER_PERIOD_START_TIME},\"$lte\":{\"$date\":FUNIFIER_PERIOD_END_TIME}}}},{\"$group\":{\"_id\":\"$userId\",\"total\":{\"$sum\":\"$attributes.price\"},\"max\":{\"$max\":\"$attributes.price\"}}}]"
+}
+```
+Depois referencie em um leaderboard com `operation.type = 10` e `operation.prepared = "kpi_volume_vendas"`.
+
+### Anti-pattern (o que NÃO fazer)
+- ❌ Usar `$param:player` dentro de um `challenge_rule_prepared` — ele só entende `FUNIFIER_*`; o `$param:` ficaria literal e quebraria a query.
+- ❌ Confiar no `analyze` para validar dados — ele não roda a agregação. Use `/v3/find`.
+- ❌ Criar a fórmula na coleção legada `kpi` esperando cálculo automático — `DashboardManager` é código morto e `/v3/database/kpi` rejeita `POST`/`PUT` (guard de 3 caracteres).
+- ❌ Esquecer `max`/`total`/`_id` no pipeline de KPI de ranking — o ranking sai vazio sem erro explícito.
+
+---
+
+## Checklist de Configuração
 
-- [ ] Fórmula retorna resultados esperados
-- [ ] Cálculo funciona com diferentes combinações de dados
+- [ ] **Escolheu o subsistema certo**: `prepared_aggregate` (relatórios/campos calculados via `/v3/find`) **vs** `challenge_rule_prepared` (KPI de ranking).
+- [ ] `collection` (em `prepared_aggregate`) ou `entity` (em `challenge_rule_prepared`) preenchido e existente.
+- [ ] Sintaxe de parâmetro correta: `$param:`/`$date` para Prepared; `FUNIFIER_*` para KPI Rule.
+- [ ] KPI de ranking: pipeline retorna `_id`, `total` e `max`.
+- [ ] Se usar `cache`: TTL adequado (armadilha — resultado "preso" até expirar; polling de até ~30s na primeira materialização).
+- [ ] Pré-script Groovy cabe no timeout (`timeout`, default 5s) e usa só tokens permitidos.
+- [ ] `parent`, se usado, aponta para um `prepared_aggregate` **sem** parent (encadeamento de 1 nível).
+- [ ] Não use a coleção legada `kpi` — sem efeito de cálculo e com CRUD bloqueado.