funifier-mcp 0.2.26 → 0.2.27

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

@@ -1,82 +1,692 @@
-# Mystery (Mistério / Caixa Surpresa)
+# `mystery`
 
 **Acesso Studio:** `/studio/mystery`
 **API Endpoint:** `/v3/mystery`
+**Coleções MongoDB:** `mystery_box`, `mystery_box_log`, `mystery_folder` (as vitórias e recompensas ficam em `achievement` com `type=6`)
 
-## O que é
+> Documentação de engenharia reversa, produzida a partir do código-fonte real do `funifier-service` (commit `830037e`). Os exemplos da API antiga (`MysteryBoxRest.java`) contêm campos que o runtime **ignora silenciosamente** — este documento prioriza o comportamento do código sobre o que os exemplos sugerem.
 
-Jogos de probabilidade e recompensas aleatórias. Permite criar experiências como caixas surpresa, rodas da fortuna, raspadinhas e outros jogos baseados em sorte, definindo as chances e prêmios disponíveis.
+---
 
-## Quando usar
+## 1. Visão Geral
 
-- Para criar rodas da fortuna
-- Para raspadinhas premiadas
-- Para jogos de cara ou coroa
-- Para recompensas aleatórias com probabilidades definidas
+O módulo `mystery` (Mystery Box / "caça-níquel"/slot machine/raspadinha) implementa **recompensa aleatória por probabilidade**. O jogador "gira a roleta" (executa a mystery box) e o sistema sorteia, para cada coluna, uma das opções configuradas respeitando a probabilidade de cada uma. O conjunto de opções sorteadas é comparado contra a `win_chart` (tabela de combinações vencedoras); se houver casamento, o jogador recebe a recompensa associada.
 
-## Checklist de Configuração no Studio
+Papel arquitetural:
 
-- [ ] Definir título da mystery box
-- [ ] Definir opções com probabilidades (devem somar 1.0)
-- [ ] Definir número de colunas para exibição
-- [ ] Configurar combinações vencedoras (win_chart)
-- [ ] Definir recompensas para cada combinação
-- [ ] Configurar requisitos para jogar (requirements)
+- A configuração é um documento na coleção `mystery_box` (`MysteryBox.java`). **Não existe Service nem Repository/Dao dedicados** — toda persistência é feita diretamente via `Jongo` dentro de `MysteryBoxManager` (`MysteryBoxManager.java`, L31-754).
+- **Não há coleção própria de "resultados"**: a jogada vencedora e cada recompensa viram documentos na coleção `achievement`, reutilizando o `AchievementManager` (totais, level-up, `player_status`, triggers, webhooks). Por isso o módulo depende fortemente de [achievement](achievement.md).
+- Toda execução é registrada na coleção `mystery_box_log` (auditoria de tentativas / "attempts").
+- A execução é **sempre síncrona e manual** (chamada de endpoint). Não há scheduler/job automático para mystery — diferente de [lottery](lottery.md).
 
-## API Endpoints
+Relação com outros módulos:
 
-### Listar Mystery Boxes
-**Método:** GET
-**Endpoint:** `/v3/mystery`
+- [achievement](achievement.md) — a jogada vira `Achievement type=6` (somente em vitória); cada recompensa vira um achievement adicional (ponto/desafio/item).
+- [trigger](../guides/triggers.md) — dispara `before_win`/`after_win`/`before_lose`/`after_lose` (entidade `mystery_box`), além do evento literal `before_win_reward` e dos eventos `before_win`/`after_win` na coleção da recompensa.
+- [challenge](challenge.md) (`Requirement`) — define tanto o **custo de jogar** (`requirements`) quanto a **recompensa** de cada combinação (`win_chart[].reward`).
+- `point_category`, `catalog_item` (virtual good) — tipos de recompensa suportados (além de `challenge`).
+- [folder](folder.md) — agrupamento via coleção `mystery_folder`.
+- `ai` — `POST /v3/ai/build/mystery` (`AIRest.buildMystery`, L2088) **gera** um JSON de mystery box via OpenAI a partir de linguagem natural, mas **não persiste** — apenas devolve o objeto desserializado.
 
