funifier-mcp 0.2.26 → 0.2.27

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

@@ -1,83 +1,565 @@
-# Level (Nível)
+# `level`
 
 **Acesso Studio:** `/studio/level`
 **API Endpoint:** `/v3/level`
+**Coleção MongoDB:** `level` (configuração global em `level_config`)
 
-## O que é
+---
 
-Sistema de progressão por níveis. Permite definir a progressão dos jogadores com base em pontos acumulados ou outros critérios, atribuindo títulos ou benefícios a cada nível. Pode-se exigir desafios específicos para desbloquear certos níveis.
+## 1. Visão Geral
 
-## Quando usar
+O módulo `level` define a **escada de progressão** de um jogo Funifier: uma lista ordenada de níveis que o jogador conquista à medida que acumula pontos. Cada documento da coleção `level` é uma **definição estática** (configuração do designer); o nível efetivamente alcançado por um jogador **não é gravado no documento do jogador**, e sim derivado da coleção `achievement`.
 
-- Para criar senso de progressão e conquista
-- Para desbloquear funcionalidades por nível
-- Para segmentar jogadores por experiência
-- Exemplos: Júnior → Pleno → Sênior; faixas coloridas
+Pontos arquiteturais que diferem da intuição REST/CRUD:
 
-## Dependências
+- O módulo `level` em si (`LevelRest` + `LevelManager` + `LevelDaoMongo`) é apenas **CRUD da definição de níveis**. Ele não contém o motor de promoção.
+- O **motor de level-up real vive em `AchievementManager`** — métodos `evaluateLevelUp`, `findLatestLevelAchieved` e `updatePlayerStatus`. É lá que se decide quando o jogador sobe de nível, não no `LevelManager`.
+- O nível atual de um jogador é o **achievement mais recente do tipo `LEVEL`** (`Achievement.TYPE_LEVEL = 3`). Níveis nunca são removidos/regredidos (comentário do código: *"challenges and levels will never be deducted to avoid problems"*).
+- O snapshot de progresso (`LevelProgress`) é materializado dentro de `player_status.level_progress`, recalculado a cada `updatePlayerStatus`.
 
-- **Point**: a categoria de ponto usada para progressão deve existir antes
-- **Configuração global**: definir qual ponto controla os níveis via `/v3/database/level_config`
+Relação com outros módulos:
 
-## Checklist de Configuração no Studio
+- **`achievement`** — fonte da verdade. Gera o achievement `TYPE_LEVEL` na promoção e soma os pontos (`sumTotalRewards`) que disparam a subida. `updatePlayerStatus` é o ponto onde o nível é avaliado e materializado.
+- **`point` / `point_category`** — a progressão consome o total de pontos. A categoria considerada depende de `level_config.pointCategory` (global) ou da categoria embutida no nível via `getPoint()`.
+- **`challenge` (Requirement)** — o array `requirements` de um nível reusa a classe `Requirement` para exigir pré-condições (desafios, items, pontos) antes de liberar a promoção.
+- **`trigger`** — eventos `before_win` / `after_win` na entidade `level` são disparados em torno do registro da promoção.
+- **`notification`** — `NotificationDefinition[]` do nível com evento `EVENT_WIN` gera notificação na promoção.
+- **`technique` (GameTechniqueManager)** — usa `level_config` e `getPoint()` para desenhar as ligações ponto → nível ("level up") no mapa do jogo; código de técnica do módulo = **GT85**.
+- **`player_status`** — coleção materializada que guarda `level_progress` por jogador.
 
-- [ ] Definir _id do nível (ex: L0, L1, L2)
-- [ ] Definir nome do nível (ex: "Apprentice", "Master")
-- [ ] Definir descrição motivadora
-- [ ] Definir minPoints (pontuação mínima crescente)
-- [ ] Definir position (ordem sequencial, iniciando em 0)
-- [ ] Configurar categoria de ponto global (level_config)
+---
 
-## API Endpoints
+## 2. Arquitetura e Fluxos
 
-### Listar Níveis
-**Método:** GET
-**Endpoint:** `/v3/level`
+### 2.1 Classes envolvidas
 
