funifier-mcp 0.2.26 → 0.2.27

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

@@ -1,200 +1,669 @@
-# Leaderboard (Ranking)
+# `leaderboard`
 
 **Acesso Studio:** `/studio/leaderboard`
 **API Endpoint:** `/v3/leaderboard`
+**Coleção MongoDB:** `leaderboard`
+**Coleções auxiliares:** `leader` (resultado calculado), `leader_header` (metadados do cálculo), `expire` (controle de TTL do cache) — **compartilhadas com o módulo de crowning**.
 
-## O que é
+> Documentação de engenharia reversa. Baseada no código de `funifier-service` (commit `830037e`).
+> Classes principais: `LeaderBoard_V2`, `Operation`, `Period`, `Filter` (pacote `engine.crowning`); `Leader` (`engine.leader`); `LeaderBoardManager` (`engine.leader`); `CrowningManager` (`engine.crowning`); `LeaderboardRest` (`rest.v3.rest`).
 
-Rankings que comparam o desempenho dos jogadores por pontos, contagem de ações, atributos ou métricas customizadas. Podem ser individuais ou por equipe, em tempo real ou por período fixo.
+---
 
-## Técnica
+## 1. Visão Geral
 
-Leaderboard usa **sempre** `"techniques": ["GT03"]` — é o único código válido e é obrigatório.
+Leaderboard é um ranking que ordena **jogadores** ou **equipes** por um valor calculado a partir de dados de gamificação: contagem de ações, soma/média de atributos de ações, soma de conquistas (pontos, challenges, etc.) ou um KPI pré-preparado. O ranking é sempre relativo a um **período** (janela relativa ou intervalo fixo) e compara a posição atual com a do período anterior (`previous_position`, `move`).
 
-## Tabela de Referência dos Enums
+A entidade de configuração é `LeaderBoard_V2`, persistida na coleção `leaderboard`. O **resultado** do ranking não é calculado em cada requisição; ele é materializado na coleção `leader`, com metadados em `leader_header` e validade controlada por um registro na coleção `expire`. Quando o cache expira, o ranking é recalculado.
 
-### `principalType` — quem é rankeado
+### Particularidade arquitetural central: dois motores de cálculo distintos
 
-| Valor | Label |
-|---|---|
-| `0` | Player (jogadores individuais) |
-| `1` | Team (equipes) |
+O módulo possui **duas implementações independentes** de cálculo de líderes, acionadas por endpoints diferentes, com comportamentos divergentes. Entender essa divisão é o ponto mais importante deste módulo:
 
-### `operation.type` — como calcular o score
+| Motor | Endpoint | Classe / método | Triggers | Tipos de operação suportados | Cache (TTL default) |
+| --- | --- | --- | --- | --- | --- |
+| **A — V3 "leaders"** | `GET /v3/leaderboard/{id}/leaders` | `CrowningManager.calculateLeaderBoardV3` | dispara `before_render` e `after_render` | player: 1,2,3,10 (**type 4 quebra**); team: 1,2,3,4,10 | `+1h` |
+| **B — "aggregate"** | `POST /v3/leaderboard/{id}/leader/aggregate` | `LeaderBoardManager.findLiveLeadersAggregate` / `findCacheLeadersAggregate` | nenhum | player: 1,2,3,10 (**type 4 quebra**); team: 1,2,3,10 **mas filtro de equipe está hardcoded/quebrado** | `+3h` |
 
-| Valor | Label | Uso |
-|---|---|---|
-| `1` | Count Actions | Conta quantas vezes a action foi executada |
-| `2` | Sum of attributes | Soma um atributo numérico de uma action |
-| `3` | Sum achievements | Soma pontos/conquistas acumulados (**mais comum**) |
-| `4` | Average of attributes | Média de um atributo numérico de uma action |
-| `10` | Prepared KPI | Usa um KPI pré-configurado |
+Os dois motores **não compartilham cache** (usam chaves de referência diferentes na coleção `expire`) e produzem resultados com formatos de campo ligeiramente diferentes. Detalhes nas seções 2, 5 e 7.
 
-### `operation.achievement_type` — tipo de conquista (somente quando `operation.type = 3`)
+### Relação com outros módulos
 
