funifier-mcp 0.2.26 → 0.2.28

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

@@ -1,163 +1,608 @@
-# Quiz (Quiz)
+# `quiz`
 
 **Acesso Studio:** `/studio/quiz`
 **API Endpoint:** `/v3/quiz`
+**Endpoint Legado:** não existe (apenas v3)
+**Coleção MongoDB:** `quiz` (configuração) + `quiz_log` (tentativas dos jogadores)
 
-## O que é
+> Documentação de engenharia reversa baseada no código real de `funifier-service`
+> (`com.funifier.engine.quiz.*`, `com.funifier.rest.v3.rest.QuizRest`). Onde o comportamento
+> do runtime diverge do schema/documentação anterior, o fato está registrado explicitamente.
 
-Agrupamento de perguntas em formato de prova ou simulado. Permite criar provas compostas por perguntas, definir nota total, controlar tentativas e embaralhar questões para cada jogador. Os quizzes podem ser apresentados como mini games.
+---
 
-## Quando usar
+## 1. Visão Geral
 
-- Para criar provas e avaliações
-- Para simulados com nota
-- Para treinamentos com pontuação
-- Para concursos de conhecimento
+O módulo `quiz` agrupa um conjunto de perguntas (`question`) em uma "prova" e gerencia o ciclo de uma **tentativa** de um jogador: iniciar → responder → finalizar → calcular nota → registrar uma `action_log`.
 
-## Dependências
+Papel arquitetural:
 
-- **Question**: perguntas devem ser criadas para compor o quiz
+- A coleção `quiz` guarda **apenas a configuração** da prova (título, nota máxima, feedbacks por faixa de nota, limite de tentativas, ação a disparar). **Ela não contém as perguntas.** As perguntas vivem na coleção `question` e apontam para o quiz pelo campo `Question.quiz` (relação inversa — vide §3.1).
+- A coleção `quiz_log` é o **log de tentativas**: cada documento representa uma tentativa de um jogador em um quiz, com data de início (`started`), data de fim (`finished`) e os totais consolidados (`percent`, `grade`, `questionsGrade`, `questions`, `answers`).
+- A **avaliação por questão** não acontece no módulo `quiz` — acontece no módulo `question` (`QuestionManager.answer`), que calcula `QuestionLog.percent ∈ [0,1]` e `QuestionLog.grade`. O módulo `quiz` apenas **agrega** esses valores ao finalizar a tentativa.
 
-## Checklist de Configuração no Studio
+Problemas que resolve:
 
-- [ ] Definir título e descrição do quiz
-- [ ] Definir nota total (grade)
-- [ ] Criar perguntas associadas ao quiz
-- [ ] Configurar embaralhamento (shuffle)
-- [ ] Definir se mostra nota antes de finalizar (showGradeBeforeFinish)
-- [ ] Configurar numeração das questões (questionNumbering)
+- Provas, simulados, mini-testes e quizzes de conhecimento com nota.
+- Controle de quantas vezes um quiz pode ser respondido (`Limit`, por jogador ou por gamificação, com janela de tempo).
+- Disparo de uma `action_log` ao finalizar (integração com o motor de gamificação — pontos, desafios, etc. via `quiz.action`).
+- Feedback textual por faixa de nota (`feedbacks` com `grade boundary`).
 
-## API Endpoints
+Relação com outros módulos:
 
-### Listar Quizzes
-**Método:** GET
-**Endpoint:** `/v3/database/quiz`
+- **`question` / `question_log`** — fonte real das notas. Ao responder uma questão vinculada a um `quiz_log`, o `QuestionManager` chama de volta `QuizManager.updateLog(quiz_log)` (vide §2.4).
+- **`action` / `achievement`** — `finishLog` monta uma `ActionLog` (`actionId = quiz.action`) e a registra via `ActionManager.trackWithRestrictions`, alimentando o motor de gamificação.
+- **`trigger`** — eventos `before_create`/`after_create`/`before_update`/`after_update` são disparados sobre as coleções `quiz` e `quiz_log` (vide §6).
+- **`player`** — usado para resolver `player` ("me" → token) e para parametrizar fórmulas de `Limit` e mensagens de feedback (Mustache).
+- **AI (`/v3/ai/build/quiz`)** — gera *texto* de configuração de quiz via OpenAI; **não persiste nada** (vide §7).
 
-### Criar Quiz
-**Método:** POST
-**Endpoint:** `/v3/quiz`
+---
+
+## 2. Arquitetura e Fluxos
+
+### 2.1 Classes envolvidas
+
+| Classe | Arquivo | Papel |
+|---|---|---|
+| `com.funifier.engine.quiz.Quiz` | `engine/quiz/Quiz.java` | Entidade de configuração (documento raiz da coleção `quiz`) |
+| `com.funifier.engine.quiz.QuizLog` | `engine/quiz/QuizLog.java` | Entidade da tentativa (documento raiz da coleção `quiz_log`) |
+| `com.funifier.engine.quiz.Feedback` | `engine/quiz/Feedback.java` | Feedback por faixa de nota (`grade` + `message`) |
+| `com.funifier.engine.quiz.QuizManager` | `engine/quiz/QuizManager.java` | Manager: CRUD, start/finish, cálculo de nota, agregação |
+| `com.funifier.rest.v3.rest.QuizRest` | `rest/v3/rest/QuizRest.java` | Controller REST v3 (`/v3/quiz`) |
+| `com.funifier.engine.quiz.settings.QuizSettings` | `engine/quiz/settings/QuizSettings.java` | Settings de UI (feedback/stuck) — **persistido mas não aplicado** (§7) |
+| `com.funifier.engine.quiz.settings.FeedbackSettings` | idem | Subobjeto de UI — não aplicado pelo servidor |
+| `com.funifier.engine.quiz.settings.StuckSettings` | idem | Subobjeto de UI — não aplicado pelo servidor |
+| `com.funifier.engine.quiz.settings.FeedbackDefaults` | idem | Helpers de default — **sem chamadores** (código morto, §7) |
+| `com.funifier.engine.action.Limit` | `engine/action/Limit.java` | Limite de tentativas (reaproveitado de `action`) |
+
+Não há `Repository`/`Dao` dedicado — toda manipulação MongoDB é feita via `Jongo` dentro de `QuizManager`. Não há scheduler/job que processe o módulo `quiz`.
+
+### 2.2 Pipeline principal (sequência de uma tentativa)
+
+A ordem real de chamadas, do início ao fim de uma tentativa:
 
