funifier-mcp 0.2.25 → 0.2.27

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

@@ -1,111 +1,1045 @@
-# Folder (Pasta)
+# `folder`
 
 **Acesso Studio:** `/studio/folder`
 **API Endpoint:** `/v3/folder`
+**Coleções MongoDB:** `folder`, `folder_content`, `folder_content_type`, `folder_log`
 
-## O que é
+---
 
-Organização de conteúdos e monitoramento do progresso em cursos ou trilhas. Permite criar pastas virtuais para agrupar conteúdos como quizzes, desafios, materiais de estudo e jogos, facilitando o acompanhamento do progresso dos jogadores em jornadas de aprendizagem ou trilhas gamificadas.
+## 1. Visão Geral
 
-## Quando usar
+O módulo `folder` implementa um sistema de trilhas hierárquicas (cursos, módulos, aulas, conteúdos). Cinco artefatos formam o módulo:
 
-- Para estruturar cursos online
-- Para criar trilhas de capacitação
-- Para acompanhar progresso em treinamentos
-- Para organizar conteúdos em hierarquias (módulos → aulas → conteúdos)
+- `folder` — nó da árvore (pasta).
+- `folder_content` — vínculo entre uma pasta e um item de conteúdo (referência a documento em outra coleção, ou item próprio em coleção de formulário).
+- `folder_content_type` — schema do tipo de conteúdo (define a coleção real onde os dados ficam e se é `repository` ou `formulary`).
+- `folder_log` — registro de progresso do jogador em um `folder_content`.
+- `Inside` — DTO transitório calculado em runtime (árvore + progresso); **não persiste em MongoDB**.
 
-## Checklist de Configuração no Studio
+O módulo resolve três problemas:
 
-- [ ] Criar estrutura hierárquica de pastas
-- [ ] Definir títulos das pastas
-- [ ] Associar conteúdos às pastas (quizzes, desafios, textos)
-- [ ] Definir tipos de conteúdo (folder_content_type)
-- [ ] Configurar pasta-pai (parent) para hierarquia
+1. **Organização hierárquica arbitrária** — pastas aninhadas sem limite de profundidade, com ordem (`position`) e visibilidade (`active`) por pasta.
+2. **Vinculação de conteúdo** — duas estratégias: `repository` (a pasta aponta para um item já existente em outra coleção) ou `formulary` (o item é criado e mantido junto ao vínculo, em uma coleção definida pelo `ContentType`).
+3. **Rastreamento de progresso por jogador** — log granular por item (`folder_log`) e agregação recursiva por pasta (`Inside.percent/done/total`), com disparo de triggers `folder_log` e `folder_progress` por nível do breadcrumb.
 
-## API Endpoints
+**Limitações estruturais confirmadas no código:**
 
-### Listar Pastas
-**Método:** GET
-**Endpoint:** `/v3/database/folder`
+- Não há DAO separado: toda persistência é feita pelo próprio `FolderManager` via Jongo.
+- Não há scheduler nem job de background — todo o processamento é síncrono dentro da requisição HTTP.
+- O recurso `folder_content_type` **não tem endpoints próprios** em `FolderRest`. Sua manipulação é feita pela API genérica `/v3/database/folder_content_type`.
 
-### Criar Pasta
-**Método:** POST
-**Endpoint:** `/v3/folder`
+---
+
+## 2. Arquitetura e Fluxos
+
+### 2.1 Componentes
+
+| Camada | Classe | Responsabilidade |
+|---|---|---|
+| REST | `FolderRest` (`src/main/java/com/funifier/rest/v3/rest/FolderRest.java`) | Endpoints HTTP, auth via `AuthBean`, dispatch para `FolderManager`. |
+| Domínio | `FolderManager` (`src/main/java/com/funifier/engine/folder/FolderManager.java`) | Toda a lógica de negócio, persistência e disparo de triggers. |
+| Modelos | `Folder`, `Content`, `ContentType`, `FolderLog`, `UnlockPolicy`, `Inside` | POJOs serializados via Jackson (`@JsonIgnoreProperties(ignoreUnknown=true)`). |
+| Integração | `ManagerFactory.getTriggerManager()` | Disparo dos triggers `folder_log` e `folder_progress`. |
+| Infra | `ConnectionPool.createIndexes()` | Cria índices MongoDB no startup. |
+
+Acesso: `FrontController.getInstance(authBean.getApiKey()).getManagerFactory().getFolderManager()`. Cada `apiKey` mapeia para uma instância isolada de `ManagerFactory` (isolamento por tenant).
+
+### 2.2 Pipeline `insertFolder` (`POST /v3/folder`)
+
+`FolderManager.insertFolder(Folder folder)` — linhas 31–39:
+
+1. Se `folder == null` → retorna sem fazer nada.
+2. Obtém `MongoCollection` da coleção `folder`.
+3. Se `_id` for `null` ou só whitespace → gera `Guid.shortTimeMillis()`.
+4. Se `position == null` → `position = 0`.
+5. Se `active == null` → `active = true`.
+6. `c.save(folder)` — Jongo faz upsert por `_id`.
+
+> Sem validação de campos obrigatórios. Sem disparo de trigger. Sem checagem de existência do `parent`. O endpoint serve tanto para criar quanto para atualizar (full-replace por `_id`).
+
+### 2.3 Pipeline `insertLog` (`POST /v3/folder/log`) — critical path
+
+`FolderManager.insertLog(FolderLog log)` — linhas 556–646:
+
+1. Se `log == null` → retorna sem fazer nada.
+2. Busca `Content content = folder_content.findOne({_id: log.item})`.
+3. **Se `content == null` → retorna silenciosamente** (sem erro, sem save). O endpoint ainda devolve HTTP 201 com o `log` original.
+4. Se `log._id` for `null` ou whitespace → gera `Guid.newShortGuid()`.
+5. Procura log ativo existente: `folder_log.findOne({player: log.player, item: log.item, finished: {$exists: false}})`.
+   - Se **existe** → `log._id = current._id`; `log.started = current.started`.
+   - Se **não existe** → `log.started = now`.
+6. Normalização status/percent (linhas 574–584):
+   - `status == "done"` → `percent = 100.0`.
+   - `percent != null && percent >= 100` → `status = "done"`; `percent = 100.0`.
+   - `status == "done" && finished == null` → `finished = now`.
+7. Se `started == null` ainda assim → `started = now` (fallback de segurança).
+8. **Cálculo de diff** (linha 594):
+
+   ```java
+   double diff = (current == null) ? log.percent
+               : (current != null) ? log.percent - current.percent
+                                   : 0;
+   ```
+
+   - Auto-unboxing de `Double` para `double`. Se `log.percent == null` ou `current.percent == null`, lança `NullPointerException` **antes** de salvar (ver Seção 7).
+9. Se `diff > 0`:
+   - `path = breadcrumbFolder(content.parent)` (lista do raiz até o pai do content).
+   - `before = playerProgress(path.get(0)._id, log.player)` — snapshot do progresso da raiz **antes** do save.
+10. `triggerManager.execute(log._id, log, "folder_log", BEFORE_CREATE, log.player, null)`.
+11. `c.save(log)` — upsert do log.
+12. `triggerManager.execute(log._id, log, "folder_log", AFTER_CREATE, log.player, null)`.
+13. Se `diff > 0` (mesma condição de antes):
+    - `after = playerProgress(path.get(0)._id, log.player)` — snapshot **depois** do save.
+    - `Collections.reverse(path)` — inverte para `[content.parent, ..., raiz]`.
+    - Para cada `folder` no path: compara `folderAfter.percent` com `folderBefore.percent`. Se aumentou, dispara `triggerManager.execute(folder._id, payloadProgress, "folder_progress", AFTER_CREATE, log.player, null)`.
+
+**Payload do trigger `folder_progress`:**
 
-**Exemplo de Body:**
 ```json
 {
-  "title": "CoreDrives",
-  "parent": "D0MmmNf"
+  "_id": "<folderId>",
+  "player": "<playerId>",
+  "folder": { /* Folder completo */ },
+  "progress": { /* Inside com percent/done/total */ },
+  "previous_percent": 60.0,
+  "current_percent": 75.0,
+  "time": "<Date now>"
 }
 ```
 