-| Valor | Label |
-|---|---|
+- **`action`/`action_log`** — operações `Count Actions`, `Sum/Avg attribute` agregam sobre `action_log`.
+- **`achievement`** — operação `Sum achievements` agrega sobre a coleção `achievement` (pontos, challenges, levels, etc.).
+- **`team`/`team_player`** — rankings de equipe usam `team_player` (membros) e `team` (nome/imagem).
+- **`player`** — nomes e imagens dos jogadores; jogadores não registrados são removidos do resultado (motor A).
+- **`challenge_rule_prepared`** — operação `Prepared KPI` (type 10) executa um pipeline de agregação armazenado.
+- **`trigger`** — eventos `before_render`/`after_render` (somente motor A).
+- **`package`** — `PackageManager` exporta/importa leaderboards (`findAll`, `findById`, `addLeaderboard`, `delete`).
+- **`crowning`** — feature separada (coroamento de 1 posição) que compartilha o pacote, os helpers de cálculo e as coleções `leader`/`leader_header`/`expire`. **Não confundir** com leaderboard.
+
+---
+
+## 2. Arquitetura e Fluxos
+
+### 2.1 Pipeline de persistência (criar / atualizar / excluir)
+
+**Criar/atualizar** — `POST /v3/leaderboard` → `LeaderBoardManager.addLeaderboard` (`LeaderBoardManager.java:94`):
+
+1. Se `_id` ausente/vazio → gera `Guid.shortTimeMillis()`.
+2. `c.save(board)` na coleção `leaderboard` — **upsert/full-replace**, não patch.
+3. **Purga o cache do board** (side effect): remove de `leader` (`{boardId:#}`), de `expire` (`{extra.item:#}`) e de `leader_header` (`{board:#}`).
+4. Resposta: o próprio objeto com campos nulos removidos (`JsonUtil.toJsonRemoveNullFields`), status `201`.
+
+**Excluir** — `DELETE /v3/leaderboard/{id}` → `LeaderBoardManager.delete` (`LeaderBoardManager.java:108`): remove o board e executa a mesma purga das 3 coleções auxiliares. Status `204`.
+
+> Não há validação de `operation`, `period` ou `principalType` no insert. Configurações inválidas são aceitas silenciosamente e só falham no momento do cálculo (ver seções 5 e 7).
+
+### 2.2 Motor A — `GET /v3/leaderboard/{id}/leaders`
+
+`LeaderboardRest.findLeaders` (`LeaderboardRest.java:241`) → `CrowningManager.calculateLeaderBoardV3` (`CrowningManager.java:109`) + `findHeaderV3`.
+
+Sequência:
+
+1. **Monta período de consulta.** Se `time_amount`+`time_scale` informados → `Period` variável; senão se `start_date`+`end_date` → `Period` fixo; senão usa o `period` default do board. Esse período sobrescreve `board.period` e entra na **chave de cache** (`getSearchId`).
+2. `reference = getSearchId(board, sub)` = `"leaderboard_" + board.id + "_" + sub + "_" + board.period.toString()`.
+3. Busca `expire` por `{extra.reference:#}`.
+4. **Se cache expirou ou não existe:**
+   a. dispara trigger `before_render` na coleção `leaderboard`;
+   b. `calculateLeaderBoardLeadersIfNecessaryV3` (recalcula — ver 2.3);
+   c. dispara trigger `after_render`.
+5. Consulta a coleção `leader` por `{extra.cache: expire.id}`, aplica filtro de view, ordena por `position` e limita.
+6. Monta resposta com `leaderboard`, dados do header (`creation_datetime`, `expiration_datetime`, `start_datetime`, `end_datetime`, `operation_unit`) e `leaders`.
+
+#### Fluxo de cálculo — Motor A (`/leaders`)
+
+```mermaid
+flowchart TD
+    A["GET /{id}/leaders"] --> B["monta Period da query<br/>(time_scale/start_date) ou usa board.period"]
+    B --> C["reference = getSearchId(board, sub)"]
+    C --> D{"expire existe<br/>e não expirou?"}
+    D -- sim --> J["consulta coleção leader<br/>{extra.cache: expire.id}"]
+    D -- não --> E["trigger before_render"]
+    E --> F["calculateLeaderBoardLeadersIfNecessaryV3"]
+    F --> G["trigger after_render"]
+    G --> J
+    J --> K["aplica view (FRIENDS/MIDDLE)"]
+    K --> L["sort position + limit"]
+    L --> M["resposta: leaderboard + header + leaders"]
+```
+
+### 2.3 Recálculo do Motor A — `calculateLeaderBoardLeadersIfNecessaryV3`
+
+Método `synchronized` (`CrowningManager.java:196`):
+
+1. Cria registro `expire` se não existir (`extra.reference`, `extra.type="leaderboard"`, `extra.item=board.id`).
+2. Se expirado: remove `leader` antigos (`{extra.cache: expire.id}`).
+3. **Calcula faixas de tempo.** Trata **apenas** `TYPE_VARIABLE` e `TYPE_FIXED`. ⚠️ **`period.expression` é ignorado aqui** (diferente de `Period.getCurrentRange`, usado pelo Motor B).
+   - `currentRange` = janela atual; `previewRange` = janela anterior (mesmo tamanho, imediatamente antes).
+4. **Player** (`principalType=0`):
+   - `findPlayerIds(board.principals)` resolve principals (cada um pode ser jogador ou equipe) em ids de usuário; se vazio → todos.
+   - `excludePrincipals` = todos os `teamId` (remove equipes do ranking de jogadores).
+   - `calculatePlayerLeadersHelper(operation, currentRange, ...)` e idem para `previewRange`.
+   - Para cada líder: resolve `Player`, define `position` (1-based), `name`, `image` (`image.medium.url`), `boardId`, `extra.cache`. **Jogadores não encontrados na coleção `player` são descartados.**
+   - Calcula `previous_position`/`previous_total` cruzando com a janela anterior e define `move` (ver pseudocódigo).
+5. **Team** (`principalType=1`):
+   - `linkedTeams` é passado **vazio** (`new ArrayList<>()`, `CrowningManager.java:292` — `findAllTeamsByLeaderboard` comentado), então `calculateTeamLeadersHelper` usa **todas** as equipes.
+   - `board.principals` é **ignorado** para equipes.
+6. Salva cada `Leader` na coleção `leader`.
+7. Define `expire.expireAt` = `board.timeout` (keyword) ou **`+1h`** default.
+8. Monta `LeaderHeader` (datas + `unit`):
+   - `Sum achievements` → `unit = findOptionByTypeAndItem(achievement_type, item)`.
+   - `Count actions`/`Sum attribute` → `unit = {type:"action", item, title, image}` (+ `attribute` no caso de sum attribute).
+   - **Sem `unit` para `Avg attribute` (4) e `Prepared KPI` (10).**
+
+Pseudocódigo do cálculo de `move` (Motor A):
+
+```
+se position == previous_position:        move = "stop"
+senão se position < previous_position
+        OU previous_position == 0:       move = "up"     // novo entrante sobe
+senão se position > previous_position:   move = "down"
+```
+
+### 2.4 Motor B — `POST /v3/leaderboard/{id}/leader/aggregate`
+
+`LeaderboardRest.findAllLeadersAggregate` (`LeaderboardRest.java:352`). Aceita um corpo JSON com **estágios de agregação extras** (array) que são anexados ao pipeline do ranking.
+
+```mermaid
+flowchart TD
+    A["POST /{id}/leader/aggregate?live="] --> B{"live=true?"}
+    B -- "true" --> C["findLiveLeadersAggregate<br/>(pipeline Mongo em tempo real)"]
+    B -- "false (default)" --> D["findCacheLeadersAggregate"]
+    D --> E{"cache válido?"}
+    E -- não --> F["recalcula via findLiveLeadersAggregate<br/>insere em leader em lotes de 5000"]
+    E -- sim --> G["$match {extra.cache: expire.id}"]
+    F --> G
+    C --> H["applyViewLeadersAggregate (FRIENDS/MIDDLE)"]
+    G --> H
+    H --> I["anexa estágios de agregação do corpo"]
+    I --> J["PaginationUtil (Range header) → resposta paginada"]
+```
+
+- **`live=true`** → `findLiveLeadersAggregate` (`LeaderBoardManager.java:302`): monta o pipeline Mongo completo em tempo real (não persiste).
+- **`live=false` / ausente** → `findCacheLeadersAggregate` (`LeaderBoardManager.java:146`):
+  - `reference = "leaderboard_" + id` (+ `"_" + period` se `period` informado). ⚠️ **Chave diferente da do Motor A.**
+  - Se expirado: cria/atualiza `expire`, recalcula via `findLiveLeadersAggregate`, remove `leader` antigos (`{extra.cache: expire.id}`), insere os novos **em lotes de 5.000** na coleção `leader`. TTL = `board.timeout` ou **`+3h`** default.
+  - Retorna `$match {extra.cache: expire.id}` sobre `leader`.
+
+Estrutura interna do pipeline `findLiveLeadersAggregate` (por operação): um `$facet` com `p1` (janela atual) e `p2` (janela anterior), `$group` por jogador/equipe, ordenação com desempate por `time`, `$unwind` com `includeArrayIndex` para gerar `position`, `$cmp` para calcular `move`, `$lookup` em `player`/`team` para nome/imagem (`image.small.url`), e marcação `extra.cache` + `_id` composto `"<id>_<cache>"`.
+
+Cálculo de `move` no Motor B: `move = $cmp(prev_pos, position)` com `prev_pos` default `9999999` quando nulo → `1`→`"up"`, `0`→`"stop"`, `-1`→`"down"`.
+
+### 2.5 Interação entre componentes (Motor A)
+
+```mermaid
+sequenceDiagram
+    participant C as Cliente
+    participant R as LeaderboardRest
+    participant CM as CrowningManager
+    participant T as TriggerManager
+    participant DB as MongoDB (leader/expire/leader_header)
+
+    C->>R: GET /{id}/leaders
+    R->>CM: calculateLeaderBoardV3(board, sub, ...)
+    CM->>DB: findOne expire {extra.reference}
+    alt cache expirado
+        CM->>T: execute(board, "before_render")
+        CM->>CM: calculateLeaderBoardLeadersIfNecessaryV3
+        CM->>DB: remove + save leaders, save expire, save header
+        CM->>T: execute(board, "after_render")
+    end
+    CM->>DB: aggregate leader {extra.cache}
+    CM-->>R: List<Leader>
+    R->>CM: findHeaderV3(board, sub)
+    R-->>C: { leaderboard, header, leaders }
+```
+
+---
+
+## 3. Estrutura dos Objetos
+
+### 3.1 `LeaderBoard_V2` — documento raiz (coleção `leaderboard`)
+
+| Campo | Tipo | Padrão | Obrigatório | Descrição |
+| --- | --- | --- | --- | --- |
+| `_id` | String | auto (`Guid.shortTimeMillis()` se ausente) | — | Identificador. POST com `_id` existente faz **full replace**. |
+| `title` | String | — | recomendado | Título exibido. |
+| `description` | String | — | não | Descrição. **Persiste, mas não tem getter/setter** (acesso por campo via Jackson). |
+| `principalType` | int | `0` | sim (na prática) | `0` = Player, `1` = Team. |
+| `operation` | `Operation` | — | sim (para cálculo) | Define como calcular o valor. Ver 3.2. |
+| `period` | `Period` | — | sim (para cálculo) | Janela de tempo do ranking. Ver 3.3. |
+| `principals` | List<String> | `null` | não | Restringe o escopo a jogadores/equipes específicos. **Usado só em rankings de player; ignorado em team.** |
+| `techniques` | List<String> | `null` | não | Códigos de técnica (GT). Backfill automático com `GT03` por rotina de manutenção (ver 3.8). |
+| `timeout` | String | `null` | não | Expressão keyword de TTL do cache (ex.: `30m`, `3h`, `1d`). Sem ele: `+1h` (motor A) ou `+3h` (motor B). |
+| `extra` | Map<String,Object> | `{}` | não | Mapa de extensão **livre**. Persistido, mas **nenhuma chave é consumida** pelo motor de cálculo. |
+
+Campos do schema **não consumidos em runtime**: `extra` (apenas armazenado).
+Não há campos computados persistidos no documento raiz.
+
+### 3.2 `Operation` — fórmula de cálculo
+
+| Campo | Tipo | Obrigatório | Descrição |
+| --- | --- | --- | --- |
+| `type` | int | sim | Tipo de operação (enum abaixo). |
+| `achievement_type` | int | quando `type=3` | Tipo de conquista (enum abaixo). |
+| `item` | String | depende | `type=3`: `_id` do ponto/conquista; `type=1/2/4`: `_id` da action. |
+| `attribute` | String | quando `type=2/4` | Nome do atributo numérico da action a somar/mediar. **É `attribute`, NÃO `kpi`.** |
+| `filters` | List<`Filter`> | não | Filtros sobre `attributes.*` da action (ver 3.4). |
+| `sort` | int | não | `-1` = maior primeiro (desc), `1` = menor primeiro (asc). Qualquer valor ≠ 1 vira `-1`. |
+| `sub` | boolean | não | Habilita **sub-rankings** por atributo de action. Ver correção em 3.7. |
+| `subAttribute` | String | quando `sub=true` | Atributo da action que define o sub-ranking (ex.: `restaurante`). |
+| `prepared` | String | quando `type=10` | `_id` de um `challenge_rule_prepared` (pipeline de agregação). |
+
+**`operation.type` (enum, `Operation.java`):**
+
+| Valor | Constante | Significado | Coleção agregada |
+| --- | --- | --- | --- |
+| `1` | TYPE_COUNT_ACTIONS | Conta execuções da action | `action_log` |
+| `2` | TYPE_SUM_ATTRIBUTE | Soma `attributes.<attribute>` da action | `action_log` |
+| `3` | TYPE_SUM_ACHIEVEMENTS | Soma o `total` de conquistas | `achievement` |
+| `4` | TYPE_AVG_ATTRIBUTE | Média `attributes.<attribute>` | `action_log` |
+| `10` | TYPE_PREPARED_KPI | Executa pipeline `prepared` | `prepared.entity` |
+
+> ⚠️ `type=4` (média) **não é uniformemente suportado** — ver seção 7.
+
+**`operation.achievement_type` (usado direto como `type` no match de `achievement`; aceita todo o enum de `Achievement`):**
+
+| Valor | Significado |
+| --- | --- |
+| `-1` | ACHIEVEMENT_TYPE_NONE — não filtra por tipo |
 | `0` | Point |
 | `1` | Challenge |
 | `2` | Catalog Item |
 | `3` | Level |
