funifier-mcp 0.2.26 → 0.2.28

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

@@ -1,149 +1,851 @@
-# Competition (Competição)
+# `competition`
 
 **Acesso Studio:** `/studio/competition`
 **API Endpoint:** `/v3/competition`
+**Coleção MongoDB:** `competition` (configuração) + `competition_join` (inscrições)
 
-## O que é
+---
 
-Configuração de disputas diretas entre jogadores ou equipes. Permite criar competições com regras próprias, prêmios para diferentes posições e critérios de apuração customizáveis. Geralmente, o jogador ou equipe precisa se inscrever para participar.
+## 1. Visão Geral
 
-## Quando usar
+O módulo `competition` configura **disputas temporais entre jogadores ou times**. Uma competição define um período (`period`), um critério de classificação (`operation`, idêntico ao de um leaderboard), um número máximo de vencedores (`maxWinners`) e participantes (`maxPlayers`), um custo de inscrição opcional (`requires`) e prêmios por posição (`rewards`). Jogadores precisam se inscrever (`join`) para serem considerados na apuração. Ao final, a competição é **executada** — os vencedores são apurados, premiados e marcados com um achievement do tipo `9 (TYPE_COMPETITION)`.
 
-- Para criar disputas temporais (ex: competição de vendas mensal)
-- Para premiar os melhores colocados em um período
-- Para engajar equipes com competições internas
+Papel arquitetural:
 
-## Dependências
+- O ranking é calculado **sob demanda** por `findLeadersAggregate` — uma aggregation MongoDB construída em runtime sobre `action_log` ou `achievement`, restrita ao `period` e aos jogadores inscritos. Não há materialização de placar; cada leitura recalcula.
+- A apuração final (`execute`) é **idempotente por flag**: só roda se `executed == null`. Pode ser disparada manualmente (`GET /v3/competition/{id}/execute`) ou automaticamente pelo `AsyncProcessor` (thread que roda a cada 5 minutos por gamificação).
 
-- **Point** ou **Action**: métrica de avaliação deve existir
-- **Player** ou **Team**: participantes devem existir
+**Diferença arquitetural crítica — competição NÃO usa `fireAction`.** Tanto as deduções de inscrição quanto as recompensas dos vencedores são gravadas como documentos `achievement` **diretamente via Jongo (`ac.save(...)`)**, sem passar por `AchievementManager.addAchievement`/`fireAction`. Consequências (ver seções 5 e 7):
 
-## Checklist de Configuração no Studio
+- **Não recalcula `player_status`** — saldos materializados ficam defasados após inscrição/premiação até o próximo evento natural do jogador.
+- **Não avalia level-up** — pontos de prêmio não promovem o jogador de nível imediatamente.
+- **Não dispara webhook `achievement_created`**.
+- **Não dispara triggers `before_win`/`after_win` da `point_category`** — apenas os triggers próprios da competição (entidade `"competition"`).
 
-- [ ] Definir título e descrição
-- [ ] Definir período de apuração (period.expression)
-- [ ] Definir número máximo de vencedores (maxWinners)
-- [ ] Definir número máximo de participantes (maxPlayers)
-- [ ] Definir critério de ranking (operation: tipo, item, ordenação)
-- [ ] Definir custo de inscrição (requires) se aplicável
-- [ ] Definir recompensas por posição (rewards com position_start/position_ends)
-- [ ] Definir se é competição de equipes (teamCompetition)
-- [ ] Ativar competição (active: true)
-- [ ] Definir execução automática (autoExecute)
+Relação com outros módulos:
 
-## API Endpoints
+- `achievement` — competição grava (e remove, na exclusão/rollback) documentos nesta coleção diretamente. `TYPE_COMPETITION = 9`.
+- `action_log` — fonte de dados para `operation.type` ∈ {COUNT_ACTIONS, SUM_ATTRIBUTE, AVG_ATTRIBUTE}.
+- `crowning` — reusa `Operation`, `Period`, `Filter` e `CrowningManager.buildJsonFilter`/`findPlayerIds`.
+- `challenge` — reusa `Requirement` (custo e prêmio) e `ChallengeRulePrepared` (operation `PREPARED_KPI`).
+- `team` / `team_player` — em competições de time, resolve membros via `findUserIdsByTeamIds` e reagrupa o placar por time.
+- `trigger` — eventos `before_create`/`after_create` (competition e competition_join) e `before_win`/`after_win`.
+- `notification` — apenas o evento `EVENT_WIN` é notificado na execução.
+- `principal` — valida o tipo (player vs team) e a lista de autorizados (`principals`).
 
-### Listar Competições
-**Método:** GET
-**Endpoint:** `/v3/competition`
+Os únicos chamadores de `CompetitionManager` no código são `CompetitionRest` (API) e `AsyncProcessor` (scheduler) — o módulo é autocontido, nenhum outro manager o invoca.
 