-### Deletar Pasta
-**Método:** DELETE
-**Endpoint:** `/v3/folder/:id`
+### 2.4 Pipeline `playerProgress` (`POST /v3/folder/progress`)
 
-### Obter Breadcrumb
-**Método:** POST
-**Endpoint:** `/v3/folder/breadcrumb`
+`FolderManager.playerProgress(folder, player)` — linhas 132–149:
 
-**Exemplo de Body:**
-```json
-{
-  "folder": "CD1"
-}
+1. `Folder current = folder.findOne({_id: folder})`.
+2. Se `current == null` → retorna `null`.
+3. `Inside inside = insideFolder(folder)` — monta árvore estrutural (sem progresso).
+4. `inside.player = player`.
+5. `playerProgressCascade(inside, player, root=inside)` — popula `total`, `done`, `percent`, `time`, `is_unlocked` em toda a árvore.
+6. Se `inside.time == null` → `inside.time = getMaxTimeInside(inside, null)` (fallback com bugs latentes — ver Seção 7).
+7. Retorna `Inside`.
+
+Após o `FolderManager.playerProgress`, **`FolderRest.progress` (linhas 119–129) sempre dispara o trigger `folder_progress`** para o folder consultado, mesmo sem mudança de percentual:
+
+```java
+manager.getTriggerManager().execute(folder, progress, "folder_progress", Trigger.EVENT_AFTER_CREATE, player, null);
 ```
 
-### Listar Tipos de Conteúdo
-**Método:** GET
-**Endpoint:** `/v3/database/folder_content_type`
+Neste caminho `previous_percent == current_percent == inside.percent` — não há "antes/depois" no endpoint de leitura.
 
-### Criar/Atualizar Tipo de Conteúdo
-**Método:** PUT
-**Endpoint:** `/v3/database/folder_content_type`
+### 2.5 Pipeline `playerProgressCascade` (recursivo)
 
-**Exemplo de Body:**
-```json
-{
-  "_id": "text",
-  "input": "formulary",
-  "form": [
-    { "name": "title", "type": "string", "title": "Title" },
-    { "name": "content", "type": "text", "title": "Content" }
-  ],
-  "title": "Text",
-  "entity": "text__c"
-}
+`FolderManager.playerProgressCascade(inside, player, root)` — linhas 151–234:
+
+```
+contentIds = inside.getContentIds(cascade=true)   // todos os ids de content na sub-árvore
+inside.total = contentIds.size()
+inside.done = 0
+inside.percent = 0.0
+
+se contentIds não vazio:
+  aggregate folder_log:
+    {$match:{ item:{$in:contentIds}, player:#, status:"done" }}
+    {$group:{ _id:"$item", time:{$max:"$finished"} }}
+    {$group:{ _id:null, done:{$sum:1}, time:{$max:"$time"} }}
+  → inside.done, inside.percent = (done/total)*100, inside.time
+
+para cada item m em inside.items:
+  se m.folder == false (content):
+    log = folder_log.findOne({item:m._id, player:#, status:"done"})
+    se log:
+      m.percent = 100.0; m.time = log.finished
+    senão:
+      log2 = folder_log.findOne({item:m._id, player:#})
+      m.percent = (log2 != null && log2.percent != null) ? log2.percent : 0.0
+  senão se m.folder == true:
+    playerProgressCascade(m, player, root)   // recursão
+
+# pós-processamento: is_unlocked apenas para folders
+onlyFolders = filtra items onde folder == true
+para cada child em onlyFolders (com índice i):
+  policy = resolveUnlockPolicy(child._id)
+  se policy == null OR policy.type != "progress":
+    child.is_unlocked = true
+    continue
+  ref = policy.folder_ref ?: "prev"
+  min = policy.min_percent ?: 0
+  se ref == "prev":
+    se i == 0 → child.is_unlocked = true
+    senão     → child.is_unlocked = (onlyFolders[i-1].percent ?: 0) >= min
+  senão (ref é folderId):
+    target = root.getInsideById(ref, cascade=true)
+    se target == null → child.is_unlocked = true
+    senão              → child.is_unlocked = (target.percent ?: 0) >= min
+```
+
+### 2.6 Pipeline `deleteFolderCascade` (recursivo)
+
+`FolderManager.deleteFolderCascade(id)` — linhas 324–364:
+
+1. Se `id` nulo/whitespace → retorna.
+2. `folder.remove({_id: id})`.
+3. Para cada `Content` em `folder_content.find({parent: id})`:
+   - Resolve `ContentType` por `content.type`.
+   - Se `type != null && type.input == "formulary"` → `db[type.entity].remove({_id: content.content})` (apaga o dado real).
+   - `folder_log.remove({item: content._id})`.
+4. `folder_content.remove({parent: id})` (após o loop).
+5. Para cada `Folder` em `folder.find({parent: id})` → recursão `deleteFolderCascade(child._id)`.
+
+> Sem transação. Sem trigger. Sem checagem de `active` — sub-folders inativos também caem na cascata.
+
+### 2.7 Diagrama — fluxo de `insertLog`
+
+```mermaid
+flowchart LR
+    A[POST /v3/folder/log] --> B{content existe?}
+    B -- Não --> Z[retorno silencioso<br/>HTTP 201 sem save]
+    B -- Sim --> C{log ativo<br/>player+item+!finished?}
+    C -- Sim --> D[reutiliza _id e started]
+    C -- Não --> E[started = now]
+    D --> F[normaliza<br/>status/percent]
+    E --> F
+    F --> G[diff = log.percent - currentPercent]
+    G --> H{diff > 0?}
+    H -- Sim --> I[breadcrumb +<br/>playerProgress before]
+    H -- Não --> J[BEFORE_CREATE folder_log]
+    I --> J
+    J --> K[c.save log]
+    K --> L[AFTER_CREATE folder_log]
+    L --> M{diff > 0?}
+    M -- Não --> END[fim]
+    M -- Sim --> N[playerProgress after<br/>+ reverse path]
+    N --> O[para cada folder no path:<br/>se after.percent &gt; before.percent<br/>→ folder_progress AFTER_CREATE]
+    O --> END
+```
+
+### 2.8 Diagrama — interação entre módulos no `insertLog`
+
+```mermaid
+sequenceDiagram
+    participant C as Cliente
+    participant FR as FolderRest
+    participant FM as FolderManager
+    participant DB as MongoDB
+    participant TM as TriggerManager
+
+    C->>FR: POST /v3/folder/log
+    FR->>FM: insertLog(log)
+    FM->>DB: findOne folder_content {_id: item}
+    alt content não existe
+        FM-->>FR: retorno silencioso
+        FR-->>C: HTTP 201 (sem save)
+    else content existe
+        FM->>DB: findOne folder_log {player, item, !finished}
+        FM->>FM: normaliza status/percent
+        opt diff > 0
+            FM->>FM: breadcrumbFolder(content.parent)
+            FM->>FM: playerProgress(root, player) → before
+        end
+        FM->>TM: execute folder_log BEFORE_CREATE
+        FM->>DB: save(log)
+        FM->>TM: execute folder_log AFTER_CREATE
+        opt diff > 0
+            FM->>FM: playerProgress(root, player) → after
+            loop cada folder no path (do mais próximo ao raiz)
+                FM->>TM: execute folder_progress AFTER_CREATE
+            end
+        end
+        FM-->>FR: retorno
+        FR-->>C: HTTP 201 + log JSON
+    end
+```
+
+### 2.9 Diagrama — ciclo de vida de `FolderLog`
+
+```mermaid
+stateDiagram-v2
+    [*] --> Iniciado: insertLog (content existe)<br/>started = now
+    Iniciado --> EmAndamento: insertLog com percent &lt; 100<br/>(reutiliza _id; finished não setado)
+    EmAndamento --> EmAndamento: insertLog com percent &lt; 100
+    Iniciado --> Concluido: insertLog com status="done"<br/>ou percent ≥ 100
+    EmAndamento --> Concluido: insertLog com status="done"<br/>ou percent ≥ 100
+    Concluido --> [*]: deleteLog<br/>(sem recálculo de progresso pai)
+    Iniciado --> [*]: deleteLog
+    EmAndamento --> [*]: deleteLog
+
+    note right of Iniciado: percent pode ser null<br/>finished == null<br/>idempotência ativa
+    note right of Concluido: percent = 100.0<br/>finished = now<br/>idempotência se quebra<br/>(novo log começa do zero)
+```
+
+> **Idempotência:** "ativa" enquanto `finished` é nulo. Após `status="done"`, novos `insertLog` para o mesmo `(player, item)` criam um log paralelo (a query `{finished: {$exists:false}}` deixa de bater).
+
+---
+
+## 3. Estrutura dos Objetos
+
+### 3.1 `Folder` — coleção `folder`
+
+Definido em `src/main/java/com/funifier/engine/folder/Folder.java`.
+
+| Campo | Tipo | Padrão | Obrigatório | Descrição |
+|---|---|---|---|---|
+| `_id` | `String` | `Guid.shortTimeMillis()` | — | Auto-gerado se nulo/whitespace no insert. |
+| `type` | `String` | — | Não | Categoria livre (ex: `"course"`, `"module"`, `"lesson"`). Usado também como `Inside.type` no retorno. |
+| `parent` | `String` | — | Não | `_id` do folder pai. Ausência ou string vazia = nó raiz. |
+| `title` | `String` | — | Não (sem validação) | Título exibível. |
+| `position` | `Integer` (wrapper) | `0` no insert | — | Ordenação entre irmãos. Default `0` se nulo no insert. |
+| `active` | `Boolean` (wrapper) | `true` no insert | — | Default `true` se nulo. `false` esconde da árvore (`insideFolder`/`moveFolder`); **não bloqueia `deleteFolderCascade`**. |
+| `unlock_policy` | `UnlockPolicy` | — | Não | Política de desbloqueio condicional (ver 3.2). Herdada via `parent` quando ausente. |
+| `extra` | `Map<String,Object>` | `new HashMap<>()` | Não | Campos livres. |
+
+**Campos desconhecidos no JSON de entrada são silenciosamente descartados** (`@JsonIgnoreProperties(ignoreUnknown=true)`). Não existem campos deprecated ou comentados nesta classe.
+
+**Comportamento de `active` por operação:**
+
+| Operação | Considera `active`? |
+|---|---|
+| `insideFolder` / `insideFolderCascade` | `{$or:[{active:true},{active:{$exists:false}}]}` — esconde apenas `active:false` explícito. |
+| `moveFolder` (irmãos) | Mesmo filtro acima — `active:false` não é renumerado nem movido. |
+| `deleteFolderCascade` | **Ignora** `active`. Sub-folders inativos também são removidos. |
+| `breadcrumbFolder` | Ignora — busca puramente por `_id`/`parent`. |
+| `playerProgress` | Usa `insideFolder`, portanto herda o filtro. |
+
+### 3.2 `UnlockPolicy` — embutido em `Folder.unlock_policy`
+
+Definido em `src/main/java/com/funifier/engine/folder/UnlockPolicy.java`.
+
+| Campo | Tipo | Valores | Descrição |
+|---|---|---|---|
+| `type` | `String` | apenas `"progress"` é interpretado | Qualquer outro valor (ou `null`) → `is_unlocked = true`. |
+| `folder_ref` | `String` | `"prev"` ou ID de folder | `"prev"` = folder irmão anterior na lista ordenada. Outro valor é tratado como ID de folder e procurado em toda a árvore via `root.getInsideById(ref, cascade=true)`. |
+| `min_percent` | `Integer` (wrapper) | `0`–`100` | Percentual mínimo do alvo. Default `0` se nulo. Comparação é `target.percent >= min_percent` (inclusivo). |
+
+**Resolução via `resolveUnlockPolicy(folderId)`** — linhas 236–248:
+
+```
+f = folder.findOne({_id: folderId})
+enquanto f != null:
+  se f.unlock_policy != null → return f.unlock_policy
+  se f.parent é nulo/whitespace → break
+  f = folder.findOne({_id: f.parent})
+return null
+```
+
+Sobe a árvore até achar o primeiro ancestral com política. Sem política em nenhum ancestral → `is_unlocked = true`.
+
+### 3.3 `Content` — coleção `folder_content`
+
+Definido em `src/main/java/com/funifier/engine/folder/Content.java`.
+
+| Campo | Tipo | Padrão | Obrigatório | Descrição |
+|---|---|---|---|---|
+| `_id` | `String` | `Guid.shortTimeMillis()` | — | Auto-gerado se nulo/whitespace no insert. |
+| `type` | `String` | — | Sim (runtime) | `_id` do `ContentType`. Sem isso, `findContentData` retorna `null` e `title` automático não funciona. |
+| `content` | `String` | — | Condicional | `_id` do item real em `ContentType.entity`. Obrigatório quando `input=repository`. Em `formulary` aponta para o documento criado por outro fluxo. |
+| `parent` | `String` | — | Sim (runtime) | `_id` do `Folder` pai. Sem validação de existência. |
+| `title` | `String` | — | Não | Calculado automaticamente em `insertContent` quando nulo, OU sempre quando `ContentType.input == "formulary"`. |
+| `extra` | `Map<String,Object>` | `new HashMap<>()` | Não | Campos livres. |
+| `position` | `int` (primitivo) | `0` | — | Sempre presente (primitivo). Inválido enviar `null`. |
+
+> **Diferença em relação a `Folder`:** `Content` **não tem campo `active`** — não pode ser escondido sem ser deletado. `moveContent` consequentemente **não filtra por `active`** (e nem poderia).
+
+**Auto-cálculo de `title` em `insertContent`** (linhas 399–415):
+
+```
+ContentType ct = folder_content_type.findOne({_id: content.type})
+se content.title == null OU (ct != null && ct.input == "formulary"):
+  raw = findContentData(content, jongo)   // busca em ct.entity
+  se raw != null:
+    title = raw["title"] ?: raw["name"] ?: String.valueOf(raw["_id"])
+    content.title = title
 ```
 
