funifier-mcp 0.2.26 → 0.2.28

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

@@ -1,328 +1,1156 @@
-# Challenge (Desafio)
+# `challenge`
 
 **Acesso Studio:** `/studio/challenge`
 **API Endpoint:** `/v3/challenge`
+**Coleção MongoDB:** `challenge`
 
-## O que é
+> Documentação produzida por engenharia reversa direta do código-fonte em `funifier-service` (pacote `com.funifier.engine.challenge` e `com.funifier.engine.achievement.AchievementManager`). Onde a documentação contradiz o schema histórico, o **código tem prioridade**.
 
-Configuração de desafios a serem completados por jogadores ou equipes. Permite criar desafios personalizados, definindo ações que o jogador precisa realizar e recompensas que receberá. Os desafios podem variar de simples tarefas a missões complexas compostas por múltiplas ações ou etapas.
+---
 
-## Quando usar
+## 1. Visão Geral
 
-- Em quase todo projeto de gamificação
-- Para definir missões e objetivos para jogadores
-- Para vincular ações a recompensas (pontos, itens, etc.)
-- Para criar progressão e senso de conquista
+`challenge` é o módulo de **desafios/missões** da gamificação. Cada documento descreve um objetivo composto por uma ou mais regras (`rules`), cada regra ligada a uma `Action` do sistema. Quando uma `Action` é registrada via `fireAction` (ver `AchievementManager.fireAction`), todos os challenges válidos para aquela action são re-avaliados em tempo real e, ao serem concluídos, geram:
 
-## Dependências
+- Um `Achievement` do tipo `TYPE_CHALLENGE` (id da conquista guardado em `achievement.item = challenge._id`);
+- Pontuações configuradas em `points`;
+- Recompensas materializadas em `rewards` (catalog items, lottery tickets, challenges, pontos);
+- Notificações em `notifications`;
+- Deduções automáticas via `requirements` com `operation = DEDUCT`.
 
-- **Point**: tipos de ponto devem existir antes de criar challenges que os recompensam
-- **Action**: ações devem existir antes de criar challenges que as referenciam
+Papel arquitetural:
 
-## Campos Obrigatórios vs Opcionais
+- O Challenge é a **engrenagem central** da regra de pontuação não-trivial. `Action` registra direto apenas os pontos definidos em `Action.points`; tudo que dependa de contagens, filtros, janelas temporais ou metas só existe em Challenge.
+- Não tem scheduler / worker / job dedicado. A avaliação é **100% reativa**, disparada pelo método `AchievementManager.fireAction` (chamado por `ActionManager.trackSynchonous`).
+- Compartilha o documento de progresso (`challenge_progress`) com o módulo `achievement`.
 
-| Campo | Obrigatório | Descrição |
+Relação direta com outros módulos:
+
+| Módulo | Onde | Como |
 |---|---|---|
-| `challenge` | sim | Nome/título do desafio |
-| `techniques` | sim | Array com pelo menos um código GT (ex: `["GT35"]`) |
-| `rules` | sim | Regras que definem o que o jogador deve fazer |
-| `points` | recomendado | Recompensas em pontos ao completar |
-| `description` | não | Descrição exibida ao jogador |
-| `active` | não | `true` por padrão |
-| `_id` | não | Gerado automaticamente se omitido |
-| `range` | não | Obrigatório quando há múltiplas rules; padrão `0` |
-| `teamChallenge` | não | `true` para desafios de equipe |
-| `limitTotal` | não | Limite de vezes que pode ser completado |
-| `limitPerType` | não | A quem se aplica o limite |
-| `limitTimeAmount` | não | Número de períodos para o limite |
-| `limitTimeScale` | não | Escala de tempo do limite |
-| `notifications` | não | Notificações ao completar/criar/alterar |
-| `requirements` | não | Pré-requisitos para desbloquear |
-| `rewards` | não | Recompensas adicionais (itens de catálogo) |
-| `when` | não | Restrição de data/hora de disponibilidade |
-| `principals` | não | Restringe o desafio a jogadores/equipes específicos |
-| `trackFullProgress` | não | Rastrear progresso completo de cada rule |
-| `extra` | não | Campos customizados livres |
-| `i18n` | não | Traduções do título/descrição |
-
-## Imagem (badge)
-
-Challenges usam o campo `badge` (não `image`) para a imagem do desafio:
+| `action` | `ChallengeRule.actionId` | identifica qual `Action` dispara a avaliação |
+| `achievement` | `fireAction`, `Achievement.TYPE_CHALLENGE` | conquista é registrada na coleção `achievement` |
+| `point` | `RewardPoint.category` | pontuação ao concluir |
+| `catalog` | `Requirement.type = TYPE_CATALOG_ITEM` | recompensas/requisitos de virtual goods |
+| `lottery` | `Requirement.type = TYPE_LOTTERY_TICKET` | tickets de loteria como recompensa |
+| `level` | `Requirement.type = TYPE_LEVEL` | apenas requisito (não é dedutível) |
+| `join` (`join_log`) | `Challenge.join`, `JoinManager.insert` | controla aceite obrigatório do jogador |
+| `trigger` | `EVENT_BEFORE_WIN` / `EVENT_AFTER_WIN` | hooks Groovy disparados ao conceder challenge |
+| `webhook` | `Webhook.EVENT_ACHIEVEMENT_CREATED` | notificação externa de conquistas |
+| `notification` | `NotificationDefinition.EVENT_WIN` | mensagens privadas/newsfeed ao concluir |
+| `principal`/`team` | `Challenge.principals`, `teamChallenge` | filtragem de elegibilidade |
+| `technique` | `GameTechniqueManager` | challenge sem techniques recebe automaticamente `GT35` |
+
+---
+
+## 2. Arquitetura e Fluxos
+
+### 2.1 Classes envolvidas
+
+| Classe | Papel |
+|---|---|
+| `com.funifier.rest.v3.rest.ChallengeRest` | Controller REST `/v3/challenge` |
+| `com.funifier.engine.challenge.ChallengeManager` | Orquestra CRUD, validações, geração de descrição |
+| `com.funifier.engine.challenge.ChallengeDaoMongo` | Persistência direta em MongoDB (collection `challenge`) |
+| `com.funifier.engine.challenge.Challenge` | Entidade raiz (documento `challenge`) |
+| `com.funifier.engine.challenge.ChallengeRule` | Regra individual de avaliação |
+| `com.funifier.engine.challenge.ChallengeRuleFilter` | Filtro sobre atributos da action |
+| `com.funifier.engine.challenge.ChallengeRulePrepared` | Aggregation salva (collection `challenge_rule_prepared`) |
+| `com.funifier.engine.challenge.RewardPoint` | Pontos concedidos ao concluir |
+| `com.funifier.engine.challenge.Requirement` | Requisito de entrada **e** recompensa de catálogo/loteria |
+| `com.funifier.engine.achievement.ChallengeProgress` | Snapshot de progresso (collection `challenge_progress`) |
+| `com.funifier.engine.achievement.ChallengeRuleProgress` | Snapshot por regra dentro do progresso |
+| `com.funifier.engine.achievement.AchievementManager` | **Avaliador real** — `fireAction`, `findValidChallenges`, `evaluatePrincipal`, `evaluateLimit`, `isChallengeAvailable` |
+| `com.funifier.engine.challenge.LinkPrincipal` | **Deprecated**, todo uso comentado |
+| `com.funifier.engine.challenge.ChallengeReward` | **Deprecated**, modelo antigo desconectado |
+
+### 2.2 Pipeline principal — `fireAction` (avaliação de challenges)
+
+Ponto de entrada: `AchievementManager.fireAction(ActionLog trigger)` — invocado por `ActionManager.trackSynchonous`.
 
