funifier-mcp 0.2.25 → 0.2.27

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

@@ -1,34 +1,333 @@
-# Action (Ação)
+# `action`
 
-**Acesso Studio:** `/studio/action`
+**Acesso Studio:** `/studio/action` _(convenção de UI; não verificável no `funifier-service`)_
 **API Endpoint:** `/v3/action`
+**Endpoint Legado:** `/2.0.0/action` (`com.funifier.rest.engine.ActionRest`)
+**Endpoint System:** `/v3/system/action` (gamificação de sistema)
+**Coleção MongoDB:** `action`
 
-## O que é
+> Documento de engenharia reversa baseado **exclusivamente** no código de `funifier-service` (commit `830037e`). Cobre o **cadastro/registro de ações** (entidade `Action`, coleção `action`). O registro de execuções (firing) — entidade `ActionLog`, coleção `action_log`, endpoints `/v3/action/log*` — está documentado em `action-log.md`. Os dois compartilham o mesmo controller (`ActionRest`).
 
-Cadastro das diferentes ações que os jogadores podem realizar na gamificação. As ações são a base da estratégia de engajamento — definem o que pode ser feito e servem para disparar desafios e recompensas. É possível adicionar atributos extras para detalhar o contexto (ex: `produto`, `valor` numa ação de venda).
+---
 
-## Quando usar
+## 1. Visão Geral
 
-- Em todo projeto de gamificação (obrigatório)
-- Para definir os comportamentos que serão rastreados
-- Para criar a base de eventos que disparam challenges e recompensas
+O módulo `action` é o **catálogo de tipos de ação** que os jogadores podem executar na gamificação. Cada documento da coleção `action` é a *definição* de um comportamento rastreável (ex: `sell`, `watch_video`, `checkin`), não a ocorrência dele. A ocorrência é registrada como `action_log` (vide `action-log.md`).
 
-## Ação simples vs ação com atributos
+Papel arquitetural:
 