-### Criar Competição
-**Método:** POST
-**Endpoint:** `/v3/competition`
+---
+
+## 2. Arquitetura e Fluxos
+
+### 2.1 Classes envolvidas
+
+| Classe | Arquivo | Papel |
+|---|---|---|
+| `Competition` | `engine/competition/Competition.java` | Entidade raiz (coleção `competition`) |
+| `CompetitionJoin` | `engine/competition/CompetitionJoin.java` | Inscrição (coleção `competition_join`) |
+| `TieBreaker` | `engine/competition/TieBreaker.java` | Critério de desempate (`field`, `sort`) |
+| `AutoJoin` | `engine/competition/AutoJoin.java` | Inscrição automática por aggregation |
+| `CompetitionManager` | `engine/competition/CompetitionManager.java` | Toda a lógica: CRUD, join, apuração, ranking |
+| `CompetitionRest` | `rest/v3/rest/CompetitionRest.java` | Controller REST v3 |
+| `Operation` | `engine/crowning/Operation.java` | Critério de classificação (reusado do crowning) |
+| `Period` | `engine/crowning/Period.java` | Período (reusado do crowning) |
+| `Filter` | `engine/crowning/Filter.java` | Filtro de atributos da action |
+| `Requirement` | `engine/challenge/Requirement.java` | Custo (`requires`) e prêmio (`rewards`) |
+| `Leader` | `engine/leader/Leader.java` | Linha do ranking projetada pela aggregation |
+| `AsyncProcessor` | `controller/AsyncProcessor.java` | Thread que auto-executa competições vencidas |
+
+Não há `Repository`/`Dao` — todo acesso ao MongoDB é via Jongo dentro do `CompetitionManager`.
+
+### 2.2 Pipeline — `insert(Competition)` (criação e atualização)
+
+`POST /v3/competition` cobre **criação e atualização** (upsert por `_id`). Não existe `PUT`.
+
+```
+[1] Se id null/vazio → competition.id = Guid.newShortGuid()
+[2] current = competition.findOne({_id: id})
+    - se current == null → created = now; create = true
+    - senão               → created = current.created (preserva)
+[3] updated = new Date()                              (sempre)
+[4] CÁLCULO DE PERÍODO (ver 2.2.1) — pode recalcular startDate/endDate
+[5] se create → trigger before_create (entidade "competition")
+[6] c.save(competition)                               (upsert)
+[7] se create → trigger after_create
+```
+
+**Triggers só disparam na criação.** Atualizações (quando `current != null`) **não** disparam `before_update`/`after_update` — esses eventos não são chamados pelo módulo.
+
+#### 2.2.1 Cálculo de período — bug de comparação por referência
+
+O bloco de período usa **comparação de referência Java (`!=`) entre Strings**, não `.equals()`:
+
+```java
+if(competition.period.expression != null && competition.period.expression.trim().length() > 0
+|| (current != null && current.period != null && current.period.expression != competition.period.expression)) {
+
+    if(current != null && current.period != null && current.period.expression != competition.period.expression) {
+        competition.period.startDate = null;   // limpa
+        competition.period.endDate = null;
+    }
+    String[] dts = competition.period.expression.split(";");
+    if(competition.period.startDate == null && dts.length > 0) {
+        Date dt0 = DateUtil.fromKeyword(dts[0], competition.updated);     // keyword relativo a AGORA
+        if(dt0 == null) dt0 = DateUtil.parseZonedDateToLocalDate(dts[0]); // ou data absoluta
+        competition.period.startDate = dt0;
+    }
+    if(competition.period.startDate != null && competition.period.endDate == null && dts.length > 1) {
+        Date dt1 = DateUtil.fromKeyword(dts[1], competition.period.startDate);
+        if(dt1 == null) dt1 = DateUtil.parseZonedDateToLocalDate(dts[1]);
+        competition.period.endDate = dt1;
+    }
+}
+```
+
+Como `competition` é desserializado a cada request, `competition.period.expression` é sempre um objeto String distinto de `current.period.expression` lido do Mongo. Portanto `!=` é **quase sempre verdadeiro** quando o documento já existe. Efeito prático:
+
+- **Toda atualização de uma competição existente recalcula `startDate`/`endDate` a partir da `expression`.**
+- Se a expressão usa **keyword relativa** (ex.: `-0M-;+1M+`), o `startDate` é recalculado relativo ao **momento da edição** (`updated`), deslocando a janela a cada save.
+- Se a expressão usa **datas absolutas** (ex.: `2018-01-30T00:00:00-03:00;+1M+`), `startDate` fica estável (parse absoluto), mas `endDate` (keyword) é recalculado relativo ao novo `startDate`.
+
+> Campos legados comentados na entidade: `start` (Date), `end` (Date) e `period` (String) estão comentados — não existem em runtime. O período atual é o objeto `Period`.
+
+### 2.3 Pipeline — `insertJoin(CompetitionJoin)`
+
+```
+[1] ci = competition.findOne({_id: join.competition})
+    - se ci == null → adiciona "competition_does_not_exist" (porém ver ARMADILHA abaixo)
+[2] Se join.player == "FUNIFIER_RANDOM_PLAYER":
+      sorteia (até 5 tentativas) um player ainda não inscrito que passe em checkRestrictions
+[3] Verifica existência:
+      - !teamCompetition && player não existe → "player_does_not_exist"
+      - teamCompetition  && team   não existe → "team_does_not_exist"
+[4] restrictions += checkRestrictions(ci, join.player)     (ver 2.3.1)
+[5] SE restrictions vazio:
+      [5.1] Debita requires (custo de inscrição) — ver 2.3.2
+      [5.2] join.id = Guid.newShortGuid(); join.created = now
+      [5.3] trigger before_create (entidade "competition_join", player)
+      [5.4] cj.save(join)
+      [5.5] trigger after_create
+[6] Retorna { join, status: "OK"|"UNAUTHORIZED", restrictions?: [...] }
+```
+
+**ARMADILHA (NPE):** quando a competição **não existe**, `ci == null`, mas o código continua até `if(!ci.teamCompetition && ...)` (linha 223) e lança `NullPointerException` ao acessar `ci.teamCompetition`. A restrição `"competition_does_not_exist"` é **inalcançável** — o cliente recebe erro 500, não a restrição.
+
+#### 2.3.1 `checkRestrictions` — árvore de restrições do join
+
+Avaliada em ordem; cada falha adiciona um código (todos são acumulados):
+
+| Verificação | Método | Código de restrição | Observação |
+|---|---|---|---|
+| Competição ativa | `competition.active` | `competition_disabled` | |
+| Atende aos `requires` | `evaluateRequirements` | `insufficient_requirements` | usa `Requirement.period` se presente |
+| Dentro do prazo | `checkIsInInterval` | `competition_out_of_time` | **só compara `endDate`** — ver abaixo |
+| Vagas disponíveis | `checkIsInMaxPlayers` | `max_players_exceeded` | só checa se `maxPlayers > -1`; conta `competition_join` |
+| Ainda não inscrito | `checkNotJoinedYet` | `player_already_joined` | `count({competition, player}) >= 1` |
+| Tipo de principal correto | `checkIsCorrectPrincipalType` | `team_is_not_allowed` / `player_is_not_allowed` | lookup em `principal` |
+| Está nos `principals` | `checkIsPrincipalAllowed` | `principal_not_allowed` | inclui membros de times listados |
+
+`checkIsInInterval` **só valida `endDate`** (`now <= endDate`); se `endDate == null` retorna `true`. Portanto **é possível se inscrever ANTES de `startDate` começar** — o início do período não bloqueia inscrições.
+
+`checkIsCorrectPrincipalType` consulta a coleção `principal` por `userId`/`teamId`. Se o principal não existir lá, retorna `false` → restrição. Player/team precisam estar registrados em `principal`.
+
+#### 2.3.2 Débito do custo de inscrição (`requires`)
+
+Para cada `Requirement` em `requires` com `operation == OPERATION_DEDUCT (1)`, `total != 0` e `type` ∈ {`POINT(0)`, `CATALOG_ITEM(2)`, `CHALLENGE(1)`}:
+
+```js
+// achievement de dedução (total negativo) — gravado DIRETO via ac.save()
+db.achievement.save({
+  _id: <shortGuid>, player: <join.player>, total: -|r.total|,
+  type: <r.type>, item: <r.item>, time: <now>,
+  extra: { origin_item: <join.competition>, origin_type: 9 }
+})
+```
+
+Tipos fora de {POINT, CATALOG_ITEM, CHALLENGE} são **silenciosamente ignorados** — não há débito. Como é `ac.save()` direto, **`player_status` não é recalculado** após o débito.
+
+### 2.4 Pipeline — `execute(id)` (apuração final)
+
+```
+[1] competition = find(id)
+[2] SÓ executa se: competition != null && active && executed == null
+[3] now = new Date()
+[4] leaders = findLeadersAggregate(id).and("{$limit: #}", maxWinners)   ← ver ARMADILHA maxWinners
+[5] Para cada leader (na ordem do ranking):
+      SE minScore <= 0 OU leader.total >= minScore:
+        [5.1] rewards = getRewardByWinnerPosition(leader.position)       ← ver 3.x position
+        [5.2] credita cada reward (POINT/CATALOG_ITEM/CHALLENGE, total positivado):
+              ac.save({player: leader.player, total: |r.total|, type, item, time: now,
+                       extra:{origin_item: competition.id, origin_type: 9}})
+        [5.3] win = achievement(total:1, type:9 COMPETITION, item: competition.id,
+                                extra:{position: leader.position, total: leader.total})
+        [5.4] trigger before_win (entidade "competition", TriggerContext: item, leader, rewards, leaders)
+        [5.5] ac.save(win); winners.add(win)
+        [5.6] trigger after_win
+        [5.7] notifica EVENT_WIN (scope != CUSTOM) — mustache em params
+[6] re-find competition; competition.executed = now; save
+```
+
+**ARMADILHA (`maxWinners`):** o `execute` repassa `competition.maxWinners` direto para `{$limit: maxWinners}` **sem nenhuma guarda**. O default da entidade é `-1` (documentado como "ilimitado"). Como o `$limit` do MongoDB exige um inteiro **> 0**, uma competição com `maxWinners` não definido (`-1`) ou `0` **não pode ser executada** — a aggregation falha. **Sempre defina `maxWinners >= 1`.**
+
+Quando a falha ocorre na auto-execução, a exceção sobe até o `try/catch` único do `AsyncProcessor.run()`, abortando **o restante daquele ciclo de 5 minutos** (demais competições da iteração, processamento de `lost` e limpeza de auditoria). O ciclo seguinte tentará de novo — e falhará novamente enquanto `maxWinners <= 0`.
+
+Ordem das gravações: **prêmios são gravados ANTES** do achievement de vitória. Tudo via `ac.save()` direto → sem recálculo de `player_status`, sem level-up, sem webhook.
+
+### Fluxo de apuração — `execute`
+
+```mermaid
+flowchart TD
+    S[execute id] --> A{competition != null<br/>&& active<br/>&& executed == null?}
+    A -- não --> Z[retorna lista vazia<br/>nada é gravado]
+    A -- sim --> L[findLeadersAggregate + $limit maxWinners]
+    L --> LOOP{para cada leader}
+    LOOP --> MS{minScore <= 0<br/>OU total >= minScore?}
+    MS -- não --> LOOP
+    MS -- sim --> RW[grava rewards da posição<br/>ac.save total positivo]
+    RW --> WIN[grava win achievement<br/>type=9, total=1]
+    WIN --> TB[trigger before_win]
+    TB --> SV[ac.save win]
+    SV --> TA[trigger after_win]
+    TA --> NT[notificações EVENT_WIN]
+    NT --> LOOP
+    LOOP -- fim --> EX[executed = now; save]
+```
+
+### 2.5 Pipeline — `undoExecute(id)` (rollback)
+
+```
+SE competition.executed != null:
+  [1] db.achievement.remove({type:9, item: id})                 // achievements de vitória
+  [2] db.achievement.remove({"extra.origin_item": id})          // prêmios (e deduções de join!)
+  [3] competition.executed = null; competition.autoExecute = false; save
+  [4] db.notification.remove({"item.type":"competition", "item.id": id})
+```
+
+Observações:
+
+- `[3]` força `autoExecute = false` — após um rollback, a competição **não será re-executada automaticamente** pelo scheduler. É preciso reativar `autoExecute` manualmente.
+- `[2]` remove por `extra.origin_item` **sem filtrar `origin_type`** — isso também apaga as **deduções de custo de inscrição** (que carregam o mesmo `origin_item`). O rollback, portanto, devolve implicitamente o custo de quem se inscreveu, além de remover os prêmios.
+- Inconsistência com `delete()`: `delete` remove prêmios por `{origin_type:9, origin_item:id}` (mais estrito); `undoExecute` remove por `{origin_item:id}` apenas.
+
+### 2.6 Pipeline — `delete(id)` (exclusão em cascata)
+
+```
+[1] db.achievement.remove({type:9, item: id})
+[2] db.achievement.remove({"extra.origin_type":9, "extra.origin_item": id})
+[3] db.competition_join.remove({competition: id})
+[4] db.notification.remove({"item.type":"competition", "item.id": id})
+[5] db.competition.remove({_id: id})
+```
+
+`delete` **não dispara** triggers `before_delete`/`after_delete` — esses eventos não são chamados.
+
+### 2.7 Motor de ranking — `findLeadersAggregate(id, jongo)`
+
+Constrói a aggregation que produz o placar. Etapas:
+
+```
+[1] competition = find(id)
+[2] players = db.competition_join.distinct("player", {competition: id})
+[3] autoJoinMemberIds = findAutoJoinIds(competition)
+    SE != null → players = autoJoinMemberIds   ← SUBSTITUI a lista (não soma!)
+[4] filter = CrowningManager.buildJsonFilter(operation)   (ver 2.8)
+[5] Ramifica por teamCompetition e por operation.type (ver tabela)
+[6] Ordenação + paginação por facet/unwind para anexar a posição (1-based)
+```
+
+**`autoJoin` substitui os inscritos.** Se `autoJoin` estiver configurado e retornar ids, as inscrições manuais (`competition_join`) são **ignoradas** no ranking — o conjunto de participantes passa a ser exclusivamente o resultado da aggregation do `autoJoin`.
+
+Estágio de agrupamento por `operation.type` (ramo **player**; o ramo **team** é análogo, mas filtra por membros e reagrupa por time):
+
+| `operation.type` | Coleção | `$match` (resumo) | `$group` |
+|---|---|---|---|
+| `1` `COUNT_ACTIONS` | `action_log` | `time ∈ [start,end]`, `userId ∈ players`, `actionId = item` + filtros | `total: {$sum: 1}`, `max: {$max:"$time"}` |
+| `2` `SUM_ATTRIBUTE` | `action_log` | idem | `total: {$sum: "$attributes.<attribute>"}` |
+| `4` `AVG_ATTRIBUTE` | `action_log` | idem | `total: {$avg: "$attributes.<attribute>"}` |
+| `3` `SUM_ACHIEVEMENTS` | `achievement` | `time ∈ [start,end]`, `type = achievement_type` (se != -1), `player ∈ players`, `item = item` | `total: {$sum: "$total"}` |
+| `10` `PREPARED_KPI` | `prepared.entity` | aggregation do `ChallengeRulePrepared` com tokens substituídos | definido pelo prepared |
+
+**Filtros (`operation.filters`) só se aplicam aos tipos baseados em `action_log`** (COUNT, SUM_ATTRIBUTE, AVG_ATTRIBUTE). Em `SUM_ACHIEVEMENTS` e `PREPARED_KPI` os filtros **não são aplicados** (o `filter` não é concatenado nesses ramos).
+
+Ordenação final:
+
+```js
+// sem tieBreaker:
+{ $sort: { total: <dir>, max: 1 } }   // dir = 1 se operation.sort==1 (asc), senão -1 (desc)
+// com tieBreaker (field != "" e sort != 0):
+{ $sort: { total: <dir>, <tieBreaker.field>: <tieBreaker.sort> } }
+```
+
+- `operation.sort == 1` (`SORT_ASC`) → ranqueia do **menor** total para o maior (ex.: tempo/erros, "menor é melhor").
+- Qualquer outro valor (`0` default, ou `-1`) → **maior** total primeiro (placar padrão).
+- **Desempate padrão (sem `tieBreaker`):** `max: 1` (ascendente) — entre totais iguais, vence quem tem o **menor `max`** (o timestamp do evento qualificador mais recente é o mais antigo), ou seja, quem atingiu o total **primeiro**. Isso **contradiz o comentário** da classe `TieBreaker` ("o padrão é max:-1").
+
+PREPARED_KPI substitui os tokens: `FUNIFIER_PLAYER_IDS`, `FUNIFIER_TRIGGER_TIME`, `FUNIFIER_PERIOD_START_TIME`, `FUNIFIER_PERIOD_END_TIME`. **Não substitui** `FUNIFIER_TRIGGER_ACTION_ID` nem `FUNIFIER_RULE_ACTION_ID` (usados por challenge) — um prepared escrito para challenge não funciona aqui sem ajuste.
+
+### 2.8 `buildJsonFilter(operation)` — tradução de `operation.filters`
+
+```java
+// produz: , $and: [ {attributes.<param>: <expr>}, ... ]
+```
+
+| `operator` (código) | Expressão gerada |
+|---|---|
+| `EQUAL (1)` | `{attributes.X: <value>}` |
+| `REGEX (3)` | `{attributes.X: { $regex: <value>}}` |
+| `GREATER_THAN (4)` | `{attributes.X: { $gt: <value>}}` |
+| `GREATER_THAN_OR_EQUAL (5)` | `{attributes.X: { $gte: <value>}}` |
+| `LESS_THAN (6)` | `{attributes.X: { $lt: <value>}}` |
+| `LESS_THAN_OR_EQUAL (7)` | `{attributes.X: { $lte: <value>}}` |
+
+O `value` é numérico se fizer parse como `Double`; caso contrário vira string entre aspas.
+
+**Operadores não suportados geram JSON malformado.** `NONE(0)`, `LIKE(2)`, `NOT_EQUAL(8)`, `EXIST(9)`, `NOT_EXIST(10)`, `MAX_DISTANCE_IN_METERS(20)`, `MOD(40)` não têm ramo no `buildJsonFilter` usado pela competição: o código emite `{attributes.X : }` (sem valor) → a aggregation falha ao ser parseada. Use apenas os 6 operadores da tabela em filtros de competição.
+
+### 2.9 Auto-execução — `AsyncProcessor` + `findCompetitionsToExecute`
+
+```mermaid
+sequenceDiagram
+    participant T as AsyncProcessor (thread)
+    participant CM as CompetitionManager
+    participant DB as MongoDB
+    participant TR as TriggerManager
+    participant NM as NotificationManager
+    loop a cada 5 minutos
+        T->>CM: findCompetitionsToExecute()
+        CM->>DB: match active:true, autoExecute:true,<br/>executed:null, period.endDate <= now
+        DB-->>CM: competições vencidas
+        loop cada competição
+            T->>CM: execute(competition.id)
+            CM->>DB: findLeadersAggregate + $limit(maxWinners)
+            CM->>DB: ac.save(rewards + win)
+            CM->>TR: before_win / after_win
+            CM->>NM: send(EVENT_WIN)
+            CM->>DB: set executed = now
+        end
+    end
+```
+
+Query do scheduler:
+
+```js
+db.competition.aggregate([
+  { $match: { active: true, autoExecute: true, executed: null, "period.endDate": { $lte: <now> } } }
+])
+```
+
+---
+
+## 3. Estrutura dos Objetos
+
+### 3.1 `Competition` — documento raiz (coleção `competition`)
+
+| Campo | Tipo | Padrão | Obrigatório | Descrição |
+|---|---|---|---|---|
+| `_id` | String | `Guid.newShortGuid()` se ausente | Não (auto) | Id curto interno (não é ObjectId) |
+| `title` | String | — | Não | Título exibido |
+| `description` | String | — | Não | Descrição |
+| `image` | String | — | Não | URL da imagem |
+| `period` | `Period` | `new Period()` | **Sim (na prática)** | Janela da competição; ver 3.2 |
+| `maxWinners` | long | `-1` | **Sim p/ executar** | Nº máximo de vencedores. Vira `$limit`; **deve ser >= 1** para `execute` funcionar |
+| `maxPlayers` | long | `-1` | Não | Nº máximo de inscritos. `-1` = ilimitado (não checado) |
+| `minScore` | long | `0` | Não | Score mínimo para ser premiado. `<= 0` desativa a checagem |
+| `operation` | `Operation` | — | **Sim** | Critério de ranking; ver 3.3 |
+| `requires` | List<`Requirement`> | `[]` | Não | Custo de inscrição (deduzido no join) |
+| `rewards` | List<`Requirement`> | `[]` | Não | Prêmios por posição (creditados na execução) |
+| `notifications` | List<`NotificationDefinition`> | `[]` | Não | **Apenas `EVENT_WIN (0)` é disparado** |
+| `active` | boolean | `false` | **Sim** | Só competições ativas recebem join e podem ser executadas |
+| `teamCompetition` | boolean | `false` | Não | Se `true`, participantes são times; ranking reagrupa por time |
+| `autoExecute` | boolean | `false` | Não | Auto-execução pelo `AsyncProcessor` ao vencer `period.endDate` |
+| `extra` | Map | `{}` | Não | Atributos livres |
+| `techniques` | List<String> | `null` | Não | Códigos de game techniques (GT…); apenas metadado |
+| `created` | Date | `now` na criação | Auto | Data de criação (preservada em updates) |
+| `updated` | Date | `now` em todo save | Auto | Última atualização |
+| `executed` | Date | `null` | Auto | Data da apuração; bloqueia re-execução enquanto != null |
+| `tieBreaker` | `TieBreaker` | `null` | Não | Desempate; ver 3.4 |
+| `principals` | List<String> | `null` | Não | Ids de players/times autorizados a participar |
+| `autoJoin` | `AutoJoin` | `null` | Não | Inscrição automática por aggregation; ver 3.5 |
+| `now` | Date | — | Runtime | **Não persistido de forma útil** — preenchido só na listagem (ver abaixo) |
+
+#### Campos computados / assimétricos
+
+- **`now`**: a entidade tem o campo, e o endpoint **de listagem** (`GET /v3/competition`) seta `c.now = new Date()` em cada item da resposta (para o frontend comparar com `period.startDate/endDate`). O endpoint de **busca individual** (`GET /v3/competition/{id}`) **não** seta `now`. Não há uso de `now` persistido.
+
+#### Campos aceitos mas ignorados (silenciosos)
+
+- **`techniques`**: aceito e persistido, porém puramente informativo — nenhuma lógica de competição o consulta.
+- **Campos legados comentados** na entidade: `start` (Date), `end` (Date), `period` (String) — não existem em runtime.
+- `@JsonIgnoreProperties(ignoreUnknown=true)`: qualquer campo extra fora do mapeado é **descartado silenciosamente** no POST.
+
+### 3.2 `Period` — subdocumento `period`
+
+| Campo | Tipo | Usado pela competição? | Descrição |
+|---|---|---|---|
+| `expression` | String | **Sim** | `"<start>;<end>"`. Start relativo à criação; ex.: `-0M-;+1M+` ou `2018-01-30T00:00:00-03:00;+1M+` |
+| `startDate` | Date | **Sim** | Calculado da expression (ou informado). Início da janela |
+| `endDate` | Date | **Sim** | Calculado da expression (ou informado). Fim da janela e gatilho do auto-execute |
+| `type` | int | **Não** (ignorado) | `0 VARIABLE`, `1 FIXED` — usado pelo crowning, não pela competição |
+| `timeAmount` | int | **Não** (ignorado) | Idem |
+| `timeScale` | int | **Não** (ignorado) | Idem |
+
+A competição calcula `startDate`/`endDate` em `insert` (ver 2.2.1) — **não** usa `Period.getCurrentRange()`. Os campos `type`/`timeAmount`/`timeScale` são aceitos mas nunca lidos aqui.
+
+### 3.3 `Operation` — subdocumento `operation` (critério de ranking)
+
+| Campo | Tipo | Descrição |
+|---|---|---|
+| `type` | int | `1` COUNT_ACTIONS, `2` SUM_ATTRIBUTE, `3` SUM_ACHIEVEMENTS, `4` AVG_ATTRIBUTE, `10` PREPARED_KPI |
+| `achievement_type` | int | Só para `SUM_ACHIEVEMENTS`: `-1` NONE (qualquer), `0` POINT, `1` CHALLENGE, `2` CATALOG_ITEM, `3` LEVEL |
+| `item` | String | COUNT/SUM/AVG: `actionId`. SUM_ACHIEVEMENTS: `item` do achievement (ex.: id da point_category) |
+| `attribute` | String | Só SUM/AVG_ATTRIBUTE: caminho em `attributes.<attribute>` |
+| `filters` | List<`Filter`> | Filtros de `attributes` (só action_log; ver 2.8) |
+| `sort` | int | `1` asc (menor primeiro); demais valores → desc (maior primeiro) |
+| `prepared` | String | Só PREPARED_KPI: id de `ChallengeRulePrepared` |
+| `sub` | boolean | **Ignorado pela competição** (recurso de sub-rankings do crowning) |
+| `subAttribute` | String | **Ignorado pela competição** |
+
+### 3.4 `TieBreaker` — subdocumento `tieBreaker`
+
+| Campo | Tipo | Descrição |
+|---|---|---|
+| `field` | String | Campo numérico (somado no `$group`) usado como desempate |
+| `sort` | int | Direção do desempate (`1` asc / `-1` desc). Só ativa se `field != ""` **e** `sort != 0` |
+
+Sem `tieBreaker`, o desempate padrão é `max: 1` (quem atingiu o total primeiro). O comentário da classe diz "padrão max:-1" — **desatualizado** em relação ao código.
+
+### 3.5 `AutoJoin` — subdocumento `autoJoin`
+
+| Campo | Tipo | Descrição |
+|---|---|---|
+| `entity` | String | Coleção onde a aggregation roda (ex.: `"player"`) |
+| `aggregate` | String | Pipeline (JSON array) que retorna documentos com campo `_id` = id do participante |
+
+Se `principals` estiver preenchido, o resultado é filtrado por `{_id: {$in: <findPlayerIds(principals)>}}`. **Quando `autoJoin` retorna ids, eles substituem totalmente os inscritos manuais** no ranking (ver 2.7).
+
+### 3.6 `Requirement` — usado em `requires` e `rewards`
+
+| Campo | Tipo | Usado? | Descrição |
+|---|---|---|---|
+| `total` | int | Sim | Quantidade. Em reward é positivado; em require (DEDUCT) é negativado |
+| `type` | int | Sim | Só `POINT(0)`, `CHALLENGE(1)`, `CATALOG_ITEM(2)` têm efeito; demais ignorados |
+| `item` | String | Sim | Id do item (point_category, challenge, catalog_item) |
+| `operation` | int | Sim (em `requires`) | `0` VERIFY, `1` DEDUCT. Só `DEDUCT` debita no join |
+| `extra` | Map | Sim (em `rewards`) | **Apenas `position_start`/`position_ends`** controlam a posição; ver 3.7 |
+| `period` | String | Sim (em `requires`) | Janela para `evaluateRequirements` (ex.: `-30d-`) |
+| `folder` | String | **Não** (ignorado pela competição) | |
+| `restrict` | boolean | **Não** (ignorado) | Sem checagem de estoque de item (diferente de challenge/catalog) |
+| `perPlayer` | boolean | **Não** (ignorado) | |
+
+Tipos de `Requirement`: `POINT 0`, `CHALLENGE 1`, `CATALOG_ITEM 2`, `LEVEL 3`, `CROWN 4`, `LOTTERY 5`, `MYSTERY_BOX 6`, `CHARACTER_STAR_STAT 7`, `LOTTERY_TICKET 50`. **Competição só processa 0/1/2.** Não há suporte a `FUNIFIER_RANDOM` em prêmios (diferente de challenge).
+
+### 3.7 Distribuição de prêmio por posição — `getRewardByWinnerPosition(position)`
+
+A regra real para decidir se um `reward` se aplica a um vencedor:
+
+```
+para cada reward:
+  se reward.extra é null OU vazio:
+      aplica a TODOS os vencedores (prêmio geral)
+  senão (extra tem alguma chave):
+      start = parseInt(extra.position_start)   // -1 se ausente/inválido
+      ends  = parseInt(extra.position_ends)    // -1 se ausente/inválido
+      se position_start == null E position_ends == null:
+          aplica a TODOS                       ← inclui o caso extra.position!
+      senão se position_start != null E start <= position E position_ends == null:
+          aplica de start em diante
+      senão se position_start != null E start <= position E position_ends != null E position <= ends:
+          aplica no intervalo [start, ends]
+```
+
+**`extra.position` é código morto.** Apenas `position_start` e `position_ends` são lidos. Um reward com `extra: {position: 1}` cai no ramo "`position_start == null && position_ends == null`" → é distribuído a **todos** os vencedores, não só ao 1º colocado. O exemplo do apidoc do controller e o `CompetitionTest` usam `position` — e portanto premiam todo mundo igualmente (bug demonstrado no próprio teste).
+
+### 3.8 `CompetitionJoin` — inscrição (coleção `competition_join`)
+
+| Campo | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `_id` | String | `Guid.newShortGuid()` | Id da inscrição |
+| `competition` | String | — | Id da competição |
+| `player` | String | — | Id do player (ou time, se `teamCompetition`) |
+| `created` | Date | `now` | Data da inscrição |
+
+---
+
+## 4. Endpoints
+
+Todos os endpoints exigem `Authorization: Bearer <token>` e respondem JSON. As respostas usam `JsonUtil.toJsonRemoveNullFields` — **campos nulos são omitidos** (ex.: `executed`, `tieBreaker`, `principals`, `autoJoin`, `techniques` aparecem só quando preenchidos).
+
+### 4.1 `POST /v3/competition`
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Criar **ou atualizar** competição (upsert por `_id`) |
+| Full replace ou patch | **Full replace** — o body inteiro substitui o documento |
+| Triggers | `before_create`/`after_create` **só na criação** (não em update) |
+| Resposta | `201 Created` com a competição (campos nulos removidos) |
+
+Comportamento real: gera `_id` se ausente; preserva `created`; recalcula `period` (ver 2.2.1, atenção ao bug de referência); dispara triggers só na criação.
+
+### 4.2 `GET /v3/competition`
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Listar competições |
+
+**Query params:**
+
+| Param | Tipo | Descrição |
+|---|---|---|
+| `id` | String | Filtra por `_id` exato |
+| `to` | String | Competições disponíveis para o player. `me` resolve via token. Aplica `$or` sobre `principals` (null/ausente/[]/contém player ou seus times) |
+| `q` | String | Critério MongoDB raw injetado no `$match` (ver seção 8) |
+| `fields` | CSV | Projeção `{$project}` |
+| `orderby` / `reverse` | String | Ordenação |
+| `max_results` | int | Limite (default 100; `<= 0` vira 100) |
+
+Cada item retornado recebe `now = <hora do servidor>`.
+
+### 4.3 `GET /v3/competition/{id}`
+
+Busca uma competição. **Não** seta `now`. Retorna `200`.
+
+### 4.4 `DELETE /v3/competition/{id}`
+
+Exclusão em cascata (ver 2.6): remove achievements de vitória, prêmios, joins, notificações e a competição. Retorna `204`. Sem triggers de delete.
+
+### 4.5 `POST /v3/competition/join`
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Inscrever player/time na competição |
+| Body | `{ "competition": "<id>", "player": "<id|FUNIFIER_RANDOM_PLAYER>" }` |
+| Resposta | `201` com `{ join, status, restrictions? }` |
+
+**Comportamento real:** mesmo quando há restrições, o status HTTP é `201` — o resultado de negócio está no corpo (`status: "OK"` ou `"UNAUTHORIZED"` + lista `restrictions`). Custo (`requires` DEDUCT) é debitado só quando não há restrições. **Inscrever em competição inexistente lança 500 (NPE)** — ver 2.3.
+
+**Exemplo de resposta UNAUTHORIZED:**
 
