funifier-mcp 0.2.25 → 0.2.27

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

@@ -1,136 +1,656 @@
-# Question (Pergunta)
+# `question`
 
 **Acesso Studio:** `/studio/question`
 **API Endpoint:** `/v3/question`
+**Coleção MongoDB:** `question` (definições) e `question_log` (respostas dos jogadores)
 
-## O que é
+> Documentação de engenharia reversa baseada **exclusivamente** no código-fonte do projeto `funifier-service` (commit `830037e`). Fonte primária:
+> `QuestionRest.java`, `QuestionManager.java`, `Question.java`, `QuestionLog.java`, `Choice.java`, `Feedback.java`, `InteractionModel.java` (+ `MatchingModel`, `MatchingItem`, `MatchingPair`, `MissingWordsModel`, `Blank`, `PoolItem`, `DragDropTextModel`, `Target`) e `presentation/PresentationSettings.java`.
 
-Configuração de perguntas e respostas para os jogadores. Permite criar perguntas em diferentes formatos (múltipla escolha, verdadeiro/falso, com mídia), definir respostas corretas ou colher opiniões, e aplicar pesos diferentes para as perguntas. A apresentação pode ser no formato tradicional ou em mini games como caça-palavras e cruzadinhas.
+---
 
-## Quando usar
+## 1. Visão Geral
 
-- Para criar quizzes e avaliações
-- Para pesquisas de opinião
-- Para treinamentos e capacitação
-- Para mini games educativos
+O módulo `question` implementa **perguntas avaliáveis e coletas de resposta** dentro da gamificação Funifier. Ele tem dois documentos distintos:
 
-## Checklist de Configuração no Studio
+- **`question`** — a *definição* da pergunta (enunciado, opções, gabarito, tipo, peso, feedbacks, limites).
+- **`question_log`** — o *registro de cada resposta* dada por um jogador, já com a nota calculada (`grade`) e o percentual de acerto (`percent`).
 
-- [ ] Definir tipo da pergunta (MULTIPLE_CHOICE, TRUE_FALSE, etc.)
-- [ ] Definir título e texto da pergunta
-- [ ] Criar opções de resposta com grades (pontuação)
-- [ ] Definir se permite uma ou múltiplas respostas (select)
-- [ ] Configurar embaralhamento (shuffle)
-- [ ] Definir peso/grade da pergunta
+Papel arquitetural:
 
-## API Endpoints
+- É um módulo de **avaliação síncrona**: ao registrar um `question_log`, o `QuestionManager` correge a resposta no mesmo request (`insertLog`) e devolve `grade`, `percent`, `feedbacks` e eventuais `errors` na própria resposta HTTP.
+- Funciona **standalone** ou como **peça interna de um `quiz`**. Quando o log carrega `quiz_log`, o módulo recalcula o progresso do quiz (`QuizManager.updateLog`).
+- É uma **porta de entrada para o motor de gamificação**: se a pergunta tiver o campo `action`, responder gera um `ActionLog` que é processado por `ActionManager.trackWithRestrictions`, podendo creditar pontos, completar desafios e disparar achievements.
+- Persiste tudo diretamente via `Jongo` (MongoDB). **Não há `Repository`/`Dao` dedicado** — a manipulação é feita dentro do próprio `QuestionManager`.
 
-### Listar Perguntas
-**Método:** GET
-**Endpoint:** `/v3/question`
+Problemas que resolve:
 