-## Casos de Uso Comuns
+> Em `formulary`, o título do `Content` é **sempre sobrescrito** pelo título do item real — qualquer `title` enviado pelo cliente é descartado.
 
-- **Curso Online:** Pasta raiz "Curso de Vendas" → Subpastas "Módulo 1", "Módulo 2" → Conteúdos (textos, vídeos, quizzes)
-- **Trilha de Capacitação:** Pastas representam etapas; cada etapa contém materiais e avaliações
-- **Catálogo de Produtos:** Pastas como categorias; conteúdos como fichas de produto
-- **Onboarding:** Pastas representam fases do onboarding; progresso monitora completude
+### 3.4 `ContentType` — coleção `folder_content_type`
 
-## Progresso do Jogador
+Definido em `src/main/java/com/funifier/engine/folder/ContentType.java`.
 
-O Folder monitora automaticamente o progresso do jogador dentro da árvore de diretórios. Isso permite:
+| Campo | Tipo | Descrição |
+|---|---|---|
+| `_id` | `String` | Identificador (ex: `"video"`, `"quiz"`). |
+| `entity` | `String` | Nome da coleção MongoDB que armazena o item real (ex: `"video__c"`). |
+| `title` | `String` | Label de exibição (não é usado nas decisões internas). |
+| `image` | `String` | URL de ícone. |
+| `input` | `String` | `"repository"` ou `"formulary"`. Apenas essas duas constantes são interpretadas pelo código. |
+| `slug` | `String` | Slug para URL. |
+| `attributes` | `List<HashMap>` | Definição do formulário para `input=formulary`. Não é validada pelo backend de folder. |
 