-**Exemplo de Body:**
-```json
-{
-  "_id": "650c82fe832",
-  "title": "Funifier Exam",
-  "description": "Test your knowledge about the best gamification platform in the world.",
-  "grade": 10,
-  "i18n": {},
-  "extra": {},
-  "feedbacks": [],
-  "questionNumbering": "uppercase_letters",
-  "showGradeBeforeFinish": false,
-  "shuffle": false
-}
 ```
+1. [Admin] POST /v3/quiz                 -> QuizManager.insert(quiz)        (cria/atualiza config)
+2. [Admin] POST /v3/question (xN)        -> QuestionManager.insert          (cada questão com quiz=<quizId>)
+3. [Player] POST /v3/quiz/start          -> QuizManager.startLog(log)       (cria quiz_log, verifica Limit)
+4. [Player] POST /v3/question/log (xN)   -> QuestionManager.answer          (avalia questão, salva question_log)
+            ou /v3/question/log/bulk        -> se log.quiz_log != null       -> QuizManager.updateLog(quiz_log)
+5. [Player] POST /v3/quiz/finish         -> QuizManager.finishLog(id,async) (consolida nota, dispara action_log)
+```
+
+Características:
+
+- **Síncrono** em todas as etapas. A única assíncronia opcional é o registro da `action_log` em `finishLog`, controlado pelo query param `?async=` repassado a `ActionManager.trackWithRestrictions(al, async)`.
+- **Sem transação MongoDB.** Cada `save`/`remove` é independente; uma falha no meio do pipeline deixa estado parcial.
+- A nota só é **definitiva** após o `finish`. Durante a tentativa, `updateLog` só grava nota parcial se `quiz.showGradeBeforeFinish == true` (§2.3).
+
+#### Diagrama — sequência de uma tentativa (`firequiz`)
+
+```mermaid
+sequenceDiagram
+    participant C as Cliente (Player)
+    participant QR as QuizRest
+    participant QM as QuizManager
+    participant QnM as QuestionManager
+    participant DB as MongoDB
+
+    C->>QR: POST /v3/quiz/start {quiz, player}
+    QR->>QM: startLog(log)
+    QM->>QM: verifyLimit(quiz, log)
+    QM->>DB: save quiz_log (started=now)
+    QM-->>C: { log: quiz_log }
+
+    loop para cada questão
+        C->>QR: POST /v3/question/log {question, answer, quiz_log}
+        QR->>QnM: answer(log)
+        QnM->>QnM: avalia tipo -> percent, grade
+        QnM->>DB: save question_log (id = quiz_log + "_" + question)
+        QnM->>QM: updateLog(quiz_log)
+        QM->>DB: atualiza questions/answers (e nota se showGradeBeforeFinish)
+    end
+
+    C->>QR: POST /v3/quiz/finish {quiz_log}
+    QR->>QM: finishLog(id, async)
+    QM->>QM: percent = soma(answer.percent)/questions, grade = quiz.grade x percent
+    QM->>DB: save quiz_log (finished=now)
+    QM->>QnM: (action) ActionManager.trackWithRestrictions(action_log)
+    QM-->>C: { log, feedbacks, action }
+```
+
+### 2.3 Cálculo de nota — `finishLog` e `updateLog`
+
+Pseudocódigo real de `finishLog` (`QuizManager.java:251`):
+
+```
+questions   = SELECT * FROM question WHERE quiz = quiz_log.quiz       // todas as questões do quiz
+answers     = SELECT * FROM question_log WHERE quiz_log = quiz_log.id // respostas desta tentativa
+
+percent        = 0
+questionsGrade = 0
+para cada answer em answers:
+    se answer.grade   != null: questionsGrade += answer.grade
+    se answer.percent != null: percent        += answer.percent
+
+log.percent        = percent / questions.size()        // média simples sobre TODAS as questões
+log.grade          = quiz.grade * log.percent          // escala 0..quiz.grade (default 0..10)
+log.questionsGrade = questionsGrade                    // soma ponderada (peso por questão)
+log.questions      = questions.size()
+log.answers        = answers.size()
+se log.finished == null: log.finished = now()
+feedback           = quiz.getFeedback(log.grade)       // maior boundary <= grade
+```
+
+Pontos não óbvios:
+
+- `log.percent` é **média sobre o total de questões do quiz**, não sobre as respondidas. Questões não respondidas entram no denominador e **penalizam** a nota.
+- `questionsGrade` é a **soma ponderada** (`Σ question.grade × percent_da_questão`), enquanto `grade` trata todas as questões com peso igual. Os dois números podem divergir.
+- `quiz.getFeedback(grade)` (`Quiz.java:98`) retorna o `Feedback` cujo `grade boundary` é o **maior valor ≤ grade obtida**. Sem boundary aplicável → `null`.
+- `updateLog` (`QuizManager.java:201`) roda a cada resposta, mas: **(a)** só atualiza se `log.finished == null`; **(b)** só grava `percent`/`grade`/`questionsGrade` se `quiz.showGradeBeforeFinish == true`; **(c)** sempre atualiza `questions` e `answers`.
+
+> ⚠️ **Divisão por zero:** se o quiz não tem questões, `questions.size() == 0` e `percent/0` produz `NaN` (Java, double). `log.grade` vira `NaN`, `getFeedback(NaN)` retorna `null` (toda comparação com NaN é falsa) e a `action_log` recebe `grade = NaN`. Não há erro nem log.
+
+### 2.4 Integração com `question` (callback de atualização)
+
+Quando uma resposta é registrada (`QuestionManager.answer`, `QuestionManager.java:533`):
+
+```
+se log.quiz_log != null e não vazio:
+    manager.getQuizManager().updateLog(log.quiz_log)
+```
+
+É **a única forma** de manter `quiz_log.questions`/`answers` em dia durante a tentativa. Se o cliente responder questões sem informar `quiz_log`, o `quiz_log` não é atualizado e o `finish` ainda assim recalcula tudo (busca `question_log` por `quiz_log`). Ou seja: o vínculo crítico é `QuestionLog.quiz_log` apontar para `QuizLog._id`.
+
+### 2.5 Cascata de exclusão
+
+#### Diagrama — `QuizManager.delete(id)`
+
+```mermaid
+flowchart LR
+    A["delete(quizId)"] --> B["remove quiz where _id = quizId"]
+    A --> C["remove quiz_log where quiz = quizId"]
+    A --> D["remove question where quiz = quizId"]
+    A --> E["remove question_log where quiz = quizId"]
+```
+
+- `delete(id)` (`QuizManager.java:75`) apaga o quiz **e** todas as suas tentativas, questões e respostas. Operação destrutiva e **sem trigger** (§6/§7).
+- `deleteLog(id)` (`QuizManager.java:83`) apaga uma tentativa e os `question_log` ligados a ela (`quiz_log = id`).
+- `PlayerDaoMongo` (`engine/player/PlayerDaoMongo.java:108`) remove `quiz_log` de um jogador quando o player é excluído (`remove {player:#}`).
+
+---
+
+## 3. Estrutura dos Objetos
+
+### 3.1 `Quiz` — documento raiz (coleção `quiz`)
+
+| Campo | Tipo | Padrão | Obrigatório | Descrição |
+|---|---|---|---|---|
+| `_id` | String | auto (`Guid.newShortGuid()`) | — | ID; gerado se ausente/vazio no insert |
+| `title` | String | `null` | não | Título exibido no admin |
+| `description` | String | `null` | não | Descrição |
+| `grade` | double | `10` | não | Nota máxima da prova (escala da nota final) |
+| `i18n` | Map<String,Map<String,String>> | `{}` | não | Internacionalização |
+| `extra` | Map<String,Object> | `{}` | não | Campos livres |
+| `created` | Date | auto | — | Definido no 1º insert; preservado em updates |
+| `updated` | Date | auto | — | Atualizado a cada insert |
+| `limit` | `Limit` | `null` | não | Limite de tentativas (§3.5) |
+| `action` | String | `null` | não | ID/nome da ação registrada ao finalizar |
+| `techniques` | List<String> | `null` | não | Códigos de técnica de jogo (GT) — apenas armazenados |
+| `feedbacks` | List<`Feedback`> | `[]` | não | Mensagens por faixa de nota (§3.3) |
+| `settings` | `QuizSettings` | `null` | não | Settings de UI — **persistido mas não aplicado** (§3.4/§7) |
+| `questionNumbering` | String | `null` | não | Numeração das respostas (enum em §3.1) |
+| `showGradeBeforeFinish` | boolean | `false` | não | Se `true`, expõe nota parcial em `updateLog` |
+| `shuffle` | boolean | `false` | não | Embaralhar questões — **flag apenas armazenada** (servidor não embaralha; §7) |
+
+**Enum `questionNumbering`** (constantes estáticas em `Quiz.java`, aplicação no frontend):
+
+| Valor | Significado |
+|---|---|
+| `arabic_numerals` | 1, 2, 3 |
+| `roman_numerals` | I, II, III |
+| `uppercase_letters` | A, B, C |
+
+**Campos computados / não presentes no schema do `Quiz`:**
+
+- **`questions` NÃO é campo do `Quiz`.** O comentário de cabeçalho de `Quiz.java` cita "questions", e a versão legada de `findAllQuestionsByQuiz` (comentada, `QuizManager.java:384`) lia `q.questions`. O modelo atual **não tem esse campo** — as questões são buscadas por `question.quiz = quizId`. A relação é inversa.
+
+**Campos aceitos e silenciosamente ignorados:**
+
+- `@JsonIgnoreProperties(ignoreUnknown=true)` em `Quiz` → qualquer campo extra no JSON é descartado sem erro (ex.: `gradePercent`, `gradeCheck` citados em docs antigas **não existem** no modelo).
+
+#### Relação entre coleções
+
+```mermaid
+erDiagram
+    QUIZ ||--o{ QUESTION : "question.quiz = quiz._id"
+    QUIZ ||--o{ QUIZ_LOG : "quiz_log.quiz = quiz._id"
+    QUIZ_LOG ||--o{ QUESTION_LOG : "question_log.quiz_log = quiz_log._id"
+    QUESTION ||--o{ QUESTION_LOG : "question_log.question = question._id"
+```
+
+### 3.2 `QuizLog` — documento da tentativa (coleção `quiz_log`)
+
+| Campo | Tipo | Padrão | Obrigatório | Descrição |
+|---|---|---|---|---|
+| `_id` | String | auto (`Guid.newShortGuid()`) | — | ID da tentativa; gerado em `startLog` se ausente |
+| `player` | String | — | **sim** | Jogador da tentativa |
+| `quiz` | String | — | **sim** | ID do quiz |
+| `questions` | int | `0` | auto | Total de questões do quiz (preenchido em update/finish) |
+| `answers` | int | `0` | auto | Total de respostas registradas (preenchido em update/finish) |
+| `percent` | Double | `null` | auto | Média de acerto ∈ [0,1] (parcial só se `showGradeBeforeFinish`) |
+| `grade` | Double | `null` | auto | `quiz.grade × percent` |
+| `questionsGrade` | Double | `null` | auto | Soma ponderada dos `grade` das respostas |
+| `started` | Date | auto (`startLog`) | auto | Início; gerado se ausente |
+| `finished` | Date | auto (`finishLog`) | auto | Fim; define a tentativa como encerrada |
+
+**Estados de uma tentativa:**
+
+```mermaid
+stateDiagram-v2
+    [*] --> Iniciada: startLog (started=now)
+    Iniciada --> Iniciada: answer chama updateLog (questions/answers, nota se showGradeBeforeFinish)
+    Iniciada --> Finalizada: finishLog (finished=now, nota consolidada, action_log)
+    Finalizada --> [*]
+    note right of Finalizada
+        updateLog não altera mais nada
+        (guarda: log.finished == null)
+    end note
+```
+
+### 3.3 `Feedback` (quiz-level) — `engine/quiz/Feedback.java`
+
+| Campo | Tipo | Descrição |
+|---|---|---|
+| `grade` | double | *Grade boundary*: nota mínima para este feedback aparecer |
+| `message` | String | Texto exibido (suporta Mustache; parâmetros: `player`, `log`, `feedbacks`, `errors`, `quiz`) |
+
+> ⚠️ Existe **outra** classe `Feedback` em `engine/question/Feedback.java`, totalmente diferente: usa o campo `event` (`correct`/`partial_correct`/`wrong`) em vez de `grade`. A do quiz é por **faixa de nota**; a da question é por **evento**. Não confundir.
+
+### 3.4 `QuizSettings` / `FeedbackSettings` / `StuckSettings` (UI — não aplicado pelo servidor)
+
+`Quiz.settings` é persistido como veio no JSON, mas **nenhum caminho de runtime lê esses campos** (vide §7). Documentado aqui por completude do schema:
+
+`QuizSettings`: `feedback: FeedbackSettings`, `stuck: StuckSettings`.
+
+`FeedbackSettings`:
+
+| Campo | Tipo | Valores / default sugerido |
+|---|---|---|
+| `mode` | String | `immediate` \| `deferred` \| `none` (default sugerido `deferred`) |
+| `position` | String | `inline` \| `toast` \| `modal` |
+| `autoHideMs` | Integer | `0`/`null` = não auto-esconde |
+| `allowRetry` | Boolean | default sugerido `false` |
+| `lockOnCorrect` | Boolean | default sugerido `true` |
+| `showPercent` | Boolean | default sugerido `false` |
+| `showAfterSubmitReview` | Boolean | relevante para `deferred` |
+| `blockNavigationUntilFeedbackHidden` | Boolean | — |
+
+`StuckSettings`: `enabled` (Boolean), `attemptsThreshold` (Integer), `timeThresholdSeconds` (Integer), `message` (String), `offerHint` (Boolean).
+
+> Os defaults acima existem apenas em `FeedbackDefaults.defaultQuizFeedback()` / `defaultQuizStuck()`, métodos **sem chamadores** no código.
+
+### 3.5 `Limit` — controle de tentativas (`engine/action/Limit.java`)
+
+| Campo | Tipo | Descrição |
+|---|---|---|
+| `total` | Object | Número (ex.: `3`) **ou** fórmula Mustache+exp4j (ex.: `{{player.extra.max}}`) |
+| `per` | String | `player` (PER_PLAYER), `team`, `gamification` (PER_GAME) |
+| `every` | String | Janela de tempo (ex.: `1d`, `5h`); ausência ⇒ janela de `10y` |
+| `query` | String | Filtro extra concatenado à query de contagem (Mustache; mínimo 3 chars) |
+
+Avaliado em `verifyLimit` (`QuizManager.java:91`) durante `startLog`. **Atenção:** apenas `per = player` e `per = gamification` são tratados na contagem; **`team` não tem ramo** e não limita nada.
+
+---
+
+## 4. Endpoints
+
+Todos exigem `Authorization: Bearer <token>` (`@BeanParam AuthBean`). O isolamento por organização é feito por `FrontController.getInstance(authBean.getApiKey())` (cada API key → conexão/banco próprios).
+
+### `POST /v3/quiz` — criar/atualizar quiz
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Cria ou atualiza a configuração do quiz (upsert por `_id`) |
+| Autenticação | Bearer token |
+| Full replace ou patch | **Full replace** — `c.save(quiz)` substitui o documento inteiro |
+| Método de update | Não há PUT; reenviar POST com o mesmo `_id` sobrescreve |
+
+**Comportamento real:** se `_id` ausente/vazio → gera ID. `created` é preservado de um documento existente; `updated` sempre renovado. Triggers `before_create`/`after_create` **só disparam quando é criação** (vide §6). Resposta: `JsonUtil.toJsonRemoveNullFields(quiz)` com status `201 CREATED` (inclusive em updates).
+
+> ⚠️ **Bug de doc na fonte:** o `@apiExample` de `QuizRest.insert` mostra um payload de **Question** (`type`, `choices`, `select`...), não de Quiz. Ignore-o. Exemplo real de Quiz em §10.
 
-### Deletar Quiz
-**Método:** DELETE
-**Endpoint:** `/v3/quiz/:id`
+### `GET /v3/quiz/{id}` — buscar quiz
 
-### Listar Perguntas de um Quiz
-**Método:** GET
-**Endpoint:** `/v3/quiz/:id/question`
+Retorna a configuração do quiz (`200 OK`). Retorna corpo `null` se não existir (não 404).
 
-### Criar Pergunta para um Quiz
-**Método:** POST
-**Endpoint:** `/v3/question`
+### `POST /v3/quiz/aggregate` — listar/agregar quizzes
+
+| Param (query) | Tipo | Descrição |
+|---|---|---|
+| `player` | String | Se informado, **injeta** campos `started`/`finished` por quiz |
+| `started_min` / `started_max` | String | Janela para marcar `started` (keyword de data ou ISO) |
+| `finished_min` / `finished_max` | String | Janela para marcar `finished` |
+| Header `Range` | String | Paginação (ex.: `items=0-100`) |
+| Body | List<Object> | **Pipeline de aggregation do MongoDB** enviado pelo cliente |
+
+**Comportamento real (enriquecimento server-side, `findAllAggregate`, `QuizManager.java:478`):** quando `player` é informado, antes do pipeline do cliente são injetados estágios `$facet`/`$project`/`$unwind`/`$replaceRoot` que adicionam, em cada quiz, os booleanos `started` e `finished` (se aquele player iniciou/finalizou aquele quiz na janela). Os IDs vêm de `getStartedQuizIds`/`getFinishedQuizIds` (distinct em `quiz_log`). Esses campos **não existem** no documento `quiz` — são computados na consulta.
+
+### `GET /v3/quiz/{id}/question` — listar questões do quiz
+
+Retorna as questões onde `question.quiz = id` (`findAllQuestionsByQuiz` → `find({quiz:#})`). Não pagina (limite implícito do cursor / header `Range` global).
+
+### `DELETE /v3/quiz/{id}` — excluir quiz (cascata)
+
+Remove `quiz`, `quiz_log`, `question` e `question_log` do quiz (§2.5). `204 NO_CONTENT`. **Sem trigger.**
+
+### `POST /v3/quiz/start` — iniciar tentativa
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Cria um `quiz_log` (tentativa) |
+| Body | `{ "quiz": "<id>", "player": "<player|me>" }` |
+| Resolução de player | `player == null` ou `"me"` → resolvido do token (`getPlayerFromTokenIfExist`) |
+
+**Comportamento real:** valida `quiz`/`player` obrigatórios e existência do quiz; aplica `verifyLimit`. Se passar, gera `_id`/`started` e dispara `before_create`/`after_create` em `quiz_log`. Retorna `{ log, errors? }` com `201`. Se o limite estourar, retorna `errors` e **não** cria o log.
+
+### `POST /v3/quiz/finish` — finalizar tentativa
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Consolida nota, dispara feedback e `action_log` |
+| Body | `{ "quiz_log": "<id>" }` (campo lido é `quiz_log`) |
+| Query | `?async=` repassado ao `ActionManager.trackWithRestrictions` |
+
+**Comportamento real:** recalcula tudo (§2.3) **independente** de `showGradeBeforeFinish`; grava `finished`; dispara `before_update`/`after_update` em `quiz_log`; aplica Mustache nas mensagens de feedback; se `quiz.action` existir e a ação for válida, registra `action_log` com atributos `quiz`, `percent`, `answers`, `questions`, `grade`, `questionsGrade`. Se `quiz.action` apontar para ação inexistente → adiciona erro `quiz.action ... does not exist` (mas o log já foi salvo). Body ausente de `quiz_log` → erro `field id is required`. Status `201`.
+
+### `DELETE /v3/quiz/log/{id}` — excluir tentativa
+
+Remove o `quiz_log` e seus `question_log` (`quiz_log = id`). **Sem trigger.**
+
+> ⚠️ **NPE:** `deleteLog` faz `findOne(...)` e na linha seguinte usa `log.id`. Se o `id` não existir, `log` é `null` → `NullPointerException` (`QuizManager.java:85`).
+
+### Endpoints relacionados (módulo `question`, usados no fluxo)
+
+- `POST /v3/question/log` — registra **uma** resposta (`QuestionManager.answer`). Inclua `quiz_log` para vincular à tentativa.
+- `POST /v3/question/log/bulk` — registra **várias** respostas de uma vez.
+
+---
+
+## 5. Regras de Negócio
+
+Regras presentes no código e ausentes do schema:
+
+- **ID composto de resposta:** em `QuestionManager.answer`, se `log.id == null` **e** `log.quiz_log` informado → `log.id = quiz_log + "_" + question` (`QuestionManager.java:478`). Isso garante **uma resposta por questão por tentativa** — re-responder **sobrescreve**. Se o cliente enviar um `id` explícito, essa proteção é **burlada** e podem surgir respostas duplicadas (contadas em `answers`).
+- **Nota penaliza não respondidas:** `percent = Σpercent / total_de_questões` (não / respondidas). Pular questões reduz a nota.
+- **Nota parcial é opt-in:** `updateLog` só grava `percent`/`grade` se `quiz.showGradeBeforeFinish == true`; caso contrário, durante a tentativa só evoluem `questions`/`answers`.
+- **Limite por janela:** `verifyLimit` conta tentativas em `quiz_log` no período `every` (default `10y`). `per=player` filtra por player+quiz; `per=gamification` filtra só por quiz; **`per=team` não é tratado** (não limita).
+- **Limite com fórmula:** `total` pode ser expressão Mustache avaliada por exp4j (ex.: `{{player.extra.max_attempts}}`). Falha na avaliação → erro e a tentativa **não** é registrada.
+- **Feedback por faixa:** `quiz.getFeedback(grade)` escolhe o maior `boundary ≤ grade`. As faixas são comparadas na escala de `quiz.grade` (default 0..10).
+- **`finish` é idempotente em parte:** se `finished` já existe, não é sobrescrito; mas a nota **é recalculada** a cada chamada de `finish` (não há guarda de "já finalizado").
+- **Multi-tenant:** todo acesso é resolvido por API key → banco isolado. Não há campo de organização no documento.
+- **Consistência eventual:** sem transações; `updateLog`/`finishLog` recalculam a partir das coleções, então valores convergem mesmo que um passo intermediário falhe — desde que `question_log.quiz_log` esteja correto.
+
+---
+
+## 6. Comportamentos Automáticos
+
+| Comportamento | Trigger (gatilho) | Impacto | Persistência |
+|---|---|---|---|
+| Geração de `_id` (quiz) | `insert` sem `_id` | `Guid.newShortGuid()` | Sim (`quiz`) |
+| `created`/`updated` | `insert` | `created` no 1º insert; `updated` sempre | Sim (`quiz`) |
+| Trigger `before_create`/`after_create` (quiz) | `insert` **apenas em criação** | Executa triggers da coleção `quiz` | Conforme trigger |
+| Geração de `_id`/`started` (quiz_log) | `startLog` | IDs e início | Sim (`quiz_log`) |
+| Trigger `before_create`/`after_create` (quiz_log) | `startLog` | Triggers da coleção `quiz_log` | Conforme trigger |
+| `updateLog` (counters) | cada `question.answer` com `quiz_log` | Atualiza `questions`/`answers` (e nota se `showGradeBeforeFinish`) | Sim (`quiz_log`) |
+| Consolidação de nota | `finishLog` | `percent`/`grade`/`questionsGrade`/`finished` | Sim (`quiz_log`) |
+| Trigger `before_update`/`after_update` (quiz_log) | `finishLog` | Triggers da coleção `quiz_log` | Conforme trigger |
+| Registro de `action_log` | `finishLog` com `quiz.action` | Alimenta gamificação (pontos/desafios) | Sim (`action_log`) |
+| Mustache em feedback | `finishLog` | Interpola mensagens com `player`/`log`/`quiz` | Não (só na resposta) |
+| Cascata de exclusão | `delete`/`deleteLog`/exclusão de player | Remove logs/questões relacionados | Sim (remoções) |
+
+#### Diagrama — gatilhos do `finishLog`
+
+```mermaid
+flowchart LR
+    F["finishLog(id)"] --> R["recalcula percent/grade/questionsGrade"]
+    R --> FB["getFeedback(grade)"]
+    R --> T1["trigger before_update (quiz_log)"]
+    T1 --> S["save quiz_log (finished)"]
+    S --> T2["trigger after_update (quiz_log)"]
+    R --> AC{"quiz.action definido?"}
+    AC -- sim --> AL["ActionManager.trackWithRestrictions(action_log)"]
+    AC -- não --> X["sem action_log"]
+```
+
+> ⚠️ **Assimetria importante:** `insert` dispara trigger **apenas quando cria** o quiz. Atualizar um quiz existente **não** dispara `before_update`/`after_update`. `delete`/`deleteLog` **não** disparam nenhum trigger.
+
+---
+
+## 7. Suportado vs NÃO Suportado
+
+### ✅ Suportado
+
+- CRUD de configuração de quiz (`POST`/`GET`/`DELETE /v3/quiz`).
+- Ciclo de tentativa: `start` → respostas (via módulo `question`) → `finish`.
+- Cálculo de nota agregada (`percent`, `grade`, `questionsGrade`) ponderada por questão.
+- Feedback textual por faixa de nota, com Mustache.
+- Limite de tentativas por `player` ou `gamification`, com janela temporal e fórmula.
+- Disparo de `action_log` ao finalizar (integração com gamificação).
+- Triggers `before_create`/`after_create` (quiz e quiz_log) e `before_update`/`after_update` (quiz_log no finish).
+- Exclusão em cascata; listagem/agregação com enriquecimento `started`/`finished` por player.
+- Nota parcial durante a tentativa via `showGradeBeforeFinish`.
+
+### ❌ NÃO Suportado
+
+- **`Quiz.settings` (QuizSettings/FeedbackSettings/StuckSettings) não tem efeito no servidor.** É persistido, mas `resolvePresentation`/`ensureQuizDefaults`/`defaultQuiz*` (em `FeedbackDefaults`) **não têm chamadores** — código morto. `mode`, `position`, `lockOnCorrect`, `stuck.*` etc. são apenas dicas de UI.
+- **`shuffle` (quiz e question) não embaralha no servidor.** É apenas uma flag armazenada; eventual embaralhamento é responsabilidade do frontend.
+- **`questionNumbering`/`answerNumbering`** — apenas armazenados; aplicação é do frontend.
+- **`techniques`** — apenas armazenado; nenhuma lógica server-side no módulo quiz.
+- **Sem campo `questions` no Quiz** — relação é inversa (`question.quiz`); não há endpoint para "adicionar questão ao quiz" (cria-se a questão com `quiz=<id>`).
+- **Sem trigger em update de quiz** e **sem trigger em delete/deleteLog**.
+- **`Limit.per = team` não limita** (sem ramo no `verifyLimit`).
+- **Sem PUT/PATCH** — atualização só por full replace via POST.
+- **Sem endpoint para ler `quiz_log` diretamente** (só `DELETE /v3/quiz/log/{id}`); leitura de resultados via endpoints genéricos de banco/aggregate sobre `quiz_log`.
+- **`/v3/ai/build/quiz` não persiste** — apenas chama OpenAI e retorna o JSON gerado (com questões aninhadas no formato do prompt) para o cliente persistir depois.
+- **Campos desconhecidos descartados** — `@JsonIgnoreProperties(ignoreUnknown=true)`; ex.: `gradePercent`/`gradeCheck` (citados em docs antigas) não existem em `Choice` e somem.
+- **Sem scheduler/job** próprio do módulo.
+
+---
+
+## 8. Segurança e Permissões
+
+- **Autenticação:** Bearer token em todos os endpoints (`AuthBean`). Não há checagem de papel/role explícita na camada `QuizRest` — qualquer token válido da organização opera o módulo.
+- **Isolamento multi-tenant:** `FrontController.getInstance(apiKey)` resolve uma conexão Mongo por organização; não há campo de tenant no documento — o isolamento é a nível de conexão/banco.
+- **Resolução de identidade:** `start` aceita `player: "me"` e resolve do token; se `player` for fornecido explicitamente, **não há validação** de que o token corresponde a esse player (um token pode iniciar tentativa em nome de outro player, conforme permissões da API key).
+- **Superfícies de injeção:**
+  - `POST /v3/quiz/aggregate` recebe um **pipeline de aggregation arbitrário** (`List<Object>`) do cliente e o executa direto no Mongo. É o comportamento padrão dos endpoints `aggregate` da Funifier, mas é uma superfície poderosa — proteja por permissão de API key.
+  - `verifyLimit` concatena `Limit.query` (após Mustache) **diretamente** na string de query do Mongo (`QuizManager.java:120/127`). Como `Limit` é configurado por admin, o risco é de config maliciosa, não de input de player.
+  - `findAllQuestionLogsByLog` monta `"quiz_log:\"" + log + "\""` por concatenação de string (`QuizManager.java:393`). O `log` é o `quiz_log.id` (controlado pelo servidor no fluxo normal), mas a montagem por concatenação é frágil.
+- **Comportamento inseguro documentado:** `deleteLog` lança NPE para id inexistente (não trata `null`) — não vaza dado, mas gera erro 500.
+
+---
+
+## 9. Observabilidade e Troubleshooting
+
+### Diagnóstico rápido
+
+```
+# Configuração do quiz
+GET /v3/quiz/{quizId}
+
+# Questões vinculadas
+GET /v3/quiz/{quizId}/question
+
+# Tentativas de um quiz (via aggregate genérico sobre quiz_log)
+POST /v3/database/quiz_log/aggregate
+[ { "$match": { "quiz": "{quizId}" } }, { "$sort": { "started": -1 } } ]
+
+# Respostas de uma tentativa
+POST /v3/database/question_log/aggregate
+[ { "$match": { "quiz_log": "{quizLogId}" } } ]
+
+# Status started/finished por player (enriquecimento embutido)
+POST /v3/quiz/aggregate?player={player}
+[ { "$match": {} } ]
+```
+
+### Erros comuns e causas
+
+| Sintoma | Causa provável |
+|---|---|
+| `errors: ["quiz dont exist"]` no start | `quiz` inexistente / id errado |
+| `errors: [... exced the limit ...]` | `Limit` atingido na janela `every` |
+| `errors: ["quiz.action ... does not exist"]` no finish | `quiz.action` aponta para ação inválida (log já salvo) |
+| Nota menor que o esperado | Questões não respondidas entram no denominador (§2.3) |
+| `grade`/`percent` ausentes durante a tentativa | `showGradeBeforeFinish=false` (esperado; só aparecem no finish) |
+| `grade = NaN` | Quiz sem questões (divisão por zero, §2.3) |
+| Respostas duplicadas em `answers` | Cliente enviou `question_log` com `id` explícito, burlando o id composto |
+| HTTP 500 ao deletar log | `quiz_log` inexistente → NPE em `deleteLog` |
+| `quiz_log.questions/answers` desatualizados | Respostas enviadas sem `quiz_log` (não chamam `updateLog`) |
+
+### O que verificar quando "não funciona"
+
+1. `question.quiz` aponta para o `quiz._id` correto? (sem isso, o quiz não tem questões).
+2. `question_log.quiz_log` aponta para o `quiz_log._id`? (sem isso, nota não consolida).
+3. `quiz.action` existe? (necessário para gerar pontos/achievement).
+4. O `Limit` não está bloqueando silenciosamente novas tentativas?
+
+---
+
+## 10. Exemplos Práticos
+
+### 10.1 Exemplo mínimo funcional
+
+```json
+// POST /v3/quiz
+{
+  "_id": "prova_historia",
+  "title": "Prova de História",
+  "grade": 10
+}
+```
 
-**Exemplo de Body:**
 ```json
+// POST /v3/question  (repetir para cada questão, sempre com "quiz")
 {
-  "quiz": "650c82fe832",
+  "quiz": "prova_historia",
   "type": "MULTIPLE_CHOICE",
-  "title": "Best Platform",
-  "question": "What is the best gamification platform?",
+  "question": "Quem descobriu o Brasil?",
   "grade": 1,
-  "choices": [
-    { "answer": "1", "label": "Funifier", "grade": 1, "extra": {}, "gradePercent": 100, "gradeCheck": true },
-    { "answer": "2", "label": "Points", "grade": 0, "extra": {}, "gradePercent": 0 },
-    { "answer": "3", "label": "Badges", "grade": 0, "extra": {}, "gradePercent": 0 },
-    { "answer": "4", "label": "Leaderboards", "grade": 0, "extra": {}, "gradePercent": 0 }
-  ],
-  "i18n": {},
   "select": "one_answer",
-  "shuffle": false
+  "choices": [
+    { "answer": "1", "label": "Pedro Álvares Cabral", "grade": 1.0 },
+    { "answer": "2", "label": "Dom Pedro I",          "grade": 0.0 }
+  ]
 }
 ```
 
-### Iniciar Quiz
-**Método:** POST
-**Endpoint:** `/v3/quiz/start`
+```json
+// POST /v3/quiz/start  -> retorna { "log": { "_id": "<quizLogId>", "started": ... } }
+{ "quiz": "prova_historia", "player": "me" }
+```
+
+```json
+// POST /v3/question/log  (vincular à tentativa via quiz_log)
+{ "quiz_log": "<quizLogId>", "quiz": "prova_historia",
+  "question": "<questionId>", "answer": ["1"], "player": "tom" }
+```
+
+```json
+// POST /v3/quiz/finish
+{ "quiz_log": "<quizLogId>" }
+```
+
+### 10.2 Exemplo avançado (feedback por faixa, limite e ação)
 
-**Exemplo de Body:**
 ```json
+// POST /v3/quiz
 {
-  "quiz": "650c82fe832",
-  "player": "tom"
+  "_id": "simulado_enem",
+  "title": "Simulado ENEM",
+  "description": "Simulado com nota e limite de tentativas",
+  "grade": 10,
+  "showGradeBeforeFinish": false,
+  "action": "finalizou_simulado",
+  "limit": { "total": 3, "per": "player", "every": "1d" },
+  "feedbacks": [
+    { "grade": 0,   "message": "Que pena {{player.name}}, continue estudando." },
+    { "grade": 6,   "message": "Bom trabalho! Você tirou {{log.grade}}." },
+    { "grade": 9,   "message": "Excelente, {{player.name}}!" }
+  ],
+  "questionNumbering": "uppercase_letters"
 }
 ```
 
-### Registrar Respostas em Lote
-**Método:** POST
-**Endpoint:** `/v3/question/log/bulk`
+Notas: `feedbacks` é avaliado por **maior boundary ≤ nota**; `limit` permite 3 tentativas por player a cada 24h; `action` registra `action_log` com `grade`/`percent`/`questions`/`answers` ao finalizar.
+
+### 10.3 Anti-pattern (o que NÃO fazer)
 
-**Exemplo de Body:**
-```json
-[
-  {
-    "quiz": "650c82fe832",
-    "quiz_log": "650dc6168325771ffaa94098",
-    "question": "650dc4d98325771ffaa93e5e",
-    "answer": ["1"],
-    "player": "tom"
-  }
-]
-```
-
-### Finalizar Quiz
-**Método:** POST
-**Endpoint:** `/v3/quiz/finish`
-
-**Exemplo de Body:**
 ```json
+// ❌ Achar que "settings"/"shuffle" mudam o comportamento do servidor
 {
-  "quiz_log": "650dc6168325771ffaa94098"
+  "_id": "quiz_errado",
+  "title": "Quiz",
+  "grade": 10,
+  "shuffle": true,                       // servidor NÃO embaralha
+  "settings": {                          // persistido, porém IGNORADO no runtime
+    "feedback": { "mode": "immediate", "lockOnCorrect": true }
+  },
+  "questions": [ { "type": "TRUE_FALSE", "question": "..." } ]  // ❌ "questions" não é campo do Quiz: descartado
 }
 ```
 
-## Fluxo Completo do Quiz
+Por quê: `shuffle`/`settings` são apenas dicas de UI (§7); `questions` não existe no modelo `Quiz` e é silenciosamente descartado — as questões devem ser criadas em `/v3/question` com o campo `quiz`. Além disso, registrar respostas com `id` explícito quebra a regra de "uma resposta por questão por tentativa" (§5).
 
-```
-1. Admin cria Quiz (POST /v3/quiz)
-2. Admin cria Questions vinculadas ao Quiz (POST /v3/question com "quiz": "quiz_id")
-3. Jogador inicia Quiz (POST /v3/quiz/start → retorna quiz_log_id)
-4. Jogador responde questões (POST /v3/question/log/bulk com quiz_log_id)
-5. Jogador finaliza Quiz (POST /v3/quiz/finish → calcula nota)
-```
+---
 
-## Campos Importantes
+## Checklist de Configuração
 
-| Campo | Tipo | Descrição |
-|-------|------|-----------|
-| `grade` | Number | Nota total do quiz (ex: 10) |
-| `shuffle` | Boolean | Embaralhar ordem das perguntas |
-| `showGradeBeforeFinish` | Boolean | Mostrar nota parcial antes de finalizar |
-| `questionNumbering` | String | Formato numeração (`uppercase_letters`, `numbers`, etc.) |
-| `feedbacks` | Array | Mensagens de feedback por faixa de nota |
-
-## Apresentação como Mini Game
-
-Quizzes podem ser apresentados em formatos de mini games:
-- Corrida espacial
-- Quiz tradicional com timer
-- Formato personalizado via widget/frontend
-
-## Validações e Testes
-
-- [ ] Quiz aparece na lista GET /v3/database/quiz
-- [ ] Perguntas estão associadas ao quiz
-- [ ] Jogador consegue iniciar quiz (POST /v3/quiz/start)
-- [ ] Respostas são registradas corretamente (POST /v3/question/log/bulk)
-- [ ] Ao finalizar, nota é calculada (POST /v3/quiz/finish)
-- [ ] Embaralhamento funciona (se ativado)
-- [ ] Feedbacks aparecem conforme faixa de nota
+- [ ] `quiz.grade` (nota máxima) definido — é a escala de `feedbacks` e da nota final.
+- [ ] Questões criadas em `/v3/question` com `question.quiz = <quizId>` (a relação é inversa; não há lista `questions` no quiz).
+- [ ] `quiz.action` aponta para uma ação **existente** se você quer gerar pontos/achievement no finish.
+- [ ] `feedbacks` com `grade boundaries` cobrindo as faixas desejadas (lembre: maior boundary ≤ nota).
+- [ ] Decidiu sobre `showGradeBeforeFinish` (nota parcial durante a tentativa? padrão `false`).
+- [ ] `Limit` configurado com `per = player` ou `gamification` (⚠️ `team` **não** limita).
+- [ ] Armadilha: `settings`/`shuffle`/`questionNumbering`/`techniques` são **dicas de UI** — não esperar comportamento server-side.
+- [ ] Armadilha: ao registrar respostas, **sempre** enviar `quiz_log` e **não** enviar `id` explícito (mantém o id composto e os counters corretos).
+- [ ] Armadilha: quiz **sem questões** gera `grade = NaN` no finish.