-### Criar Pergunta
-**Método:** POST
-**Endpoint:** `/v3/question`
+- Quizzes, avaliações, provas, pesquisas de opinião e mini-games (matching, completar lacunas, arrastar-e-soltar).
+- Correção automática multi-formato (8 tipos de pergunta) com pesos configuráveis.
+- Coleta auditável de respostas por jogador, com limites de tentativas e integração com triggers/actions.
+
+Relação com outros módulos (confirmada no código):
+
+| Módulo | Direção | Como |
+|---|---|---|
+| `quiz` | `question` → `quiz` | `insertLog` chama `QuizManager.updateLog(quiz_log)` quando o log pertence a um quiz |
+| `action` / `achievement` | `question` → `action` | `insertLog` cria um `ActionLog` e chama `ActionManager.trackWithRestrictions` quando `question.action` está setado |
+| `trigger` | bidirecional | eventos `before_create`/`after_create`/`before_update`/`after_update` na coleção `question`; `before_create`/`after_create` na coleção `question_log` |
+| `player` | leitura | `PlayerManager.findById` em `verifyLimit` e na montagem do contexto de feedback |
+| `technique` (GameTechnique) | escrita pontual | `GameTechniqueManager.autoConfigureMissingTechniqueFields` atribui o código `GT05` a perguntas sem `techniques` |
+
+> **Fora de escopo deste módulo** (não servidos por `/v3/question`): a coleção `partner_question` (mesma classe `Question`, mas outra coleção) e o pacote `com.funifier.engine.system.question` (perguntas de suporte do sistema: `accountId`, `topic`, `subject`, `description` — domínio totalmente distinto). Ver §7.
+
+---
+
+## 2. Arquitetura e Fluxos
+
+### 2.1 Classes envolvidas
+
+| Classe | Papel |
+|---|---|
+| `com.funifier.rest.v3.rest.QuestionRest` | Controller REST v3 (`/v3/question`) |
+| `com.funifier.engine.question.QuestionManager` | Manager: CRUD, validação, correção por tipo, limites, integração quiz/action |
+| `com.funifier.engine.question.Question` | Documento raiz da coleção `question` |
+| `com.funifier.engine.question.QuestionLog` | Documento da coleção `question_log` (resposta do jogador) |
+| `Choice` | Opção de resposta (formato legado) |
+| `Feedback` | Mensagem de retorno por evento (`correct`/`partial_correct`/`wrong`) |
+| `InteractionModel` + `MatchingModel`/`MissingWordsModel`/`DragDropTextModel` | Modelo "novo" para tipos especiais (substitui a avaliação legada por `choices`) |
+| `MatchingItem`, `MatchingPair`, `Blank`, `PoolItem`, `Target` | Sub-elementos dos modelos novos |
+| `presentation.PresentationSettings` | Configuração de UI (`FeedbackSettings`, `StuckSettings`) — apenas armazenada |
+
+Não há Scheduler/Job/Runner que processe `question`/`question_log` (confirmado por busca no projeto).
+
+### 2.2 Pipeline de criação/atualização — `insert(Question)`
+
+`QuestionManager.insert` (linhas 69-104) é um **upsert idempotente por `_id`**:
+
+```
+[1] validate(question)                       → coleta erros por tipo
+    se erros.size() > 0 → NÃO salva; retorna a lista de erros (NÃO lança exceção)
+[2] gera _id (Guid.newShortGuid) se vazio
+[3] busca documento atual por _id
+    se não existe → created = now; create = true
+    se existe     → mantém created original; create = false
+[4] updated = now (sempre)
+[5] trigger before_create  OU  before_update   (coleção "question")
+[6] normalizeQuestionForPersistence(question)  → normaliza aliases do dragDropText
+[7] c.save(question)                            → upsert no Mongo
+[8] trigger after_create  OU  after_update      (coleção "question")
+```
+
+```mermaid
+flowchart TD
+  A["POST /v3/question"] --> B["QuestionManager.insert"]
+  B --> C{"validate() vazio?"}
+  C -->|"não"| Z["retorna exceptions<br/>NÃO salva — HTTP 201"]
+  C -->|"sim"| D["gera _id se vazio"]
+  D --> E{"_id já existe?"}
+  E -->|"não"| F["created=now<br/>trigger before_create"]
+  E -->|"sim"| G["mantém created<br/>trigger before_update"]
+  F --> H["updated=now<br/>normalizeQuestionForPersistence"]
+  G --> H
+  H --> I["c.save(question)"]
+  I --> J["trigger after_create / after_update"]
+```
+
+> **Atenção (síncrono, sem transação):** não há transação MongoDB. Os triggers `before_*` rodam **antes** do `save`; se um trigger lançar, o comportamento depende do `TriggerManager` (fora do escopo deste módulo).
+
+### 2.3 Pipeline de resposta — `insertLog(QuestionLog, async)`
+
+`QuestionManager.insertLog` (linhas 425-583) corrige e persiste a resposta **de forma síncrona**:
+
+```
+[1] valida obrigatórios: log != null, log.question, log.player
+[2] carrega Question por _id (erro "question dont exist" se não achar)
+[3] verifyLimit(question, log, errors)         → checa limite de tentativas
+    se há erros → encerra sem salvar
+[4] dispatch por question.type → answerXxx(...) → calcula log.percent e log.grade
+[5] monta log._id:
+       se log.quiz_log != null  → id = quiz_log + "_" + question  (impede 2ª resposta no quiz)
+       senão                      → id = Guid.newShortGuid()
+[6] log.time = now (se ausente)
+[7] feedbacks = question.getFeedback(log.grade)    ← chave é grade, NÃO percent (ver §5)
+[8] monta ActionLog (al) com id=log.id, actionId=question.action, userId=log.player
+[9] trigger before_create (coleção "question_log", com TriggerContext)
+[10] save(question_log)
+[11] trigger after_create
+[12] meta.attemptsCount = count(question_log {player, question})
+[13] se quiz_log != null → QuizManager.updateLog(quiz_log)
+[14] resolve mensagens de feedback via Mustache (player, log, feedbacks, errors, question)
+[15] se question.action != null:
+        valida action existe (erro se não) → ActionManager.trackWithRestrictions(al, async)
+        adiciona result["action"]
+[16] result = { log, feedbacks?, errors?, meta? , action? }
+```
+
+```mermaid
+sequenceDiagram
+  participant C as Client
+  participant QR as QuestionRest
+  participant QM as QuestionManager
+  participant TM as TriggerManager
+  participant QZ as QuizManager
+  participant AM as ActionManager
+  C->>QR: POST /v3/question/log
+  QR->>QM: insertLog(log, async)
+  QM->>QM: valida + carrega Question
+  QM->>QM: verifyLimit
+  QM->>QM: answerXxx → percent, grade
+  QM->>TM: execute(before_create, question_log)
+  QM->>QM: save(question_log)
+  QM->>TM: execute(after_create, question_log)
+  alt log.quiz_log != null
+    QM->>QZ: updateLog(quiz_log)
+  end
+  alt question.action != null
+    QM->>AM: trackWithRestrictions(actionLog, async)
+    AM-->>QM: action (points/achievements)
+  end
+  QM-->>QR: {log, grade, percent, feedbacks, action, errors}
+```
+
+### 2.4 Avaliação por tipo (métodos `answerXxx`)
+
+| Tipo | Método | Formato de `answer` | Cálculo de `percent` |
+|---|---|---|---|
+| `MULTIPLE_CHOICE` | `answerMultipleChoice` | `List<String>` (valores `choice.answer`) | **soma** de `choice.grade` das opções marcadas. **Sem limite superior** (pode passar de 1.0) |
+| `TRUE_FALSE` | `answerTrueFalse` | `Boolean` | `1` se `answer == question.correctAnswer`, senão `0` |
+| `MATCHING` | `answerMatching` | `Map<String,String>` (`leftId`→`rightId`) | modelo: `correct/totalPairs` (`per_pair`) ou tudo-ou-nada (`all_or_nothing`); legado: `1/nº choices` por par correto (`answer`+`match`) |
+| `SHORT_ANSWER` | `answerShortAnswer` | `String` | **maior** `choice.grade` entre as opções que casam com o texto (case-sensitive opcional, default `false`) |
+| `SELECT_MISSING_WORDS` | `answerSelectMissingWords` | `Map<String,String>` (`blankId`→`optionId`) | modelo: `correct/nº blanks` (`per_blank`) ou `all_or_nothing`; legado: `1/nº lacunas [[n]]` por acerto |
+| `DRAG_AND_DROP_INTO_TEXT` | `answerDragAndDropIntoText` | `Map<String,String>` (`targetId`→`optionId`) | modelo: `correct/nº targets` (`per_target`) ou `all_or_nothing`; legado: `1/nº lacunas [[n]]` por acerto |
+| `ESSAY` | `answerEssay` | `String` | **sempre `0`** (não há correção automática) |
+| `CUSTOM` | `answerCustom` | qualquer | **sempre `0`** (sem avaliação) |
+
+**Em todos os tipos**: `log.grade = question.grade * percent` e `log.percent = percent`. Ou seja, `grade` é o `percent` multiplicado pelo peso da pergunta.
+
+Pseudocódigo do dispatcher (`insertLog`, linhas 450-473):
+
+```
+se type == MULTIPLE_CHOICE          → answerMultipleChoice
+senão se type == TRUE_FALSE         → answerTrueFalse
+senão se type == MATCHING           → answerMatching
+senão se type == SHORT_ANSWER       → answerShortAnswer
+senão se type == SELECT_MISSING_WORDS → answerSelectMissingWords
+senão se type == DRAG_AND_DROP_INTO_TEXT → answerDragAndDropIntoText
+senão se type == ESSAY              → answerEssay
+senão se type == CUSTOM             → answerCustom
+(nenhum else: tipo desconhecido NÃO calcula grade/percent → ficam null)
+```
+
+> **Modelo novo vs legado:** para `MATCHING`, `SELECT_MISSING_WORDS` e `DRAG_AND_DROP_INTO_TEXT`, a correção usa `question.model` **se** ele estiver presente e `model.interactionType` for `null` ou igual ao `type`. Caso contrário cai no caminho **legado** baseado em `choices` e marcadores `[[n]]` no campo `question`.
+
+### 2.5 Cálculo de "já respondida" — campo `answered` (runtime, não persistido)
+
+`findAllPaginated` (linhas 121-186) injeta o booleano `answered` **apenas quando `player` é informado**, via pipeline `$facet`:
+
+```
+{ $match: { _id: { $exists: true } , <id?> , <q?> } }
+{ $facet: {
+    p1: [ { $match: { _id: { $in: <ids_respondidos> } } }, { $addFields: { answered: true } } ],
+    p2: [ { $match: { _id: { $nin: <ids_respondidos> } } }, { $addFields: { answered: false } } ]
+} }
+{ $project: { all: { $concatArrays: [ "$p1", "$p2" ] } } }
+{ $unwind: "$all" }
+{ $replaceRoot: { newRoot: "$all" } }
+```
+
+`<ids_respondidos>` vem de `getAnsweredQuestionIds`: `db.question_log.distinct("question", { player: #, time: {$gte/$lte} })`. Os filtros `answered_min`/`answered_max` aceitam timestamp RFC 3339 **ou** keywords relativas (`-1d`, `-30m`, etc.) via `DateUtil.fromKeyword`.
+
+---
+
+## 3. Estrutura dos Objetos
+
+> Todas as classes do módulo usam `@JsonIgnoreProperties(ignoreUnknown=true)` → **qualquer campo desconhecido enviado é silenciosamente descartado** (sem erro, sem log).
+
+### 3.1 `Question` — documento da coleção `question`
+
+| Campo | Tipo | Padrão | Obrigatório | Descrição |
+|---|---|---|---|---|
+| `_id` | String | GUID curto se vazio | — | Identificador. Definido pelo cliente ou gerado em `insert` |
+| `quiz` | String | `null` | não | ID do quiz pai. **Apenas referência informativa** — o vínculo de resposta é feito via `quiz_log` no log |
+| `type` | String | `null` | **sim** | Tipo da pergunta (enum, §3.5) |
+| `title` | String | `null` | **sim** (exceto `CUSTOM`) | Título usado no admin. Exigido por `validateBasic` |
+| `question` | String | `null` | depende | Enunciado. Obrigatório (com `[[1]]`) nos caminhos **legados** de `DRAG_AND_DROP_INTO_TEXT` e `SELECT_MISSING_WORDS` |
+| `grade` | double | `1` | não | **Peso** da pergunta. `log.grade = grade * percent` |
+| `choices` | `List<Choice>` | `[]` | depende | Opções (obrigatório em `MULTIPLE_CHOICE`; usado nos caminhos legados) |
+| `i18n` | `Map<String,Map<String,String>>` | `{}` | não | Traduções. **Apenas armazenado** — nenhuma lógica de servidor o lê |
+| `techniques` | `List<String>` | `null` | não | Códigos de técnica de jogo (GT). Default `GT05` via job de técnicas |
+| `select` | String | `null` | **sim** p/ `MULTIPLE_CHOICE` | `one_answer` / `multiple_answers`. **Dica de UI** — a correção NÃO força escolha única |
+| `answerNumbering` | String | `null` | não | `arabic_numerals` / `roman_numerals` / `uppercase_letters` (UI) |
+| `correctAnswer` | Boolean | `null` | **sim** p/ `TRUE_FALSE` | Resposta correta do verdadeiro/falso |
+| `caseSensitive` | Boolean | `null` | **sim** p/ `SHORT_ANSWER` | Na avaliação assume `false` se `null` |
+| `totalLines` | Integer | `null` | não | Linhas sugeridas para `ESSAY` (UI) |
+| `shuffle` | boolean | `false` | não | Embaralhar opções (UI) |
+| `feedbacks` | `List<Feedback>` | `[]` | não | Mensagens por evento (§3.4) |
+| `presentation` | `PresentationSettings` | `null` | não | Settings de UI (feedback/stuck) — apenas armazenado |
+| `model` | `InteractionModel` | `null` | não | Modelo novo para `MATCHING`/`SELECT_MISSING_WORDS`/`DRAG_AND_DROP_INTO_TEXT` |
+| `extra` | `Map<String,Object>` | `{}` | não | Campos livres (imagens, vídeo, metadados) |
+| `created` | Date | auto | — | Definido no primeiro `insert`; preservado em updates |
+| `updated` | Date | auto | — | Atualizado a cada `insert` |
+| `limit` | `Limit` | `null` | não | Limite de respostas (§3.6) |
+| `requires` | `List<Requirement>` | `[]` | não | **Aceito e persistido, mas NUNCA lido** pelo `QuestionManager` (§7) |
+| `action` | String | `null` | não | ID/nome da action disparada ao responder |
+
+**Campos computados (não persistem na coleção `question`):**
+- `answered` (boolean) — injetado em runtime no `GET /v3/question` quando `player` é informado (§2.5).
+
+**Campos aceitos e silenciosamente ignorados:**
+- Qualquer atributo não declarado nas classes (`@JsonIgnoreProperties(ignoreUnknown=true)`). Exemplos comuns que **não existem** no modelo de `Choice` e seriam descartados: `gradePercent`, `gradeCheck`.
+
+### 3.2 `QuestionLog` — documento da coleção `question_log`
+
+| Campo | Tipo | Padrão | Obrigatório | Descrição |
+|---|---|---|---|---|
+| `_id` | String | GUID, ou `quiz_log + "_" + question` | — | Em quiz, o id composto impede responder a mesma pergunta 2x |
+| `player` | String | — | **sim** | Jogador que respondeu. `"me"` resolve para o player do token |
+| `question` | String | — | **sim** | ID da pergunta respondida |
+| `answer` | Object | — | **sim** | Resposta crua; formato varia por tipo (§2.4) |
+| `percent` | Double | calculado | — | Percentual de acerto (saída da correção) |
+| `grade` | Double | calculado | — | `question.grade * percent` (saída da correção) |
+| `time` | Date | now | — | Momento da resposta |
+| `mentor` | String | `null` | não | Instrutor avaliador. **Aceito/persistido, mas sem workflow** que o utilize (§7) |
+| `extra` | `Map<String,Object>` | `null` | não | Campos adicionais |
+| `quiz` | String | `null` | não | Referência ao quiz |
+| `quiz_log` | String | `null` | não | Vincula a resposta ao log do quiz (dispara `QuizManager.updateLog`) |
+
+### 3.3 `Choice` — opção de resposta (formato legado)
+
+| Campo | Tipo | Descrição |
+|---|---|---|
+| `answer` | String | Identificador/valor da opção (referenciado pela resposta do jogador) |
+| `label` | String | Texto amigável exibido |
+| `grade` | Double | Percentual desta opção (0..1). Em `MULTIPLE_CHOICE` soma; em `SHORT_ANSWER` usa-se o máximo |
+| `match` | String | Sub-pergunta do `MATCHING` legado |
+| `extra` | `Map<String,Object>` | Metadados |
+
+### 3.4 `Feedback`
+
+| Campo | Tipo | Descrição |
+|---|---|---|
+| `event` | String | `correct` / `partial_correct` / `wrong` |
+| `message` | String | Texto (processado por Mustache com `{player, log, feedbacks, errors, question}`) |
+
+### 3.5 Enum de tipos (`Question.TYPE_*`)
+
+| Valor | Significado operacional |
+|---|---|
+| `MULTIPLE_CHOICE` | Múltipla escolha; nota = soma dos `grade` das opções marcadas |
+| `TRUE_FALSE` | Verdadeiro/Falso; nota cheia ou zero |
+| `MATCHING` | Relacionar colunas (left↔right); pontuação por par ou tudo-ou-nada |
+| `SHORT_ANSWER` | Resposta curta em texto; nota = maior `grade` entre as opções que casam |
+| `SELECT_MISSING_WORDS` | Selecionar palavras em lacunas (dropdown) |
+| `DRAG_AND_DROP_INTO_TEXT` | Arrastar opções para lacunas do texto |
+| `ESSAY` | Dissertativa; **nota sempre 0** (correção manual não implementada) |
+| `CUSTOM` | Customizada; **sem validação e sem avaliação** (nota 0) |
+
+Outros enums:
+- `select`: `one_answer`, `multiple_answers`.
+- `answerNumbering`: `arabic_numerals`, `roman_numerals`, `uppercase_letters`.
+- `scoring` (modelos novos): `per_pair`/`per_blank`/`per_target` (default) ou `all_or_nothing`.
+
+### 3.6 `Limit` — limite de respostas
+
+| Campo | Tipo | Descrição |
+|---|---|---|
+| `total` | Object | Número **ou** expressão Mustache+exp4j (`{{player.extra.max}}`) avaliada em runtime |
+| `per` | String | `player` ou `gamification`. **`team` é definido mas NÃO tratado** em `verifyLimit` (§5/§7) |
+| `every` | String | Janela (ex.: `1d`, `5h`). Sem `every` → janela de `-10y` |
+| `query` | String | Filtro Mongo adicional (Mustache, ex.: `attributes.city:'{{player.extra.city}}'`) |
+
+### 3.7 `InteractionModel` e submodelos (modelo novo)
+
+`InteractionModel`: `interactionType` (`MATCHING`/`SELECT_MISSING_WORDS`/`DRAG_AND_DROP_INTO_TEXT`), `questionHtml`, `shufflePool`, mais um dos modelos:
+
+- **`MatchingModel`**: `left: List<MatchingItem{id,text}>`, `right: List<MatchingItem>`, `solution: List<MatchingPair{leftId,rightId}>`, `solutions: Map<String,String>` (forma alternativa), `scoring`.
+- **`MissingWordsModel`**: `html` (com `[[1]]`...), `blanks: List<Blank>`, `scoring`. `Blank`: `id`, `options: List<PoolItem{id,text}>`, `correctId` (JSON: `correctOptionId`, alias `correctId`).
+- **`DragDropTextModel`**: `html` (JSON `text`, alias `html`), `pool` (JSON `optionsPool`, alias `pool`), `targets: List<Target>`, `scoring`. `Target`: `id`, `accepts` (JSON `acceptedOptionIds`, alias `accepts`), `correctId` (JSON `correctOptionId`, alias `correctId`).
+
+> **Normalização assimétrica (`normalizeQuestionForPersistence`, linhas 42-65):** apenas o `dragDropText` é "endurecido" — o manager copia manualmente `text→html`, `optionsPool→pool`, `target.acceptedOptionIds→accepts`, `target.correctOptionId→correctId` antes de salvar. `MatchingModel` e `MissingWordsModel` dependem **somente** dos `@JsonAlias` do Jackson. Ver §7.
+
+### 3.8 Técnicas de jogo (`techniques`)
+
+| Código | Origem no código | Significado |
+|---|---|---|
+| `GT05` | `GameTechniqueManager` (`BLANKFILLS_CODE`) | Atribuído automaticamente a perguntas **sem** `techniques` durante `autoConfigureMissingTechniqueFields` |
+
+Outros códigos GT podem ser adicionados manualmente ao array `techniques`, mas o único default automático para `question` é `GT05`.
+
+---
+
+## 4. Endpoints
+
+Base: `/v3/question`. Autenticação: **Bearer token** (`AuthBean`) em todos. Multi-tenant via `apiKey` (`FrontController.getInstance(apiKey)`).
+
+### `POST /v3/question`
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Criar **ou** atualizar (upsert por `_id`) uma pergunta |
+| Full replace ou patch | **Full replace** — o `save` grava o documento inteiro recebido |
+| Status | Sempre `201 CREATED`, **mesmo com erros de validação** |
+
+**Comportamento real:** a validação **não lança** — erros voltam no array `exceptions` do corpo e o documento **não é salvo**. O cliente **deve** inspecionar `exceptions`.
 
