funifier-mcp 0.2.26 → 0.2.27

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

@@ -1,112 +1,845 @@
-# Lottery (Sorteio)
+# `lottery`
 
 **Acesso Studio:** `/studio/lottery`
 **API Endpoint:** `/v3/lottery`
+**Endpoint Legado:** `/2.0.0/lottery`
+**Coleções MongoDB:** `lottery`, `lottery_folder`, `lottery_ticket` (vencedores ficam em `achievement` com `type=5`)
 
-## O que é
+---
 
-Configuração de sorteios e concursos. Permite criar sorteios nos quais os jogadores participam com cupons obtidos em outras mecânicas, como desafios. É possível definir datas, limites de ganhadores e prêmios para os sorteados.
+## 1. Visão Geral
 
-## Quando usar
+O módulo `lottery` implementa a mecânica de **sorteio** (loteria/rifa) da gamificação Funifier. Jogadores acumulam **bilhetes** (`lottery_ticket`) e, em uma data de sorteio (`drawDate`), o sistema escolhe um ou mais bilhetes vencedores por um dos métodos de escolha suportados. Cada vencedor recebe um `Achievement` do tipo `TYPE_LOTTERY (5)` e, opcionalmente, recompensas (`rewards`).
 
-- Para criar campanhas promocionais com prêmios
-- Para sorteios de viagens, produtos ou experiências
-- Para incentivar participação em desafios (cupons como recompensa)
+Papel arquitetural:
 
-## Dependências
+- A configuração do sorteio é um documento na coleção `lottery`. Os bilhetes são documentos independentes em `lottery_ticket`, ligados por `lottery_ticket.lottery = lottery._id`.
+- **Não há coleção própria de "vencedores"**: o resultado de um sorteio é gravado na coleção `achievement` (`type=5, item=<lotteryId>`), reutilizando todo o motor de `AchievementManager` (totais, level-up, player_status, triggers, webhooks). Por isso o módulo `lottery` depende fortemente do módulo [achievement](achievement.md).
+- A execução pode ser **manual** (`GET /v3/lottery/{id}/execute`) ou **automática** (thread `AsyncProcessor`, a cada 5 minutos, para loterias com `autoExecute=true` e `drawDate` no passado).
 
-- **Virtual Good** (opcional): itens podem ser usados como prêmio do sorteio
+Problemas que resolve:
 
-## Checklist de Configuração no Studio
+- Distribuição de prêmios "alguém tem que ganhar" por sorteio (chance proporcional ao número de bilhetes).
+- Campanhas promocionais onde bilhetes são distribuídos como recompensa de desafios/ações (via `Requirement.type = TYPE_LOTTERY_TICKET (50)` no módulo [challenge](challenge.md)).
 
-- [ ] Definir título e descrição do sorteio
-- [ ] Definir data do sorteio (drawDate)
-- [ ] Definir método de escolha (random_ticket)
-- [ ] Definir número máximo de ganhadores (maxWinners)
-- [ ] Definir limite por jogador (maxPerPlayer)
-- [ ] Configurar recompensas (rewards)
-- [ ] Definir se executa automaticamente (autoExecute)
+Relação com outros módulos:
 
-## API Endpoints
+- [achievement](achievement.md) — vencedor vira `Achievement` type=5; recompensas viram achievements adicionais (pontos/items/desafios).
+- [challenge](challenge.md) — desafios podem creditar bilhetes de loteria como recompensa (`TYPE_LOTTERY_TICKET`).
+- [trigger](../guides/triggers.md) — dispara `before_win`, `after_win` (entidade `lottery`) e `after_execute`.
+- `notification` — notificações `EVENT_WIN` configuradas no sorteio são enviadas ao vencedor.
+- `virtual_good` / `catalog_item`, `point_category` — possíveis tipos de recompensa.
 