+| `4` | Crown |
 | `5` | Lottery |
+| `6` | Mystery Box |
+| `7` | Character Star Stat |
+| `8` | Bonus |
 | `9` | Competition |
+| `50` | Lottery Ticket |
+| `99` | Custom |
+
+Legado: a constante `subType` está comentada no código (`Operation.java:38`) — funcionalidade não existe.
+
+### 3.3 `Period` — janela de tempo
 
-### `operation.item` — o que rankear
+| Campo | Tipo | Descrição |
+| --- | --- | --- |
+| `type` | int | `0` = Variable (relativa), `1` = Fixed (intervalo). |
+| `timeAmount` | int | Quantidade de unidades (variable). |
+| `timeScale` | int | Escala (variable): `4`=Hour, `5`=Day, `6`=Week, `7`=Month, `8`=Year (`TimeScale`). |
+| `startDate` | Date | Início (fixed). |
+| `endDate` | Date | Fim (fixed). |
+| `expression` | String | Expressão keyword (v3) ex.: `-0M-;+3d` (start;end). |
 
-- Quando `operation.type = 3` e `achievement_type = 0` (Point): use o `_id` do ponto (ex: `"xp"`, `"coin"`)
-- Quando `operation.type = 1, 2 ou 4` (action-based): use o `_id` da action
+Resolução de faixa (`Period.getCurrentRange`): **`expression` tem prioridade** (se `length > 5`), depois `Variable`, depois `Fixed`.
+⚠️ **`expression` só é honrada pelo Motor B e por `getCurrentRange`. O Motor A (`/leaders`) ignora `expression`** e trata apenas `Variable`/`Fixed` (`CrowningManager.java:225`).
 