-**Ação simples** — sem atributos. Use quando o contexto não importa, só o fato de ter ocorrido:
+- **Vocabulário de eventos da gamificação.** Nenhum `action_log` pode ser registrado para um `actionId` que não exista e esteja `active` (validado em `ActionRest.insertLog`, linhas 415-421).
+- **Esquema de atributos.** O campo `attributes` declara quais chaves o `action_log.attributes` pode carregar e o *tipo* esperado de cada uma. O tipo é consultado por consumidores (challenge, leaderboard, crowning, csv) para decidir coerção de valor (`ActionAttribute.TYPE_NUMBER`/`TYPE_BOOLEAN`).
+- **Configuração de comportamento no disparo.** Uma `Action` pode carregar `points`, `notifications` e `limit`. Esses campos não fazem nada no momento do cadastro — são lidos quando um `action_log` correspondente é processado (`AchievementManager.fireAction`).
+- **Base para challenges e triggers.** `ChallengeRule.actionId` e `trigger_html.actions` referenciam `action._id`. Por isso a exclusão de uma action tem efeito cascata (seção 6).
+
+Problemas que resolve:
+
+- Define o que pode ser rastreado e com qual contexto (atributos).
+- Permite recompensa direta por ação (pontos por ação, sem precisar de challenge).
+- Permite limitar a frequência de registro de uma ação (anti-fraude / anti-spam) via `limit`.
+
+Relação com outros módulos:
+
+| Módulo | Relação |
+|---|---|
+| `action-log` | Toda inserção de log valida a existência e `active` da action; resolve `actionId` por `_id` **ou** nome. |
+| `achievement` | `AchievementManager.fireAction` lê `action.points` (linha 152) e `action.notifications` (linha 196) ao processar um log. |
+| `challenge` | `ChallengeRule.actionId` aponta para `action._id`. Excluir a action **remove a rule** do challenge. |
+| `trigger` (`trigger_html`) | `trigger_html.actions` referencia actions; excluir a action a remove dessa lista. |
+| `point_category` | `RewardPoint.category` referencia uma categoria de pontos. |
+| `player` | Limites `per: "player"` contam `action_log` por `userId`. |
+
+---
+
+## 2. Arquitetura e Fluxos
+
+### 2.1 Classes envolvidas
+
+| Classe | Papel |
+|---|---|
+| `com.funifier.engine.action.Action` | Entidade/POJO raiz — documento da coleção `action`. |
+| `com.funifier.engine.action.ActionAttribute` | Subentidade — definição de atributo (`name`, `type`, `get_value_script`). |
+| `com.funifier.engine.action.Limit` | Subentidade — configuração de limite de frequência. |
+| `com.funifier.engine.action.LinkedAction` | Subentidade **legada/morta** — sem consumidores (seção 7). |
+| `com.funifier.engine.action.ActionDaoMongo` | Repositório Jongo. Coleção `action`. Faz sanitização e cascata de exclusão. |
+| `com.funifier.engine.action.ActionManager` | Manager. Delega CRUD ao DAO; calcula disponibilidade; orquestra o tracking de logs. |
+| `com.funifier.engine.action.ActionAsyncProcessor` | Thread por gamificação que consome a fila de `action_log` (firing assíncrono). |
+| `com.funifier.rest.v3.rest.ActionRest` | Controller REST v3 (`/v3/action` + `/v3/action/log*` + `/queue/*`). |
+| `com.funifier.engine.challenge.RewardPoint` | Subentidade de `points` (recompensa direta por ação). |
+| `com.funifier.engine.notify.NotificationDefinition` | Subentidade de `notifications`. |
+| `com.funifier.engine.image.Image` | Subentidade de `image` (`small`/`medium`/`original`). |
+
+Não há validação dedicada de schema; `Action` usa `@JsonIgnoreProperties(ignoreUnknown=true)` — **campos desconhecidos são silenciosamente descartados na desserialização**.
+
+### 2.2 Pipeline de criação/atualização — `POST /v3/action`
+
+Sequência real (`ActionRest.insert` → `ActionManager.addAction` → `ActionDaoMongo.addAction`):
+
+```
+[1] ActionRest.insert(action)            → ManagerFactory.getActionManager().addAction(action)
+[2] ActionManager.addAction(action)      → mongo.addAction(action, jongo)
+[3] ActionDaoMongo.addAction:
+    se action.id == null:
+        action.id = Guid.newShortGuid()                         // gera ID curto
+    senão:
+        action.id = Normalizer.normalize(id, NFD)
+                       .replaceAll("[^\\p{ASCII}]", "")          // remove acentos/não-ASCII
+                       .trim()
+                       .replaceAll(" ", "_")                     // espaços viram _
+                       .replaceAll("[^a-zA-Z0-9_]", "")          // remove o resto
+    para cada attribute:
+        att.name = Normalizer.normalize(att.name, NFD)
+                       .replaceAll("[^\\p{ASCII}]", "")
+                       .trim()
+                       .replaceAll(" ", "_")
+                       .replaceAll("[^a-zA-Z0-9_.]", "")         // nomes de attribute também permitem '.'
+    c.save(action)                                              // UPSERT por _id (Jongo)
+[4] Retorna 201 CREATED com a action (JsonUtil.toJsonRemoveNullFields)
+```
+
+**Síncrono.** Sem transação. `c.save` é **upsert por `_id`**: reenviar a mesma action substitui o documento inteiro (full replace, não patch).
+
+#### Fluxo de criação/atualização — `POST /v3/action`
+
+```mermaid
+flowchart LR
+  A[POST /v3/action] --> B{_id informado?}
+  B -- não --> C[gera Guid.newShortGuid]
+  B -- sim --> D["sanitiza _id<br/>NFD, strip não-ASCII,<br/>espaços→_, strip ^a-zA-Z0-9_"]
+  C --> E["sanitiza nomes de attributes<br/>(permite . além de a-zA-Z0-9_)"]
+  D --> E
+  E --> F["c.save(action)<br/>UPSERT por _id"]
+  F --> G[201 CREATED]
+```
+
+> **Não existe endpoint PUT.** `ActionManager.updateAction` / `ActionDaoMongo.updateAction` existem mas **não são acessíveis pelo REST** — toda escrita passa por `addAction` (upsert).
+
+### 2.3 Pipeline de exclusão — `DELETE /v3/action/:id` (cascata)
+
+`ActionRest.delete` → `ActionManager.deleteAction` → `ActionDaoMongo.deleteAction`:
+
+```
+[1] updateChallenges(id):
+    para CADA challenge da coleção `challenge`:
+        remove toda ChallengeRule cujo actionId == id
+        se removeu alguma rule → cc.remove(_id) + cc.save(challenge)   // re-salva o challenge alterado
+[2] updateActionConfigs(id):
+    para CADA trigger_html da coleção `trigger_html`:
+        remove a action da lista `actions` onde action.id == id
+        se removeu → re-salva o trigger_html
+[3] c.remove("{_id:#}", id)   // remove o documento da action
+[4] Retorna 204 NO CONTENT
+```
+
+Esse comportamento é **silencioso e cascateado** — vide seção 6. Não há log nem aviso; um challenge pode ficar com **zero rules** após a exclusão da action.
+
+### 2.4 Como a configuração da action influencia o disparo (firing)
+
+Os campos `points`, `notifications`, `limit` e `active` só produzem efeito quando um `action_log` correspondente é processado. Onde cada um é lido:
+
+| Campo | Lido em | Efeito |
+|---|---|---|
+| `active` | `ActionRest.insertLog:419` | Se `false`, o log é rejeitado (`"action ... is not active"`). |
+| `limit` | `ActionRest.insertLog:494` / `ActionManager.evaluateLimit` | Bloqueia o registro se exceder a frequência. |
+| `points` | `AchievementManager.fireAction:152` | Gera `Achievement` TYPE_POINT para o jogador (recompensa direta). |
+| `notifications` | `AchievementManager.fireAction:196` | Envia notificações de `EVENT_WIN` (scope ≠ custom). |
+| `attributes[].type` | `AchievementManager:2054`, `LeaderBoardManager:127`, `CsvManager:186`, `CrowningManager` | Coerção de valor (Number/Boolean) na agregação dos logs. |
+
+```mermaid
+sequenceDiagram
+  participant C as Cliente
+  participant R as ActionRest
+  participant AM as ActionManager
+  participant Ach as AchievementManager
+  C->>R: POST /v3/action/log {actionId, userId, attributes}
+  R->>AM: findActionByIdOrName(actionId)
+  AM-->>R: Action (erro 400 se null ou active=false)
+  R->>R: resolve player + checa Limit
+  alt async=false (síncrono)
+    R->>AM: trackSynchonous(log)
+    AM->>AM: triggerManager.execute(BEFORE_WIN) + addLog
+    AM->>Ach: fireAction(log)
+    Ach->>Ach: lê action.points → Achievement TYPE_POINT (só para player)
+    Ach->>Ach: lê action.notifications (EVENT_WIN) → envia
+  else async=true (default)
+    R->>AM: track(log) → enfileira (ActionAsyncProcessor)
+  end
+```
+
+**Importante:** recompensa por `points` e `notifications` da action só ocorrem quando o `principal` é **jogador** (`principal.isPlayer()`); para times, esta seção do `fireAction` é ignorada.
+
+### 2.5 Listagem — `GET /v3/action`
+
+`ActionManager.findAllActions(id, action, q, fields, orderby, reverse, max_results)` monta um pipeline de aggregation sobre a coleção `action`:
+
+```
+$match { _id: {$exists:true}
+         [, _id: <id>]
+         [, <q literal — concatenado cru>]
+         [, action: {$regex: <action>, $options:'i'}] }
+[$project { <fields separados por vírgula>: 1 }]
+[$sort { <orderby>: 1|-1 }]
+$limit <max_results>      // default 100 quando max_results <= 0
+```
+
+`q`, `orderby` e `fields` são **concatenados literalmente** na string do pipeline (superfície de injeção — seção 8). A resposta é um array JSON via `Callback.callback` (**não paginado**; o header `Range` não se aplica a `/v3/action`, apenas aos endpoints `/log*`).
+
+---
+
+## 3. Estrutura dos Objetos
+
+### 3.1 `Action` — documento raiz (coleção `action`)
+
+| Campo | Tipo | Padrão | Obrigatório | Descrição |
+|---|---|---|---|---|
+| `_id` | String | auto (`shortGuid`) ou sanitizado | — | ID da action. Se omitido, gerado; se informado, **sanitizado** (NFD, sem acentos, espaços→`_`, só `a-zA-Z0-9_`). |
+| `action` | String | — | recomendado | Nome amigável (ex: `"Sell"`). Pode ser usado para resolver a action no registro de log (`findActionByIdOrName`). |
+| `attributes` | `ActionAttribute[]` | — | não | Definição dos atributos aceitos no `action_log`. Vide 3.2. |
+| `points` | `RewardPoint[]` | — | não | Pontos concedidos **diretamente** quando a action é disparada (jogadores). Vide 3.4. |
+| `notifications` | `NotificationDefinition[]` | — | não | Notificações disparadas no `EVENT_WIN` ao disparar a action. Vide 3.5. |
+| `image` | `Image` | — | não | Imagem (`small`/`medium`/`original`). Vide 3.6. |
+| `limit` | `Limit` | — | não | Limite de frequência de registro de logs. Vide 3.3. |
+| `active` | boolean | `true` | não | Se `false`, logs para esta action são rejeitados. |
+| `extra` | `Map<String,Object>` | `{}` | não | Metadado livre. Persistido, **não interpretado** pelo firing. |
+| `available` | Boolean | — | — | **Campo calculado em runtime** (não persistido por design). Vide abaixo. |
+| `linkedActions` | `LinkedAction[]` | — | não | **Legado/morto** — aceito e persistido, **nunca lido**. Vide 3.7 e seção 7. |
+
+**Campo computado (não-persistente):**
+
+- `available` — preenchido somente em `GET /v3/action?available=true&player=<id>` por `ActionManager.isActionsAvailable` → `evaluateLimit`. `true` quando a action **não tem `limit`** ou o jogador ainda está abaixo do limite; `false` quando excedeu o limite **ou** a expressão de `limit.total` lançou exceção (falha silenciosa). Não é gravado no Mongo a menos que o cliente o envie explicitamente no POST.
+
+**Campos silenciosamente sanitizados no save (`ActionDaoMongo.addAction`):**
+
+- `_id` informado → normalizado (perde acentos, espaços viram `_`, caracteres especiais removidos). Ex: `"Vender Açaí"` → `Vender_Acai`.
+- `attributes[].name` → mesma normalização (adicionalmente permite `.`).
+
+**Campos aceitos mas descartados:**
+
+- Qualquer chave não mapeada na classe `Action` → descartada (`@JsonIgnoreProperties(ignoreUnknown=true)`).
+
+### 3.2 `ActionAttribute` — subentidade de `attributes`
+
+| Campo | Tipo | Obrigatório | Descrição |
+|---|---|---|---|
+| `name` | String | sim | Nome do atributo (sanitizado, permite `.`). |
+| `type` | String | recomendado | `"String"`, `"Number"` ou `"Boolean"`. **Não validado na escrita.** |
+| `get_value_script` | String | não | Exclusivo de trigger HTML — script de localização do valor numa página. |
+
+**`type` não é validado no cadastro.** As constantes `ActionAttribute.TYPE_STRING/NUMBER/BOOLEAN` só são consultadas por *consumidores* dos logs para decidir coerção: `Number` → cast numérico; `Boolean` → cast booleano; qualquer outro valor → tratado como string. Logo, um `type` arbitrário (ex: `"Integer"`) é aceito silenciosamente e se comporta como `String`.
+
+### 3.3 `Limit` — subentidade de `limit`
+
+| Campo | Tipo | Descrição |
+|---|---|---|
+| `total` | Object (Number **ou** String) | Número máximo de registros no período, **ou** fórmula Mustache+exp4j avaliada com `{player, action_log}` (ex: `"{{player.extra.max_actions}}"`). |
+| `per` | String | Escopo da contagem: `"player"`, `"team"` ou `"gamification"`. |
+| `every` | String | Janela de tempo (ex: `"1h"`, `"5h"`, `"1d"`). Se ausente → janela de `-10y` (efetivamente sempre). |
+| `query` | String | Filtro Mongo adicional, Mustache-parseado com `{player, action_log}`, **concatenado cru** na query de contagem. |
+
+Constantes: `PER_PLAYER = "player"`, `PER_TEAM = "team"`, `PER_GAME = "gamification"`.
+
+> ⚠️ **`per: "team"` é um branch morto.** A verificação de limite (`evaluateLimit`, `trackWithRestrictions`, `ActionRest.insertLog`, `insertLogBulk`) só trata `PER_PLAYER` e `PER_GAME`. Com `per: "team"` nenhum branch executa, `count` permanece `0`, `0 >= total` é falso → **o limite nunca bloqueia**. Vide seção 7.
+
+Lógica de contagem (quando `total > 0`):
+
+```
+from = (every != null) ? agora - every : agora - 10anos
+PER_PLAYER → db.action_log.count({userId, actionId, time: {$gte: from} <query>})
+PER_GAME   → db.action_log.count({actionId,        time: {$gte: from} <query>})
+se count >= total → bloqueia
+```
+
+### 3.4 `RewardPoint` — subentidade de `points`
+
+| Campo | Tipo | Descrição |
+|---|---|---|
+| `total` | double | Quantidade base de pontos. |
+| `category` | String | ID da categoria de pontos (`point_category`). |
+| `operation` | int | `0` NONE; `1` MULTIPLY_BY_ATTRIBUTE; `2` DIVIDE_BY_ATTRIBUTE. |
+| `value` | String | Nome do atributo do `action_log` usado em multiply/divide. |
+| `perPlayer` | boolean | Presente no schema; **não consultado** no firing de action. |
+
+Cálculo em `fireAction` (linhas 152-191), apenas para jogadores e quando `total != 0`:
 