-**Exemplo de Body:**
 ```json
 {
-  "title": "Sales Race",
-  "description": "Leads the competition who has the highest amount of closed sales in the month.",
-  "period": {
-    "expression": "-0M-;+1M+"
-  },
-  "maxWinners": 1,
-  "maxPlayers": 100,
-  "minScore": 0,
-  "operation": {
-    "type": 1,
-    "achievement_type": 0,
-    "item": "sell",
-    "filters": [],
-    "sort": -1,
-    "sub": false
-  },
-  "requires": [
-    {
-      "total": 10,
-      "type": 0,
-      "item": "coin",
-      "operation": 1,
-      "extra": {},
-      "restrict": false,
-      "perPlayer": false
-    }
-  ],
+  "join": { "competition": "race", "player": "tom" },
+  "restrictions": ["player_already_joined"],
+  "status": "UNAUTHORIZED"
+}
+```
+
+### 4.6 `DELETE /v3/competition/join`
+
+Remove a inscrição. Body: `{ "competition": "<id>", "player": "<id>" }`. Query: `db.competition_join.remove({competition, player})`. **Não estorna** o custo de inscrição debitado. Retorna `204`.
+
+### 4.7 `GET /v3/competition/join`
+
+Lista inscrições. Params: `id`, `competition`, `player` (`me` resolve via token), `q`, `fields`, `published_min`/`published_max` (RFC 3339 ou keyword, sobre `created`), `orderby`/`reverse`, `max_results`.
+
+### 4.8 `GET /v3/competition/leader?id=<id>`
+
+Placar em tempo real (paginado via header `Range: items=<from>-<size>`). Roda `findLeadersAggregate` (ver 2.7). Resposta no formato `paginatedCallback`.
+
+### 4.9 `POST /v3/competition/leader/aggregate?id=<id>`
+
+Placar com **estágios de aggregation adicionais** (body = lista de estágios). Os estágios do body são anexados **após** o pipeline de `findLeadersAggregate`. Paginação via `Range` (default 0–100).
+
+### 4.10 `GET /v3/competition/{id}/execute`
+
+Apura e premia (ver 2.4). Retorna `{ competition, winners }`. Idempotente: se `executed != null`, `winners` volta vazio e nada é gravado.
+
+### 4.11 `DELETE /v3/competition/{id}/execute`
+
+Rollback da execução (ver 2.5). Remove achievements (vitória + prêmios + deduções com mesmo `origin_item`) e notificações, zera `executed` e força `autoExecute=false`. Retorna `{ competition, message: "Execution Rollback Done" }`.
+
+---
+
+## 5. Regras de Negócio
+
+Regras presentes no código, não no schema:
+
+### 5.1 Competição não passa por `fireAction`
+
+Prêmios e deduções são `ac.save()` diretos. **Não** recalculam `player_status`, **não** avaliam level-up, **não** disparam webhook nem os triggers de `point_category`. O saldo materializado do jogador fica defasado até o próximo evento natural.
+
+### 5.2 `extra.position` não funciona — use `position_start`/`position_ends`
+
+Ver 3.7. Reward com `extra.position` é tratado como prêmio geral (todos os vencedores).
+
+### 5.3 `maxWinners` deve ser `>= 1`
+
+Vira `$limit` sem guarda. Default `-1` impede a execução. Ver 2.4.
+
+### 5.4 Inscrição permitida antes do início (`startDate` não barra join)
+
+`checkIsInInterval` só compara `endDate`. Ver 2.3.1.
+
+### 5.5 Apenas `EVENT_WIN` é notificado; `SCOPE_CUSTOM` é ignorado
+
+O comentário da entidade fala em eventos "create, join, end, win", mas `execute` só dispara `EVENT_WIN (0)`. E `getNotificationsByEvent` exclui `SCOPE_CUSTOM (99)` — uma notificação de vitória com scope custom **não** é enviada.
+
+### 5.6 Tipos de `Requirement` limitados a POINT/CHALLENGE/CATALOG_ITEM
+
+Em `requires` (DEDUCT) e `rewards`, outros tipos são ignorados sem erro.
+
+### 5.7 `autoExecute` é desligado após rollback
+
+`undoExecute` força `autoExecute=false`. Reativação é manual.
+
+### 5.8 Multi-tenant por conexão
+
+Não há `apiKey` no documento. O isolamento vem do roteamento de conexão Jongo por tenant (`manager.getJongoConnection()`).
+
+### 5.9 Edição recalcula o período (bug de `!=`)
+
+Ver 2.2.1. Editar uma competição com expressão por keyword desloca a janela.
+
+### 5.10 `autoJoin` substitui inscrições manuais no ranking
+
+Ver 2.7. Não há merge entre `competition_join` e `autoJoin`.
+
+---
+
+## 6. Comportamentos Automáticos
+
+| Comportamento | Trigger | Impacto | Persistência |
+|---|---|---|---|
+| `_id` (ShortGuid) | `insert`/`insertJoin` se id ausente | Id curto interno | Sim |
+| Cálculo de `period.startDate/endDate` | `insert` (ver 2.2.1) | Recalculado a cada update (bug `!=`) | Sim |
+| `created`/`updated` | `insert` | created preservado; updated sempre = now | Sim |
+| Débito de `requires` | `insertJoin` sem restrições | achievement(s) negativo(s) com `origin_item`/`origin_type` | Sim (sem recalc de status) |
+| Crédito de `rewards` | `execute`, por vencedor/posição | achievement(s) positivo(s) | Sim (sem recalc de status) |
+| Achievement de vitória | `execute` | `type=9`, `total=1`, `extra.position`, `extra.total` | Sim |
+| Trigger `before_create`/`after_create` | criação de competition e de competition_join | scripts customizados | Side effects |
+| Trigger `before_win`/`after_win` | `execute`, por vencedor (entidade `"competition"`) | scripts com `TriggerContext` (item, leader, rewards, leaders) | Side effects |
+| Notificação `EVENT_WIN` | `execute`, por vencedor (scope != CUSTOM) | documento em `notification` (mustache em `params`) | Sim |
+| Auto-execução | `AsyncProcessor` a cada 5 min, se vencida e `autoExecute` | apura e marca `executed` | Sim |
+| `autoExecute=false` | `undoExecute` | bloqueia re-execução automática | Sim |
+
+### Cascata de gravações em `execute` (por vencedor)
+
+```mermaid
+flowchart LR
+    W[vencedor x] --> R[rewards da posição<br/>ac.save total positivo]
+    R --> WIN[win achievement type=9]
+    WIN --> BW[trigger before_win]
+    BW --> SV[ac.save win]
+    SV --> AW[trigger after_win]
+    AW --> N[notification EVENT_WIN]
+```
+
+---
+
+## 7. Suportado vs NÃO Suportado
+
+### ✅ Suportado
+
+- CRUD via `/v3/competition` (POST upsert, GET list, GET by id, DELETE com cascata).
+- Inscrição/desinscrição (`/join`), com custo (`requires` DEDUCT) e validação de restrições.
+- Inscrição de player aleatório (`player: "FUNIFIER_RANDOM_PLAYER"`, até 5 tentativas).
+- Inscrição automática por aggregation (`autoJoin`).
+- Placar em tempo real (`/leader`, `/leader/aggregate`) com paginação por `Range`.
+- 5 critérios de ranking: COUNT_ACTIONS, SUM_ATTRIBUTE, AVG_ATTRIBUTE, SUM_ACHIEVEMENTS, PREPARED_KPI.
+- Competições de time (`teamCompetition`) com reagrupamento por time via `team_player`.
+- Filtros de atributo (6 operadores) em rankings baseados em `action_log`.
+- Desempate por `tieBreaker` (campo + direção) ou padrão (quem chegou primeiro).
+- Prêmios por faixa de posição (`position_start`/`position_ends`).
+- `minScore` para premiar só quem atingiu um mínimo.
+- Execução manual e automática (`autoExecute` + `AsyncProcessor`), com rollback (`undoExecute`).
+- Triggers de create (competition/join) e win; notificações de vitória.
+- Lista restrita por `principals` e endpoint `to=me`.
+
+### ❌ NÃO Suportado / Pegadinhas
+
+- **`extra.position` em rewards** — código morto; só `position_start`/`position_ends` funcionam (3.7).
+- **`maxWinners` ilimitado (`-1`)** — quebra `execute` (`$limit` exige > 0). Default não é executável (2.4).
+- **Recálculo de `player_status`/level-up/webhook** após prêmio ou dedução — não acontece (5.1).
+- **Inscrição em competição inexistente** — lança NPE (500), não devolve `competition_does_not_exist` (2.3).
+- **`startDate` não barra inscrições** — só `endDate` (2.3.1, 5.4).
+- **Notificações de `create`/`join`/`end`** — não existem; só `EVENT_WIN` é disparado (5.5).
+- **Notificação de vitória com `SCOPE_CUSTOM (99)`** — filtrada, nunca enviada (5.5).
+- **Triggers `before_update`/`after_update`/`before_delete`/`after_delete`** — não chamados pela competição.
+- **`Trigger.ENTITY_COMPETITION`** — constante **comentada** no código; triggers devem usar a string crua `"competition"` (ou `"competition_join"`).
+- **Tipos de Requirement** fora de POINT/CHALLENGE/CATALOG_ITEM — ignorados (5.6).
+- **`Requirement.restrict`/`perPlayer`/`folder` e `FUNIFIER_RANDOM` em prêmios** — não suportados (diferente de challenge/catalog).
+- **`operation.sub`/`subAttribute`** — aceitos, mas ignorados (sub-rankings não existem em competição).
+- **`Period.type`/`timeAmount`/`timeScale`** — aceitos, mas ignorados (só `expression`/`startDate`/`endDate`).
+- **Operadores de filtro além de EQUAL/REGEX/GT/GTE/LT/LTE** — geram JSON malformado e quebram o ranking (2.8).
+- **Estorno de custo ao desinscrever** (`DELETE /join`) — não devolve o que foi debitado.
+- **`PUT`** — não existe; atualização é via `POST` (não dispara triggers de update).
+
+---
+
+## 8. Segurança e Permissões
+
+- **Autenticação:** todos os endpoints v3 exigem `Authorization: Bearer <token>`. Não há endpoint legado `/2.0.0/competition`.
+- **Isolamento multi-tenant:** por conexão Jongo (`getJongoConnection()`); não há `apiKey` no documento. Documentos cross-tenant são impossíveis enquanto o roteamento estiver correto.
+- **Autorização de participação:** `principals` (lista de players/times) + `checkIsCorrectPrincipalType` (lookup em `principal`). Sem `principals`, qualquer principal do tipo correto pode entrar.
+- **Triggers para autorização de competição:** como `Trigger.ENTITY_COMPETITION` está comentado, use a string `"competition"`/`"competition_join"` no campo `entity` do trigger.
+
+### Superfícies de injeção
+
+- **`q` (raw query)** em `GET /v3/competition` e `GET /v3/competition/join`: concatenado **literalmente** no `$match` (`{ _id:{$exists:true}, <q> }`). Permite injeção de operadores MongoDB. Restringir quem pode chamar com `q` arbitrário.
+- **`operation.attribute`, `tieBreaker.field`, `orderby`, `fields`**: concatenados diretamente na string da aggregation (ex.: `'$attributes.' + operation.getAttribute()`, `"{ $sort : {" + orderby + " : #}}"`). Valores controlados por quem cria a competição/consulta entram sem sanitização no pipeline.
+- **`POST /v3/competition/leader/aggregate`**: aceita estágios de aggregation arbitrários do cliente, anexados ao pipeline — permite consultas livres sobre as coleções do tenant.
+- **`autoJoin.aggregate`**: pipeline arbitrário executado sobre `autoJoin.entity` (qualquer coleção do tenant) na apuração/ranking.
+
+---
+
+## 9. Observabilidade e Troubleshooting
+
+### Diagnóstico
+
+```
+# A competição está ativa e dentro do prazo?
+GET /v3/competition/{id}      # confira active=true, period.startDate/endDate, executed
+
+# Quem se inscreveu?
+GET /v3/competition/join?competition={id}&max_results=1000
+
+# Placar atual (recalculado sob demanda)
+GET /v3/competition/leader?id={id}
+# Header: Range: items=0-100
+```
+
+### Queries úteis (MongoDB)
+
+```js
+// Inscritos
+db.competition_join.find({ competition: "<id>" })
+
+// Achievements gerados pela competição (vitórias)
+db.achievement.find({ type: 9, item: "<id>" })
+
+// Prêmios + deduções (rastreados por origin_item)
+db.achievement.find({ "extra.origin_item": "<id>" })
+
+// Competições que o scheduler deveria executar agora
+db.competition.find({ active: true, autoExecute: true, executed: null,
+                      "period.endDate": { $lte: new Date() } })
+```
+
+### Erros comuns e causas
+
+| Sintoma | Causa provável |
+|---|---|
+| `execute` não premia ninguém | `maxWinners <= 0` (quebra `$limit`); ou `executed != null`; ou `active=false`; ou ninguém atingiu `minScore` |
+| Auto-execução nunca roda | `autoExecute=false` (inclusive após um `undoExecute`); `period.endDate` no futuro; thread `AsyncProcessor` abortou o ciclo por exceção de outra competição |
+| Prêmio dado a todos em vez do 1º lugar | usou `extra.position` em vez de `extra.position_start`/`position_ends` (3.7) |
+| Saldo do jogador "errado" após premiação | `player_status` não foi recalculado (5.1) — disparado só no próximo evento natural |
+| 500 ao inscrever | competição não existe → NPE em `ci.teamCompetition` (2.3) |
+| Placar vazio ou erro de aggregation | operador de filtro não suportado (2.8); ou janela `period` recalculada após edição (2.2.1); ou `autoJoin` retornando vazio e substituindo inscritos |
+| Janela de datas mudou sozinha | edição recalculou `period` por causa do bug de comparação `!=` (2.2.1) |
+| Inscrição aceita antes da data de início | esperado — `startDate` não barra join (5.4) |
+
+---
+
+## 10. Exemplos Práticos
+
+### 10.1 Mínimo funcional — competição individual por contagem de ações
+
+```json
+POST /v3/competition
+{
+  "_id": "race",
+  "title": "Corrida de Vendas",
+  "period": { "expression": "-0M-;+1M+" },
+  "maxWinners": 3,
+  "operation": { "type": 1, "item": "sell", "sort": -1 },
   "rewards": [
-    {
-      "total": 100,
-      "type": 0,
-      "item": "xp",
-      "operation": 0,
-      "extra": {
-        "position_start": 1,
-        "position_ends": 3
-      },
-      "restrict": false,
-      "perPlayer": false
-    }
+    { "total": 100, "type": 0, "item": "xp", "extra": { "position_start": 1, "position_ends": 3 } }
   ],
-  "notifications": [],
   "active": true,
-  "teamCompetition": false,
-  "autoExecute": true,
-  "extra": {},
-  "techniques": ["GT26"],
-  "_id": "race"
+  "autoExecute": true
 }
 ```
 