-**Exemplo de Body:**
 ```json
-{
-  "_id": "64a5b2c2d8dcca49bcf7eb6e",
-  "type": "MULTIPLE_CHOICE",
-  "title": "Visual Components",
-  "question": "In Funifier, what is the small visual components that can be added to a web page to display feedbacks?",
-  "grade": 1,
-  "choices": [
-    { "answer": "1", "label": "Points", "grade": 0, "extra": {} },
-    { "answer": "2", "label": "Badges", "grade": 0, "extra": {} },
-    { "answer": "3", "label": "Challenges", "grade": 0, "extra": {} },
-    { "answer": "4", "label": "Leaderboards", "grade": 0, "extra": {} },
-    { "answer": "5", "label": "Widgets", "grade": 1, "extra": {} }
-  ],
-  "techniques": ["GT05"],
-  "select": "one_answer",
-  "answerNumbering": "uppercase_letters",
-  "shuffle": false,
-  "feedbacks": [],
-  "extra": {}
-}
+// resposta
+{ "question": { "_id": "...", "type": "MULTIPLE_CHOICE", ... }, "exceptions": [] }
 ```
 
-### Deletar Pergunta
-**Método:** DELETE
-**Endpoint:** `/v3/question/:id`
+### `POST /v3/question/bulk`
 