-### Criar Nível
-**Método:** POST
-**Endpoint:** `/v3/level`
+| Classe | Papel |
+|---|---|
+| `com.funifier.engine.level.Level` | Entidade/POJO — documento raiz da coleção `level` |
+| `com.funifier.engine.level.LevelConfig` | Configuração global (`level_config`, `_id: "global"`) — define `pointCategory` |
+| `com.funifier.engine.level.LevelProgress` | DTO de progresso, **não persiste sozinho** — embutido em `player_status.level_progress` |
+| `com.funifier.engine.level.LevelManager` | CRUD + queries auxiliares; **não promove jogadores** |
+| `com.funifier.engine.level.LevelDaoMongo` | Acesso MongoDB direto (Jongo) à coleção `level` |
+| `com.funifier.rest.v3.rest.LevelRest` | Controller REST v3 (`/v3/level`) |
+| `com.funifier.engine.achievement.AchievementManager` | **Motor real de level-up** (`evaluateLevelUp`, `findLatestLevelAchieved`, `updatePlayerStatus`, `findPlayerStatusByLevel`) |
+| `com.funifier.engine.challenge.Requirement` | Pré-requisitos de promoção (reusada de challenge) |
 
-**Exemplo de Body:**
+> A configuração `level_config` **não tem endpoint próprio** no `LevelRest`. Ela é manipulada pelo módulo genérico de banco/custom-object (`/v3/database/level_config`). `LevelManager.findConfig()` apenas a lê (`_id: "global"`).
+
+### 2.2 Pipeline principal — promoção de nível
+
+O motor não é acionado pelo `LevelRest`. Ele roda dentro de `AchievementManager.updatePlayerStatus(player, jongo)`, que é chamado **após qualquer registro de achievement** (ex.: ganho de pontos via `fireAction` linha 805/861, compras em `CatalogManager`, trocas em `SwapManager`).
+
+Sequência real (linhas 1012-1055 de `AchievementManager.java`):
+
+```
+[1] while(evaluateLevelUp(player, jongo, achievements));   // promove 1 nível por iteração até não haver mais
+[2] level       = findLatestLevelAchieved(player, jongo);  // nível atual = último achievement TYPE_LEVEL
+[3] next_level  = clevel.findOne("{position: {$gte: #}}", level.position+1).orderBy("{position:1}")
+                  // se não há nível atual → primeiro nível por position asc
+[4] total_levels = clevel.count();
+[5] calcula percent_completed e next_points (ver 2.3)
+[6] status.level_progress = new LevelProgress(level, percent, next_level, next_points, total_levels);
+[7] player_status: remove({_id: player}) + save(status)    // full replace do snapshot
+```
+
+Detalhe de `evaluateLevelUp` (linhas 1132-1199) — avalia **uma** promoção:
+
+```
+currentLevel = findLatestLevelAchieved(player)              // pode ser null (jogador sem nível)
+nextLevel    = primeiro level com position >= currentLevel.position+1 (asc)
+               // se currentLevel == null → primeiro level por position asc
+config       = level_config (_id: "global")
+pointCategory = (config.pointCategory não-vazio) ? config.pointCategory : null
+points       = sumTotalRewards(player, TYPE_POINT, pointCategory)
+               // pointCategory == null  → soma TODOS os pontos do jogador
+
+se nextLevel != null E points >= nextLevel.minPoints:
+    se evaluateRequirements(nextLevel.requirements, player, jongo):     // ver 2.4
+        trigger.execute(level, EVENT_BEFORE_WIN)
+        addAchievement( Achievement(TYPE_LEVEL, item = nextLevel._id) )  // registra promoção
+        trigger.execute(level, EVENT_AFTER_WIN)
+        envia NotificationDefinition(EVENT_WIN) do nível
+        retorna true        // → o while volta e tenta o PRÓXIMO nível
+retorna false               // → encerra o loop
+```
+
+Consequência do `while`: se o jogador ganha pontos suficientes para pular vários níveis de uma vez, **cada nível intermediário gera seu próprio achievement, trigger e notificação** — ele "passa" por todos, não salta direto para o final.
+
+### Fluxo de promoção — `evaluateLevelUp` (loop de `updatePlayerStatus`)
+
+```mermaid
+flowchart TD
+    A[updatePlayerStatus] --> B{evaluateLevelUp}
+    B --> C[currentLevel = findLatestLevelAchieved]
+    C --> D["nextLevel = level position >= current.position+1<br/>(ou 1º level se sem nível)"]
+    D --> E["pointCategory = level_config.pointCategory<br/>(ou null = todos os pontos)"]
+    E --> F["points = sumTotalRewards(TYPE_POINT, pointCategory)"]
+    F --> G{nextLevel != null<br/>E points >= nextLevel.minPoints?}
+    G -- não --> H[retorna false → fim do loop]
+    G -- sim --> I{evaluateRequirements<br/>nextLevel.requirements?}
+    I -- não --> H
+    I -- sim --> J[trigger before_win]
+    J --> K["addAchievement TYPE_LEVEL<br/>item = nextLevel._id"]
+    K --> L[trigger after_win + notificação EVENT_WIN]
+    L --> M[retorna true → tenta próximo nível]
+    M --> B
+    H --> N[calcula LevelProgress e grava player_status]
+```
+
+### 2.3 Cálculo de `LevelProgress` (percent / next_points)
+
+Trecho real (linhas 1020-1055). Define quanto falta para o próximo nível:
+
+```
+percent_completed = 100      // default quando não há próximo nível
+next_points       = 0
+
+se next_level != null:
+    point1 = (level != null) ? level.getPoint() : null
+    point2 = next_level.getPoint()
+    // só usa total por categoria se AMBOS os níveis apontam para a MESMA categoria
+    total_points = (point1 != null && point2 != null && point1.equals(point2))
+                   ? sumTotalRewards(TYPE_POINT, point1)
+                   : status.total_points          // senão: total global de pontos
+
+    next_points = max(0, next_level.minPoints - total_points)
+
+    se level != null:
+        diff_total = total_points     - level.minPoints
+        diff_next  = next_level.minPoints - level.minPoints
+    senão:                                          // jogador ainda sem nível → base 0
+        diff_total = total_points
+        diff_next  = next_level.minPoints
+
+    percent_completed = (total_points <= next_level.minPoints)
+                        ? round2( (diff_total / diff_next) * 100 )
+                        : 100
+```
+
+`percent_completed` é arredondado para 2 casas decimais (`ParserUtil.setDoubleDecimalScale(x, 2)`).
+
+### 2.4 Avaliação de `requirements` no level-up
+
+`AchievementManager.evaluateRequirements(Requirement[] all, String player, Jongo jongo)` (linhas 2584-2601) é o validador usado pelo level-up:
+
+```
+para cada r em requirements:
+    period = DateUtil.fromKeywordPeriodExpression(r.period)
+    total  = sumTotalRewards(player, r.type, r.item, period)
+    se r.total > total: retorna false   // requisito não atingido
+retorna true
+```
+
+**Comportamento silencioso crítico:** esta variante **ignora `r.operation`**. Não existe dedução — todo requirement de um nível é tratado como `VERIFY` (apenas confere se `total >= r.total`). Configurar `operation: 1 (DEDUCT)` num requirement de nível **não deduz nada**; comporta-se como `VERIFY`.
+
+### 2.5 Interação entre módulos na promoção
+
+```mermaid
+sequenceDiagram
+    participant Act as ActionManager / Catalog / Swap
+    participant AM as AchievementManager
+    participant Lvl as coleção level / level_config
+    participant Ach as coleção achievement
+    participant Trg as TriggerManager
+    participant Ntf as NotificationManager
+
+    Act->>AM: updatePlayerStatus(player)
+    loop até não promover
+        AM->>Ach: sumTotalRewards(TYPE_POINT, pointCategory)
+        AM->>Lvl: lê level_config + próximo nível (position)
+        AM->>Ach: evaluateRequirements (sumTotalRewards por requirement)
+        alt points >= minPoints e requirements ok
+            AM->>Trg: execute(level, before_win)
+            AM->>Ach: addAchievement(TYPE_LEVEL, nextLevel._id)
+            AM->>Trg: execute(level, after_win)
+            AM->>Ntf: send(EVENT_WIN)
+        end
+    end
+    AM->>AM: monta LevelProgress
+    AM->>Ach: player_status.save(level_progress)
+```
+
+### 2.6 CRUD da definição (síncrono)
+
+`LevelDaoMongo` (coleção fixa `"level"`):
+
+- `add(level)` → se `_id` ausente/vazio gera `Guid.newShortGuid()`, depois `c.save(level)` (**upsert** por `_id`).
+- `update(level)` → `c.remove({_id: level._id})` **seguido de** `c.save(level)` → **full replace** (remove e regrava o documento inteiro; não há merge/patch).
+- `delete(id)` → `c.remove({_id: id})`.
+- `findById(id)` / `findAll()` → `findAll` ordena por `{position: 1}`.
+
+`LevelManager.updateAllPositions()` (linhas 32-42): carrega **todos** os níveis ordenados por `{minPoints: 1}` e reatribui `position = índice` (0-based), salvando cada um — realinha `position` à ordem de `minPoints`.
+
+---
+
+## 3. Estrutura dos Objetos
+
+### 3.1 `Level` — documento raiz (coleção `level`)
+
+| Campo | Tipo | Padrão | Obrigatório | Descrição |
+|---|---|---|---|---|
+| `_id` | String | auto (`Guid.newShortGuid()`) | — | Identificador. Gerado no POST se ausente/vazio. |
+| `level` | String | — | Recomendado | Nome/título do nível (ex.: "Apprentice"). É o campo exibido como título no Studio (`GameManager`). |
+| `position` | int | 0 | Sim (na prática) | Ordem do nível. **Governa a navegação "próximo nível"** no motor (não o `minPoints`). |
+| `description` | String | — | Não | Descrição livre. |
+| `minPoints` | int | 0 | Sim (na prática) | Limiar de pontos para promoção a este nível. |
+| `image` | Image | — | Não | Imagem; estrutura `{small, medium, original}` cada um com `url` (vide exemplo do `LevelRest`). |
+| `notifications` | NotificationDefinition[] | null | Não | Notificações disparadas; só as de `event = EVENT_WIN (0)` são usadas na promoção. |
+| `requirements` | Requirement[] | null | Não | Pré-condições de promoção (ver 3.2). Tratadas sempre como `VERIFY`. |
+| `i18n` | Map<String, Map<String,String>> | `{}` | Não | Traduções. Campo público, persistido como veio. |
+| `extra` | Map<String, Object> | `{}` | Não | Campos arbitrários do designer. Persistido. |
+| `techniques` | List\<String\> | `null` | Não | Códigos de técnica de jogo (GT). Ver 3.4. |
+
+**Campo computado `point` (getter `getPoint()`):**
+
+Não existe campo `point` armazenável diretamente. O getter `Level.getPoint()` (linhas 39-49) **deriva** a categoria de ponto do nível:
+
+```
+se requirements tem EXATAMENTE 1 item
+   E requirements[0].type == TYPE_POINT (0)
+   E requirements[0].operation == OPERATION_VERIFY (0)
+   E requirements[0].total == minPoints:
+       point = requirements[0].item    // a categoria de ponto
+senão:
+       point = null
+```
+
+Como Jackson serializa todo getter público sem `@JsonIgnore`, a propriedade `point` **aparece nas respostas REST** e **é gravada no documento Mongo** como snapshot do cálculo. Não há `setPoint` → um `point` enviado no corpo de um POST é **silenciosamente descartado** (regenerado a partir de `requirements`).
+
+**Campos removidos/legados:**
+
+- `apiKey` (linha 20) — **comentado no código** (legado: vincularia o nível a uma licença específica). Não existe em runtime.
+- `getPoint()` não-nulo só ocorre quando o nível tem exatamente 1 requirement de ponto cujo `total` casa com `minPoints`; em qualquer outra configuração de `requirements`, `point` é `null`.
+
+### 3.2 `Requirement` (subentidade de `requirements`)
+
+| Campo | Tipo | Descrição |
+|---|---|---|
+| `total` | int | Quantidade mínima exigida (no level, sempre comparada como `>=`). |
+| `type` | int | Tipo do item exigido (ver enum abaixo). |
+| `item` | String | Id do item exigido (challenge_id, catalog_item_id, point_category…). |
+| `operation` | int | `0 VERIFY` / `1 DEDUCT`. **Ignorado no level-up** (sempre VERIFY). |
+| `period` | String | Expressão de período (ex.: `-5h;-0h`) para limitar o somatório. |
+| `extra`, `folder`, `restrict`, `perPlayer` | — | Demais campos da classe; não usados pelo fluxo de level. |
+
+Enum `type` (`Requirement`): `0 POINT`, `1 CHALLENGE`, `2 CATALOG_ITEM`, `3 LEVEL`, `4 CROWN`, `5 LOTTERY`, `6 MYSTERY_BOX`, `7 CHARACTER_STAR_STAT`, `50 LOTTERY_TICKET`.
+
+### 3.3 `LevelConfig` — configuração global (coleção `level_config`)
+
+| Campo | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `_id` | String | `"global"` | Único documento de config; o motor sempre lê `_id: "global"`. |
+| `pointCategory` | String | null | Categoria de ponto que controla a progressão. Se vazio/null → progressão usa o **total de todos os pontos**. |
+
+### 3.4 `LevelProgress` — snapshot embutido em `player_status.level_progress`
+
+Os nomes JSON vêm dos getters (não dos campos):
+
+| Propriedade JSON | Campo Java | Tipo | Descrição |
+|---|---|---|---|
+| `level` | `level` | Level | Nível atual (null se o jogador ainda não conquistou nenhum). |
+| `percent` | `percent_completed` | double | % concluído rumo ao próximo nível (2 casas). 100 se não há próximo. |
+| `next_level` | `next_level` | Level | Próximo nível por `position`; null no topo da escada. |
+| `next_points` | `next_points` | int | Pontos faltantes para o próximo nível (`max(0, …)`). |
+| `total_levels` | `total_levels` | int | Total de documentos na coleção `level`. |
+
+### 3.5 Técnicas de jogo (`techniques`)
+
+O único código associado ao módulo `level` é:
+
+| Código GT | Significado operacional |
+|---|---|
+| `GT85` | **Level up** — técnica de gamificação "níveis/progressão". Atribuída automaticamente a níveis sem `techniques` por `GameTechniqueManager.autoConfigureMissingTechniqueFields()` (constante `LEVEL_CODE = "GT85"`). |
+
+> O campo `techniques` é uma `List<String>` livre; o sistema só **autoinjeta** `GT85` quando o nível não tem técnica alguma. Outros códigos GT pertencem a outros módulos (ex.: `GT01` point, `GT35` challenge, `GT03` leaderboard).
+
+### 3.6 Ciclo de vida do nível de um jogador
+
+```mermaid
+stateDiagram-v2
+    [*] --> SemNivel: jogador novo (nenhum achievement TYPE_LEVEL)
+    SemNivel --> Nivel0: points >= level[pos=0].minPoints + requirements
+    Nivel0 --> Nivel1: points >= próximo.minPoints + requirements
+    Nivel1 --> NivelN: ... (1 promoção por iteração do while)
+    NivelN --> NivelN: nunca regride (levels não são deduzidos)
+    NivelN --> [*]: topo da escada (next_level == null)
+```
+
+---
+
+## 4. Endpoints
+
+Base: `@Path("v3/level")`, `Produces: application/json; charset=UTF-8`. Autenticação: `@BeanParam AuthBean` (Bearer token) em todos.
+
+### `GET /v3/level`
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Lista todos os níveis. |
+| Implementação | `LevelManager.findAll()` → ordenado por `position` asc. |
+| Resposta | Array de `Level`; campos nulos removidos (`JsonUtil.toJsonRemoveNullFields`). |
+
+### `GET /v3/level/{id}`
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Busca um nível por `_id`. |
+| Resposta | Objeto `Level` (200) ou objeto vazio se não encontrado. |
+
+### `POST /v3/level`
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | **Cria OU atualiza** um nível. |
+| Full replace ou patch | **Full replace** — `c.save()` faz upsert por `_id`. |
+| Status | `201 CREATED`. |
+
+**Comportamento real:**
+- Sem `_id` no corpo → gera `_id` curto automático.
+- Com `_id` existente → **sobrescreve o documento inteiro** (não é merge). Campos omitidos são perdidos.
+- **Não existe `PUT /v3/level/{id}`** — a atualização de um nível é feita por este POST com `_id` preenchido.
+- `point` enviado no corpo é descartado (recalculado de `requirements`).
+
+**Exemplo (do javadoc do `LevelRest`):**
 ```json
+POST /v3/level
 {
-  "level": "Apprentice",
-  "position": 0,
-  "description": "It indicates that you are learning and growing.",
-  "minPoints": 10,
-  "notifications": [],
-  "requirements": [],
-  "i18n": {},
-  "extra": {},
-  "techniques": ["GT85"],
-  "_id": "L0"
+  "level": "Level",
+  "description": "Level Description",
+  "position": 1,
+  "minPoints": 100,
+  "image": {
+    "small":    { "url": "http://funifier.com/level.png" },
+    "medium":   { "url": "http://funifier.com/level.png" },
+    "original": { "url": "http://funifier.com/level.png" }
+  }
 }
 ```
 