-### `operation.sort` — ordem do ranking
+### 3.4 `Filter` — filtro de atributo de action
 
-| Valor | Label |
-|---|---|
-| `-1` | With more — maior valor primeiro (padrão) |
-| `1` | With less — menor valor primeiro |
+| Campo | Tipo | Descrição |
+| --- | --- | --- |
+| `param` | String | Nome do atributo. Aplicado como `attributes.<param>`. |
+| `operator` | int | Operador (tabela abaixo). |
+| `value` | String | Valor (numérico se parseável, senão string). |
 
-### `operation.sub` — saldo líquido
+`operator` — **somente estes são tratados** por `buildJsonFilter` (`CrowningManager.java:1279`):
 
-| Valor | Comportamento |
-|---|---|
-| `false` | Total bruto acumulado (padrão) |
-| `true` | Saldo líquido — desconta débitos (útil para pontos trocáveis GT75) |
+| Valor | Operador | Mongo |
+| --- | --- | --- |
+| `1` | Equal | igualdade direta |
+| `3` | Regex (Contains) | `$regex` |
+| `4` | Greater Than | `$gt` |
+| `5` | Greater Than or Equal | `$gte` |
+| `6` | Less Than | `$lt` |
+| `7` | Less Than or Equal | `$lte` |
 
-### `period.type` — tipo de período
+> ⚠️ Operadores existentes em `Operator` mas **não tratados** (`2`=Like, `8`=Not Equal, `9`=Exist, `10`=Not Exist, `20`=Max Distance, `40`=Mod) geram uma cláusula JSON malformada (`{attributes.<param>: }`) que **quebra o parse do pipeline**. Ver seção 7.
+> Filtros **não são aplicados** quando `operation.type=3` (Sum achievements) — o branch de achievements não anexa `buildJsonFilter`.
 
-| Valor | Label | Comportamento |
-|---|---|---|
-| `0` | Variable | Janela relativa: últimos N períodos (ex: última semana) |
-| `1` | Fixed | Intervalo fixo com data de início e fim |
+### 3.5 `Leader` — registro calculado (coleção `leader`, somente leitura)
 
-### `period.timeScale` — escala de tempo
+Saída do cálculo; **não é criado manualmente**.
 
-| Valor | Label |
-|---|---|
-| `4` | Hour |
-| `5` | Day |
-| `6` | Week |
-| `7` | Month |
-| `8` | Year |
+| Campo | Tipo | Descrição |
+| --- | --- | --- |
+| `_id` | String | Motor A: GUID. Motor B: composto `"<principalId>_<cache>"`. |
+| `boardId` | String | `_id` do leaderboard. |
+| `player` | String | Id do jogador ou da equipe. |
+| `name` | String | Nome do jogador/equipe. |
+| `image` | String | URL da imagem. Varia por branch: player ~ `image.medium` (Motor A) / `image.small` (Motor B); equipes e paths `Prepared KPI` usam `image.original`. |
+| `position` | int | Posição atual (1-based). |
+| `total` | **long** | Valor agregado. ⚠️ Tipo inteiro — ver nota. |
+| `previous_position` | int | Posição na janela anterior (`0` se ausente). |
+| `previous_total` | long | Total na janela anterior. |
+| `move` | String | `up` / `down` / `stop`. |
+| `sub` | String | Valor do sub-ranking (quando aplicável). |
+| `period` | `Period` | Período do cálculo (geralmente não populado). |
+| `extra.cache` | String | Id do `expire` que originou o registro (chave de cache). |
 
-`period.timeAmount` = quantidade de unidades (ex: `timeAmount: 1, timeScale: 6` = última semana).
+> **Nota sobre `total` (long):** `$sum`/`$avg` sobre atributos decimais retornam `double`, mas `Leader.total` é `long`. O comportamento exato na desserialização (truncamento) **não foi verificado** — valide para casos com valores fracionários, especialmente `Avg attribute`.
 