-### Deletar Competição
-**Método:** DELETE
-**Endpoint:** `/v3/competition/:id`
-
-### Listar Participações (Joins)
-**Método:** GET
-**Endpoint:** `/v3/competition/join?competition=:id`
+`operation.type=1` (COUNT_ACTIONS) conta `action_log` com `actionId="sell"` no período; `sort=-1` ranqueia do maior para o menor; o prêmio vai para os colocados 1 a 3.
 
-### Criar Participação (Join)
-**Método:** POST
-**Endpoint:** `/v3/competition/join`
+### 10.2 Avançado — competição de time, custo de inscrição, desempate e SUM_ACHIEVEMENTS
 
-**Exemplo de Body:**
 ```json
+POST /v3/competition
 {
-  "competition": "race",
-  "player": "jerry"
+  "_id": "team_cup",
+  "title": "Copa de Times",
+  "description": "Maior soma de pontos no mês",
+  "image": "https://cdn/holiday.png",
+  "period": { "expression": "2026-05-01T00:00:00-03:00;2026-05-31T23:59:59-03:00" },
+  "maxWinners": 1,
+  "maxPlayers": 8,
+  "minScore": 50,
+  "teamCompetition": true,
+  "operation": { "type": 3, "achievement_type": 0, "item": "point", "sort": -1 },
+  "tieBreaker": { "field": "total", "sort": -1 },
+  "requires": [
+    { "total": 10, "type": 0, "item": "coin", "operation": 1 }
+  ],
+  "rewards": [
+    { "total": 500, "type": 0, "item": "xp", "extra": { "position_start": 1, "position_ends": 1 } },
+    { "total": 50,  "type": 0, "item": "xp" }
+  ],
+  "principals": ["team_a", "team_b", "team_c"],
+  "notifications": [
+    { "event": 0, "type": 0, "scope": 0, "content": "Parabéns, {{player.name}} venceu a {{item.title}}!" }
+  ],
+  "active": true,
+  "autoExecute": true
 }
 ```
 
