funifier-mcp 0.2.25 → 0.2.27

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

@@ -1,67 +1,197 @@
-# Public (Endpoints Públicos)
+# `public`
 
 **Acesso Studio:** `/studio/public`
-**API Endpoint:** `/v3/public`
+**API Endpoint (CRUD):** `/v3/public`
+**API Endpoint (execução):** `/v3/pub/{apikey}/{slug}`
+**Coleção MongoDB:** `public_endpoint`
 
-## O que é
+> Documentação de engenharia reversa baseada **exclusivamente** no código-fonte de `funifier-service`.
+> Arquivos analisados:
+> - `com/funifier/rest/v3/rest/PublicRest.java` (CRUD autenticado)
+> - `com/funifier/rest/v3/rest/PubRest.java` (execução pública)
+> - `com/funifier/engine/pub/PublicManager.java` (lógica de compilação/execução)
+> - `com/funifier/engine/pub/PublicEndpoint.java` (entidade)
+> - `com/funifier/engine/pub/PublicResponse.java` (DTO de resposta)
+> - `com/funifier/engine/integration/trigger/TriggerExpressionChecker.java` (sandbox Groovy)
+> - `com/funifier/engine/util/Entity.java` (`PUBLIC_ENDPOINT("public_endpoint", ...)`)
+> - `com/funifier/engine/app/AppManager.java` (criação programática / instalação de app)
 
-Criação e gerenciamento de endpoints públicos personalizados. Esses endpoints são ideais para integração com plataformas externas (como Circle, Zapier, Typeform), pois não exigem autenticação via token. A autenticação é feita via `apikey` incluída na URL pública no formato: `/v3/pub/{apikey}/{slug}`.
+---
 
-## Quando usar
+## 1. Visão Geral
 
-- Para receber dados de formulários externos (Typeform, Google Forms)
-- Para integrar com automações (Zapier, Make)
-- Para criar webhooks de recebimento
-- Para endpoints que não requerem autenticação por token
+O módulo `public` permite definir **endpoints HTTP dinâmicos** cuja lógica é um **script Groovy** armazenado no banco. Cada endpoint é um documento na coleção `public_endpoint`. A invocação acontece por uma URL **sem token de autenticação**: `GET|POST /v3/pub/{apikey}/{slug}`, onde `apikey` é a chave pública da gamificação (resolve o tenant) e `slug` é o `_id` do documento.
 
-## Checklist de Configuração no Studio
+**Papel arquitetural:**
 
-- [ ] Definir _id (slug) do endpoint
-- [ ] Definir título e descrição
-- [ ] Definir método HTTP (GET, POST, etc.)
-- [ ] Escrever script Java com método `public Object handle(Object payload)`
-- [ ] Ativar endpoint (active: true)
-- [ ] Testar via URL pública
+- É a superfície "serverless" da plataforma: o cliente envia um payload e o servidor executa um script Groovy arbitrário (dentro de um sandbox) que tem acesso ao `ManagerFactory` daquela gamificação — ou seja, a todos os managers (Player, Point, Achievement, Database, etc.).
+- Resolve o problema de **integração com sistemas externos que não conseguem autenticar via token** (formulários, automações tipo Zapier/Make, webhooks de terceiros) — basta conhecer a `apikey` pública e o `slug`.
+- A entidade carrega comentários internos chamando-a de *"prepared aggregate"* (ex.: `PublicEndpoint.java:40`, e o método comentado `// public String getScript(PreparedAggregate trigger)` em `PublicManager.java:109`). Isso é **legado**: o código foi adaptado da entidade `prepared_aggregate` (`Entity.PREPARED_AGGREGATE`). **Não existe nenhum pipeline de aggregate MongoDB no runtime do `public`** — o script é Groovy livre, não um aggregate preparado.
 
-## API Endpoints
+**Relação com outros módulos:**
 
-### Listar Public Endpoints
-**Método:** GET
-**Endpoint:** `/v3/database/public_endpoint`
+- Compartilha a mesma técnica de sandbox de script com `trigger` e `scheduler`: o checker `TriggerExpressionChecker` (pacote `engine.integration.trigger`) é reutilizado aqui.
+- A criação pode ser disparada pela instalação de um **App/pacote** (`AppManager.funifierCreateCustomEndpoint`), além do CRUD direto.
+- Em runtime, o script pode tocar qualquer coleção/manager via `manager.getXxxManager()`.
 