-### Listar Sorteios
-**Método:** GET
-**Endpoint:** `/v3/lottery`
+> **Fora de escopo:** existe um módulo distinto **`brazilian_lottery`** (`com.funifier.engine.brazilian.lottery.*`, coleção `brazilian_lottery`), que modela a loteria federal brasileira (padrão de números da sorte, `FederalResult`, `WinnerRule`). Apesar do nome semelhante, é um módulo separado, com entidade, manager e REST próprios — **não** é coberto por este documento.
+
+---
+
+## 2. Arquitetura e Fluxos
+
+### 2.1 Classes envolvidas
+
+| Classe | Papel |
+|---|---|
+| `com.funifier.engine.lottery.Lottery` | Entidade/POJO do sorteio — documento raiz (`Lottery.java`, L26-128) |
+| `com.funifier.engine.lottery.LotteryTicket` | Bilhete — documento em `lottery_ticket` |
+| `com.funifier.engine.lottery.LotteryFolder` | Agrupamento (pasta) de sorteios |
+| `com.funifier.engine.lottery.Participant` | DTO de aggregation (`_id`=player, `tickets`=contagem) — não persistido |
+| `com.funifier.engine.lottery.LotteryManager` | Manager monolítico (`LotteryManager.java`, L36-888): CRUD, tickets, execução do sorteio, rollback |
+| `com.funifier.rest.v3.rest.LotteryRest` | Controller REST v3 (`/v3/lottery`) |
+| `com.funifier.rest.engine.LotteryRest` | Controller REST legado (`/2.0.0/lottery`) |
+| `com.funifier.controller.AsyncProcessor` | Thread assíncrona que executa sorteios automáticos (L22-54) |
+| `com.funifier.engine.challenge.Requirement` | Estrutura de uma recompensa (`rewards[]`) |
+
+**Não há `Repository`/`Dao` dedicado** — toda manipulação MongoDB é feita diretamente via `Jongo` dentro de `LotteryManager`.
+
+### 2.2 Pipeline principal — `execute(String id)` (L607-848)
+
+Método **`synchronized`**. Síncrono. Não há transação MongoDB — cada `save`/`addAchievement` é independente.
+
+```
+[1] Carrega Lottery por id (L609).
+    ⚠️ Se não existir → NPE em L612 (lottery.maxWinners) → HTTP 500.
+[2] max = maxWinners > 0 ? maxWinners : 1   (usado só por first_ticket/last_ticket, L612)
+[3] Cria índice {random:1} em lottery_ticket (L619) — VESTIGIAL (ver §7).
+[4] who = teamManager.findUserIdsByPrincipalIds(lottery.principals) (L622)
+    - principals null/vazio → who = null → sorteio considera TODOS os jogadores.
+    - principals com ids → expande times em userIds + inclui os próprios ids.
+[5] Despacha por choiceMethod (L625-639):
+    random_ticket → executeRandomTicket(...)   ($sample do MongoDB)
+    random_value  → executeRandomValue(...)     (escolhe um value e pega todos os tickets com esse value)
+    first_ticket  → sort {created:1}, limit max
+    last_ticket   → sort {created:-1}, limit max
+[6] SE selected != null E selected.size() > 0 E lottery.executedDate == null (L643):
+    Para cada ticket vencedor (L647):
+      [6.1] Achievement(novoId, ticket.player, total=1, TYPE_LOTTERY=5, item=lottery.id, now)
+            achievement.extra.ticket = ticket.id                       (L650-652)
+      [6.2] trigger.execute(lottery, BEFORE_WIN, player, context)      (L659)
+      [6.3] achievementManager.addAchievement(achievement)             (L661)
+      [6.4] trigger.execute(lottery, AFTER_WIN, player, context)       (L663)
+      [6.5] Processa rewards[] (L668-819) — ver §6
+      [6.6] Envia notifications EVENT_WIN ao vencedor (L824-830)
+    [6.7] Recarrega lottery2, seta executedDate = now, save (L835-837)
+    [6.8] trigger.execute(lottery2, "after_execute", null, {lottery, winners}) (L840-844)
+[7] Retorna a lista de tickets vencedores (selected).
+```
+
+**Consequência crítica (L643):** se nenhum ticket for selecionado (ex.: loteria sem bilhetes), `executedDate` **não** é gravado. Uma loteria `autoExecute=true` sem bilhetes é reprocessada pelo `AsyncProcessor` a cada 5 minutos **indefinidamente** (ver §5 e §9).
+
+### Fluxo de execução — `execute(id)`
+
+```mermaid
+flowchart TB
+    A["execute(id) synchronized"] --> B{lottery existe?}
+    B -- não --> Z["NPE → HTTP 500"]
+    B -- sim --> C["who = principals → userIds"]
+    C --> D{choiceMethod}
+    D -- random_ticket --> E["executeRandomTicket\n$sample"]
+    D -- random_value --> F["executeRandomValue\nescolhe value, pega todos iguais"]
+    D -- first_ticket --> G["sort created asc, limit max"]
+    D -- last_ticket --> H["sort created desc, limit max"]
+    E --> I{selected > 0 E\nexecutedDate == null?}
+    F --> I
+    G --> I
+    H --> I
+    I -- não --> Y["NÃO grava executedDate\n(loteria continua aberta)"]
+    I -- sim --> J["loop vencedores"]
+    J --> K["Achievement type=5\n+ trigger before_win/after_win"]
+    K --> L["processa rewards (§6)"]
+    L --> M["notifications EVENT_WIN"]
+    M --> N["executedDate = now (save)"]
+    N --> O["trigger after_execute"]
+```
+
+### 2.3 Algoritmo `executeRandomTicket` (L408-498)
+
+Método de escolha `random_ticket`: cada bilhete tem chance igual; jogador com mais bilhetes tem mais chance.
+
+```
+totTickets  = count({lottery:id})                                  (L411)
+totPlayers  = distinct(player) onde lottery=id [e player ∈ who]    (L412-414)
+
+maxWinners  = maxWinners < 0 ? totPlayers : (maxWinners == 0 ? 1 : maxWinners)  (L417)
+maxPerPlayer= maxPerPlayer < 0 ? totTickets : maxPerPlayer                       (L418)
+maxTickets  = min(maxWinners * maxPerPlayer, totTickets)                          (L419)
+
+required = maxTickets
+enquanto required > 0:
+    list = aggregate({lottery:id, used != true [, player ∈ who]})
+           .and($sample: { size: required })                       (L438-446)
+    para cada ticket em list:
+        se player novo E (#jogadores já escolhidos >= maxWinners):
+            rejeita                                                 (L453-455)
+        senão:
+            incrementa contador do jogador
+            se contador <= maxPerPlayer: seleciona                  (L466-467)
+            senão: rejeita
+        ticket.used = true; save(ticket)                            (L475-476)
+    se não há mais tickets com used != true: required = 0           (L484-485)
+    senão se selected >= maxTickets: required = 0                   (L487-488)
+    senão: required = maxTickets - selected.size()                  (L491)
+```
+
+Observações:
+- A seleção é feita por `$sample` do MongoDB (amostra aleatória), **não** pelo campo `random` do bilhete.
+- Todos os bilhetes percorridos no loop recebem `used=true` (mesmo os rejeitados), o que evita reescolha na próxima iteração.
+
+### 2.4 Algoritmo `executeRandomValue` (L502-600)
+
+Método `random_value`: escolhe **um valor** aleatório entre os bilhetes e premia **todos** os bilhetes com aquele `value` (ex.: "número sorteado").
+
+```
+n = count({lottery:id})
+r = floor(random() * n)
+sample = find({lottery:id}).skip(r).limit(1)                       (L529-531)
+se sample.value != null:                                          (L532)
+    seleciona (respeitando maxWinners/maxPerPlayer) todos os
+    tickets com {lottery:id, value: sample.value, used != true}    (L541-543)
+    marcando used=true em cada um percorrido.
+senão:
+    retorna lista VAZIA → nenhum vencedor (ver §5.9)
+```
+
+Limites `maxWinners`/`maxPerPlayer`/`maxTickets` calculados igual a `executeRandomTicket`.
+
+⚠️ **Falha silenciosa (L532):** toda a seleção é condicionada a `sample.value != null`. Se o bilhete sorteado aleatoriamente tiver `value` nulo, o método retorna lista vazia mesmo havendo bilhetes. Combinado com a guarda de L643, o sorteio "ghost": não há vencedor e `executedDate` não é gravado.
+
+### 2.5 Execução automática — `AsyncProcessor` + `findLotteriesToExecute`
+
+```mermaid
+sequenceDiagram
+    participant Thread as AsyncProcessor (1 por gamificação)
+    participant LM as LotteryManager
+    participant Mongo as lottery / lottery_ticket
+    participant AM as AchievementManager
+    participant Trg as TriggerManager
+    participant Ntf as NotificationManager
+
+    loop a cada 5 minutos (L29)
+        Thread->>LM: findLotteriesToExecute()
+        LM->>Mongo: find {executedDate:{$exists:false},<br/>drawDate:{$lte:now}, autoExecute:true}
+        Mongo-->>LM: loterias pendentes
+        loop para cada loteria
+            Thread->>LM: execute(lottery.id)
+            LM->>Mongo: seleciona tickets vencedores
+            LM->>Trg: before_win / after_win
+            LM->>AM: addAchievement(type=5)
+            LM->>Ntf: notification EVENT_WIN
+            LM->>Mongo: set executedDate=now
+            LM->>Trg: after_execute
+        end
+    end
+```
+
+Query de `findLotteriesToExecute()` (L399-402):
+
+```js
+db.lottery.find({
+  executedDate: { $exists: false },
+  drawDate:     { $lte: <now> },
+  autoExecute:  true
+})
+```
+
+Execução **manual** (`GET /v3/lottery/{id}/execute`) **ignora** `autoExecute` e `drawDate` — executa imediatamente qualquer loteria ainda não executada.
+
+### 2.6 Rollback — `undoExecute(String id)` (L860-887)
+
+```
+SE lottery != null E lottery.executedDate != null:
+  [1] Para cada Achievement (type=5, item=lottery.id):                    (L866)
+        remove achievements onde {extra.origin: <id_do_achievement>}      (L867)
+        → apaga as recompensas derivadas (pontos/items)
+  [2] remove achievements {type:5, item:lottery.id}                       (L871)
+        → apaga os registros de vencedor
+  [3] update {lottery:id} → $unset {used:""} em todos os tickets          (L874-876)
+        → bilhetes voltam a ficar disponíveis
+  [4] lottery.autoExecute = false                                         (L880)  ⚠️
+      lottery.executedDate = null
+      save(lottery)                                                       (L882)
+  [5] remove notifications {item.type:lottery, item.id:lottery.id}        (L885)
+```
+
+⚠️ **Efeitos colaterais não óbvios:**
+- `autoExecute` é forçado para `false` (L880). Após um rollback, a loteria **não** será reexecutada automaticamente pelo scheduler — só manualmente.
+- `drawDate` **não** é resetada (L879, comentada).
+- `undoExecute` **não** chama `updateUserStatus` — o `player_status` do ex-vencedor permanece desatualizado (mostrando pontos/items já removidos) até o próximo evento que recalcule o status.
+
+---
+
+## 3. Estrutura dos Objetos
+
+### 3.1 `Lottery` — documento raiz (coleção `lottery`)
+
+Anotação: `@JsonIgnoreProperties(ignoreUnknown=true)` — campos não mapeados enviados no POST são **silenciosamente descartados**.
+
+| Campo | Tipo | Padrão | Obrigatório | Descrição |
+|---|---|---|---|---|
+| `_id` | String | `Guid.shortTimeMillis()` se ausente | Não (auto) | Id curto interno (`insert`, L48). **Não** é ObjectId Mongo |
+| `title` | String | — | "Sim" só na doc | Título. **Sem validação server-side** — aceita ausente |
+| `description` | String | — | "Sim" só na doc | Descrição. Sem validação |
+| `image` | String | — | "Sim" só na doc | URL da imagem. Sem validação |
+| `tags` | List\<String> | `[]` | Não | Tags (filtráveis por `$all` em `GET /v3/lottery`) |
+| `drawDate` | Date | — | "Sim" só na doc | Data do sorteio. Usada pelo scheduler. Sem validação |
+| `autoExecute` | boolean | `false` | Não | Se `true`, o scheduler executa após `drawDate` |
+| `choiceMethod` | String | `"random_ticket"` se null (L53-54) | Não (auto) | Método de escolha (ver §3.5) |
+| `maxWinners` | long | `-1` | Não | Máx. de jogadores premiados. `-1`=ilimitado (todos jogadores distintos); `0`→tratado como `1` (L417) |
+| `maxPerPlayer` | long | `-1` | Não | Máx. de bilhetes premiados por jogador. `-1`=ilimitado |
+| `notifications` | List\<NotificationDefinition> | `[]` | Não | Notificações disparadas ao vencedor (`EVENT_WIN`) |
+| `link` | String | — | "Sim" só na doc | Call-to-action. Sem validação, sem uso no backend |
+| `extra` | Map\<String,Object> | `{}` | Não | Campos arbitrários |
+| `principals` | List\<String> | `null` | Não | Ids de jogadores/times elegíveis. `null`/vazio = todos |
+| `folder` | String | `"default"` se null/vazio (L58-60) | Não (auto) | Pasta. Cria `LotteryFolder` automaticamente se não existir (L61-67) |
+| `techniques` | List\<String> | `null` | Não | Códigos de técnica de jogo (ver §3.6). Auto-preenchido externamente |
+| `executedDate` | Date | `null` | — (controle) | Preenchido após execução (L836). Marca loteria como sorteada |
+| `createdDate` | Date | `new Date()` se null (L50-51) | Não (auto) | Data de criação |
+| `rewards` | List\<Requirement> | `[]` | Não | Recompensas dos vencedores (ver §3.4 e §6) |
+
+#### Campos computados / não persistidos
+
+Nenhum — todos os campos de `Lottery` são persistidos via Jongo `save` (full replace).
+
+#### Comportamento de `save` (full replace)
+
+`insert()` faz `c.save(lottery)` (L69). O Jongo serializa o **POJO inteiro**: qualquer campo ausente no objeto vira ausente no documento. Logo:
+
+- **`PUT`/`POST` é sempre full-replace, nunca merge parcial.** Omitir um campo no body o **apaga** do documento (exceto os que recebem default no `insert`).
+- Omitir `createdDate` num update faz `insert()` re-setar `createdDate = now` (L50-51) → **a data de criação é resetada a cada atualização** que não reenvie o valor.
+
+#### Métodos com nomes específicos (uso via trigger/Groovy)
+
+`Lottery` expõe setters individuais (`setExecutedDate`, `setId`, `setTitle`, `setAutoExecute`, `setCreatedDate`, L113-127) — comentário em L112 indica que existem para alterar campos via trigger.
+
+### 3.2 `LotteryTicket` — bilhete (coleção `lottery_ticket`)
+
+`@JsonIgnoreProperties(ignoreUnknown=true)`.
+
+| Campo | Tipo | Padrão | Obrigatório | Descrição |
+|---|---|---|---|---|
+| `_id` | String | `Guid.newShortGuid()` se ausente (L300-301) | Não (auto) | Id do bilhete. **Diferente** do `Lottery._id` que usa `shortTimeMillis()` |
+| `lottery` | String | — | **Sim** (silencioso) | Id da loteria. Se ausente, `insertTicket` faz **no-op silencioso** (L299) |
+| `player` | String | — | **Sim** (silencioso) | Jogador dono. Se ausente, no-op silencioso |
+| `value` | Object | — | Não | Valor livre (número/texto). Usado por `random_value` |
+| `created` | Date | `new Date()` se null (L303-304) | Não (auto) | Data de criação |
+| `random` | long | `random()*10_000_000` se `-1` (L306-309) | Não (auto) | Número aleatório. **Vestigial neste módulo** (ver §7) |
+| `extra` | Map\<String,Object> | `null` | Não | Atributos arbitrários. Convenção: `extra.origin` quando o bilhete vem de recompensa |
+| `used` | Boolean | `null` | — (controle) | Marcado `true` durante a execução; `$unset` no rollback |
+
+### 3.3 `LotteryFolder` — pasta (coleção `lottery_folder`)
+
+| Campo | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `_id` | String | = `folder` informado | Id da pasta |
+| `title` | String | = `_id` na criação automática (L65) | Título |
+
+Criada automaticamente no `insert` da loteria quando o `folder` informado ainda não existe (L61-67). A pasta `"default"` é criada na primeira loteria sem `folder`.
+
+### 3.4 `Requirement` — recompensa (`Lottery.rewards[]`)
+
+Mesma classe usada por `challenge`/`competition` (`com.funifier.engine.challenge.Requirement`). No contexto de loteria, apenas alguns campos são lidos por `execute` (ver §6):
+
+| Campo | Tipo | Uso em lottery |
+|---|---|---|
+| `total` | int | Quantidade. `total == 0` → recompensa ignorada (L694). Valor negativo é convertido para positivo (`abs`, L696) |
+| `type` | int | Tipo da recompensa (ver tabela abaixo) |
+| `item` | String | Id do item; valor especial `"FUNIFIER_RANDOM"` para item de catálogo aleatório (L703) |
+| `folder` | String | Filtra catálogo no caso `FUNIFIER_RANDOM` (L708-713) |
+| `restrict` | boolean | Se `true`, só credita item de catálogo válido/disponível (L716-720) |
+| `operation`, `period`, `perPlayer` | — | **Ignorados** no fluxo de loteria (lógica de time/dedução está comentada, L671-689) |
+
+**Tipos de recompensa (`Requirement.TYPE_*`) efetivamente creditados pela loteria:**
+
+| Valor | Constante | Creditado? | Observação |
+|---|---|---|---|
+| `0` | `TYPE_POINT` | ✅ Sim | Coleção `point_category` (L796-797) |
+| `1` | `TYPE_CHALLENGE` | ✅ Sim | Coleção `challenge` (L799-800) |
+| `2` | `TYPE_CATALOG_ITEM` | ✅ Sim | Coleção `catalog_item`; suporta `FUNIFIER_RANDOM` (L802-803) |
+| `50` | `TYPE_LOTTERY_TICKET` | ❌ **NÃO** | Passa pelo filtro (L694) mas é **silenciosamente descartado** — ver §6 e §7 |
+| `3,4,6,7,...` | LEVEL, CROWN, MYSTERY_BOX… | ❌ Não | Nem entram no filtro de L694 |
+
+### 3.5 Métodos de escolha (`choiceMethod`)
+
+Constantes definidas em `Lottery.java` (L31-47):
+
+| Valor | Constante | Comportamento |
+|---|---|---|
+| `random_ticket` | `CHOICE_METHOD_RANDOM_TICKET` | (padrão) Escolhe bilhetes aleatórios via `$sample`, respeitando `maxWinners`/`maxPerPlayer` |
+| `random_value` | `CHOICE_METHOD_RANDOM_VALUE` | Sorteia um `value` e premia todos os bilhetes com esse valor |
+| `first_ticket` | `CHOICE_METHOD_FIRST_TICKET` | Os `max` (=`maxWinners` ou 1) bilhetes mais antigos por `created` |
+| `last_ticket` | `CHOICE_METHOD_LAST_TICKET` | Os `max` bilhetes mais recentes por `created` |
+| ~~`more_tickets`~~ | comentado (L38) | **NÃO suportado** — código comentado |
+| ~~`less_tickets`~~ | comentado (L41) | **NÃO suportado** — código comentado |
+
+> Para `first_ticket`/`last_ticket`, `maxPerPlayer` é **ignorado** — o `$limit` usa apenas `max` (L612, 634, 638).
+
+### 3.6 Técnica de jogo (`techniques`) — `GT74`
+
+O campo `techniques` **não** é preenchido pelo módulo de loteria no CRUD. Ele é populado por uma rotina de manutenção do `GameTechniqueManager`, que percorre as loterias sem técnica e adiciona o código `LOTTERY_CODE = "GT74"` (`GameTechniqueManager.java`, L73 + L149-159):
+
+```java
+String LOTTERY_CODE = "GT74";
+...
+for(Lottery o : lotteries) {
+    if(o.techniques == null) { o.techniques = new ArrayList<>(); }
+    o.techniques.add(LOTTERY_CODE);
+    jongo.getCollection(Entity.LOTTERY.collection).save(o);
+}
+```
+
+`GT74` é o código operacional da técnica **Lottery** no grafo de técnicas do Funifier.
+
+### 3.7 Ciclo de vida da loteria
+
+```mermaid
+stateDiagram-v2
+    [*] --> Aberta: insert (executedDate=null)
+    Aberta --> Aberta: drawDate no futuro\n(scheduler ignora)
+    Aberta --> Executada: GET /{id}/execute (manual)\nou scheduler (autoExecute + drawDate<now)
+    Aberta --> Aberta: execute sem bilhetes\n(executedDate NÃO gravado → re-tentado)
+    Executada --> Revertida: DELETE /{id}/execute\n(undoExecute)
+    Revertida --> Executada: re-executar (manual)\n— autoExecute=false impede scheduler
+    Executada --> [*]: DELETE /{id}\n(orfãos: achievements type=5 ficam)
+    Aberta --> [*]: DELETE /{id}
+    note right of Revertida
+        executedDate=null
+        autoExecute=false
+        used dos tickets removido
+    end note
+```
+
+---
+
+## 4. Endpoints
+
+Todos os endpoints v3 exigem **Bearer token** (resolvido via `AuthBean`/`FrontController.getInstance(apiKey)`).
+
+### 4.1 `GET /v3/lottery/{id}`
+
+Busca uma loteria por id. Retorna o documento `Lottery` (ou `null` serializado se não existir). (L51-57)
+
+### 4.2 `GET /v3/lottery`
+
+**Listar loterias (aggregation com filtros).** (L81-105)
+
+| Param | Tipo | Descrição |
+|---|---|---|
+| `id` | String | Filtra por `_id` exato |
+| `title` | String | Regex case-insensitive em `title` |
+| `description` | String | Regex case-insensitive em `description` |
+| `executed_min` / `executed_max` | String | Faixa sobre `executedDate` (RFC 3339) |
+| `published_min` / `published_max` | String | Faixa sobre `createdDate` (RFC 3339 ou keyword `-1d`, `-30m`…) |
+| `tags` | CSV | `tags: {$all: [...]}` |
+| `fields` | CSV | Projeção `$project` |
+| `orderby` | String | Campo de ordenação |
+| `reverse` | bool | `true`=desc |
+| `max_results` | int | Limite (default 100; ≤0 vira 100, L144) |
+
+**Comportamento real:**
+- **Não existe parâmetro `q`** neste endpoint (diferente de `/ticket`). Não há injeção de pipeline aqui.
+- A resposta usa `toJsonRemoveNullFields` — campos `null` são omitidos do JSON.
+
+### 4.3 `POST /v3/lottery`
+
+**Criar loteria.** Body = objeto `Lottery`. (L164-169)
+
+| Aspecto | Detalhe |
+|---|---|
+| Persistência | `c.save(lottery)` — full replace por `_id` |
+| Defaults automáticos | `_id`=`shortTimeMillis()`, `createdDate`=now, `choiceMethod`=`random_ticket`, `folder`=`default` (+ cria a pasta) |
+| Validação | **Nenhuma** sobre campos "obrigatórios" da doc (title, drawDate, etc.) |
+| Status | `201 Created` com o objeto serializado |
+
+### 4.4 `PUT /v3/lottery/{id}`
+
+**Atualizar loteria.** (L181-187)
+
+⚠️ **Comportamento não-óbvio:** o handler chama `getLotteryManager().insert(lottery)` **sem usar o `{id}` da URL**. Consequências:
+
+- O id efetivo é `lottery._id` **do body**, não o da URL.
+- Se o body **não** trouxer `_id`, `insert()` gera um **novo** id (`shortTimeMillis`) e **cria uma loteria nova** — o `PUT` não atualiza nada.
+- É full-replace: campos omitidos são apagados; `createdDate` omitido é re-setado para now.
+- Não há diferença real entre `POST` e `PUT` além do código de status — ambos chamam `insert`.
+
+### 4.5 `DELETE /v3/lottery/{id}`
+
+Remove a loteria. (L118-124, manager L221-224)
+
+```js
+db.lottery_ticket.remove({ lottery: id })   // remove TODOS os bilhetes
+db.lottery.remove({ _id: id })              // remove a loteria
+```
+
+⚠️ **Não remove**: achievements de vencedor (`type=5, item=id`) nem notificações. Deletar uma loteria já executada deixa **achievements órfãos** na coleção `achievement` (continuam contando no saldo dos jogadores).
+
+### 4.6 `POST /v3/lottery/ticket`
+
+**Criar bilhete.** Body = `LotteryTicket`. (L234-259)
+
+| Aspecto | Detalhe |
+|---|---|
+| `player` especial | `"me"` → resolve para o jogador do token (L246-248) |
+| Validação | `ticket == null` → 400; `ticket.player == null` → 400 |
+| Restrições | `checkRestrictions(lottery, player)` — se houver, retorna **400** com a lista |
+| Defaults | `_id`=`newShortGuid()`, `created`=now, `random`=aleatório |
+
+`checkRestrictions` (L250-274) pode retornar: `item_not_exist`, `was_executed`, `principal_not_allowed`.
+
+⚠️ **Bug — NPE quando a loteria não existe:** em L259-264, após `if(item == null) restrictions.add("item_not_exist")`, o código segue para `if(item.executedDate != null)` **sem `else`**, desreferenciando `item` nulo → **`NullPointerException` → HTTP 500** (em vez de um 400 limpo com `item_not_exist`). O mesmo ocorre se `ticket.lottery` for `null` (o `findOne` retorna null).
+
+### 4.7 `GET /v3/lottery/ticket`
+
+**Listar bilhetes.** (L281-310, manager L330-392)
+
+| Param | Tipo | Descrição |
+|---|---|---|
+| `id`, `lottery`, `player` | String | Filtros exatos (`player="me"` resolve via token) |
+| `value` | String | Filtro por valor |
+| `q` | String | **Critério MongoDB raw** injetado no `$match` (L354) — ver §8 |
+| `fields`, `orderby`, `reverse`, `max_results` | — | Projeção/ordenação/limite |
+| `published_min`/`max` | String | Faixa sobre `created` |
+
+### 4.8 `GET /v3/lottery/winner`
+
+**Listar vencedores.** (L357-400)
+
+Internamente busca em `achievement`: `findAllAchievements(player, TYPE_LOTTERY=5, lottery, ...)`. O parâmetro `lottery` mapeia para `achievement.item`. Cada resultado é enriquecido com `extra.player_name` e `extra.player_image` (L387-397).
+
+| Param | Descrição |
+|---|---|
+| `lottery` | Id da loteria (= `achievement.item`) |
+| `player` | Filtra por jogador (`"me"` suportado) |
+| `q`, `fields`, `published_min/max`, `orderby`, `reverse`, `max_results` | Padrão de query de achievement |
+
+**Response (200):**
 