-### Criar Mystery Box
-**Método:** POST
-**Endpoint:** `/v3/mystery`
+---
+
+## 2. Arquitetura e Fluxos
+
+### 2.1 Classes envolvidas
+
+| Classe | Papel |
+|---|---|
+| `com.funifier.engine.mystery.MysteryBox` | Entidade/POJO raiz — documento em `mystery_box` (`MysteryBox.java`, L24-89) |
+| `com.funifier.engine.mystery.MysteryOption` | Uma opção sorteável (valor + probabilidade) (`MysteryOption.java`) |
+| `com.funifier.engine.mystery.MysteryWin` | Linha da `win_chart` (combinação vencedora + recompensa + limites) (`MysteryWin.java`) |
+| `com.funifier.engine.mystery.MysteryResult` | DTO de saída do `execute` — **não persistido** (`MysteryResult.java`) |
+| `com.funifier.engine.mystery.MysteryBoxLog` | Log de tentativa — documento em `mystery_box_log` (`MysteryBoxLog.java`) |
+| `com.funifier.engine.mystery.MysteryFolder` | Pasta de agrupamento — documento em `mystery_folder` |
+| `com.funifier.engine.mystery.MysteryBoxFolder` | **Classe morta** — duplicata de `MysteryFolder`, sem nenhuma referência no código (ver §7) |
+| `com.funifier.engine.mystery.ProbabilityUtil` | Sorteio ponderado por probabilidade (`getChoice`) (`ProbabilityUtil.java`) |
+| `com.funifier.engine.mystery.MysteryBoxManager` | Manager monolítico: CRUD, execução, limites, rollback, evaluate (`MysteryBoxManager.java`, L31-754) |
+| `com.funifier.rest.v3.rest.MysteryBoxRest` | Controller REST v3 (`/v3/mystery`) (`MysteryBoxRest.java`, L44-572) |
+
+### 2.2 Pipeline de criação — `insert(MysteryBox)` (L39-70)
+
+`POST /v3/mystery` → `MysteryBoxManager.insert`. Comportamento de **upsert** (Jongo `c.save` grava por `_id`; reenviar o mesmo `_id` **substitui o documento inteiro**).
+
+```
+[1] Se _id ausente/vazio → gera Guid.newShortGuid()                     (L42-44)
+[2] Se active == null → active = true                                   (L46-48)
+[3] prepareOptions(mystery)  — recalcula probabilidades das opções      (L51 → L117-146)
+[4] prepareWinchart(mystery) — atribui _id "o1","o2",... às combinações (L54 → L85-111)
+[5] Se folder vazio → folder = "default"                                (L57-59)
+[6] Garante que o documento da pasta exista em mystery_folder;
+    se não existir, cria MysteryFolder {id=folder, title=folder}        (L60-67)
+[7] c.save(mystery) na coleção mystery_box                              (L69)
+```
+
+> **Não existe `PUT`.** Atualização = re-`POST` com o mesmo `_id`. Como é `save` (full replace), **omitir um campo o apaga** — não é patch parcial.
+
+#### `prepareOptions` — recálculo de probabilidades (L117-146)
+
+Apesar do comentário do método citar `type == option_probability`, ele é executado **sempre**, independentemente de qualquer `type` (que aliás é ignorado — ver §3/§7).
+
+```
+para cada opção o:
+    se o.probability == null OU == 0   → vai para zeroOptions
+    senão se 0 < o.probability <= 1    → vai para goodOptions; goodTotal += o.probability
+    senão (prob > 1 OU prob < 0)       → DESCARTADA silenciosamente   (!)
+
+diffTotal = 1 - goodTotal
+division  = diffTotal / zeroOptions.size()
+para cada opção em zeroOptions:
+    o.probability = division           (divide o "resto" igualmente entre as opções sem prob.)
+
+mystery.options = goodOptions ++ (zeroOptions já ajustadas)   → ORDEM É ALTERADA (!)
+```
+
+Regras emergentes (não documentadas no schema):
+
+- Opções com `probability > 1` ou `< 0` são **removidas silenciosamente** do documento salvo.
+- Opções sem probabilidade (`null`/`0`) recebem partes iguais do "resto" (`1 - soma das demais`).
+- Se a soma das probabilidades informadas for `< 1` **e não houver** opção de probabilidade zero, o "resto" vira a chance de **NONE** (sorteio devolve `null` — ver §2.4).
+- **Foot-gun:** se `goodTotal > 1`, `diffTotal` fica **negativo** e as opções "zero" recebem probabilidade **negativa**, corrompendo `ProbabilityUtil.getChoice()` (ver §5).
+- A lista é **reordenada** (boas primeiro, depois as ex-zero) — qualquer UI/Groovy que dependa da ordem de entrada verá a ordem mudar após o primeiro save.
+
+### 2.3 Pipeline principal — `execute(id, player[, extra])` (L173-419)
+
+Método **`synchronized`** (lock de **instância** do `MysteryBoxManager`, que é por API key / `ManagerFactory`). Serializa execuções concorrentes **dentro da mesma JVM**; **não é lock distribuído** — múltiplos pods podem competir. Síncrono, **sem transação MongoDB** (cada `save`/`addAchievement` é independente).
+
+A validação de `active`, `limit` e `attempts` acontece **na camada REST** (`MysteryBoxRest.execute`, L244-317) **antes** de chamar o manager. O manager re-busca o documento e executa:
+
+```
+[1] Re-carrega MysteryBox por id; carrega Player                        (L178-181)
+    Se mystery == null OU player == null → não faz nada, retorna result vazio (L184)
+[2] Cria a1 = Achievement(novoGuid, player, total=1, TYPE_MYSTERY_BOX=6, item=id, now)  (L187)
+[3] SALVA MysteryBoxLog(a1.id, item=id, player, time, extra) em mystery_box_log  (L191-192) (!) SEMPRE
+[4] Se há requirements: evaluateRequirements; se OK → deductRequirements,
+    senão → throw "insufficient requirements" (HTTP 400)                (L195-202)
+    (!) O log do passo [3] já foi gravado mesmo se falhar aqui.
+[5] columns = (mystery.columns > 0) ? mystery.columns : 1               (L206)
+[6] [Apenas se columns == 1] Exclusão de opções com recompensa esgotada (L213-283) — ver §2.5
+[7] Monta ProbabilityUtil (opções viáveis OU originais) e sorteia
+    `columns` valores → lista `win` (pode conter null = NONE)           (L286-298)
+[8] result = {mystery:id, player, time, result:win}                     (L301-304)
+[9] SE win_chart não-vazia (L307):
+      status = containsWinCombination(win) ? WIN : LOSE                 (L313-317)
+      SE WIN  → result.achievements.add(a1);
+                trigger before_win (mystery_box);
+                addAchievement(a1)   <- a1 só persiste em VITÓRIA (!)    (L320-331)
+      SE LOSE → trigger before_lose (mystery_box)                       (L333-337)
+      Para cada win_chart[i] que casa com `win` (L340-397):
+          checkRewardIsInLimit && checkInventoryIsInLimit              (L345-348)
+          se reward != null E disponível → cria a2, dispara triggers,
+             addAchievement(a2)  (só p/ reward type 0/1/2)             (L351-390)
+          senão → System.out.println("MysteryWin not registered because of limit")  (L393)
+      SE WIN  → trigger after_win (mystery_box)                         (L400-403)
+      SE LOSE → trigger after_lose (mystery_box)                       (L407-409)
+[10] updatePlayerStatus(player) — SEMPRE que mystery!=null && player!=null (L414)
+```
+
+> **Distinção crítica entre `limit` e `attempts`:** o achievement `a1` (`type=6`) só é gravado em **vitória** (passo [9], L330). Logo:
+> - **`limit`** conta documentos `achievement type=6` → é um limite de **VITÓRIAS**.
+> - **`attempts`** conta documentos `mystery_box_log` → é um limite de **TENTATIVAS/jogadas** (gravado sempre, passo [3]).
+>
+> Uma derrota **não** incrementa `limit`, mas **incrementa** `attempts`.
+
+> **Sem `win_chart`:** se a box não tiver `win_chart` (vazia/nula), nenhum `status` é definido, **nenhum** achievement `a1` é gravado e **nenhum** trigger dispara. O `result` sai com `result[]` preenchido e `status` ausente.
+
+### Fluxo de execução — `execute(id, player)`
+
+```mermaid
+flowchart TB
+    A["REST: validacoes<br/>(existe? active? limit? attempts?)"] --> B["Manager.execute<br/>(synchronized)"]
+    B --> C{"mystery != null<br/>&& player != null?"}
+    C -- nao --> Zr["retorna result vazio"]
+    C -- sim --> D["cria a1 (Achievement type=6)"]
+    D --> E["salva MysteryBoxLog (SEMPRE)"]
+    E --> F{requirements OK?}
+    F -- nao --> Z["throw 400<br/>(log ja persistido)"]
+    F -- sim --> G["deductRequirements"]
+    G --> H{columns == 1?}
+    H -- sim --> I["exclui opcoes c/ recompensa<br/>esgotada e renormaliza"]
+    H -- nao --> J["usa opcoes originais"]
+    I --> K["sorteia colunas<br/>(ProbabilityUtil)"]
+    J --> K
+    K --> L{win_chart vazia?}
+    L -- sim --> P["sem status, sem trigger"]
+    L -- nao --> M{containsWinCombination?}
+    M -- sim --> N["status=WIN<br/>before_win + addAchievement(a1)"]
+    M -- nao --> O["status=LOSE<br/>before_lose"]
+    N --> Q["loop win_chart: rewards (sec.6)"]
+    O --> Q
+    Q --> R{WIN?}
+    R -- sim --> S["after_win (mystery_box)"]
+    R -- nao --> T["after_lose (mystery_box)"]
+    P --> U["updatePlayerStatus (SEMPRE)"]
+    S --> U
+    T --> U
+```
+
+### Interação entre módulos — vitória com recompensa
+
+```mermaid
+sequenceDiagram
+    participant C as Cliente
+    participant R as MysteryBoxRest
+    participant M as MysteryBoxManager
+    participant Tr as TriggerManager
+    participant A as AchievementManager
+    participant DB as MongoDB
+
+    C->>R: GET /v3/mystery/execute/{id}?player=X
+    R->>R: valida active / limit (wins) / attempts (logs)
+    R->>M: execute(id, player)
+    M->>DB: save mystery_box_log (tentativa)
+    M->>A: evaluate+deduct requirements
+    M->>M: sorteia colunas (ProbabilityUtil)
+    M->>Tr: before_win (mystery_box)
+    M->>A: addAchievement(a1 type=6)  [so em WIN]
+    loop cada win_chart que casa
+        M->>M: checkRewardIsInLimit + checkInventoryIsInLimit
+        M->>Tr: before_win_reward (mystery_box)
+        M->>Tr: before_win (colecao da recompensa)
+        M->>A: addAchievement(a2)
+        M->>Tr: after_win (colecao da recompensa)
+    end
+    M->>Tr: after_win (mystery_box)
+    M->>A: updatePlayerStatus(player)
+    M-->>R: MysteryResult
+    R-->>C: 200 {result, status, achievements}
+```
+
+### 2.4 Sorteio — `ProbabilityUtil.getChoice()` (L95-104)
+
+```
+rand = Math.random()                  // [0,1)
+para cada item (probs):
+    se rand < prob(item) → retorna item
+    rand -= prob(item)
+retorna null                          // "resto" não coberto = NONE
+```
+
+- A iteração segue a ordem do `HashMap` (não determinística entre opções) — não é estável, mas é estatisticamente correta.
+- Se a soma das probabilidades for `< 1`, sobra uma faixa para a qual `getChoice` devolve **`null`** → o valor `null` entra em `result.result[]` e representa "não ganhou nada" naquela coluna.
+
+### 2.5 Exclusão de opções esgotadas (apenas `columns == 1`) (L213-283)
+
+Melhoria solicitada pela CH Media. Quando `columns == 1`, antes do sorteio o sistema verifica, para cada combinação vencedora de **1 elemento**, se a recompensa atingiu `limit`/`inventory`. As opções cuja recompensa está esgotada são **removidas do pool** e a probabilidade delas é **redistribuída proporcionalmente** entre as opções viáveis (algoritmo "v2", L274-279):
+
+```
+para cada opção viável o:
+    novaProb(o) = o.probability + (o.probability / somaViáveis) * somaIgnoradas
+```
+
+A substituição só ocorre se `0 < #ignoradas < #opções` (se todas estiverem esgotadas, mantém as opções originais). **Para `columns > 1` esta proteção não existe** — pode-se sortear uma combinação cuja recompensa já está esgotada (a recompensa simplesmente não é creditada no passo de win_chart).
+
+---
+
+## 3. Estrutura dos Objetos
+
+### 3.1 `MysteryBox` — documento raiz (coleção `mystery_box`)
+
+| Campo | Tipo | Padrão | Obrigatório | Descrição |
+|---|---|---|---|---|
+| `_id` | String | `Guid.newShortGuid()` | — | Gerado se ausente/vazio (L42-44). Reenviar o mesmo `_id` substitui o documento. |
+| `title` | String | — | sim (de fato) | Título exibido. Não há validação de obrigatoriedade no backend, mas é esperado pela UI. |
+| `image` | `Image` (objeto) | `null` | não | Imagem de capa. |
+| `options` | `MysteryOption[]` | `[]` | sim | Opções sorteáveis. Reescritas por `prepareOptions` no save (ver §2.2). |
+| `columns` | int | `1` | não | Quantos valores são sorteados por jogada (os "carretéis" do slot). `<= 0` é tratado como `1` na execução (L206). |
+| `requirements` | `Requirement[]` | `[]` | não | **Custo** para jogar (ex.: 1 moeda). Verificados e debitados no `execute` (L195-202). |
+| `win_chart` | `MysteryWin[]` | `[]` | não | Combinações vencedoras e recompensas. Sem `win_chart`, nunca há vitória nem trigger (ver §2.3). |
+| `limit` | `Limit` | `null` | não | Limite de **vitórias** (conta `achievement type=6`). |
+| `attempts` | `Limit` | `null` | não | Limite de **tentativas** (conta `mystery_box_log`). |
+| `folder` | String | `"default"` | não | Pasta de agrupamento. Cria o doc em `mystery_folder` se não existir (L60-67). |
+| `active` | Boolean | `true` (no insert) | não | **Só `false` explícito bloqueia** o execute: `!(active==null \|\| active==true)` (L244). `null`/ausente = ativo. |
+| `extra` | Map | `{}` | não | Metadado livre. **Persistido mas nunca lido** pela lógica do módulo mystery — passthrough puro (ver §7). |
+| `techniques` | String[] | `null` | não | **Legado/inativo.** Nunca escrito nem lido pelo módulo (ver §3.7 e §7). |
+
+#### Campos aceitos no JSON mas **silenciosamente ignorados**
+
+`MysteryBox` é anotado com `@JsonIgnoreProperties(ignoreUnknown=true)`. Logo, qualquer campo não mapeado é descartado **sem erro**. Em particular:
+
+- **`type`** (`"option_probability"` / `"combination_probability"`) — aparece nos exemplos antigos da API (L117, L149) mas **não existe** na entidade. É descartado. O comportamento de recálculo de probabilidades é o mesmo para qualquer "type".
+
+#### Métodos de domínio em `MysteryBox`
+
+- `containsWinCombination(result)` (L67-76) — `true` se **alguma** linha de `win_chart` casa com o resultado.
+- `getOption(value)` (L78-88) — localiza a `MysteryOption` pelo `value`.
+
+### 3.2 `MysteryOption` — uma opção sorteável
+
+| Campo | Tipo | Padrão | Obrigatório | Descrição |
+|---|---|---|---|---|
+| `value` | String | — | sim | Identificador da opção (usado nas combinações da `win_chart`). |
+| `probability` | Double | `null` | não | Entre 0 e 1. `null`/`0` → calculada como parte igual do "resto"; `>1` ou `<0` → opção **descartada** (§2.2). |
+| `title` | String | `null` | não | Rótulo exibível. |
+| `image` | String | `null` | não | URL da imagem da opção. |
+
+### 3.3 `MysteryWin` — linha da `win_chart`
+
+| Campo | Tipo | Padrão | Obrigatório | Descrição |
+|---|---|---|---|---|
+| `_id` | String | `"o1"`,`"o2"`,… | — | Atribuído por `prepareWinchart` se ausente (L96-108). Usado no escopo de `limit`/`inventory` isolados. |
+| `combination` | String[] | — | sim | Lista de `value`s que formam a combinação vencedora. |
+| `orderSensitive` | boolean | `false` | não | `true` = igualdade exata (ordem importa); `false` = **contagem por tipo** (multiset/subconjunto) — ver §5. |
+| `reward` | `Requirement` | `null` | não | Recompensa. **Usa apenas `total`, `type`, `item`** (o `operation` é ignorado — comentário L21). |
+| `limit` | `Limit` | `null` | não | Limite de quantas vezes a recompensa pode ser obtida. **Só `player` e `gamification`** (ver §5/§7). |
+| `inventory` | Double | `null` | não | Estoque global da recompensa (cap absoluto de unidades distribuídas). |
+| `isolated` | boolean | `false` | não | Se `true`, `limit`/`inventory` contam apenas conquistas **desta** mystery box (e, com `_id`, desta combinação). |
+
+#### Campo aceito mas ignorado
+
+- **`probability`** em cada item de `win_chart` — aparece nos exemplos antigos (L175, L179…) mas **não existe** em `MysteryWin`. É descartado. A chance de uma combinação vencedora **deriva exclusivamente** das probabilidades em `options` × `columns`, **não** de uma probabilidade por combinação.
+
+#### `isWinCombination(result)` (L36-78)
+
+```
+se orderSensitive:
+    retorna  String(combination) == String(result)        // igualdade EXATA e ordenada
+senão:
+    // conta ocorrências por tipo em result e em combination
+    para cada tipo da combination:
+        se result não tem aquele tipo OU tem MENOS que o exigido → perdeu
+    retorna ganhou
+```
+
+(!) Com `orderSensitive=false` é **contenção de multiconjunto**, não igualdade: `result=[a,a,b]` **satisfaz** `combination=[a,a]`. Com várias colunas, **uma única jogada pode casar várias linhas** da `win_chart` e creditar **múltiplas recompensas** (o loop L340-397 percorre todas).
+
+### 3.4 `MysteryResult` — saída do `execute` (não persistido)
+
+| Campo | Tipo | Descrição |
+|---|---|---|
+| `mystery` | String | id da box. |
+| `player` | String | id do jogador. |
+| `time` | String | timestamp ISO (zoned). |
+| `result` | String[] | valores sorteados (1 por coluna). **Pode conter `null`** = NONE. |
+| `status` | String | `"WIN"` / `"LOSE"`. **Ausente** se `win_chart` vazia. |
+| `achievements` | `Achievement[]` | a jogada (`a1`, só em WIN) + recompensas creditadas (`a2`). |
+
+Constantes: `STATUS_WIN = "WIN"`, `STATUS_LOSE = "LOSE"`.
+
+### 3.5 `MysteryBoxLog` — log de tentativa (coleção `mystery_box_log`)
+
+| Campo | Tipo | Descrição |
+|---|---|---|
+| `_id` | String | = id do achievement `a1` da jogada. |
+| `item` | String | = id da mystery box. |
+| `player` | String | jogador. |
+| `time` | Date | momento da tentativa. |
+| `extra` | Map | metadado enviado no `execute` (POST). |
+
+### 3.6 `MysteryFolder` — pasta (coleção `mystery_folder`)
+
+| Campo | Tipo | Descrição |
+|---|---|---|
+| `_id` | String | id da pasta (= valor de `MysteryBox.folder`). |
+| `title` | String | título; no auto-create recebe o mesmo valor do id (L64-65). |
+
+### 3.7 Técnicas de jogo (`techniques`)
+
+O campo `techniques` existe em `MysteryBox` mas, **diferente de point/challenge/level/leaderboard/lastmile/virtual_good/lottery/question/competition**, o `mystery_box` **não** está na rotina de atribuição de código GT do `GameTechniqueManager` (L63-181). **Não existe constante de GT code para mystery box** na lista (L67-75). O `GameTechniqueManager` apenas lê as boxes para montar o **grafo de relacionamentos** (nós = boxes, links = box → item de recompensa, L295-297 e L636-647) — nunca grava `techniques`. Portanto: **não há código GT operacional para mystery; o campo é legado.**
+
+---
+
+## 4. Endpoints
+
+Todos sob `@Path("v3/mystery")`, `Produces: application/json; charset=UTF-8`. Autenticação via Bearer token (`AuthBean`).
+
+### `GET /v3/mystery/{id}` — buscar uma box
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Retorna a configuração da box (`find`, L59). |
+| Autenticação | Bearer token |
+| (!) id inexistente | Retorna **`200 OK` com corpo `null`** — **não** 404 (não há null-check). |
+
+### `GET /v3/mystery` — listar todas
+
+Retorna todas as boxes (`findAll`, L76). Coleção vazia → `200` com `[]`. Sem paginação na API (o header `Range: items=0-1000` é aplicado globalmente no nível de infra).
+
+### `POST /v3/mystery` — criar/atualizar (upsert)
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | `insert` (L208-213). |
+| Full replace ou patch | **Full replace** (Jongo `save` por `_id`). Omitir campo o apaga. |
+| Status | `201 Created`, devolve a box já com `_id`/`options` recalculados. |
+| Efeitos colaterais | Recalcula `options`, atribui `_id` às combinações, cria pasta se ausente. |
+
+### `DELETE /v3/mystery/{id}` — remover box
+
+`delete` (L94). Remove o documento de `mystery_box` (`remove {_id:#}`, L82). **Não** remove logs nem achievements relacionados. Status `200`.
+
+### `GET /v3/mystery/execute/{id}?player={player}` — jogar (GET)
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Executa a box e retorna `MysteryResult` (L229-321). |
+| `player=me` | Resolve o jogador a partir do token (L234-235). |
+| Validações (REST, antes do manager) | box existe (400 se não), `active` (400 se `false`), `limit` de vitórias (400 se excedido), `attempts` (400 se excedido). |
+
+### `POST /v3/mystery/execute` — jogar (POST, com `extra`)
+
+Body: `{ "_id": "...", "player": "...", "extra": { ... } }` (L324-421). Permite anexar `extra` (gravado no log). `player=me` → token.
+
+### `POST /v3/mystery/execute_by_player/{player}` — jogar por jogador na URL
+
+Body: `{ "_id": "...", "extra": { ... } }` (L424-521). O jogador vem do path param (não do body). Mesmas validações.
+
+### `DELETE /v3/mystery/execute` — rollback de jogada
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Desfaz uma jogada (`undoExecute`, L525-540 → L158-171). |
+| Body | `{ "_id": "<achievementId da jogada>" }`. |
+| Comportamento | Só age se o achievement for `type=6`. Remove os achievements de recompensa (`extra.origin == id`) **e** o achievement da jogada. |
+| (!) Não faz | **Não** estorna `requirements` debitados; **não** remove o `mystery_box_log`. |
+| Resposta | `200 {"message":"Execution Rollback Done"}` |
+
+### `GET /v3/mystery/evaluate/{id}?player={player}&time={time}` — diagnóstico
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Avalia elegibilidade sem jogar (`evaluate` → `evaluateAnalyze`, L543-571 / L524-563). |
+| `time` | Aceita epoch ms, data ISO/zoned, keyword (ex. `-1d`) ou vazio (→ agora) (L556-560). |
+| Retorno | `{ params, exists, limit_wins, limit_attempts, limit, attempts, requirements, active, milliseconds }`. |
+| (!) Bug | A chave `active` é **sempre `{}`** e o status de `active` é gravado por engano em `exists.status` (L556-558). Box inativa faz `exists.status="UNAUTHORIZED"` mesmo existindo (ver §7/§9). |
+
+#### Exemplo de execução (request/response)
+
+```
+GET /v3/mystery/execute/heads_or_tails?player=ricardo@acme.com
+Authorization: Bearer eyJhbGciOiJIUzUxMiIs...
+```
+
+```json
+{
+  "mystery": "heads_or_tails",
+  "player": "ricardo@acme.com",
+  "time": "2026-05-20T13:40:11-03:00",
+  "result": ["heads"],
+  "status": "WIN",
+  "achievements": [
+    { "_id": "aZ8...", "player": "ricardo@acme.com", "total": 1, "type": 6, "item": "heads_or_tails", "time": "..." },
+    { "_id": "bY9...", "player": "ricardo@acme.com", "total": 10, "type": 0, "item": "coin", "time": "...",
+      "extra": { "origin": "aZ8...", "origin_item": "heads_or_tails", "origin_type": 6, "mystery_win_id": "o1" } }
+  ]
+}
+```
+
+---
+
+## 5. Regras de Negócio
+
+Regras que **existem no código** e não no schema:
+
+1. **`limit` = vitórias, `attempts` = tentativas.** `limit` conta `achievement type=6` (gravado só em WIN); `attempts` conta `mystery_box_log` (gravado em toda jogada). Ver §2.3.
+2. **`limit.total` pode ser fórmula.** Aceita número **ou** string Mustache+exp4j avaliada por jogador, ex.: `"{{player.extra.max_plays}} * 2"` (L255-264). Erro de avaliação → 400 ("It was impossible to identify the limit…").
+3. **Tentativa falha por requisito ainda gera log.** O `mystery_box_log` é gravado antes da verificação de `requirements` (L191-192 vs L195-202). Insuficiência lança 400 **depois** do log → conta como attempt.
+4. **`limit`/`reward.limit` com `per:"team"` não é aplicado.** `checkRewardIsInLimit` só trata `PER_PLAYER` e `PER_GAME` (L483-511); com `team`, nenhum branch roda, `count=0` e o limite **nunca** bloqueia (silenciosamente permissivo).
+5. **Só recompensas `type` 0/1/2 são creditadas.** Em vitória, o `a2` só persiste se `type` for `point(0)` → `point_category`, `challenge(1)` → `challenge`, `catalog_item(2)` → `catalog_item` (L366-390). Outros tipos: `a2` é criado em memória mas `collection==null` pula triggers e `addAchievement` — recompensa **silenciosamente não registrada**.
+6. **Combinação multiset.** `orderSensitive=false` casa por contagem de tipos (subconjunto), não por igualdade — uma jogada pode disparar **múltiplas** linhas vencedoras (§3.3).
+7. **NONE é implícito.** Se as probabilidades não somam 1 (e não há opção zero para absorver), há chance de `result` conter `null` (sem prêmio) — §2.4.
+8. **Foot-gun de probabilidade > 1.** Se a soma das probabilidades informadas exceder 1, `prepareOptions` gera probabilidade **negativa** para opções zero, corrompendo o sorteio (`getChoice` pode nunca retornar certas opções / retornar `null` quase sempre). Não há validação que impeça isso. Ver §2.2.
+9. **`inventory` é cap global** por `reward.type+item` (ou isolado por box / box+combinação se `isolated`). Conta `achievement` (L421-449).
+10. **`updatePlayerStatus` sempre roda** ao final do execute (mesmo em LOSE / sem win_chart), desde que box e player existam (L414).
+11. **Multi-tenant:** isolamento por API key resolvido no `FrontController.getInstance(apiKey)`; cada tenant tem seu `ManagerFactory`/conexão Jongo. O `synchronized` do `execute` é por instância (tenant), **não** distribuído.
+
+---
+
+## 6. Comportamentos Automáticos
+
+| Comportamento | Trigger/Origem | Impacto | Persistência |
+|---|---|---|---|
+| Gera `_id` da box | `insert` (L42-44) | id curto se ausente | `mystery_box` |
+| `active=true` default | `insert` (L46-48) | box nasce ativa | `mystery_box` |
+| Recalcula `options` | `prepareOptions` (L51) | probabilidades normalizadas, opções inválidas removidas, ordem alterada | `mystery_box` |
+| Atribui `_id` às combinações | `prepareWinchart` (L54) | `o1`,`o2`,… | `mystery_box` |
+| Cria pasta default | `insert` (L57-67) | doc em `mystery_folder` | `mystery_folder` |
+| Log de tentativa | `execute` (L191-192) | toda jogada registrada | `mystery_box_log` |
+| Débito de `requirements` | `execute` (L195-202) | custo deduzido (achievements negativos) | `achievement` |
+| Achievement da jogada (`a1`) | `execute` em WIN (L330) | conta para `limit` | `achievement` (`type=6`) |
+| Achievement da recompensa (`a2`) | `execute` por combinação (L386) | crédito ao jogador | `achievement` (point/challenge/catalog_item) |
+| `updatePlayerStatus` | `execute` (L414) | recalcula status do jogador | `player_status` |
+| Triggers | `execute` | ver fluxo abaixo | conforme handler |
+
+### Encadeamento de triggers numa vitória com recompensa
+
+Eventos disparados, **nesta ordem** (L320-409):
+
+1. `before_win` — entidade `mystery_box` (a jogada `a1`).
+2. `addAchievement(a1)` — persiste a jogada.
+3. Para **cada** combinação vencedora que casa:
+   1. `before_win_reward` — entidade `mystery_box` ((!) **string literal hardcoded** em L376, **não** é constante `Trigger.EVENT_*`; grep por constante não acha).
+   2. `before_win` — entidade = **coleção da recompensa** (`point_category`/`challenge`/`catalog_item`).
+   3. `addAchievement(a2)` — persiste a recompensa.
+   4. `after_win` — entidade = coleção da recompensa (**após** persistir).
+4. `after_win` — entidade `mystery_box`.
+
+Em derrota: `before_lose` (antes do loop, que não credita nada) e `after_lose` (no fim) — entidade `mystery_box`.
+
+```mermaid
+flowchart LR
+    W{WIN?} -- sim --> BW["before_win (mystery_box)"]
+    BW --> AA["addAchievement(a1)"]
+    AA --> LP["loop win_chart casadas"]
+    LP --> BWR["before_win_reward<br/>(literal, mystery_box)"]
+    BWR --> BWC["before_win<br/>(colecao da recompensa)"]
+    BWC --> AA2["addAchievement(a2)"]
+    AA2 --> AWC["after_win<br/>(colecao da recompensa)"]
+    AWC --> AW["after_win (mystery_box)"]
+    W -- nao --> BL["before_lose (mystery_box)"]
+    BL --> AL["after_lose (mystery_box)"]
+```
+
+---
+
+## 7. Suportado vs NÃO Suportado
+
+### ✅ Suportado
+
+- CRUD de mystery box (`GET`/`GET all`/`POST` upsert/`DELETE`).
+- Execução por GET, POST (com `extra`) e `execute_by_player`.
+- Sorteio ponderado por probabilidade, multi-coluna (`columns`).
+- `win_chart` com combinação ordenada (`orderSensitive=true`) ou por contagem (`false`).
+- Recompensas `point` (0), `challenge` (1), `catalog_item` (2).
+- `limit` (vitórias) e `attempts` (jogadas) por `player` e `gamification`, com janela `every` e `total` numérico **ou** fórmula.
+- `reward.limit` e `reward.inventory`, com isolamento por box/combinação (`isolated`).
+- Exclusão dinâmica de opções com recompensa esgotada (somente `columns==1`).
+- Rollback de jogada (`DELETE /v3/mystery/execute`).
+- Diagnóstico (`GET /v3/mystery/evaluate/{id}`).
+- Pastas (`mystery_folder`) com auto-criação.
+- Triggers `before_win`/`after_win`/`before_lose`/`after_lose` + `before_win_reward`.
+- Geração assistida por IA (`POST /v3/ai/build/mystery`) — **não persiste**, só devolve o JSON.
+
+### ❌ NÃO Suportado / Pegadinhas
+
+- **`type`** (`option_probability`/`combination_probability`) — não existe na entidade; **descartado** silenciosamente (`@JsonIgnoreProperties`).
+- **`probability` por combinação** em `win_chart` — não existe em `MysteryWin`; **descartado**. Odds vêm de `options`×`columns`.
+- **`reward.operation`** — ignorado; só `total/type/item` são usados (comentário L21 de `MysteryWin`).
+- **Recompensa com `type` ≠ 0/1/2** (level, crown, lottery, etc.) — `a2` criado mas **nunca persistido** (collection null).
+- **`limit.per = "team"`** em `limit` da box e em `reward.limit` — branch inexistente; limite **nunca aplicado** (permissivo). `evaluateLimitAnalyze`/`evaluateAttemptsAnalyze` também só tratam `player`/`gamification`.
+- **`Limit.query`** — campo existe no POJO `Limit` mas **nunca é consumido** por nenhuma verificação de mystery.
+- **`MysteryBox.extra`** — persistido, mas **nunca lido** pela lógica do módulo (passthrough).
+- **`MysteryBox.techniques`** — legado; nunca escrito/lido pelo módulo; sem GT code (§3.7).
+- **`MysteryBoxFolder.java`** — classe **morta**, duplicata de `MysteryFolder`, sem referências.
+- **`PUT`** — inexistente; atualização é re-`POST` (full replace).
+- **404 em id inexistente** — `GET /{id}` devolve `200` com `null`.
+- **Proteção de recompensa esgotada para `columns > 1`** — não existe (só `columns==1`).
+- **Validação de probabilidade > 1** — inexistente; gera probabilidade negativa (foot-gun, §2.2/§5).
+- **Estorno de `requirements` no rollback** — `undoExecute` não devolve o custo nem apaga o log.
+- **Bug no `evaluate`**: chave `active` sempre `{}`; status de `active` sobrescreve `exists.status` (L556-558).
+- **Copy-paste em `evaluateAttemptsAnalyze`**: mensagem de erro referencia `a.limit.total` em vez de `a.attempts.total` (L674) — NPE se `limit==null` e `attempts.total` for string malformada.
+- **Scheduler/job automático** — não existe para mystery (toda execução é via endpoint).
+
+---
+
+## 8. Segurança e Permissões
+
+- **Autenticação:** Bearer token em todos os endpoints (`@BeanParam AuthBean`). Operações de CRUD/`delete` exigem credenciais de administrador (token do jogo); `execute` pode usar `player=me` resolvendo o jogador pelo token.
+- **Isolamento multi-tenant:** resolvido por `FrontController.getInstance(apiKey)` → `ManagerFactory`/conexão Jongo por tenant. Não há vazamento entre organizações desde que a API key esteja correta.
+- **Concorrência:** `execute` é `synchronized` na instância do manager (por tenant/JVM). **Não** há lock distribuído — sob múltiplos pods, dois `execute` simultâneos podem ultrapassar `limit`/`inventory` (condição de corrida em estoques pequenos). Mitigação parcial: o `limit` é re-checado tanto no REST quanto no manager, mas sem atomicidade.
+- **Injeção:** as queries MongoDB usam **parâmetros posicionais** do Jongo (`"{_id:#}"`, `count("{type:#,...}", ...)`), o que evita injeção via valores. Porém **`limit.total`/`attempts.total` como fórmula** são avaliados por `MustacheUtils.parse` + `exp4j` — uma fórmula maliciosa configurada por um admin pode lançar exceção (tratada → 400) ou consumir CPU; o conteúdo é definido por administrador, não pelo jogador final, então a superfície é limitada a quem já tem acesso de configuração.
+- **Comportamento permissivo inseguro documentado:** `reward.limit.per="team"` **não bloqueia nada** (§5/§7) — não confie nele para conter distribuição de prêmios.
+
+---
+
+## 9. Observabilidade e Troubleshooting
+
+### Diagnóstico rápido
+
+```
+GET /v3/mystery/{id}                       # a box existe? (200 null = não existe)
+GET /v3/mystery/evaluate/{id}?player=ME    # elegibilidade: limit_wins, limit_attempts, requirements
+```
+
+> Ao ler o `evaluate`, lembre-se do bug do `active` (§4/§7): a chave `active` vem vazia e, se a box estiver inativa, `exists.status` aparecerá como `UNAUTHORIZED`.
+
+### Queries MongoDB úteis
+
+```js
+// jogadas (tentativas) de um jogador numa box
+db.mystery_box_log.find({ item: "<boxId>", player: "<player>" }).sort({ time: -1 })
+
+// vitórias contam aqui (type=6)
+db.achievement.count({ type: 6, item: "<boxId>", player: "<player>" })
+
+// recompensas creditadas por esta box
+db.achievement.find({ "extra.origin_item": "<boxId>" })
+
+// recompensas de uma combinação específica
+db.achievement.find({ "extra.origin_item": "<boxId>", "extra.mystery_win_id": "o1" })
+
+// estoque já distribuído de uma recompensa (inventory)
+db.achievement.count({ type: 0, item: "coin" })
+```
+
+### Erros comuns e causas
+
+| Sintoma | Causa provável |
+|---|---|
+| `400 insufficient requirements` | Jogador não tem o custo (`requirements`) — mas o `mystery_box_log` já foi gravado. |
+| `400 You have exced the limit … earned` | `limit` (vitórias) atingido no período `every`. |
+| `400 You have exced the limit … executed` | `attempts` (jogadas) atingido. |
+| `400 mysterybox is not active` | `active=false` explícito. |
+| `400 mysterybox does not exist` | id inválido no `execute` (no `GET /{id}` retornaria 200/null). |
+| Prêmio não creditado mesmo "ganhando" | `reward.type` ∉ {0,1,2}; ou `limit`/`inventory` da recompensa esgotado (log no console: `"MysteryWin not registered because of limit"`). |
+| Limite "não funciona" | `reward.limit.per="team"` (não suportado); ou soma de probabilidades > 1 corrompendo o sorteio. |
+| Opção nunca sai / `result` quase sempre `null` | Probabilidades somam > 1 → probabilidade negativa em opções zero (§2.2). |
+| Resultado contém `null` | Probabilidades somam < 1 → faixa NONE (esperado, §2.4). |
+
+### O que verificar quando "não funciona"
+
+1. A box está `active`? (`GET /{id}` → campo `active`, lembrando que `null` = ativa).
+2. As probabilidades das `options` somam ≤ 1? Há opções `>1`/`<0` que foram descartadas no save?
+3. A combinação da `win_chart` realmente casa com o `result`? Confira `orderSensitive`.
+4. O `reward.type` é 0/1/2? Caso contrário não é creditado.
+5. `limit`/`inventory` da recompensa esgotou? Veja o console (`MysteryWin not registered because of limit`).
+
+---
+
+## 10. Exemplos Práticos
+
+### 10.1 Mínimo funcional — cara ou coroa
 