-**Exemplo de Resposta:**
-```json
-[
-  {
-    "_id": "recebe_email",
-    "title": "Recebe Email",
-    "description": "Recebe email e registra na colecao email__c",
-    "active": true,
-    "method": "POST",
-    "script": "public Object handle(Object payload) { payload._id = payload.email; manager.getJongoConnection().getCollection(\"email__c\").save(payload); Map<String, Object> response = new HashMap<>(); response.put(\"email\", payload.email); return response; }",
-    "sample": "{ \"email\": \"user@email.com\" }",
-    "extra": {}
-  }
-]
+---
+
+## 2. Arquitetura e Fluxos
+
+### 2.1 Pipeline principal — execução (`/v3/pub/{apikey}/{slug}`)
+
+Sequência real (`PubRest.executePublicEndpoint` → `PublicManager.run` → `executor`):
+
+```
+[Trigger HTTP]  → PubRest.handleGet / handlePost
+[Montagem payload]
+   GET  → uriInfo.getQueryParameters() → payload.put(key, values.get(0))   // apenas o 1º valor de cada query param
+   POST → body (JSON desserializado em HashMap<String,Object>)
+[Resolução tenant] → FrontController.getInstance(apikey).getManagerFactory()
+[Lookup]        → PublicManager.find(slug)                 // findOne({_id: slug})
+[Validação 1]   → endpoint == null      → HTTP 404 (PublicResponse 404)
+[Validação 2]   → !endpoint.active      → HTTP 403 (PublicResponse 403)
+[Validação 3]   → !method.equalsIgnoreCase(endpoint.method) → HTTP 406 (PublicResponse statusCode=405)
+[Execução]      → PublicManager.run(endpoint, payload, manager)
+[Resposta]      → Response.status(result.statusCode).entity(result.payload)
+                + header X-Response-Time: <ms>
+```
+
+Lógica interna de `run()`:
+
+```
+se endpoint.updated == null:
+    save(endpoint)                          # rede de segurança p/ docs inseridos fora do save()
+
+lastCompilation = dates[endpoint._id]
+clazz           = compiled[endpoint._id]
+
+se clazz == null OU lastCompilation == null OU lastCompilation.before(endpoint.updated):
+    script = getScript(endpoint.script)     # injeta imports + wrapper class
+    clazz  = compile(script)                # SecureASTCustomizer + TriggerExpressionChecker
+    compiled[endpoint._id] = clazz
+    dates[endpoint._id]    = agora
+
+result = executor(clazz, endpoint, payload, manager)   # roda handle(payload) com timeout
+retorna PublicResponse(200, "OK", result)
+
+# em qualquer exceção (compilação OU execução):
+retorna PublicResponse(500, "Erro ao compilar ou executar o script", ex.getMessage())
 ```
 
-### Criar Public Endpoint
-**Método:** POST
-**Endpoint:** `/v3/public`
+Características:
+
+- **Síncrono.** A requisição HTTP fica bloqueada até o script terminar (ou estourar timeout).
+- **Sem transação.** Não há transação MongoDB envolvendo o que o script faz. Cada operação do script no banco é independente.
+- **Dois timeouts** (ver seção 5): `@TimedInterrupt(5s)` no wrapper Groovy + `Future.get(timeout)` no executor (default 10s, ou `endpoint.timeout`).
+
+### Fluxo de execução — `/v3/pub`
+
+```mermaid
+flowchart TD
+    A["Cliente: GET/POST /v3/pub/{apikey}/{slug}"] --> B[PubRest.executePublicEndpoint]
+    B --> C[FrontController.getInstance apikey]
+    C --> D["PublicManager.find(slug)"]
+    D --> E{endpoint == null?}
+    E -- sim --> E1["HTTP 404 — PublicResponse(404)"]
+    E -- não --> F{active?}
+    F -- não --> F1["HTTP 403 — PublicResponse(403)"]
+    F -- sim --> G{method confere?}
+    G -- não --> G1["HTTP 406 — PublicResponse statusCode=405"]
+    G -- sim --> H["PublicManager.run()"]
+    H --> I{cache de classe válido?}
+    I -- não --> J["getScript + compile + cacheia"]
+    I -- sim --> K[reusa classe compilada]
+    J --> L["executor: handle(payload) — single-thread + timeout"]
+    K --> L
+    L --> M{exceção / timeout?}
+    M -- sim --> M1["HTTP 500 — corpo = ex.getMessage()"]
+    M -- não --> N["HTTP 200 — corpo = retorno de handle()"]
+```
+
+### Interação entre componentes
+
+```mermaid
+sequenceDiagram
+    participant C as Cliente
+    participant R as PubRest
+    participant M as PublicManager
+    participant G as Groovy (FunifierPublicEndpoint)
+    C->>R: POST /v3/pub/{apikey}/{slug} + payload
+    R->>M: find(slug)
+    M-->>R: PublicEndpoint (ou null)
+    R->>M: run(endpoint, payload, manager)
+    M->>M: compile + cache (se dates[_id] < updated)
+    M->>G: setManager(manager)
+    M->>G: handle(payload)  [executor single-thread, timeout]
+    G-->>M: result
+    M-->>R: PublicResponse(200, "OK", result)
+    R-->>C: HTTP 200 + result   (somente o payload)
+```
+
+### 2.2 Pipeline secundário — CRUD (`/v3/public`)
+
+`PublicRest` expõe o gerenciamento autenticado (ver seção 4). É um CRUD fino sobre `PublicManager`:
+
+```
+GET    /v3/public/{id}  → PublicManager.find(id)   → 200 + JSON (campos null omitidos)
+POST   /v3/public       → PublicManager.save(obj)  → 201 + JSON do objeto salvo
+DELETE /v3/public/{id}  → PublicManager.delete(id) → 204 No Content
+```
+
+---
+
+## 3. Estrutura dos Objetos
+
+### 3.1 `PublicEndpoint` — documento raiz (coleção `public_endpoint`)
+
+Anotações: `@Data @NoArgsConstructor @AllArgsConstructor @JsonIgnoreProperties(ignoreUnknown=true)`. **Todos os campos são `public`** (acesso direto, sem getters/setters obrigatórios no script).
+
+| Campo         | Tipo                  | Padrão        | Obrigatório | Descrição |
+| ------------- | --------------------- | ------------- | ----------- | --------- |
+| `_id`         | String                | auto          | não         | Slug usado na URL pública (`/v3/pub/{apikey}/{_id}`). Se vazio/`null` no `save()`, gerado via `Guid.shortTimeMillis()`. |
+| `apikey`      | String                | `null`        | não         | "apikey da gamificação". **Não é usado na execução** — o tenant vem da `apikey` da URL. Campo informativo/legado. |
+| `title`       | String                | `null`        | não         | Nome amigável (uso interno/Studio). |
+| `description` | String                | `null`        | não         | Descrição interna do propósito. |
+| `active`      | boolean               | `false`       | não*        | Se `false`, a execução retorna **403**. Como `boolean` primitivo, ausência no JSON ⇒ `false` ⇒ endpoint **desativado por padrão**. |
+| `method`      | String                | `"POST"`      | não         | Método HTTP aceito. Comparado via `equalsIgnoreCase`. Valores usados: `"POST"` ou `"GET"`. |
+| `script`      | String                | `null`        | sim (de fato)| Corpo do script Groovy. Deve definir o método `handle(payload)`. |
+| `timeout`     | Long                  | `null`        | não         | Timeout de execução **em segundos**. `null` ou `<= 0` ⇒ usa **10s**. |
+| `sample`      | String                | `null`        | não         | Exemplo de payload esperado (documentação; não usado em runtime). |
+| `updated`     | Date                  | auto          | não         | Setado para `new Date()` a cada `save()`. **Chave da invalidação de cache** de compilação. |
+| `extra`       | Map\<String,Object\>  | `{}`          | não         | Campo livre. **Atenção:** é um campo literal chamado `extra`, **não** um catch-all do Jackson (não há `@JsonAnySetter`). Só é populado se o JSON tiver a chave `"extra"`. |
 
-### Executar Public Endpoint
-**Método:** POST (ou conforme configurado)
-**Endpoint:** `/v3/pub/{apikey}/{slug}`
-**Descrição:** Executa o endpoint público. Não requer token de autenticação.
+\* Tecnicamente nenhum campo tem validação de obrigatoriedade no código; `script` é obrigatório na prática (sem ele não há `handle` para invocar).
 
-## Script Runtime Environment (Wrapper Class)
+**Campos computados / não persistidos pelo cliente:**
+- `updated` é sempre sobrescrito pelo servidor no `save()` — qualquer valor enviado pelo cliente é ignorado.
 
-O script que você escreve no Studio **não é standalone** — ele é inserido dentro de uma classe Java wrapper gerada automaticamente pelo Funifier. Isso tem implicações importantes:
+**Campos aceitos e silenciosamente ignorados:**
+- `apikey` — aceito no schema, **não tem efeito** no fluxo de execução (`PubRest` resolve o tenant pela `apikey` da URL).
+- `sample` — persistido, mas nunca lido pelo runtime.
+- Qualquer chave JSON desconhecida — descartada por `@JsonIgnoreProperties(ignoreUnknown=true)` (**não** vai para `extra`).
 
-### Estrutura do Wrapper
+**Geração de `_id`:** `Guid.shortTimeMillis()` ⇒ `encode(System.currentTimeMillis(), Guid.range)` — string curta derivada do timestamp. Só ocorre quando `_id` é vazio/`null`.
 
-```java
-// --- Imports automáticos (NÃO escreva import no seu script) ---
+### 3.2 `PublicResponse` — DTO de resposta
+
+| Campo        | Tipo   | Descrição |
+| ------------ | ------ | --------- |
+| `statusCode` | int    | Código lógico (200, 404, 403, 405, 500). **Nem sempre igual ao status HTTP** (ver seção 4). |
+| `message`    | String | Mensagem resumida. **Descartada no sucesso** (ver abaixo). |
+| `payload`    | Object | Dado de retorno. No sucesso, é o valor retornado por `handle()`. |
+
+> **Assimetria crítica do corpo da resposta** (`PubRest`):
+> - **Sucesso** → `entity(result.payload)`: o corpo é **apenas** o retorno de `handle()`. `statusCode` e `message` do `PublicResponse` são **descartados**.
+> - **Erro de pré-checagem** (404/403/406) → `entity(new PublicResponse(...))`: o corpo é o **objeto `PublicResponse` completo** em JSON.
+> - **Erro no script** (capturado dentro de `run()`) → `run()` devolve `PublicResponse(500, "Erro...", ex.getMessage())` e `PubRest` ainda faz `entity(result.payload)` ⇒ o corpo é a **string crua da mensagem de exceção**, com HTTP 500.
+
+### 3.3 Wrapper de execução (`FunifierPublicEndpoint`)
+
+O `script` do usuário **não roda standalone**: `getScript()` o injeta dentro de uma classe Groovy gerada. Estrutura literal montada (`PublicManager.getScript`, linhas 110-207):
+
+```groovy
+// imports automáticos (NÃO escreva 'import' no seu script)
 import groovyx.net.http.*
 import static groovyx.net.http.Method.*
 import static groovyx.net.http.ContentType.*
@@ -77,34 +207,49 @@ import org.apache.http.client.methods.HttpPost
 import org.apache.http.impl.client.HttpClientBuilder
 import org.apache.commons.io.IOUtils
 import java.lang.StringBuffer
-import java.io.*
+// resize de imagens
+import net.coobird.thumbnailator.Thumbnails
+import java.io.InputStream
+import java.io.ByteArrayInputStream
+import java.io.ByteArrayOutputStream
+import java.io.BufferedReader
+import java.io.IOException
 import com.fasterxml.jackson.core.JsonProcessingException
-// Unirest (HTTP client)
+// Unirest
 import com.mashape.unirest.http.HttpResponse
 import com.mashape.unirest.http.JsonNode
+import com.mashape.unirest.http.ObjectMapper
 import com.mashape.unirest.http.Unirest
 import com.mashape.unirest.http.exceptions.UnirestException
 import com.mashape.unirest.request.GetRequest
 import com.mashape.unirest.request.HttpRequestWithBody
-// Mail (Simple Java Mail)
+// Mail
 import org.simplejavamail.email.Email
 import org.simplejavamail.email.EmailBuilder
 import org.simplejavamail.mailer.MailerBuilder
-// Funifier entities
-import com.funifier.engine.action.*
-import com.funifier.engine.achievement.*
-import com.funifier.engine.lottery.*
-import com.funifier.engine.challenge.*
-import com.funifier.engine.constant.*
-import com.funifier.engine.guid.*
-import com.funifier.engine.level.*
+// Entidades Funifier
+import com.funifier.engine.action.Action
+import com.funifier.engine.action.ActionLog
+import com.funifier.engine.achievement.Achievement
+import com.funifier.engine.lottery.Lottery
+import com.funifier.engine.lottery.LotteryTicket
+import com.funifier.engine.challenge.Challenge
+import com.funifier.engine.challenge.ChallengeRule
+import com.funifier.engine.challenge.ChallengeRuleFilter
+import com.funifier.engine.challenge.Requirement
+import com.funifier.engine.challenge.RewardPoint
+import com.funifier.engine.constant.Operator
+import com.funifier.engine.constant.TimeScale
+import com.funifier.engine.guid.Guid
+import com.funifier.engine.level.Level
 import com.funifier.engine.notify.*
-import com.funifier.engine.player.*
-import com.funifier.engine.point.*
-import com.funifier.engine.team.*
-import com.funifier.engine.catalog.*
-import com.funifier.engine.mail.*
-// Funifier utils
+import com.funifier.engine.player.Player
+import com.funifier.engine.point.Point
+import com.funifier.engine.team.Team
+import com.funifier.engine.catalog.Catalog
+import com.funifier.engine.catalog.CatalogItem
+import com.funifier.engine.mail.FunifierMail
+// Utils Funifier
 import com.funifier.engine.util.DateUtil
 import com.funifier.engine.util.JsonUtil
 import com.funifier.engine.util.HttpUtil
@@ -112,142 +257,327 @@ import com.funifier.engine.util.HttpClientFunifier
 import com.funifier.engine.util.MustacheUtils
 import com.funifier.controller.ManagerFactory
 
-@TimedInterrupt(value = 5L, unit = TimeUnit.SECONDS)
-class FunifierPublicEndpoint {
+@TimedInterrupt(value = 5L, unit = TimeUnit.SECONDS)class FunifierPublicEndpoint {
     ManagerFactory manager = null;
-    void setManager(ManagerFactory c) { manager = c; }
+    void setManager(ManagerFactory c){ manager = c; };
 
-    // --- SEU SCRIPT É INSERIDO AQUI ---
+    // <<< AQUI ENTRA O CONTEÚDO DE endpoint.script >>>
 }
 ```
 
