funifier-mcp 0.2.26 → 0.2.28

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

@@ -1,46 +1,1144 @@
-# Achievement (Conquista)
+# `achievement`
 
+**Acesso Studio:** `/studio/achievement`
 **API Endpoint:** `/v3/achievement`
+**Endpoint Legado:** `/2.0.0/achievement`
+**Coleção MongoDB:** `achievement`
 
-## O que é
+---
 
-Registro das conquistas dos jogadores ao atingirem marcos relevantes. Todas as conquistas — como completar desafios, subir de nível, ganhar pontos ou adquirir itens — são registradas neste módulo. Ele automatiza o reconhecimento dos marcos alcançados, mas permite ajustes manuais.
+## 1. Visão Geral
 
-## Quando usar
+O módulo `achievement` é o registro imutável de **todo evento de recompensa ou perda** dentro da gamificação Funifier. Cada documento da coleção `achievement` representa um único "movimento de conta" sobre o saldo de um jogador (ou time) em uma das dimensões suportadas: pontos, desafios completos, items de catálogo, níveis, coroamentos, loterias, mystery boxes, character star stats, bônus, competições e tipos customizados.
 
-- Para consultar conquistas dos jogadores
-- Para criar relatórios de desempenho
-- Para usar em aggregates e dashboards
-- Para triggers que reagem a conquistas
+Papel arquitetural:
 