-**Exemplo de Resposta:**
 ```json
 [
   {
-    "title": "Travel to Cancun",
-    "description": "Travel with a companion to Cancun, with airfare and accommodation, for 7 days.",
-    "drawDate": 1690824650503,
-    "autoExecute": true,
-    "choiceMethod": "random_ticket",
-    "maxWinners": 1,
-    "maxPerPlayer": 1,
-    "techniques": ["GT74"],
-    "rewards": [
-      {
-        "total": 1,
-        "type": 2,
-        "item": "flight_ticket"
-      }
-    ],
-    "_id": "DTj0x5z"
+    "player": "player@funifier.com",
+    "total": 1,
+    "type": 5,
+    "item": "DTj0x5z",
+    "time": 1497962136775,
+    "extra": {
+      "ticket": "5943ceba8517662bd342620d",
+      "player_name": "Cleia Santos",
+      "player_image": { "small": { "url": "photo.png" } }
+    },
+    "_id": "594916988517661881b33b96"
   }
 ]
 ```
 
-### Criar Sorteio
-**Método:** POST
-**Endpoint:** `/v3/lottery`
-(Body igual ao exemplo de resposta acima)
+### 4.9 `GET /v3/lottery/participants`
+
+**Painel de participação.** (L402-435)
+
+Param: `lottery` (id). Agrega `lottery_ticket` agrupando por `player` (`Participant{_id, tickets}`) e combina com a contagem de vencedores.
+
+**Response (200):**
 