-### `operation.filters[].operator` — filtros de action
+### 3.6 `LeaderHeader` — metadados do cálculo (coleção `leader_header`)
 
-| Valor | Label |
-|---|---|
-| `1` | Equals |
-| `3` | Contains (Regex) |
-| `4` | Greater Than |
-| `5` | Greater Than or Equal |
-| `6` | Less Than |
-| `7` | Less Than or Equal |
+| Campo | Tipo | Descrição |
+| --- | --- | --- |
+| `_id` | String | = `expire.id`. |
+| `board` | String | Id do leaderboard/crown. |
+| `creation_datetime` | String | Quando foi calculado (ISO zoned). |
+| `expiration_datetime` | String | Quando expira/recalcula. |
+| `start_datetime` | String | Início da faixa de registros usada. |
+| `end_datetime` | String | Fim da faixa. |
+| `unit` | Map | Unidade do valor (ponto/action). Ausente para `type=4` e `type=10`. |
 
-## Exemplos por caso de uso
+### 3.7 Correção: `sub`/`subAttribute` ≠ saldo líquido
 
-### Ranking por pontos (caso mais comum)
+⚠️ Documentações anteriores descreviam `operation.sub=true` como "saldo líquido — desconta débitos (GT75)". **Isto está incorreto.** No código, `sub`+`subAttribute` habilitam **sub-rankings filtrados por um atributo da action** (ex.: ranking por restaurante). O filtro é aplicado em `getSubValueFilter` / nos helpers, combinando `subAttribute` (config) com o query param `sub` (valor). As classes `Lost`/`LostDebit`/`LostManager` **não têm nenhuma relação** com leaderboard.
+
+### 3.8 Técnica de jogo (`techniques`)
+
+- Código relevante: **`GT03`** (LEADERBOARD_CODE).
+- **Não é obrigatório no insert** e `addLeaderboard` não o define nem valida.
+- É preenchido automaticamente por `GameTechniqueManager.autoConfigureMissingTechniqueFields()` (rotina de manutenção): boards sem `techniques` recebem `["GT03"]`. Serve para categorização/mapa de técnicas no Studio.
+
+---
+
+## 4. Endpoints
+
+Todos exigem `Authorization: Bearer <token>` (via `AuthBean`).
+
+### `POST /v3/leaderboard`
+
+| Aspecto | Detalhe |
+| --- | --- |
+| Finalidade | Cria ou substitui um leaderboard |
+| Full replace ou patch | **Full replace** (`c.save`) — envie o objeto completo |
+| Comportamento real | Gera `_id` se ausente; **purga** `leader`/`expire`/`leader_header` do board; resposta sem campos nulos; status `201` |
 
 ```json
 {
-  "title": "Top Players",
-  "description": "Jogadores com mais XP na semana",
+  "title": "General",
   "principalType": 0,
-  "operation": {
-    "type": 3,
-    "achievement_type": 0,
-    "item": "xp",
-    "sort": -1,
-    "sub": false,
-    "filters": []
-  },
-  "period": { "type": 0, "timeAmount": 1, "timeScale": 6 },
-  "techniques": ["GT03"]
+  "operation": { "type": 3, "achievement_type": 0, "item": "xp", "sort": -1, "sub": false, "filters": [] },
+  "period": { "type": 0, "timeAmount": 1, "timeScale": 7 },
+  "principals": []
 }
 ```
 
-### Ranking mensal por equipe
+### `DELETE /v3/leaderboard/{id}`
+
+Remove o board e purga as 3 coleções auxiliares. Status `204`.
+
+### `GET /v3/leaderboard`
+
+Lista/filtra leaderboards (pipeline de agregação).
+
+| Param | Tipo | Descrição |
+| --- | --- | --- |
+| `id` | String | Filtra por `_id` |
+| `title` | String | Filtra por título (`$regex`, case-insensitive) |
+| `type` | String | `"team"` → `principalType=1`; qualquer outro → `0` |
+| `fields` | String | Projeção: campos separados por vírgula (`$project`) |
+| `orderby` | String | Campo de ordenação (injetado direto no `$sort` — ver seção 8) |
+| `reverse` | boolean | `true` → ordem descendente |
+| `max_results` | int | Limite (default `100`) |
+
+### `GET /v3/leaderboard/{id}`
+
+Retorna a configuração do board (sem campos nulos).
+
+### `GET /v3/leaderboard/{id}/leaders` — **Motor A**
+
+| Aspecto | Detalhe |
+| --- | --- |
+| Finalidade | Retorna o ranking calculado (com cache, triggers `before/after_render`) |
+| Comportamento real | Recalcula se cache expirou; TTL default `+1h`; ignora `period.expression` |
+
+| Query param | Tipo | Descrição |
+| --- | --- | --- |
+| `player` | String | Jogador de referência (`"me"` resolve do token); obrigatório para `view=1/2` |
+| `team` | String | Restringe a membros de uma equipe |
+| `sub` | String | Valor do sub-ranking |
+| `time_amount` + `time_scale` | int | Período variável que sobrescreve o default |
+| `start_date` + `end_date` | String (RFC 3339 ou keyword) | Período fixo |
+| `max_results` | int | Limite (default `100`) |
+| `view` | int | `0`=Default, `1`=Middle (vizinhos), `2`=Friends |
 
 ```json
 {
-  "title": "Top Teams - Month",
-  "principalType": 1,
-  "operation": {
-    "type": 3,
-    "achievement_type": 0,
-    "item": "xp",
-    "sort": -1,
-    "sub": false,
-    "filters": []
-  },
-  "period": { "type": 0, "timeAmount": 1, "timeScale": 7 },
-  "techniques": ["GT03"]
+  "leaderboard": { "_id": "...", "title": "...", "operation": {...} },
+  "creation_datetime": "2026-05-20T10:00:00-03:00",
+  "expiration_datetime": "2026-05-20T11:00:00-03:00",
+  "start_datetime": "2026-05-13T00:00:00-03:00",
+  "end_datetime": "2026-05-20T23:59:59-03:00",
+  "operation_unit": { "type": "point", "item": "xp" },
+  "leaders": [
+    { "player": "ana@x.com", "name": "Ana", "position": 1, "total": 100, "previous_position": 2, "previous_total": 80, "move": "up" }
+  ]
 }
 ```
 