-### Excluir Nível
-**Método:** DELETE
-**Endpoint:** `/v3/level/:id`
+### `PUT /v3/level/position`
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Recalcula `position` de todos os níveis ordenando por `minPoints` asc. |
+| Implementação | `LevelManager.updateAllPositions()` → `position = índice` (0-based). |
+| Corpo | Nenhum (não recebe payload). |
+| Resposta | `201 CREATED` `{ "status": "OK" }`. |
+
+### `DELETE /v3/level/{id}`
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Remove a definição do nível. |
+| Resposta | `204 NO_CONTENT`. |
+| Efeito colateral | **Nenhum** sobre achievements/jogadores. Achievements `TYPE_LEVEL` que apontam para o `_id` removido permanecem; `findLatestLevelAchieved` pode retornar um nível inexistente (ver §5). |
+
+> **Não exposto via `/v3/level`:** gestão de `level_config`. Use o módulo de banco: `PUT /v3/database/level_config` com `{ "_id": "global", "pointCategory": "<categoria>" }`.
+
+---
+
+## 5. Regras de Negócio
+
+Regras que existem no código mas não no schema:
+
+1. **`position` define a ordem, `minPoints` define o limiar.** O motor escolhe o "próximo nível" por `{position: {$gte: atual.position+1}}` ordenado por `position`. O gatilho de promoção compara `points >= nextLevel.minPoints`. Se `position` e `minPoints` ficarem **desalinhados** (ex.: o nível com `position` seguinte tem `minPoints` menor que o atual), o jogador pode subir de forma inesperada ou um nível pode ficar inalcançável. Use `PUT /v3/level/position` para realinhar.
+
+2. **Categoria de ponto da progressão:**
+   - `level_config.pointCategory` definido → conta apenas aquela categoria.
+   - vazio/ausente → soma **todos** os pontos (`sumTotalRewards(..., null)`).
+   - O `LevelConfig` é **global por tenant**; não há configuração por nível além do truque do `getPoint()`.
+
+3. **`getPoint()` por nível** só vale quando o nível tem exatamente 1 requirement de ponto com `total == minPoints`. O `percent_completed` só usa esse total por categoria quando **ambos** (atual e próximo) apontam para a **mesma** categoria; caso contrário usa o total global.
+
+4. **Promoção é monotônica e em cascata.** Níveis nunca regridem; um único `updatePlayerStatus` pode promover vários níveis em sequência (um achievement/trigger/notificação por nível).
+
+5. **Requirements são sempre VERIFY** no contexto de nível (operação ignorada). Não há dedução de pontos/itens ao subir de nível.
+
+6. **`findPlayerStatusByLevel(Level level)`** consulta `player_status` com `{level_progress.level: <objeto Level inteiro>}` — é uma **igualdade de objeto embutido completo**, frágil: qualquer divergência de campo (ex.: `point` recalculado, `image`, `extra`) faz o match falhar.
+
+7. **Consistência eventual:** o nível só muda quando `updatePlayerStatus` roda (após ganho de pontos, compra, troca, etc.). Alterar `minPoints` de um nível **não** rebaixa nem promove jogadores retroativamente até o próximo `updatePlayerStatus` daquele jogador.
+
+8. **Multi-tenant:** todo acesso passa por `FrontController.getInstance(apiKey)` → `ManagerFactory` → conexão Jongo do banco do tenant. Níveis e `level_config` são isolados por organização.
+
+---
+
+## 6. Comportamentos Automáticos
+
+| Comportamento | Trigger | Impacto | Persistência |
+|---|---|---|---|
+| Geração de `_id` | POST sem `_id` | Cria GUID curto | Sim (`level`) |
+| Promoção de nível | `updatePlayerStatus` após ganho de pontos | Registra achievement `TYPE_LEVEL` | Sim (`achievement`) |
+| Trigger `before_win`/`after_win` | Em torno de cada promoção (entidade `level`) | Executa triggers configurados | Conforme trigger |
+| Notificação de nível | Promoção, `NotificationDefinition` com `EVENT_WIN` | Envia notificação ao jogador | Conforme notification |
+| Recalculo de `LevelProgress` | Todo `updatePlayerStatus` | Atualiza `player_status.level_progress` | Sim (`player_status`, full replace) |
+| Snapshot `point` | `c.save(level)` (POST) | Grava propriedade derivada `point` | Sim (`level`) |
+| Autoinjeção `GT85` | `autoConfigureMissingTechniqueFields()` | Adiciona técnica a níveis sem `techniques` | Sim (`level`) |
+
+### Encadeamento na promoção
+
+```mermaid
+flowchart LR
+    P[Ganho de pontos] --> U[updatePlayerStatus]
+    U --> E{evaluateLevelUp:<br/>points >= minPoints<br/>e requirements?}
+    E -- sim --> BW[trigger before_win]
+    BW --> AC[achievement TYPE_LEVEL]
+    AC --> AW[trigger after_win]
+    AW --> NT[notificação EVENT_WIN]
+    NT --> E
+    E -- não --> LP[grava level_progress<br/>em player_status]
+```
+
+---
+
+## 7. Suportado vs NÃO Suportado
+
+### ✅ Suportado
+
+- CRUD da definição de níveis (`GET`, `GET /{id}`, `POST`, `DELETE /{id}`).
+- Reordenação automática por `minPoints` (`PUT /v3/level/position`).
+- Progressão automática por pontos (categoria global ou total).
+- Pré-requisitos de promoção via `requirements` (como VERIFY).
+- Triggers `before_win`/`after_win` e notificações `EVENT_WIN` por nível.
+- Materialização de progresso (`percent`, `next_points`, `next_level`, `total_levels`) em `player_status`.
+- i18n e `extra` arbitrários.
+- Isolamento multi-tenant.
+
+### ❌ NÃO Suportado / Armadilhas
+
+- **`PUT /v3/level/{id}` não existe** — atualização só via `POST` (full replace).
+- **`POST` não faz patch** — campos omitidos são apagados do documento.
+- **`operation` em `requirements` de nível é ignorado** — sempre VERIFY; não há dedução ao subir.
+- **`LevelManager.findCurrentByPoints` e `findNextByPoints` são código morto** — nenhum chamador no projeto (confirmado via grafo). Além disso usam `minPoints` (não `position`), divergindo do motor real. Não confie neles para entender o comportamento.
+- **`level_config` não tem endpoint no módulo level** — apenas leitura via `findConfig()`; escrita via `/v3/database/level_config`.
+- **`point` enviado no corpo é descartado** — é derivado de `requirements`.
+- **`apiKey`** no `Level` é legado comentado — inexistente em runtime.
+- **DELETE não limpa achievements** — remover um nível não remove achievements `TYPE_LEVEL` que o referenciam; `findLatestLevelAchieved` pode retornar id órfão e `findById` devolver objeto vazio.
+- **Sem rebaixamento** — reduzir pontos do jogador (estorno) **não** o rebaixa; o achievement `TYPE_LEVEL` mais recente permanece como nível atual.
+- **`findPlayerStatusByLevel`** depende de igualdade de objeto embutido completo — quebradiço.
+- Não há job/scheduler dedicado ao módulo `level` (não localizado no código).
 