-### Deletar Sorteio
-**Método:** DELETE
-**Endpoint:** `/v3/lottery/:id`
+```json
+{
+  "total_participants": 2,
+  "total_tickets": 15,
+  "total_winners": 1,
+  "participants": [ { "_id": "tom", "tickets": 10 }, { "_id": "ana", "tickets": 5 } ],
+  "lottery": { "_id": "DTj0x5z", "title": "..." },
+  "winners": [ { "player": "tom", "type": 5, "item": "DTj0x5z" } ]
+}
+```
 
-### Listar Cupons
-**Método:** GET
-**Endpoint:** `/v3/lottery/ticket?lottery=:id`
+### 4.10 `GET /v3/lottery/{id}/execute`
 
-### Criar Cupom
-**Método:** POST
-**Endpoint:** `/v3/lottery/ticket`
+**Executar o sorteio manualmente.** (L447-459) Ignora `autoExecute`/`drawDate`. Chama `manager.execute(id)`.
+
+**Response (200):**
 
-**Exemplo de Body:**
 ```json
 {
-  "lottery": "DTj0x5z",
-  "player": "tom"
+  "lottery": { "_id": "DTj0x5z", "executedDate": 1690824999999, "...": "..." },
+  "tickets": [ { "_id": "tkt1", "lottery": "DTj0x5z", "player": "tom", "used": true } ]
 }
 ```
 