-**Exemplo de Body:**
 ```json
+POST /v3/mystery
 {
+  "_id": "heads_or_tails",
   "title": "Heads or Tails",
   "options": [
     { "title": "Heads", "value": "heads", "probability": 0.5 },
     { "title": "Tails", "value": "tails", "probability": 0.5 }
   ],
   "columns": 1,
-  "requirements": [],
   "win_chart": [
-    {
-      "combination": ["heads"],
-      "orderSensitive": false,
-      "reward": {
-        "total": 1,
-        "type": 0,
-        "item": "coin"
-      }
-    }
+    { "combination": ["heads"], "orderSensitive": false,
+      "reward": { "total": 1, "type": 0, "item": "coin" } }
+  ]
+}
+```
+
+Jogar: `GET /v3/mystery/execute/heads_or_tails?player=me`.
+
+### 10.2 Avançado — slot 3 colunas, custo, limites e estoque
+
+```json
+POST /v3/mystery
+{
+  "_id": "office_prizes",
+  "title": "Office Prizes",
+  "options": [
+    { "title": "Notebook", "value": "notebook", "probability": 0.1 },
+    { "title": "Backpack", "value": "backpack", "probability": 0.3 },
+    { "title": "Mouse",    "value": "mouse",    "probability": 0.6 }
+  ],
+  "columns": 3,
+  "requirements": [
+    { "total": 4, "type": 0, "item": "coin", "operation": 1 }
   ],
-  "techniques": ["GT72"],
-  "_id": "64a5b464d8dcca49bcf7edd0"
+  "win_chart": [
+    { "combination": ["notebook","notebook","notebook"], "orderSensitive": false,
+      "reward": { "total": 1, "type": 2, "item": "notebook" },
+      "inventory": 5, "isolated": true,
+      "limit": { "total": 1, "per": "player", "every": "1M" } },
+    { "combination": ["mouse","mouse","mouse"], "orderSensitive": false,
+      "reward": { "total": 1, "type": 2, "item": "mouse" } }
+  ],
+  "limit":    { "total": 1, "per": "player", "every": "1M" },
+  "attempts": { "total": 1, "per": "player", "every": "1d" }
+}
+```
+
+- `requirements`: custa 4 `coin` por jogada (`operation:1` = deduct).
+- `limit`: máx. **1 vitória** por jogador por mês.
+- `attempts`: máx. **1 jogada** por jogador por dia.
+- `inventory: 5` + `isolated`: só 5 notebooks distribuídos por esta box.
+
+### 10.3 Anti-pattern — o que NÃO fazer
+
+```json
+{
+  "_id": "broken_box",
+  "title": "Broken",
+  "type": "option_probability",                       // (X) ignorado (não existe na entidade)
+  "options": [
+    { "value": "a", "probability": 0.7 },
+    { "value": "b", "probability": 0.6 }              // (X) soma 1.3 > 1 -> prob. negativa, sorteio corrompido
+  ],
+  "columns": 3,
+  "win_chart": [
+    { "combination": ["a","a","a"],
+      "probability": 0.01,                            // (X) ignorado (não existe em MysteryWin)
+      "reward": { "total": 1, "type": 3, "item": "lvl" },  // (X) type=3 (level) nunca é creditado
+      "limit": { "total": 5, "per": "team" }          // (X) per=team não bloqueia nada
+    }
+  ]
 }
 ```
 
