funifier-mcp 0.2.26 → 0.2.27

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

@@ -1,40 +1,483 @@
-# Compact (Compactação)
+# `compact`
 
-**Acesso Studio:** `/studio/compact`
 **API Endpoint:** `/v3/compact`
+**Coleção MongoDB:** `compact` (configurações) e `compact_log` (logs de execução)
+**Acesso Studio:** não verificado neste repositório — o módulo foi confirmado apenas via API (`funifier-service` não contém código de UID/Studio para `compact`).
 
-## O que é
+> Documentação de engenharia reversa baseada exclusivamente no código-fonte de `funifier-service`
+> (`src/main/java/com/funifier/engine/compact/` e `src/main/java/com/funifier/rest/v3/rest/CompactRest.java`).
+> Reflete o comportamento **real** do runtime, não o comportamento REST convencional.
 
-Compactação e otimização do armazenamento de dados. Configura rotinas para agrupar registros e reduzir o espaço ocupado por dados históricos, como achievements ou logs, melhorando o tempo de resposta das consultas e a performance geral.
+---
 
-## Quando usar
+## 1. Visão Geral
 
-- Para compactar registros de achievements acumulados
-- Para otimizar coleções de acesso rápido
-- Para reduzir volume de dados históricos
+O módulo `compact` executa **compactação de coleções MongoDB via pipeline de agregação definido pelo cliente**. Ele não faz "compressão de armazenamento" genérica — ele **substitui N documentos por M documentos agregados** (M ≤ N) dentro de uma mesma coleção.
 
-## Checklist de Configuração no Studio
+O caso de uso canônico (visto em `_CompactTest`) é compactar o histórico de `achievement`: milhares de registros individuais antigos de um jogador são agrupados (`$group`) em um único registro consolidado com `total` somado e a lista dos `_id` originais preservada em `extra.compact`.
 
-- [ ] Definir coleções a compactar
-- [ ] Configurar critérios de agrupamento
-- [ ] Testar impacto na performance
+Papel arquitetural:
 
-## API Endpoints
+- É uma ferramenta **administrativa/operacional de manutenção de dados**, não um recurso de gamificação voltado ao jogador final.
+- Opera sobre **qualquer coleção** do banco do tenant — a coleção-alvo é um parâmetro (`collection`), não fixa.
+- O `match` (filtro) e o `aggregate` (pipeline) são **comandos MongoDB crus**, fornecidos pelo cliente e executados diretamente. O módulo é essencialmente um executor genérico de "agregação destrutiva".
 
-### Listar Compactações
-**Método:** GET
-**Endpoint:** `/v3/compact`
+Componentes (`com.funifier.engine.compact`):
 
-### Criar Compactação
-**Método:** POST
-**Endpoint:** `/v3/compact`
+| Classe | Papel |
+| --- | --- |
+| `Compact` | Entidade de configuração (coleção `compact`). |
+| `CompactLog` (+ `CompactLog.Total`) | Log/estado de uma execução (coleção `compact_log`). |
+| `CompactManager` | Manager: `save`, `delete`, `find`, `execute`, `compact`, `asyncExecute`, `findLog`. |
+| `CompactAsyncProcessor` | `Runnable` com fila em memória; uma thread por tenant. |
+| `CompactRest` | Resource JAX-RS em `/v3/compact`. |
 
-### Deletar Compactação
-**Método:** DELETE
-**Endpoint:** `/v3/compact/:id`
+O `CompactManager` é instanciado por tenant em `ManagerFactory` (linha 130), e seu construtor inicia imediatamente a thread assíncrona `Funifier-Compact-Async-<apiKey>`.
 
-## Validações e Testes
+---
 