-### Listar Respostas de Jogadores
-**Método:** GET
-**Endpoint:** `/v3/question/log?question=:id`
+Recebe `List<Question>`; chama `insert` para cada. Resposta separa `registered`/`total_registered` de `ignored`/`total_ignored` (itens com `exceptions`). Status `201`.
 
-### Criar Resposta de Jogador
-**Método:** POST
-**Endpoint:** `/v3/question/log`
+### `GET /v3/question/{id}`
+
+| Param | Tipo | Descrição |
+|---|---|---|
+| `id` (path) | String | ID da pergunta, ou `FUNIFIER_RANDOM_QUESTION` |
+| `q` | String | Critério Mongo (usado no random) |
+| `player` | String | `"me"` resolve para o player do token |
+| `answered_min` / `answered_max` | String | Janela RFC 3339 ou keyword |
+
+**Comportamento real:** se `id == FUNIFIER_RANDOM_QUESTION` **e** `player` informado → `findRandomNotAnsweredForPlayer` (sorteia uma pergunta ainda não respondida pelo player). Senão → `find(id)` simples.
+
+### `GET /v3/question`
+
+| Param | Tipo | Descrição |
+|---|---|---|
+| `id` | String | Filtra por id; aceita `FUNIFIER_RANDOM_QUESTION` |
+| `player` | String | Se informado, injeta `answered:true/false` por pergunta (§2.5). `"me"` suportado |
+| `answered_min`/`answered_max` | String | Janela para considerar "respondida" |
+| `q` | String | Critério Mongo cru concatenado no `$match` |
+| `fields` | String | Projeção (`campo1,campo2`) |
+| `orderby` | String | Campo de ordenação |
+| `reverse` | boolean | Ordem descendente |
+| `Range` (header) | String | Paginação `items=0-100` (default/máx 100) |
+
+### `DELETE /v3/question/{id}`
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Remover a pergunta |
+| Status | `204 NO_CONTENT` |
+
+**Comportamento real (cascata, não-REST padrão):** além de remover o documento `question`, executa `db.question_log.remove({ question: id })` — **apaga todos os logs de resposta daquela pergunta** (`delete`, linhas 111-115). Operação irreversível.
+
+### `GET /v3/question/log`
+
+Lista respostas. Params: `player`, `question`, `q`, `published_min`, `published_max`, `orderby`, `reverse`, `max_results` (default 100). **Não paginado por header** (retorna lista direta). Não existe `GET /v3/question/log/{id}` (busca de log único é só por filtro).
+
+### `POST /v3/question/log`
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Registrar e **corrigir** a resposta de um jogador |
+| Query `async` | Repassado para `ActionManager.trackWithRestrictions` |
+| Status | `201 CREATED` |
+
+**Comportamento real:** corrige a resposta no mesmo request; devolve `grade`, `percent`, `feedbacks`, `meta.attemptsCount` e, se houver `action`, o resultado do tracking. Erros de formato/limite voltam em `errors`. `player == "me"` (ou ausente) resolve para o token.
 
