funifier-mcp 0.2.26 → 0.2.27

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

@@ -1,88 +1,495 @@
-# Action Log (Registro de Ação)
+# `action-log`
 
-**API Endpoint:** `/v3/action/log`
+**Acesso Studio:** sem tela dedicada no backend; os logs são consumidos via API e aparecem indiretamente no frontend do Studio (atividade do jogador / módulo Action). Nenhuma rota `/studio/...` é definida neste serviço.
+**API Endpoint:** `/v3/action/log` (gamificação) · `/v3/system/action/log` (sistema) · `/2.0.0/action/log` (legado)
+**Coleção MongoDB:** `action_log`
 
-## O que é
+---
 
-Registro detalhado de todas as ações executadas pelos jogadores. Armazena cada ação realizada, com detalhes como quem executou, qual ação foi feita e quando ocorreu. Esse registro alimenta todos os outros módulos da plataforma.
+## 1. Visão Geral
 
-## Quando usar
+O módulo `action-log` é o **ponto de entrada de eventos de jogador** na gamificação Funifier. Cada documento da coleção `action_log` representa uma ocorrência de uma `Action` previamente cadastrada — quem fez (`userId`), o que fez (`actionId`), quando (`time`) e com quais dados (`attributes`).
 
-- Para registrar que um jogador executou uma ação
-- Para alimentar desafios, rankings e recompensas
-- Para importar ações em lote de sistemas externos
-- Para rastrear comportamento dos jogadores
+Papel arquitetural:
 
-## Dependências
+- É o **gatilho universal do motor de gamificação**: registrar um action log é o que dispara a avaliação de desafios, pontuação, níveis, triggers e webhooks. O processamento real acontece em `AchievementManager.fireAction(ActionLog)` (ver `achievement.md` §2.2) — este módulo apenas valida, persiste e enfileira.
+- É também a **fonte de verdade histórica para contadores baseados em frequência**: desafios, KPIs e regras de elegibilidade contam/agrupam documentos de `action_log` por jogador, por time e por janela de tempo (métodos `countActionLogsRegistered*`).
+- A escrita é **assíncrona por padrão** — a chamada HTTP retorna imediatamente e o processamento ocorre em uma fila em memória por gamificação.
 
-- **Action**: a ação referenciada deve existir
-- **Player**: o jogador referenciado deve existir
+Problemas que resolve:
 
-## API Endpoints
+- Desacopla a captura do evento (rápida, sob alta carga) do seu processamento (caro: avaliação de desafios, agregações).
+- Mantém um log auditável de tudo que cada jogador executou, com atributos arbitrários por evento.
+- Permite contagens e agregações temporais (frequência, somatórios de atributos) diretamente sobre o histórico bruto.
 
-### Listar ActionLogs
-**Método:** GET
-**Endpoint:** `/v3/action/log`
+Relação direta com outros módulos:
 