-```json
-{
-  "_id": "watch_video",
-  "action": "Watch Video",
-  "active": true,
-  "attributes": []
-}
 ```
+NONE                  → totalPoints = total
+MULTIPLY_BY_ATTRIBUTE → totalPoints = total * action_log.attributes[value]
+DIVIDE_BY_ATTRIBUTE   → totalPoints = total / action_log.attributes[value]
+```
+
+> Se o atributo de `value` não existir ou não for numérico, a exceção é **engolida** e `totalPoints` permanece com o `total` base (a operação degrada silenciosamente para NONE).
+
+### 3.5 `NotificationDefinition` — subentidade de `notifications`
+
+| Campo | Tipo | Descrição |
+|---|---|---|
+| `event` | int | `0` WIN; `1` CREATE; `2` CHANGE; `3` LOSE; `4` REMOVE. |
+| `type` | int | `0` TEXT; `1` VIDEO. |
+| `scope` | int | `0` PRIVATE; `1` NEWSFEED; `99` CUSTOM. |
+| `content` | String | Conteúdo/mensagem. |
+| `tag` | String | Tag opcional. |
+
+No disparo da action, somente `event = EVENT_WIN (0)` com `scope ≠ SCOPE_CUSTOM (99)` é enviado (`getNotificationsByEvent` ignora scope custom).
+
+### 3.6 `Image` — subentidade de `image`
+
+Três variantes `ImageItem` (`small`, `medium`, `original`), cada uma com `url` (e `size`/`width`/`height`/`depth`, default `0`). Na prática, preencher `url` igual nas três variantes é suficiente.
+
+### 3.7 `LinkedAction` — subentidade de `linkedActions` _(legado/morto)_
+
+| Campo | Tipo | Descrição |
+|---|---|---|
+| `action` | String | ID da action filha a ser rastreada. |
+| `playerAttributeName` | String | Nome do atributo da action pai que referencia o jogador da action filha. |
+
+**Sem consumidores em `funifier-service`.** A classe e o campo só possuem getters/setters; nenhuma lógica de firing os lê. Aceito e persistido, porém inerte.
+
+---
 
-Exemplos típicos: `login`, `acessar_feed`, `assistir_video`, `jogar_mini`, `compartilhar`.
+## 4. Endpoints
 
-**Ação com atributos** — adicione atributos quando precisar filtrar ou acumular valores dentro de um challenge. Tipos disponíveis: `String`, `Number`, `Boolean`.
+Todos sob `ActionRest` (`@Path("v3/action")`). Autenticação: Bearer token (`AuthBean`). Abaixo apenas os endpoints do **cadastro de actions**; os endpoints de log (`/log`, `/log/bulk`, `/log/frequency`, `/log/aggregate`, `/log/{id}`, `/log/attribute/.../index/*`) e de fila (`/queue/*`) estão em `action-log.md`.
+
+### `GET /v3/action`
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Listar/pesquisar actions. |
+| Paginação | **Não paginado** (`Callback.callback`, array completo). |
+| Resposta | Array de `Action` com campos nulos removidos. |
+
+**Query params:**
+
+| Param | Tipo | Descrição |
+|---|---|---|
+| `id` | String | Filtra por `_id` exato. |
+| `action` | String | Filtra por nome (`$regex`, case-insensitive). |
+| `q` | String | Critério Mongo bruto (concatenado no `$match`). |
+| `fields` | String | Projeção (lista separada por vírgula). |
+| `orderby` | String | Campo de ordenação. |
+| `reverse` | boolean | `true` = descendente. |
+| `max_results` | int | Limite; default `100` quando `<= 0`. |
+| `player` | String | Usado com `available`. |
+| `available` | String | `"true"` + `player` → calcula `Action.available` por `evaluateLimit`. |
+
+### `GET /v3/action/:id`
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Buscar uma action por `_id` **exato** (`findActionById`). |
+| Observação | **Não** resolve por nome amigável — diferente do caminho de log. |
+
+### `POST /v3/action`
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Criar **ou** atualizar action. |
+| Full replace ou patch | **Full replace** (upsert por `_id` via `c.save`). |
+| Status | `201 CREATED`. |
+| Comportamento real | Gera/sanitiza `_id`; sanitiza `attributes[].name`; descarta campos desconhecidos. Não há erro em `_id` duplicado (upsert). |
+
+**Exemplo (action com atributos, pontos e limite):**
 
 ```json
 {
@@ -38,56 +337,186 @@ Exemplos típicos: `login`, `acessar_feed`, `assistir_video`, `jogar_mini`, `com
   "attributes": [
     { "name": "product", "type": "String" },
     { "name": "price", "type": "Number" }
-  ]
+  ],
+  "points": [
+    { "total": 10, "category": "xp", "operation": 1, "value": "price" }
+  ],
+  "limit": { "total": 5, "per": "player", "every": "1d" }
 }
 ```
 
-Use atributos quando quiser criar challenges como "vender 10 livros" (filtro por `product = "book"`) ou "vender R$500 em eletrônicos" (soma de `price`).
+### `DELETE /v3/action/:id`
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Excluir action. |
+| Status | `204 NO CONTENT`. |
+| Comportamento real | **Cascata silenciosa**: remove a action das rules de **todos** os challenges e da lista `actions` de **todos** os `trigger_html` antes de remover o documento (seções 2.3 e 6). |
+
+### Variantes adicionais
+
+- **Legado** `/2.0.0/action` (`rest.engine.ActionRest`) — endpoints `GET/DELETE /{id}` e `/log` antigos. Preferir v3.
+- **System** `/v3/system/action` (`rest.v3.rest.system.ActionRest`) — equivalente para a gamificação de sistema/admin.
+
+---
+
+## 5. Regras de Negócio
+
+Regras presentes no código que **não** estão no schema:
+
+1. **`_id` é sempre saneado.** Não é possível persistir `_id` com acentos, espaços ou símbolos — eles são transformados/removidos no save. O `_id` final pode diferir do enviado.
+2. **POST é upsert.** Reenviar com `_id` existente substitui o documento inteiro (full replace). Campos omitidos são apagados.
+3. **Resolução por nome no firing.** Ao registrar um `action_log`, o `actionId` é resolvido por `_id` **ou** por `action` (nome). O log persistido sempre usa o `_id` canônico (`log.actionId = a.getId()`).
+4. **`active = false` bloqueia logs.** Em `/log` retorna 400; em `/log/bulk` o item é silenciosamente descartado.
+5. **Limite por período.** `limit` restringe quantos logs de uma action podem ser registrados por jogador/gamificação numa janela (`every`). `total` pode ser uma fórmula dinâmica baseada em `player`/`action_log`.
+6. **Pontos diretos.** Uma action com `points` concede pontos ao jogador a cada log processado, independentemente de challenges.
+7. **Multi-tenant.** Cada gamificação (apiKey) tem sua própria coleção `action` e sua própria thread `ActionAsyncProcessor` (`"Funifier-ActionLog-Async-<apiKey>"`).
+8. **Consistência eventual no firing assíncrono.** Por padrão (`async=true`), o log é enfileirado e processado por uma thread; os efeitos (pontos, achievements) não são imediatos na resposta.
+
+---
+
+## 6. Comportamentos Automáticos
+
+| Comportamento | Trigger | Impacto | Persistência |
+|---|---|---|---|
+| Geração de `_id` | POST sem `_id` | `Guid.newShortGuid()` | Sim |
+| Sanitização de `_id` | POST com `_id` | NFD/strip/espaços→`_` | Sim |
+| Sanitização de `attributes[].name` | POST | NFD/strip (permite `.`) | Sim |
+| Upsert | POST com `_id` existente | Substitui documento inteiro | Sim |
+| **Cascata de exclusão em challenges** | DELETE | Remove a action das rules de todos os challenges; re-salva os alterados | Sim (challenge) |
+| **Cascata de exclusão em trigger_html** | DELETE | Remove a action da lista `actions` de todos os `trigger_html` | Sim (trigger_html) |
+| Cálculo de `available` | GET `?available=true&player=` | Preenche `Action.available` via limite | Não |
+| Recompensa por `points` | Log processado (firing) | Cria `Achievement` TYPE_POINT (só player) | Sim (achievement) |
+| Notificações por `notifications` | Log processado (firing) | Envia notificações `EVENT_WIN` | Sim (notification) |
+
+#### Fluxo de exclusão em cascata — `DELETE /v3/action/:id`
+
+```mermaid
+flowchart TD
+  A["DELETE /v3/action/:id"] --> B["updateChallenges(id)"]
+  A --> C["updateActionConfigs(id)"]
+  B --> B1["varre TODOS os challenges"]
+  B1 --> B2{"rule.actionId == id?"}
+  B2 -- sim --> B3["remove a rule + re-salva o challenge"]
+  B2 -- não --> B4["mantém"]
+  C --> C1["varre TODOS os trigger_html"]
+  C1 --> C2["remove id de actions + re-salva config"]
+  B3 --> D["c.remove(_id) da action"]
+  B4 --> D
+  C2 --> D
+  D --> E[204 No Content]
+```
 
-## Imagem
+> ⚠️ A documentação antiga afirmava que excluir uma action "pode causar inconsistências, verifique antes". **Isso está incorreto.** O sistema *auto-limpa* as rules dos challenges e as listas de trigger_html. O efeito colateral real é: um challenge que dependia exclusivamente daquela action fica **sem rules** (e potencialmente nunca mais completa).
 
-Actions podem ter uma imagem associada via campo `image` com três tamanhos:
+---
 
-```json
-"image": {
-  "small":    { "url": "https://...", "size": 0, "width": 0, "height": 0, "depth": 0 },
-  "medium":   { "url": "https://...", "size": 0, "width": 0, "height": 0, "depth": 0 },
-  "original": { "url": "https://...", "size": 0, "width": 0, "height": 0, "depth": 0 }
-}
-```
+## 7. Suportado vs NÃO Suportado
+
+### ✅ Suportado
+
+- CRUD de actions: `GET /v3/action`, `GET /v3/action/:id`, `POST /v3/action` (upsert), `DELETE /v3/action/:id` (com cascata).
+- Atributos tipados (`String`/`Number`/`Boolean`) consumidos por challenge, leaderboard, crowning, csv.
+- `active` para habilitar/desabilitar o registro de logs.
+- `limit` com `per: "player"` e `per: "gamification"`, `every` (janela), `query` (filtro extra) e `total` numérico ou fórmula Mustache+exp4j.
+- `points` (recompensa direta por ação, com operações NONE/MULTIPLY/DIVIDE).
+- `notifications` de `EVENT_WIN`.
+- `image` (small/medium/original).
+- Cálculo de disponibilidade (`available`) por jogador.
+- Resolução de action por `_id` ou nome no registro de logs.
 
-Na prática basta preencher `url` nos três tamanhos com a mesma URL se não houver versões distintas.
+### ❌ NÃO Suportado / Armadilhas
 
-## Comportamento de `_id` duplicado (upsert)
+- **`linkedActions`** — campo e classe `LinkedAction` existem, são persistidos, mas **nenhum código os lê**. Inerte.
+- **`limit.per: "team"`** — constante `PER_TEAM` existe, mas **nenhum branch trata** esse valor; o limite nunca bloqueia (no-op silencioso). Use `"player"` ou `"gamification"`.
+- **Validação de `attributes[].type`** — inexistente na escrita. Tipos inválidos são aceitos e tratados como `String`.
+- **Endpoint `PUT`** — não existe. `updateAction` no manager/DAO é inacessível pelo REST.
+- **Patch parcial** — não suportado; POST é full replace (upsert).
+- **`extra`** — persistido mas não interpretado pelo firing de action.
+- **`RewardPoint.perPlayer`** — presente no schema, não consultado no firing de action.
+- **`points`/`notifications` para times** — ignorados; só processados quando o principal é jogador.
+- **Paginação em `GET /v3/action`** — não há; retorna o array completo.
+- **Inconsistência de janela no limite** (vide seção 8) — o mesmo `limit` pode avaliar diferente conforme o ponto de entrada.
 
-O endpoint POST faz **upsert**: se o `_id` já existir, a ação é **atualizada**; se não existir, é **criada**. Não retorna erro em caso de duplicata.
+---
 
-Isso significa que é seguro reenviar a mesma ação para atualizar atributos ou o nome — os challenges existentes que referenciam esse `_id` continuam funcionando.
+## 8. Segurança e Permissões
 
-## Boas Práticas
+- **Autenticação:** Bearer token via `AuthBean`/`FrontController.getInstance(apiKey)`. Cada apiKey isola a coleção `action` da sua gamificação.
+- **Isolamento multi-tenant:** garantido pela resolução de `ManagerFactory` por apiKey; não há cruzamento entre gamificações.
+- **Registro de log por jogador:** em `/v3/action/log`, um jogador autenticado só pode registrar log para si mesmo (`ActionRest.insertLog:489`); registro para terceiros exige credencial de admin.
 
-- `_id`: letras minúsculas, sem espaços ou acentos — use `_` como separador (`watch_video`, não `Watch Video`)
-- Crie ações **genéricas** e use atributos para detalhar: prefira `comprar` com atributo `produto` a criar `comprar_sapato` e `comprar_camisa`
-- Omita `attributes` (ou envie `[]`) quando o contexto não for necessário para nenhum challenge
+**Superfícies de injeção (confirmadas no código):**
 
-## API Endpoints
+1. **`GET /v3/action` — `q`, `orderby`, `fields`** são concatenados literalmente na string do pipeline de aggregation (`ActionManager.findAllActions`). Entrada controlável pode alterar o pipeline (NoSQL injection / DoS por query). Mitigação no código: nenhuma.
+2. **`limit.query`** é Mustache-parseado com `{player, action_log}` e **concatenado cru** na query de contagem (`ActionRest.insertLog:522`, `evaluateLimit:285`, `trackWithRestrictions:200`). Valores controláveis que caiam nos placeholders entram na query sem sanitização.
+3. **`limit.total` como fórmula** é avaliada via `ExpressionBuilder` (exp4j) sobre string Mustache — exceções são engolidas, podendo silenciosamente liberar o registro.
 
-### Listar Ações
-**Método:** GET  
-**Endpoint:** `/v3/action`
+**Inconsistência de comportamento (mesma config, resultado diferente conforme entrada):**
+
+| Caminho | Janela de contagem |
+|---|---|
+| `ActionRest.insertLog` / `insertLogBulk` | `{$gte: from, $lte: log.time}` |
+| `ActionManager.trackWithRestrictions` | `{$gte: from}` |
+| `ActionManager.evaluateLimit` (cálculo de `available`) | `{$gte: from}` |
+
+O `available` exibido (sem limite superior) pode divergir do que de fato será permitido em `insertLog` (com `$lte log.time`).
+
+---
+
+## 9. Observabilidade e Troubleshooting
+
+**Verificar se uma action existe / está ativa:**
 
-**Busca múltipla com funifier_list:** o parâmetro `search` aceita termos separados por vírgula (OR):
 ```
-funifier_list type=action search="assistir video, jogar mini, acessar feed"
+GET /v3/action/<id>
+GET /v3/action?action=<nome>          # busca por nome (regex, case-insensitive)
 ```
 
-### Criar / Atualizar Ação
-**Método:** POST  
-**Endpoint:** `/v3/action`
+**Verificar disponibilidade para um jogador (limite):**
+
+```
+GET /v3/action?available=true&player=<playerId>
+# cada action retorna "available": true|false
+```
 
-POST com `_id` existente = update (upsert). POST sem `_id` = cria com ID gerado.
+**Inspecionar via banco (coleção `action`):**
+
+```
+db.action.findOne({_id: "<id>"})
+db.action.find({active: false})                    # actions desativadas
+db.action.find({"limit.per": "team"})              # ATENÇÃO: limite inerte (no-op)
+```
+
+**Antes de excluir uma action — quais challenges/triggers a usam:**
+
+```
+db.challenge.find({"rules.actionId": "<id>"})      # serão alterados pela cascata
+db.trigger_html.find({"actions._id": "<id>"})      # serão alterados pela cascata
+```
+
+**Erros comuns (registro de log) e causas:**
+
+| Mensagem | Causa |
+|---|---|
+| `action <x> does not exist` | `actionId` não casa com `_id` nem `action` (nome). |
+| `action <x> is not active` | `active = false` na action. |
+| `you have exced the limit ...` | `limit` excedido para o período/escopo. |
+| `it was not possible to identify the limit ...` | Fórmula `limit.total` lançou exceção ao avaliar. |
+
+**O que verificar quando algo não funciona:**
+
+- Action não concede pontos → confira `points` na action **e** que o principal é jogador (times não recebem). Confira que o log foi de fato processado (firing assíncrono por padrão).
+- Limite não bloqueia → confira se `per` é `"player"`/`"gamification"` (não `"team"`).
+- `_id` "mudou" após criar → sanitização (acentos/espaços/símbolos removidos).
+- Atributo numérico tratado como texto → confira `attributes[].type == "Number"` na definição da action.
+
+---
+
+## 10. Exemplos Práticos
+
+### 10.1 Mínimo funcional — ação simples
 
-**Ação simples:**
 ```json
 {
   "_id": "watch_video",
@@ -96,7 +525,8 @@ POST com `_id` existente = update (upsert). POST sem `_id` = cria com ID gerado.
 }
 ```
 
-**Ação com atributos:**
+### 10.2 Avançado — atributos, pontos dinâmicos, limite e notificação
+
 ```json
 {
   "_id": "sell",
@@ -105,33 +535,55 @@ POST com `_id` existente = update (upsert). POST sem `_id` = cria com ID gerado.
   "attributes": [
     { "name": "product", "type": "String" },
     { "name": "price", "type": "Number" }
-  ]
+  ],
+  "points": [
+    { "total": 1, "category": "revenue", "operation": 1, "value": "price" }
+  ],
+  "notifications": [
+    { "event": 0, "type": 0, "scope": 1, "content": "Você registrou uma venda!" }
+  ],
+  "limit": {
+    "total": "{{player.extra.daily_quota}}",
+    "per": "player",
+    "every": "1d",
+    "query": "attributes.product:'{{action_log.attributes.product}}'"
+  }
 }
 ```
 
-### Excluir Ação
-**Método:** DELETE  
-**Endpoint:** `/v3/action/:id`
+- `operation: 1` (MULTIPLY_BY_ATTRIBUTE) com `value: "price"` → pontos = `1 * price`.
+- `limit.total` é fórmula dinâmica resolvida do `player.extra.daily_quota`.
+- `limit.query` restringe a contagem ao mesmo `product`.
 
-> ⚠ Deletar uma ação que é referenciada em challenges ativos pode causar inconsistências. Verifique antes quais challenges usam essa ação:
-> ```
-> funifier_database action=aggregate collection=challenge pipeline='[{"$match": {"rules.actionId": "<action_id>"}}]'
-> ```
+### 10.3 Anti-pattern — o que NÃO fazer
 
-## Validação após criar
+```json
+{
+  "_id": "Vender Açaí #1",
+  "action": "venda",
+  "attributes": [ { "name": "preço final", "type": "Integer" } ],
+  "linkedActions": [ { "action": "bonus", "playerAttributeName": "indicado" } ],
+  "limit": { "total": 3, "per": "team", "every": "1h" }
+}
+```
 
-Use `funifier_list` para confirmar que a ação foi criada:
+Por que está errado:
 
-```
-funifier_list type=action search=<_id ou nome>
-```
+- `_id` com espaços/acentos/símbolos → será sanitizado para `Vender_Acai_1` (não será o que você espera referenciar).
+- `attributes[].name` `"preço final"` → vira `preo_final`; e `type: "Integer"` é inválido → tratado como `String` (sem coerção numérica).
+- `linkedActions` → **inerte**, nunca executado.
+- `limit.per: "team"` → **não bloqueia nada** (branch morto); o limite é ignorado.
 
-Não use `funifier_logs` para validar actions — esse comando é específico para triggers e schedulers.
+---
 
-## Checklist
+## Checklist de Configuração
 
-- [ ] `_id` definido: minúsculas, sem espaços (`watch_video`, não `Watch Video`)
-- [ ] `action` (nome amigável) preenchido
-- [ ] `active: true`
-- [ ] Atributos com tipos corretos: `String`, `Number` ou `Boolean`
-- [ ] Confirmado com `funifier_list type=action search=<_id>`
+- [ ] `_id` em minúsculas, sem espaços/acentos (`watch_video`, não `Watch Video`) — caso contrário será sanitizado.
+- [ ] `action` (nome amigável) preenchido.
+- [ ] `active: true` (senão logs serão rejeitados).
+- [ ] `attributes[].type` ∈ `String` | `Number` | `Boolean` (qualquer outro vira `String` silenciosamente).
+- [ ] Se usar `limit`: `per` ∈ `player` | `gamification` (**nunca** `team` — não funciona).
+- [ ] Se usar `points`: `category` aponta para um `point_category` existente; lembre que só jogadores recebem.
+- [ ] Antes de `DELETE`: ciente de que rules de challenges e referências em trigger_html serão removidas em cascata.
+- [ ] Não conte com `linkedActions` (campo morto).
+- [ ] Validado com `GET /v3/action/<id>` ou `GET /v3/action?action=<nome>`.