-### Deletar Cupom
-**Método:** DELETE
-**Endpoint:** `/v3/lottery/ticket/:id`
+⚠️ Executar um id inexistente → NPE no manager (L612) → **HTTP 500**.
+
+### 4.11 `DELETE /v3/lottery/{id}/execute`
+
+**Reverter a execução (rollback).** (L462-473) Chama `undoExecute(id)` (ver §2.6).
+
+**Response (200):**
+
+```json
+{ "lottery": { "...": "..." }, "message": "Execution Rollback Done" }
+```
+
+### 4.12 Endpoints legados `/2.0.0/lottery`
+
+Controller `com.funifier.rest.engine.LotteryRest`. Auth via query param `?api_key=...` (sem Bearer token).
+
+| Endpoint | Comportamento |
+|---|---|
+| `GET /2.0.0/lottery/{id}` | `find(id)` |
+| `GET /2.0.0/lottery` | `findAll()` — **sem filtros** (lista tudo) |
+| `DELETE /2.0.0/lottery/{id}` | `delete(id)` |
+| `POST /2.0.0/lottery` | `insert(lottery)` |
+| `POST /2.0.0/lottery/ticket` | `insertTicket(ticket)` — **sem** `checkRestrictions` e **sem** validação de `player` (no-op silencioso se faltar `lottery`/`player`) |
+| `GET /2.0.0/lottery/execute/{id}` | `execute(id)` — note o **formato de path diferente** do v3 (`/execute/{id}` vs `/{id}/execute`) |
+
+O legado **não** possui endpoints de `winner`, `participants`, `update` (PUT) nem `undoExecute`. Não recomendado para novas integrações.
+
+---
+
+## 5. Regras de Negócio
+
+Regras presentes no código mas ausentes do schema das entidades:
+
+### 5.1 Semântica de `maxWinners` / `maxPerPlayer` (L417-419)
+
+- `maxWinners = -1` (padrão) → **ilimitado** = total de jogadores distintos.
+- `maxWinners = 0` → tratado como **1** (não como "nenhum").
+- `maxPerPlayer = -1` (padrão) → ilimitado = total de bilhetes.
+- `maxTickets = min(maxWinners * maxPerPlayer, totTickets)` limita o total premiado.
+- Em `first_ticket`/`last_ticket`, `maxPerPlayer` é **ignorado**.
+
+### 5.2 Elegibilidade por `principals` (L276-295)
+
+`checkIsPrincipalAllowed`:
+- `principals` null/vazio → **todos** podem participar.
+- Contém o id do jogador/time → permitido.
+- Contém um id de **time** → permitido se o jogador for membro do time (`isUserOfTeam`).
+
+`principals` afeta **somente** a criação de bilhetes (`checkRestrictions`) e o universo `who` da execução. **Não** restringe a leitura (`GET /v3/lottery`/`winner`/`participants`).
+
+### 5.3 Loteria não pode receber bilhetes após executada
+
+`checkRestrictions` adiciona `was_executed` quando `executedDate != null` (L264-266). A criação de bilhete via v3 é bloqueada (400). (O legado `/2.0.0` **não** valida isso.)
+
+### 5.4 Execução é idempotente por `executedDate`
+
+`execute` só registra vencedores se `executedDate == null` (L643). Chamar `execute` duas vezes não duplica vencedores — a segunda chamada seleciona tickets (e pode marcá-los `used`) mas não grava achievements porque a guarda falha. Para reexecutar, é preciso `undoExecute` antes.
+
+### 5.5 Loteria sem bilhetes nunca "fecha" (loop infinito do scheduler)
+
+Como `executedDate` só é gravado quando `selected.size() > 0` (L643), uma loteria `autoExecute=true` com `drawDate` no passado e **zero bilhetes** continua aparecendo em `findLotteriesToExecute()` e é reprocessada a cada 5 minutos indefinidamente. Sem efeito de dados (não há vencedor), mas consome ciclos do `AsyncProcessor`.
+
+### 5.6 Recompensa de tipo `LOTTERY_TICKET` é silenciosamente descartada
+
+Ver §6 e §7. Diferente do módulo [achievement](achievement.md), onde `fireAction` cria bilhetes para `TYPE_LOTTERY_TICKET`; em `lottery.execute` essa lógica está comentada.
+
+### 5.7 `delete` não limpa vencedores
+
+`delete` remove loteria + bilhetes, mas não os achievements `type=5`. Saldos dos jogadores continuam refletindo a loteria removida (ver §4.5).
+
+### 5.8 Multi-tenant
+
+Não há campo `apiKey` nos documentos de loteria/bilhete. O isolamento é dado **inteiramente** pelo roteamento de connection do Jongo (`manager.getJongoConnection()`), uma por gamificação.
+
+### 5.9 `random_value` depende de `value` não-null no bilhete sorteado
+
+`executeRandomValue` sorteia **um único** bilhete e usa o `value` dele como número vencedor (L529-531). Se esse bilhete tiver `value == null` (L532), o método retorna **lista vazia** — nenhum vencedor, mesmo havendo bilhetes válidos com valor. É uma falha **probabilística**: depende de qual bilhete o `skip(random)` sortear. Diferente de §5.5 (zero bilhetes), aqui **há** bilhetes, mas o sorteio não premia ninguém e a loteria permanece aberta. Mitigação: em loterias `random_value`, garanta que **todos** os bilhetes tenham `value`.
+
+---
+
+## 6. Comportamentos Automáticos
+
+| Comportamento | Trigger | Impacto | Persistência |
+|---|---|---|---|
+| `_id` da loteria (`shortTimeMillis`) | `insert` se `_id` null | Cria id curto | Sim |
+| `createdDate = now` | `insert` se null | **Reseta em update sem o campo** | Sim |
+| `choiceMethod = random_ticket` | `insert` se null | Default silencioso | Sim |
+| `folder = default` + cria `LotteryFolder` | `insert` se folder vazio | Cria pasta automática | Sim |
+| `_id`/`created`/`random` do bilhete | `insertTicket` | Defaults silenciosos | Sim |
+| Índice `{random:1}` em `lottery_ticket` | Toda `execute` (L619) | Cria índice (vestigial) | Sim |
+| Achievement `type=5` por vencedor | `execute` | Registra vencedor | Sim (coleção `achievement`) |
+| Trigger `before_win`/`after_win` (entidade `lottery`) | Em torno de `addAchievement` do vencedor | Scripts customizados | Side effects |
+| Trigger `after_execute` | Fim de `execute` com vencedores | Notifica fim do sorteio | Side effects |
+| Recompensas (POINT/CHALLENGE/CATALOG_ITEM) | `execute`, por vencedor | Achievements adicionais + `updateUserStatus` | Sim |
+| Notification `EVENT_WIN` | `execute`, por vencedor | Documentos em `notification` | Sim |
+| `used=true` nos bilhetes | `executeRandomTicket`/`executeRandomValue` | Marca bilhetes processados | Sim |
+| Execução automática | `AsyncProcessor` a cada 5 min | Sorteios `autoExecute` vencidos | Sim |
+| Auto-tag `GT74` | `GameTechniqueManager` (rotina externa) | Preenche `techniques` | Sim |
+
+### Fluxo de recompensas — o ramo `LOTTERY_TICKET` descartado
+
+```mermaid
+flowchart TB
+    A["Para cada reward em lottery.rewards"] --> B{"total != 0 E type ∈\n{POINT, CATALOG_ITEM,\nCHALLENGE, LOTTERY_TICKET}?"}
+    B -- não --> X["Ignorado (LEVEL, CROWN,\nMYSTERY_BOX, etc.)"]
+    B -- sim --> C{"item == FUNIFIER_RANDOM\nE type == CATALOG_ITEM?"}
+    C -- sim --> D["catalogManager.findRandom/\nfindValidRandom → a1"]
+    C -- não --> E["código de criação de TICKET\nestá COMENTADO (L725-781)"]
+    E --> F["else: a1 = Achievement(type=r.type)"]
+    D --> G{"collection != null?\n(POINT/CHALLENGE/CATALOG_ITEM)"}
+    F --> G
+    G -- sim --> H["addAchievement(a1)\n+ triggers + updateUserStatus"]
+    G -- não --> I["LOTTERY_TICKET (50):\ncollection = null →\na1 NUNCA é salvo ❌"]
+```
+
+Detalhamento do descarte de `TYPE_LOTTERY_TICKET (50)`:
+
+1. **L694** — o filtro de entrada aceita `type=50`.
+2. **L703-781** — os ramos que criariam bilhetes (`FUNIFIER_RANDOM` lottery e lottery específica) estão **inteiramente comentados** (`/* ... */`).
+3. **L783-785** — cai no `else`, criando `a1 = new Achievement(..., r.getType()=50, r.getItem(), ...)`.
+4. **L795-805** — `collection` só é resolvida para `TYPE_POINT`/`TYPE_CHALLENGE`/`TYPE_CATALOG_ITEM`. Para `type=50`, `collection` permanece `null`.
+5. **L806** — `if(collection != null)` é **falso** → `a1` **nunca é persistido**, nenhum bilhete é criado, nenhum trigger dispara.
+
+Resultado: configurar `rewards: [{type:50,...}]` numa loteria **não tem efeito algum**.
+
+---
 