-- [ ] Compactação é executada sem perda de dados
-- [ ] Volume de dados é reduzido
-- [ ] Consultas mantêm resultados corretos após compactação
+## 2. Arquitetura e Fluxos
+
+### 2.1 Pipeline principal
+
+A operação é dividida em uma **fase síncrona** (disparo) e uma **fase assíncrona** (execução real em background).
+
+**Fase síncrona — `CompactManager.execute(id)` (chamada por `CompactRest.execute`):**
+
+```
+1. busca Compact em "compact" por _id
+   se não existir            → retorna null (nada acontece)
+2. busca em "compact_log" um log com {compact:id, finish:{$exists:false}}  (execução em andamento)
+   se existir                → retorna esse log e NÃO inicia nova execução   (guard de concorrência)
+   se não existir            → segue para 3
+3. cria CompactLog {status:"started", total:{original:0, compacted:0}, start:now}
+   salva em "compact_log"
+   async.track(log)          → enfileira para a thread assíncrona
+4. retorna o log imediatamente (status "started")
+```
+
+`execute` é `synchronized`. O método `compact(id)` também existe, é `synchronized` e apenas delega para `execute(id)` — **não é usado pelo REST** (entrada alternativa/legada).
+
+**Fase assíncrona — `CompactManager.asyncExecute(log)` (rodando na thread do tenant):**
+
+```
+ 5. re-busca Compact por log.compact            → se null, encerra em silêncio
+ 6. source = coleção(compact.collection)
+ 7. total.original = source.count(match)        ; status="count items"        ; salva log
+ 8. parse do aggregate (JSON array) em estágios
+    monta source.aggregate("{$match:...}") + estágios, allowDiskUse(true)     ; status="group data" ; salva
+ 9. tmp = coleção "<logId>_tmp" ; tmp.drop()
+    para cada doc agregado: tmp.save(doc)        ; status="temp saved : N" (a cada 50)
+10. source.remove(match)                         ; status="removing original" ; salva   ← REMOVE ORIGINAIS
+11. para cada doc em tmp: source.save(doc)       ; status="compacted saved : N" (a cada 50)
+12. tmp.drop()
+13. total.compacted=N ; status="finished" ; finish=now ; salva
+14. dispara trigger after_finish na entidade "compact_log"
+    em qualquer exceção: status="error" ; finish=now ; message=<erro> ; salva ; (NENHUM trigger)
+```
+
+Características confirmadas no código:
+
+- **Assíncrono e serial por tenant.** A fila (`LinkedBlockingQueue` em `CompactAsyncProcessor`) é consumida por uma única thread por tenant. Dois `execute` para `compact` **diferentes** no mesmo tenant **enfileiram e rodam em sequência, não em paralelo**.
+- **Sem transação.** O `remove` da origem (passo 10) acontece **antes** da reinserção (passo 11). Não há rollback.
+- **`allowDiskUse(true)`** está habilitado na agregação (suporta datasets grandes).
+- **Trigger só no sucesso.** O `after_finish` (passo 14) está no caminho feliz; em erro, o `catch` registra o log e não dispara trigger.
+
+### 2.2 Fluxo de execução assíncrona — `asyncExecute`
+
+```mermaid
+flowchart TD
+    A["execute(id) cria CompactLog<br/>status: started"] --> B["async.track(log)<br/>enfileira"]
+    B --> C{"thread do tenant<br/>poll na fila"}
+    C --> D["asyncExecute(log)"]
+    D --> E{"Compact ainda<br/>existe?"}
+    E -- não --> Z1["encerra em silêncio"]
+    E -- sim --> F["count(match)<br/>total.original"]
+    F --> G["agrega para tmp<br/>&lt;logId&gt;_tmp"]
+    G --> H["source.remove(match)<br/>REMOVE ORIGINAIS"]
+    H --> I["reinsere tmp em source<br/>total.compacted"]
+    I --> J["tmp.drop()"]
+    J --> K["status: finished<br/>finish: now"]
+    K --> L["trigger after_finish<br/>(entidade compact_log)"]
+    F -.->|exceção| X["status: error<br/>message, finish<br/>(sem trigger)"]
+    G -.->|exceção| X
+    H -.->|exceção| X
+    I -.->|exceção| X
+```
+
+### 2.3 Interação entre componentes
+
+```mermaid
+sequenceDiagram
+    participant C as Cliente
+    participant R as CompactRest
+    participant M as CompactManager
+    participant Q as CompactAsyncProcessor (thread/tenant)
+    participant DB as MongoDB
+    participant T as TriggerManager
+
+    C->>R: GET /v3/compact/{id}/execute
+    R->>M: execute(id)
+    M->>DB: findOne compact / log em andamento
+    alt log em andamento existe
+        M-->>R: log existente (sem nova execução)
+    else
+        M->>DB: save(CompactLog status=started)
+        M->>Q: track(log)
+        M-->>R: log (started)
+    end
+    R-->>C: 200 + CompactLog
+
+    Note over Q: assíncrono
+    Q->>M: asyncExecute(log)
+    M->>DB: count(match) / aggregate -> tmp
+    M->>DB: remove(match) / reinsere tmp / drop tmp
+    M->>DB: save(log finished)
+    M->>T: execute(after_finish, compact_log)
+```
+
+---
+
+## 3. Estrutura dos Objetos
+
+### 3.1 `Compact` — documento de configuração (coleção `compact`)
+
+| Campo | Tipo | Padrão | Obrigatório | Descrição |
+| --- | --- | --- | --- | --- |
+| `_id` | String | auto (`Guid.shortTimeMillis()`) | — | Gerado se ausente/vazio no `save`. Cliente pode fornecer o próprio. |
+| `title` | String | — | Não | Rótulo descritivo. **Não é validado nem usado em nenhuma lógica.** |
+| `collection` | String | — | **Sim** | Coleção MongoDB de origem a ser compactada. |
+| `match` | String | — | **Sim** | Filtro MongoDB (JSON) que seleciona os documentos a compactar. Suporta keywords de data Funifier (ver 3.4). |
+| `aggregate` | String | — | **Sim** | Pipeline de agregação MongoDB (JSON **array**) que produz os documentos compactados. |
+| `created` | Date | auto | — | Definido no primeiro `save` (quando `_id` é gerado). |
+| `updated` | Date | auto | — | Atualizado em **todo** `save`. |
+
+**Tipo dos campos `match` e `aggregate`:** são `String` em Java. O corpo da requisição deve enviá-los como **strings JSON escapadas** (JSON-encoded), **não** como objeto/array JSON nativo. Não foi encontrado `ContextResolver<ObjectMapper>` customizado no JAX-RS, então a desserialização padrão do Jackson exige string para um campo `String`. Todos os exemplos da seção 10 seguem esse contrato.
+
+**Campos legados/comentados (NÃO suportados):**
+
+- `active` (boolean) — comentado em `Compact.java`. **Não há flag de ativação/desativação.**
+- `cron` (String) — comentado. **Não há agendamento automático.** Toda execução é manual via endpoint.
+
+> O comentário de design no topo de `CompactManager.java` menciona `{title, active, collection, match, group, cron}`, mas `active`, `group` e `cron` não existem no runtime — `aggregate` substituiu `group`.
+
+### 3.2 `CompactLog` — log/estado de execução (coleção `compact_log`)
+
+| Campo | Tipo | Descrição |
+| --- | --- | --- |
+| `_id` | String | `Guid.shortTimeMillis()`. **Também é o nome base da coleção temporária** `<_id>_tmp`. |
+| `compact` | String | `_id` da configuração `Compact` associada. |
+| `status` | String | Estado textual do processo (ver 3.3). Não é enum — é string livre. |
+| `start` | Date | Início da execução. |
+| `finish` | Date | Fim da execução. **Ausente enquanto em andamento** — campo-chave do guard de concorrência. |
+| `total` | `Total` | Contagens de itens (ver abaixo). |
+| `message` | String | Mensagem de erro (`e.getMessage()`), preenchida apenas em falha. |
+
+`CompactLog.Total`:
+
+| Campo | Tipo | Descrição |
+| --- | --- | --- |
+| `original` | long | Quantidade de documentos que casaram com `match` (antes da compactação). |
+| `compacted` | long | Quantidade de documentos reinseridos após a agregação. |
+
+### 3.3 Ciclo de vida de `CompactLog.status`
+
+```mermaid
+stateDiagram-v2
+    [*] --> started: execute()
+    started --> count_items: count(match)
+    count_items --> group_data: monta aggregate
+    group_data --> temp_saved: insere em tmp (a cada 50)
+    temp_saved --> removing_original: source.remove(match)
+    removing_original --> compacted_saved: reinsere (a cada 50)
+    compacted_saved --> finished: finish=now + trigger
+    finished --> [*]
+    count_items --> error: exceção
+    group_data --> error: exceção
+    temp_saved --> error: exceção
+    removing_original --> error: exceção
+    compacted_saved --> error: exceção
+    error --> [*]
+```
+
+Valores reais de `status`: `started`, `count items`, `group data`, `temp saved : <N>`, `removing original`, `compacted saved : <N>`, `finished`, `error`.
+
+### 3.4 Keywords de data no `match` (`FunifierMarshaller`)
+
+Antes de executar, `match` passa por `FunifierMarshaller.toString`, que converte expressões de data Funifier em epoch millis. Ex. (de `_CompactTest`):
+
+```json
+{"time":{ "$gte":{"$date":"-10y"}, "$lte":{"$date":"now"} }}
+```
+
+`{"$date":"-10y"}` e `{"$date":"now"}` são resolvidos para timestamps numéricos via `DateUtil.fromKeyword`. Isso permite filtros relativos (ex.: "tudo com mais de 10 anos").
+
+> Observação técnica: no passo do `$match` da agregação o código aplica `FunifierMarshaller.toString` **duas vezes** (`toString(toString(match))`). A segunda passagem é redundante (re-parse/re-serialize de um JSON já normalizado) — inofensiva, mas é código a ser simplificado.
+
+---
+
+## 4. Endpoints
+
+Base: `/v3/compact` (`CompactRest`). Autenticação via `AuthBean` (Bearer token JAX-RS); o nível de permissão exato não foi verificado nesta leitura.
+
+### `POST /v3/compact` — criar/atualizar configuração
+
+| Aspecto | Detalhe |
+| --- | --- |
+| Finalidade | Persiste uma `Compact` (cria se `_id` ausente, atualiza se presente). |
+| Handler | `CompactRest.insert` → `CompactManager.save` |
+| Full replace ou patch | **Full replace** — `col.save(obj)` substitui o documento inteiro. |
+| Status de sucesso | `201 CREATED` |
+| Resposta | Objeto `Compact` com nulos removidos (`toJsonRemoveNullFields`). |
+
+**Comportamento real (crítico):** `save` só persiste se `obj != null && collection != null && match != null && aggregate != null`. Se qualquer um (`collection`, `match`, `aggregate`) for nulo, **nada é gravado e nenhum erro é retornado** — o endpoint ainda responde `201 CREATED` com o corpo enviado. `title` **não** é obrigatório. Ver seções 5 e Checklist.
+
+### `GET /v3/compact/{id}` — buscar configuração
+
+| Aspecto | Detalhe |
+| --- | --- |
+| Finalidade | Retorna a `Compact` por `_id`. |
+| Handler | `CompactRest.find` → `CompactManager.find` |
+| Status | `200 OK` |
+| Resposta | `Compact` (nulos removidos). Se `_id` não existe, corpo vazio/`null`. |
+
+### `DELETE /v3/compact/{id}` — remover configuração
+
+| Aspecto | Detalhe |
+| --- | --- |
+| Finalidade | Remove a `Compact` **e todos os seus logs** associados. |
+| Handler | `CompactRest.delete` → `CompactManager.delete` |
+| Status | `204 NO CONTENT` |
+
+**Comportamento real:** cascata — remove de `compact` por `_id` **e** de `compact_log` por `{compact:id}`. Não remove dados já compactados na coleção de origem (a compactação é irreversível por aqui).
+
+### `GET /v3/compact/{id}/execute` — disparar compactação
+
+| Aspecto | Detalhe |
+| --- | --- |
+| Finalidade | Inicia (ou retorna a execução em andamento) da compactação. |
+| Handler | `CompactRest.execute` → `CompactManager.execute` |
+| Verbo | **`GET`** — apesar de causar efeito colateral destrutivo (não é idempotente no sentido REST). |
+| Status | `200 OK` |
+| Resposta | `CompactLog` recém-criado (`started`) ou o log em andamento existente. |
+
+**Comportamento real:** retorna **imediatamente** (processamento assíncrono). Se já houver um log sem `finish` para esse `compact`, retorna esse log e **não** inicia nova execução. Use o `_id` do log retornado para acompanhar o progresso consultando a coleção `compact_log`.
+
+**Exemplo de resposta de `execute`:**
+
+```json
+{
+  "_id": "Xa9bC2",
+  "compact": "c1",
+  "status": "started",
+  "start": 1747699200000,
+  "total": { "original": 0, "compacted": 0 }
+}
+```
+
+---
+
+## 5. Regras de Negócio
+
+Regras presentes no código mas ausentes do schema:
+
+- **Validação silenciosa no `save`.** Sem `collection`/`match`/`aggregate`, o `save` é ignorado sem erro — porém o `POST` retorna `201`. É o footgun mais perigoso do módulo.
+- **Guard de concorrência por log não finalizado.** `execute` não inicia nova execução enquanto existir um `compact_log` sem `finish` para o mesmo `compact`. Isso evita execuções concorrentes — mas também **trava permanentemente** novas execuções se um log ficar "preso" (ver seção 9).
+- **Execução serial por tenant.** Uma única thread por tenant processa a fila; compactações concorrem em fila, não em paralelo.
+- **Janela de perda de dados (não-transacional).** O passo `source.remove(match)` ocorre **antes** da reinserção. Uma falha do servidor entre remover e reinserir deixa os originais apenas na coleção temporária `<logId>_tmp` (que **não** é dropada em caso de crash). Não há rollback automático.
+- **`aggregate` deve produzir substitutos válidos.** O cliente é responsável por escrever um pipeline que gere documentos que substituam corretamente os originais. Convenção observada em `_CompactTest`: `$group` + `$project` preservando os `_id` originais em `extra.compact` e gerando novo `_id`. Nada disso é validado pelo código.
+- **Comandos MongoDB crus.** `match` e `aggregate` são executados diretamente contra o MongoDB. Qualquer coleção do tenant pode ser alvo. Ver seção 8.
+- **Multi-tenant.** Toda operação ocorre via `manager.getJongoConnection()`, que é a conexão do banco do tenant (resolvido pela `apiKey`). Isolamento é por banco de tenant.
+
+---
+
+## 6. Comportamentos Automáticos
+
+| Comportamento | Trigger | Impacto | Persistência |
+| --- | --- | --- | --- |
+| Geração de `_id` | `save` com `_id` nulo/vazio | `Guid.shortTimeMillis()` + `created=now` | coleção `compact` |
+| `updated` automático | todo `save` | `updated=now` | coleção `compact` |
+| Cascata de logs | `DELETE /{id}` | remove todos `compact_log` do compact | coleção `compact_log` |
+| Atualização de status | durante `asyncExecute` | salva log a cada estágio e a cada 50 inserções | coleção `compact_log` |
+| Trigger `after_finish` | fim **bem-sucedido** de `asyncExecute` | dispara `TriggerManager.execute` | conforme triggers configurados |
+
+**Trigger `after_finish`** — única integração externa do módulo. Chamada (passo 14):
+
+```
+TriggerManager.execute(
+    id      = log.compact,                 // _id da config Compact
+    o       = log,                         // o CompactLog finalizado
+    entity  = "compact_log",
+    event   = "after_finish",
+    player  = null,
+    context = { extra: { "compact": <Compact> } }
+)
+```
+
+Para reagir ao término de uma compactação, registre um trigger na entidade `compact_log` com evento `after_finish`. **Não dispara em caso de erro.**
+
+---
+
+## 7. Suportado vs NÃO Suportado
+
+### ✅ Suportado
+
+- Criar/atualizar configuração de compactação (`POST`).
+- Buscar configuração por `_id` (`GET /{id}`).
+- Deletar configuração + cascata de logs (`DELETE /{id}`).
+- Disparar compactação manualmente (`GET /{id}/execute`).
+- Pipeline de agregação MongoDB arbitrário definido pelo cliente.
+- Filtro `match` com keywords de data relativas (`-10y`, `now`, etc.).
+- Acompanhamento de progresso via documento `compact_log` (status textual + totais).
+- Trigger `after_finish` no término bem-sucedido.
+- `allowDiskUse` em agregações grandes.
+
+### ❌ NÃO Suportado
+
+- **Listar configurações** — não existe `GET /v3/compact` (sem endpoint de listagem). A documentação antiga que mencionava "Listar Compactações" estava incorreta.
+- **Ler `CompactLog` via REST** — `findLog` existe no manager mas **não é exposto**. O acompanhamento depende de consultar a coleção `compact_log` por outra via (ex.: API de database/aggregate).
+- **Agendamento/cron** — campo `cron` comentado; nenhuma execução automática.
+- **Ativar/desativar** — campo `active` comentado; toda config é sempre "executável".
+- **Transacionalidade / rollback** — não há; existe janela de perda de dados (seção 5).
+- **Reversão de compactação** — o `DELETE` remove config e logs, não restaura documentos compactados.
+- **Durabilidade da fila** — a fila é em memória (`LinkedBlockingQueue`); reinício do servidor perde execuções enfileiradas e pode deixar logs presos.
+- **Recuperação automática de log preso** — não há; intervenção manual em `compact_log` é necessária.
+- **Validação do pipeline** — `aggregate`/`match` não são validados; erros só aparecem em runtime no `compact_log` (status `error`).
+- **`title` operacional** — aceito mas ignorado pela lógica.
+- **Trigger em falha** — `after_finish` não dispara em erro; não há evento de erro.
+
+---
+
+## 8. Segurança e Permissões
+
+- **Autenticação:** via `AuthBean` (Bearer token, padrão JAX-RS dos resources `/v3`). O nível/role exigido **não foi verificado** nesta leitura — não confirme "somente admin" sem checar o filtro de autenticação.
+- **Isolamento por tenant:** todas as operações usam a conexão Jongo do tenant (resolvida pela `apiKey`), confinando o efeito ao banco daquele tenant.
+- **Superfície de injeção / capacidade perigosa (confirmada no código):** `match` e `aggregate` são **comandos MongoDB crus** fornecidos pelo cliente e executados diretamente (`source.count`, `source.aggregate`, `source.remove`). Quem puder chamar `/v3/compact`:
+  - pode apontar `collection` para **qualquer coleção** do tenant (inclusive coleções de sistema/configuração);
+  - pode escrever um `match` que casa com **todos** os documentos e um `aggregate` que os reduz/destrói — efetivamente um `remove` em massa disfarçado de compactação;
+  - não há lista de coleções permitidas, nem sanitização do pipeline.
+  Trate o acesso a este módulo como **privilégio administrativo de banco de dados**, não como recurso de aplicação.
+- **`GET` com efeito destrutivo:** `GET /{id}/execute` modifica dados. Isso pode ser disparado acidentalmente por mecanismos que assumem `GET` como seguro (prefetch, crawlers, retries). Considere isso ao expor a rota.
+
+---
+
+## 9. Observabilidade e Troubleshooting
+
+Não há endpoint REST para ler logs; investigue diretamente na coleção `compact_log`.
+
+**Verificar a execução mais recente de um compact:**
+
+```
+// na coleção compact_log
+{ "compact": "<compactId>" }   // ordenar por start desc
+```
+
+**Encontrar execuções presas (em andamento, sem `finish`):**
+
+```
+{ "finish": { "$exists": false } }
+```
+
+- Erros comuns e causas:
+  - **`POST` retornou 201 mas a config "sumiu":** faltou `collection`, `match` ou `aggregate` → `save` ignorado silenciosamente. Confira com `GET /v3/compact/{id}`.
+  - **`execute` sempre retorna o mesmo log `started`/intermediário e nunca roda de novo:** existe um `compact_log` sem `finish` (log preso, geralmente por reinício do servidor durante o processamento). O guard em `execute` bloqueia novas execuções. **Correção:** localizar o log preso (`{compact:id, finish:{$exists:false}}`) e removê-lo ou definir `finish`; verificar se a coleção temporária `<logId>_tmp` contém dados ainda não reinseridos antes de descartá-la.
+  - **`status: "error"`:** ler o campo `message` do `compact_log` (vem de `e.getMessage()`); causas típicas: `aggregate` malformado, `match` inválido, `collection` inexistente.
+  - **Dados originais sumiram e não foram recompactados:** possível crash entre `remove` (passo 10) e reinserção (passo 11). Procurar a coleção `<logId>_tmp` — ela retém os documentos agregados e **não** é dropada em crash.
+
+**Diagnóstico de saúde do módulo:** a thread `Funifier-Compact-Async-<apiKey>` deve estar viva por tenant; ela loga `COMECOU EXECUCAO DA THREAD COMPACT ASYNC` no start. Sem ela, logs ficam em `started` para sempre.
+
+Comandos úteis:
+
+```
+GET /v3/compact/<id>            # ver a configuração
+GET /v3/compact/<id>/execute    # disparar e obter o _id do log
+# acompanhar progresso: consultar compact_log por _id do log (status/total)
+```
+
+---
+
+## 10. Exemplos Práticos
+
+> Lembre-se: `match` e `aggregate` vão no corpo como **strings JSON escapadas**.
+
+### 10.1 Exemplo mínimo funcional
+
+Compactar achievements antigos de cada jogador em um único registro consolidado (baseado em `_CompactTest`):
+
+```json
+POST /v3/compact
+{
+  "_id": "c1",
+  "title": "Compact Achievements",
+  "collection": "achievement",
+  "match": "{\"time\":{\"$gte\":{\"$date\":\"-10y\"},\"$lte\":{\"$date\":\"now\"}}}",
+  "aggregate": "[{\"$group\":{\"_id\":{\"player\":\"$player\",\"type\":\"$type\",\"item\":\"$item\"},\"total\":{\"$sum\":\"$total\"},\"time\":{\"$max\":\"$time\"},\"ids\":{\"$push\":\"$_id\"}}},{\"$project\":{\"_id\":0,\"player\":\"$_id.player\",\"type\":\"$_id.type\",\"item\":\"$_id.item\",\"total\":1,\"time\":1,\"extra\":{\"compacted\":\"true\",\"compact\":\"$ids\"}}}]"
+}
+```
+
+Disparar:
+
+```
+GET /v3/compact/c1/execute
+```
+
+### 10.2 Exemplo avançado — gerar novo `_id` no documento compactado
+
+O `$project` zera o `_id` original; um `$addFields` gera um novo `ObjectId` como string (evita colisão ao reinserir). Pipeline (forma legível, antes de escapar):
+
+```json
+[
+  { "$group": {
+      "_id": { "player": "$player", "type": "$type", "item": "$item" },
+      "total": { "$sum": "$total" },
+      "time": { "$max": "$time" },
+      "ids": { "$push": "$_id" }
+  }},
+  { "$project": {
+      "_id": 0, "player": "$_id.player", "type": "$_id.type", "item": "$_id.item",
+      "total": 1, "time": 1, "extra": { "compacted": "true", "compact": "$ids" }
+  }},
+  { "$addFields": {
+      "_id": { "$function": {
+          "body": "function() { return new ObjectId().toString().replace(/ObjectId\\(\"|\"\\)/g, ''); }",
+          "args": [], "lang": "js"
+      }}
+  }}
+]
+```
+
+Preservar os `_id` originais em `extra.compact` é a única forma de rastrear o que foi colapsado — o módulo **não** guarda isso automaticamente.
+
+### 10.3 Anti-pattern — o que NÃO fazer
+
+```json
+POST /v3/compact
+{
+  "title": "Limpar logs",
+  "collection": "achievement",
+  "match": "{}"
+}
+```
+
+Por que está errado:
+
+1. **Falta `aggregate`** → `save` é ignorado silenciosamente, mas o `POST` retorna `201`. Você acha que criou; não criou.
+2. Mesmo que `aggregate` fosse incluído, **`match: "{}"` casa com TODOS os documentos** da coleção. O passo `source.remove(match)` apagaria a coleção inteira antes da reinserção — se o `aggregate` estiver errado, é perda total.
+3. `collection: "achievement"` sem entender o pipeline de substituição transforma "compactação" em "deleção em massa".
+
+**Regra:** sempre teste o `match` (quantos documentos casa) e valide o `aggregate` em ambiente controlado **antes** de executar em produção, pois a operação remove os originais.
+
+---
+
+## Checklist de Configuração
+
+- [ ] `collection` preenchido (coleção de origem existe).
+- [ ] `match` preenchido — e **testado**: confira quantos documentos ele casa antes de executar.
+- [ ] `aggregate` preenchido — pipeline válido que **gera documentos substitutos completos** (incluindo `_id`).
+- [ ] Armadilha: se `collection`/`match`/`aggregate` faltarem, o `POST` retorna `201` mas **nada é salvo** — confirme com `GET /v3/compact/{id}`.
+- [ ] Armadilha: `match` amplo (ex.: `{}`) + `aggregate` incorreto = **perda de dados** (remove antes de reinserir, sem transação).
+- [ ] Preserve os `_id` originais no pipeline (ex.: `extra.compact`) se precisar de rastreabilidade — o módulo não faz isso sozinho.
+- [ ] Pós-execução: acompanhe o `compact_log` (`status`/`total`); `finished` = ok, `error` = leia `message`.
+- [ ] Recuperação: se um log ficar preso sem `finish`, novas execuções são bloqueadas — limpe o log e verifique a coleção `<logId>_tmp`.
+- [ ] Trigger opcional: registre `after_finish` na entidade `compact_log` para reagir ao término.
+- [ ] Lembre-se: `match`/`aggregate` viajam como **strings JSON escapadas** no corpo da requisição.