-### Regras para escrever scripts
-
-1. **NÃO use `import`** — todos os imports necessários já estão no wrapper. Se precisar de uma classe não importada, use o nome completo (fully qualified): `com.example.MinhaClasse`
-2. **O método principal é `public Object handle(Object payload)`** — este é o entry point
-3. **`manager` está disponível** como campo da classe (ManagerFactory)
-4. **Timeout padrão de 10 segundos** — o executor limita a execução. **Pode ser customizado** via campo `timeout` (em segundos) no objeto do endpoint — ver seção "Campo timeout" abaixo. Nota: o `@TimedInterrupt(5s)` no wrapper Groovy é uma segunda camada de proteção
-5. **Groovy, não Java puro** — o script roda em Groovy, então features como GString, closures e tipagem dinâmica funcionam
-6. **Cuidado com `$` em GStrings** — operadores MongoDB (`$set`, `$inc`) e strings com `$` são interpretados como variáveis Groovy. Use `String.valueOf((char)0x24)` para escapar:
-   ```groovy
-   def d = String.valueOf((char)0x24)  // = "$"
-   def setCmd = '{"' + d + 'set": {"name": "Novo Nome"}}'
-   ```
-7. **Use apenas ASCII em comentários** — caracteres UTF-8 especiais (em dash `—`, acentos em comentários) podem causar erros de parse no Groovy
-8. **`instanceof` é bloqueado** pelo SecureASTCustomizer — use `getClass().getName()` ou try/catch
-9. **NÃO use `groovy.json.JsonSlurper`** para parsear JSON que será retornado na response — o `LazyMap` do JsonSlurper causa `ClassCastException: [B incompatible with [C` quando o Funifier tenta serializar. Use `JsonUtil.fromJsonToMap(jsonString)` em vez de `slurper.parseText(jsonString)`
-10. **Player.extra é público** — acesse direto com `player.extra`, não com `player.getExtra()` (método não existe)
-11. **Para salvar player:** `manager.getPlayerManager().findById(id)` → modifique → `manager.getPlayerManager().insert(player)` (upsert)
-
-### Campo `timeout` (Customizar timeout do script)
-
-O timeout padrão de **10 segundos** (confirmado no source: `PublicManager.java` linha 255) pode ser insuficiente para endpoints que fazem chamadas HTTP externas (ex: verificar token OAuth, chamar APIs de IA, download de imagens). O campo `timeout` permite aumentar esse limite.
-
-**Campo:** `timeout` (Long, em **segundos**)
-**Padrão:** `null` (usa 10 segundos — source: `PublicManager.java:255`)
-**Nota:** Este campo **não aparece no formulário do Studio** — só pode ser configurado via API.
-
-```bash
-# Exemplo: definir timeout de 30 segundos para o endpoint google_login
-curl -X POST "https://service2.funifier.com/v3/public" \
-  -H "Authorization: Basic <token>" \
-  -H "Content-Type: application/json" \
-  -d '{"_id": "google_login", "timeout": 30}'
-```
-
-**Este campo também existe em Triggers e Schedulers** — mesma estrutura, mesma API (`/v3/trigger`, `/v3/scheduler`).
-
-**Mecanismo de execução (Java):**
-```java
-// O executor usa Executors.newSingleThreadExecutor() com Future.get(timeout, TimeUnit.SECONDS)
-long timeout = 10; // padrão
-if (endpoint.timeout != null && endpoint.timeout > 0) {
-    timeout = endpoint.timeout;
-}
-Object result = future.get(timeout, TimeUnit.SECONDS);
-```
-
-**Nota:** O `@TimedInterrupt(value = 5L, unit = TimeUnit.SECONDS)` no wrapper Groovy é uma segunda camada de proteção. O timeout do executor (campo `timeout`) é a camada principal e deve ser >= ao TimedInterrupt para funcionar corretamente.
-
-**Estrutura da classe PublicEndpoint (Java):**
-```java
-public class PublicEndpoint {
-    public String _id;          // slug (URL identifier)
-    public String apikey;       // gamification apikey
-    public String title;        // friendly name
-    public String description;  // internal description
-    public boolean active;      // enabled/disabled
-    public String method;       // "POST" or "GET" (default: "POST")
-    public String script;       // Groovy script body
-    public Long timeout;        // timeout in SECONDS (null = default 10s)
-    public String sample;       // example payload
-    public Date updated;        // last update timestamp
-    public Map<String, Object> extra; // extra metadata
+Observações fiéis ao código:
+- O método de entrada **deve se chamar `handle`** e receber 1 argumento: `executor()` chama `obj.invokeMethod("handle", new Object[]{ payload })`.
+- O campo `manager` (`ManagerFactory`) é injetado via `setManager` antes do `handle`. É o acesso a toda a plataforma.
+- A anotação `@TimedInterrupt(...)` é concatenada **sem espaço** antes de `class` (`...SECONDS)class FunifierPublicEndpoint`) — reproduzido aqui exatamente como o código gera.
+
+---
+
+## 4. Endpoints
+
+### `GET /v3/public/{id}` — buscar endpoint (CRUD)
+
+| Aspecto      | Detalhe |
+| ------------ | ------- |
+| Finalidade   | Recuperar um `PublicEndpoint` por `_id`. |
+| Autenticação | Header `Authorization` (resolvido por `AuthBean` → Basic `apiKey:secretKey`, Bearer JWT, Studio, Account). |
+| Resposta     | `200` + JSON do endpoint, **com campos `null` omitidos** (`JsonUtil.toJsonRemoveNullFields`). |
+
+**Comportamento real:** se o `_id` não existir, `findOne(...).as(PublicEndpoint.class)` retorna `null` e a resposta é **`200` com corpo literal `null`** (não há 404 neste endpoint de CRUD).
+
+### `POST /v3/public` — criar/atualizar endpoint (upsert)
+
+| Aspecto              | Detalhe |
+| -------------------- | ------- |
+| Finalidade           | Criar ou atualizar um `PublicEndpoint`. |
+| Autenticação         | Header `Authorization` (idem acima). |
+| Full replace ou patch| **Full replace.** `col.save(obj)` substitui o documento inteiro pelo objeto recebido. Campos omitidos voltam ao default da classe (ex.: `method` → `"POST"`, `active` → `false`). |
+
+**Comportamento real:**
+- `_id` vazio/`null` ⇒ gerado automaticamente (`Guid.shortTimeMillis`).
+- `updated` ⇒ sempre setado para o instante do save (valor do cliente ignorado).
+- Efeito colateral: remove `compiled[_id]` do cache do nó atual (força recompilar no próximo `run`).
+- Resposta `201 Created` + JSON do objeto salvo (campos null omitidos), incluindo `_id` e `updated` resultantes.
+
+**Exemplo de request:**
+```json
+{
+  "_id": "recebe-email",
+  "title": "Recebe email",
+  "active": true,
+  "method": "POST",
+  "timeout": 20,
+  "script": "def handle(payload){ payload._id = payload.email; manager.getJongoConnection().getCollection('email__c').save(payload); return ['ok': true] }"
 }
 ```
 
-**Quando usar timeout customizado:**
-- Endpoints que fazem chamadas HTTP externas (OAuth, APIs externas)
-- Endpoints com BCrypt hashing (custo computacional)
-- Endpoints que fazem múltiplas operações em sequência
-- **Recomendação:** 20-30s para endpoints com chamadas externas
+### `DELETE /v3/public/{id}` — remover endpoint (CRUD)
+
+| Aspecto      | Detalhe |
+| ------------ | ------- |
+| Finalidade   | Remover o documento e limpar o cache de compilação. |
+| Autenticação | Header `Authorization`. |
+| Resposta     | `204 No Content`. |
+
+**Comportamento real:** `remove({_id:#}, id)` é idempotente (sem erro se não existir). Limpa `compiled[id]` **e** `dates[id]` do nó atual.
+
+### `GET /v3/pub/{apikey}/{slug}` — execução pública (GET)
+
+| Aspecto      | Detalhe |
+| ------------ | ------- |
+| Finalidade   | Executar o script do endpoint cujo `_id == slug`. |
+| Autenticação | **Nenhuma** (sem token/secret). A `apikey` da URL é a chave pública da gamificação e seleciona o tenant. |
+| Payload      | Query params ⇒ `Map`. **Apenas o primeiro valor** de cada parâmetro é mantido. |
+
+### `POST /v3/pub/{apikey}/{slug}` — execução pública (POST)
+
+| Aspecto      | Detalhe |
+| ------------ | ------- |
+| Finalidade   | Idem GET, recebendo corpo JSON. |
+| Autenticação | **Nenhuma** (apenas a `apikey` pública da URL). |
+| Payload      | Corpo JSON desserializado em `HashMap<String,Object>`. **Deve ser um objeto JSON** (array/escalar falha na desserialização). |
+
+**Comportamento real (ambos):**
+
+| Condição                              | Status HTTP | Corpo |
+| ------------------------------------- | ----------- | ----- |
+| `slug` não encontrado                 | `404`       | `PublicResponse(404, "Endpoint '...' não encontrado", null)` |
+| `active == false`                     | `403`       | `PublicResponse(403, "Este endpoint está desativado", null)` |
+| Método HTTP não confere               | **`406`**   | `PublicResponse(405, "Método HTTP '...' não permitido...", null)` |
+| Sucesso                               | `200`       | **somente** o retorno de `handle()` (serializado em JSON) |
+| Exceção no script (compilar/executar) | `500`       | **string** da mensagem de exceção |
+
+> **Inconsistência confirmada no código:** na checagem de método, `Response.status(Response.Status.NOT_ACCEPTABLE)` ⇒ **HTTP 406**, mas o corpo `PublicResponse.statusCode = 405`. A intenção do desenvolvedor era `405 Method Not Allowed`; o status HTTP efetivo é `406`.
 
-### Atualizar Public Endpoint via API
+Todas as respostas de `/v3/pub` incluem o header **`X-Response-Time: <ms>`**.
 
+---
+
+## 5. Regras de Negócio
+
+Regras presentes no código que **não** estão expressas no schema:
+
+1. **Endpoint desativado por padrão.** `active` é `boolean` primitivo (default `false`). Criar um endpoint sem `"active": true` resulta em **403** na execução.
+2. **Método default `POST`.** Omitir `method` no save grava `"POST"` (inicializador do campo). Chamar via GET nesse caso ⇒ **406**.
+3. **Comparação de método case-insensitive** (`equalsIgnoreCase`): `get`/`GET`/`Get` são equivalentes. Se `method` ficar `null` no documento (ex.: gravado fora do `save()` com `method:null`), a checagem `endpoint.method.equalsIgnoreCase(...)` lança **NPE** (não tratada → 500 do container).
+4. **Cache de compilação por nó + coerência via `updated`.** Cada nó do cluster mantém `compiled[_id]` e `dates[_id]` em memória. Recompila quando `clazz == null || dates[_id] == null || dates[_id].before(endpoint.updated)`. Como `save()` atualiza `updated`, qualquer nó que ainda tenha a classe antiga recompila no próximo `run` (o nó que salvou também já limpou o cache local).
+5. **Auto-save em `run()` se `updated == null`.** Endpoints inseridos por fora (ex.: via `/v3/database/public_endpoint` sem passar pelo `save()`) recebem `updated` na primeira execução.
+6. **Dois timeouts independentes:**
+   - `@TimedInterrupt(value = 5L, unit = SECONDS)` — transformação AST do Groovy; interrompe loops/métodos longos em **5s** (hardcoded no wrapper).
+   - `Future.get(timeout, SECONDS)` no `executor` — **10s** por padrão, ou `endpoint.timeout` se `> 0`. É a parede de wall-clock da chamada a `handle()`.
+   - **Inversão:** o `TimedInterrupt` (5s) é menor que o default do executor (10s). Aumentar `timeout` **não** afeta o limite de 5s do `TimedInterrupt` para código que cai sob suas verificações (loops/métodos). Os dois mecanismos coexistem.
+7. **Multi-tenant pela `apikey` da URL.** `FrontController.getInstance(apikey)` isola o `ManagerFactory` (e o MongoDB) daquela gamificação. O `slug` é buscado dentro desse tenant.
+8. **Sem transação / consistência eventual.** O que o script faz no banco é aplicado operação a operação; não há rollback automático em caso de timeout no meio da execução.
+
+---
+
+## 6. Comportamentos Automáticos
+
+| Comportamento | Trigger | Impacto | Persistência |
+| ------------- | ------- | ------- | ------------ |
+| Geração de `_id` | `save()` com `_id` vazio/null | Cria slug via `Guid.shortTimeMillis()` | Sim (documento) |
+| Carimbo de `updated` | Todo `save()` | `updated = new Date()` (sobrescreve cliente) | Sim |
+| Invalidação de cache local | `save()` | `compiled.remove(_id)` (não remove `dates[_id]`) | Não (memória do nó) |
+| Limpeza de cache | `delete()` | `compiled.remove(id)` + `dates.remove(id)` | Não (memória do nó) |
+| Recompilação cross-cluster | `run()` em nó com classe defasada | Recompila se `dates[_id] < updated` | Não (memória do nó) |
+| Auto-save | `run()` com `updated == null` | Persiste `updated` antes de executar | Sim |
+| Criação via instalação de App | `AppManager.funifierCreateCustomEndpoint` | Cria/atualiza endpoint a partir do pacote | Sim |
+
+### Criação automática na instalação de um App/pacote
+
+`AppManager` (linhas ~1131-1162) lê `funifierCreates.customEndpoints[]` na config do app:
+
+```mermaid
+flowchart TD
+    A["App install: funifierCreates.customEndpoints[]"] --> B{elemento é JSONObject?}
+    B -- sim --> C["funifierCreateCustomEndpoint(doc)"]
+    C --> D["PublicManager.save() — upsert em public_endpoint"]
+    B -- "não, é String id" --> E{categoria do doc == backend?}
+    E -- sim --> F["[skip] sem payload"]
+    E -- não --> G["[skip] categoria não-java"]
 ```
-POST /v3/public
-Authorization: Basic <base64(apiKey + ":")>
-Content-Type: application/json
 
-{
-    "_id": "slug_do_endpoint",
-    "title": "Titulo",
-    "description": "Descricao",
-    "active": true,
-    "method": "POST",
-    "script": "public Object handle(Object payload) { ... }",
-    "sample": "{}",
-    "extra": {}
-}
+`funifierCreateCustomEndpoint(JSONObject)` simplesmente faz `manager.getPublicManager().save(JsonUtil.fromJson(payload, PublicEndpoint.class))`. O bloco de código comentado logo abaixo (`AppManager.java:447-458`) mostra a **implementação anterior**, que fazia `Unirest.post(FUNIFIER_SERVER + "/v3/public")` — hoje substituída por chamada direta ao manager.
+
+---
+
+## 7. Suportado vs NÃO Suportado
+
+### ✅ Suportado
+
+- CRUD autenticado de endpoints (`GET/POST/DELETE /v3/public`).
+- Execução pública sem token (`GET/POST /v3/pub/{apikey}/{slug}`).
+- Script Groovy com acesso ao `ManagerFactory` (todos os managers da gamificação).
+- Imports pré-carregados de HTTP (Unirest, Apache HttpClient, groovyx.net.http), JSON (`groovy.json`, `JsonUtil`), e-mail (`simplejavamail`, `FunifierMail`), resize de imagem (Thumbnailator) e entidades Funifier.
+- Timeout configurável por endpoint (`timeout`, em segundos).
+- Cache de classe compilada por nó, com invalidação automática por `updated`.
+- Criação programática e via instalação de App.
+
+### ❌ NÃO Suportado / Limitações confirmadas no código
+
+- **Sem pipeline de aggregate.** Apesar dos comentários "prepared aggregate", **não há** montagem de aggregate MongoDB — é Groovy livre. Legado da entidade `prepared_aggregate`.
+- **`apikey` (campo da entidade) ignorado na execução** — o tenant vem da URL.
+- **`sample` ignorado em runtime** — apenas documentação.
+- **`extra` não é catch-all** — só captura a chave JSON literal `"extra"`; chaves desconhecidas são descartadas.
+- **GET multivalorado não suportado** — apenas o 1º valor de cada query param entra no payload.
+- **Sem 404 no CRUD** — `GET /v3/public/{id}` inexistente retorna `200` com corpo `null`.
+- **Status HTTP de método incorreto** — retorna `406` onde o corpo declara `405`.
+- **Sem listagem nativa** — `PublicRest` não expõe `GET /v3/public` (lista). Para listar, usa-se `/v3/database/public_endpoint`.
+- **Sem versionamento, sem histórico, sem rate limiting** no módulo.
+- **`message` do `PublicResponse` perdida no sucesso** — o cliente nunca vê `"OK"`.
+
+### ⚠️ Bug confirmado — vazamento de threads no `executor()`
+
+`PublicManager.executor()` cria `Executors.newSingleThreadExecutor()` a **cada** execução. O `executor.shutdownNow()` só é chamado no bloco `catch` (timeout/erro). **No caminho de sucesso o `shutdown` não é chamado explicitamente.** Como `newSingleThreadExecutor()` usa threads **não-daemon**, o worker permanece vivo até ser reclamado — o `FinalizableDelegatedExecutorService` retornado faz `shutdown()` apenas na finalização pelo GC. Na prática: o encerramento é **deferido e dependente do GC**, e threads/executors **acumulam sob carga** (reclamação lenta e frágil, presa a um hook do JVM). (Trecho relevante: `executor()`, linhas ~252-273.)
+
+---
+
+## 8. Segurança e Permissões
+
+**Autenticação:**
+- **CRUD (`/v3/public`):** exige header `Authorization`, resolvido por `AuthBean.getApiKey()` (suporta `Basic apiKey:secretKey`, `Bearer <jwt>`, `Studio <token>`, `Account ...`). O `PublicRest` em si **não faz checagem de role/permissão adicional** — o isolamento é dado pela `apikey` resolvida (tenant). Pela convenção Funifier, operações de escrita usam Basic com `apiKey:secretKey`.
+- **Execução (`/v3/pub`):** **sem autenticação**. Conhecer a `apikey` pública + o `slug` é suficiente. Por isso, scripts públicos **não devem** expor dados sensíveis nem executar operações destrutivas sem validação própria dentro do `handle`.
+
+**Isolamento por tenant:** `FrontController.getInstance(apikey)` garante que `find`/`run` operem apenas na gamificação da `apikey`.
+
+**Sandbox do script** (`compile()` + `TriggerExpressionChecker`):
+
+1. `SecureASTCustomizer` com **whitelist de tokens** (operadores permitidos):
+   `=`, `+`, `-`, `*`, `/`, `%`, `**`, `++`, `+=`, `--`, `==`, `!=`, `<`, `<=`, `>`, `>=`, `||`, `||=`, `&&`, `&&=`, `[`, `]`.
+   Operadores **fora dessa lista são rejeitados na compilação** — por exemplo `instanceof` (`KEYWORD_INSTANCEOF` não está na whitelist) não compila.
+2. `TriggerExpressionChecker` (blacklist):
+   - Bloqueia expressões cujo **tipo** seja `System`, `ProcessBuilder`, `File`, `GroovyShell` ou `GroovyObject`.
+   - Bloqueia expressões cujo **texto** contenha `.execute`, `.getDB`, `.getMongo` ou `.dropDatabase`.
+
+**Superfícies de risco confirmadas no código:**
+- O sandbox é **baseado em blacklist textual/por-tipo** — é contornável (ex.: reflexão, nomes construídos dinamicamente, classes não listadas). Não é uma sandbox forte.
+- O script tem acesso total ao `ManagerFactory` ⇒ pode ler/escrever qualquer coleção do tenant. Combinado com a execução **sem token**, qualquer um que conheça `apikey` + `slug` aciona essa lógica.
+- `endpoint.script` é compilado e executado — quem tem permissão de **escrita** no CRUD tem, na prática, **execução de código** no servidor (RCE dentro dos limites do sandbox).
+
+---
+
+## 9. Observabilidade e Troubleshooting
+
+**Diagnóstico rápido:**
+- O header `X-Response-Time` aparece em toda resposta de `/v3/pub` — útil para medir latência do script.
+- Erros de instalação de App via pacote são impressos em stdout: `[funifier:public] criado: ...` / `Falha public: <msg>` (`AppManager`).
+
+**Listar / inspecionar endpoints:**
+```
+GET /v3/database/public_endpoint        # lista todos (via database genérico)
+GET /v3/public/{id}                      # busca um (200 + null se não existir)
 ```
 
-O mesmo endpoint serve para criar e atualizar (upsert por `_id`)
+**Erros comuns e causas:**
 
-### Bibliotecas HTTP disponíveis
+| Sintoma | Causa provável |
+| ------- | -------------- |
+| `403 "Este endpoint está desativado"` | `active != true` no documento. |
+| `406` ao chamar | `method` do endpoint difere do verbo usado (corpo dirá `405`). |
+| `404 "Endpoint '...' não encontrado"` | `slug` ≠ `_id`, ou criado em outro tenant (`apikey` da URL errada). |
+| `500` com string de exceção | Erro de **compilação** (token bloqueado, classe na blacklist) **ou** de **execução** do `handle`. A string é `ex.getMessage()`. |
+| `500` por `TimeoutException` | `handle` excedeu `timeout` (default 10s) — note também o limite de 5s do `@TimedInterrupt`. |
+| Mudança no script "não pega" | Cache de classe; só invalida via `save()` (que atualiza `updated`). Editar o doc direto no Mongo sem mudar `updated` mantém a classe antiga em cache. |
+| `GET /v3/public/{id}` retornando `null` com 200 | Comportamento esperado — não há 404 no CRUD. |
 
-| Biblioteca | Uso recomendado |
-|-----------|----------------|
-| **Unirest** | HTTP client mais simples — `Unirest.post(url).header(...).body(...).asJson()` |
-| **Apache HttpClient** | Alternativa mais verbosa |
-| **groovyx.net.http** | HTTP Builder para Groovy |
-| **HttpUtil / HttpClientFunifier** | Utilitários Funifier |
+**O que verificar quando "não funciona":**
+1. `active == true`?
+2. `method` bate com o verbo da chamada?
+3. `script` define `def handle(payload) { ... }`?
+4. A `apikey` da URL é a da gamificação correta?
+5. O erro 500 traz a mensagem de exceção no corpo — leia-a.
 
-### Exemplo usando Unirest
+### Notas operacionais (observadas em runtime — **não** provadas pelo código deste módulo)
 
-```groovy
-public Object handle(Object payload) {
-    def response = Unirest.post("https://api.external.com/endpoint")
-        .header("Content-Type", "application/json")
-        .header("Authorization", "Bearer my-token")
-        .body(JsonUtil.toJson(payload))
-        .asString()
-
-    def result = new groovy.json.JsonSlurper().parseText(response.getBody())
-    return result
+> As notas abaixo vêm de experiência operacional com o motor Groovy/Jackson e **não** são deriváveis dos arquivos do módulo `public`. Trate-as como heurísticas, não como contrato:
+> - `groovy.json.JsonSlurper` pode produzir estruturas (`LazyMap`) que falham na serialização da resposta — preferir `JsonUtil.fromJsonToMap(...)`.
+> - `$` dentro de GStrings é interpretado como variável Groovy; comandos Mongo (`$set`, `$inc`) precisam ser escapados/concatenados.
+> - Caracteres não-ASCII em comentários do script podem causar erro de parse.
+> - Acesso a propriedades de entidades (ex.: `player.extra`) depende da definição da classe correspondente — confirmar no código da entidade.
+
+---
+
+## 10. Exemplos Práticos
+
+### 10.1 Mínimo funcional — eco do payload
+
+```json
+POST /v3/public
+{
+  "_id": "echo",
+  "active": true,
+  "method": "POST",
+  "script": "def handle(payload){ return payload }"
 }
 ```
+Chamada:
+```
+POST /v3/pub/{apikey}/echo
+{ "nome": "Ana" }
+→ 200  { "nome": "Ana" }     # corpo = retorno de handle()
+```
 
-> ⚠️ **Triggers e Schedulers usam a mesma estrutura de wrapper** com os mesmos imports pré-disponíveis. A diferença é apenas o método principal: triggers usam `void trigger(event, entity, player, database)` e schedulers usam `void execute()`.
-
-## Boas Práticas
+### 10.2 Avançado — gravar em coleção + usar managers + timeout
 
-- Não expor dados sensíveis em endpoints públicos
-- Não realizar operações críticas sem validação adicional
-- Validar payload recebido no script Java
+```json
+POST /v3/public
+{
+  "_id": "recebe-lead",
+  "title": "Recebe lead de formulário externo",
+  "active": true,
+  "method": "POST",
+  "timeout": 20,
+  "sample": "{ \"email\": \"user@x.com\", \"nome\": \"User\" }",
+  "script": "def handle(payload){ payload._id = payload.email; manager.getJongoConnection().getCollection('lead__c').save(payload); def resp = [:]; resp.ok = true; resp.id = payload.email; return resp }"
+}
+```
+Chamada (sem token):
+```
+POST /v3/pub/{apikey}/recebe-lead
+{ "email": "ana@x.com", "nome": "Ana" }
+→ 200  { "ok": true, "id": "ana@x.com" }
+```
 
-## Validações e Testes
+### 10.3 Anti-padrão — o que NÃO fazer
 
-- [ ] Endpoint aparece na lista
-- [ ] URL pública é acessível sem token
-- [ ] Script processa payload corretamente
-- [ ] Resposta é retornada conforme esperado
+```json
+{
+  "_id": "ruim",
+  "script": "def handle(payload){ for(i in 0..1000000000){ }; return 'fim' }"
+}
+```
+Problemas:
+- Sem `"active": true` ⇒ retorna **403** (esquecimento mais comum).
+- Loop longo ⇒ interrompido pelo `@TimedInterrupt` (5s) ⇒ **500**.
+- Usar `import` dentro do script ⇒ erro de compilação (imports já estão no wrapper).
+- Nomear o método diferente de `handle` ⇒ `invokeMethod("handle", ...)` falha ⇒ **500**.
+- Usar `instanceof`, `System.exit`, `.execute()`, `.getDB()` ⇒ bloqueado pelo sandbox ⇒ **500**.
+- Retornar estrutura de `JsonSlurper` que não serializa ⇒ erro na resposta (ver Notas operacionais).
+
+---
+
+## Checklist de Configuração
+
+- [ ] `_id` (slug) definido — ou deixe vazio para gerar automaticamente.
+- [ ] `"active": true` — **sem isso, todas as chamadas retornam 403** (default é `false`).
+- [ ] `method` bate com o verbo que o cliente vai usar (`"POST"` é o default).
+- [ ] `script` define **`def handle(payload) { ... }`** (o nome `handle` é obrigatório).
+- [ ] **Não** usar `import` no script — todos os imports já estão no wrapper.
+- [ ] `timeout` (segundos) ajustado se o script faz I/O externo (default 10s; lembre do limite de 5s do `@TimedInterrupt`).
+- [ ] Tenant correto: a `apikey` da URL `/v3/pub/{apikey}/{slug}` é a da gamificação onde o endpoint foi salvo.
+- [ ] Não retornar dados sensíveis — a execução é **pública e sem token**.
+- [ ] Validar o `payload` dentro do `handle` (não confie na entrada).
+- [ ] Armadilha silenciosa: omitir `method`/`active` no `POST /v3/public` reseta esses campos (full replace) — `method` volta a `"POST"`, `active` volta a `false`.
+- [ ] Após editar via Mongo direto, garanta que `updated` mude — senão o cache de classe não invalida.
+
+---
+
+## REGRAS DE OURO (resumo do comportamento real)
+
+1. `/v3/public` = CRUD autenticado; `/v3/pub/{apikey}/{slug}` = execução pública sem token.
+2. Execução é **síncrona**, com dois timeouts (5s TimedInterrupt + 10s/`timeout` executor).
+3. No **sucesso**, o corpo é só o retorno de `handle()`; em **erro de script**, é a string da exceção (500); em **pré-checagem**, é um `PublicResponse` JSON.
+4. Método errado ⇒ HTTP **406** (corpo diz 405). Inativo ⇒ 403. Inexistente ⇒ 404.
+5. Cache de classe por nó, invalidado por `updated`.
+6. Sandbox é blacklist (contornável); script tem acesso total ao tenant via `manager`.
+7. **Bug conhecido:** vazamento de thread no caminho de sucesso do `executor()`.
+8. Não existe aggregate pipeline — "prepared aggregate" é só legado de nomenclatura.