-- Saber que um jogador completou X% de um curso
-- Registrar action logs ao progredir (aciona técnicas de jogos)
-- Criar desafios vinculados à completude de um folder (ex: "Complete o curso para ganhar 500 XP")
+**Constantes no código:**
+
+```java
+ContentType.INPUT_REPOSITORY = "repository"
+ContentType.INPUT_FORMULARY  = "formulary"
+```
+
+**Impacto no delete:** quando `input == "formulary"`, `deleteContent`/`deleteFolderCascade` removem **também** o documento real em `ContentType.entity` (`{_id: content.content}`). Em `repository`, apenas o vínculo é removido.
+
+> **Não há endpoints REST para `ContentType` em `FolderRest`.** Use a API genérica `/v3/database/folder_content_type` para CRUD.
+
+### 3.5 `FolderLog` — coleção `folder_log`
+
+Definido em `src/main/java/com/funifier/engine/folder/FolderLog.java`.
+
+| Campo | Tipo | Padrão | Obrigatório | Descrição |
+|---|---|---|---|---|
+| `_id` | `String` | `Guid.newShortGuid()` | — | Auto-gerado se nulo/whitespace. Sobrescrito pelo `_id` do log ativo existente quando há idempotência. |
+| `item` | `String` | — | Sim | `_id` do `Content`. Sem isso, `insertLog` aborta silenciosamente. |
+| `player` | `String` | — | Sim | ID do jogador. |
+| `status` | `String` | — | Não | Única constante interpretada: `STATUS_DONE = "done"`. Outros valores são preservados mas ignorados pela lógica. |
+| `started` | `Date` | `now` no insert | — | Preenchido automaticamente; preservado de log ativo existente. |
+| `finished` | `Date` | `now` quando `status="done"` | — | Preenchido apenas quando o log fica `done`. Logs em andamento têm `finished == null` — esta é a chave operacional de idempotência. |
+| `percent` | `Double` (wrapper) | — | Não | `0.0`–`100.0`. **Pode ser `null`** — gatilho de NPE em `insertLog` (Seção 7). |
+| `extra` | `HashMap<String,Object>` | — | Não | Campos livres. Não é inicializado (pode ser `null`). |
+
+**Constantes:**
+
+```java
+FolderLog.STATUS_DONE = "done"
+```
+
+**Normalização aplicada pelo servidor em `insertLog`:**
+
+| Entrada | Resultado |
+|---|---|
+| `status == "done"` | `percent = 100.0` (qualquer valor enviado é sobrescrito) |
+| `percent != null && percent >= 100` | `status = "done"`, `percent = 100.0` |
+| `status == "done" && finished == null` | `finished = now` |
+| `started == null` no final do pipeline | `started = now` |
+
+**Chave operacional de idempotência:** `(player, item, finished:{$exists:false})`. Existe no máximo um log "ativo" por par `(player, item)`. Após `status="done"` (i.e., `finished` setado), o próximo `insertLog` criará um log novo.
+
+### 3.6 `Inside` — DTO de resposta (não persistido)
+
+Definido em `src/main/java/com/funifier/engine/folder/Inside.java`.
+
+| Campo | Tipo | Descrição |
+|---|---|---|
+| `_id` | `String` | `_id` do nó (folder ou content). |
+| `folder` | `boolean` (primitivo) | `true` = pasta; `false` = conteúdo. |
+| `title` | `String` | Vem de `Folder.title` ou `Content.title`. |
+| `type` | `String` | Vem de `Folder.type` ou `Content.type` (ContentType id no caso de conteúdo). |
+| `content` | `String` | Apenas em conteúdos — copia `Content.content` (id do item real). |
+| `items` | `List<Inside>` | Filhos ordenados: **folders primeiro** (todos), **depois conteúdos** (todos). Cada grupo ordenado por `position`. |
+| `player` | `String` | Setado apenas no `playerProgress`. |
+| `total` | `Integer` | Total de conteúdos na sub-árvore (contagem recursiva). |
+| `done` | `Integer` | Conteúdos com pelo menos um `folder_log` `status="done"` para o player. |
+| `percent` | `Double` | Folder: `(done/total)*100`. Content: `100.0` se há log `done`, senão `log.percent ?: 0.0`. |
+| `time` | `Date` | Maior `finished` entre os logs `done` da sub-árvore. Em folders sem nenhum log `done`, cai no fallback `getMaxTimeInside` (com bugs — ver Seção 7). |
+| `is_unlocked` | `Boolean` | `true`/`false` para folders; **`null` para conteúdos**. |
+
+**Métodos utilitários internos (package-private):**
+
+- `getContentIds(boolean cascade)` — coleta `_id` de conteúdos descendentes; se `cascade=false`, apenas os conteúdos diretos do `inside`.
+- `getInsideById(String id, boolean cascade)` — busca o próprio `Inside` ou um filho/descendente por `_id`. Retorna o **primeiro match** (DFS, conteúdo antes de descer em folder filho que casa pelo id — ver código linhas 70–90).
+
+---
+
+## 4. Endpoints
+
+Todos os endpoints exigem `Bearer token` (via `AuthBean`). O `apiKey` extraído do token resolve o `FrontController` (tenant) e o `ManagerFactory` correspondente.
+
+### 4.1 `POST /v3/folder`
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Criar ou atualizar pasta (upsert por `_id`). |
+| Body | `Folder` JSON. |
+| Comportamento | Full replace via `MongoCollection.save()`. Defaults aplicados quando `position` ou `active` forem `null`. |
+| Status | `201 Created`. |
+| Triggers | Nenhum. |
+
+**Exemplo:**
+
+```http
+POST /v3/folder
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{ "title": "Módulo 1 — Introdução", "parent": "trail001", "position": 0 }
+```
+
+```http
+HTTP/1.1 201 Created
+{ "_id": "ABC123xyz", "title": "Módulo 1 — Introdução", "parent": "trail001", "position": 0, "active": true }
+```
+
+### 4.2 `GET /v3/folder/{id}`
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Buscar pasta por `_id`. |
+| Resposta | `200 OK` com `Folder` ou body vazio se `findOne` retornar `null`. |
+
+### 4.3 `GET /v3/folder/{id}/move?direction=up|down`
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Mover folder uma posição para cima/baixo entre seus irmãos `active=true`. |
+| Status | `204 No Content`. |
+
+**Algoritmo (`moveFolder` linhas 251–295):**
+
+1. `findOne({_id: id})` — se `null`, no-op.
+2. Lista todos os irmãos `{parent: o.parent, active:true|inexistente}` ordenados por `position`.
+3. **Renumera todos os irmãos** sequencialmente `0, 1, 2…` e salva cada um (mesmo os que não mudam).
+4. Localiza índice do alvo; identifica `antes` (`index-1`) e `depois` (`index+1`).
+5. Se `direction == "up"` e `index > 0`: troca `position` do alvo com o de `antes`, salva ambos.
+6. Se `direction == "down"` e `index < size-1`: troca com `depois`.
+7. Qualquer outro valor de `direction` (ou `null`): apenas a renumeração (passo 3) é aplicada.
+
+> Efeito colateral: o endpoint **sempre re-grava todos os irmãos** mesmo quando o alvo já está nas pontas. Não é idempotente em termos de I/O.
+
+### 4.4 `DELETE /v3/folder/{id}`
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Deletar pasta com cascata total (ver 2.6). |
+| Status | `204 No Content`. |
+| Triggers | Nenhum em `folder` / `folder_content`; **`folder_log` também não** (cascata deleta logs por `remove`, sem passar pelo `deleteLog`). |
+
+> Irreversível. Sem transação — uma falha no meio deixa estado inconsistente.
+
+### 4.5 `DELETE /v3/folder?q=<query>`
+
+`FolderRest.deleteAll` linhas 71–80. Executa:
+
+```java
+distinct("_id").query("{" + q + "}")
+```
+
+…concatenando o parâmetro `q` diretamente. Depois itera os IDs e chama `deleteFolder` para cada. Risco de injeção MongoDB descrito na Seção 8.
+
+### 4.6 `POST /v3/folder/inside`
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Retornar árvore estrutural (sem progresso). |
+| Body | `{ "folder": "<id ou vazio>" }` |
+| Resposta | `Inside` recursivo. |
+
+**Comportamento por valor de `folder`:**
+
+| Input | Comportamento |
+|---|---|
+| ID existente | Retorna `Inside` cuja raiz corresponde ao folder; `items` contém sub-folders (filtrados por `active`) e contents. |
+| ID inexistente (não-vazio) | Retorna `Inside` raiz "vazio" (apenas `folder=true`, `items=[]`) — a query por `parent: <id>` não acha nada. |
+| `null` ou `""` | Retorna **todos os folders raiz** (`{parent: {$exists: false}}`) **e** os `folder_content` raiz (registros de `folder_content` sem `parent`, se existirem). |
+
+**Ordem dos `items`:** sempre `[folder_0, folder_1, …, content_0, content_1, …]`. Pastas e conteúdos **não são intercalados** por `position`.
+
+### 4.7 `POST /v3/folder/breadcrumb`
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Retornar caminho do raiz até a pasta informada. |
+| Body | `{ "folder": "<id>" }` |
+| Resposta | `List<Folder>` ordenada `[raiz, ..., alvo]`. |
+
+**Algoritmo (`breadcrumbFolder` linhas 46–57):**
+
+```
+list = []
+f = folder.findOne({_id: id})
+list.add(f)
+enquanto f.parent != null && !f.parent.trim().isEmpty():
+  f = folder.findOne({_id: f.parent})
+  list.add(f)
+Collections.reverse(list)
+return list
+```
+
+> **NPE garantida** se `id` não existir (`f` será `null`, e `f.parent` rompe na primeira iteração). Mesmo problema se algum `parent` no caminho não existir no banco.
+
+### 4.8 `POST /v3/folder/progress`
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Calcular o progresso do jogador na árvore + disparar trigger. |
+| Body | `{ "folder": "<id>", "player": "<playerId>" }` |
+| Resposta | `Inside` com `percent/done/total/time/is_unlocked` preenchidos. |
+
+`FolderRest.progress` (linhas 104–133) sempre dispara `folder_progress` (`EVENT_AFTER_CREATE`) ao final, com `previous_percent == current_percent == inside.percent`. Use o trigger via `insertLog` quando precisar de "antes/depois" reais.
+
+> **NPE confirmada** quando `folder` não existe: `FolderManager.playerProgress` retorna `null`, mas `FolderRest.progress` linhas 125–126 fazem `progress.put("previous_percent", inside.percent)` — quebra antes de devolver resposta.
+
+### 4.9 `POST /v3/folder/log`
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Registrar/atualizar progresso de um conteúdo (ver pipeline 2.3). |
+| Body | `FolderLog` JSON. |
+| Status | `201 Created` (mesmo quando o log **não** é salvo por falta de content). |
+| Triggers | `folder_log` BEFORE/AFTER `CREATE`; `folder_progress` AFTER `CREATE` por cada folder cujo `percent` aumentou. |
+
+**Falha silenciosa:** se `log.item` não existir em `folder_content`, retorna 201 com o body original, sem persistir nada (`FolderManager.insertLog` linhas 561–562: o `if(content != null)` engole tudo).
+
+**Query de idempotência:**
+
+```javascript
+db.folder_log.findOne({ player: "<player>", item: "<item>", finished: {$exists: false} })
+```
 