-## Estrutura do Objeto
+- É a **única fonte da verdade** para totais de pontos, badges (challenges), items, levels e demais conquistas — não há um campo `Player.points`. Todos os totais são calculados sob demanda via aggregation sobre a coleção `achievement` (vide seção 2.5).
+- Atua como **log de eventos de gamificação**: cada lançamento é uma linha; estornos são lançamentos com `total` negativo.
+- Concentra o **motor principal de avaliação de desafios** (`AchievementManager.fireAction`) — apesar do nome, é este módulo, não o módulo `challenge`, que decide se uma `action_log` recém-recebida completa algum desafio, contabiliza progresso, aplica deduções e dispara recompensas.
+- Atualiza materializações derivadas: `player_status` (snapshot de carteira por jogador) e `game_status` (totalizador de gamificação).
+
+Problemas que resolve:
+
+- Auditoria completa de tudo que cada jogador ganhou/perdeu, com timestamp e origem opcional (`extra.origin`).
+- Cálculo idempotente de totais (sempre via `$sum` de `total`), o que permite estornos com `total` negativo sem corromper o saldo.
+- Ponto único de inserção para que triggers (`before_win` / `after_win`), webhooks (`achievement_created`) e progressão de níveis sejam disparados de forma consistente independentemente da origem (desafio, compra, mystery box, ajuste manual, etc.).
+
+Relação direta com outros módulos:
+
+- `action` — toda chamada a `ActionManager.trackSynchonous(action)` invoca `AchievementManager.fireAction(action)` ao final. Esta é a porta de entrada principal.
+- `challenge` — `fireAction` lê `challenge`, avalia regras e gera achievements do tipo CHALLENGE.
+- `point_category`, `catalog_item`, `lottery`, `mystery_box`, `bonus`, `crown`, `competition`, `character_star_stats` — todos esses módulos inserem achievements via `addAchievement` ou via `fireAction`.
+- `player` — `PlayerManager.updateUserStatus(player)` recalcula `player_status` a partir da coleção `achievement`.
+- `trigger` — `before_win` / `after_win` são disparados em torno de cada `addAchievement` significativo dentro de `fireAction`.
+- `webhook` — `achievement_created` é disparado uma vez ao fim de `fireAction` com a lista completa de achievements gerados.
+- `lottery_ticket` — caso especial: `type=50 (LOTTERY_TICKET)` **não** gera registro em `achievement`; em vez disso, insere documentos na coleção `lottery_ticket`.
+
+---
+
+## 2. Arquitetura e Fluxos
+
+### 2.1 Classes envolvidas
+
+| Classe | Papel |
+|---|---|
+| `com.funifier.engine.achievement.Achievement` | Entidade/POJO principal — documento raiz |
+| `com.funifier.engine.achievement.AchievementManager` | Manager monolítico (3232 linhas): CRUD, avaliação de desafios, level-up, atualização de status, queries agregadas |
+| `com.funifier.rest.v3.rest.AchievementRest` | Controller REST v3 (`/v3/achievement`) |
+| `com.funifier.rest.engine.AchievementRest` | Controller REST legado (`/2.0.0/achievement`) |
+| `com.funifier.engine.achievement.ChallengeProgress` | Sub-entidade persistida em `challenge_progress` |
+| `com.funifier.engine.achievement.ChallengeRuleProgress` | Sub-elemento de `ChallengeProgress.rules` |
+| `com.funifier.engine.achievement.PlayerStatus` | Snapshot persistido em `player_status` |
+| `com.funifier.engine.achievement.GameStatus` | Snapshot global persistido em `game_status` |
+| `com.funifier.engine.achievement.GroupAttribute` | DTO interno de aggregation (`total`, `max`) |
+| `com.funifier.engine.achievement.GroupLog` | DTO interno legado de aggregation (`total`) |
+
+Não há `Repository`/`Dao` dedicado — a manipulação MongoDB é feita diretamente via `Jongo` dentro do `AchievementManager`.
+
+### 2.2 Pipeline principal — `fireAction(ActionLog trigger)`
+
+Comentário do código (linha 105-116 de `AchievementManager.java`) descreve as 7 etapas oficiais:
+
+```
+1. PRE CONTROLLERS  : principal, requirements
+2. FIND CHALLENGES  : action, active, when, teamchallenge
+3. EVALUATE PLAYER  : player, principals, level, limit, requirements
+4. EVALUATE RULES   : rules, every, filters, (simplify ignore operators)
+5. REGISTER REWARDS : achievement, points, itens, requirements (deductions)
+6. UPDATE STATUS    : challenge_progress, level_up, player_status
+7. POS PROCESS      : notifications, trigger_url
+```
+
+Detalhamento numerado conforme o código real:
+
+```
+[1] Resolve principal (jogador OU time) por userId / teamId em `principal`.
+    Se principal não existir → sai e retorna lista vazia. (linhas 122-129)
+
+[2] Se principal é PLAYER e a Action tem RewardPoints configurados:
+    [2.1] Para cada RewardPoint:
+          - operation = NONE        → totalPoints = p.total
+          - operation = MULTIPLY_BY_ATTRIBUTE → totalPoints = p.total * trigger.attributes[p.value]
+          - operation = DIVIDE_BY_ATTRIBUTE   → totalPoints = p.total / trigger.attributes[p.value]
+          - ATENÇÃO: parsing de atributo silencioso — exceção é engolida (linhas 162-176)
+    [2.2] Se totalPoints != 0:
+          - trigger.execute(point_category, item, BEFORE_WIN)
+          - addAchievement (TYPE_POINT)
+          - trigger.execute(point_category, item, AFTER_WIN)
+    [2.3] Dispara NotificationDefinition.EVENT_WIN das notifications da Action
+
+[3] FIND CHALLENGES (findValidChallenges):
+    db.challenge.find({ active: true, rules: { $elemMatch: { actionId: # } } })
+    Filtra por `Challenge.when.isDateAllowed(...)` em memória (não em query).
+    Conversão de timezone considera Security.getTimeZone() do tenant.
+
+[4] EVALUATE PRINCIPAL (evaluatePrincipal):
+    Para cada challenge:
+      [4.1] teamChallenge match (player vs team)         ← evaluateLimit + isUserChallengePrincipal
+      [4.2] limit (LIMIT_PER_PLAYER/TEAM/GAME)
+      [4.3] principals contém player/time ?
+      [4.4] requirements (sumTotalRewards >= r.total para cada Requirement do Challenge)
+      [4.5] join obrigatório? (challenge.join.required → JoinLog existente E em timeframe)
+    Reprovados são removidos silenciosamente.
+
+[5] EVALUATE RULES — para cada challenge aprovado:
+    Para cada rule do challenge:
+      - rule_total computado: literal numérico, ou expressão Mustache+exp4j com {player, team, rule, challenge}
+      - tipo de regra (getRuleType):
+          RULE_TYPE_EVERY (2): everyAmount > 0 && everyScale != NONE && timeAmount > 0
+          RULE_TYPE_SEVERAL (1): rule_total > 1 && everyScale == NONE
+          RULE_TYPE_ONE   (0): caso restante
+      - se rule.prepared está setado → carrega ChallengeRulePrepared e injeta entity/aggregate
+      - se rule.entity + rule.aggregate → executa aggregation customizada substituindo:
+          FUNIFIER_PLAYER_IDS, FUNIFIER_TRIGGER_TIME, FUNIFIER_TRIGGER_ACTION_ID,
+          FUNIFIER_RULE_ACTION_ID, FUNIFIER_PERIOD_START_TIME, FUNIFIER_PERIOD_END_TIME
+      - senão usa o caminho countActionLogsRegisteredBetweenDatesV3 ou
+        checkActionLogsFrequencyRegisteredBetweenDates conforme o tipo.
+
+[6] AVALIAÇÃO DE COMPLETUDE (linhas 425-453):
+    - RANGE_ALL (0)          → _true == rules.length
+    - RANGE_ANY (1)          → _true > 0
+    - RANGE_ALL_IN_ORDER (2) → _true == rules.length E orderTime[i] <= orderTime[i+1]
+    Se ordem quebra: marca todas rules >= i como uncompletedBecauseOfTime (zera percent, completed=false)
+
+[7] SE COMPLETED:
+    [7.1] deleteProgress(player, challenge)
+    [7.2] Se challenge.join.required:
+          - completeAll(joinLog)
+          - guarda extra.join = joinLog.id no achievement
+          - SE NÃO HÁ JoinLog NÃO COMPLETO → "continue" (pula este challenge inteiramente)
+    [7.3] addAchievement(TYPE_CHALLENGE, total=1) com trigger.execute(challenge, BEFORE_WIN/AFTER_WIN)
+    [7.4] REGISTER POINTS (challenge.points[]):
+          mesma lógica do passo [2.1] com perPlayer→winners para teamChallenge
+          se challenge.propagateOrigin == true → achievement.extra.origin = parent_achievement.id
+          atualiza updatePlayerStatus(winner) para CADA winner que recebe pontos
+    [7.5] REGISTER REWARDS (challenge.rewards[]):
+          Tipos suportados: TYPE_POINT, TYPE_CATALOG_ITEM, TYPE_CHALLENGE, TYPE_LOTTERY_TICKET
+          Casos especiais com item == "FUNIFIER_RANDOM":
+            - CATALOG_ITEM: catalogManager.findValidRandom(...) ou findRandom — filtra por r.folder
+            - LOTTERY_TICKET: lotteryManager.findValidRandom(...) e cria N tickets em loop
+          Caso item específico tipo LOTTERY_TICKET: cria N LotteryTickets, NÃO cria Achievement
+          Trigger collection é resolvida por type (point_category, challenge, catalog_item)
+          updatePlayerStatus(winner) é chamado APÓS cada reward
+    [7.6] REGISTER NOTIFICATIONS de NotificationDefinition.EVENT_WIN do challenge
+    [7.7] DEDUCT REQUIREMENTS (deductRequirements):
+          Para cada Requirement do Challenge com operation=DEDUCT e tipo válido:
+          insere achievement com total = -|r.total| (deduz)
+          a.extra.origin = challenge_achievement.id (se propagateOrigin)
+
+[8] SE NÃO COMPLETED MAS (rules.length==1 || _true>0 || challenge.trackFullProgress):
+    deleteProgress + addProgress com percent_completed calculado
+    progress só é salvo se percent_completed > 0 OU trackFullProgress
+
+[9] UPDATE PLAYER STATUS (se algum challenge foi avaliado, evaluated=true):
+    Se principal é PLAYER → updatePlayerStatus(userId)
+    Se principal é TEAM   → TODO (sem implementação) ← marcador no código
+
+[10] AVALIAÇÃO RECURSIVA DE TIME:
+    Se principal é PLAYER, busca times do jogador e re-invoca fireAction(new ActionLog(actionId, teamId, time, attributes))
+    Isto causa segunda passagem com principal=TEAM, avaliando challenges com teamChallenge=true.
+
+[11] WEBHOOK:
+    Se result.size() > 0 → WebhookManager.execute("achievement_created", result)
+```
+
+### Fluxo de avaliação — `fireAction`
+
+```mermaid
+flowchart TB
+    A[ActionLog trigger] --> B{Principal existe?}
+    B -- não --> Z[Retorna lista vazia]
+    B -- player --> C[Reward points da Action]
+    B -- team --> D[Pula reward points individuais]
+    C --> E[findValidChallenges]
+    D --> E
+    E --> F[evaluatePrincipal: limit, principals, requirements, join]
+    F --> G[Loop rules: countActionLogs / aggregate / frequency]
+    G --> H{Completed?}
+    H -- sim --> I[deleteProgress + addAchievement CHALLENGE]
+    H -- não --> J{trackFullProgress OR _true>0 OR 1 rule?}
+    I --> K[Distribui pontos + rewards + tickets]
+    K --> L[deductRequirements]
+    J -- sim --> M[addProgress challenge_progress]
+    J -- não --> N[Nenhum progress salvo]
+    L --> O[updatePlayerStatus]
+    M --> O
+    N --> O
+    O --> P{Principal é player?}
+    P -- sim --> Q[Loop teams do player → fireAction recursivo]
+    P -- não --> R[Skip recursão]
+    Q --> S[Webhook achievement_created]
+    R --> S
+```
+
+### 2.3 Pipeline — `addAchievement(Achievement)` (POST direto)
+
+Caminho usado pelo endpoint REST `POST /v3/achievement` e também internamente como ajuste manual de saldo:
+
+```
+[1] Se achievement.id == null → Guid.newShortGuid()      (SHORT GUID, NÃO ObjectId Mongo)
+[2] Se achievement.time == null → new Date()             (hora do servidor)
+[3] jongo.getCollection("achievement").save(achievement) (upsert por _id)
+[4] (chamado pelo Rest, NÃO pelo Manager): updateUserStatus(achievement.player)
+```
+
+**Importante:** `POST /v3/achievement` **não dispara**:
+
+- Triggers (`before_win`/`after_win`) — só são disparados quando `addAchievement` é chamado de dentro do `fireAction` ou de cálculos derivados (purchase, mystery box, etc.).
+- Webhooks (`achievement_created`) — só dentro do `fireAction`.
+- Avaliação de level-up (exceto via `updateUserStatus` que internamente roda `evaluateLevelUp` em loop).
+
+### 2.4 Pipeline — `updatePlayerStatus(player)`
+
+Atualização materializada de `player_status` (coleção `player_status`):
+
+```
+[1] Busca Player.findById(player)
+[2] Loop while(evaluateLevelUp(player, achievements)):
+    - busca level corrente (último Achievement TYPE_LEVEL ordenado por time DESC)
+    - busca próximo level por position
+    - lê LevelConfig {_id:"global"}.pointCategory para decidir categoria de pontos
+    - calcula points = sumTotalRewards(player, TYPE_POINT, pointCategory)
+    - se points >= nextLevel.minPoints E evaluateRequirements(nextLevel.requirements):
+        addAchievement(TYPE_LEVEL) + trigger BEFORE_WIN/AFTER_WIN em ENTITY_LEVEL
+        envia notificações EVENT_WIN do level
+        retorna true → loop continua (permite múltiplos levels em sequência)
+[3] Calcula totais por tipo via aggregation:
+    - total_challenges, challenges{}    via sumTotalRewards/getTotalRewardsGroupedByType (TYPE_CHALLENGE)
+    - total_points, point_categories{}  via sumTotalPoints/getTotalPointsGroupedByType (TYPE_POINT)
+    - total_catalog_items, catalog_items{} via sumTotalRewards/getTotalRewardsGroupedByType (TYPE_CATALOG_ITEM)
+[4] Monta LevelProgress com percent_completed calculado entre level atual e próximo
+[5] Carrega challenge_progress (lista filtrada por player de challenge_progress)
+[6] Copia p.teams, p.friends
+[7] Carrega positions (leaderboards) via CrowningManager.findLeadersByPlayerId
+[8] Salva: c.remove("{_id:#}") + c.save(status)   ← DELETE + INSERT, não upsert
+```
+
+### 2.5 Sumarização de saldos — `sumTotalRewards` (cálculo central)
+
+Todo "saldo" do jogador é calculado via aggregation sobre `achievement`:
+
+```js
+// sumTotalRewards(player, type, item)
+db.achievement.aggregate([
+  { $match: { player: <player>, type: <type>, item: <item> } },
+  { $group: { _id: "$item", total: { $sum: "$total" } } }
+])
+```
+
+```js
+// sumTotalPoints(player) — equivalente para TYPE_POINT
+db.achievement.aggregate([
+  { $match: { player: <player>, type: 0 } },
+  { $group: { _id: "$type", total: { $sum: "$total" } } }
+])
+```
+
+```js
+// getTotalRewardsGroupedByType — retorna mapa item→total
+db.achievement.aggregate([
+  { $match: { player: <player>, type: <type> } },
+  { $group: { _id: "$item", total: { $sum: "$total" } } }
+])
+```
+
+Consequências práticas:
+
+- Lançamentos com `total` negativo subtraem do saldo (mecanismo de estorno / dedução).
+- Não há "snapshot" de saldo armazenado no `Player`. Performance de leitura depende de índices em `{player:1, type:1, item:1}` (não documentados no código).
+
+### 2.6 Interações entre módulos (vista de chamadas)
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant ActionRest
+    participant ActionManager
+    participant AchievementManager
+    participant ChallengeColl as challenge<br/>(MongoDB)
+    participant Trigger
+    participant Webhook
+
+    Client->>ActionRest: POST /v3/action/log
+    ActionRest->>ActionManager: trackSynchonous(action)
+    ActionManager->>ActionManager: addLog(action)
+    ActionManager->>AchievementManager: fireAction(action)
+    AchievementManager->>ChallengeColl: find({active:true, rules.actionId})
+    AchievementManager->>Trigger: BEFORE_WIN (point_category)
+    AchievementManager->>AchievementManager: addAchievement(POINT)
+    AchievementManager->>Trigger: AFTER_WIN (point_category)
+    loop para cada challenge completado
+        AchievementManager->>AchievementManager: addAchievement(CHALLENGE)
+        AchievementManager->>AchievementManager: addAchievement(POINT/CATALOG_ITEM/...)
+        AchievementManager->>AchievementManager: deductRequirements
+    end
+    AchievementManager->>AchievementManager: updatePlayerStatus (loop evaluateLevelUp)
+    AchievementManager->>AchievementManager: fireAction recursivo para cada team
+    AchievementManager->>Webhook: execute("achievement_created", result)
+    ActionManager-->>Client: 200 + lista de Achievements
+```
+
+Outros pontos de entrada (chamadores de `addAchievement` fora do `fireAction`):
+
+| Origem | Quando dispara |
+|---|---|
+| `PurchaseManager.buy` | Compra de catalog item — dedução de pontos + ganho de CATALOG_ITEM |
+| `LotteryManager.execute` | Ganhador de loteria — TYPE_LOTTERY com prêmio |
+| `MysteryBoxManager.execute` | Mystery box aberto — TYPE_MYSTERY_BOX + recompensas (PrizesType) |
+| `LostManager.execute` | Perda de itens — total negativo (estorno) |
+| `CrowningManager.calculateCrown` | Coroamento de leaderboard — TYPE_CROWN |
+| `CharacterStarManager.evaluateLevelUp` | Subiu nível de Character Star — TYPE_CHARACTER_STAR_STAT |
+| `BetManager.execute` / `purchase` / `delete` / `undoExecute` | Apostas — múltiplos tipos com origem propagada |
+| `SwapManager.*` | Troca entre players — pares de achievements (positivo/negativo) |
+
+---
+
+## 3. Estrutura dos Objetos
+
+### 3.1 `Achievement` — documento raiz (coleção `achievement`)
+
+| Campo | Tipo | Padrão | Obrigatório | Descrição |
+|---|---|---|---|---|
+| `_id` | String | `Guid.newShortGuid()` se ausente | Não (auto) | Identificador SHORT GUID interno do Funifier. **Não é** ObjectId do Mongo |
+| `player` | String | — | **Sim** | Identificador do jogador OU time que recebeu/perdeu a conquista |
+| `total` | double | — | Sim (significativo) | Quantidade da conquista. Pode ser **negativo** (estorno/dedução). `total == 0` faz o registro ser ignorado em alguns fluxos internos |
+| `type` | int | — | Sim | Tipo de conquista (ver enum abaixo) |
+| `item` | String | — | Não em runtime | Identificador do item conquistado (ex: id de point_category, challenge, level…). Para `TYPE_POINT` é o id da category |
+| `time` | Date | `new Date()` se ausente em `addAchievement(Achievement)` (a sobrecarga com 1 arg) | Não (auto) | Timestamp do evento. Sempre serializado pelo Jackson como número (epoch ms) na resposta JSON |
+| `extra` | Map<String,Object> | — | Não | Atributos arbitrários do achievement. Convenções de uso conhecidas: `origin` (id do achievement pai quando `challenge.propagateOrigin=true`), `origin_item`, `origin_type`, `join` (id do JoinLog completado) |
+
+Anotação Jackson na classe: `@JsonIgnoreProperties(ignoreUnknown=true)` — campos extras enviados no POST são **silenciosamente descartados** se não estiverem mapeados acima.
+
+Construtor com 6 args (`id, player, total, type, item, time`) **não** popula `extra` — `extra` é setado depois via mutação direta.
+
+#### Campos computados / não persistidos
+
+Nenhum — todos os campos da entidade `Achievement` são persistidos.
+
+#### Campos removidos silenciosamente
+
+Nenhum no `Achievement`. Porém: a sobrecarga `addAchievement(Achievement)` (sem Jongo) preenche `time = new Date()` se vier `null`, **substituindo** silenciosamente o valor do cliente quando ele envia `time: null` (mas mantém se enviar uma data inválida que o Jackson interprete como null).
+
+#### Constantes legadas comentadas no código
+
+```java
+//public static final int TYPE_ACTION = 100;  // linha 31 — declarado/removido
+```
+
+A constante `TYPE_ACTION = 100` está comentada na entidade — não existe em runtime. Documentos persistidos com `type: 100` são tecnicamente possíveis (o campo é `int`, sem validação de enum), mas nenhum código produzirá ou consumirá esse valor.
+
+### 3.2 Tabela completa de `type` (Achievement.TYPE_*)
+
+| Valor | Constante Java | Significado operacional | Onde é gerado |
+|---|---|---|---|
+| `0` | `TYPE_POINT` | Ponto ganho em uma `point_category` específica. `item` = id da category | `fireAction` (action.points + challenge.points + challenge.rewards); `PurchaseManager`; `LostManager` |
+| `1` | `TYPE_CHALLENGE` | Desafio completado. `item` = id do challenge. `total` é sempre 1 nos fluxos automáticos | `fireAction` (challenge completo) |
+| `2` | `TYPE_CATALOG_ITEM` | Item de catálogo adquirido. `item` = id do catalog_item | `PurchaseManager.buy`; `fireAction` (challenge.rewards) |
+| `3` | `TYPE_LEVEL` | Level atingido. `item` = id do level. `total` = 1 | `evaluateLevelUp` (chamado dentro de `updatePlayerStatus`) |
+| `4` | `TYPE_CROWN` | Coroamento obtido em leaderboard. `item` = id do crown | `CrowningManager.calculateCrown` |
+| `5` | `TYPE_LOTTERY` | Vencedor de loteria. `item` = id da loteria | `LotteryManager.execute` |
+| `6` | `TYPE_MYSTERY_BOX` | Mystery box aberta. `item` = id do mystery_box | `MysteryBoxManager.execute` |
+| `7` | `TYPE_CHARACTER_STAR_STAT` | Subiu nível de Character Star. `item` = id do level | `CharacterStarManager.evaluateLevelUp` |
+| `8` | `TYPE_BONUS` | Bônus recebido (Last Mile). `item` = id do bonus | `BonusManager` |
+| `9` | `TYPE_COMPETITION` | Conquista de competição. `item` = id da competição | `CompetitionManager` |
+| `99` | `TYPE_CUSTOM` | Tipo customizado / livre. Sem semântica do core. Pode ser usado para integrações | Exclusivamente externo (`POST /v3/achievement`) |
+| `50` | `TYPE_LOTTERY_TICKET` | **NÃO É REGISTRADO COMO ACHIEVEMENT.** Comentário do código (linha 29): *"nao e registrado como achievement, fica em uma colecao a parte lottery_ticket"*. Aparece em `Requirement.type` e em `findOptionsByType` mas o `fireAction` insere documentos em `lottery_ticket` em vez disso | Convenção interna em `Requirement` |
+
+### 3.3 `ChallengeProgress` — sub-entidade (coleção `challenge_progress`)
+
+Persiste o **progresso parcial** de um jogador em um desafio não-completo.
+
+| Campo | Tipo | Padrão | Obrigatório | Descrição |
+|---|---|---|---|---|
+| `_id` | String | `Guid.newShortGuid()` em `addProgress` | Não (auto) | Identificador |
+| `player` | String | — | Sim | Jogador (ou time) que está progredindo |
+| `challenge` | String | — | Sim | Id do challenge |
+| `name` | String | — | Não | Cópia do `challenge.challenge` (nome) |
+| `image` | Image | — | Não | Cópia de `challenge.badgeUrl` no momento do progresso (snapshot) |
+| `rules_completed` | int | 0 | — | Quantas rules estão completas |
+| `rules_total` | int | 0 | — | Total de rules do challenge |
+| `percent_completed` | double | 0 | — | Calculado em `calculatePercentCompleted()` (ver pseudocódigo abaixo) |
+| `time` | Date | — | — | Hora do trigger que produziu este progresso |
+| `rules` | List<ChallengeRuleProgress> | `[]` | — | Detalhe por rule |
+
+Cálculo de `percent_completed`:
+
+```
+se rules_total == 1 E rules_completed == 0:
+    percent_completed = rules[0].percent_completed
+senão:
+    percent_completed = (rules_completed/rules_total)*100   (limitado a 100)
+```
+
+Comportamentos importantes:
+
+- A cada `fireAction` que avalia este (player, challenge): primeiro chama `deleteProgress(player, challenge)` para garantir 1 documento por par. **Não há histórico de progresso.**
+- Só é salvo se `percent_completed > 0` OU `challenge.trackFullProgress == true`.
+- Quando o desafio é completado, o progresso é apagado (não preservado como "100%").
+
+### 3.4 `ChallengeRuleProgress` — sub-elemento de `ChallengeProgress.rules`
+
+| Campo | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `rule` | String | — | Id da rule (corresponde a `ChallengeRule.id`) |
+| `completed` | boolean | false | Se a rule foi cumprida nesta avaliação |
+| `times_completed` | long | 0 | Quantas vezes a action foi feita |
+| `times_required` | long | 0 | Quantas vezes era necessária |
+| `percent_completed` | double | 0 | `(times_completed/times_required)*100`, limitado a 100. `NaN` → 0 |
+
+Método `setUncompletedBecauseOfTime()`: chamado quando rules em ordem (`RANGE_ALL_IN_ORDER`) são quebradas. Zera tudo: `completed=false`, `times_completed=0`, `percent_completed=0`.
+
+#### Campos legados comentados (linhas 5-10 e 47-53)
+
+```java
+//String rule;
+//long times;
+//long every_times;
+//boolean completed;
+```
+
+```java
+//public ChallengeRuleProgress(String rule, long times, long every_times, boolean completed)
+```
+
+Esses campos da versão antiga (`times`, `every_times`) não existem mais — registros antigos em `challenge_progress` podem ter esses campos no Mongo mas não são lidos pelo código atual.
+
+### 3.5 `PlayerStatus` — snapshot (coleção `player_status`)
+
+Materialização de leitura de tudo do jogador. **Persistido em `player_status`, não em `player`.**
+
+| Campo | Tipo | Descrição |
+|---|---|---|
+| `_id` | String | Mapeado de `player` (id do jogador OU time) |
+| `name` | String | Nome do jogador no momento do snapshot |
+| `image` | Image | Imagem do jogador no momento do snapshot |
+| `total_challenges` | long | `sumTotalRewards(player, TYPE_CHALLENGE)` |
+| `challenges` | Map<String,Long> | itemId → soma; via `getTotalRewardsGroupedByType` |
+| `total_points` | double | `sumTotalPoints(player)` |
+| `point_categories` | Map<String,Double> | categoryId → soma de pontos |
+| `total_catalog_items` | long | `sumTotalRewards(player, TYPE_CATALOG_ITEM)` |
+| `catalog_items` | Map<String,Long> | catalogItemId → quantidade |
+| `level_progress` | LevelProgress | `{level, percent, next_level, next_points, total_levels}` |
+| `challenge_progress` | List<ChallengeProgress> | Cópia dos documentos de `challenge_progress` do jogador |
+| `teams` | List<String> | `Player.teams` |
+| `friends` | List<String> | `Player.friends` |
+| `positions` | List<Leader> | Posições nos leaderboards (via `CrowningManager.findLeadersByPlayerId`) |
+| `time` | Date | Hora do snapshot |
+| `attributes` | Object | Reservado — não populado no código atual (comentários antigos referenciam mas a atribuição está comentada) |
+| `extra` | Map<String,Object> | Copia de `Player.extra` |
+
+Comportamento de save em `updatePlayerStatus`:
+
+```
+c.remove("{_id:#}", player);   // remove antes
+c.save(status);                // insere depois
+```
+
+**Não é upsert**. Existe uma janela curta entre o `remove` e o `save` em que o documento não existe — leituras concorrentes podem retornar `null`.
+
+Quando chamado para um time (`calculateTeamStatus`): retorna o objeto **sem persistir** (não salva em `player_status`) — o método é só de leitura projetada.
+
+### 3.6 `GameStatus` — snapshot global (coleção `game_status`)
+
+| Campo | Tipo | Descrição |
+|---|---|---|
+| `_id` | String | Mapeado para `api_key` do tenant |
+| `total_players` | long | `db.player_status.count()` |
+| `total_players_by_achievement_item` | Map<String,Long> | Para cada `item` distinto, conta quantos players distintos receberam — via aggregation sobre `achievement` (excluindo player ids que sejam ids de teams) |
+
+Comportamento: cache lazy. `findGameStatus()` retorna o documento se existir; senão chama `updateGameStatus(jongo)` que salva. **Não há invalidação automática** — o `game_status` só é atualizado nas chamadas manuais a `updateGameStatus` ou na primeira leitura após `deleteGameStatus`. No `fireAction`, as chamadas a `updateGameStatus` e `deleteGameStatus` estão **comentadas** (linhas 811-812):
+
+```java
+//updateGameStatus(jongo);
+//deleteGameStatus(jongo);
+```
+
+Consequência: **`game_status` fica desatualizado em produção** até alguém invocar `deleteGameStatus` + `findGameStatus` manualmente.
+
+### 3.7 `GroupAttribute` / `GroupLog` — DTOs de aggregation interna
+
+Não são entidades persistidas — apenas mapeamento de resultados de aggregations.
+
+- `GroupAttribute { long total; Date max; }` — usado por `countWithAggregateRegisteredBetweenDatesV3` e `checkActionLogsFrequencyRegisteredBetweenDates`
+- `GroupLog { int total; }` — usado pelo método legado `checkActionLogsFrequencyRegisteredBetweenDatesOLD`
+
+---
+
+## 4. Endpoints
+
+### 4.1 `GET /v3/achievement`
+
+**Listar conquistas paginadas.**
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Buscar achievements filtrados |
+| Autenticação | Bearer token |
+| Paginação | Header `Range: items=0-100` (zero-based, inclusivo) |
+
+**Query params:**
+
+| Param | Tipo | Descrição |
+|---|---|---|
+| `player` | String | Filtro por jogador. **Valor especial `me`** → resolve para `authBean.getPlayerFromTokenIfExist()` |
+| `type` | int | Filtro por tipo. **ATENÇÃO**: o código aplica filtro apenas se `type > 0` (linha 1246, 1305) — **não é possível filtrar por `type=0` (POINT)** via este endpoint |
+| `item` | String | Filtro por item |
+| `q` | String | Critério MongoDB raw (injetado no `$match`) — vide seção 8 |
+| `fields` | CSV String | Projeção: `field1,field2,...` |
+| `published_min` | String | RFC 3339 OU keyword (`-1d`, `-30m`…). Mapeia para `time >= X` |
+| `published_max` | String | Idem, mapeia para `time <= X` |
+| `orderby` | String | Campo de ordenação (player, total, type, item, time) |
+| `reverse` | bool | true = desc, false = asc |
+| `max_results` | int | Limite (default 100; valores ≤ 0 são tratados como 100) |
+
+**Comportamento real:**
+
+- Sempre injeta `player: {$exists:true}` no `$match` — documentos sem `player` (corrompidos) nunca aparecem.
+- `q` é concatenado **literalmente** com prefixo `, ` no `$match`: `{ player: {$exists:true}, q-aqui }` — injeção de pipeline MongoDB; vide seção 8.
+- Resposta segue formato `paginatedCallback` (header `Content-Range` + body com lista).
+
+**Exemplo:**
+
+```
+GET /v3/achievement?type=1&player=me&orderby=time&reverse=true&max_results=10
+Authorization: Bearer eyJhbGciOi...
+Range: items=0-9
+```
+
+**Response (200):**
+
+```json
+[
+  {
+    "_id": "62c0a91c8b00",
+    "player": "joao@empresa.com",
+    "total": 1.0,
+    "type": 1,
+    "item": "challenge_first_login",
+    "time": 1685011053000
+  }
+]
+```
+
+### 4.2 `GET /v3/achievement/frequency`
+
+**Conquistas agrupadas por janela de tempo.**
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Curva de frequência de conquistas |
+| Autenticação | Bearer token |
+
+**Query params:**
+
+| Param | Tipo | Descrição |
+|---|---|---|
+| `player` | String | (suporta `me`) |
+| `type` | int | Filtro de tipo (mesmo bug do `type=0` se aplica) |
+| `item` | String | Filtro de item |
+| `q` | String | Critério Mongo raw |
+| `published_min` / `published_max` | String | RFC 3339 ou keyword |
+| `every` | String | **Obrigatório** se quiser agrupamento. Formato `<n><unit>` onde unit ∈ `y, M, d, h, m, s, w`. Ex: `1d`, `3M` |
+| `time_zone` | String | Timezone IANA (ex: `America/Sao_Paulo`). Aplica offset ao `time` antes de agrupar |
+| `sum_field` | String | Se preenchido, soma este campo em vez de `$sum: 1` |
+
+**Comportamento real:**
+
+- `every` é parseado: último caractere = unit, restante = amount. Parse pode lançar `NumberFormatException` se o formato for inválido — **não há tratamento** no método.
+- Cada combinação de `everyAmount + everyScale` gera uma estratégia distinta de `$project` + `$group` (vide linhas 3096-3181 com switch de TimeScale).
+- Resposta: lista de HashMaps com `_id` (chave composta de date parts) + `total` (ou `total` somando `sum_field`) + `start`/`end` (min/max do bucket).
+
+### 4.3 `POST /v3/achievement/aggregate`
+
+**Aggregation pipeline customizado sobre `achievement`.**
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Permitir queries arbitrárias via Mongo Aggregation Framework |
+| Autenticação | Bearer token |
+| Body | `List<String>` — cada string é um estágio JSON do pipeline |
+
+**Query params:**
+
+| Param | Tipo | Descrição |
+|---|---|---|
+| `player` | String | Filtro |
+| `team` | String | Filtro: resolve para `player: {$in: <playersDoTeam>}` via lookup em `team_player.linkId` |
+| `type` | String | Filtro (parse silencioso — exceção engolida) |
+| `item` | String | Filtro |
+| `q` | String | Critério raw injetado |
+| `published_min` / `published_max` | String | Datas |
+
+**Comportamento real:**
+
+- Os estágios do body são concatenados **após** o `$match` inicial (que inclui `player: {$exists:true}` + filtros derivados de query params).
+- Bug-bait: o filtro `team` é aplicado **antes** dos estágios do body — se o time não tem jogadores em `team_player`, a query roda **sem o `$in`** (o filtro é omitido quando `players.size() == 0`), retornando dados do tenant inteiro.
+
+### 4.4 `POST /v3/achievement`
+
+**Criar achievement (ajuste manual).**
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Inserção direta de Achievement (não dispara fireAction) |
+| Autenticação | Bearer token |
+| Persistência | `c.save(achievement)` — upsert por `_id` |
+
+**Body:** objeto `Achievement` (campos da seção 3.1).
+
+**Comportamento real:**
+
+- Se `_id` é null/ausente → gera novo `Guid.newShortGuid()`.
+- Se `time` é null → o construtor de 6 args **não** atribui automaticamente; só a sobrecarga `addAchievement(Achievement)` sem Jongo atribui `new Date()`. **No fluxo do REST**, o caminho usado é o `manager.getAchievementManager().addAchievement(achievement)` (a sobrecarga com 1 arg), portanto `time` ausente vira `now`.
+- **Sempre** chama `playerManager.updateUserStatus(achievement.player)` ao final — isto dispara `evaluateLevelUp` em loop. Inserir um achievement de pontos pode causar level-ups em cascata.
+- **Não dispara** triggers `before_win`/`after_win`.
+- **Não dispara** webhook `achievement_created`.
+- **Não valida** `type` contra os enums conhecidos — aceita qualquer `int`.
+- **Não valida** existência de `item` referenciado.
+
+**Exemplo:**
+
+```json
+POST /v3/achievement
+Content-Type: application/json
+Authorization: Bearer ...
+{
+  "player": "joao@empresa.com",
+  "total": 100,
+  "type": 0,
+  "item": "5fa2c7e1b8c00012345abcde"
+}
+```
+
+### 4.5 `POST /v3/achievement/bulk`
+
+**Inserção em lote.**
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Importação em massa de achievements |
+| Autenticação | Bearer token |
+
+**Body:** `List<Achievement>`.
+
+**Comportamento real:**
+
+- Loop simples: para cada item da lista, chama `addAchievement(item)`.
+- **NÃO chama `updateUserStatus` por item** (`manager.getPlayerManager().updateUserStatus(achievement.player)` está comentado no código, linha 294) — `player_status` fica defasado até o próximo trigger natural.
+- Status response: `201 Created` com `{ total, registered, ignored: 0, content: [...] }`. O campo `ignored` é sempre 0 — o código não tem nenhuma lógica de skip.
+- Sem rollback em caso de falha parcial.
+
+### 4.6 `DELETE /v3/achievement/{id}`
+
+**Excluir achievement.**
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Remover um achievement individual e recalcular player_status |
+| Autenticação | Bearer token |
+
+**Comportamento real:**
+
+```
+[1] a = findAchievement(id)
+[2] se a != null:
+      deleteAchievement(id)
+      updateUserStatus(a.player)
+[3] retorna 204 No Content (sempre, mesmo se não existir)
+```
+
+- Resposta 204 mesmo quando o id não existe → cliente não consegue distinguir "deletei" de "não havia nada".
+- Recalcula `player_status` após delete — saldos voltam a refletir o estado corrente.
+- Não dispara triggers `before_delete`/`after_delete` sobre `achievement` (não há entry para essa entidade no fluxo).
+
+### 4.7 `GET /v3/achievement/options/{type}`
+
+**Listar items disponíveis para um tipo.**
+
+Retorna a lista de items que podem ser usados no campo `item` para o `type` informado:
+
+| `type` | Origem da lista |
+|---|---|
+| `0` POINT | `PointManager.findAll()` |
+| `1` CHALLENGE | `ChallengeManager.findAll()` |
+| `2` CATALOG_ITEM | `CatalogManager.findAllItems()` |
+| `3` LEVEL | `LevelManager.findAll()` |
+| `4` CROWN | `CrowningManager.findAll()` |
+| `5` LOTTERY | `LotteryManager.findAll()` |
+| `6` MYSTERY_BOX | `MysteryBoxManager.findAll()` |
+| `7` CHARACTER_STAR_STAT | `CharacterStarManager.findAllLevels()` |
+| `8` BONUS | `BonusManager.findAll()` |
+| `50` LOTTERY_TICKET | `LotteryManager.findAll()` (mesma lista que 5) |
+
+Tipo desconhecido (incluindo `9 COMPETITION` e `99 CUSTOM`) → retorna lista vazia.
+
+### 4.8 `GET /v3/achievement/totalPlayersByAchievement`
+
+Retorna `GameStatus` global (cache lazy — vide 3.6).
+
+### 4.9 `POST /v3/achievement/evaluate/requirement`
+
+**Avaliar se o jogador atende a uma lista de Requirements.**
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Verificar se um jogador tem os recursos exigidos por uma lista de Requirements (pontos, items, etc.) |
+| Body | `List<Requirement>` |
+| Query | `?player=<id>` |
+
+**Comportamento real:** chama `evaluateRequirements(Requirement[], player)` — para cada requirement compara `sumTotalRewards(player, type, item, period)` com `r.total`. Se algum falha, retorna `complete: false`.
 
 ```json
 {
-  "_id": "64a5d2",
-  "player": "john",
-  "total": 25.0,
+  "complete": true,
+  "player": "joao@empresa.com"
+}
+```
+
+### 4.10 Endpoints legados `/2.0.0/achievement`
+
+| Endpoint | Comportamento |
+|---|---|
+| `GET /2.0.0/achievement` | Versão sem paginação, com auth via query params `?api_key=...` |
+| `POST /2.0.0/achievement` | Idêntico ao v3 mas exige `app_secret` válido em `securityManager.isAppAllowed(app_secret)`; sem isso retorna 401 |
+
+Estes endpoints continuam disponíveis mas usam o caminho legado (sem `Bearer token`). Não recomendados para novas integrações.
+
+---
+
+## 5. Regras de Negócio
+
+Regras presentes no código mas **não no schema** das entidades:
+
+### 5.1 `total: 0` é tratado como no-op em vários pontos
+
+```
+if (totalPoints != 0) { ... addAchievement(...) ... }
+```
+
+Nas etapas de cálculo de pontos via RewardPoint, o lançamento é silenciosamente pulado quando o cálculo resulta em zero. Em `addAchievement(Achievement)` direto, `total=0` **é persistido** sem aviso — o que pode poluir queries de leitura.
+
+### 5.2 `LOTTERY_TICKET (50)` nunca vira documento em `achievement`
+
+Mesmo quando aparece em `Requirement.type` (recompensa) o código cria documentos em `lottery_ticket` e não em `achievement`. Consultas em `achievement?type=50` sempre retornam vazio em sistemas que não receberam inserts manuais com esse tipo.
+
+### 5.3 Propagação de origem é **opt-in** por challenge
+
+`challenge.propagateOrigin == true` faz com que **todos** os achievements derivados (pontos, items, deduções) recebam `extra.origin = <id_do_achievement_de_challenge>`. Sem esse flag, achievements descendentes ficam sem rastreabilidade.
+
+### 5.4 Recursão time-after-player em `fireAction`
+
+Toda `ActionLog` de um player gera uma segunda passagem por `fireAction` por cada time em que ele está. Consequências:
+
+- Se um team challenge bater junto com um player challenge, **dois achievements de challenge** são gerados (um para o player, outro para o team).
+- Custo de CPU/IO escala linearmente com o número de teams do jogador.
+- A recursão só acontece **uma vez** — `fireAction` para `team` não recursa novamente (porque `principal.isPlayer()` é falso).
+
+### 5.5 Avaliação de level-up roda em **loop**
+
+```java
+while (evaluateLevelUp(player, jongo, achievements));
+```
+
+Um único `updatePlayerStatus` pode gerar **múltiplos** achievements de TYPE_LEVEL sequencialmente — o jogador "salta" todos os levels que seus pontos cobrem em uma única chamada. Cada level-up dispara triggers e notifica.
+
+### 5.6 `evaluateRequirements` usa `Requirement.period` (keyword)
+
+Quando o Requirement tem `period` (ex: `-30d-` ou `-1y-`), `sumTotalRewards` é restrito a esse intervalo. Sem `period`, soma desde sempre. Isto permite requirements como "ganhou X pontos nos últimos 30 dias".
+
+### 5.7 `evaluateRequirements(multiplier)` para compras de múltiplas unidades
+
+Versão com `multiplier` multiplica `r.total` pelo número de items sendo comprados (chamada por `PurchaseManager`).
+
+### 5.8 Limites por tipo (`LIMIT_PER_TEAM` é igual a `LIMIT_PER_PLAYER`)
+
+```java
+else if(challenge.getLimitPerType() == Challenge.LIMIT_PER_TEAM) {
+    total = countChallengeAchievementsByPlayer(action.getUserId(), ...);
+}
+```
+
+A query usada para `LIMIT_PER_TEAM` é **idêntica** à de `LIMIT_PER_PLAYER` — usa `action.getUserId()` (que para principal=Team é o teamId, já que `fireAction` chama recursivamente com teamId), portanto funciona por accident: o limite é por team somente porque o usuário no `Achievement` é o teamId nesse caminho. Em código de chamada manual onde se passa player diretamente, o resultado seria errado.
+
+### 5.9 Filtros de regra (`buildJsonFilter`) — geo / tipos de atributo
+
+Tipos numéricos e booleanos são convertidos para o valor literal (sem aspas) no JSON do filtro **somente** se conseguirem fazer o parse — senão ficam como string. Geolocation usa `$nearSphere` e cria o índice `2dsphere` na coleção `action_log` na primeira utilização (linhas 2103-2105).
+
+Operator `NOT_EXIST` gera `$or: [{attributes.X: false, attributes.X: {$exists:false}}]` — atenção que isto **inclui** documentos com o atributo `false`.
+
+### 5.10 ChallengeRule.prepared / entity / aggregate (avaliação customizada)
+
+Quando uma rule define `prepared` (id de `ChallengeRulePrepared`) ou `entity` + `aggregate` diretamente, a contagem da rule **não** consulta `action_log` — executa o pipeline arbitrário sobre a coleção `entity` informada (pode ser qualquer coleção do tenant). Suporta tokens:
+
+- `FUNIFIER_PLAYER_IDS` → JSON array dos ids
+- `FUNIFIER_TRIGGER_TIME` → epoch ms do trigger
+- `FUNIFIER_TRIGGER_ACTION_ID`
+- `FUNIFIER_RULE_ACTION_ID`
+- `FUNIFIER_PERIOD_START_TIME` / `FUNIFIER_PERIOD_END_TIME` (default: últimos 10 anos se não houver período)
+
+Pipeline customizado retorna `{ total, max }` — `max` é usado para ordenação em `RANGE_ALL_IN_ORDER`.
+
+### 5.11 Multi-tenant
+
+Não há campo `apiKey` no documento `achievement`. O isolamento é **inteiramente** dado pelo banco de dados — cada tenant tem sua própria connection ao Jongo (`manager.getJongoConnection()`). Documentos cross-tenant são logicamente impossíveis enquanto o roteamento de connection estiver correto.
+
+### 5.12 Ordem temporal em `RANGE_ALL_IN_ORDER`
+
+Para considerar o desafio concluído, é preciso que `orderTime[0] <= orderTime[1] <= ... <= orderTime[n-1]`. O algoritmo (linhas 437-451) **não** trata empate (`==`) explicitamente — usa `.after()` que é estrito. Duas actions com o mesmo timestamp podem invalidar a ordem ou não dependendo da ordem de iteração das rules.
+
+---
+
+## 6. Comportamentos Automáticos
+
+| Comportamento | Trigger | Impacto | Persistência |
+|---|---|---|---|
+| Atribuição de `_id` (ShortGuid) | `addAchievement` se `_id` é null | Cria id curto interno | Sim, no doc inserido |
+| Atribuição de `time = new Date()` | `addAchievement(Achievement)` (1 arg) se time é null | Override silencioso | Sim |
+| `evaluateLevelUp` em loop | `updatePlayerStatus` | Múltiplos achievements TYPE_LEVEL em cascata | Sim, um doc por level |
+| Recálculo de `player_status` | Após `POST /v3/achievement`, `DELETE`, fim de `fireAction` (se evaluated), purchase, mystery box | Substitui doc em `player_status` (remove+save) | Sim |
+| Recursão fireAction → team | Quando principal é player e tem times | Avaliação adicional de teamChallenges | Sim (achievements para team) |
+| Trigger `before_win`/`after_win` | `addAchievement` dentro de `fireAction` | Executa scripts customizados | Side effects livres |
+| Webhook `achievement_created` | Fim de `fireAction` com `result.size() > 0` | Notifica consumidores externos | Async (depende do WebhookManager) |
+| Notification `EVENT_WIN` | Action win, Challenge win, Level win | Cria documents em `notification` | Sim |
+| `deleteProgress` antes de salvar progresso | A cada avaliação de challenge | Apaga progresso anterior do par (player, challenge) | Sim |
+| Deduções de requirements (`OPERATION_DEDUCT`) | Challenge completado com `requirements` | Achievements com `total` negativo no MESMO type | Sim |
+| Update `player_status` chamado por challenge.points / challenge.rewards | Dentro do loop de winners em fireAction | Pode ser chamado **N vezes** por challenge (1 por winner por reward), gerando overhead | Sim |
+| Update `game_status` | **Não acontece automaticamente** (chamadas comentadas) | `game_status` fica defasado | Stale by design |
+| Criação de índice `2dsphere` em `action_log` | Primeiro filtro `MAX_DISTANCE_IN_METERS` em qualquer challenge | `action_log` ganha índice global | Sim, persistente |
+
+### Fluxo de cascata após challenge completado
+
+```mermaid
+flowchart TB
+    Done[Challenge completed]
+    Done --> P[deleteProgress player+challenge]
+    P --> J{join.required?}
+    J -- sim --> Jc[completeAll JoinLog]
+    J -- não --> Sk[skip join]
+    Jc --> A[addAchievement TYPE_CHALLENGE]
+    Sk --> A
+    A --> Pts[Loop challenge.points → achievement TYPE_POINT por winner]
+    Pts --> Rw[Loop challenge.rewards → achievement por type+winner]
+    Rw --> Lt[Loop lottery_ticket → insertTicket por unidade]
+    Lt --> Nt[Notifications EVENT_WIN]
+    Nt --> Dd[deductRequirements → achievements negativos]
+    Dd --> Up[updatePlayerStatus por winner]
+    Up --> Lev[Loop evaluateLevelUp → achievements TYPE_LEVEL extra]
+```
+
+---
+
+## 7. Suportado vs NÃO Suportado
+
+### ✅ Suportado
+
+- CRUD básico via `/v3/achievement` (GET list, POST single, POST bulk, DELETE by id)
+- Aggregation customizado via `POST /v3/achievement/aggregate`
+- Frequência temporal via `GET /v3/achievement/frequency`
+- Filtro por player com valor especial `me` (auto-resolve via token)
+- Filtros de data com keywords (`-1d`, `-30m`, etc.)
+- Tipos enumerados 0..9 + 99 (custom)
+- Recompensas paralelas para todos os membros de um time (`perPlayer: true`)
+- Recompensas aleatórias em catálogo (`item: "FUNIFIER_RANDOM"`) e em loteria
+- Avaliação de challenge com aggregation customizada (`rule.entity` + `rule.aggregate` + tokens FUNIFIER_*)
+- Progressão parcial de challenge (`challenge_progress`)
+- Level-up automático em cascata (múltiplos levels em uma ação)
+- Propagação de origem entre achievements (`challenge.propagateOrigin`)
+- Estorno via lançamento negativo (mesmo type/item, total negativo)
+- Multi-tenant via roteamento de connection por `api_key`
+- Webhook `achievement_created` em todas as gerações dentro de `fireAction`
+- Triggers `before_win` / `after_win` em pontos críticos da avaliação
+
+### ❌ NÃO Suportado
+
+- **Filtro por `type=0` (POINT) em `GET /v3/achievement`** — o código aplica filtro apenas se `type > 0` (linhas 1246, 1305). Para listar pontos é preciso passar `type=0` via `q` (ex: `q=type:0`).
+- **Atualização (`PUT`)** — não há endpoint de update. Para "corrigir" um achievement é preciso DELETE + POST.
+- **Triggers em `POST /v3/achievement` direto** — apenas o caminho via `fireAction` dispara triggers. Insert manual não.
+- **Webhook em `POST /v3/achievement` direto** — idem.
+- **Atualização incremental de `player_status`** — sempre é DELETE + INSERT no `player_status`.
+- **Atualização automática de `game_status`** — as chamadas a `updateGameStatus`/`deleteGameStatus` em `fireAction` estão comentadas. Stale by design.
+- **Cálculo de `team_status` persistente** — `calculateTeamStatus` retorna em memória, não persiste. Não há materialização equivalente a `player_status` para times.
+- **Atomicidade entre lançamentos relacionados** — `addAchievement` + `updatePlayerStatus` não são transacionais. Crash entre eles deixa estado inconsistente até o próximo `updateUserStatus`.
+- **Rollback de bulk insert** — `POST /v3/achievement/bulk` insere item por item; falha parcial deixa dados parciais persistidos.
+- **`updateUserStatus` no bulk** — chamada está comentada (linha 294); `player_status` defasa após bulk até próximo evento.
+- **Validação de `type`** — qualquer `int` é aceito, inclusive valores fora do enum oficial.
+- **Validação de `item` existir** — não há verificação. `item: "naoexiste"` é persistido como string opaca.
+- **Validação de `player` existir** — não há verificação. Achievements para player inexistente são aceitos e nunca contabilizados em status (porque `updateUserStatus` lê via `findById` que retorna null).
+- **`TYPE_ACTION = 100`** — constante comentada no código fonte (linha 31 de `Achievement.java`). Não existe em runtime.
+- **Triggers `before_create`/`after_create`** sobre a entidade `achievement` — só existe `before_win`/`after_win` para os items relacionados (point_category, challenge, catalog_item, level, etc.).
+- **`TYPE_COMPETITION (9)` em `findOptionsByType`** — apesar do enum existir, o switch não tem case para `TYPE_COMPETITION` — retorna lista vazia.
+- **Filtros geo (`MAX_DISTANCE_IN_METERS`) sobre `achievement`** — só sobre `action_log` via `buildJsonFilter` de challenges.
+- **Distinguir 200 vs 404 em DELETE** — sempre retorna 204.
+- **`evaluateRequirements` levando em conta período no helper público** — apenas a sobrecarga interna usa `Requirement.period`; o público `evaluateRequirements(Requirement[], player)` usa o período igualmente (chama a versão com `Jongo`).
+- **Histórico de `challenge_progress`** — cada avaliação apaga o progresso anterior. Não há trilha de versões.
+- **`game_status` por tenant múltiplo** — `findOne()` sem filtro: assume 1 documento por banco.
+- **Bulk endpoint não suporta async** — diferente do `/v3/database/bulk`, este é sempre síncrono.
+- **`TYPE_LOTTERY_TICKET` registrado como achievement** — apesar da constante existir (50), nunca produz documento em `achievement` (vide 5.2).
+
+### Comportamentos confusos / legado relevante
+
+- `findValidChallengesOLD` (linhas 2248-2343): query MongoDB gigante deprecada com `when.*` aninhado. **Não é chamada por nenhum caminho ativo**. Mantida para referência.
+- `buildJsonFilterOLD` (linhas 2131-2192): versão anterior do filtro, ainda no arquivo. Não invocada.
+- `checkActionLogsFrequencyRegisteredBetweenDatesOLD` (linha 1701): versão antiga sem `time_zone` e sem `sum_field`. Não chamada.
+- Constantes commentadas indicando refactor incompleto: `COLLECTION_REWARD`, `COLLECTION_PRINCIPAL`, `COLLECTION_ACHIEVEMENT` duplicada (linhas 83-89).
+- `total` é declarado como `double` em `Achievement.total`, mas vários métodos retornam `long` (`sumTotalRewards`, `countChallengeAchievementsByPlayer`) — **perda de precisão decimal** em totais agregados. Apenas `sumTotalPoints` usa double.
+- Vários `e.printStackTrace()` com comentários "//e.printStackTrace();" — erros silenciosamente engolidos (parsing de RewardPoint, conversão de timezone, geolocation index).
+
+---
+
+## 8. Segurança e Permissões
+
+### Autenticação
+
+- Endpoints v3 exigem `Authorization: Bearer <token>` resolvido em `AuthBean`.
+- Endpoint legado `/2.0.0/achievement POST` exige `?api_key=<id>&app_secret=<secret>` validado por `securityManager.isAppAllowed(app_secret)`.
+- Não há separação de scopes/permissions no `AchievementRest` v3 — qualquer token autenticado no tenant pode listar, criar, ou deletar achievements.
+
+### Isolamento multi-tenant
+
+Cada tenant tem sua conexão MongoDB própria via `FrontController.getInstance(apiKey).getManagerFactory().getJongoConnection()`. Não há chave de tenant no documento `achievement` — a separação é puramente física.
+
+### Superfícies de injeção MongoDB
+
+Múltiplos endpoints concatenam strings diretamente em queries Jongo:
+
+| Endpoint / método | Parâmetro vulnerável | Trecho do código |
+|---|---|---|
+| `GET /v3/achievement` (`q`) | `query.append(", " + q);` | linha 1248 / 1307 |
+| `GET /v3/achievement/frequency` (`q`) | idem | linha 3188 |
+| `POST /v3/achievement/aggregate` (`q` + body `aggregations`) | `query.append(", " + q);` e `a.and(aggregations.get(i))` | linhas 2995 / 3023 |
+| `findAllPlayerStatus` (`q`) | idem | linha 884 |
+| `buildJsonFilter` | atributos da rule concatenados com `+ value` | linhas 2043-2113 |
+
+O conteúdo de `q` e do array `aggregations` é **interpretado** pelo Jongo / driver Mongo como pipeline. Um cliente autenticado pode:
+
+- Injetar `$where` (NoSQL injection clássico) → execução JavaScript no servidor Mongo (se permitido pelo cluster).
+- Disparar `$lookup` para outras coleções → ler dados não relacionados a achievements.
+- Forçar `$out` para criar coleções arbitrárias (mitigado pelo método ser `aggregate` sem cursor de saída, mas dependente da versão do driver).
+
+**Não há sanitização ou whitelist** — o sistema de segurança assume que tokens autenticados são confiáveis.
+
+### Outras superfícies
+
+- **Aggregations em `rule.aggregate`** (challenges customizados): mesmo modelo de risco — usuários com permissão de criar/editar challenges podem cravar pipelines maliciosos que rodam em todas as ações de jogadores.
+- **Reflexivo em `MustacheUtils.parse` + `ExpressionBuilder.evaluate`** (linhas 277-284): o `rule.total` quando String é avaliado como expressão matemática com Mustache. `ExpressionBuilder` só executa aritmética (exp4j), mas Mustache permite acessar propriedades do `player`/`team`/`rule`/`challenge` que vão pro template — risco baixo de injeção arbitrária, alto de DoS via expressões grandes.
+- **`Operator.MAX_DISTANCE_IN_METERS`** cria índice `2dsphere` automaticamente em `action_log` na primeira execução — usuários com permissão de criar challenges podem forçar criação de índices arbitrários.
+
+---
+
+## 9. Observabilidade e Troubleshooting
+
+### Diagnóstico básico
+
+| Sintoma | Verificar |
+|---|---|
+| Player ganhou pontos mas saldo errado em `player_status` | `db.achievement.aggregate([{$match:{player:X, type:0}}, {$group:{_id:'$item', total:{$sum:'$total'}}}])` vs `db.player_status.findOne({_id:X}).point_categories` |
+| Challenge não está sendo completado | `db.challenge.findOne({_id:X}).active`, regras + `when`, `team_challenge` vs principal, `requirements`, `join.required` |
+| Level não está subindo | `db.level_config.findOne({_id:"global"}).pointCategory` → `sumTotalRewards(player, 0, <category>)` >= `nextLevel.minPoints` E todos os `requirements` cumpridos? |
+| Progresso não aparece | `db.challenge_progress.find({player:X, challenge:Y})` — só persiste se `percent_completed > 0` OU `trackFullProgress=true` |
+| `game_status` desatualizado | Sempre. `updateGameStatus` está comentado no `fireAction`. Force `db.game_status.drop()` e leia novamente |
+| `player_status` defasado depois de bulk | Esperado. Insira um achievement vazio (total=0) ou chame `GET /v3/player/{id}/status` (rota que dispara updateUserStatus) |
+| Achievements duplicados | Verificar se `deleteProgress` foi chamado; se há recursão team→player com mesmo challenge |
+
+### Queries úteis (mongosh)
+
+```js
+// Saldo de pontos por categoria do jogador X
+db.achievement.aggregate([
+  { $match: { player: "X", type: 0 } },
+  { $group: { _id: "$item", total: { $sum: "$total" } } }
+])
+
+// Lista de achievements de um jogador, mais recentes primeiro
+db.achievement.find({ player: "X" }).sort({ time: -1 }).limit(20)
+
+// Total de challenges completos por player no último mês
+db.achievement.aggregate([
+  { $match: { type: 1, time: { $gte: new Date(Date.now()-30*24*3600*1000) } } },
+  { $group: { _id: "$player", total: { $sum: 1 } } },
+  { $sort: { total: -1 } }
+])
+
+// Achievements derivados de um challenge específico (via propagateOrigin)
+db.achievement.find({ "extra.origin": "<id_do_achievement_de_challenge>" })
+
+// Estornos (totais negativos)
+db.achievement.find({ total: { $lt: 0 } })
+
+// ChallengeProgress órfãos (challenge inexistente)
+const cids = db.challenge.distinct("_id");
+db.challenge_progress.find({ challenge: { $nin: cids } })
+```
+
+### Comandos HTTP úteis
+
+```
+GET  /v3/achievement?player=joao@empresa.com&type=1&max_results=50
+GET  /v3/achievement/frequency?player=joao@empresa.com&every=1d&published_min=-30d
+POST /v3/achievement/aggregate?published_min=-7d
+     Body: ["{$group: {_id: '$player', total: {$sum:'$total'}}}", "{$sort: {total:-1}}", "{$limit: 10}"]
+GET  /v3/achievement/options/3      → lista de Levels
+GET  /v3/achievement/totalPlayersByAchievement
+DELETE /v3/achievement/<id>
+```
+
+### Erros comuns
+
+| Erro / sintoma | Causa provável |
+|---|---|
+| `POST /v3/achievement` retorna 200 mas saldo não muda | `total: 0` foi enviado; ou `player` não existe em `player` collection (achievement é persistido mas `updateUserStatus` no-ops) |
+| `GET /v3/achievement?type=0` retorna lista cheia (não filtra) | Bug documentado em 4.1 — `type=0` é ignorado. Use `q=type:0` |
+| `DELETE` retorna 204 mas achievement continua | id errado (case-sensitive); ou foi deletado mas `player_status` ainda tem snapshot antigo se nenhum recálculo foi feito |
+| `findValidChallenges` lento | Filtro `active:true` + `rules.actionId` é a única parte indexada; `when` é filtrado em memória — challenges com muitos `when` complexos não escalam |
+| `evaluateLevelUp` loop infinito | Improvável (cada iter aumenta o level corrente); mas se `nextLevel.minPoints == currentLevel.minPoints` e requirements cumpridos, pode laçar |
+| Pipeline `rule.aggregate` falha | Erro engolido por `try/catch` no for de challenges (linhas 794-797); apenas `e.printStackTrace()` no log da JVM |
+
+### Logs gerados pelo módulo
+
+- `System.out.println("Falha ao avaliar desafio " + challenge.getChallenge())` + stack trace (linhas 795-796) — único log explícito em `fireAction`.
+- `e.printStackTrace()` em conversão de timezone (linha 2222), índice geo (2107, 2181), conversão de pontos (silenciado em alguns casos).
+- Não há logs estruturados nem instrumentação de métricas no manager.
+
+---
+
+## 10. Exemplos Práticos
+
+### 10.1 Exemplo mínimo — registrar manualmente pontos para um jogador
+
+```http
+POST /v3/achievement HTTP/1.1
+Authorization: Bearer eyJhbGc...
+Content-Type: application/json
+
+{
+  "player": "maria@empresa.com",
+  "total": 50,
   "type": 0,
-  "item": "xp",
-  "time": {"$date": "2023-07-05T20:57:33.303Z"}
+  "item": "xp"
+}
+```
+
+Resultado: insere achievement; `updateUserStatus(maria@empresa.com)` recalcula `player_status`; se pontos somados cruzarem `minPoints` de um Level, dispara `evaluateLevelUp` em loop.
+
+### 10.2 Exemplo avançado — estorno com rastreio de origem
+
+Cenário: corrigir cobrança duplicada de catalog_item para um jogador. Estornar mantendo a relação com o item original.
+
+```http
+POST /v3/achievement HTTP/1.1
+Authorization: Bearer eyJhbGc...
+Content-Type: application/json
+
+{
+  "player": "maria@empresa.com",
+  "total": -1,
+  "type": 2,
+  "item": "vg_camisa_polo",
+  "time": 1685011053000,
+  "extra": {
+    "origin": "achievement_id_da_compra_original",
+    "reason": "ajuste_manual_atendimento",
+    "operator": "joao@suporte.empresa.com"
+  }
+}
+```
+
+Comentários sobre o exemplo:
+
+- `total: -1` decrementa o saldo de catalog items.
+- `time` explícito mantém a ordenação histórica adequada.
+- `extra.origin` permite reconstruir a árvore via `db.achievement.find({"extra.origin":"..."})`.
+- Trigger `before_win`/`after_win` **não dispara** neste fluxo (POST direto).
+
+### 10.3 Exemplo avançado — bulk import com posterior reconciliação de status
+
+```http
+POST /v3/achievement/bulk HTTP/1.1
+Authorization: Bearer eyJhbGc...
+Content-Type: application/json
+
+[
+  {"player":"u1","total":10,"type":0,"item":"xp","time":1685010000000},
+  {"player":"u2","total":20,"type":0,"item":"xp","time":1685010100000},
+  {"player":"u1","total":5,"type":0,"item":"xp","time":1685010200000}
+]
+```
+
+Após o bulk, `player_status` **não** é recalculado. Para forçar:
+
+```http
+GET /v3/player/u1/status
+GET /v3/player/u2/status
+```
+
+(esses endpoints invocam `updateUserStatus` internamente).
+
+### 10.4 Anti-pattern — usar `POST /v3/achievement` para "simular" uma action
+
+```http
+POST /v3/achievement HTTP/1.1
+{
+  "player": "maria@empresa.com",
+  "total": 1,
+  "type": 1,
+  "item": "challenge_pioneirismo"
 }
 ```
 
-**Tipos de Achievement (campo type):**
-- `0` = Point (ponto ganho)
-- `1` = Challenge (desafio completado)
-- `2` = Virtual Good (item comprado)
-- `3` = Level (nível atingido)
+**Por que é errado:**
+
+- Não dispara `fireAction`. As recompensas (`points`, `rewards`, `notifications`) do challenge **não acontecem**.
+- Não deduz requirements do challenge.
+- Não dispara webhook `achievement_created`.
+- Triggers `before_win`/`after_win` do challenge não rodam.
+- `progress` órfão pode permanecer (não há `deleteProgress` chamado).
+
+**Correto:** registrar a action via `POST /v3/action/log` com `actionId` que dispara o challenge. Se o objetivo é forçar a conquista sem ação registrada, use o caminho oficial de "force complete" (não existe atualmente — é uma lacuna documentada). Como workaround, registrar a `action_log` correspondente.
+
+### 10.5 Anti-pattern — confiar em `game_status` para métricas em tempo real
+
+```http
+GET /v3/achievement/totalPlayersByAchievement
+```
 
-## API Endpoints
+**Por que é errado:** `updateGameStatus` está comentado em `fireAction`. O resultado retornado é o último snapshot persistido, que pode ser de horas/dias atrás. Para métricas live, rode aggregations diretas em `achievement` via `POST /v3/achievement/aggregate`.
 
-### Listar Conquistas
-**Método:** GET
-**Endpoint:** `/v3/achievement`
+---
 
-## Validações e Testes
+## Checklist de Configuração
 
-- [ ] Ao completar desafio, achievement tipo 1 é criado
-- [ ] Ao ganhar pontos, achievement tipo 0 é criado
-- [ ] Ao comprar item, achievement tipo 2 é criado
-- [ ] Ao subir de nível, achievement tipo 3 é criado
+- [ ] `point_category` do tenant existe **antes** de gerar achievements TYPE_POINT (`findOptionsByType(0)` retorna a categoria desejada)
+- [ ] `level_config` `{_id:"global"}` define `pointCategory` correta — caso contrário `evaluateLevelUp` soma **todos** os pontos sem filtro de categoria
+- [ ] Levels têm `position` e `minPoints` configurados — sem `position` o `findLatestLevelAchieved → nextLevel` quebra
+- [ ] Challenges com `RANGE_ALL_IN_ORDER` consideram timestamps com resolução suficiente — actions com mesmo `time` podem invalidar a ordem (vide 5.12)
+- [ ] Challenges com `join.required=true` exigem que o jogador tenha um `JoinLog` aberto **antes** da action — caso contrário `fireAction` ignora (continue) silenciosamente
+- [ ] Challenges com `rule.entity` + `rule.aggregate` foram revisados — pipelines mal formados são engolidos por try/catch e o desafio nunca completa
+- [ ] Para teams, configurar `Challenge.teamChallenge=true` E `Challenge.principals` com os times — sem `teamChallenge=true` a recursão player→team avalia mas falha em `evaluatePrincipal`
+- [ ] **Armadilha**: `GET /v3/achievement?type=0` **não filtra** — passe `q=type:0` para conseguir filtrar achievements de pontos
+- [ ] **Armadilha**: `POST /v3/achievement/bulk` não atualiza `player_status` — chame `GET /v3/player/{id}/status` ou faça um `POST /v3/achievement` com `total: 0` para forçar
+- [ ] **Armadilha**: `POST /v3/achievement` direto não dispara triggers nem webhook — se o consumo downstream depende disso, registre via action ou chame manualmente o trigger
+- [ ] **Armadilha**: `game_status` está stale by design — não usar para painéis em tempo real
+- [ ] **Armadilha**: campo `extra.origin` só é setado quando `challenge.propagateOrigin=true` — para rastreabilidade, marcar `propagateOrigin=true` desde o cadastro
+- [ ] Considerar que `total` é declarado como `double` em `Achievement` mas vários cálculos retornam `long` — para items fracionários (créditos em decimais), validar caminho de cada agregação
+- [ ] **Armadilha**: `Achievement.id` é ShortGuid (não ObjectId) — strings curtas, suficientes apenas para isolamento por tenant; não usar para correlação global multi-tenant
+- [ ] Removidos em batch (`DELETE` em massa): **não existe endpoint**. Para apagar muitos achievements use `/v3/database` direto com `collection=achievement` (e perde-se `updateUserStatus` automático)