-### Configurar Ponto Global para Níveis
-**Método:** PUT
-**Endpoint:** `/v3/database/level_config`
+---
 
-**Exemplo de Body:**
+## 8. Segurança e Permissões
+
+- **Autenticação:** todos os endpoints exigem `AuthBean` (Bearer token). Não há checagem de papel/role explícita dentro de `LevelRest` — o controle de acesso administrativo depende da chave/token do tenant resolvido por `FrontController.getInstance(apiKey)`.
+- **Isolamento por organização:** cada tenant opera no próprio banco (conexão Jongo via `ManagerFactory`). `level` e `level_config` não cruzam tenants.
+- **Superfície de script (Groovy):** `PublicManager` importa `com.funifier.engine.level.Level` em scripts dinâmicos (linha 172). Conteúdo de scripts públicos/customizados que manipulem níveis deve ser auditado — execução de script é um vetor sensível.
+- **Operações destrutivas silenciosas:** `POST` sobrescreve o documento inteiro e `update` (DAO) faz `remove` + `save`. Uma chamada malformada pode apagar campos sem erro. `PUT /v3/level/position` reescreve `position` de **todos** os níveis de uma vez.
+- Não há sanitização explícita dos campos do `Level` antes de `c.save` — confie no contrato do `AuthBean` e valide entradas na camada cliente.
+
+---
+
+## 9. Observabilidade e Troubleshooting
+
+**Diagnóstico — o jogador subiu de nível?**
+```
+GET /v3/level                      # confere a escada e a ordem (position)
+GET /v3/level/<id>                 # confere minPoints/requirements de um nível
+# nível atual do jogador está em player_status.level_progress:
+GET /v3/player/<player_id>/status  # ou inspecione a coleção player_status
+```
+
+**Queries úteis (via /v3/database, coleção achievement):**
+```jsonc
+// histórico de promoções de um jogador (type 3 = LEVEL)
+{ "player": "<player_id>", "type": 3 }   // ordenar por time desc → nível atual
+
+// total de pontos que o motor enxerga (categoria global de level_config)
+// equivale a sumTotalRewards(player, TYPE_POINT, pointCategory)
+```
+
+**Erros comuns e causas:**
+
+| Sintoma | Causa provável |
+|---|---|
+| Jogador não sobe de nível mesmo com pontos | `level_config.pointCategory` aponta para categoria errada/inexistente → `points = 0`; ou `requirements` do próximo nível não atendidos; ou `position` desalinhado de `minPoints`. |
+| Jogador "pula" níveis com 1 ganho | Comportamento esperado: o `while` promove em cascata (cada nível ainda gera achievement/notificação). |
+| `percent` parece errado | Categorias de ponto de `getPoint()` divergem entre nível atual e próximo → cálculo cai no total global. |
+| Nível atual aponta para id inexistente | Nível foi deletado mas o achievement `TYPE_LEVEL` permaneceu. |
+| Atualizar um nível "apagou" campos | `POST` é full replace; reenvie o documento completo. |
+| `requirements` com dedução não deduziu | Esperado: no level, `operation` é ignorado (sempre VERIFY). |
+
+**O que verificar quando algo não funciona:** confirme `level_config`; confirme que `position` é sequencial e coerente com `minPoints` (rode `PUT /v3/level/position`); confirme que algum evento dispara `updatePlayerStatus` (ganho de pontos, compra, troca).
+
+---
+
+## 10. Exemplos Práticos
+
+### 10.1 Exemplo mínimo funcional (progressão por total de pontos)
+```json
+POST /v3/level
+{ "_id": "L0", "level": "Iniciante", "position": 0, "minPoints": 0 }
+```
+```json
+POST /v3/level
+{ "_id": "L1", "level": "Bronze", "position": 1, "minPoints": 100 }
+```
+Com `level_config` ausente/vazio, a soma de **todos** os pontos governa a subida.
+
+### 10.2 Exemplo avançado (categoria específica + requirement de desafio)
+```json
+PUT /v3/database/level_config
+{ "_id": "global", "pointCategory": "xp" }
+```
+```json
+POST /v3/level
+{
+  "_id": "L2",
+  "level": "Prata",
+  "position": 2,
+  "minPoints": 500,
+  "description": "Requer 500 xp e o desafio de onboarding.",
+  "image": { "medium": { "url": "https://cdn.exemplo.com/silver.png" } },
+  "requirements": [
+    { "type": 1, "item": "challenge_onboarding", "total": 1, "operation": 0 }
+  ],
+  "notifications": [ { "event": 0, "scope": 0, "title": "Você chegou ao Prata!" } ],
+  "i18n": { "en": { "level": "Silver" } },
+  "techniques": ["GT85"]
+}
+```
+Para "minPoints em uma categoria via `getPoint()`", use **um único** requirement de ponto com `total == minPoints`:
 ```json
 {
-  "_id": "global",
-  "pointCategory": "xp"
+  "_id": "L3", "level": "Ouro", "position": 3, "minPoints": 1000,
+  "requirements": [ { "type": 0, "item": "xp", "total": 1000, "operation": 0 } ]
 }
 ```