-**Exemplo de Body:**
 ```json
+// request
+{ "player": "ricardo@x.com", "question": "q1", "answer": ["Pedro Alvares Cabral"] }
+// response (exemplo)
 {
-  "question": "64a5b2c2d8dcca49bcf7eb6e",
-  "answer": ["5"],
-  "player": "tom"
+  "log": { "_id":"...", "player":"ricardo@x.com", "question":"q1", "answer":["Pedro Alvares Cabral"], "percent":1.0, "grade":1.0, "time":"..." },
+  "feedbacks": [ { "event":"correct", "message":"Parabéns você acertou" } ],
+  "meta": { "attemptsCount": 1 }
 }
 ```
 
-### Deletar Resposta
-**Método:** DELETE
-**Endpoint:** `/v3/question/log/:id`
+### `POST /v3/question/log/bulk`
 
-## Tipos de Pergunta
+Recebe `List<QuestionLog>`; chama `insertLog` para cada (capturando exceções por item). Resposta agrega `registered`/`total_registered`.
 
-| Tipo | Descrição |
-|------|-----------|
-| `MULTIPLE_CHOICE` | Múltipla escolha (uma ou várias respostas) |
-| `TRUE_FALSE` | Verdadeiro ou Falso |
-| `ESSAY` | Dissertativa (resposta livre) |
-| `CROSSWORD` | Caça-palavras (mini game) |
-| `WORD_SEARCH` | Cruzadinha (mini game) |
+### `POST /v3/question/log/aggregate`
 