-### Deletar Participação
-**Método:** DELETE
-**Endpoint:** `/v3/competition/join`
+Observações: o reward sem `extra` (`total:50`) é **geral** — todos os vencedores recebem; o reward com `position_start/ends=1` é exclusivo do 1º. Custo de 10 `coin` é debitado no join. `SUM_ACHIEVEMENTS` soma achievements `type=0` (point) `item="point"` no período, por membro, reagrupado por time.
+
+### 10.3 Anti-pattern — o que NÃO fazer
 
-**Exemplo de Body:**
 ```json
 {
-  "competition": "race",
-  "player": "tom"
+  "_id": "bad",
+  "title": "Competição quebrada",
+  "period": { "expression": "-0M-;+1M+" },
+  "operation": { "type": 2, "attribute": "valor",
+                 "filters": [ { "param": "uf", "operator": 2, "value": "SP" } ] },
+  "rewards": [
+    { "total": 100, "type": 5, "item": "lottery_x", "extra": { "position": 1 } }
+  ],
+  "active": true,
+  "autoExecute": true
 }
 ```
 
-### Listar Líderes da Competição
-**Método:** POST
-**Endpoint:** `/v3/competition/leader/aggregate?id=:id`
+Por que está errado:
+
+- **`maxWinners` ausente** → default `-1` → `execute` falha no `$limit` (5.3).
+- **`filters[].operator: 2` (LIKE)** → não suportado pelo `buildJsonFilter` → JSON malformado quebra o ranking (2.8). Use `1`/`3`/`4`/`5`/`6`/`7`.
+- **`reward.type: 5` (LOTTERY)** → ignorado; só POINT/CHALLENGE/CATALOG_ITEM premiam (5.6).
+- **`extra.position: 1`** → ignorado; vira prêmio geral. Use `position_start`/`position_ends` (3.7).
+
+---
+
+## Checklist de Configuração
 