+Aqui `getPoint()` retornará `"xp"` e a resposta REST trará `"point": "xp"`.
+
+### 10.3 Anti-pattern (o que NÃO fazer)
+```json
+// ❌ ERRADO: tentar "atualizar só o minPoints" via POST parcial
+POST /v3/level
+{ "_id": "L2", "minPoints": 600 }
+```
+Isto **apaga** `level`, `position`, `requirements`, `image` etc. do nível L2 (full replace). Sempre reenvie o documento completo.
+
+```json
+// ❌ ERRADO: esperar dedução de pontos ao subir de nível
+{ "type": 0, "item": "xp", "total": 100, "operation": 1 }  // operation DEDUCT é ignorado no level → vira VERIFY
+```
+
+```jsonc
+// ❌ ERRADO: position fora de ordem com minPoints
+{ "_id": "A", "position": 0, "minPoints": 500 }
+{ "_id": "B", "position": 1, "minPoints": 100 }  // "próximo" nível tem minPoints menor → progressão incoerente
+// Rode PUT /v3/level/position para realinhar position ao minPoints.
+```
 
-### Atualizar Posições dos Níveis
-**Método:** PUT
-**Endpoint:** `/v3/level/position`
-**Descrição:** Recalcula posições com base no minPoints.
+---
 