-## Campos Importantes
+Roda aggregation customizada sobre `question_log`. Body = `List<String>` de estágios Mongo. Filtros `player`/`question`/`q`/`published_min`/`published_max` montam o `$match` inicial; os estágios do body são anexados. Retorna via `Content-Range`.
 
-| Campo | Tipo | Descrição |
-|-------|------|-----------|
-| `quiz` | String | ID do quiz pai (vincula pergunta ao quiz) |
-| `type` | String | Tipo da pergunta (ver tabela acima) |
-| `question` | String | Texto da pergunta |
-| `grade` | Number | Peso/pontuação da pergunta |
-| `choices` | Array | Opções de resposta (ver estrutura abaixo) |
-| `select` | String | `one_answer` ou `multiple_answers` |
-| `shuffle` | Boolean | Embaralhar opções |
-| `techniques` | Array | IDs de técnicas de jogos vinculadas |
-
-### Estrutura de Choice (Opção de Resposta)
+---
+
+## 5. Regras de Negócio
+
+Regras presentes no código mas não óbvias no schema:
+
+1. **Validação por tipo (`validate`, linhas 673-709):**
+   - Todos (exceto `CUSTOM`): exigem `type` e `title` (`validateBasic`).
+   - `MULTIPLE_CHOICE`: exige `choices` e `select`.
+   - `TRUE_FALSE`: exige `correctAnswer`.
+   - `SHORT_ANSWER`: exige `caseSensitive`.
+   - `MATCHING`: modelo → `left`, `right` e (`solution` **ou** `solutions`); legado → `choices`.
+   - `SELECT_MISSING_WORDS`: modelo → `blanks` com `options`; legado → `choices` + `[[1]]` em `question`.
+   - `DRAG_AND_DROP_INTO_TEXT`: modelo → `targets` + `[[1]]` em `html`/`question`; legado → `choices` + `[[1]]` em `question`.
+   - `ESSAY`: apenas básico. `CUSTOM`: **nenhuma validação**.
+
+2. **Peso vs feedback — pegadinha do `grade`:** `getFeedback` (linhas 129-145) seleciona feedback pela **nota final** `log.grade` (= `question.grade * percent`), **não** pelo `percent`. Limiares (inclusivos):
+   - `grade >= 1` → `correct`
+   - `grade <= 0` → `wrong`
+   - `0 < grade < 1` → `partial_correct`
+
+   Consequência: se `question.grade != 1`, os limiares deslocam. Ex.: `grade=2, percent=0.5 → log.grade=1 → "correct"`; `grade=0.5, percent=1.0 → log.grade=0.5 → "partial_correct"` mesmo com 100% de acerto.
+
+3. **`MULTIPLE_CHOICE` é ilimitado e não força `select`:** o `percent` é a **soma** dos `choice.grade` das opções marcadas, sem teto. Marcar várias opções "certas" acumula acima de `1.0`. O campo `select: one_answer` é só dica de UI — o backend não impede múltiplas marcações.
+
+4. **Limite de tentativas (`verifyLimit`, linhas 374-421):** se `limit.total` (número ou expressão) for atingido na janela `limit.every`, o log **não é registrado** e um erro é retornado. Suporta `per = player` e `per = gamification`; **`per = team` não tem branch** (é ignorado silenciosamente).
+
+5. **Unicidade dentro de quiz:** quando `quiz_log` está presente, o id do log vira `quiz_log + "_" + question`, garantindo **uma resposta por pergunta por execução de quiz** (re-POST sobrescreve).
+
+6. **Propagação para gamificação:** com `question.action` setado, responder gera um `ActionLog` (atributos: `question`, `percent`, `answer`, `grade`, `type`) processado por `trackWithRestrictions`. Se a action não existir → erro `question.action ... does not exist`.
+
+7. **Multi-tenant:** todo acesso é isolado pelo `apiKey` do token; não há ACL por pergunta. O campo `requires` (que poderia gatear elegibilidade) **não é avaliado**.
+
+8. **Consistência eventual:** sem transação. O `save` do log, o `updateLog` do quiz e o `trackWithRestrictions` da action são passos sequenciais independentes; falha em um passo posterior não desfaz os anteriores.
+
+---
+
+## 6. Comportamentos Automáticos
+
+| Comportamento | Trigger | Impacto | Persistência |
+|---|---|---|---|
+| Geração de `_id` | `insert`/`insertLog` sem id | Cria GUID curto (ou id composto em quiz) | Sim |
+| `created`/`updated` | `insert` | `created` no 1º save, `updated` sempre | Sim |
+| Normalização de aliases | `insert` (só `dragDropText`) | `text→html`, `optionsPool→pool`, `acceptedOptionIds→accepts`, `correctOptionId→correctId` | Sim |
+| Triggers de ciclo de vida | `insert`/`insertLog` | `before_*`/`after_*` em `question` e `question_log` | Depende do trigger |
+| Correção automática | `insertLog` | Calcula `percent` e `grade` | Sim (no log) |
+| Atualização do quiz | `insertLog` com `quiz_log` | `QuizManager.updateLog` recalcula percent/grade/questions/answers | Sim (em `quiz_log`) |
+| Tracking de action | `insertLog` com `question.action` | `ActionLog` → pontos/desafios/achievements | Sim (via engine) |
+| Cascata de exclusão | `delete` | Remove todos os `question_log` da pergunta | Sim |
+| `meta.attemptsCount` | `insertLog` | Conta tentativas player×question | Não (só na resposta) |
+| Default de técnica | `autoConfigureMissingTechniqueFields` | Adiciona `GT05` a perguntas sem `techniques` | Sim |
+
+```mermaid
+flowchart LR
+  A["question_log salvo"] --> B{"quiz_log definido?"}
+  B -->|"sim"| C["QuizManager.updateLog<br/>recalcula progresso do quiz"]
+  A --> D{"question.action definido?"}
+  D -->|"sim"| E["cria ActionLog<br/>(question, percent, answer, grade, type)"]
+  E --> F["ActionManager.trackWithRestrictions"]
+  F --> G["Engine: pontos, desafios, achievements"]
+  D -->|"não"| H["fim"]
+```
+
+---
+
+## 7. Suportado vs NÃO Suportado
+
+### ✅ Suportado
+
+- CRUD de perguntas (`POST`, `GET`, `DELETE`) + `bulk`.
+- 8 tipos de pergunta com correção automática (exceto `ESSAY`/`CUSTOM`).
+- Modelo novo (`model`) para `MATCHING`/`SELECT_MISSING_WORDS`/`DRAG_AND_DROP_INTO_TEXT`, com `scoring` `per_*` ou `all_or_nothing`.
+- Registro de respostas (`question_log`) com nota, percentual e feedbacks.
+- Limite de tentativas por `player`/`gamification`, com `total` literal ou via expressão.
+- Pergunta aleatória não respondida (`FUNIFIER_RANDOM_QUESTION`).
+- Campo `answered` por jogador no `GET`.
+- Integração com `quiz` (composição) e `action`/`achievement` (gamificação).
+- Triggers de ciclo de vida em `question` e `question_log`.
+- Aggregation customizada de logs (`/log/aggregate`).
+- i18n armazenado para uso de front-end.
+
+### ❌ NÃO Suportado
+
+- **Correção/nota de `ESSAY`**: sempre `0`. Não há endpoint para o `mentor` lançar nota — `answerEssay` sobrescreve `grade=0` a cada save.
+- **Campo `mentor`**: aceito e persistido, mas **nenhum fluxo o utiliza**.
+- **Campo `requires` (`List<Requirement>`)**: presente na entidade, **nunca lido** pelo `QuestionManager` — não gateia elegibilidade.
+- **`limit.per = team`**: definido em `Limit`, mas `verifyLimit` só trata `player` e `gamification`.
+- **Forçar `select: one_answer`**: o backend não impede múltiplas marcações em `MULTIPLE_CHOICE`.
+- **Teto de `percent` em `MULTIPLE_CHOICE`**: não há clamp; pode passar de `1.0`.
+- **Campos `gradePercent`/`gradeCheck` em `Choice`**: **não existem** no modelo; seriam silenciosamente descartados (vale para qualquer campo desconhecido, devido a `@JsonIgnoreProperties(ignoreUnknown=true)`).
+- **Hardening de aliases para `Matching`/`MissingWords`**: só o `dragDropText` é normalizado no manager; os outros dependem do Jackson. Se o binding ignorar os aliases, esses modelos podem perder dados silenciosamente.
+- **`GET /v3/question/log/{id}`**: não existe — log único só por filtro.
+- **Validação de tipo desconhecido na correção**: um `type` fora do enum não cai em nenhum `answerXxx` → `grade`/`percent` ficam `null`.
+- **Scheduler/Job**: nenhum job processa `question`/`question_log`.
+- **Fora do módulo**: coleção `partner_question` (mesma classe, outra coleção, não exposta em `/v3/question`) e `com.funifier.engine.system.question.*` (perguntas de suporte do sistema — `accountId`/`topic`/`subject`/`description`).
+
+---
+
+## 8. Segurança e Permissões
+
+- **Autenticação:** Bearer token (`AuthBean`) em todas as rotas; resolução de tenant pelo `apiKey` (`FrontController.getInstance`).
+- **Identidade implícita:** `player == "me"` (ou ausente, no `POST /log`) é substituído pelo player do token (`getPlayerFromTokenIfExist`).
+- **Isolamento multi-tenant:** cada `apiKey` opera sobre sua própria conexão `Jongo`/banco. Não há ACL por pergunta — qualquer chamador autenticado no tenant pode ler/escrever/excluir.
+- **Superfície de injeção (por design):** os parâmetros `q`, `orderby` e `fields` são **concatenados como string crua** nas pipelines de aggregation:
+  - `query.append(", " + q)` no `$match` (`findAllPaginated`, `findAll`, `findAllQuestionLogs*`).
+  - `"{$sort : {" + orderby + " : #}}"` no `$sort`.
+  - `fields.split(",")` montando `$project`.
+  - `/log/aggregate` injeta diretamente os estágios enviados no body.
+
+  Isso expõe a sintaxe de query do Mongo ao cliente (comportamento intencional da plataforma Funifier), mas significa que entrada não confiável nesses campos pode alterar a pipeline. **Não sanitize no front esperando proteção do back** — trate esses campos como superfície de query Mongo.
+- **Exclusão destrutiva:** `DELETE /v3/question/{id}` apaga em cascata todos os `question_log` — sem confirmação e sem soft-delete.
 