-## Integração com Outras Técnicas
+### 4.10 `GET /v3/folder/log/{id}`
+
+`findLog`. Retorna `FolderLog` ou body vazio se não encontrado.
+
+### 4.11 `DELETE /v3/folder/log/{id}`
+
+`FolderManager.deleteLog` linhas 653–660:
+
+1. `findOne({_id: id})` → `log`.
+2. `triggerManager.execute(log._id, log, "folder_log", BEFORE_DELETE, log.player, null)`.
+3. `c.remove({_id: id})`.
+4. `triggerManager.execute(..., AFTER_DELETE, ...)`.
+
+> **NPE confirmada** quando `id` não existe: `log` será `null` e o passo 2 quebra em `log._id`. **Não recalcula** progresso das pastas pai.
+
+### 4.12 `POST /v3/folder/content`
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Criar vínculo `Content` entre pasta e item. |
+| Body | `Content` JSON. |
+| Status | `201 Created`. |
+| Triggers | Nenhum. |
+
+Auto-cálculo de `title` ver 3.3. Sem validação de existência de `parent` (folder) nem do item real apontado por `content`.
+
+### 4.13 `POST /v3/folder/content/aggregate`
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Listar `folder_content` via pipeline MongoDB customizado, com paginação e enriquecimento opcional do dado real. |
+| Body | `List<Object>` — estágios adicionais do aggregate (já vêm depois do `$match` interno). |
+| Headers | `Range: items=0-N` (paginação via `PaginationUtil`, default `0-100`). |
+
+**Query params:**
+
+| Param | Tipo | Descrição |
+|---|---|---|
+| `folder` | `String` | Se não vazio: filtro de escopo. |
+| `cascade` | `boolean` | `true` → expande para todos os contents na sub-árvore (`insideFolder(folder).getContentIds(true)`); `false` → apenas contents diretos. |
+| `append_data` | `boolean` | `true` → para cada item retornado, adiciona campo `data` com o documento real da coleção `ContentType.entity` (via `findContentData(id)`). |
+
+**Pipeline construído (`findAllContentAggregate` linhas 493–544):**
+
+```
+estágio 0 (sempre):
+  {$match: { ... } }
+  ├── se folder não vazio && cascade  → {_id: {$in: [ids]}}
+  ├── se folder não vazio && !cascade → {parent: folder}
+  └── se folder vazio                 → {} (match-tudo)
+estágios 1+ (do body) → adicionados via Aggregate.and(FunifierMarshaller.toString(stage))
+```
+
+Resultado é paginado por `PaginationUtil.getPageResultThrowsException(a, range, 0, 100)`.
+
+> Estágios injetados pelo cliente (`$lookup`, `$out`, `$merge`, etc.) são executados sem validação. Ver Seção 8.
+
+### 4.14 `GET /v3/folder/content/{id}`
+
+Retorna `Content` ou body vazio.
+
+### 4.15 `GET /v3/folder/content/{id}/data`
+
+Retorna o documento real em `ContentType.entity` por `{_id: content.content}`. Retorna body vazio se:
+
+- `content == null` (ID inexistente), ou
+- `content.type` ou `content.content` `null`, ou
+- `ContentType` ou item real não existirem.
+
+`findContentData` engole essas condições e retorna `null`.
+
+### 4.16 `GET /v3/folder/content/{id}/move?direction=up|down`
+
+Mesmo algoritmo de `moveFolder`, na coleção `folder_content`, **sem filtro por `active`** (`Content` não tem o campo). Status `204`.
+
+> Diferença importante em relação a `moveFolder`: `Content.position` é `int` primitivo, não há null-guards (linhas 460–471) — direto `atual.position - 1`.
+
+### 4.17 `DELETE /v3/folder/content/{id}`
+
+`FolderManager.deleteContent` linhas 477–490:
+
+1. `Content content = folder_content.findOne({_id: id})`.
+2. `ContentType type = folder_content_type.findOne({_id: content.type})`.
+3. Se `type != null && type.input == "formulary"` → `db[type.entity].remove({_id: content.content})`.
+4. `folder_content.remove({_id: id})`.
+5. `folder_log.remove({item: id})`.
+
+> **NPE confirmada** quando `id` não existe (`content == null`) — passo 2 quebra em `content.type`. **Sem trigger**. **Sem recálculo** de progresso.
+
+### 4.18 `DELETE /v3/folder/content?q=<query>`
+
+Mesmo padrão de `4.5` na coleção `folder_content`. `q` interpolado sem sanitização. Itera os IDs e chama `deleteContent` para cada.
+
+---
+
+## 5. Regras de Negócio
+
+### 5.1 Idempotência ativa do log de progresso
+
+Enquanto `finished == null`, qualquer `insertLog` com mesmo `(player, item)` atualiza o log existente preservando `_id` e `started`. Quando o log é fechado (`status="done"` → `finished` setado), a chave de idempotência deixa de bater — chamadas posteriores criam **um novo** log.
+
+### 5.2 Normalização cruzada de status e percent
+
+Servidor força a consistência:
+
+- `status="done"` ⇒ `percent=100.0` (sobrescreve qualquer valor).
+- `percent>=100` ⇒ `status="done"`, `percent=100.0`.
+- Outros valores de `status` não são interpretados — apenas armazenados.
+
+### 5.3 Herança de `unlock_policy`
+
+Sobe a árvore (`f.parent`) até achar o primeiro ancestral com `unlock_policy != null`. Sem nenhum ancestral com política → `is_unlocked = true`.
+
+### 5.4 Tipos não reconhecidos de política desbloqueiam
+
+Em `playerProgressCascade`: se `policy.type == null` ou `policy.type != "progress"` → `is_unlocked = true; continue`. Não há outros tipos suportados.
+
+### 5.5 Primeiro folder em `prev` é sempre desbloqueado
+
+Quando `folder_ref == "prev"` e o índice do folder na lista `onlyFolders` é `0`, `is_unlocked = true` independentemente de `min_percent` — não há "irmão anterior".
+
+### 5.6 `min_percent` é comparação inclusiva (`>=`)
+
+`is_unlocked = (target.percent ?: 0) >= min` — `target.percent` `null` é tratado como `0.0`.
+
+### 5.7 Visibilidade vs deleção (`active`)
+
+`active=false` esconde o folder da árvore de leitura e do `moveFolder`, mas **não impede a remoção em cascata** quando um ancestral é deletado.
+
+### 5.8 Progresso conta contents distintos com `status="done"`
+
+O aggregate em `playerProgressCascade` agrupa por `item` antes de somar — mesmo que existam N logs com `status="done"` para o mesmo content (logs históricos após reset/recriação), eles contam **1 vez**.
+
+### 5.9 Triggers `folder_progress` disparam do mais próximo ao raiz, só quando o percent aumenta
+
+Ordem após `Collections.reverse(path)`: `[content.parent, ..., raiz]`. O disparo é condicional a `folderAfter.percent > folderBefore.percent`. Logs `done` que **não mudam** o percent do folder (por exemplo, reapertar `done` no mesmo content) **não disparam** o trigger.
+
+### 5.10 Trigger `folder_progress` do endpoint `/progress` é incondicional
+
+Independente de mudança, `POST /v3/folder/progress` dispara o trigger uma vez por chamada com `previous_percent == current_percent`. Útil para "ping" do progresso, ruim para handlers que assumem mudança.
+
+### 5.11 Multi-tenant
+
+Cada `apiKey` resolve um `FrontController` próprio, com `ManagerFactory` e `JongoConnection` próprios. Não há cross-tenant query no módulo.
+
+---
+
+## 6. Comportamentos Automáticos
+
+| Comportamento | Trigger | Impacto | Persistência |
+|---|---|---|---|
+| Auto-`_id` em `Folder` | `insertFolder` com `_id` nulo/vazio | `Guid.shortTimeMillis()` | Sim |
+| Auto-`_id` em `Content` | `insertContent` com `_id` nulo/vazio | `Guid.shortTimeMillis()` | Sim |
+| Auto-`_id` em `FolderLog` | `insertLog` com `_id` nulo/vazio (e sem log ativo) | `Guid.newShortGuid()` | Sim |
+| Default `position=0` | `insertFolder` com `position` nulo | Pasta na posição 0 | Sim |
+| Default `active=true` | `insertFolder` com `active` nulo | Pasta visível | Sim |
+| Auto-`title` de `Content` | `insertContent` com `title==null` OU `ContentType.input=formulary` | Resolve `title`/`name`/`_id` do item real | Sim |
+| Reutilização de `_id` do log ativo | `insertLog` com log existente `(player,item,!finished)` | Mantém histórico contínuo | Sim |
+| Auto-`started` | `insertLog` sem log ativo | `started = now` | Sim |
+| Auto-`finished` | `insertLog` com `status="done"` e `finished==null` | `finished = now` | Sim |
+| Normalização `status`↔`percent` | `insertLog` | Coerência entre os dois campos | Sim |
+| Trigger `folder_log` BEFORE/AFTER CREATE | `insertLog` (apenas se content existe) | Executa regras externas | Não (somente externo) |
+| Trigger `folder_log` BEFORE/AFTER DELETE | `deleteLog` (apenas se id existe) | Executa regras externas | Não |
+| Trigger `folder_progress` por breadcrumb | `insertLog` quando `diff>0` e `folderAfter.percent > folderBefore.percent` | Um trigger por folder no path, do mais próximo ao raiz | Não |
+| Trigger `folder_progress` do endpoint | `POST /v3/folder/progress` | Disparo único, incondicional, no folder consultado | Não |
+| Cascata de `formulary` | `deleteContent` ou `deleteFolderCascade` | Remove dado real em `ContentType.entity` | Sim (destrutivo) |
+| Renumeração total de irmãos | `moveFolder` / `moveContent` | Salva **todos** os irmãos com posições sequenciais | Sim |
+
+### 6.1 Diagrama — encadeamento automático em `insertLog`
+
+```mermaid
+flowchart LR
+    A[insertLog] --> B[normalização status/percent]
+    B --> C{content<br/>existe?}
+    C -- Não --> X[abort silencioso]
+    C -- Sim --> D[trigger folder_log<br/>BEFORE_CREATE]
+    D --> E[save]
+    E --> F[trigger folder_log<br/>AFTER_CREATE]
+    F --> G{diff &gt; 0?}
+    G -- Não --> Z[fim]
+    G -- Sim --> H[breadcrumb invertido]
+    H --> I[para cada folder do path]
+    I --> J{folderAfter.percent<br/>&gt; folderBefore.percent?}
+    J -- Não --> I
+    J -- Sim --> K[trigger folder_progress<br/>AFTER_CREATE]
+    K --> I
+    I --> Z
+```
+
+---
+
+## 7. Suportado vs NÃO Suportado
+
+### ✅ Suportado
+
+- Hierarquia arbitrária de pastas com aninhamento ilimitado.
+- Duas estratégias de vínculo de conteúdo (`repository`, `formulary`).
+- Reordenação de folders e contents via `move?direction=up|down`.
+- Cálculo recursivo de progresso por jogador com aggregate MongoDB.
+- Desbloqueio condicional de pastas por percent (`unlock_policy.type="progress"`), com referência a folder específico ou `prev`.
+- Herança de `unlock_policy` via ancestrais (`resolveUnlockPolicy`).
+- Idempotência operacional de logs em andamento via `(player, item, !finished)`.
+- Triggers `folder_log` BEFORE/AFTER CREATE e BEFORE/AFTER DELETE.
+- Triggers `folder_progress` por folder no breadcrumb (apenas quando o percent realmente aumenta).
+- Trigger `folder_progress` incondicional ao consultar progresso (`POST /v3/folder/progress`).
+- Listagem de conteúdos via aggregate customizado com `cascade` e `append_data`.
+- Deleção em cascata de pastas (folders, contents, logs, dados `formulary`).
+- Auto-cálculo de `title` de `Content` baseado no item real.
+
+### ❌ NÃO Suportado
+
+- **`GET /v3/folder` (listagem geral)** — não existe rota em `FolderRest`. Use `/v3/database/folder?q=...`.
+- **`PUT /v3/folder/{id}`** — não existe. `POST /v3/folder` cobre create+update (upsert).
+- **Endpoints CRUD para `folder_content_type`** — gestão é via `/v3/database/folder_content_type`.
+- **Intercalação de folders e contents por `position`** — `insideFolder` sempre retorna **folders antes de contents**, ambos ordenados por `position` dentro do próprio grupo.
+- **Filtragem de contents por `active`** — `Content` não tem `active`; um content só some quando deletado.
+- **Transações atômicas** — nenhum dos pipelines (insert, delete, cascata) usa transação MongoDB. Falha parcial deixa estado inconsistente.
+- **Triggers para `folder` e `folder_content`** — `insertFolder`/`deleteFolder`/`insertContent`/`deleteContent` não disparam triggers.
+- **Recálculo de progresso ao deletar log** — `deleteLog` é cirúrgico; nenhum folder pai é re-agregado.
+- **Validação de referências** — nenhum método valida que `parent`, `type` ou `content` apontam para documentos existentes (com exceção de `insertLog` que requer `content` existir).
+- **Scheduler/job de background** — não há `Runner`/`Scheduler`/job que processe folder.
+- **`type != "progress"` em `unlock_policy`** — outros valores resultam em `is_unlocked=true` (passa direto).
+- **Recurso `folder_log` pago/`paginado` via `/v3/folder`** — listagem só por `/v3/database/folder_log`.
+
+### 7.1 Bugs e edge cases confirmados
+
+| Local | Comportamento |
+|---|---|
+| `FolderManager.insertLog` linha 594 | `double diff = log.percent` (auto-unbox). Se `log.percent == null` (sem `status="done"` e sem `percent`), lança `NullPointerException` **antes** de salvar o log. Mesmo problema com `current.percent` em logs antigos. |
+| `FolderManager.breadcrumbFolder` linhas 49–53 | `id` inexistente → `findOne` retorna `null` → `folder.parent` NPEs. Mesmo erro se algum `parent` referenciado não existir. |
+| `FolderManager.deleteLog` linhas 655–657 | `id` inexistente → `log == null` → `log._id` NPEs antes do trigger. |
+| `FolderManager.deleteContent` linhas 481–482 | `id` inexistente → `content == null` → `content.type` NPEs. |
+| `FolderRest.progress` linhas 125–126 | `folder` inexistente → `FolderManager.playerProgress` retorna `null` → `inside.percent` NPEs. |
+| `FolderManager.getMaxTimeInside` linhas 297–315 | (1) Quando `m.time == null` no primeiro item content, `MAX = m.time = null` (porque a condição `max==null` curto-circuita o `m.time.after(max)`), e o resto da iteração herda `null`. (2) Em recursão de folder, `MAX = getMaxTimeInside(m, max)` usa o **parâmetro** `max`, não o `MAX` acumulado — descarta valores anteriores. |
+| `FolderManager.findFolder` (e similares) | Quando `_id` não existe, retorna `null`. `FolderRest.find` serializa via `JsonUtil.toJsonRemoveNullFields(null)` → resposta com body vazio mas `200 OK`. Não há `404` no módulo. |
+| `FolderManager.insertLog` | Quando `log.item` aponta para um content inexistente, retorna sem salvar e sem erro — **HTTP 201 silencioso** (Seção 2.3). |
+| `DELETE /v3/folder?q=` / `/content?q=` | Concatenação direta de `q` no `query("{" + q + "}")` (Seção 8). |
+
+---
+
+## 8. Segurança e Permissões
+
+**Autenticação:** Bearer token via `@BeanParam AuthBean`. O `apiKey` (extraído do token) é o seletor de tenant em `FrontController.getInstance(authBean.getApiKey())`.
+
+**Isolamento por tenant:** cada `FrontController` mantém seu próprio `ManagerFactory` e `Jongo`/`MongoCollection`. Não há query cross-tenant em `FolderManager`.
+
+**Superfícies de injeção MongoDB confirmadas no código:**
+
+1. **`DELETE /v3/folder?q=<query>`** — `FolderRest.java:75`:
+
+   ```java
+   jongo.getCollection(Entity.FOLDER.collection)
+        .distinct("_id").query("{" + q + "}").as(String.class);
+   ```
+
+   `q` é concatenado bruto. Um cliente autenticado pode injetar operadores `$where`, `$or`, `$regex` etc. e disparar `deleteFolder` (cascata destrutiva) em todos os IDs retornados.
+
+2. **`DELETE /v3/folder/content?q=<query>`** — `FolderRest.java:230`: mesmo padrão na coleção `folder_content`.
+
+3. **`POST /v3/folder/content/aggregate` (body)** — `FolderManager.java:517`:
+
+   ```java
+   a.and(FunifierMarshaller.toString(aggregations.get(i)));
+   ```
+
+   Cada item do body é serializado e empurrado como estágio adicional do pipeline. Não há validação ou whitelist — `$lookup`, `$out`, `$merge`, `$function` (em Mongo recente) podem ser executados.
+
+**Recomendações operacionais:**
+
+- Restringir o uso desses endpoints a chaves administrativas; nunca expor diretamente ao cliente final.
+- Considerar um proxy / WAF que filtre `q` por regex de operadores perigosos.
+- Logs de auditoria devem capturar `q` integral e payload do aggregate.
+
+---
+
+## 9. Observabilidade e Troubleshooting
+
+### 9.1 Índices MongoDB
+
+Criados em `ConnectionPool.createIndexes()` (linhas 184–197):
+
+| Coleção | Campo(s) | Direção |
+|---|---|---|
+| `folder` | `parent` | `1` |
+| `folder_content` | `parent` | `1` |
+| `folder_content` | `position` | `1` |
+| `folder_log` | `item` | `1` |
+| `folder_log` | `player` | `1` |
+| `folder_log` | `status` | `1` |
+| `folder_log` | `time` | `1` |
+
+> **Faltam índices úteis:** `folder_log` não tem índice composto `(player, item)` nem `(player, item, finished)` — a query de idempotência (executada em todo `insertLog`) faz scan parcial.
+
+### 9.2 Comandos de diagnóstico
+
+```http
+# Existe a pasta?
+GET /v3/folder/<id>
+
+# Listar pastas raiz
+GET /v3/database/folder?q={"parent":{"$exists":false}}
+
+# Listar conteúdos diretos de uma pasta
+GET /v3/database/folder_content?q={"parent":"<folder_id>"}
+
+# Logs de progresso de um jogador
+GET /v3/database/folder_log?q={"player":"<player_id>"}
+
+# Log ativo (em andamento)
+GET /v3/database/folder_log?q={"player":"<p>","item":"<i>","finished":{"$exists":false}}
+
+# Verificar tipo de conteúdo
+GET /v3/database/folder_content_type?q={"_id":"<type_id>"}
+
+# Calcular progresso completo do jogador
+POST /v3/folder/progress
+{"folder":"<root_folder_id>","player":"<player_id>"}
+
+# Árvore estrutural (sem progresso)
+POST /v3/folder/inside
+{"folder":"<root_folder_id>"}
+```
+
+### 9.3 Sintomas vs causas
+
+| Sintoma | Causa provável |
+|---|---|
+| `POST /v3/folder/log` retorna `201` mas log não aparece em `folder_log` | `log.item` não existe em `folder_content`; pipeline aborta silenciosamente. |
+| `POST /v3/folder/log` lança `500` (NPE) | `log.percent == null` e `status != "done"`. Ou `current.percent` de um log antigo é `null`. |
+| `POST /v3/folder/breadcrumb` lança `500` (NPE) | `folder` inexistente, ou algum `parent` referenciado não existe no banco. |
+| `POST /v3/folder/progress` lança `500` (NPE) | `folder` inexistente — `FolderRest` não trata `inside == null`. |
+| `DELETE /v3/folder/log/{id}` lança `500` (NPE) | `id` inexistente. |
+| `DELETE /v3/folder/content/{id}` lança `500` (NPE) | `id` inexistente. |
+| `inside.percent` em folder folha está sempre `0.0` | Não há `folder_log` com `status="done"` para o player nesses contents; ou logs foram inseridos com `item` apontando para `Content._id` errado. |
+| `inside.time` zerado mas há `done` | Provavelmente caiu no fallback `getMaxTimeInside` que tem dois bugs latentes (Seção 7). |
+| Folder não aparece em `/inside` | `active == false` explícito. |
+| `is_unlocked == true` em folder bloqueado | Ancestor sem `unlock_policy`, ou `policy.type` diferente de `"progress"`. |
+| Trigger `folder_progress` não dispara após `insertLog` | (a) `content.parent` resolve em breadcrumb inválido; (b) o percent do folder **não aumentou** (mudança apenas no content individual sem cruzar threshold). |
+| Após `insertLog`, `started` aparece muito antigo | Há log ativo `!finished` para o mesmo `(player,item)`. Esperado. |
+| Após `deleteLog`, progresso da pasta não muda | Por design: `deleteLog` não recalcula folders pai. Re-consulte `POST /v3/folder/progress`. |
+
+---
+
+## 10. Exemplos Práticos
+
+### 10.1 Exemplo mínimo — trilha com um módulo e um conteúdo
+
+```http
+# 1. Criar pasta raiz
+POST /v3/folder
+{ "title": "Trilha de Onboarding" }
+# → 201 { "_id":"trail001","title":"Trilha de Onboarding","position":0,"active":true }
+
+# 2. Criar módulo filho
+POST /v3/folder
+{ "title": "Módulo 1 — Boas-vindas", "parent":"trail001", "position":0 }
+# → 201 { "_id":"mod001","parent":"trail001","position":0,"active":true }
+
+# 3. Definir tipo de conteúdo (via API de database — não há endpoint próprio)
+POST /v3/database/folder_content_type
+{ "_id":"video", "entity":"video__c", "input":"repository", "title":"Vídeo" }
+
+# 4. Vincular conteúdo ao módulo
+POST /v3/folder/content
+{ "type":"video", "content":"vid001", "parent":"mod001", "position":0 }
+# → 201 { "_id":"fc001","type":"video","content":"vid001","parent":"mod001","title":"<auto>","position":0 }
+
+# 5. Registrar conclusão pelo jogador
+POST /v3/folder/log
+{ "item":"fc001", "player":"player123", "status":"done" }
+# → 201 { "_id":"log001","item":"fc001","player":"player123","status":"done","percent":100.0,"started":"...","finished":"..." }
+
+# 6. Consultar progresso completo
+POST /v3/folder/progress
+{ "folder":"trail001", "player":"player123" }
+# → 200 { "_id":"trail001","folder":true,"player":"player123","total":1,"done":1,"percent":100.0,"is_unlocked":true,"items":[ ... ] }
+```
+
+### 10.2 Exemplo avançado — desbloqueio condicional por progresso de irmão anterior
+
+```http
+# Mod 1 (sem policy — sempre desbloqueado por ser primeiro irmão)
+POST /v3/folder
+{ "_id":"mod001", "title":"Módulo 1", "parent":"trail001", "position":0 }
+
+# Mod 2 — bloqueado até Mod 1 atingir 80%
+POST /v3/folder
+{ "_id":"mod002", "title":"Módulo 2", "parent":"trail001", "position":1,
+  "unlock_policy": { "type":"progress", "folder_ref":"prev", "min_percent":80 } }
+
+# Mod 3 — bloqueado até Mod 1 (específico) atingir 100%
+POST /v3/folder
+{ "_id":"mod003", "title":"Módulo 3", "parent":"trail001", "position":2,
+  "unlock_policy": { "type":"progress", "folder_ref":"mod001", "min_percent":100 } }
+
+# Filhos de Mod 3 herdam essa policy via resolveUnlockPolicy se não tiverem uma própria.
+```
+
+### 10.3 Exemplo — aggregate de conteúdos com dado real
+
+```http
+# Todos os contents da trilha (cascade), enriquecidos com `data`, primeiros 50
+POST /v3/folder/content/aggregate?folder=trail001&cascade=true&append_data=true
+Range: items=0-49
+[]
+# → { "results":[ { "_id":"fc001","type":"video","content":"vid001","parent":"mod001","data":{ ... item real ... } }, ... ], "pagination":{...} }
+
+# Mesma chamada com pipeline extra (ex: limitar a contents de tipo "video")
+POST /v3/folder/content/aggregate?folder=trail001&cascade=true
+Range: items=0-49
+[ { "$match": { "type": "video" } } ]
+```
+
+### 10.4 Anti-patterns — o que NÃO fazer
+
+```http
+# ❌ Inserir log direto na coleção via /v3/database — bypassa
+#    idempotência, normalização status/percent, breadcrumb, triggers folder_progress.
+POST /v3/database/folder_log
+{ "item":"fc001", "player":"p1", "status":"done" }
+
+# Use sempre:
+POST /v3/folder/log
+{ "item":"fc001", "player":"p1", "status":"done" }
+
+# ❌ DELETE em massa sem revisar `q`
+DELETE /v3/folder?q={"$where":"true"}    # remove TODAS as pastas
+
+# ❌ Enviar log sem `percent` e sem `status="done"` quando não há log ativo
+POST /v3/folder/log
+{ "item":"fc001", "player":"p1" }
+# Resultado: NullPointerException no servidor (Seção 7). Sempre envie ou
+# `status="done"` ou um `percent` numérico.
+
+# ❌ Renomear/mover folder por update direto da coleção `folder`
+POST /v3/database/folder
+{ "_id":"mod002", "parent":"<novo>", "position":3 }
+# Posições de irmãos ficam furadas porque `moveFolder` é quem normaliza —
+# Use POST /v3/folder/{id}/move?direction=up|down repetidamente.
+
+# ❌ Confiar em `POST /v3/folder/progress` como gatilho de mudança
+# Ele dispara `folder_progress` mesmo sem mudança (previous_percent ==
+# current_percent). Handlers que reagem a esse evento precisam comparar
+# valores ou só agir em payloads vindos do `insertLog`.
+```
 