-### Executar Competição
-**Método:** GET
-**Endpoint:** `/v3/competition/:id/execute`
-**Descrição:** Finaliza a competição, calcula resultados e premia os vencedores.
+- [ ] `active: true` (sem isso, não recebe join nem executa).
+- [ ] `maxWinners >= 1` (default `-1` quebra a execução).
+- [ ] `period.expression` válida; lembre que **editar** recalcula `startDate`/`endDate` (keywords deslocam a janela).
+- [ ] `operation.type` definido; `item`/`attribute`/`achievement_type` coerentes com o tipo.
+- [ ] `operation.sort`: `-1` (ou `0`) para "maior vence", `1` para "menor vence".
+- [ ] Filtros de `operation` usam apenas operadores EQUAL/REGEX/GT/GTE/LT/LTE.
+- [ ] Prêmios por posição usam **`position_start`/`position_ends`**, nunca `position`.
+- [ ] Prêmios e custos usam apenas `type` 0/1/2 (POINT/CHALLENGE/CATALOG_ITEM).
+- [ ] Itens referenciados (point_category, catalog_item, challenge, actionId) existem antes.
+- [ ] Em `teamCompetition`, os times existem e têm membros em `team_player`; inscreva **times**, não players.
+- [ ] Player/time inscrito existe na coleção `principal` (senão `*_is_not_allowed`).
+- [ ] Notificações de vitória usam `event: 0` e `scope != 99`.
+- [ ] Triggers de competição usam `entity: "competition"` ou `"competition_join"`.
+- [ ] Após premiação, lembre-se de que `player_status` só atualiza no próximo evento do jogador.
+- [ ] Para auto-execução: `autoExecute: true` **e** `period.endDate` definido; reative `autoExecute` após qualquer `undoExecute`.
 
-### Reverter Execução
-**Método:** DELETE
-**Endpoint:** `/v3/competition/:id/execute`
+---
 
-## Validações e Testes
+## Regras de Ouro (resumo operacional)
 
-- [ ] Competição aparece na lista GET /v3/competition
-- [ ] Jogador consegue se inscrever (join)
-- [ ] Lista de líderes retorna dados ordenados
-- [ ] Ao executar, vencedores recebem recompensas
-- [ ] Custo de inscrição é debitado corretamente
+1. Competição grava achievements **direto** — não confie em level-up/webhook/`player_status` automáticos.
+2. `maxWinners >= 1` sempre.
+3. Prêmio por posição = `position_start`/`position_ends`. `position` não existe para o runtime.
+4. Filtros: só 6 operadores. Outros quebram o ranking.
+5. Editar uma competição recalcula o período — cuidado com keywords.
+6. Só o evento **win** notifica/triga na apuração. "create/join/end" não geram notificação.