funifier-mcp 0.2.26 → 0.2.28

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

@@ -1,40 +1,618 @@
-# Backup (Backup)
+# `backup`
 
 **Acesso Studio:** `/studio/backup`
 **API Endpoint:** `/v3/backup`
+**Coleção MongoDB:** `backup` (configurações) e `backup_log` (logs de execução)
 
-## O que é
+> Documentação de engenharia reversa baseada **exclusivamente** no código-fonte do projeto `funifier-service` (`com.funifier.engine.backup.*` e `com.funifier.rest.v3.rest.BackupRest`). Onde o comportamento real difere do esperado por convenção REST ou do que o schema sugere, isso está marcado explicitamente.
 
-Backup e remoção controlada de dados antigos. Permite criar rotinas automáticas de backup de registros importantes, além de remover dados antigos de maneira controlada para manter a performance da plataforma.
+---
 
-## Quando usar
+## 1. Visão Geral
 
-- Para fazer backup de logs antigos antes de atualizações
-- Para remover registros históricos e otimizar consultas
-- Para manter performance em grandes volumes de dados
+O módulo `backup` move/copia documentos de uma coleção MongoDB para outra coleção, opcionalmente aplicando um pipeline de **aggregate** de transformação e opcionalmente **removendo os documentos originais** após a cópia. É o mecanismo usado para arquivar dados antigos (logs, achievements históricos, etc.) e aliviar coleções de alto volume.
 
-## Checklist de Configuração no Studio
+Papel arquitetural:
 
-- [ ] Definir quais coleções serão backupeadas
-- [ ] Configurar frequência do backup
-- [ ] Definir critério de remoção de dados antigos
+- Uma **configuração de backup** (documento na coleção `backup`) descreve *o que* copiar (`collection` + `match`), *como transformar* (`aggregate`), *para onde* (`backupCollectionName`), e *o que fazer com a origem* (`deleteOriginalDataAfterBackup`).
+- A execução é **assíncrona e manual/on-demand**: disparada via endpoint `GET /v3/backup/{id}/execute`, processada por uma thread dedicada por tenant (`BackupAsyncProcessor`).
+- Cada execução gera um documento de **log** (coleção `backup_log`) que registra status, contagens e timestamps.
 
-## API Endpoints
+Relação com outros módulos:
 
-### Listar Backups
-**Método:** GET
-**Endpoint:** `/v3/backup`
+- É um quase-clone estrutural do módulo `compact` (`com.funifier.engine.compact.CompactManager`). Ambos seguem o mesmo padrão (config + log + thread assíncrona por tenant). A diferença conceitual é que `backup` foca em copiar/transformar para outra coleção; `compact` foca em compactar.
+- Integra com o módulo `trigger`: ao **finalizar com sucesso**, dispara o evento `after_finish` sobre a entidade `backup_log` (ver Seção 6).
+- É multi-tenant: cada `apiKey` tem sua própria instância de `BackupManager` e sua própria thread/fila assíncrona (ver Seção 5).
 
-### Criar Backup
-**Método:** POST
-**Endpoint:** `/v3/backup`
+> **Atenção:** Diferente do que a documentação anterior afirmava, o módulo **não** possui agendamento automático (cron), **não** possui flag `active`, e **não** possui endpoint de listagem. Esses recursos estão ausentes do código (ver Seção 7).
 
-### Deletar Backup
-**Método:** DELETE
-**Endpoint:** `/v3/backup/:id`
+---
 
-## Validações e Testes
+## 2. Arquitetura e Fluxos
 