-### Ranking por contagem de ações
+### `POST /v3/leaderboard/{id}/leader/aggregate` — **Motor B**
+
+| Aspecto | Detalhe |
+| --- | --- |
+| Finalidade | Retorna o ranking permitindo **estágios de agregação extras** no corpo |
+| Comportamento real | `live=true` calcula em tempo real; default usa/gera cache (TTL `+3h`); paginação via header `Range` |
+
+| Query param | Tipo | Descrição |
+| --- | --- | --- |
+| `live` | boolean | `true` = tempo real; default = cache |
+| `strict` | boolean | `true` = serialização via Gson |
+| `player` | String | Referência para view (`"me"` resolve do token) |
+| `view` | int | `0`/`1`/`2` (default/middle/friends) |
+| `limit` | int | Limite (default `100`) |
+| `period` | String | Expressão keyword de período |
+| `Range` (header) | String | Paginação, ex.: `items=0-99` |
+
+Corpo: array JSON de estágios de agregação Mongo anexados ao final do pipeline. Ex.: `[{"$match": {"total": {"$gte": 10}}}]`.
+
+### `GET /v3/leaderboard/reset`
+
+`CrowningManager.reset` → **dropa as coleções `expire`, `leader_header` e `leader` inteiras**. Afeta **todos** os leaderboards e crownings do tenant. Ver seção 5.
+
+> Legado: existe um endpoint antigo `GET /2.0.0/leaderboard/reset` (`rest.engine.LeaderboardRest`) — apenas reset, API v2 obsoleta.
+
+---
+
+## 5. Regras de Negócio
+
+Regras presentes no código e ausentes do schema:
+
+- **Validação deferida.** `addLeaderboard` não valida `type`/`item`/`period`/`principalType`. Configurações inválidas são aceitas no insert e só falham (ou retornam vazio) no cálculo.
+- **TTL de cache diverge por motor:** Motor A default `+1h`, Motor B default `+3h`. Com `board.timeout` definido, ambos usam a expressão (com `+` forçado). Operadores que consomem os dois endpoints veem janelas de atualização diferentes.
+- **Caches separados por motor.** As chaves de `expire.extra.reference` são diferentes (`leaderboard_<id>_<sub>_<period>` no A; `leaderboard_<id>[_<period>]` no B). Recalcular por um endpoint não atualiza o cache do outro.
+- **Somente jogadores registrados aparecem** (Motor A): líderes sem `Player` correspondente são descartados.
+- **Equipes são excluídas de rankings de player** (`$nin` sobre todos os `teamId`).
+- **`principals` é ignorado em rankings de equipe** (`linkedTeams` vazio → todas as equipes).
+- **Filtros não se aplicam a `Sum achievements`** (type 3).
+- **Sub-ranking** exige `operation.sub=true` **e** `operation.subAttribute` **e** o query param `sub`; o tipo do valor é convertido conforme o tipo do atributo da action (number/boolean/string).
+- **Ordenação com desempate:** empates em `total` são desempatados pelo `time` mais recente (`max:1`).
+- **Isolamento multi-tenant:** toda operação resolve o cliente por `apiKey` (`FrontController.getInstance(apiKey)`), apontando para o banco do tenant.
+- **Consistência eventual:** o ranking exibido é o do último cálculo; mudanças em ações/conquistas só refletem após expiração do cache ou `reset`.
+
+---
+
+## 6. Comportamentos Automáticos
+
+| Comportamento | Trigger | Impacto | Persistência |
+| --- | --- | --- | --- |
+| Geração de `_id` | POST sem `_id` | `Guid.shortTimeMillis()` | Sim |
+| Purga de cache | POST/DELETE do board | Remove `leader`/`expire`/`leader_header` do board | Sim (remoção) |
+| Backfill de técnica | `autoConfigureMissingTechniqueFields()` (manutenção) | Adiciona `GT03` a boards sem `techniques` | Sim |
+| Trigger `before_render` | Cache expirado, **Motor A** | Executa triggers da coleção `leaderboard` antes do cálculo | Conforme trigger |
+| Trigger `after_render` | Após recálculo, **Motor A** | Executa triggers depois do cálculo | Conforme trigger |
+| Recálculo + cache | Cache expirado, qualquer motor | Materializa `leader`, grava `expire`/`leader_header` | Sim |
+| Cálculo de `move` | Cada cálculo | Compara posição atual vs anterior (`up`/`down`/`stop`) | Sim (no `leader`) |
+| Inserção em lote | Recálculo Motor B | Insere `leader` em lotes de 5.000 | Sim |
+
+### Fluxo de behaviors automáticos (recálculo)
+
+```mermaid
+flowchart LR
+    A["cache expirado"] --> B{"motor?"}
+    B -- "A (/leaders)" --> C["before_render"]
+    C --> D["calcula líderes"]
+    D --> E["salva leader/expire/header"]
+    E --> F["after_render"]
+    B -- "B (aggregate)" --> G["calcula pipeline"]
+    G --> H["insere leader em lotes de 5000"]
+```
+
+> **Código legado/aparente bug:** em `findCacheLeadersAggregate` (`LeaderBoardManager.java:230-233`) há um bloco que **sempre** reatribui `a = aggregate({$match:{extra.cache: expire.id}})` logo após o bloco condicional. É redundante (mesmo resultado), mas chama atenção numa primeira leitura.
+
+---
+
+## 7. Suportado vs NÃO Suportado
+
+### ✅ Suportado
+
+- Rankings de **player** e **team** (motor A).
+- Operações: Count actions (1), Sum attribute (2), Sum achievements (3), Prepared KPI (10).
+- `Avg attribute` (4) **apenas para team via `/leaders`**.
+- Períodos variáveis e fixos; `expression` (apenas Motor B).
+- Filtros de atributo com operadores `1,3,4,5,6,7`.
+- Sub-rankings por atributo de action.
+- Views: default, middle (vizinhos), friends.
+- Estágios de agregação customizados no corpo do `/leader/aggregate`.
+- Cache com TTL configurável (`timeout`).
+- Comparação com período anterior (`previous_*`, `move`).
+
+### ❌ NÃO Suportado / quebrado
+
+- **Rankings de equipe via `/leader/aggregate` (Motor B):** o `$match` de equipe está **hardcoded** como `{"team":{"$in":["t1","t2"]}}` em todos os branches de team (`LeaderBoardManager.java:398, 414, 490, 506, 581, 596`). Resultado: só retorna equipes literalmente chamadas `t1`/`t2` — na prática, **vazio**. Use o Motor A (`/leaders`) para equipes.
+- **`Avg attribute` (4) para player:** `calculatePlayerLeadersHelper` (Motor A) e `findLiveLeadersAggregate` (Motor B) **não têm branch para type 4**. No Motor A, a execução chega a `a.and(...)` com `a==null` (`CrowningManager.java:921`) → **NullPointerException**. (O helper singular `calculatePlayerLeaderHelper`, que suporta avg, é usado só pelo `BonusManager`, não por leaderboard.)
+- **`Prepared KPI` (10) sem `prepared` válido:** `a` permanece nulo → mesmo NPE/erro.
+- **`period.expression` no Motor A (`/leaders`):** ignorada — só `Variable`/`Fixed` são tratados.
+- **Operadores de filtro `2,8,9,10,20,40`:** não tratados em `buildJsonFilter`; produzem JSON malformado e quebram o pipeline.
+- **Filtros em `Sum achievements` (3):** silenciosamente não aplicados.
+- **Validação no insert:** inexistente — configs inválidas passam por POST/GET sem erro e só falham no cálculo.
+- **`board.extra`:** persistido, mas nenhuma chave é lida pelo motor.
+- **`description`:** persiste, mas sem getter/setter (não exposto programaticamente além do campo).
+- **Totais decimais:** `Leader.total` é `long` — soma/média de atributos fracionários pode truncar (não verificado).
+- **Endpoint legado `2.0.0/leaderboard`:** somente `/reset`.
+
+---
+
+## 8. Segurança e Permissões
+
+- **Autenticação:** Bearer token via `AuthBean` em todos os endpoints. `player="me"` resolve o jogador do token.
+- **Isolamento multi-tenant:** `FrontController.getInstance(apiKey)` direciona para o banco do tenant; leaderboards, leaders e cache são por tenant.
+- **`GET /reset` é destrutivo e global:** dropa `expire`, `leader_header` e `leader` inteiras — afeta todos os rankings e crownings do tenant. Não há filtro por board.
+- **Superfícies de injeção (concatenação de string em queries Mongo):**
+
+| Origem | Local | Risco |
+| --- | --- | --- |
+| `orderby` (query param) | `{$sort:{<orderby>:...}}` (`LeaderBoardManager.java:88`) | Campo injetado cru no `$sort` |
+| `operation.attribute` | `$sum/$avg:'$attributes.<attribute>'` (vários) | Caminho de campo injetado cru |
+| `operation.subAttribute` + `sub` | `attributes.<subAttribute>` (`getSubValueFilter`, helpers) | Nome e valor injetados crus |
+| `Filter.param` / `Filter.value` | `buildJsonFilter` (`CrowningManager.java:1279`) | Pode injetar operadores Mongo; valor não-numérico só é "quotado", sem sanitização |
+| corpo de `/leader/aggregate` | estágios anexados ao pipeline | Permite agregação arbitrária sobre `leader` (escopo do tenant) |
+| `prepared` (type 10) | pipeline armazenado em `challenge_rule_prepared` | Executa agregação arbitrária definida na config |
+
+> Esses campos vêm de configuração administrativa (Studio) ou de tokens autenticados do tenant; ainda assim, são concatenados sem sanitização — tratar como superfície de injeção dentro do escopo do tenant.
+
+---
+
+## 9. Observabilidade e Troubleshooting
+
+### Diagnóstico
+
+1. Confirme a configuração: `GET /v3/leaderboard/{id}`.
+2. Force recálculo do cache: `GET /v3/leaderboard/reset` (⚠️ global — derruba o cache de tudo).
+3. Compare os dois motores: se `/leaders` retorna dados e `/leader/aggregate` não (em board de equipe), é o bug do `t1/t2`.
+
+### Inspeção direta no MongoDB
+
+```js
+// configuração
+db.leaderboard.findOne({_id: "<id>"})
+
+// registros de cache do ranking (resultado materializado)
+db.leader.find({boardId: "<id>"}).sort({position: 1})
+
+// metadados/validade do cálculo
+db.expire.find({"extra.item": "<id>"})
+db.leader_header.find({board: "<id>"})
+```
+
+### Erros comuns e causas
+
+| Sintoma | Causa provável |
+| --- | --- |
+| Ranking vazio em board de **equipe** via `/leader/aggregate` | Bug do filtro hardcoded `t1/t2` — use `/leaders` |
+| `500`/NPE ao consultar `/leaders` | `operation.type=4` em board de **player**, ou `type=10` sem `prepared` válido |
+| Pipeline quebra / erro de parse | Filtro com operador não suportado (`2,8,9,10,...`) |
+| Período "errado" só em `/leaders` | `period.expression` ignorada nesse motor — use `Variable`/`Fixed` |
+| Scores zerados | `operation.item` incorreto (`_id` do ponto/action, não o nome) ou `achievement_type` divergente |
+| Resultados desatualizados | Cache ainda válido (TTL `+1h`/`+3h`); aguarde ou `reset` |
+| Jogador não aparece | Sem `Player` registrado, ou é uma equipe num board de player, ou fora de `principals` |
+
+### Comandos de verificação
+
+```
+GET /v3/leaderboard/<id>
+GET /v3/leaderboard/<id>/leaders?max_results=10
+POST /v3/leaderboard/<id>/leader/aggregate?live=true   (body: [])
+GET /v3/leaderboard/reset
+```
+
+---
+
+## 10. Exemplos Práticos
+
+### Exemplo mínimo — ranking de pontos por semana
 
 ```json
 {
-  "title": "Mais Vendas",
+  "title": "Top XP - Semana",
   "principalType": 0,
-  "operation": {
-    "type": 1,
-    "item": "sell",
-    "sort": -1,
-    "filters": []
-  },
-  "period": { "type": 0, "timeAmount": 1, "timeScale": 5 },
-  "techniques": ["GT03"]
+  "operation": { "type": 3, "achievement_type": 0, "item": "xp", "sort": -1 },
+  "period": { "type": 0, "timeAmount": 1, "timeScale": 6 }
 }
 ```
 