-### Deletar Mystery Box
-**Método:** DELETE
-**Endpoint:** `/v3/mystery/:id`
+Por que é errado:
 
-### Avaliar Condições
-**Método:** GET
-**Endpoint:** `/v3/mystery/evaluate/:id?player=:player_id`
-**Descrição:** Verifica se o jogador está apto a executar a Mystery Box.
+- `type` no topo e `probability` na combinação são **descartados** silenciosamente.
+- Probabilidades das `options` somam **> 1** → `prepareOptions` quebra o sorteio.
+- `reward.type=3` não está em {0,1,2} → o prêmio **nunca** é registrado.
+- `limit.per="team"` é **silenciosamente ignorado** → sem limite real.
+- Sem `_id` nas combinações, mas isso é OK (o sistema gera `o1`,`o2`…) — só não dependa dele antes do primeiro save.
 
-### Executar Mystery Box
-**Método:** GET
-**Endpoint:** `/v3/mystery/execute/:id?player=:player_id`
-**Descrição:** Executa o sorteio e retorna o resultado.
+---
 
-## Validações e Testes
+## Checklist de Configuração
 
-- [ ] Mystery Box aparece na lista
-- [ ] Soma das probabilidades é 1.0
-- [ ] Jogador consegue executar a mystery box
-- [ ] Combinação vencedora entrega recompensa corretamente
-- [ ] Requisitos são validados antes da execução
+- [ ] `title` preenchido.
+- [ ] `options` com `value` único por opção; probabilidades somando **≤ 1** (evite `> 1` → quebra o sorteio).
+- [ ] Nenhuma opção com `probability > 1` ou `< 0` (seriam **descartadas** no save).
+- [ ] `columns` definido conforme o jogo (1 = roleta simples; >1 = slot).
+- [ ] `win_chart[].combination` usa exatamente os `value`s das `options`.
+- [ ] `orderSensitive` definido conscientemente (`false` = contagem por tipo, pode casar várias linhas).
+- [ ] `reward.type` ∈ {0 (point), 1 (challenge), 2 (catalog_item)} — outros tipos **não** são creditados.
+- [ ] Itens/pontos/desafios de `reward.item` e `requirements.item` **existem** antes de criar a box.
+- [ ] Para limites por jogador/jogo use `per: "player"` ou `"gamification"` — **`team` não funciona**.
+- [ ] Diferencie `limit` (vitórias) de `attempts` (jogadas): se quer limitar quantas vezes pode jogar, use `attempts`.
+- [ ] Ciente de que `extra`, `techniques` e `type` no payload são metadados/ignorados.
+- [ ] Ciente de que `POST` é **full replace** — reenvie o documento completo ao atualizar.
+- [ ] Ciente de que rollback (`DELETE /execute`) **não** estorna `requirements`.