-**Exemplo de Resposta:**
+- `action` — toda action log referencia uma `Action` (`actionId`). A `Action` define limites (`limit`) e atributos esperados. Sem action ativa correspondente, o log é rejeitado (na via de gamificação).
+- `achievement` — `trackSynchonous` chama `AchievementManager.fireAction` ao final; é onde desafios são avaliados e recompensas geradas.
+- `trigger` — `before_win` e `after_win` da entidade `action` são disparados em torno da persistência.
+- `challenge`, `level`, `kpi-formulas`, `crossword`, etc. — consomem os contadores de action log (`countActionLogsRegisteredByUser/Team`, `findLatestActionLogDate...`) para avaliar regras.
+- `csv-data` — `CsvManager.importActionLogRows` converte linhas de CSV em action logs.
+- `question`, `quiz`, `account`, `arduino/SensorManager` — constroem `ActionLog` internamente e o injetam no pipeline.
+
+---
+
+## 2. Arquitetura e Fluxos
+
+### 2.1 Classes envolvidas
+
+| Classe | Arquivo | Papel |
+|---|---|---|
+| `com.funifier.engine.action.ActionLog` | `engine/action/ActionLog.java` (8-77) | Entidade/POJO — documento raiz |
+| `com.funifier.engine.action.ActionManager` | `engine/action/ActionManager.java` (35-839) | Manager de gamificação: track, validação de limites, queries/agregações, contadores |
+| `com.funifier.engine.action.ActionDaoMongo` | `engine/action/ActionDaoMongo.java` | Acesso MongoDB (`action_log`, `action`, `trigger_html`) |
+| `com.funifier.engine.action.ActionAsyncProcessor` | `engine/action/ActionAsyncProcessor.java` | Thread + fila em memória (`LinkedBlockingQueue`) |
+| `com.funifier.engine.action.Limit` | `engine/action/Limit.java` | Constantes e config de limite por player/team/game |
+| `com.funifier.rest.v3.rest.ActionRest` | `rest/v3/rest/ActionRest.java` | Controller REST v3 (`/v3/action`) |
+| `com.funifier.rest.engine.ActionRest` | `rest/engine/ActionRest.java` | Controller legado (`/2.0.0/action`) |
+| `com.funifier.rest.v3.rest.system.ActionRest` | `rest/v3/rest/system/ActionRest.java` | Controller de sistema (`/v3/system/action`) |
+| `com.funifier.engine.system.action.ActionManager` | `engine/system/action/ActionManager.java` | Manager de sistema — escrita direta, **sem pipeline** |
+
+> Não há `Repository` para a entidade `ActionLog` além do `ActionDaoMongo`; várias queries de `action_log` são montadas diretamente no `ActionManager`.
+
+### 2.2 Pipeline principal — `POST /v3/action/log`
+
+Sequência real (método `ActionRest.insertLog`, `rest/v3/rest/ActionRest.java:408`):
+
+```
+[1] Resolve a Action          → ActionManager.findActionByIdOrName(log.actionId)
+                                 query: {$or:[{_id:#},{action:#}]}  (aceita id OU nome)
+    Se null            → 400 "action ... does not exist"
+    Se a.active==false → 400 "action ... is not active"
+
+[2] Defaults silenciosos
+    - log.time   = new Date()        se null
+    - log.id     = Guid.newShortGuid() se null
+    - log.actionId = a.getId()       ← NORMALIZA para o _id canônico da Action
+
+[3] Resolve o principal (jogador OU time)
+    - userId null/vazio/"me"                → usa player do token; senão 400 "player is required"
+    - findPrincipalByUserOrTeamId(userId)≠null → ok (jogador ou time existente)
+    - findByAlternativeLogin(userId)≠null      → userId = player.getId()
+    - senão                                    → tenta auto-criar (ver §5); se não puder → 400
+
+[4] Restrição de token de jogador
+    Se autenticado como jogador e player != log.userId → 400
+    (só pode registrar a própria ação)
+
+[5] Avaliação de limite (a.limit), se a.limit.total != null   → ver §5
+    Se count >= total → 400 "you have exced the limit ..."
+
+[6] Persistência
+    - async != "false"  → ActionManager.track(log)            (enfileira, retorna já)
+    - async == "false"  → ActionManager.trackSynchonous(log)  (processa e retorna achievements)
+```
+
+### Fluxo de registro — `action-log`
+
+```mermaid
+flowchart TD
+    A["POST /v3/action/log"] --> B{"Action existe<br/>e ativa?"}
+    B -- não --> E1["400 Bad Request"]
+    B -- sim --> C["Defaults: time, _id<br/>actionId = id canônico"]
+    C --> D{"Principal<br/>resolvido?"}
+    D -- não --> E2["400 / auto-create"]
+    D -- sim --> F{"Token de jogador<br/>= userId?"}
+    F -- não --> E3["400"]
+    F -- sim --> G{"Limite excedido?"}
+    G -- sim --> E4["400 limit exceeded"]
+    G -- não --> H{"async == 'false'?"}
+    H -- não --> Q["track() → fila em memória"]
+    H -- sim --> S["trackSynchonous()"]
+    Q -.->|thread async| S
+    S --> T1["trigger before_win"]
+    T1 --> P["addLog → save em action_log"]
+    P --> T2["trigger after_win"]
+    T2 --> FA["AchievementManager.fireAction()"]
+    FA --> R["achievements retornados"]
+```
+
+### 2.3 Núcleo de processamento — `trackSynchonous(ActionLog)`
+
+`ActionManager.trackSynchonous` (`engine/action/ActionManager.java:322`) é o coração do pipeline. Ordem **exata** de execução:
+
+1. Cria `TriggerContext` e injeta uma lista `achievements` em `context.extra`.
+2. `triggerManager.execute(actionId, action, Trigger.ENTITY_ACTION, Trigger.EVENT_BEFORE_WIN, userId, context)` — dispara triggers `before_win` da entidade `action`. **Ocorre antes da persistência**, então um trigger pode mutar `attributes` antes do save.
+3. `addLog(action)` → `ActionDaoMongo.addLog` → `c.save(action)` na coleção `action_log`.
+4. `triggerManager.execute(... Trigger.EVENT_AFTER_WIN ...)` — dispara triggers `after_win`. **Ocorre após o save**; mutações aqui não re-persistem o log automaticamente.
+5. `AchievementManager.fireAction(action)` — avalia desafios, pontos, níveis, etc. (ver `achievement.md` §2.2).
+6. Retorna `fireAction(...)` + os achievements acumulados pelos triggers em `context.extra`.
+
+> A entidade de trigger é `Trigger.ENTITY_ACTION = "action"`. Não existe entidade de trigger separada para action log — `ENTITY_ACTIONLOG = "action_log"` está **comentada** no código (`Trigger.java:13`).
+
+### 2.4 Sequência síncrona (`async=false`)
+
+```mermaid
+sequenceDiagram
+    participant C as Cliente
+    participant R as ActionRest
+    participant AM as ActionManager
+    participant TM as TriggerManager
+    participant DB as Mongo (action_log)
+    participant ACH as AchievementManager
+
+    C->>R: POST /v3/action/log?async=false
+    R->>R: valida action, principal, limite
+    R->>AM: trackSynchonous(log)
+    AM->>TM: execute(action, before_win)
+    AM->>DB: save(log)
+    AM->>TM: execute(action, after_win)
+    AM->>ACH: fireAction(log)
+    ACH-->>AM: List<Achievement>
+    AM-->>R: achievements
+    R-->>C: 201 { action, achievements }
+```
+
+### 2.5 Processamento assíncrono — `ActionAsyncProcessor`
+
+- No construtor de `ActionManager` (`:41-46`) é iniciada **uma thread por gamificação**, nomeada `Funifier-ActionLog-Async-<apiKey>`, rodando `ActionAsyncProcessor.run()`.
+- `track(log)` apenas faz `queue.offer(log)` em um `LinkedBlockingQueue<ActionLog>` **em memória**.
+- O loop (`run()`, `:32-61`): `poll()` retira da fila; **se** `actionId != null && userId != null` → `trackSynchonous`; senão a entrada é **descartada silenciosamente** (já foi removida pelo `poll`). `Thread.sleep(100)` só ocorre quando a fila está vazia.
+- A fila **não é persistida**: reinício/crash do processo perde tudo que estava enfileirado e não processado. Há um paliativo manual: `PUT /v3/action/queue/save` despeja a fila atual na coleção `action_log_memory`.
+
+---
+
+## 3. Estrutura dos Objetos
+
+### 3.1 `ActionLog` — documento raiz (coleção `action_log`)
+
+| Campo | Tipo | Padrão | Obrigatório | Descrição |
+|---|---|---|---|---|
+| `_id` | String | `Guid.newShortGuid()` se omitido | Não (gerado) | Short GUID alfanumérico (**não** é ObjectId). Mapeado de `id` via `@JsonProperty("_id")`. |
+| `actionId` | String | — | Sim | Id da `Action`. Na via de gamificação é **normalizado** para o `_id` canônico da Action (aceita nome no input). |
+| `userId` | String | token / auto | Sim | Id do jogador OU id do time (principal). Aceita `"me"` (resolve via token). |
+| `time` | Date (BSON date, UTC) | `new Date()` se omitido | Não | Momento da ação. Mongo armazena em GMT0. |
+| `attributes` | Map<String,Object> | `null` | Não | Dados livres do evento (ex: `{product, price, location}`). Tipos arbitrários. |
+
+`@JsonIgnoreProperties(ignoreUnknown=true)` na classe: **qualquer campo extra enviado no JSON é ignorado silenciosamente** (não persiste e não gera erro).
+
+**Campos legados/comentados (não existem em runtime):**
+
+- `configId` — comentado (`ActionLog.java:19`); resquício de uma versão que ligava o log a uma "action config".
+- `entity` (JsonElement) e `attributes` como `DBObject` — comentados (`:25-26`); substituídos por `Map<String,Object>`.
+- Construtor `ActionLog(configId, actionId, userId, time)` — comentado (`:48-53`).
+
+**Não há** campos `extra`, `origin`, `created`, `updated` ou índice de tenant no documento. O isolamento entre gamificações é por **banco/conexão** (ver §8), não por campo.
+
+### 3.2 `Limit` — configuração de limite (vive na `Action`, não no log)
+
+Define quantas vezes a action pode ser registrada num período. Avaliado em `insertLog` / `trackWithRestrictions` / `evaluateLimit`.
+
+| Campo | Tipo | Descrição |
+|---|---|---|
+| `total` | Object (Number **ou** String) | Limite numérico, ou expressão Mustache+exp4j (ex: `{{player.extra.max_actions}}`). |
+| `per` | String | Escopo do limite: ver constantes abaixo. |
+| `every` | String | Janela móvel (ex: `5h`, `1d`). Default `-10y` (praticamente sem limite temporal). |
+| `query` | String | Filtro Mongo adicional, Mustache-parsed (mín. 3 chars). Ex: `attributes.video:'{{action_log.attributes.video}}'`. |
+
+Constantes de `Limit.per`:
+
+| Valor | Constante | Comportamento na contagem |
+|---|---|---|
+| `player` | `PER_PLAYER` | Conta `{userId, actionId, time>=from [, query]}` |
+| `gamification` | `PER_GAME` | Conta `{actionId, time>=from [, query]}` (toda a gamificação) |
+| `team` | `PER_TEAM` | **Declarado mas NÃO tratado** nas verificações de limite (ver §7) |
+
+---
+
+## 4. Endpoints
+
+### `GET /v3/action/log` — consultar action logs
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Listar/paginar action logs |
+| Método | `ActionManager.findAllActionLogs` (`:534`) |
+| Autenticação | Bearer token |
+| Paginação | Header `Range: items=0-100` (default 100) |
+
+**Query params:** `player` (`"me"` resolve via token), `action`, `q` (critério Mongo bruto), `published_min`/`published_max` (RFC 3339 ou keyword `-1d`,`-30m`...), `orderby` (`actionId`/`userId`/`time`), `reverse`, `max_results` (default 100).
+
+**Comportamento real:** monta um pipeline `$match` + `$sort` + `$limit`. `q` e `orderby` são **concatenados crus** na query (ver §8). Sempre limita a 100 se `max_results <= 0`.
+
+### `GET /v3/action/log/frequency` — frequência agrupada por tempo
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Agrupar ações por bucket temporal |
+| Método | `ActionManager.findAllActionLogsFrequency` (`:629`) |
+| Autenticação | Bearer token |
+
+**Query params:** `player`, `action`, `q`, `published_min/max`, `every` (ex: `1d`, `3M`), `time_zone` (ex: `America/Sao_Paulo`), `sum_field` (soma `attributes.<sum_field>` em vez de contar ocorrências).
+
+**Comportamento real:** Mongo grava datas em GMT0; `time_zone` aplica um offset via `$add`/`$subtract` antes do agrupamento. Sem `sum_field`, usa `total: {$sum: 1}`. O agrupamento usa `$dayOfYear`/`$week`/`$month`/`$year` + `$mod` para janelas múltiplas (`everyAmount`).
+
+### `POST /v3/action/log/aggregate` — agregação livre
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Rodar pipeline de agregação arbitrário |
+| Método | `ActionManager.findAllActionLogsAggregate` (`:581`) |
+| Autenticação | Bearer token |
+| Body | Lista de stages (strings) de aggregation Mongo |
+
+**Comportamento real:** aplica um `$match` (filtros player/action/q/time) e **acrescenta os stages do body** após ele. Default (body vazio) sugerido: `["{$group:{_id:\"$userId\",total:{$sum:1},start:{$min:\"$time\"},end:{$max:\"$time\"}}}"]`. Superfície de injeção (§8).
+
+### `POST /v3/action/log` — registrar action log
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Registrar ocorrência de uma action |
+| Método | `ActionRest.insertLog` (`:408`) |
+| Autenticação | Bearer token |
+| Full replace ou patch | Insert; com `_id` reutilizado vira **replace + reprocessamento** (§5) |
+
+**Query param `async`:** **somente a string literal `"false"`** ativa o modo síncrono (`if(async != null && "false".equals(async))`). Qualquer outro valor (`"true"`, `"sync"`, `"0"`, ausência) → assíncrono. No modo síncrono a resposta inclui os achievements gerados.
+
+**Exemplo de request (síncrono):**
+```
+POST /v3/action/log?async=false
+{ "actionId": "buy", "userId": "player@x.com", "attributes": { "product": "book", "price": 86.5 } }
+```
+**Response 201:**
 ```json
-[
-  {
-    "_id": "6509e4e28325771ffaa4506e",
-    "actionId": "sell",
-    "userId": "jerry",
-    "time": 1695147234712,
-    "attributes": {
-      "product": "bike",
-      "price": 1200
-    }
-  }
-]
+{ "action": { "_id": "aB3xQ", "actionId": "buy", "userId": "player@x.com", "time": 1737300000000, "attributes": { "product": "book", "price": 86.5 } },
+  "achievements": [ { "type": 0, "total": 10, "point": "xp" } ] }
 ```
 