-### Executar Sorteio
-**Método:** GET
-**Endpoint:** `/v3/lottery/:id/execute`
-**Descrição:** Executa o sorteio e seleciona os vencedores aleatoriamente.
+## 7. Suportado vs NÃO Suportado
 
-### Reverter Execução do Sorteio
-**Método:** DELETE
-**Endpoint:** `/v3/lottery/:id/execute`
+### ✅ Suportado
 
-### Listar Vencedores
-**Método:** GET
-**Endpoint:** `/v3/lottery/winner?lottery=:id`
+- CRUD de loterias via `/v3/lottery` (GET por id, GET lista filtrada, POST, PUT*, DELETE).
+- CRUD de bilhetes (`/v3/lottery/ticket` POST/GET/DELETE).
+- Execução manual (`GET /{id}/execute`) e rollback (`DELETE /{id}/execute`).
+- Execução automática via scheduler (`autoExecute=true` + `drawDate` vencida).
+- 4 métodos de escolha: `random_ticket`, `random_value`, `first_ticket`, `last_ticket`.
+- Limites `maxWinners` e `maxPerPlayer` (com semântica de §5.1).
+- Elegibilidade por jogador/time (`principals`), inclusive expansão de membros de time.
+- Recompensas de **ponto, desafio e item de catálogo** (incl. catálogo aleatório `FUNIFIER_RANDOM`).
+- Notificações `EVENT_WIN` ao vencedor.
+- Triggers `before_win`, `after_win`, `after_execute`.
+- Listagem de vencedores e painel de participantes.
+- Agrupamento em pastas (`folder`).
+- Multi-tenant por roteamento de connection.
+
+### ❌ NÃO Suportado
+
+- **Recompensa `TYPE_LOTTERY_TICKET (50)`** — aceita na config mas **silenciosamente descartada** na execução (§6). Não cria bilhete nem achievement.
+- **Métodos `more_tickets` / `less_tickets`** — constantes comentadas em `Lottery.java` (L38, L41).
+- **`PUT` real por path id** — `PUT /v3/lottery/{id}` ignora o `{id}` da URL e usa o `_id` do body; sem `_id` no body, cria loteria nova (§4.4).
+- **Merge parcial em update** — todo save é full-replace; campos omitidos são apagados, `createdDate` é resetada.
+- **Validação de campos "obrigatórios"** — `title`, `description`, `image`, `drawDate`, `link` são marcados "(required)" só nos javadocs; o backend não valida.
+- **Recompensas de LEVEL, CROWN, MYSTERY_BOX, etc.** — não entram no filtro de recompensa (L694).
+- **`recompensa.operation` (deduct), `period`, `perPlayer`, lógica de team challenge** — comentados/ignorados na loteria (L671-689).
+- **Parâmetro `q` em `GET /v3/lottery`** — não existe (existe só em `/ticket`).
+- **Limpeza de vencedores no `DELETE`** — achievements `type=5` ficam órfãos (§5.7).
+- **Reexecução automática após rollback** — `undoExecute` zera `autoExecute` (§2.6).
+- **Atomicidade/transação** — execução grava achievements, status e `executedDate` em passos separados, sem rollback em falha parcial.
+- **Campo `random` do bilhete na escolha** — embora indexado e preenchido, não é usado para sortear neste módulo (`$sample` é usado); é vestígio do `brazilian_lottery`.
+
+---
+
+## 8. Segurança e Permissões
+
+- **Autenticação:** v3 exige Bearer token (`AuthBean`); legado `/2.0.0` usa `?api_key=` em query string (menos seguro, evitar).
+- **Autorização:** não há checagem de role/escopo por endpoint. Qualquer token válido do tenant pode criar/executar/deletar loterias. `principals` controla apenas **quem participa**, não quem administra.
+- **Isolamento multi-tenant:** garantido apenas pelo roteamento de connection do Jongo. Não há `apiKey` nos documentos.
+- **Superfície de injeção de pipeline MongoDB:**
+  - `GET /v3/lottery/ticket?q=...` — o `q` é concatenado **literalmente** no `$match` (`LotteryManager.findAllTickets`, L354: `query.append(", " + q)`). Um `q` malicioso pode injetar operadores/estágios adicionais. Como em outros módulos, o isolamento por connection limita o impacto ao tenant, mas permite leitura arbitrária dentro da coleção.
+  - `GET /v3/lottery/winner?q=...` — repassado ao `AchievementManager.findAllAchievements` (mesma característica de query raw do módulo achievement).
+- **DoS leve não intencional:** loteria `autoExecute` sem bilhetes (§5.5) é reprocessada a cada 5 min — não é injeção, mas é um custo recorrente silencioso.
+- **Falhas convertidas em 500:** ids inexistentes em `execute` (L612) e loteria inexistente/`null` em `checkRestrictions` (L259-264) causam NPE → 500. Não vazam dados, mas dificultam diagnóstico no cliente.
+
+---
+
+## 9. Observabilidade e Troubleshooting
+
+### Diagnóstico rápido
+
+```
+GET /v3/lottery/{id}                      → confirma existência e executedDate
+GET /v3/lottery/{id}/... (participants)   → total de bilhetes e vencedores
+GET /v3/lottery/ticket?lottery={id}&max_results=1000  → bilhetes registrados
+GET /v3/lottery/winner?lottery={id}       → vencedores (achievements type=5)
+```
+
+### Queries MongoDB úteis
+
+```js
+// A loteria foi executada?
+db.lottery.findOne({ _id: "DTj0x5z" }, { executedDate: 1, autoExecute: 1, drawDate: 1 })
+
+// Loterias que o scheduler vai (tentar) executar
+db.lottery.find({ executedDate: { $exists: false }, drawDate: { $lte: new Date() }, autoExecute: true })
+
+// Quantos bilhetes por jogador
+db.lottery_ticket.aggregate([
+  { $match: { lottery: "DTj0x5z" } },
+  { $group: { _id: "$player", tickets: { $sum: 1 } } }
+])
+
+// Vencedores (não há coleção "winner" — é achievement type=5)
+db.achievement.find({ type: 5, item: "DTj0x5z" })
+
+// Bilhetes já marcados como usados (indício de execução)
+db.lottery_ticket.count({ lottery: "DTj0x5z", used: true })
+```
+
+### Erros comuns e causas
+
+| Sintoma | Causa provável |
+|---|---|
+| `POST /ticket` retorna 500 (NPE) | `lottery` inexistente ou ausente no body → bug L259-264 (§4.6). Verifique se a loteria existe |
+| `POST /ticket` retorna 400 `was_executed` | Loteria já sorteada (`executedDate != null`). Use `undoExecute` para reabrir |
+| `POST /ticket` retorna 400 `principal_not_allowed` | Jogador não está em `principals` (nem em time elegível) |
+| Bilhete "criado" mas não aparece | `lottery`/`player` ausentes → `insertTicket` faz no-op silencioso (L299) |
+| Sorteio "não acontece" automaticamente | `autoExecute=false`, ou `drawDate` no futuro, ou já tem `executedDate` |
+| Sorteio reexecuta sozinho repetidamente | Sem bilhetes → `executedDate` nunca grava (§5.5) |
+| Sorteio `random_value` não premia ninguém apesar de haver bilhetes | O bilhete sorteado tinha `value` null (§5.9). Garanta `value` em todos os bilhetes desse método |
+| Recompensa de bilhete não é creditada | `type=50` é descartado (§6). Use o módulo challenge para distribuir bilhetes |
+| Update via `PUT` "não salva" / cria duplicata | `PUT` ignora o id da URL (§4.4). Envie `_id` no body |
+| `createdDate` mudou após editar | Full-replace re-setou `createdDate` (§3.1) |
+| Após rollback, scheduler não reexecuta | `undoExecute` setou `autoExecute=false` (§2.6) |
+| Saldo do jogador conta loteria deletada | `DELETE /{id}` não remove achievements type=5 (§5.7) |
+
+---
+
+## 10. Exemplos Práticos
+
+### 10.1 Exemplo mínimo (sorteio simples por bilhete aleatório)
+
+```json
+POST /v3/lottery
+Authorization: Bearer <token>
+Content-Type: application/json
+{
+  "title": "Sorteio Relâmpago",
+  "drawDate": 1690824650503,
+  "autoExecute": true,
+  "choiceMethod": "random_ticket",
+  "maxWinners": 1
+}
+```
+
+Defaults aplicados: `_id` gerado, `createdDate`=agora, `folder`="default", `maxPerPlayer`=-1.
+
+### 10.2 Exemplo avançado (prêmios, elegibilidade, notificação)
+
+```json
+POST /v3/lottery
+{
+  "title": "Travel to Cancun",
+  "description": "Viagem para Cancún com acompanhante.",
+  "image": "https://cdn.exemplo.com/cancun.png",
+  "tags": ["viagem", "premium"],
+  "drawDate": 1690824650503,
+  "autoExecute": true,
+  "choiceMethod": "random_ticket",
+  "maxWinners": 1,
+  "maxPerPlayer": 1,
+  "principals": ["team_vendas"],
+  "rewards": [
+    { "total": 1, "type": 2, "item": "flight_ticket" },
+    { "total": 500, "type": 0, "item": "points" }
+  ],
+  "notifications": [
+    { "event": 0, "type": 0, "scope": 0, "content": "Parabéns, você ganhou a viagem!" }
+  ]
+}
+```
+
+```json
+POST /v3/lottery/ticket
+{ "lottery": "<id_retornado>", "player": "me" }
+```
+
+```
+GET /v3/lottery/<id>/execute     # sorteia 1 vencedor entre membros de team_vendas
+```
+
+### 10.3 Anti-pattern (o que NÃO fazer)
+
+```json
+// ❌ Recompensa de bilhete de loteria — silenciosamente ignorada (§6)
+{
+  "title": "Acumule bilhetes",
+  "rewards": [ { "total": 5, "type": 50, "item": "outra_loteria" } ]
+}
+// type=50 não cria bilhetes nem achievements. Para distribuir bilhetes,
+// use rewards de TYPE_LOTTERY_TICKET em um CHALLENGE, não em uma loteria.
+```
+
+```
+// ❌ "Atualizar" a loteria sem reenviar o _id
+PUT /v3/lottery/DTj0x5z
+{ "title": "Novo título" }
+// Cria uma loteria NOVA (id gerado), não atualiza a DTj0x5z (§4.4).
+// Correto: incluir "_id": "DTj0x5z" no body e reenviar TODOS os campos.
+```
+
+```
+// ❌ Esperar que DELETE limpe vencedores
+DELETE /v3/lottery/DTj0x5z
+// Os achievements type=5 dos vencedores permanecem. Para reverter prêmios,
+// rode DELETE /v3/lottery/DTj0x5z/execute (undoExecute) ANTES de deletar.
+```
 