+---
+
+## 9. Observabilidade e Troubleshooting
+
+**Diagnóstico — a pergunta existe e está correta?**
+```
+GET /v3/question/<id>
+GET /v3/question?q={"type":"MULTIPLE_CHOICE"}
+```
+
+**A resposta foi registrada?**
+```
+GET /v3/question/log?question=<id>&player=<player>
+```
+
+**Quantas tentativas um jogador fez?** (mesmo cálculo do `meta.attemptsCount`)
+```
+db.question_log.count({ player: "<player>", question: "<id>" })
+```
+
+**Erros comuns e causas:**
+
+| Mensagem / sintoma | Causa |
+|---|---|
+| `question dont exist` | `question` do log aponta para id inexistente |
+| `answer in invalid format: type X requires ...` | Formato de `answer` não bate com o tipo (ex.: `MULTIPLE_CHOICE` exige `List<String>`, `MATCHING` exige `Map`) |
+| `you have exced the limit ...` | `limit.total` atingido na janela `limit.every` |
+| `question.action ... does not exist` | `question.action` referencia action inexistente |
+| Pergunta criada mas "não salvou" | Erros em `exceptions` no `POST` (HTTP ainda é 201) — inspecione o array |
+| `grade`/`percent` ausentes no log | `type` fora do enum, ou erro de validação anterior interrompeu a correção |
+| Feedback "errado" para acerto parcial | Lembre que o feedback usa `log.grade` (peso × percent), não `percent` (§5.2) |
+| `ESSAY` sempre com nota 0 | Comportamento esperado — sem correção automática |
+| Dados do modelo "sumiram" em Matching/MissingWords | Aliases não normalizados no manager (só `dragDropText` é) — envie os nomes canônicos |
+
+**O que verificar quando algo não funciona:**
+1. O `type` está no enum e os campos obrigatórios da §5.1 estão presentes?
+2. O `answer` está no formato da §2.4 para o tipo?
+3. `question.grade` está em `1` quando você espera que `percent` e `grade` coincidam?
+4. Para quiz: `quiz_log` está sendo enviado? (sem ele, não há `updateLog`.)
+5. Para gamificação: `question.action` existe e está ativa?
+
+---
+
+## 10. Exemplos Práticos
+
+### 10.1 Mínimo funcional — Múltipla escolha
+```json
+POST /v3/question
+{
+  "type": "MULTIPLE_CHOICE",
+  "title": "Descobrimento",
+  "question": "Quem descobriu o Brasil?",
+  "select": "one_answer",
+  "grade": 1.0,
+  "choices": [
+    { "answer": "cabral", "label": "Pedro Alvares Cabral", "grade": 1.0 },
+    { "answer": "dpedro", "label": "Dom Pedro I", "grade": 0.0 }
+  ]
+}
+```
+Resposta do jogador:
+```json
+POST /v3/question/log
+{ "player": "tom", "question": "<id>", "answer": ["cabral"] }
+```
+
+### 10.2 Avançado — Matching (modelo novo) + limite + action + feedbacks
 ```json
+POST /v3/question
 {
-  "answer": "1",           // identificador único da opção
-  "label": "Funifier",     // texto exibido
-  "grade": 1,              // pontuação se escolhida (0 = errada)
-  "gradePercent": 100,     // percentual de acerto
-  "gradeCheck": true,      // indica se é resposta correta
-  "extra": {}              // metadados adicionais
+  "type": "MATCHING",
+  "title": "Números romanos",
+  "grade": 1.0,
+  "model": {
+    "interactionType": "MATCHING",
+    "matching": {
+      "left":  [ {"id":"1","text":"1"}, {"id":"2","text":"2"}, {"id":"3","text":"3"} ],
+      "right": [ {"id":"I","text":"I"}, {"id":"II","text":"II"}, {"id":"III","text":"III"} ],
+      "solution": [ {"leftId":"1","rightId":"I"}, {"leftId":"2","rightId":"II"}, {"leftId":"3","rightId":"III"} ],
+      "scoring": "all_or_nothing"
+    }
+  },
+  "feedbacks": [
+    { "event": "correct", "message": "Mandou bem, {{player.name}}!" },
+    { "event": "wrong",   "message": "Tente de novo." }
+  ],
+  "limit": { "total": 3, "per": "player", "every": "1d" },
+  "action": "answer_quiz"
 }
 ```