-### Registrar ActionLog
-**Método:** POST
-**Endpoint:** `/v3/action/log`
+### `POST /v3/action/log/bulk` — registro em lote
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Registrar múltiplas action logs |
+| Método | `ActionRest.insertLogBulk` (`:564`) |
+| Autenticação | Bearer token |
+| Modo | **Sempre assíncrono** (não há opção `async`) |
+
+**Comportamento real:** valida item a item; falhas **não interrompem** o lote — itens inválidos vão para `content_with_not_allowed_actions` / `content_with_not_allowed_players` e contam em `total_ignored`. **A restrição de "jogador só registra a própria ação" NÃO existe nesta rota** (ver §7/§8).
 
-**Exemplo de Body:**
+**Response 201:**
 ```json
+{ "total_registered": 2, "content_size": 3, "total_ignored": 1, "content": [ ... ],
+  "content_with_not_allowed_players": [ { "actionId": "buy", "userId": "inexistente" } ] }
+```
+
+### `DELETE /v3/action/log/{id}` — remover action log
+
+`ActionRest.deleteLog` → `ActionManager.deleteActionLog` (`:824`): `log.remove("{_id:#}", id)`. **Não estorna** pontos/achievements já gerados pelo log.
+
+### `GET /v3/action/log/attribute/{attribute}/index/create` — criar índice geoespacial
+
+`create2dAttributeIndex` (`:765`): cria índice `2dsphere` em `attributes.<attribute>` (para queries `$near`/geo em checkins). Disponível a qualquer Bearer token.
+
+### `GET /v3/action/log/attribute/{attribute}/index/drop` — remover índice geoespacial
+
+`drop2dAttributeIndex` (`:779`): **a resposta `indexes` é montada ANTES do `dropIndex`** — portanto reflete o estado pré-remoção, incluindo o índice que está sendo removido (ver §9).
+
+### Endpoints de fila assíncrona
+
+| Endpoint | Método | Ação |
+|---|---|---|
+| `/v3/action/queue/info` | GET | Estatísticas da fila (`size`, `remaining_capacity`, durações, maior log) |
+| `/v3/action/queue/info` | DELETE | Zera as estatísticas |
+| `/v3/action/queue/clear` | DELETE | **Esvazia a fila** (descarta logs não processados) |
+| `/v3/action/queue/first` | GET | Primeiros 100 itens da fila (sem remover) |
+| `/v3/action/queue/last` | GET | Últimos 100 itens da fila (sem remover) |
+| `/v3/action/queue/save` | PUT | Despeja a fila em `action_log_memory` |
+
+### `POST /v3/system/action/log` — registro de sistema (sem pipeline)
+
+`system.ActionRest.insertLog` → `system.ActionManager.insertLog` (`engine/system/action/ActionManager.java:27`). Grava direto em `action_log` (`c.save`), com apenas defaults de `time`/`_id`. **NÃO valida action, NÃO valida player, NÃO dispara triggers, NÃO chama fireAction.** Também expõe `GET /v3/system/action/log/{id}`, `DELETE /v3/system/action/log/{id}` e `POST /v3/system/action/log/aggregate`. Use apenas para inserir registros brutos que **não devem** acionar gamificação.
+
+### `GET|POST /2.0.0/action/log` — endpoint legado
+
+`rest/engine/ActionRest.java`. Autenticação por `?api_key=` (query param). O `POST` apenas seta `time` e chama `track(log)` — **sem validar action, player ou limite**. Mantido por compatibilidade.
+
+---
+
+## 5. Regras de Negócio
+
+Regras que existem no código mas não no schema do documento:
+
+- **Normalização de `actionId` (gamificação):** `findActionByIdOrName` casa por `_id` **ou** por `action` (nome); em seguida `log.actionId` é sobrescrito pelo `_id` canônico. Postar pelo nome funciona, mas o persistido é sempre o id. As vias legado (`/2.0.0`) e sistema (`/v3/system`) **não** normalizam — persistem `actionId` verbatim.
+- **Auto-criação de jogador:** se `userId` não existe como principal nem como login alternativo, o sistema tenta `AuthenticationManager.createIfDontExist`, respeitando `Account.players_allowed`. Se o limite da conta foi atingido → 400; se a gamificação não permite auto-criação → 400.
+- **`"me"` como `userId`:** resolvido para o jogador do token.
+- **Restrição de token de jogador:** em `POST /v3/action/log`, um token de **jogador** só registra ações do próprio `userId`. Esta checagem **não** existe em `/bulk`, está **comentada** em `trackWithRestrictions` (`ActionManager.java:167-169`, usado pelo CSV) e inexiste no legado/sistema.
+- **Limite (`a.limit`):** quando `a.limit.total != null` e `> 0`, conta documentos em `action_log` na janela `time >= from` (`from = now - every`, ou `-10y`). `PER_PLAYER` filtra por `userId`; `PER_GAME` por toda a gamificação; `PER_TEAM` **não tem branch** (não limita nada). `total` pode ser expressão (`{{...}}` + exp4j); falha de parse → 400.
+- **Idempotência / risco de upsert:** `addLog` usa `c.save(action)`, que é **upsert por `_id`**. Reenviar um `_id` já existente **substitui** o documento **e dispara `fireAction` novamente** — podendo recontabilizar recompensas. Não há proteção contra reprocessamento por id repetido.
+- **Multi-tenant:** toda operação resolve a conexão via `FrontController.getInstance(apiKey).getManagerFactory().getJongoConnection()` — cada gamificação tem seu próprio contexto Mongo. O documento `action_log` não carrega campo de tenant.
+- **Consistência eventual:** no modo assíncrono (default), o retorno 201 **não garante** que o log foi processado nem persistido — apenas enfileirado.
+
+---
+
+## 6. Comportamentos Automáticos
+
+| Comportamento | Trigger | Impacto | Persistência |
+|---|---|---|---|
+| Default de `time` | `time == null` no insert | `time = new Date()` | Sim |
+| Default de `_id` | `id == null` no insert | `id = Guid.newShortGuid()` | Sim |
+| Normalização de `actionId` | via gamificação | `actionId = action._id` | Sim |
+| Trigger `before_win` | antes do save | Pode mutar `attributes`, gerar achievements | Mutação persiste (save ocorre depois) |
+| Persistência | `addLog` | `save` em `action_log` | Sim |
+| Trigger `after_win` | após o save | Efeitos colaterais; não re-salva o log | Não (salvo re-save explícito) |
+| `fireAction` | fim de `trackSynchonous` | Avalia desafios/pontos/níveis/webhooks | Gera docs em `achievement` etc. |
+| Auto-criação de jogador | `userId` inexistente | Cria `Player` (se permitido) | Sim |
+| Descarte de log inválido | `actionId`/`userId` null na fila | Item removido sem aviso | Não |
+
+```mermaid
+flowchart LR
+    IN["track(log)"] --> Q["fila em memória"]
+    Q --> CK{"actionId e userId<br/>não nulos?"}
+    CK -- não --> DROP["descarta (sem log)"]
+    CK -- sim --> BW["before_win"]
+    BW --> SV["save action_log"]
+    SV --> AW["after_win"]
+    AW --> FA["fireAction → achievements / level / webhook"]
+```
+
+---
+
+## 7. Suportado vs NÃO Suportado
+
+### ✅ Suportado
+
+- Registro síncrono e assíncrono (`/v3/action/log`).
+- Registro em lote tolerante a falhas (`/v3/action/log/bulk`).
+- Consulta paginada, por frequência temporal e por agregação livre.
+- Limite `per player` e `per gamification`, com janela `every` e filtro `query` dinâmico.
+- Atributos arbitrários por evento, incluindo geolocalização (`location` + índice `2dsphere`).
+- Contadores reutilizáveis por player e por time (usados por challenge/level/kpi).
+- Importação via CSV (`CsvManager.importActionLogRows` → `trackWithRestrictions`).
+- Inserção de sistema sem gamificação (`/v3/system/action/log`).
+
+### ❌ NÃO Suportado / armadilhas
+
+- **Limite `per team`:** `Limit.PER_TEAM` (`"team"`) é declarado mas **nenhuma verificação de limite o trata** (`insertLog`, `insertLogBulk`, `trackWithRestrictions`, `evaluateLimit` só tratam `PER_PLAYER` e `PER_GAME`). Configurar `per: "team"` → sem limite efetivo.
+- **Entidade de trigger `action_log`:** `Trigger.ENTITY_ACTIONLOG = "action_log"` está **comentada**. Triggers disparam só na entidade `action`.
+- **Durabilidade da fila assíncrona:** a fila é `LinkedBlockingQueue` em memória; **reinício/crash perde** logs enfileirados e não processados. O retorno 201 assíncrono não é garantia de processamento.
+- **Estorno ao deletar:** `DELETE /v3/action/log/{id}` remove o documento mas **não reverte** pontos/achievements/níveis já concedidos.
+- **Idempotência:** reenviar `_id` existente **reprocessa e pode duplicar** recompensas (upsert via `save`).
+- **Restrição de jogador no `/bulk`, no legado e no sistema:** ausente — ver §8.
+- **Resposta de `index/drop`:** mostra os índices **antes** da remoção (não reflete o pós-estado).
+- **Campos legados `configId`, `entity`:** aceitos no JSON mas ignorados (`@JsonIgnoreProperties`); não persistem.
+
+---
+
+## 8. Segurança e Permissões
+
+- **Autenticação:** Bearer token (v3 e sistema); `?api_key=` na via legada `/2.0.0`.
+- **Isolamento multi-tenant:** por conexão Mongo derivada do `apiKey` (`FrontController.getInstance(apiKey)`), não por campo no documento.
+- **Restrição de jogador (parcial):** apenas `POST /v3/action/log` impede um token de jogador de registrar ação de outro `userId`. **Lacunas:**
+  - `POST /v3/action/log/bulk` — sem a checagem; um token de jogador pode, em lote, enviar logs com `userId` de terceiros (desde que o principal exista).
+  - `trackWithRestrictions` (CSV) — a checagem está **comentada** (`ActionManager.java:167-169`).
+  - `/2.0.0/action/log` e `/v3/system/action/log` — sem checagem.
+- **Injeção em queries (raw):** parâmetros concatenados sem whitelist/sanitização no pipeline de agregação:
+  - `q` em `findAllActionLogs`/`Aggregate`/`Frequency` (`query.append(", " + q)`).
+  - `orderby` em `findAllActionLogs` (`"{$sort:{" + orderby + " : #}}"`).
+  - `aggregations` (body) em `/log/aggregate` — stages crus.
+  Mitigado por serem de leitura/agregação, mas permitem expressões arbitrárias de Mongo sobre `action_log` do tenant.
+- **Operações de índice abertas:** qualquer Bearer token pode criar/remover índices `2dsphere` (`/log/attribute/{attribute}/index/...`), impactando performance.
+- **Endpoints de fila** (`/v3/action/queue/*`) expõem e permitem **limpar** a fila (DELETE `/queue/clear`) — descarta logs não processados.
+
+---
+
+## 9. Observabilidade e Troubleshooting
+
+**Diagnóstico — o módulo está funcionando?**
+- `GET /v3/action/log?player=<id>&orderby=time&reverse=true&max_results=10` — confirma persistência.
+- `GET /v3/action/queue/info` — tamanho da fila e durações; fila crescente indica processamento lento/travado.
+
+**Queries úteis (Mongo / aggregate):**
+- Total por jogador na última semana:
+  ```
+  POST /v3/action/log/aggregate?published_min=-7d
+  [ "{$group:{_id:\"$userId\", total:{$sum:1}}}" ]
+  ```
+- Frequência diária de uma action:
+  ```
+  GET /v3/action/log/frequency?action=buy&every=1d&time_zone=America/Sao_Paulo
+  ```
+- Buscar um log específico: `GET /v3/system/action/log/{id}`.
+
+**Erros comuns e causas:**
+
+| Sintoma | Causa provável |
+|---|---|
+| `400 action ... does not exist` | `actionId` não casa por `_id` nem por nome; ou action de outro tenant |
+| `400 action ... is not active` | `Action.active == false` |
+| `400 player is required` | `userId` ausente e sem player no token |
+| `400 ... not allowed to create new players` | `Account.players_allowed` atingido na auto-criação |
+| `400 you have exced the limit ...` | `a.limit` atingido na janela `every` |
+| Log não aparece / sem achievements | Modo assíncrono: ainda na fila, descartado (campos null) ou perdido em reinício |
+| Recompensa duplicada | Reuso de `_id` (upsert reprocessa via `fireAction`) |
+| Limite `per team` ignorado | `PER_TEAM` não é tratado (§7) |
+
+**O que verificar quando algo não funciona:**
+1. A `Action` existe e está ativa nesta gamificação?
+2. O `userId` é um principal válido (jogador ou time)?
+3. Foi enviado com `_id` repetido?
+4. O modo é assíncrono? Cheque `/v3/action/queue/info`.
+5. Os triggers `before_win`/`after_win` da action lançam exceção (interrompem o pipeline)?
+
+---
+
+## 10. Exemplos Práticos
+
+**Mínimo funcional:**
+```
+POST /v3/action/log
+{ "actionId": "tweet", "userId": "player@funifier.com" }
+```
+
+**Avançado (síncrono, com atributos e geolocalização):**
+```
+POST /v3/action/log?async=false
 {
-  "actionId": "sell",
-  "userId": "jerry",
+  "actionId": "checkin",
+  "userId": "player@funifier.com",
+  "time": "2026-05-20T10:00:00-03:00",
   "attributes": {
-    "product": "bike",
-    "price": 1200
+    "company": "coca-cola",
+    "price": 1200,
+    "location": { "type": "Point", "coordinates": [-15.797922, -47.887791] }
   }
 }
 ```