-### Listar Participantes
-**Método:** GET
-**Endpoint:** `/v3/lottery/participants?lottery=:id`
+---
 
-## Validações e Testes
+## Checklist de Configuração
 
-- [ ] Sorteio aparece na lista GET /v3/lottery
-- [ ] Cupom é criado corretamente para jogador
-- [ ] Ao executar sorteio, vencedor é selecionado
-- [ ] Lista de vencedores retorna dados corretos
-- [ ] Reverter execução funciona
+- [ ] `title`/`description`/`image` preenchidos (o backend **não** valida, mas o Studio espera).
+- [ ] `drawDate` definida (necessária para execução automática).
+- [ ] `choiceMethod` escolhido entre `random_ticket` | `random_value` | `first_ticket` | `last_ticket` (default `random_ticket`).
+- [ ] `maxWinners`/`maxPerPlayer` ajustados (lembre: `-1`=ilimitado, `0`→1).
+- [ ] `autoExecute=true` **somente** se quiser execução pelo scheduler (e garanta que haverá bilhetes — §5.5).
+- [ ] `rewards` usam apenas `type` 0/1/2 (ponto/desafio/catálogo). **`type=50` não funciona** (§6).
+- [ ] Bilhetes existem **antes** do `drawDate` (sorteio sem bilhetes não fecha).
+- [ ] `principals` definido se a loteria for restrita a jogadores/times específicos.
+- [ ] Para distribuir **bilhetes como recompensa**, configure no módulo `challenge`, não em `lottery.rewards`.
+- [ ] Antes de `DELETE` de loteria executada, rode `undoExecute` para não deixar achievements órfãos.
+- [ ] Em update, reenvie o `_id` no body e todos os campos (full-replace + PUT ignora id da URL).