-| Técnica | Integração |
-|---------|-----------|
-| **Challenge** | Desafio completado quando jogador termina todos os itens de um folder |
-| **Quiz** | Quizzes podem ser conteúdos dentro de um folder |
-| **Point** | Pontos concedidos ao progredir no folder |
-| **Achievement** | Conquista desbloqueada ao completar 100% do folder |
+---
 
-## Validações e Testes
+## Checklist de Configuração
 
-- [ ] Pasta aparece na lista
-- [ ] Hierarquia pai-filho funciona
-- [ ] Breadcrumb retorna caminho correto
-- [ ] Conteúdos são associados corretamente
-- [ ] Progresso do jogador é calculado corretamente
-- [ ] Action log é gerado ao progredir
+- [ ] Definir `FolderContentType` para cada tipo de conteúdo via `POST /v3/database/folder_content_type` antes de criar `folder_content`.
+- [ ] Escolher `input`: `repository` (item já existe em outra coleção) **ou** `formulary` (gerenciado junto ao vínculo).
+- [ ] Criar estrutura de pastas raiz → módulos → sub-pastas com `position` sequencial (`0,1,2…`).
+- [ ] Em `folder_content`, garantir que `parent` (folder) e `content` (item real) já existam — o servidor não valida.
+- [ ] Para desbloqueio condicional, definir `unlock_policy` apenas no nível mais alto necessário; descendentes herdam via `resolveUnlockPolicy`.
+- [ ] Usar **sempre** `POST /v3/folder/log` para registrar progresso; nunca `POST /v3/database/folder_log`.
+- [ ] Ao enviar `folder_log`, garantir `status="done"` **ou** `percent` numérico — `null` em ambos lança NPE.
+- [ ] Verificar a árvore com `POST /v3/folder/inside` antes de publicar; com `POST /v3/folder/progress` para validar `is_unlocked`.
+- [ ] Antes de `DELETE /v3/folder/{id}` ou `/content/{id}`: revisar a sub-árvore — operação é cascata, irreversível, e em `formulary` deleta o dado real também.
+- [ ] Nunca expor `DELETE /v3/folder?q=` e `DELETE /v3/folder/content?q=` ao cliente final — `q` é interpolado bruto no MongoDB.
+- [ ] Logar e auditar uso de `POST /v3/folder/content/aggregate` — estágios são passados sem validação.
+- [ ] Se progresso parecer "travado" após `deleteLog`, lembre: não há recálculo automático; chame `POST /v3/folder/progress` para atualizar `is_unlocked` no front.
+- [ ] Para handlers de trigger `folder_progress`, distinguir origem: payload de `insertLog` tem `previous_percent != current_percent`; payload de `POST /v3/folder/progress` tem ambos iguais.