-- [ ] Backup é executado com sucesso
-- [ ] Dados antigos são removidos conforme critério
-- [ ] Performance melhora após limpeza
+### 2.1 Pipeline principal — disparo (`execute`)
+
+Fluxo síncrono executado quando o cliente chama `GET /v3/backup/{id}/execute` (`BackupRest.execute` → `BackupManager.execute`):
+
+1. **[Entrada]** `BackupRest.execute(authBean, id)` resolve o tenant via `FrontController.getInstance(apiKey)` e chama `getBackupManager().execute(id)`.
+2. **[Lookup config]** `execute(id)` busca a config na coleção `backup`: `findOne("{_id:#}", id)`. Se **não existir**, retorna `null` (sem erro) e o fluxo termina.
+3. **[Verificação de execução em andamento]** Busca em `backup_log` por um log do mesmo backup **sem o campo `finish`**: `findOne("{backup:#, finish:{$exists:false}}", id)`.
+   - Se já existir um log em andamento → **retorna esse log existente sem enfileirar nada** (idempotência / lock lógico). Nenhuma nova execução é iniciada.
+4. **[Criação do log]** Se não houver log em andamento, cria um novo `BackupLog` com `status="started"`, `start=now`, `total={original:0, backuped:0}` e salva em `backup_log`.
+5. **[Enfileiramento]** Chama `async.track(log)` que adiciona o log a uma fila em memória (`LinkedBlockingQueue`).
+6. **[Retorno]** Retorna o log recém-criado (status `"started"`) imediatamente — o trabalho pesado roda em background.
+
+> **Síncrono vs assíncrono:** os passos 1–6 são síncronos e rápidos (apenas criam o log e enfileiram). Todo o trabalho de cópia (passos da Seção 2.2) roda **assíncronamente** na thread `Funifier-Backup-Async-<apiKey>`.
+
+### 2.2 Pipeline principal — execução assíncrona (`asyncExecute`)
+
+A thread `BackupAsyncProcessor.run()` faz polling da fila a cada 1s (`Thread.sleep(1000)` quando vazia). Ao retirar um log, chama `BackupManager.asyncExecute(log)`:
+
+```
+[1] re-busca a config backup por log.backup           -> findOne("{_id:#}", log.backup)
+    se config == null -> nada acontece (log fica "started" para sempre)
+[2] source = coleção backup.collection
+[3] log.total.original = source.count(match)           -> status="count items", save(log)
+[4] monta pipeline aggregate:
+      [{$match: <backup.match>}, ...<backup.aggregate>] -> status="group data", save(log)
+      (allowDiskUse=true)
+[5] bkp = coleção backup.backupCollectionName
+[6] se NÃO incremental -> bkp.drop()                    (apaga a coleção de destino inteira)
+[7] para cada doc do aggregate:
+      bkp.save(doc); backuped++
+      a cada 50 docs -> status="backuped saved : N", save(log)
+[8] se deleteOriginalDataAfterBackup:
+      status="removing original", source.remove(match), save(log)
+[9] log.total.backuped = backuped
+    status="finished"; log.finish = now; save(log)
+[10] dispara trigger after_finish sobre backup_log
+```
+
+Em caso de **qualquer exceção** durante os passos acima:
+
+```
+catch(Exception e):
+  e.printStackTrace()
+  log.status = "error"
+  log.finish = now
+  log.message = e.getMessage()
+  save(log)
+  -> o trigger after_finish NÃO é disparado
+```
+
+### Fluxo de execução — `execute` → `asyncExecute`
+
+```mermaid
+flowchart TD
+    A["GET /v3/backup/{id}/execute"] --> B["BackupManager.execute(id)"]
+    B --> C{config backup existe?}
+    C -- não --> Z["retorna null (HTTP 200, body null)"]
+    C -- sim --> D{"existe log sem finish?"}
+    D -- sim --> E["retorna log em andamento\n(não re-enfileira)"]
+    D -- não --> F["cria BackupLog status=started\nsalva em backup_log"]
+    F --> G["async.track(log)\n(fila em memória)"]
+    G --> H["retorna log status=started"]
+
+    subgraph Thread["Thread Funifier-Backup-Async-apiKey"]
+      I["poll fila (1s)"] --> J["asyncExecute(log)"]
+      J --> K["count items"]
+      K --> L["monta aggregate\n[{$match}, ...aggregate]"]
+      L --> M{incremental?}
+      M -- não --> N["bkp.drop()"]
+      M -- sim --> O["mantém destino"]
+      N --> P["save cada doc\n(log a cada 50)"]
+      O --> P
+      P --> Q{deleteOriginalDataAfterBackup?}
+      Q -- sim --> R["source.remove(match)"]
+      Q -- não --> S["mantém origem"]
+      R --> T["status=finished, finish=now"]
+      S --> T
+      T --> U["trigger after_finish"]
+    end
+    G -.enfileira.-> I
+```
+
+### 2.3 Interação entre componentes
+
+```mermaid
+sequenceDiagram
+    participant C as Cliente
+    participant R as BackupRest
+    participant M as BackupManager
+    participant Q as BackupAsyncProcessor (thread)
+    participant DB as MongoDB
+    participant T as TriggerManager
+
+    C->>R: GET /v3/backup/{id}/execute
+    R->>M: execute(id)
+    M->>DB: findOne backup {_id}
+    M->>DB: findOne backup_log {backup, finish:$exists:false}
+    alt log em andamento existe
+        M-->>R: log existente
+    else
+        M->>DB: save(BackupLog status=started)
+        M->>Q: track(log)
+        M-->>R: log (started)
+    end
+    R-->>C: 200 + BackupLog
+
+    Note over Q: polling assíncrono (1s)
+    Q->>M: asyncExecute(log)
+    M->>DB: count(match) / aggregate / save / remove
+    M->>DB: save(log status=finished)
+    M->>T: execute(backup, log, "backup_log", "after_finish")
+```
+
+> Não há transações MongoDB. As atualizações de `backup_log`, as inserções na coleção de destino e a remoção da origem são operações independentes e **não atômicas**. Uma falha no meio do passo [7] deixa a coleção de destino parcialmente preenchida e o log com `status="error"`, sem rollback.
+
+---
+
+## 3. Estrutura dos Objetos
+
+### 3.1 `Backup` — documento de configuração (coleção `backup`)
+
+Mapeado por `com.funifier.engine.backup.Backup` (`@Data @Builder @JsonIgnoreProperties(ignoreUnknown=true)`).
+
+| Campo                          | Tipo    | Padrão                       | Obrigatório | Descrição |
+| ------------------------------ | ------- | ---------------------------- | ----------- | --------- |
+| `_id`                          | String  | auto (`Guid.shortTimeMillis`) | —           | Gerado no `save` quando ausente/vazio. Time-based curto. Se enviado, é respeitado (upsert). |
+| `title`                        | String  | null                         | Não         | Rótulo descritivo livre. **Não é validado nem usado pela lógica de execução.** |
+| `collection`                   | String  | null                         | **Sim**     | Coleção de **origem** dos dados. Sem ele, `save` é silenciosamente ignorado. |
+| `match`                        | String  | null                         | **Sim**     | Filtro MongoDB (JSON/BSON estendido Funifier) que seleciona quais documentos copiar. Usado em `count`, `aggregate $match` e `remove`. |
+| `aggregate`                    | String  | null                         | **Sim**     | Pipeline de aggregate (array JSON de estágios) aplicado **após** o `$match`. Transforma os dados antes do backup. |
+| `backupCollectionName`         | String  | `<collection>_bkp`           | Não         | Coleção de **destino**. Default automático no `save` quando vazio. |
+| `incremental`                  | boolean | `false`                      | Não         | `false` → destino é dropado antes da inserção. `true` → destino é preservado (ver Seção 5). |
+| `deleteOriginalDataAfterBackup`| boolean | `false`                      | Não         | `true` → remove da origem todos os documentos que casam com `match`, **após** a cópia. |
+| `created`                      | Date    | auto (na criação)            | —           | Definido **apenas** quando `_id` é novo. Ver footgun de full-replace na Seção 5. |
+| `updated`                      | Date    | auto (todo save)             | —           | Sempre redefinido para `now` no `save`. |
+
+**Campos legados / removidos (comentados no código — NÃO existem no runtime):**
+
+- `active` (`boolean`) — comentado em `Backup.java` linha 28. Indicaria se a rotina está ativa. **Não implementado.**
+- `cron` (`String`) — comentado em `Backup.java` linha 29. Indicaria expressão de agendamento automático. **Não implementado** (não há scheduler).
+
+**Comportamento de campos:**
+
+- Por `@JsonIgnoreProperties(ignoreUnknown=true)`, **qualquer campo extra enviado no request é silenciosamente descartado** (não persiste, não gera erro).
+- `title` é puramente cosmético: nunca é lido pela lógica de `execute`/`asyncExecute`.
+
+### 3.2 `BackupLog` — documento de log de execução (coleção `backup_log`)
+
+Mapeado por `com.funifier.engine.backup.BackupLog`.
+
+| Campo     | Tipo                    | Padrão     | Descrição |
+| --------- | ----------------------- | ---------- | --------- |
+| `_id`     | String                  | auto       | `Guid.shortTimeMillis`. |
+| `backup`  | String                  | —          | `_id` da config de backup associada. |
+| `status`  | String                  | `"started"`| Enum implícito (ver 3.3). |
+| `start`   | Date                    | now        | Início da execução (definido na criação do log). |
+| `finish`  | Date                    | ausente    | Definido apenas ao terminar (`finished`) ou falhar (`error`). **Sua ausência é o que marca um log "em andamento".** |
+| `total`   | `Total{original,backuped}` | `{0,0}` | Contagens (ver abaixo). |
+| `message` | String                  | null       | Preenchido **somente** no caminho de erro (`e.getMessage()`). |
+| `extra`   | `HashMap<String,Object>`| null       | **Declarado mas nunca escrito** por `BackupManager`. Campo morto (ver Seção 7). |
+
+Subobjeto `Total`:
+
+| Campo      | Tipo | Descrição |
+| ---------- | ---- | --------- |
+| `original` | long | Contagem de documentos na origem que casam com `match` (definido em "count items"). |
+| `backuped` | long | Contagem de documentos efetivamente salvos no destino (definido ao finalizar). |
+
+> `original` e `backuped` são `long` primitivos → valem `0` por padrão e **não** são removidos por `toJsonRemoveNullFields` (0 não é null). Portanto o JSON de um log sempre traz `total:{original:N, backuped:M}`.
+
+### 3.3 Ciclo de vida do `status` (enum implícito)
+
+`status` é uma `String` livre, mas o código só atribui sete valores. Os transientes (`count items`, `group data`, `backuped saved : N`, `removing original`) são gravados em `backup_log` durante o processamento — o cliente pode observá-los relendo o log diretamente do Mongo (não há endpoint REST; ver Seção 7).
+
+| Valor                  | Quando | Terminal? |
+| ---------------------- | ------ | --------- |
+| `started`              | log criado, antes do processamento | não |
+| `count items`          | contando docs da origem | não |
+| `group data`           | pipeline aggregate montado | não |
+| `backuped saved : N`   | a cada 50 documentos salvos (N = total acumulado) | não |
+| `removing original`    | removendo docs da origem (só se `deleteOriginalDataAfterBackup`) | não |
+| `finished`             | concluído com sucesso (`finish` definido) | **sim** |
+| `error`               | exceção capturada (`finish` + `message` definidos) | **sim** |
+
+```mermaid
+stateDiagram-v2
+    [*] --> started
+    started --> count_items: count items
+    count_items --> group_data: group data
+    group_data --> backuped_saved: backuped saved : N
+    backuped_saved --> backuped_saved: a cada 50 docs
+    backuped_saved --> removing_original: se deleteOriginal
+    backuped_saved --> finished: se não deleteOriginal
+    removing_original --> finished
+    finished --> [*]
+    count_items --> error: exceção
+    group_data --> error: exceção
+    backuped_saved --> error: exceção
+    removing_original --> error: exceção
+    error --> [*]
+```
+
+> **Estado órfão não modelado:** se a config for apagada entre `execute` e `asyncExecute`, o passo [1] encontra `config == null` e a função retorna sem alterar o log. O log permanece em `started` indefinidamente (sem `finish`), bloqueando futuras execuções (ver Seção 7).
+
+### 3.4 Técnicas de jogo (`techniques`)
+
+**Não aplicável.** O módulo `backup` é infraestrutura de dados e não possui códigos GT (game techniques).
+
+---
+
+## 4. Endpoints
+
+Todos sob `@Path("v3/backup")`, definidos em `BackupRest.java`. Produzem `application/json; charset=UTF-8`.
+
+### `POST /v3/backup`
+
+| Aspecto               | Detalhe |
+| --------------------- | ------- |
+| Finalidade            | Criar **ou atualizar** uma configuração de backup. |
+| Handler               | `BackupRest.insert` → `BackupManager.save` |
+| Autenticação          | `Authorization` (Bearer / Basic / Studio) ou `api_key` |
+| Full replace ou patch | **Full replace** — `col.save(obj)` substitui o documento inteiro por `_id`. |
+| Status de sucesso     | `201 CREATED` |
+
+**Comportamento real (importante):**
+
+- **Upsert disfarçado de "insert":** se o body trouxer um `_id` existente, o documento é **totalmente substituído** (não é patch). Campos omitidos no body são **perdidos**.
+- **Validação silenciosa:** `save` só persiste se `collection`, `match` e `aggregate` forem todos não-nulos. Se algum faltar, **nada é salvo, mas a resposta ainda é `201 CREATED`** com o body recebido (sem `_id`/`created`/`updated`). O cliente é levado a crer que salvou.
+- Defaults aplicados no save: `_id`, `created` (só em novos), `updated` (sempre), `backupCollectionName` (= `collection + "_bkp"` se vazio).
+- A resposta usa `toJsonRemoveNullFields` → campos nulos são omitidos.
+
+**Exemplo de request:**
+
+```json
+POST /v3/backup
+{
+  "title": "Arquivar achievements antigos",
+  "collection": "achievement",
+  "match": { "time": { "$lt": { "$date": "2024-01-01T00:00:00Z" } } },
+  "aggregate": [ { "$project": { "player": 1, "type": 1, "time": 1 } } ],
+  "backupCollectionName": "achievement_archive",
+  "incremental": true,
+  "deleteOriginalDataAfterBackup": false
+}
+```
+
+**Resposta (201):**
+
+```json
+{
+  "_id": "Xa3Bc9",
+  "title": "Arquivar achievements antigos",
+  "collection": "achievement",
+  "match": "...",
+  "aggregate": "...",
+  "backupCollectionName": "achievement_archive",
+  "incremental": true,
+  "deleteOriginalDataAfterBackup": false,
+  "created": "2026-05-20T12:00:00Z",
+  "updated": "2026-05-20T12:00:00Z"
+}
+```
+
+---
+
+### `GET /v3/backup/{id}`
+
+| Aspecto      | Detalhe |
+| ------------ | ------- |
+| Finalidade   | Buscar uma configuração de backup por `_id`. |
+| Handler      | `BackupRest.find` → `BackupManager.find` |
+| Autenticação | `Authorization` / `api_key` |
+| Status       | `200 OK` |
+
+**Path params:**
+
+| Param | Tipo   | Descrição |
+| ----- | ------ | --------- |
+| `id`  | String | `_id` da config. |
+
+**Comportamento real:** se o `_id` não existir, `find` retorna `null` e a resposta é `200 OK` com body nulo/vazio (sem 404).
+
+---
+
+### `DELETE /v3/backup/{id}`
+
+| Aspecto      | Detalhe |
+| ------------ | ------- |
+| Finalidade   | Remover a configuração **e todos os seus logs**. |
+| Handler      | `BackupRest.delete` → `BackupManager.delete` |
+| Autenticação | `Authorization` / `api_key` |
+| Status       | `204 NO_CONTENT` |
+
+**Path params:** `id` (String) — `_id` da config.
+
+**Comportamento real (cascade):** além de remover o doc da coleção `backup`, executa `remove("{backup:#}", id)` na coleção `backup_log`, **apagando todo o histórico de execuções** desse backup. É idempotente: deletar um id inexistente também retorna `204`.
+
+---
+
+### `GET /v3/backup/{id}/execute`
+
+| Aspecto      | Detalhe |
+| ------------ | ------- |
+| Finalidade   | **Disparar** uma execução de backup (assíncrona). |
+| Handler      | `BackupRest.execute` → `BackupManager.execute` |
+| Autenticação | `Authorization` / `api_key` |
+| Status       | `200 OK` |
+
+**Path params:** `id` (String) — `_id` da config.
+
+**Comportamento real — esta é uma operação NÃO-RESTful:**
+
+- **`GET` que muta estado:** apesar do verbo `GET`, este endpoint **cria um documento** em `backup_log` e enfileira trabalho. Não é seguro/idempotente no sentido HTTP, e qualquer cache/prefetch de GET pode disparar backups acidentais.
+- Retorna **imediatamente** o `BackupLog` (status `"started"`) — não espera o backup terminar.
+- Se já houver um log em andamento (sem `finish`), retorna esse log **sem disparar nova execução** (proteção contra concorrência).
+- Se o `_id` não existir, `execute` retorna `null` → resposta `200 OK` com body nulo (sem erro).
+
+**Resposta típica (200):**
+
+```json
+{
+  "_id": "Lm7Qz2",
+  "backup": "Xa3Bc9",
+  "status": "started",
+  "start": "2026-05-20T12:05:00Z",
+  "total": { "original": 0, "backuped": 0 }
+}
+```
+
+> Não há endpoint para **listar** backups, nem para **consultar o `backup_log`**. Ver Seção 7 e Seção 9.
+
+---
+
+## 5. Regras de Negócio
+
+Regras presentes no código que **não** estão no schema:
+
+1. **Obrigatoriedade efetiva (não declarada):** `collection`, `match` e `aggregate` são obrigatórios na prática — `save` no-opa silenciosamente sem eles (`BackupManager.save` linha 41). `title` e `backupCollectionName` são opcionais.
+
+2. **`aggregate` é um array de estágios, não um objeto:** em `asyncExecute` ele é desserializado como `List` (`JsonUtil.fromJson(backup.aggregate, List.class)`). O `$match` é montado **separadamente** a partir de `backup.match` e prefixado ao pipeline. O pipeline efetivo é `[{$match: <match>}, ...<aggregate>]`. Repetir o `$match` dentro de `aggregate` é redundante.
+
+3. **`incremental` = "não dropar o destino":** quando `false`, `bkp.drop()` apaga a coleção de destino inteira antes de inserir (full refresh). Quando `true`, o destino é preservado e os documentos são inseridos via `bkp.save(o)`.
+   - **Dedup por `_id`:** em modo incremental, `save` faz upsert pelo `_id` do documento. Se o pipeline `aggregate` **projetar o `_id` para fora** (ou gerar `_id` novo via `$group`), a deduplicação quebra e **cada execução insere duplicatas**.
+
+4. **Remoção da origem é por `match`, não pelos IDs copiados:** quando `deleteOriginalDataAfterBackup=true`, a remoção usa o **mesmo `match`** (`source.remove(match)`), não a lista de documentos efetivamente copiados. Se novos documentos passarem a casar com `match` entre a cópia e a remoção, eles serão **removidos sem terem sido copiados** (janela de inconsistência por não haver transação).
+
+5. **Full-replace apaga `created` em updates:** como o `POST` faz `col.save(obj)` (substituição total) e `created` só é setado no ramo de `_id` novo, **atualizar uma config sem reenviar `created` zera/remove o campo**. Sempre reenvie o documento completo (incluindo `created`) ao atualizar.
+
+6. **Lock lógico de execução única por backup:** a checagem `{finish:{$exists:false}}` garante no máximo **uma execução em andamento por config**. Um log preso sem `finish` bloqueia novas execuções indefinidamente (ver Seção 7).
+
+7. **Isolamento multi-tenant:** cada `apiKey` resolve para uma `ManagerFactory` própria (`FrontController.getInstance(apiKey)`), com seu próprio `BackupManager`, fila e thread (`Funifier-Backup-Async-<apiKey>`). As coleções `backup`/`backup_log` são por banco de tenant.
+
+8. **Consistência eventual / sem transação:** count, aggregate-insert e remove são passos independentes. Não há rollback. Falha parcial deixa estado intermediário (destino parcial + `status=error`).
+
+---
+
+## 6. Comportamentos Automáticos
+
+| Comportamento | Trigger | Impacto | Persistência |
+| ------------- | ------- | ------- | ------------ |
+| Geração de `_id` | `save` com `_id` vazio | Cria `_id` time-based (`Guid.shortTimeMillis`) | coleção `backup` |
+| `created`/`updated` | `save` | `created` só em novos; `updated` sempre | coleção `backup` |
+| Default de destino | `save` com `backupCollectionName` vazio | Define `<collection>_bkp` | coleção `backup` |
+| No-op silencioso | `save` sem `collection`/`match`/`aggregate` | Nada é salvo; resposta ainda 201 | nenhuma |
+| Cascade de logs | `DELETE /{id}` | Remove todos os `backup_log` do backup | coleção `backup_log` |
+| Drop do destino | `asyncExecute` com `incremental=false` | Apaga a coleção de destino inteira | coleção de destino |
+| Remoção da origem | `asyncExecute` com `deleteOriginalDataAfterBackup=true` | `remove(match)` na origem | coleção de origem |
+| Atualização de progresso | `asyncExecute`, a cada 50 docs | Reescreve `backup_log.status` | coleção `backup_log` |
+| Trigger `after_finish` | `asyncExecute` ao concluir **com sucesso** | Dispara cadeia de triggers | conforme triggers |
+
+### Fluxo de behaviors automáticos no `save`
+
+```mermaid
+flowchart TD
+    A["save(obj)"] --> B{"collection, match e aggregate\ntodos != null?"}
+    B -- não --> X["no-op silencioso\n(nada persiste)"]
+    B -- sim --> C{"_id vazio?"}
+    C -- sim --> D["_id = Guid.shortTimeMillis()\ncreated = now"]
+    C -- não --> E["mantém _id\n(created NÃO é redefinido)"]
+    D --> F["updated = now"]
+    E --> F
+    F --> G{"backupCollectionName vazio?"}
+    G -- sim --> H["backupCollectionName = collection + '_bkp'"]
+    G -- não --> I["mantém"]
+    H --> J["col.save(obj) — full replace"]
+    I --> J
+```
+
+### Trigger `after_finish`
+
+Ao concluir com sucesso, `asyncExecute` monta um `TriggerContext` (com `manager` e `extra.backup = <config>`) e chama:
+
+```java
+manager.getTriggerManager().execute(
+    log.backup,                   // id
+    log,                          // objeto (BackupLog)
+    Entity.BACKUP_LOG.collection, // "backup_log"
+    "after_finish",               // evento
+    null,                         // player
+    context);
+```
+
+> **Só dispara em sucesso.** No caminho de erro o trigger é pulado. Não existe trigger `before`/`antes` apesar do comentário no topo de `BackupManager.java` ("executar trigger em eventos antes e após").
+
+---
+
+## 7. Suportado vs NÃO Suportado
+
+### ✅ Suportado
+
+- Criar/atualizar config de backup (`POST /v3/backup`, upsert/full-replace).
+- Buscar config por id (`GET /v3/backup/{id}`).
+- Deletar config + cascata de logs (`DELETE /v3/backup/{id}`).
+- Disparar execução assíncrona (`GET /v3/backup/{id}/execute`).
+- Filtro por `match` + transformação por pipeline `aggregate`.
+- Modo full-refresh (`incremental=false`, dropa destino) e modo append/upsert (`incremental=true`).
+- Remoção opcional dos originais (`deleteOriginalDataAfterBackup`).
+- Lock lógico de uma execução em andamento por config.
+- Trigger `after_finish` em sucesso.
+- Isolamento multi-tenant por `apiKey`.
+
+### ❌ NÃO Suportado
+
+- **Agendamento automático / cron** — campos `active` e `cron` estão **comentados** em `Backup.java` (linhas 28–29). Não há scheduler que execute backups automaticamente. Execução é sempre manual via `/execute`.
+- **Listagem de backups** — não existe `GET /v3/backup` (a doc anterior afirmava existir; é falso). Só busca por id.
+- **Consulta de log via REST** — `BackupManager.findLog(id)` existe mas **nenhum endpoint o expõe**. Módulos irmãos (`StaticRest`, `FolderRest`, `CsvRest`) expõem `findLog`; `BackupRest` não. A única forma de inspecionar um log é consultar a coleção `backup_log` diretamente no Mongo.
+- **Campo `extra` do log** — declarado em `BackupLog` mas **nunca escrito** pelo código. Campo morto.
+- **Trigger `before`/antes do backup** — declarado no comentário de `BackupManager`, mas **não implementado**. Apenas `after_finish` (sucesso) dispara.
+- **Trigger em caso de erro** — não há evento de trigger no caminho de falha.
+- **Recuperação de execuções perdidas** — a fila é **em memória, por tenant**. Reinício do servidor descarta os logs enfileirados e ainda **não finalizados**. Pior: um log que ficou sem `finish` (por reinício, ou por config deletada antes do `asyncExecute`) **bloqueia permanentemente** novas execuções daquele backup (a checagem `{finish:{$exists:false}}` continua encontrando-o e retornando-o sem re-enfileirar). Recuperação exige intervenção manual no Mongo.
+- **Transação / atomicidade** — não há. Falha parcial não faz rollback.
+- **Validação com feedback de erro** — body inválido no `POST` retorna 200/201 "sucesso" sem persistir.
+- **404 para recursos inexistentes** — `GET`/`execute` em id inexistente retornam 200 com body nulo.
+
+---
+
+## 8. Segurança e Permissões
+
+- **Autenticação:** todas as rotas recebem `@BeanParam AuthBean`, que extrai o `apiKey` do header `Authorization` (`Bearer`, `Basic` ou `Studio`) ou de `api_key`/`X-Api-Key`. A autenticação global é aplicada pelo `SecurityFilter` (`com.funifier.rest.v3.filter.SecurityFilter`).
+- **Isolamento por tenant:** o `apiKey` extraído roteia para `FrontController.getInstance(apiKey)` → `ManagerFactory` do tenant. Operações só enxergam as coleções daquele banco.
+- **Ausência de autorização fina:** `BackupRest` **não declara** checagens de role/permissão por método. A proteção é o nível de autenticação resolvido pelo `SecurityFilter`. Como o módulo é destrutivo (drop/remove), deve ser tratado como operação **administrativa** (token Basic/Studio com privilégio de admin), mas o código não força isso na própria classe REST.
+
+**Superfícies de injeção / risco confirmadas no código:**
+
+1. **Execução de query/aggregate arbitrários:** `match` e `aggregate` são armazenados como **strings cruas** e executados diretamente contra o Mongo (`source.count(match)`, `source.aggregate(...)`, `source.remove(match)`). Quem cria uma config de backup pode rodar **qualquer filtro e qualquer pipeline** sobre **qualquer coleção** do tenant, incluindo coleções de sistema. É efetivamente uma superfície de execução de query arbitrária no banco do tenant.
+2. **Remoção arbitrária de dados:** com `deleteOriginalDataAfterBackup=true`, `source.remove(match)` apaga **qualquer conjunto de documentos** descrito por `match` em **qualquer coleção** (`collection`). Um `match` amplo (ex.: `{}`) remove a coleção inteira de origem.
+3. **Drop de coleção arbitrária:** com `incremental=false`, `bkp.drop()` apaga a coleção apontada por `backupCollectionName`. Se isso apontar para uma coleção viva (ex.: `player`, `achievement`), ela é **destruída**.
+4. **GET mutante:** `GET /{id}/execute` dispara trabalho destrutivo via um verbo idempotente — vulnerável a prefetch/cache/CSRF-via-GET se exposto a tokens com menos privilégio.
+
+> Recomendação operacional (não imposta pelo código): restringir criação/execução de backups a credenciais administrativas e revisar `collection`/`backupCollectionName`/`match` antes de cada execução.
+
+---
+
+## 9. Observabilidade e Troubleshooting
+
+### Diagnóstico rápido
+
+O módulo **não expõe logs via REST**. Toda investigação é feita direto no Mongo nas coleções `backup` e `backup_log`.
+
+```
+# Configuração de backup
+GET /v3/backup/<id>
+
+# Disparar execução (retorna o log inicial)
+GET /v3/backup/<id>/execute
+```
+
+### Queries úteis (Mongo direto)
+
+```javascript
+// Último log de um backup
+db.backup_log.find({ backup: "<id>" }).sort({ start: -1 }).limit(1)
+
+// Logs "presos" (em andamento) que bloqueiam novas execuções
+db.backup_log.find({ finish: { $exists: false } })
+
+// Logs com erro e a mensagem
+db.backup_log.find({ status: "error" }, { backup: 1, message: 1, start: 1 })
+
+// Verificar contagens da última execução
+db.backup_log.find({ backup: "<id>" }, { status: 1, total: 1, start: 1, finish: 1 }).sort({ start: -1 })
+```
+
+### Erros comuns e causas
+
+| Sintoma | Causa provável |
+| ------- | -------------- |
+| `POST` retorna 201 mas a config não aparece | Faltou `collection`, `match` ou `aggregate` → `save` no-opou silenciosamente. |
+| `/execute` retorna sempre o mesmo log e nada processa | Existe log sem `finish` (preso). Reinício de servidor ou config deletada antes do async. Limpe/finalize o log no Mongo. |
+| Coleção de destino sumiu | `incremental=false` → `bkp.drop()`. Esperado. |
+| Dados originais sumiram | `deleteOriginalDataAfterBackup=true` com `match` amplo. |
+| Destino acumula duplicatas a cada run | `incremental=true` + pipeline que remove/recria `_id`. Dedup por `_id` quebrou. |
+| `created` virou null após editar config | `POST` é full-replace e não reenviou `created`. |
+| Backup "não termina" | Trabalho roda em thread assíncrona; releia `backup_log`. Se `status` não avança e não há `finish`, ver log preso. |
+
+### Sinais no log do servidor (stdout)
+
+- `COMECOU EXECUCAO DA THREAD BACKUP ASYNC` — impresso quando a thread assíncrona inicia (log de debug legado em `BackupAsyncProcessor.run`).
+- Stacktrace via `e.printStackTrace()` — toda exceção de `asyncExecute` é impressa no stdout (não em logger estruturado). É onde aparece a causa real de um `status="error"`.
+
+### Notas de performance
+
+- `status` é reescrito em `backup_log` **a cada 50 documentos** copiados → write amplification proporcional ao volume. Em backups muito grandes isso gera muitos writes em `backup_log`.
+- O aggregate usa `allowDiskUse(true)` — pipelines pesados podem usar disco no Mongo.
+- Detalhe de implementação: no estágio de `aggregate`, o `match` passa por dupla serialização (`FunifierMarshaller.toString(FunifierMarshaller.toString(match))`, `BackupManager.java` linha 141) enquanto o `count` usa serialização simples (linha 134). É funcionalmente idempotente para BSON bem-formado, mas é um code smell.
+
+---
+
+## 10. Exemplos Práticos
+
+### 10.1 Exemplo mínimo funcional (full refresh, sem deletar origem)
+
+```json
+POST /v3/backup
+{
+  "collection": "action_log",
+  "match": { "time": { "$lt": { "$date": "2025-01-01T00:00:00Z" } } },
+  "aggregate": []
+}
+```
+
+- `aggregate: []` → pipeline efetivo é só `[{$match: ...}]` (cópia sem transformação).
+- `backupCollectionName` ausente → destino vira `action_log_bkp`.
+- `incremental` ausente (`false`) → `action_log_bkp` é dropada e recriada a cada execução.
+- Disparar: `GET /v3/backup/<id>/execute`.
+
+### 10.2 Exemplo avançado (incremental, transformando, e removendo origem)
+
+```json
+POST /v3/backup
+{
+  "title": "Arquivar achievements de 2024 com projeção enxuta",
+  "collection": "achievement",
+  "match": { "time": { "$gte": { "$date": "2024-01-01T00:00:00Z" },
+                        "$lt":  { "$date": "2025-01-01T00:00:00Z" } } },
+  "aggregate": [
+    { "$project": { "_id": 1, "player": 1, "type": 1, "total": 1, "time": 1 } }
+  ],
+  "backupCollectionName": "achievement_2024_archive",
+  "incremental": true,
+  "deleteOriginalDataAfterBackup": true
+}
+```
+
+- `_id` mantido no `$project` → dedup por upsert funciona em re-execuções (modo incremental).
+- Após copiar, remove da `achievement` os docs que casam com `match`.
+- **Atenção:** a remoção usa `match`, não os IDs copiados — qualquer doc que passe a casar entre cópia e remoção será removido sem cópia.
+
+### 10.3 Anti-pattern — o que NÃO fazer
+
+```json
+POST /v3/backup
+{
+  "collection": "achievement",
+  "match": {},
+  "aggregate": [ { "$group": { "_id": "$player", "n": { "$sum": 1 } } } ],
+  "backupCollectionName": "player",
+  "incremental": false,
+  "deleteOriginalDataAfterBackup": true
+}
+```
+
+Por que é destrutivo:
+
+1. `incremental=false` + `backupCollectionName: "player"` → `bkp.drop()` **apaga a coleção `player` inteira**.
+2. `$group` redefine `_id` → mesmo em modo incremental haveria perda de identidade; aqui o destino já foi dropado.
+3. `match: {}` + `deleteOriginalDataAfterBackup=true` → **remove TODOS os achievements** da origem.
+4. Resultado: `player` destruída e `achievement` esvaziada, sem rollback.
+
+**Regra:** nunca aponte `backupCollectionName` para uma coleção viva; nunca combine `match` amplo com `deleteOriginalDataAfterBackup`; valide o pipeline antes de executar.
+
+---
+
+## Checklist de Configuração
+
+- [ ] `collection`, `match` e `aggregate` preenchidos (sem os três, o `POST` não persiste mas retorna "201").
+- [ ] `aggregate` é um **array** de estágios (não objeto); o `$match` é montado automaticamente — não duplique.
+- [ ] `backupCollectionName` aponta para uma coleção **dedicada de destino**, nunca para uma coleção viva (com `incremental=false` ela será **dropada**).
+- [ ] Decidiu conscientemente entre `incremental=false` (full refresh, dropa destino) e `incremental=true` (append/upsert por `_id`).
+- [ ] Se `incremental=true`, o pipeline **preserva `_id`** (senão duplica a cada run).
+- [ ] `deleteOriginalDataAfterBackup` só `true` após confirmar que `match` é restrito (lembre: remove por `match`, não pelos IDs copiados).
+- [ ] Ao **atualizar** uma config, reenvie o documento **completo** (incl. `created`) — `POST` é full-replace.
+- [ ] Disparo é manual via `GET /{id}/execute`; não espere agendamento automático (não existe).
+- [ ] Para acompanhar o resultado, consulte `backup_log` **direto no Mongo** (não há endpoint de log).
+- [ ] Armadilha de log preso: se `/execute` parar de processar, verifique `backup_log` com `finish` ausente e finalize/remova manualmente.
+- [ ] Operação tratada como **administrativa** (credencial com privilégio) — o código não impõe role, mas as operações são destrutivas.