+Resposta:
+```json
+POST /v3/question/log
+{ "player": "tom", "question": "<id>", "answer": { "1": "I", "2": "II", "3": "III" } }
+```
 
-## Formatos de Apresentação
+### 10.3 Anti-pattern (o que NÃO fazer)
+```json
+// ❌ Esperar que "select":"one_answer" impeça marcar 2 opções certas.
+//    O backend SOMA os grades — percent pode passar de 1.0.
+{
+  "type": "MULTIPLE_CHOICE",
+  "title": "Errado",
+  "select": "one_answer",
+  "grade": 2.0,                      // ❌ peso != 1 desloca os limiares de feedback:
+  "choices": [                       //    percent=0.5 → grade=1.0 → feedback "correct"
+    { "answer": "a", "grade": 1.0 },
+    { "answer": "b", "grade": 1.0 }  // marcar a+b → percent=2.0, grade=4.0
+  ]
+}
+```
+Por quê é ruim: (1) `select` não é enforced; (2) `grade=2` faz a seleção de feedback (`correct`/`partial`/`wrong`) divergir do percentual real de acerto. Mantenha `grade=1` quando quiser que `grade` e `percent` coincidam, e não dependa de `select` para validar escolha única.
+
+```json
+// ❌ Campos inexistentes em Choice são descartados em silêncio.
+{ "answer": "a", "label": "A", "gradePercent": 100, "gradeCheck": true }
+// 'gradePercent' e 'gradeCheck' NÃO existem no modelo → ignorados. Use apenas 'grade'.
+```
 
-Perguntas podem incluir conteúdo rico:
-- Texto com HTML
-- Imagens (campo `image`)
-- Vídeos e áudio (via `extra`)
-- Mini games (caça-palavras, cruzadinha)
+---
 
-## Validações e Testes
+## Checklist de Configuração
 
-- [ ] Pergunta aparece na lista GET /v3/question
-- [ ] Resposta do jogador é registrada corretamente (POST /v3/question/log)
-- [ ] Grade é calculada com base na resposta
-- [ ] Opções de resposta estão corretas
-- [ ] Vinculação com quiz funciona (campo `quiz`)
-- [ ] Registro em lote funciona (POST /v3/question/log/bulk)
+- [ ] `type` definido e dentro do enum (`MULTIPLE_CHOICE`, `TRUE_FALSE`, `MATCHING`, `SHORT_ANSWER`, `SELECT_MISSING_WORDS`, `DRAG_AND_DROP_INTO_TEXT`, `ESSAY`, `CUSTOM`).
+- [ ] `title` preenchido (obrigatório exceto em `CUSTOM`).
+- [ ] Campos obrigatórios do tipo presentes (§5.1): `choices`+`select` (MC), `correctAnswer` (TF), `caseSensitive` (SA), `model.*` ou `choices` (MATCHING/SELECT/DRAG).
+- [ ] `grade = 1` se você quer que `log.grade` reflita o percentual de acerto (armadilha §5.2).
+- [ ] Para `DRAG_AND_DROP`/`SELECT_MISSING_WORDS` legados: `[[1]]`, `[[2]]`... presentes no campo `question`.
+- [ ] Resposta (`answer`) enviada no formato correto do tipo (§2.4) — formato errado gera `answer in invalid format`.
+- [ ] Para vincular a um quiz: enviar `quiz_log` no log (sem ele não há `updateLog`).
+- [ ] Para gamificar: `action` existe e está ativa antes de criar a pergunta.
+- [ ] Ciente da cascata: `DELETE /v3/question/{id}` apaga **todos** os `question_log` da pergunta.
+- [ ] Não confie em `select` para forçar escolha única, nem use campos inexistentes (`gradePercent`, `gradeCheck`).
+- [ ] Inspecionar `exceptions` no `POST /v3/question` (HTTP 201 não significa salvo).