+Retorna `{ action, achievements }` — útil para ver imediatamente o que a ação desencadeou.
+
+**Lote:**
+```
+POST /v3/action/log/bulk
+[ { "actionId": "sell", "userId": "jerry", "attributes": { "price": 1200 } },
+  { "actionId": "sell", "userId": "tom",   "attributes": { "price": 25 } } ]
+```
 
-### Registrar Múltiplos ActionLogs
-**Método:** POST
-**Endpoint:** `/v3/action/log/bulk`
+**Anti-pattern — reenviar com `_id` fixo "para atualizar":**
+```
+POST /v3/action/log
+{ "_id": "fixed-123", "actionId": "buy", "userId": "ana", "attributes": { "price": 10 } }
+```
+❌ Por quê: `save` faz upsert e `fireAction` roda de novo → recompensas podem ser **duplicadas**. Action log é um evento imutável; nunca reutilize `_id` para "editar".
 
-**Exemplo de Body:**
-```json
-[
-  {
-    "actionId": "sell",
-    "userId": "jerry",
-    "attributes": { "product": "bike", "price": 1200 }
-  },
-  {
-    "actionId": "sell",
-    "userId": "tom",
-    "attributes": { "product": "book", "price": 25 }
-  }
-]
+**Anti-pattern — confiar no 201 assíncrono como confirmação:**
+```
+POST /v3/action/log        // async (default)
+→ 201, mas o log pode falhar/ser descartado/perder-se na fila
 ```
+❌ Para confirmação de processamento, use `async=false` ou consulte depois via `GET /v3/action/log`.
+
+**Anti-pattern — usar `/v3/system/action/log` esperando gamificação:**
+❌ Esse endpoint grava o documento mas **não** dispara desafios/triggers/achievements. Para gamificar, use `/v3/action/log`.
 
-### Excluir ActionLog
-**Método:** DELETE
-**Endpoint:** `/v3/action/log/:id`
+---
 
-## Validações e Testes
+## Checklist de Configuração
 
-- [ ] ActionLog aparece na lista com dados corretos
-- [ ] Ao registrar action log, desafios relacionados progridem
-- [ ] Bulk insert registra múltiplas ações corretamente
-- [ ] Atributos são armazenados conforme definido na ação
+- [ ] A `Action` referenciada existe e está **ativa** antes de registrar o log.
+- [ ] `userId` é um principal válido (jogador ou time), ou auto-criação está habilitada e dentro de `players_allowed`.
+- [ ] Atributos numéricos usados em limite/regra estão no tipo correto (Number, não String).
+- [ ] Se precisa do resultado imediato (achievements), use `async=false` — lembre que **só a string `"false"`** ativa o modo síncrono.
+- [ ] **Nunca** reutilize `_id` (armadilha: upsert reprocessa e duplica recompensas).
+- [ ] Para limite por time: lembre que `per: "team"` **não é aplicado** — use `per: "player"`/`"gamification"` ou valide fora.
+- [ ] Para queries geoespaciais, crie o índice `2dsphere` via `/v3/action/log/attribute/{attr}/index/create` antes.
+- [ ] Não dependa do retorno 201 assíncrono como garantia de processamento; monitore `/v3/action/queue/info`.
+- [ ] Para inserir log bruto sem gamificação, use `/v3/system/action/log` conscientemente (sem triggers/fireAction).