-### Ranking por soma de atributo numérico
+### Exemplo avançado — sub-ranking por atributo, com filtro e timeout
+
+Ranking de receita (`Sum attribute`) por loja, somente vendas acima de 100, cache de 30 min:
 
 ```json
 {
-  "title": "Maior Receita",
+  "title": "Receita por Loja",
   "principalType": 0,
+  "timeout": "30m",
   "operation": {
     "type": 2,
-    "item": "sell",
-    "kpi": "price",
+    "item": "venda",
+    "attribute": "valor",
+    "sub": true,
+    "subAttribute": "loja",
     "sort": -1,
-    "filters": []
+    "filters": [
+      { "param": "valor", "operator": 5, "value": "100" }
+    ]
   },
-  "period": { "type": 0, "timeAmount": 1, "timeScale": 6 },
-  "techniques": ["GT03"]
+  "period": { "type": 0, "timeAmount": 1, "timeScale": 7 }
 }
 ```
 
-## API Endpoints
+Consulta de um sub-ranking específico:
 
-### Listar Leaderboards
-**Método:** GET — `/v3/leaderboard`
-
-### Criar / Atualizar
-**Método:** POST — `/v3/leaderboard`
+```
+GET /v3/leaderboard/<id>/leaders?sub=Loja-Centro&max_results=20
+```
 