-## Validações e Testes
+## Checklist de Configuração
 
-- [ ] Níveis aparecem na lista GET /v3/level
-- [ ] minPoints é crescente entre níveis
-- [ ] level_config aponta para o ponto correto
-- [ ] Ao ganhar pontos suficientes, jogador sobe de nível automaticamente
+- [ ] `_id` definido (ou deixe em branco para autogerar) e estável entre updates.
+- [ ] `level` (nome) preenchido — é o título exibido no Studio.
+- [ ] `minPoints` crescente e coerente com `position`.
+- [ ] `position` sequencial a partir de 0 (rode `PUT /v3/level/position` após mudanças em `minPoints`).
+- [ ] `level_config` (`_id: "global"`) configurado **antes** se a progressão deve usar uma categoria específica; senão a soma de todos os pontos é usada.
+- [ ] A `pointCategory` de `level_config` existe no módulo `point`.
+- [ ] Itens/desafios citados em `requirements` existem antes de criar o nível.
+- [ ] Ciente: `POST` é full replace — sempre envie o documento completo ao "atualizar".
+- [ ] Ciente: `operation` em `requirements` de nível é ignorado (sempre VERIFY).
+- [ ] Ciente: deletar um nível não limpa achievements `TYPE_LEVEL` que o referenciam.
+- [ ] `notifications` usam `event: 0 (EVENT_WIN)` para disparar na promoção.