-```json
-"badge": {
-  "small":    { "url": "https://...", "size": 0, "width": 0, "height": 0, "depth": 0 },
-  "medium":   { "url": "https://...", "size": 0, "width": 0, "height": 0, "depth": 0 },
-  "original": { "url": "https://...", "size": 0, "width": 0, "height": 0, "depth": 0 }
-}
+```
+[1]  findPrincipalByUserOrTeamId(trigger.userId)
+     └── se principal é null → retorna lista vazia (sem erro, sem log)
+
+[2]  ACTION POINTS — apenas se principal.isPlayer():
+     ├── Lê Action.points[]
+     ├── Para cada RewardPoint:
+     │     OPERATION_NONE      → totalPoints = p.total
+     │     MULTIPLY_BY_ATTRIBUTE → totalPoints = p.total * trigger.attributes[p.value]
+     │     DIVIDE_BY_ATTRIBUTE   → totalPoints = p.total / trigger.attributes[p.value]
+     ├── Cria Achievement(TYPE_POINT, p.category)
+     ├── TriggerManager.execute(EVENT_BEFORE_WIN) → addAchievement → EVENT_AFTER_WIN
+     └── Dispara Notifications da Action (EVENT_WIN)
+
+[3]  Resolve playerIds:
+     ├── Se isTeam: ids dos membros + o próprio teamId
+     └── Se isPlayer: [trigger.userId]
+
+[4]  findValidChallenges(trigger, jongo, timeZone):
+     ├── Query Mongo: { active:true, rules:{$elemMatch:{actionId: trigger.actionId}} }
+     ├── Itera resultado em memória aplicando challenge.when.isDateAllowed(...)
+     └── (timezone usado: Security.timeZone — NÃO o do jogador)
+
+[5]  evaluatePrincipal(trigger, challenges, principal, jongo):
+     Para cada challenge:
+       ├── XOR(principal.isTeam, challenge.teamChallenge) → reprova
+       ├── evaluateLimit (conta achievements anteriores deste challenge)
+       ├── isUserChallengePrincipal (challenge.principals contém player ou um time do player)
+       ├── evaluateRequirements (sumTotalRewards >= r.total, por período opcional)
+       └── evaluateJoin (se join.required=true exige JoinLog não-completado dentro do timeframe)
+
+[6]  Para cada challenge sobrevivente, avalia REGRAS:
+     ├── getDefaultJoinTimeFrame(challenge) — janela vinda do JoinLog.start/finish
+     ├── inOrder = (range==RANGE_ALL_IN_ORDER && rules.length > 1)
+     ├── Para cada rule[i]:
+     │     ├── rule_total = parseTotal(rule.total)
+     │     │     - null → 1
+     │     │     - Number → intValue
+     │     │     - String → ExpressionBuilder(Mustache(rule.total, {player, team, rule, challenge}))
+     │     │
+     │     ├── filter = buildJsonFilter(rule, trigger, jongo)
+     │     ├── type = getRuleType(rule, rule_total)
+     │     │     - everyAmount>0 && everyScale!=NONE && timeAmount>0 && timeScale!=NONE → EVERY
+     │     │     - rule_total>1 && everyScale==NONE → SEVERAL
+     │     │     - default → ONE
+     │     ├── between = getRuleTime(rule, trigger.time, timeframe)
+     │     │     - timeAmount==0 || timeScale==NONE → timeframe || [null,null]
+     │     │     - outOfTime=true → DateUtil.betweenOverThan(...)
+     │     │     - outOfTime=false → DateUtil.betweenLessThan(...)
+     │     │
+     │     ├── Se rule.prepared definido → carrega ChallengeRulePrepared e injeta entity+aggregate
+     │     ├── Se rule.entity && rule.aggregate definidos:
+     │     │       countWithAggregateRegisteredBetweenDatesV3(...)
+     │     │       operator EQUAL/GTE/MOD → ruleDone
+     │     ├── senão se ONE:
+     │     │       sem filtros, sem attribute → done direto se actionId == trigger.actionId
+     │     │       senão countActionLogsRegisteredBetweenDatesV3 (usa trigger.time se única rule da action)
+     │     ├── senão se SEVERAL:
+     │     │       countActionLogsRegisteredBetweenDatesV3 em [between[0], between[1]]
+     │     │       operator EQUAL/GTE/MOD → ruleDone
+     │     └── senão se EVERY:
+     │             checkActionLogsFrequencyRegisteredBetweenDates
+     │             frequency.size() < totalUnitsInPeriod → false
+     │             qualquer bucket com total < rule_total → false
+
+[7]  Avalia conclusão do challenge:
+     ├── RANGE_ALL          → _true == rules.length
+     ├── RANGE_ALL_IN_ORDER → _true == rules.length && orderTime[i] <= orderTime[i+1] ∀ i
+     └── RANGE_ANY          → _true > 0
+     Se in-order falha, marca rules subsequentes como setUncompletedBecauseOfTime().
+
+[8]  Se concluído:
+     ├── deleteProgress(player, challengeId)
+     ├── Se challenge.join.required:
+     │     ├── findNotCompleted → se null, ABORTA este challenge (continue)
+     │     └── senão completeAll dos JoinLog abertos
+     ├── Cria Achievement TYPE_CHALLENGE
+     ├── TriggerManager.execute(CHALLENGE, EVENT_BEFORE_WIN) → addAchievement → EVENT_AFTER_WIN
+     ├── REGISTER POINTS (challenge.points):
+     │     - mesmo cálculo MULTIPLY/DIVIDE da etapa [2]
+     │     - se teamChallenge && p.perPlayer=true → loop por cada membro
+     │     - addAchievement TYPE_POINT, updateUserStatus
+     │     - se challenge.propagateOrigin → achievement.extra.origin = challengeAchievement.id
+     ├── REGISTER REWARDS (challenge.rewards):
+     │     - Apenas tipos POINT, CATALOG_ITEM, CHALLENGE, LOTTERY_TICKET
+     │     - r.item == "FUNIFIER_RANDOM" + CATALOG_ITEM → CatalogManager.findRandom (ou findValidRandom se restrict)
+     │     - r.item == "FUNIFIER_RANDOM" + LOTTERY_TICKET → LotteryManager.findRandom + cria N tickets
+     │     - LOTTERY_TICKET com r.item específico → cria N LotteryTickets, dispara triggers LOTTERY_TICKET
+     │     - perPlayer + teamChallenge → loop por membros
+     ├── REGISTER NOTIFICATIONS (challenge.notifications EVENT_WIN)
+     └── deductRequirements (apenas operation=DEDUCT, tipos POINT/CATALOG_ITEM/CHALLENGE — total negativado)
+
+[9]  Se NÃO concluído mas (única rule || _true > 0 || trackFullProgress=true):
+     ├── deleteProgress
+     ├── progress.calculatePercentCompleted()
+     └── Se percent_completed > 0 || trackFullProgress → addProgress
+
+[10] updatePlayerStatus(userId) — apenas para principal.isPlayer
+     (TODO no código: não há update para team status)
+
+[11] Recursão TEAM: se principal.isPlayer e tem teams, chama fireAction novamente
+     com ActionLog clonado mas userId = teamId (uma vez por time)
+
+[12] WebhookManager.execute(EVENT_ACHIEVEMENT_CREATED, result)
 ```
 
-Na prática basta preencher `url` nos três tamanhos com a mesma URL se não houver versões distintas.
+#### Diagrama — Fluxo de avaliação
+
+```mermaid
+flowchart LR
+    A[ActionLog trigger] --> B[fireAction]
+    B --> C{principal == null?}
+    C -- sim --> Z[retorna lista vazia]
+    C -- não --> D[registra Action.points]
+    D --> E[findValidChallenges<br/>active+actionId+when]
+    E --> F[evaluatePrincipal<br/>teamChallenge+limit+principals+requirements+join]
+    F --> G[loop por rules]
+    G --> H{tipo da rule}
+    H -- ONE --> H1[countActionLogs]
+    H -- SEVERAL --> H2[count + operator]
+    H -- EVERY --> H3[checkFrequency]
+    H -- aggregate --> H4[countWithAggregate]
+    H1 & H2 & H3 & H4 --> I{range satisfeito?}
+    I -- não --> J[grava ChallengeProgress se aplicável]
+    I -- sim --> K[Achievement TYPE_CHALLENGE]
+    K --> L[points + rewards + notifications]
+    L --> M[deductRequirements]
+    M --> N[updatePlayerStatus]
+    N --> O[recursão para teams]
+    O --> P[WebhookManager EVENT_ACHIEVEMENT_CREATED]
+```
 
-## Técnicas de Jogo (techniques)
+#### Diagrama — Interação `fireAction` com outros managers
+
+```mermaid
+sequenceDiagram
+    participant AL as ActionManager
+    participant AM as AchievementManager
+    participant CM as ChallengeManager
+    participant JM as JoinManager
+    participant TM as TriggerManager
+    participant PM as PlayerManager
+    participant WM as WebhookManager
+
+    AL->>AM: fireAction(trigger)
+    AM->>AM: findValidChallenges (Mongo)
+    AM->>AM: evaluatePrincipal
+    AM->>JM: findNotCompleted (se join.required)
+    JM-->>AM: JoinLog ou null
+    AM->>AM: avalia rules
+    alt Challenge concluído
+        AM->>JM: completeAll
+        AM->>TM: execute EVENT_BEFORE_WIN
+        AM->>AM: addAchievement (TYPE_CHALLENGE)
+        AM->>TM: execute EVENT_AFTER_WIN
+        AM->>AM: registra points + rewards
+        AM->>PM: updateUserStatus
+    end
+    AM->>WM: execute EVENT_ACHIEVEMENT_CREATED
+    AM-->>AL: List<Achievement>
+```
 
-`techniques` é **obrigatório**. Cada código GT representa uma mecânica de gamificação. Para challenges, os códigos válidos são:
+### 2.3 Pipeline — CRUD via `/v3/challenge`
 
-`GT35`, `GT22`, `GT02`, `GT07`, `GT17`, `GT14`, `GT48`, `GT12`, `GT40`, `GT89`, `GT68`, `GT66`, `GT67`, `GT21`, `GT30`, `GT86`
+| Pipeline | Etapas |
+|---|---|
+| **POST** (`insert`) | `ChallengeManager.add` → set `created` (se null) → set `updated = now` → `when.compile()` (no-op atualmente) → `mongo.add` (ver 2.4) |
+| **GET por id** | `mongo.findById` → `find({_id:#})` direto |
+| **GET lista** | `manager.findAll(filters)` aggregation `$match` + `$project` + `$sort` + `$limit`; `to=me` substitui pelo token do jogador; se `available=true` + `player`, popula `challenge.available` em memória |
+| **DELETE** | `mongo.remove({_id:#})` — **não** remove achievements/progress associados |
+| **POST `/describe`** | `ChallengeManager.describe` gera texto pt-BR/en em string única |
+| **GET `/evaluate/{id}`** | `evaluatePrincipalAnalyze` (analisa principals, limit, requirements, join — **não conta logs de regras**) |
+| **GET `/prepared`** | lê `challenge_rule_prepared` direto (sem aggregation) |
 
-O mais comum para challenges é **`GT35` (Quest List)** — exibe uma lista de tarefas/missões para o jogador cumprir.
+Não existe método `PUT`. Atualização é feita reusando `POST` com `_id` preenchido (Jongo `save` é upsert).
 
-```json
-"techniques": ["GT35"]
+### 2.4 Pipeline de persistência (`ChallengeDaoMongo.add`)
+
+```
+[1] Se id null ou vazio → Guid.shortTimeMillis()
+    └── ⚠ NÃO é UUID — id baseado em timestamp curto
+[2] Se challenge.principals != null && size > 0:
+    └── reescreve principals = jongo("principal").distinct("_id").query({_id:{$in:principals}})
+        → silenciosamente REMOVE qualquer id de principal que não exista
+[3] Se rules != null:
+    └── remove silenciosamente toda rule sem actionId
+[4] Se requirements != null:
+    └── remove silenciosamente toda requirement sem item
+[5] Se rewards != null:
+    └── remove silenciosamente toda reward sem item
+[6] jongo("challenge").save(challenge) → upsert por _id
 ```
 
-## Tabela de Referência dos Enums
+`ChallengeDaoMongo.update`:
 
-### `range` — como as rules são avaliadas
+```
+[1] jongo("challenge").remove({_id: challenge.id})
+[2] jongo("challenge").save(challenge)
+```
 
-| Valor | Label |
-|---|---|
-| `0` | Complete All (completar todas as rules) |
-| `1` | Complete Any (completar qualquer uma) |
-| `2` | Complete All in Order (completar todas em ordem) |
+⚠ **NÃO é atômico**: existe uma janela de tempo em que o documento não está na coleção. Reads concorrentes podem retornar `null`. Esta operação **não é chamada pelo REST** (apenas pelo `manager.update`, que por sua vez não é exposto). Em prática, todo update real passa por `add` → `save` (upsert), que é atômico.
+
+---
+
+## 3. Estrutura dos Objetos
+
+### 3.1 `Challenge` — documento raiz (`challenge`)
+
+| Campo | Tipo | Padrão | Obrigatório | Descrição |
+|---|---|---|---|---|
+| `_id` | String | `Guid.shortTimeMillis()` | — | id do desafio. Time-based, **não** UUID |
+| `challenge` | String | — | sim (na prática) | nome legível |
+| `description` | String | — | não | descrição livre |
+| `range` | int | `0` | não | `0`=ALL, `1`=ANY, `2`=ALL_IN_ORDER |
+| `active` | boolean | `true` | não | só challenges com `active=true` entram em `findValidChallenges` |
+| `when` | `TimeRestriction` | null | não | janela de validade temporal |
+| `rules` | `ChallengeRule[]` | `[]` | sim | regras de avaliação |
+| `teamChallenge` | boolean | `false` | não | se `true`, só dispara quando o `principal` é Team |
+| `limitTotal` | int | `0` | não | máximo de conquistas (0 = ilimitado) |
+| `limitPerType` | int | `0` | não | `0`=PER_PLAYER, `1`=PER_TEAM, `2`=PER_GAME |
+| `limitTimeAmount` | int | `0` | não | tamanho da janela de limite |
+| `limitTimeScale` | int | `0` | não | unidade da janela (ver Enum TimeScale) |
+| `techniques` | List&lt;String&gt; | `null` | não | códigos GT (auto-preenchido com `GT35`) |
+| `join` | `Join` | null | não | controle de aceite obrigatório |
+| `trackFullProgress` | Boolean | null | não | se `true`, grava progress mesmo com `_true=0` |
+| `propagateOrigin` | Boolean | null | não | se `true`, propaga `origin` em achievements derivados |
+| `badge` | `Image` | null | não | imagem com `small`, `medium`, `original` |
+| `hideUntilEarned` | boolean | `false` | não | (campo só lido — não há filtro automático na listagem) |
+| `points` | `RewardPoint[]` | null | não | pontos concedidos ao concluir |
+| `notifications` | `NotificationDefinition[]` | null | não | notificações por evento |
+| `requirements` | `Requirement[]` | null | não | pré-requisitos + deduções |
+| `tags` | String[] | null | não | tags livres (filtráveis em `findAll`) |
+| `principals` | List&lt;String&gt; | null | não | players/teams elegíveis. **null/empty = todos** |
+| `extra` | Map | `{}` | não | campos livres |
+| `rewards` | List&lt;`Requirement`&gt; | `[]` | não | recompensas materializadas ao concluir |
+| `i18n` | Map&lt;String, Map&lt;String, String&gt;&gt; | `{}` | não | traduções (consumido externamente) |
+| `created` | Date | `now()` no insert | — | preenchido em `add` se null |
+| `updated` | Date | `now()` em todo `add` | — | sobrescrito em todo save |
+
+**Campos computados em runtime (não persistidos):**
+
+- `available` (Boolean): populado em memória por `AchievementManager.isChallengesAvailable` quando o `GET /v3/challenge` recebe `available=true` + `player=<id>`.
+
+**Campos removidos silenciosamente no save:**
+
+- Itens de `rules` sem `actionId`
+- Itens de `requirements` sem `item`
+- Itens de `rewards` sem `item`
+- Ids de `principals` que não existam na coleção `principal`
+
+**Campos deprecated/legados aceitos mas ignorados (estão comentados na entidade):**
+
+- `triggerUrl` — webhook por challenge, removido em 26-jul-2017 (pedido da Wiz)
+- `order` — ordem visual, removida da UI
+- `items` — recompensa de items de catálogo, substituído por `rewards`
+- `levelId` — substituído por `requirements`
+- `pointCategoryId`, `pointAward` — substituído por `points` (v2.0)
+- `notify`, `notifyMessage`, `notifyUsersNow`, `notifyUsersNowMessage` — substituído por `notifications`
+- `badgeIcon` — substituído por `badge` (v2.0)
+- `repeatable`, `activeStartDate`, `activeEndDate` — substituídos por `limitTotal`+`when`
+
+Estes campos serão **persistidos** se o cliente enviá-los (Mongo aceita campos extras), mas serão ignorados em qualquer leitura — `Challenge` não tem getters/setters para eles.
+
+#### Enums (`Challenge.*`)
+
+| Constante | Valor | Significado |
+|---|---|---|
+| `RANGE_ALL` | `0` | Conclui se todas as regras estão completas |
+| `RANGE_ANY` | `1` | Conclui se ao menos uma regra está completa |
+| `RANGE_ALL_IN_ORDER` | `2` | Todas as regras + na ordem cronológica |
+| `LIMIT_PER_PLAYER` | `0` | Limite por jogador |
+| `LIMIT_PER_TEAM` | `1` | Limite por time — **mesmo comportamento que PER_PLAYER** (ver §5) |
+| `LIMIT_PER_GAME` | `2` | Limite global da gamificação |
+
+#### Ciclo de vida do progresso
+
+```mermaid
+stateDiagram-v2
+    [*] --> SemAvaliacao: challenge ativo, jogador elegível
+    SemAvaliacao --> EmProgresso: fireAction com _true >= 1\n(ou trackFullProgress=true)
+    EmProgresso --> EmProgresso: novo fireAction\n(deleteProgress + addProgress)
+    EmProgresso --> Concluido: range satisfeito
+    SemAvaliacao --> Concluido: única rule completa
+    Concluido --> [*]: Achievement TYPE_CHALLENGE registrado\nChallengeProgress deletado
+    Concluido --> SemAvaliacao: limitTotal permite repetir
+```
 
-Padrão: `0` (Complete All). Necessário quando há mais de uma rule.
+### 3.2 `ChallengeRule` — regra (`Challenge.rules[]`)
+
+| Campo | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `_id` | String | — | id local da regra (manual ou em cliente) |
+| `actionId` | String | — | **obrigatório** — sem ele a rule é descartada no save |
+| `position` | int | `0` | posição na ordem (relevante p/ `RANGE_ALL_IN_ORDER`) |
+| `operator` | int | `0` (NONE) | comparador para `SEVERAL`/aggregate (`EQUAL`, `GTE`, `MOD`) |
+| `timeAmount` | int | `0` | tamanho da janela temporal |
+| `timeScale` | int | `0` (NONE) | unidade temporal (ver TimeScale) |
+| `outOfTime` | boolean | `false` | `false=TIME_LESS_THAN`, `true=TIME_OVER_THAN` |
+| `everyAmount` | int | `0` | tamanho do bucket de frequência (RULE_TYPE_EVERY) |
+| `everyScale` | int | `0` | unidade do bucket |
+| `filters` | List&lt;`ChallengeRuleFilter`&gt; | null | filtros sobre `action_log.attributes.*` |
+| `attribute` | String | null | atributo para `sum_attributes` (soma valores em vez de contar) |
+| `total` | Object | null | aceita Number ou String com expressão Mustache (v4) |
+| `entity` | String | null | (v5) coleção arbitrária para avaliação via aggregate |
+| `aggregate` | String | null | (v5) pipeline aggregate inline (retorna `{_id, total, max}`) |
+| `prepared` | String | null | (v5) id de `ChallengeRulePrepared` — substitui `entity`+`aggregate` |
+
+**Tipos de rule (calculados em runtime — não persistem):**
+
+| Tipo | Detecção | Avaliação |
+|---|---|---|
+| `RULE_TYPE_ONE` (0) | Default | Conta logs no intervalo; se sem filtros/attribute e action == trigger, conclui imediatamente |
+| `RULE_TYPE_SEVERAL` (1) | `rule_total > 1` e `everyScale == NONE` | Conta logs; aplica operator EQUAL/GTE/MOD contra `rule_total` |
+| `RULE_TYPE_EVERY` (2) | `everyAmount > 0` + `everyScale != NONE` + `timeAmount > 0` + `timeScale != NONE` | Verifica frequência: cada bucket no período precisa ter ≥ `rule_total` registros |
 
-### `rules[].operator` — critério de contagem da rule
+**Sobre `rule.total`:**
 
-| Valor | Label | Uso |
+- `null` ou string `"null"` → 1
+- `Number` → `intValue()` (perda de decimais)
+- `String` não vazio → parseado por `MustacheUtils.parse(rule.total, {player, team, rule, challenge})` e avaliado por `ExpressionBuilder` (exemplo: `"{{player.extra.monthly_sales_goal}} + 10"`)
+- ⚠ Se o parse falhar, `ExpressionBuilder` lança RuntimeException — **a exceção é capturada no `try` externo do `fireAction`** e o challenge é silenciosamente ignorado naquele dispatch.
+
+### 3.3 `ChallengeRuleFilter` — filtro sobre `action_log.attributes`
+
+| Campo | Tipo | Descrição |
 |---|---|---|
-| `5` | `>=` (Greater Than or Equal) | Padrão — contar N ou mais vezes |
-| `1` | `=` (Equal) | Exatamente N vezes |
-| `40` | `%` (Percentage) | Percentual |
+| `value` | String | valor a comparar. `"{{trigger}}"` é substituído pelo valor do attribute no próprio trigger |
+| `operator` | int | ver enum Operator |
+| `param` | String | nome do atributo em `action_log.attributes.<param>` |
+| `location` | DBObject | usado apenas com `MAX_DISTANCE_IN_METERS` (GeoJSON Point) |
 
-Exemplo: `operator: 5, total: 3` = executar a ação 3 ou mais vezes.
+Conversão automática em `buildJsonFilter` baseada em `Action.attribute.type`:
 
-### `rules[].filters[].operator` — operador dos filtros de atributo
+- `TYPE_NUMBER` → valor não-aspeado (numérico)
+- `TYPE_BOOLEAN` → valor não-aspeado
+- demais tipos → string aspeada
 
-| Valor | Label |
-|---|---|
-| `1` | Is (igual a) |
-| `3` | Contains (contém) |
-| `4` | Greater Than (maior que) |
-| `5` | Greater Than or Equal To |
-| `6` | Less Than (menor que) |
-| `7` | Less Than or Equal To |
-| `8` | Is Not (diferente de) |
-| `9` | Exists (campo existe) |
-| `10` | Does Not Exist (campo não existe) |
-| `20` | Near in Meters (geolocalização) |
-
-### `points[].operation` — operação sobre atributo numérico da ação
-
-| Valor | Label | Uso |
+#### Enum Operator
+
+| Constante | Valor | Operador Mongo gerado |
+|---|---|---|
+| `NONE` | 0 | (sem filtro) |
+| `EQUAL` | 1 | `<val>` |
+| `LIKE` | 2 | (não implementado em `buildJsonFilter`) |
+| `REGEX` | 3 | `{$regex:<val>}` |
+| `GREATER_THAN` | 4 | `{$gt:<val>}` |
+| `GREATER_THAN_OR_EQUAL` | 5 | `{$gte:<val>}` |
+| `LESS_THAN` | 6 | `{$lt:<val>}` |
+| `LESS_THAN_OR_EQUAL` | 7 | `{$lte:<val>}` |
+| `NOT_EQUAL` | 8 | `{$ne:<val>}` |
+| `EXIST` | 9 | `{$exists:true, $ne:null}` |
+| `NOT_EXIST` | 10 | `$or:[{attr:false, attr:{$exists:false}}]` |
+| `MAX_DISTANCE_IN_METERS` | 20 | `{$nearSphere:{$geometry:<loc>, $maxDistance:<val>}}` + cria índice `2dsphere` |
+| `MOD` | 40 | comparação em código: `total % rule_total == 0` (apenas SEVERAL/aggregate) |
+
+⚠ `LIKE` declarado mas não tratado em `buildJsonFilter` — comportamento equivale a "ignorar o filtro" (filtro vazio).
+
+### 3.4 `ChallengeRulePrepared` — coleção `challenge_rule_prepared`
+
+| Campo | Tipo | Descrição |
 |---|---|---|
-| `0` | None | Pontos fixos (padrão) |
-| `1` | Multiply By | Multiplica `total` pelo valor do atributo da ação |
-| `2` | Divide By | Divide `total` pelo valor do atributo da ação |
+| `_id` | String | id manual |
+| `title` | String | rótulo no Studio |
+| `description` | String | descrição livre |
+| `action` | String | qual `Action` esta aggregation se aplica (informativo) |
+| `entity` | String | coleção destino do aggregate (ex: `action_log`) |
+| `aggregate` | String | pipeline JSON que retorna `{_id, total, max}` |
+
+Carregado on-demand em `fireAction` quando `rule.prepared` está preenchido. Sobrescreve `rule.entity` e `rule.aggregate` em memória (não persiste).
+
+### 3.5 `RewardPoint` — `challenge.points[]`
+
+| Campo | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `total` | double | — | quantidade base de pontos |
+| `category` | String | — | id de `point_category` |
+| `operation` | int | `0` (NONE) | NONE, MULTIPLY_BY_ATTRIBUTE, DIVIDE_BY_ATTRIBUTE |
+| `value` | String | — | nome do atributo da action (usado em MULTIPLY/DIVIDE) |
+| `perPlayer` | boolean | `false` | em teamChallenge, true = distribui para cada membro |
+
+| Constante | Valor | Cálculo |
+|---|---|---|
+| `OPERATION_NONE` | 0 | `total` |
+| `OPERATION_MULTIPLY_BY_ATTRIBUTE` | 1 | `total * trigger.attributes[value]` |
+| `OPERATION_DIVIDE_BY_ATTRIBUTE` | 2 | `total / trigger.attributes[value]` |
 
-`operation > 0` só faz sentido quando a rule tem exatamente 1 action com atributo numérico. Nesse caso, `points[].value` deve conter o nome do atributo.
+⚠ Comentário no código: "ATENCAO opcao valida apenas para challenge com 1 rule de 1 action" — porém **não é validado**. Em challenges multi-rule, a operação usa silenciosamente o atributo do `trigger` que fechou o challenge, independentemente de qual rule disparou.
 
-### `limitPerType` — a quem o limite se aplica
+### 3.6 `Requirement` — `challenge.requirements[]` e `challenge.rewards[]`
 
-| Valor | Label |
-|---|---|
-| `0` | Player |
-| `1` | Team |
-| `2` | Gamification (global) |
+| Campo | Tipo | Descrição |
+|---|---|---|
+| `total` | int | quantidade requisitada ou concedida |
+| `type` | int | tipo do item (ver enum abaixo) |
+| `item` | String | id do item ou `"FUNIFIER_RANDOM"` |
+| `operation` | int | `0`=VERIFY, `1`=DEDUCT (afeta apenas `requirements`; em `rewards` é ignorado) |
+| `extra` | Map | campo livre (usado por `competition`) |
+| `period` | String | expressão de período (ex: `-5h;-0h`) — usado em `evaluateRequirements` |
+| `folder` | String | filtra item aleatório por catálogo/folder de loteria |
+| `restrict` | boolean | se `true`, em FUNIFIER_RANDOM respeita interval/requirements do destino |
+| `perPlayer` | boolean | em teamChallenge, true = distribui para cada membro |
+
+#### Enum Requirement.TYPE_*
+
+| Constante | Valor | Significado |
+|---|---|---|
+| `TYPE_POINT` | 0 | ponto |
+| `TYPE_CHALLENGE` | 1 | outro challenge (achievement) |
+| `TYPE_CATALOG_ITEM` | 2 | item de catálogo |
+| `TYPE_LEVEL` | 3 | nível (apenas como requisito — não pode ser recompensa nem dedutível) |
+| `TYPE_CROWN` | 4 | crown (apenas como requisito) |
+| `TYPE_LOTTERY` | 5 | sorteio (apenas como requisito) |
+| `TYPE_MYSTERY_BOX` | 6 | mystery box (apenas como requisito) |
+| `TYPE_CHARACTER_STAR_STAT` | 7 | character star stat (apenas como requisito) |
+| `TYPE_LOTTERY_TICKET` | 50 | ticket de loteria (recompensa especial) |
+
+**Comportamento real em `rewards`:**
+
+- Apenas `POINT`, `CATALOG_ITEM`, `CHALLENGE` e `LOTTERY_TICKET` são processados — outros tipos são **silenciosamente ignorados**.
+- `item == "FUNIFIER_RANDOM"`:
+  - `CATALOG_ITEM` → `CatalogManager.findRandom(query)` (ou `findValidRandom` se `restrict=true`)
+  - `LOTTERY_TICKET` → `LotteryManager.findRandom(query)` + cria `total` `LotteryTicket`s
+- `total < 0` é **convertido em positivo** internamente (`(r.total < 0) ? -r.total : r.total`).
+
+**Comportamento real em `requirements`:**
+
+- `evaluateRequirements`: para cada r, calcula `sumTotalRewards(player, type, item, period)`. Se algum < `total`, retorna `false`.
+- `deductRequirements`: aplica apenas se `operation == DEDUCT` E `type ∈ {POINT, CATALOG_ITEM, CHALLENGE}`. Cria Achievement com `total` **negativado**.
+- `period` aceita expressões como `"-5h;-0h"` ou `"month"` (interpretado por `DateUtil.fromKeywordPeriodExpression`).
+
+### 3.7 `ChallengeProgress` — coleção `challenge_progress`
+
+| Campo | Tipo | Descrição |
+|---|---|---|
+| `_id` | String | `Guid.newShortGuid()` |
+| `player` | String | userId (não teamId) |
+| `challenge` | String | challenge id |
+| `name` | String | snapshot do challenge name |
+| `image` | String | snapshot do `challenge.badge.small.url` |
+| `rules_completed` | int | quantas rules concluídas |
+| `rules_total` | int | total de rules da snapshot |
+| `percent_completed` | double | calculado em `calculatePercentCompleted` |
+| `time` | Date | momento do progresso (= `trigger.time`) |
+| `rules` | List&lt;`ChallengeRuleProgress`&gt; | snapshot por rule |
+
+**Algoritmo `calculatePercentCompleted`:**
+
+```
+se rules_total == 1 && rules_completed == 0:
+    percent_completed = rules[0].percent_completed
+senão:
+    percent_completed = min(rules_completed / rules_total, 1) * 100
+```
+
+⚠ Operação é **delete+insert** a cada fireAction parcial. Não há update incremental.
+
+### 3.8 `ChallengeRuleProgress`
+
+| Campo | Tipo | Descrição |
+|---|---|---|
+| `rule` | String | id da rule (rule._id) |
+| `completed` | boolean | rule concluiu? |
+| `times_completed` | long | contagem real |
+| `times_required` | long | meta (rule_total) |
+| `percent_completed` | double | `min(times_completed/times_required, 1)*100`; NaN → 0 |
+
+`setUncompletedBecauseOfTime()` zera `completed`, `times_completed` e `percent_completed` — chamado quando `RANGE_ALL_IN_ORDER` falha na ordenação cronológica.
+
+### 3.9 `Join` — `challenge.join`
+
+| Campo | Tipo | Descrição |
+|---|---|---|
+| `required` | Boolean | se `true`, exige `JoinLog` ativo para o challenge contar |
+| `timeframe` | String | janela temporal aplicada ao join (ex: `-0h;+1h`, `tomorrow`) |
 
-### `limitTimeScale` — escala de tempo do limite
+`JoinManager.insert` consome este timeframe ao registrar o aceite.
 
-| Valor | Label |
+### 3.10 `NotificationDefinition` — `challenge.notifications[]`
+
+Apenas notificações com `event == EVENT_WIN (0)` E `scope != SCOPE_CUSTOM (99)` são disparadas automaticamente ao concluir.
+
+| Campo | Tipo | Valores |
+|---|---|---|
+| `event` | int | `0`=WIN, `1`=CREATE, `2`=CHANGE, `3`=LOSE, `4`=REMOVE |
+| `type` | int | `0`=TEXT, `1`=VIDEO |
+| `scope` | int | `0`=PRIVATE, `1`=NEWSFEED, `99`=CUSTOM (não dispara) |
+| `content` | String | conteúdo da notificação |
+| `tag` | String | tag opcional |
+
+### 3.11 Técnicas de jogo (`techniques`)
+
+Códigos GT (Game Technique) presentes em `GameTechniqueManager`:
+
+| Código | Significado | Onde aplica |
+|---|---|---|
+| `GT01` | Points | `point_category` |
+| `GT03` | Leaderboard | `leaderboard` |
+| `GT05` | Blank Fills | `level` (sem techniques) |
+| `GT08` | Virtual Goods | `catalog_item` |
+| `GT26` | Elitism | `level` |
+| **`GT35`** | **Quests / Challenges** | **default para `challenge` sem `techniques`** |
+| `GT53` | Last Mile | `lastmile` |
+| `GT74` | Lottery | `lottery` |
+| `GT85` | Level | `level` |
+
+`autoConfigureMissingTechniqueFields()` adiciona `GT35` a todo challenge cujo array `techniques` esteja vazio ou ausente.
+
+---
+
+## 4. Endpoints
+
+Todos exigem `Authorization: Bearer <token>` (escopos validados via `AuthBean`).
+
+### `GET /v3/challenge`
+
+| Aspecto | Detalhe |
 |---|---|
-| `0` | None (sem janela de tempo) |
-| `2` | Second |
-| `3` | Minute |
-| `4` | Hour |
-| `5` | Day |
-| `6` | Week |
-| `7` | Month |
-| `8` | Year |
-
-### `notifications[].event`
-
-| Valor | Label |
+| Finalidade | Listar / filtrar challenges |
+| Implementação | `ChallengeRest.findAll` → `ChallengeManager.findAll` (Mongo aggregation) |
+| Response | Array de `Challenge` (campos `null` removidos via `JsonUtil.toJsonRemoveNullFields`) |
+
+**Query params:**
+
+| Param | Tipo | Descrição / Comportamento real |
+|---|---|---|
+| `id` | String | `_id == #` |
+| `challenge` | String | `challenge: { $regex: #, $options: 'i' }` |
+| `tags` | String | csv. Aplica `tags: { $all: [tag1, tag2] }` |
+| `to` | String | filtra elegibilidade para player/team. `"me"` → token. Expande: inclui também os teams do player. Aplica `$or: [{principals:null}, {principals:{$exists:false}}, {principals:[]}, {principals:{$in:[...]}}]` |
+| `player` | String | usado junto com `available` para popular `challenge.available`. `"me"` → token |
+| `available` | String | se igual à string `"true"` E `player` definido → executa `AchievementManager.isChallengesAvailable` em memória |
+| `q` | String | bloco JSON Mongo concatenado direto na query (`, ` + valor literal). **Risco de injeção** (ver §8) |
+| `fields` | String | csv → `$project` MongoDB |
+| `orderby` | String | nome de campo → `$sort` MongoDB |
+| `reverse` | String | `"true"` → ordem desc (`-1`) |
+| `max_results` | String | inteiro; default e fallback `100` |
+
+**Comportamento silencioso:**
+
+- `max_results <= 0` ou inválido → `100`
+- `reverse` inválido → `false`
+- `q` é inserido **literalmente** no `$match` sem sanitização — ver §8
+
+### `GET /v3/challenge/{id}`
+
+Retorna `Challenge` ou `null` (HTTP 200) — sem 404 quando não encontrado.
+
+### `POST /v3/challenge`
+
+| Aspecto | Detalhe |
 |---|---|
-| `0` | On Win (ao completar o desafio) |
-| `1` | On Create (ao criar o progresso) |
-| `2` | On Change (ao avançar no progresso) |
+| Finalidade | Cria **ou atualiza** (Jongo `save` é upsert por `_id`) |
+| Status | 201 com o objeto enviado |
+| Sanitização | ver §2.4 — principals inexistentes, rules sem actionId, requirements/rewards sem item são removidos |
 
-### `notifications[].scope`
+⚠ Não há PUT explícito. Para atualizar, envie POST com `_id` preenchido.
 
-| Valor | Label |
+**Request mínimo:**
+
+```json
+{
+  "challenge": "Faça 3 vendas hoje",
+  "rules": [{ "actionId": "venda", "total": 3, "operator": 5 }],
+  "active": true
+}
+```
+
+### `DELETE /v3/challenge/{id}`
+
+Status 204. Remove apenas o documento de `challenge` — **não remove** `achievement` (TYPE_CHALLENGE) nem `challenge_progress` associados.
+
+### `POST /v3/challenge/describe?language=pt|en`
+
+| Aspecto | Detalhe |
 |---|---|
-| `0` | Private (apenas o jogador) |
-| `1` | Newsfeed (visível no feed) |
-| `99` | Custom |
+| Finalidade | Gera descrição humanamente legível do challenge |
+| Body | Objeto `Challenge` (não precisa estar salvo) |
+| Response | `{"description": "..."}` |
 
-### `requirements[].type` / `rewards[].type`
+⚠ Pelo código (`ChallengeManager.describe`), há um `System.out.println("Language : " + lang)` no caminho — leak de debug em produção.
+⚠ Strings sem tradução cadastrada são impressas em stdout (`System.out.println(novo)`) — comportamento de "harvest" de strings não traduzidas.
+⚠ Erro de digitação: a tradução pt-BR de "semana" mapeia para "mês" (`pt.put("semana", "mês")`). Para `lang=pt*` a palavra "semana" será descrita como "mês".
 
-| Valor | Label |
+### `GET /v3/challenge/evaluate/{id}?player=&time=`
+
+| Aspecto | Detalhe |
 |---|---|
-| `0` | Point |
-| `1` | Challenge |
-| `2` | Catalog Item |
-| `3` | Level |
-| `5` | Lottery |
-| `9` | Competition |
-| `50` | Lottery Ticket (apenas em rewards) |
+| Finalidade | Diagnóstico: explica por que um player está/não está autorizado para um challenge naquele instante |
+| Não avalia | rules / contagem de logs |
+| Avalia | `time_restriction`, `who` (teamChallenge + principals), `amount_restrictions` (limit), `requirements`, `join` |
+| Param `time` | aceita milliseconds (long), zoned date ISO-8601, keyword (`today`, `yesterday`...). Default = agora |
+| Response | Objeto JSON com diagnóstico estruturado e métricas `*_ms` |
+
+**Comportamento real:**
 
-## API Endpoints
+- `principal == null` → retorna `{"status":"UNAUTHORIZED"}`
+- `challenge.when` é avaliado via `isDateAllowedAnalyze` (retorna detalhes do match)
+- Não conta logs de action — não diz "este desafio está progredindo"
 
-### Listar Desafios
-**Método:** GET  
-**Endpoint:** `/v3/challenge`
+### `GET /v3/challenge/prepared`
 
-### Buscar por ID
-**Método:** GET  
-**Endpoint:** `/v3/challenge/:id`
+Retorna toda a coleção `challenge_rule_prepared` sem filtros.
 
-### Criar / Atualizar Desafio
-**Método:** POST  
-**Endpoint:** `/v3/challenge`
+---
 
-Criar e atualizar usam o mesmo endpoint POST. Se `_id` for enviado e o documento existir, é atualizado.
+## 5. Regras de Negócio
 
-### Excluir Desafio
-**Método:** DELETE  
-**Endpoint:** `/v3/challenge/:id`
+### 5.1 Validações implícitas (no `add`)
 
-## Exemplos
+- IDs de `principals` inexistentes na coleção `principal` são **removidos silenciosamente**.
+- Rules sem `actionId`, requirements sem `item`, rewards sem `item` são **removidos silenciosamente**.
+- `_id` é gerado por `Guid.shortTimeMillis()` — **time-based**, não criptograficamente aleatório (id pode colidir em batch). Outros módulos usam `Guid.newShortGuid()` (UUID).
 
-### Challenge simples — executar uma ação N vezes
+### 5.2 Elegibilidade do principal (`isUserChallengePrincipal`)
+
+```
+se challenge.principals == null || empty:
+    AUTORIZADO (todos)
+senão se principals contém principal.id:
+    AUTORIZADO
+senão para cada p em principals:
+    se p é Team E principal.userId é membro de p.team:
+        AUTORIZADO
+senão:
+    NEGADO
+```
+
+⚠ A expansão team→members só é feita em **uma direção**: se principals tiver um team, players membros do team passam. Mas se principals tiver um player, players do mesmo team **não** passam.
+
+### 5.3 Limite (`evaluateLimit`)
+
+```
+se challenge.limitTotal == 0:
+    OK
+senão:
+    se limitTimeAmount > 0 && limitTimeScale != NONE:
+        between = DateUtil.betweenLessThan(now, limitTimeScale, limitTimeAmount)
+    senão:
+        between = [null, null]  ← janela INFINITA (foi removida a janela default de 50 anos)
+
+    se LIMIT_PER_PLAYER || LIMIT_PER_TEAM:
+        total = count Achievement {player: userId, type: CHALLENGE, item: challengeId, time: between}
+    senão LIMIT_PER_GAME:
+        total = count Achievement {type: CHALLENGE, item: challengeId, time: between}
+
+    return total < limitTotal
+```
+
+⚠ **`LIMIT_PER_TEAM` é idêntico a `LIMIT_PER_PLAYER`** — ambos contam achievements pelo `userId` (não pelo teamId). Bug conhecido herdado.
+
+### 5.4 Range e ordem cronológica
+
+- `RANGE_ALL_IN_ORDER` só engata se `rules.length > 1`.
+- `orderTime[i]` recebe a maior data do match (para ONE: `trigger.time` se própria action, senão `findLatestActionLogDateRegisteredBetweenDates`; para SEVERAL/EVERY: `findLatestActionLogDateRegisteredBetweenDates`; para aggregate: campo `max` retornado pelo pipeline).
+- Se a ordem falhar, `progress.rules_completed` é truncado em `i` e todas as rules a partir de `i` são marcadas como `setUncompletedBecauseOfTime`.
+
+### 5.5 Join obrigatório
+
+- `challenge.join.required == true` E sem `JoinLog` aberto dentro do timeframe → `continue` no loop de challenges (challenge é silenciosamente **pulado** sem registrar progress).
+- Quando o challenge conclui com join obrigatório, `JoinLog.completed` é preenchido e o id é guardado em `achievement.extra.join`.
+
+### 5.6 Propagação de origem (`propagateOrigin`)
+
+- Se `true`, todos os achievements derivados (points, rewards, deductions) recebem `extra.origin = challengeAchievement.id`.
+- LotteryTickets também recebem `extra.origin`.
+
+### 5.7 trackFullProgress
+
+- Por default, só registra `ChallengeProgress` se ao menos uma rule passou (`_true > 0`) ou se há uma única rule.
+- `trackFullProgress = true` força a gravar progress mesmo com `_true = 0` (útil para dashboards de progresso completo).
+
+### 5.8 teamChallenge — fluxo de pontos e recompensas
+
+- Pontos/rewards com `perPlayer=false` → registrados **uma vez** no `teamId`.
+- Pontos/rewards com `perPlayer=true` + `teamChallenge=true` → loop por cada membro do time, cria N achievements (um por membro).
+- `updateUserStatus` é chamado para cada `winner` individualmente.
+
+### 5.9 Multi-tenant
+
+- `ManagerFactory` é resolvido por `authBean.getApiKey()`. Cada tenant tem sua própria connection Mongo via `FrontController.getInstance(apiKey).getManagerFactory()`.
+- Não há cross-tenant em nenhuma query — toda operação roda no banco do tenant.
+
+### 5.10 Consistência
+
+- `ChallengeDaoMongo.update` é **delete+save** (NÃO atômico). Não é exposto via REST mas é chamado por `ChallengeManager.update`. Em produção, todo update real entra via POST/save (atômico).
+- `addProgress` é precedido por `deleteProgress` — pode haver corrida em fireActions concorrentes do mesmo player (último write wins).
+
+---
+
+## 6. Comportamentos Automáticos
+
+| Comportamento | Trigger | Impacto | Persistência |
+|---|---|---|---|
+| Geração de `_id` | POST sem `_id` | `Guid.shortTimeMillis()` (time-based) | `challenge._id` |
+| Set `created` | POST sem `created` | `new Date()` | `challenge.created` |
+| Set `updated` | Todo POST | `new Date()` | `challenge.updated` (sobrescrito sempre) |
+| Sanitização de principals | POST | Remove ids inexistentes | `challenge.principals` |
+| Sanitização de rules/requirements/rewards | POST | Remove itens com `actionId`/`item` ausente | arrays do challenge |
+| Auto-tagging técnica `GT35` | `GameTechniqueManager.autoConfigureMissingTechniqueFields()` | Adiciona `GT35` a challenges sem techniques | `challenge.techniques` |
+| Avaliação de challenges | `ActionManager.trackSynchonous` → `fireAction` | Avalia todos challenges com `actionId` correspondente | `achievement`, `challenge_progress` |
+| Reset de progresso ao concluir | Challenge concluído | `deleteProgress(player, challengeId)` | remove de `challenge_progress` |
+| Reset de progresso a cada fireAction parcial | Antes de gravar novo progresso | `deleteProgress` + `addProgress` | sobrescreve `challenge_progress` |
+| Conclusão de JoinLog | Challenge concluído com `join.required` | `JoinLog.completed = trigger.time` para todos os joins abertos | `join_log` |
+| Trigger Groovy BEFORE_WIN/AFTER_WIN | Challenge concluído | Executa scripts cadastrados no módulo `trigger` | side-effects definidos no trigger |
+| Notification dispatch | Challenge concluído com `notifications[].event=WIN` | Envia para `notification` (private/newsfeed) | `notification` |
+| Webhook dispatch | Ao final de `fireAction` com `result.size() > 0` | Dispara `EVENT_ACHIEVEMENT_CREATED` | externo |
+| Recursão para teams | `principal.isPlayer` com teams | Re-chama `fireAction` com `userId = teamId` | challenge avaliações em cascata |
+| Deduction silenciosa | Challenge concluído com `requirements[].operation=DEDUCT` | Cria Achievement negativo (apenas POINT/CATALOG_ITEM/CHALLENGE) | `achievement` |
+
+### Diagrama — Cascata de side-effects ao concluir
+
+```mermaid
+flowchart TD
+    A[Challenge concluído] --> B[deleteProgress]
+    B --> C{join.required?}
+    C -- sim --> D[completeAll JoinLog]
+    C -- não --> E[Achievement TYPE_CHALLENGE]
+    D --> E
+    E --> F[Trigger BEFORE_WIN/AFTER_WIN]
+    F --> G[Loop RewardPoints]
+    G --> H{teamChallenge && perPlayer?}
+    H -- sim --> H1[Achievement TYPE_POINT por membro]
+    H -- não --> H2[Achievement TYPE_POINT no userId]
+    H1 & H2 --> I[Loop Rewards]
+    I --> J{type?}
+    J -- POINT --> J1[Achievement TYPE_POINT]
+    J -- CATALOG_ITEM --> J2[FUNIFIER_RANDOM? findRandom : Achievement]
+    J -- LOTTERY_TICKET --> J3[N LotteryTickets + triggers]
+    J -- CHALLENGE --> J4[Achievement TYPE_CHALLENGE]
+    J1 & J2 & J3 & J4 --> K[Notifications EVENT_WIN]
+    K --> L[deductRequirements]
+    L --> M[updatePlayerStatus]
+    M --> N[Recursão fireAction para teams]
+```
+
+---
+
+## 7. Suportado vs NÃO Suportado
+
+### ✅ Suportado
+
+- CRUD via REST (`GET`, `POST`, `DELETE`).
+- Filtragem por id, nome (regex case-insensitive), tags (AND), elegibilidade por player/team, Mongo query livre (`q`), projeção, ordenação, paginação.
+- Avaliação reativa a partir de `Action` (síncrona, dentro do `fireAction`).
+- Range `ALL`, `ANY`, `ALL_IN_ORDER`.
+- 3 tipos de rule: `ONE`, `SEVERAL`, `EVERY` + aggregate inline/`prepared`.
+- 11 operadores em filtros (NONE/EQUAL/REGEX/GT/GTE/LT/LTE/NE/EXIST/NOT_EXIST/MAX_DISTANCE/MOD).
+- Pontuação com `MULTIPLY_BY_ATTRIBUTE` / `DIVIDE_BY_ATTRIBUTE`.
+- Recompensas: pontos, catalog items, lottery tickets, challenges em cascata.
+- `FUNIFIER_RANDOM` em catalog items e lottery tickets, com filtro por `folder`.
+- Limite por player / game (per-team é alias de per-player).
+- TimeRestriction com `repeat`, `frequency` (weekly/monthly), `allDay`, `weeklyRepeat`, `startDate/endDate/startTime/endTime/startDateTime/endDateTime`.
+- Join obrigatório com `timeframe` (incluindo expressões como `-0h;+1h`).
+- Multi-rule com ordenação cronológica.
+- Mustache + ExpressionBuilder em `rule.total` (`{{player.extra.field}} * 2`).
+- Internacionalização em `i18n` (campo livre — consumido por clientes).
+- TeamChallenge com expansão para membros.
+- Avaliação diagnóstica via `/evaluate/{id}` (sem contar logs).
+- Geração de descrição multilíngue via `/describe`.
+- Triggers `before_win` / `after_win`.
+- Webhooks via `EVENT_ACHIEVEMENT_CREATED`.
+
+### ❌ NÃO Suportado
+
+- **Sem endpoint PUT explícito**. Updates devem reusar POST com `_id` (a UI Studio faz isto). Sem versionamento ou control de concorrência.
+- **Sem cleanup em cascata**: `DELETE /v3/challenge/{id}` deixa `achievement` (`TYPE_CHALLENGE`) e `challenge_progress` órfãos.
+- **`LIMIT_PER_TEAM` é alias de `LIMIT_PER_PLAYER`** — sempre conta pelo `userId`. Bug não corrigido.
+- **`Operator.LIKE` (2)** declarado mas não tratado em `buildJsonFilter` — filtro é silenciosamente vazio.
+- **Tradução pt-BR de "semana" mapeia para "mês"** — erro em `ChallengeManager.describe`.
+- **`describe` imprime stdout** em produção (`System.out.println("Language : " + lang)` e linhas com strings sem tradução).
+- **`MULTIPLY_BY_ATTRIBUTE` / `DIVIDE_BY_ATTRIBUTE` não são validados**: comentário diz "apenas para challenge com 1 rule de 1 action", mas qualquer combinação é aceita; em multi-rule usa o `trigger` que fechou (não-determinístico).
+- **`ChallengeReward`** declarado e completo, mas **desconectado**: nenhum CRUD/manager o referencia.
+- **`LinkPrincipal`** deprecated — substituído por `Challenge.principals`. Métodos relacionados estão comentados.
+- **Campos schema-only** (não persistem getters/setters): `triggerUrl`, `order`, `items`, `levelId`, `pointCategoryId`, `pointAward`, `notify`, `notifyMessage`, `notifyUsersNow`, `notifyUsersNowMessage`, `badgeIcon`, `repeatable`, `activeStartDate`, `activeEndDate`. Se enviados via POST, são gravados no Mongo mas ignorados em qualquer leitura tipada.
+- **`TimeRestriction.compile()`** é no-op (corpo comentado) — chamado por `ChallengeManager.add` por compatibilidade histórica.
+- **`evaluatePrincipalAnalyze` não simula a avaliação de rules** — `/evaluate/{id}` não pode ser usado para prever se uma action específica concluiria o desafio.
+- **`evaluateLimit` com `limitTimeAmount==0`** usa janela `[null, null]` — significa **contagem global histórica**, sem corte temporal.
+- **Notificações com `scope == SCOPE_CUSTOM (99)`** são silenciosamente filtradas em `getNotificationsByEvent`.
+- **Sem job/scheduler para expirar challenges**: `challenge.when.endDateTime` no passado simplesmente faz `findValidChallenges` retornar o array vazio — não há limpeza de progress órfão.
+- **`recursão para teams` cria 1 fireAction por team a cada action do player**: se o player está em N times, são N+1 avaliações por dispatch (custo O(N) silencioso).
+- **`hideUntilEarned`** é lido (`isHideUntilEarned`) mas **nenhum endpoint REST aplica esse filtro**. Cliente precisa filtrar localmente.
+- **`Operator.MOD`** funciona apenas em `RULE_TYPE_SEVERAL` e em ramos com aggregate. Em ONE e EVERY o operador é ignorado.
+- **Sem agregação de progress entre rules** quando `RANGE_ANY`: a primeira rule completa fecha o challenge; demais rules não são avaliadas para fins de progresso.
+
+---
+
+## 8. Segurança e Permissões
+
+### 8.1 Autenticação
+
+- Todo endpoint depende de `@BeanParam AuthBean` (`Authorization: Bearer <jwt>`).
+- O `apiKey` extraído do bean resolve o `ManagerFactory` correto → **isolamento por tenant garantido no nível de conexão Mongo**.
+
+### 8.2 Autorização
+
+- Não há escopo específico para `challenge` — qualquer usuário com token válido pode CRUD challenges. A separação esperada é via roles no nível do gateway/frontend (Studio).
+
+### 8.3 Injeção de Mongo via `q`
+
+```java
+if(q != null && q.trim().length() > 0) { query.append(", " + q); }
+```
+
+O parâmetro `q` é **concatenado literalmente** dentro do `$match` da aggregation, sem sanitização nem parsing. Embora rode no contexto do tenant (`apiKey`), permite:
+
+- Acesso a campos que o cliente não deveria conhecer (ex: filtrar por `extra.internal_flag`).
+- Construção de operadores `$where` com JavaScript arbitrário (Mongo legacy aceita) — caminho de execução remota em servidores Mongo não-hardenizados.
+- DoS via aggregations pesadas (`$elemMatch` aninhados).
+
+**Mitigação esperada**: o gateway/Studio deve restringir uso de `q` a roles administrativas.
+
+### 8.4 Isolamento por organização
+
+- Tudo opera no `Jongo` do tenant. Sem chamadas cross-tenant em nenhum método.
+- IDs de challenge são únicos apenas dentro do tenant — o mesmo `_id` pode existir em tenants diferentes.
+
+### 8.5 Outras superfícies
+
+- `Action.attributes` é embutida no filtro Mongo via `buildJsonFilter`. Atributos do tipo `STRING` são aspeados; `NUMBER`/`BOOLEAN` são embutidos crus — se um atributo for declarado como `NUMBER` mas o valor for malformado, o build pode produzir JSON inválido (queda silenciosa do challenge no try/catch externo).
+- `rule.total` aceita string Mustache + ExpressionBuilder. ExpressionBuilder não executa código arbitrário (apenas operadores matemáticos), mas Mustache resolve referências em `player.*`, `team.*`, `rule.*`, `challenge.*` — qualquer campo destes objetos é acessível.
+
+### 8.6 Comportamentos inseguros documentados
+
+- `q` sem sanitização (§8.3).
+- `update()` não-atômico no DAO (race condition).
+- `_id` time-based (`Guid.shortTimeMillis`) — não criptograficamente aleatório.
+- `describe` imprime no stdout em produção.
+
+---
+
+## 9. Observabilidade e Troubleshooting
+
+### 9.1 Diagnóstico de challenge
+
+```
+GET /v3/challenge/<id>
+GET /v3/challenge/evaluate/<id>?player=<userId>&time=<iso8601_or_keyword_or_millis>
+```
+
+O endpoint `/evaluate` retorna métricas `*_ms` por etapa e o motivo de UNAUTHORIZED para cada bloco (`who`, `amount_restrictions`, `requirements`, `join`).
+
+### 9.2 Inspeção de progresso
+
+```js
+// MongoDB
+db.challenge_progress.find({ player: "<userId>" })
+db.challenge_progress.find({ challenge: "<challengeId>" })
+db.achievement.find({ player: "<userId>", type: 1, item: "<challengeId>" }) // TYPE_CHALLENGE = 1
+```
+
+### 9.3 Verificar quais challenges entram para uma action
+
+```js
+db.challenge.find(
+  { active: true, rules: { $elemMatch: { actionId: "<actionId>" } } },
+  { _id: 1, challenge: 1 }
+)
+```
+
+(esta é exatamente a query usada em `findValidChallenges` antes do filtro de `when` em memória)
+
+### 9.4 Verificar JoinLogs abertos
+
+```js
+db.join_log.find({
+  player: "<userId>",
+  entity: "challenge",
+  item: "<challengeId>",
+  completed: { $exists: false }
+})
+```
+
+### 9.5 Erros comuns e causas
+
+| Sintoma | Causa provável |
+|---|---|
+| Challenge nunca conclui | Verificar `active`, `when.isDateAllowed`, `teamChallenge` vs principal, `limitTotal` já atingido, `join.required` sem JoinLog ativo |
+| Conclui mas sem pontos | `RewardPoint.total == 0` ou attribute usado em MULTIPLY/DIVIDE inválido (catch silencioso) |
+| `LIMIT_PER_TEAM` parece quebrado | Bug: conta pelo `userId`, não `teamId` |
+| `RANGE_ALL_IN_ORDER` falha mesmo com rules feitas | Verificar `orderTime` no progress: o trigger atual define `trigger.time` para a rule da action corrente; outras rules pegam o LATEST log no `between` |
+| Pontos não creditados em teamChallenge | `RewardPoint.perPlayer` precisa ser `true` para distribuir aos membros |
+| Reward `FUNIFIER_RANDOM` não credita item | `restrict=true` E nenhum item disponível para o player → silenciosamente nada acontece |
+| Rule com aggregate retorna 0 sempre | Pipeline precisa retornar campos `_id`, `total` e opcionalmente `max`. Verifique `$group:{_id:..., total:{$sum:...}}` |
+| String `"FUNIFIER_RANDOM"` aparece literal em achievement | reward foi processado mas o `findRandom` retornou null E `r.item` era explicitamente `"FUNIFIER_RANDOM"` |
+| Descrição em pt-BR diz "mês" onde devia dizer "semana" | Bug em `describe` (`pt.put("semana", "mês")`) |
+| Challenge "desapareceu" entre 2 reads consecutivos | `manager.update()` foi chamado (delete+save não-atômico). Verifique se algum código fora do REST está chamando isso. |
+| Memory leak / logs ruidosos | `describe` imprime no stdout |
+
+### 9.6 Logs de avaliação
+
+`AchievementManager.fireAction` captura `Exception` por challenge num try externo e imprime `Falha ao avaliar desafio <name>` + stacktrace no stdout. Se um challenge falha em runtime (parse de Mustache, divisão por zero, etc.), o **dispatch continua** e os outros challenges seguem normalmente.
+
+---
+
+## 10. Exemplos Práticos
+
+### 10.1 Exemplo mínimo — 1 venda
 
 ```json
 {
-  "challenge": "Watch Video",
-  "description": "Watch a video to earn 10 xp",
-  "techniques": ["GT35"],
-  "rules": [
-    { "actionId": "watch_video", "operator": 5, "total": 1 }
-  ],
-  "points": [
-    { "total": 10, "category": "xp", "operation": 0 }
-  ]
+  "_id": "primeira_venda",
+  "challenge": "Primeira venda",
+  "active": true,
+  "rules": [{ "actionId": "venda" }],
+  "range": 0,
+  "points": [{ "total": 10, "category": "moedas", "operation": 0 }],
+  "techniques": ["GT35", "GT05"]
 }
 ```
 
-### Challenge com filtro de atributo
+Comportamento: cada `action_log` com `actionId=venda` registra +10 moedas. Como `limitTotal=0` (ilimitado), repete infinitamente.
+
+### 10.2 Exemplo intermediário — 3 vendas por dia
 
 ```json
 {
-  "challenge": "Sell 10 Books",
-  "description": "Sell 10 books to earn 25 xp",
-  "techniques": ["GT35"],
+  "challenge": "Vendedor diário",
+  "active": true,
   "rules": [
     {
-      "actionId": "sell",
+      "actionId": "venda",
+      "total": 3,
       "operator": 5,
-      "total": 10,
-      "filters": [
-        { "param": "product", "operator": 1, "value": "book" }
-      ]
+      "timeAmount": 1,
+      "timeScale": 5
     }
   ],
-  "points": [
-    { "total": 25, "category": "xp", "operation": 0 }
-  ]
+  "range": 0,
+  "limitTotal": 1,
+  "limitPerType": 0,
+  "limitTimeAmount": 1,
+  "limitTimeScale": 5,
+  "points": [{ "total": 100, "category": "moedas" }]
 }
 ```
 
-### Challenge com múltiplas rules (completar todas)
+- `operator: 5` (GREATER_THAN_OR_EQUAL), `total: 3`
+- `timeScale: 5` (DAY) com `timeAmount: 1` → janela das últimas 24h
+- `limitTotal: 1` + `limitPerType: 0` (PER_PLAYER) + `limitTimeAmount/Scale: 1/DAY` → 1 conquista por dia por jogador
+
+### 10.3 Exemplo avançado — multi-rule com join e rewards
 
 ```json
 {
-  "challenge": "Daily Routine",
-  "techniques": ["GT35"],
-  "range": 0,
+  "challenge": "Onboarding completo",
+  "active": true,
+  "range": 2,
+  "join": { "required": true, "timeframe": "+7d" },
+  "trackFullProgress": true,
   "rules": [
-    { "actionId": "login", "operator": 5, "total": 1 },
-    { "actionId": "comment", "operator": 5, "total": 3 }
+    { "actionId": "criar_perfil" },
+    { "actionId": "completar_tutorial" },
+    { "actionId": "primeira_compra" }
   ],
-  "points": [
-    { "total": 50, "category": "xp", "operation": 0 }
-  ]
+  "requirements": [
+    { "total": 1, "type": 3, "item": "novato", "operation": 0 }
+  ],
+  "rewards": [
+    { "total": 1, "type": 2, "item": "FUNIFIER_RANDOM", "folder": "catalogo_bonus", "restrict": true },
+    { "total": 50, "type": 0, "item": "xp" }
+  ],
+  "points": [{ "total": 500, "category": "xp" }],
+  "notifications": [
+    { "event": 0, "type": 0, "scope": 1, "content": "Bem-vindo! Você completou o onboarding 🎉" }
+  ],
+  "principals": [],
+  "propagateOrigin": true,
+  "tags": ["onboarding", "novato"]
 }
 ```
 
-### Challenge com limite de frequência (1x por dia por jogador)
+- `range: 2` (ALL_IN_ORDER) — as três actions precisam acontecer **nessa sequência cronológica**.
+- `join.required=true` + `timeframe: "+7d"` → o jogador precisa aceitar via `JoinLog`; tem 7 dias para concluir.
+- `requirements`: precisa já possuir o nível `novato` (TYPE_LEVEL=3) — não é dedutível.
+- `rewards`: 1 catalog item aleatório do `catalogo_bonus` (respeitando interval/requirements do item via `restrict=true`) + 50 pontos xp.
+- `trackFullProgress: true` → grava `challenge_progress` mesmo se zero rules completas.
+- `propagateOrigin: true` → todos os achievements derivados terão `extra.origin = <id-do-achievement-do-challenge>`.
+
+### 10.4 Exemplo com `techniques` — categorização explícita por mecânica de jogo
 
 ```json
 {
-  "challenge": "Daily Check-in",
-  "techniques": ["GT35"],
+  "_id": "explorador_semanal",
+  "challenge": "Explorador Semanal",
+  "description": "Visite 5 lugares diferentes em uma semana",
+  "active": true,
+  "techniques": ["GT35", "GT05"],
   "rules": [
-    { "actionId": "checkin", "operator": 5, "total": 1 }
+    {
+      "actionId": "checkin",
+      "total": 5,
+      "operator": 5,
+      "timeAmount": 1,
+      "timeScale": 6,
+      "filters": [
+        { "param": "lugar", "operator": 9, "value": "" }
+      ]
+    }
   ],
-  "points": [{ "total": 5, "category": "xp", "operation": 0 }],
+  "range": 0,
   "limitTotal": 1,
   "limitPerType": 0,
   "limitTimeAmount": 1,
-  "limitTimeScale": 5
+  "limitTimeScale": 6,
+  "points": [{ "total": 200, "category": "xp" }],
+  "tags": ["exploracao", "semanal"]
 }
 ```
 
-### Challenge com notificação ao completar
+**Comportamento da propriedade `techniques`:**
 
-```json
-{
-  "challenge": "First Comment",
-  "techniques": ["GT35"],
-  "rules": [{ "actionId": "comment", "operator": 5, "total": 1 }],
-  "points": [{ "total": 10, "category": "xp", "operation": 0 }],
-  "notifications": [
-    {
-      "event": 0,
-      "type": 0,
-      "scope": 0,
-      "content": "{{player.name}} completed {{item.name}}"
-    }
-  ]
-}
-```
+- `techniques` é um `List<String>` com códigos GT (Game Technique). É **persistido literalmente** — o backend não valida o conteúdo do array.
+- Se o cliente **não enviar** `techniques` (campo ausente, `null` ou array vazio), o método `GameTechniqueManager.autoConfigureMissingTechniqueFields()` adiciona automaticamente `["GT35"]` na próxima execução desse job. ⚠ Isso **não acontece no save** — só quando o job auto-config roda.
+- Se o cliente enviar `techniques` com qualquer valor (mesmo códigos inexistentes como `["GTX99"]`), o array é gravado **as-is** e o auto-config **não sobrescreve**.
+- Códigos comuns para challenges:
+  - `GT35` — Quests / Challenges (técnica principal, default)
+  - `GT05` — Blank Fills (preenchimento/coleção)
+  - `GT26` — Elitism (desafios exclusivos)
+- Os códigos GT são consumidos pelo módulo `technique` (coleção `technique`) e usados em relatórios / dashboards de framework de gamificação. **Não afetam a avaliação do challenge** (não entram em `fireAction`).
+
+**Detalhes deste exemplo:**
+
+- `techniques: ["GT35", "GT05"]` declara explicitamente que este challenge implementa Quests + Blank Fills (cumular 5 lugares diferentes).
+- `filters[0]`: `operator: 9` (EXIST) sobre `lugar` — exige que o atributo exista no `action_log.attributes.lugar`. (Não há operador "DISTINCT" nativo — para "5 lugares diferentes" o controle de unicidade depende de regras do filtro ou aggregate customizado.)
+- `timeScale: 6` (WEEK) com `timeAmount: 1` → janela das últimas 7 dias.
+- `limitTimeScale: 6` (WEEK) + `limitTotal: 1` → 1 conquista por semana por jogador.
 
-### Challenge com pré-requisito (desbloqueia após completar outro desafio)
+### 10.5 Anti-pattern — usar `MULTIPLY_BY_ATTRIBUTE` em challenge multi-rule
 
 ```json
 {
-  "challenge": "Advanced Task",
-  "techniques": ["GT35"],
-  "rules": [{ "actionId": "upload", "operator": 5, "total": 5 }],
-  "points": [{ "total": 100, "category": "xp", "operation": 0 }],
-  "requirements": [
-    { "type": 1, "total": 1, "item": "first_comment_challenge_id" }
+  "challenge": "Comissão sobre venda",
+  "rules": [
+    { "actionId": "venda" },
+    { "actionId": "fechamento_mes" }
+  ],
+  "range": 0,
+  "points": [
+    { "total": 1, "category": "comissao", "operation": 1, "value": "valor" }
   ]
 }
 ```
 
-## Como Validar se foi Criado Corretamente
+**Por que não fazer:**
 
-Após salvar com `funifier_save`, confirme com `funifier_get`:
+- O comentário no código diz claramente: "ATENCAO opcao valida apenas para challenge com 1 rule de 1 action".
+- Quando o challenge fechar, `trigger.attributes["valor"]` será o do **trigger que disparou o fechamento** (`fechamento_mes`), não o do `venda`. Resultado: comissão de zero (se `fechamento_mes` não tem `valor`) ou comissão calculada sobre atributo errado.
+- Sem warning, sem log, sem erro — apenas zero pontos ou pontos arbitrários.
 
-```
-funifier_get type=challenge id=<id_retornado>
-```
+**Correção:** use challenge single-rule com action `venda`, ou crie uma `Action` dedicada com `points` próprios.
 
-Ou liste e filtre:
+### 10.6 Anti-pattern — usar `q` cru do cliente
 
-```
-funifier_list type=challenge search=<nome_do_challenge>
+```http
+GET /v3/challenge?q={"extra.secret_flag":true}
 ```
 
-Para testar se o challenge está funcionando, registre a ação e verifique o progresso do jogador:
+**Por que não fazer:**
 
-```
-POST /v3/action/log  { "actionId": "...", "player": "player_id" }
-GET /v3/challenge/progress?player=player_id
-```
+- `q` é concatenado direto no aggregation sem parse. Cliente pode ler qualquer campo, incluindo flags internas ou de outros tenants se a config Mongo permitir.
+- Cliente pode forçar `$where` com JavaScript se o Mongo aceitar (deprecated mas habilitado em alguns clusters legados).
+
+**Correção:** validar/sanitizar `q` no gateway; restringir ao subconjunto de campos públicos.
+
+---
 
 ## Checklist de Configuração
 
-- [ ] `challenge` (nome) preenchido
-- [ ] `techniques` com pelo menos um código GT (ex: `["GT35"]`)
-- [ ] `rules` com `actionId` existente, `operator` e `total` definidos
-- [ ] `range` definido quando há mais de uma rule
-- [ ] `points` com `category` existente
-- [ ] Ações referenciadas nas rules existem (`funifier_list type=action`)
-- [ ] Pontos referenciados existem (`funifier_list type=point`)
-- [ ] Validado com `funifier_get` após salvar
+- [ ] Campo `challenge` (nome) preenchido — sem ele a entidade aparece sem rótulo na UI.
+- [ ] Todas as `rules[].actionId` apontam para uma `Action` existente — itens sem actionId são removidos no save.
+- [ ] `Action.attributes` declara o tipo correto (`STRING`/`NUMBER`/`BOOLEAN`) para os atributos usados em `ChallengeRuleFilter.param`.
+- [ ] Se `range = ALL_IN_ORDER`, garantir que `rules` tem mais de uma entrada (com 1 só rule, o flag é ignorado).
+- [ ] Se `limitTotal > 0` e quer janela temporal, definir `limitTimeAmount > 0` e `limitTimeScale != NONE` (NONE = janela infinita).
+- [ ] Se `teamChallenge = true`, `principals` deve conter teamIds (não playerIds) ou estar vazio.
+- [ ] Se `MULTIPLY_BY_ATTRIBUTE` ou `DIVIDE_BY_ATTRIBUTE` em `RewardPoint`, garantir challenge single-rule + single-action.
+- [ ] Para `LOTTERY_TICKET`/`CATALOG_ITEM` em rewards com `FUNIFIER_RANDOM`, definir `folder` para limitar o universo.
+- [ ] Se `join.required = true`, registrar primeiro `JoinLog` via `JoinManager.insert` antes de esperar a conclusão.
+- [ ] Para `RANGE_ALL_IN_ORDER`, considerar que `orderTime` para rules de action diferente do trigger usa `findLatestActionLogDateRegisteredBetweenDates` — uma rule pode parecer "fora de ordem" se o log mais recente do tipo está fora do `between`.
+- [ ] Não confie em `LIMIT_PER_TEAM` — usa `userId`. Para limite real por time, modelar via outro campo ou aceitar comportamento PER_PLAYER.
+- [ ] Não confie em `Operator.LIKE` em filtros — equivale a filtro vazio. Use `REGEX`.
+- [ ] Para deduzir pontos/items em requirements: `operation = 1` (DEDUCT) e `type ∈ {POINT, CATALOG_ITEM, CHALLENGE}` — outros tipos não são dedutíveis.
+- [ ] Antes de deletar um challenge, considere deletar manualmente os achievements e progress associados — não há cascade.
+- [ ] Para diagnóstico em produção, use `/evaluate/{id}` em vez de tentar reproduzir o pipeline manualmente.
+- [ ] Não envie `q` vindo do cliente sem sanitização — risco de injeção MongoDB.
+- [ ] Atenção ao bug de tradução `pt.put("semana", "mês")` em `describe(lang="pt*")`.
+- [ ] Em produção com logs limpos, esteja ciente do leak de stdout em `describe`.