-### Excluir
-**Método:** DELETE — `/v3/leaderboard/:id`
+### Exemplo de equipe — usar o motor correto
 
-### Obter líderes
-**Método:** POST — `/v3/leaderboard/:id/leader/aggregate?period=&live=true`
+```json
+{
+  "title": "Top Equipes - Mês",
+  "principalType": 1,
+  "operation": { "type": 3, "achievement_type": 0, "item": "xp", "sort": -1 },
+  "period": { "type": 0, "timeAmount": 1, "timeScale": 7 }
+}
+```
 
-### Resetar cache
-**Método:** GET — `/v3/leaderboard/reset`
+Consulta (✅ use `/leaders`; ❌ não use `/leader/aggregate` para equipes):
 
-## Troubleshooting
+```
+GET /v3/leaderboard/<id>/leaders
+```
 
-- **Ranking vazio**: verifique se o `operation.item` é o `_id` do ponto/action — não o `category` nem o nome amigável
-- **Scores errados**: confirme `operation.type` e `achievement_type` — usar `type: 3` com `achievement_type: 0` é o caminho para pontos
-- **Período incorreto**: `timeScale: 6` = semana, `timeScale: 7` = mês — fácil de confundir
-- **Cache desatualizado**: use `GET /v3/leaderboard/reset` para forçar recálculo
+### Anti-pattern — o que NÃO fazer
 
-## Checklist
+```json
+{
+  "title": "Média de Vendas (player)",
+  "principalType": 0,
+  "operation": { "type": 4, "item": "venda", "attribute": "valor", "sort": -1 },
+  "period": { "type": 0, "timeAmount": 1, "timeScale": 6 }
+}
+```
 
-- [ ] `techniques: ["GT03"]` presente
-- [ ] `principalType` definido (0=jogador, 1=equipe)
-- [ ] `operation.type` correto para o caso de uso
-- [ ] `operation.item` é o `_id` do ponto ou action (não o nome amigável)
-- [ ] `period.type` e `period.timeScale` configurados
-- [ ] Confirmado com `funifier_list type=leaderboard search=<título>`
+❌ `type=4` (Avg) em board de **player** causa **NullPointerException** ao consultar `/leaders` (não há branch para média no helper de jogadores). Alternativas: usar `Sum attribute` (2), ou um `Prepared KPI` (10) que calcule a média, ou aplicar a média via estágio extra no `/leader/aggregate`.
+
+Outros anti-patterns:
+- Usar `"kpi"` em vez de `"attribute"` para somar atributo — o campo correto é **`attribute`** (`kpi` é ignorado).
+- Esperar que `/leader/aggregate` traga equipes — está quebrado (`t1/t2`).
+- Confiar em `operation.sub` para "saldo líquido" — `sub` é sub-ranking por atributo, não desconto de débitos.
+- Usar operador de filtro `2`/`8` — quebra o pipeline.
+
+---
+
+## Checklist de Configuração
+
+- [ ] `principalType` definido (`0` player, `1` team).
+- [ ] `operation.type` válido para o motor que você vai consultar (evite `type=4` em player).
+- [ ] `operation.item` = `_id` do ponto/action (não o nome amigável).
+- [ ] `operation.type=3` → `achievement_type` correto (ex.: `0` para pontos).
+- [ ] `operation.type=2/4` → use **`attribute`** (não `kpi`).
+- [ ] `operation.type=10` → `prepared` aponta para um `challenge_rule_prepared` existente.
+- [ ] `period.type` + (`timeAmount`/`timeScale`) ou (`startDate`/`endDate`) preenchidos. `expression` só funciona no `/leader/aggregate`.
+- [ ] Filtros usam apenas operadores `1,3,4,5,6,7`.
+- [ ] Sub-ranking: `sub=true` **e** `subAttribute` definidos; passe o valor em `?sub=`.
+- [ ] Para equipes, consulte por **`/leaders`** (não `/leader/aggregate`).
+- [ ] Ciente de que POST faz **full replace** e **purga o cache** do board.
+- [ ] Ciente de que `GET /reset` é **global e destrutivo**.
+- [ ] Armadilha: omitir `timeout` deixa TTL em `+1h` (`/leaders`) ou `+3h` (`/leader/aggregate`).