funifier-mcp 0.2.26 → 0.2.27

package/datasource-funifier-docs/knowledge/modules/custom-object.md

@@ -1,53 +1,718 @@
-# Custom Object (Objeto Customizado)
+# `custom-object` — Database (Objeto Customizado)
 
-## O que é
+**Acesso Studio:** sem rota fixa — exposto através de páginas customizadas (`studio_page`) cujo `slug` é configurável (ex.: `studio/custom/car/list`). As páginas rodam HTML/AngularJS no Studio e consomem `/v3/database/<collection>` via HTTP.
+**API Endpoint:** `/v3/database` (gamification) e `/v3/system/database` (banco de sistema)
+**Coleção MongoDB:** qualquer nome — schemaless
 
-Criação de objetos personalizados para necessidades específicas. Permite criar e gerenciar coleções personalizadas no banco de dados (sufixo `__c`), que podem ser acessadas via API, triggers, schedulers e páginas personalizadas. Ideal para quando os módulos padrão não atendem a todos os requisitos do projeto.
+> **Nota de engenharia (verificada no código):** "Custom Object" **não é** um módulo com entidade própria. Não existe classe `CustomObject*` no `funifier-service` (`find -iname '*CustomObject*'` retorna vazio). É o `com.funifier.rest.v3.rest.DatabaseRest` — um CRUD genérico e schemaless sobre o MongoDB do tenant. O sufixo `__c` é apenas convenção; o servidor **não** o valida nas operações CRUD. A única validação de `__c` está no parâmetro `out` do `aggregate` (`DatabaseRest.java:548`).
+>
+> Toda a documentação abaixo foi extraída por engenharia reversa do código no commit `830037e`. Onde o comportamento diverge do REST convencional ou de uma documentação anterior, isso está marcado explicitamente.
 
-## Quando usar
+**Classes-fonte:**
+- `com.funifier.rest.v3.rest.DatabaseRest` — CRUD do tenant (`DatabaseRest.java`)
+- `com.funifier.rest.v3.rest.system.DatabaseRest` — operações no banco de sistema
+- `com.funifier.engine.database.DatabaseManager` — bulk insert e fila assíncrona
+- `com.funifier.engine.database.DatabaseAsyncProcessor` / `DatabaseAsyncTask` — fila de bulk
+- Dependências: `TriggerManager`, `AuditManager`, `CryptManager`/`AesCrypt`, `PaginationUtil`, `JsonUtil`, `Callback`, `Guid`, `AuthBean`
 
-- Para cadastrar entidades específicas do negócio (produtos, imóveis, etc.)
-- Para criar listas customizadas (pontos turísticos, categorias, etc.)
-- Para armazenar dados que não se encaixam nos módulos padrão
+---
 
-## API Endpoints
+## 1. Visão Geral
 
-Objetos customizados são acessados via o módulo Database:
+O módulo `custom-object` expõe um **CRUD genérico schemaless** sobre o MongoDB da gamification. Permite criar, ler, atualizar, deletar, contar e agregar documentos em **qualquer coleção** — incluindo as coleções internas do framework (`player`, `action_log`, `challenge`, `trigger`, etc.).
 
-### Listar Objetos
-**Método:** GET
-**Endpoint:** `/v3/database/<nome>__c`
+**Papel arquitetural:**
+- Armazenamento de dados de negócio que não se encaixam nos módulos padrão (produtos, veículos, categorias, imóveis…), por convenção em coleções `*__c`.
+- Backend de páginas customizadas do Studio (`studio_page`): a página renderiza HTML/AngularJS e usa `/v3/database/<collection>` para listar/criar/editar/excluir (ex.: o exemplo "Car List/Car Form" usa `car__c`).
+- Coleções de cache/configuração do próprio framework também moram aqui: `csv_config__c`, `csv_log__c`, `csv_format__c` (CsvManager), `find_cache_<id>__c` (FindRest/PreparedManager), `email_code_verifier_log__c` (CRM Email/Calendar/Doc).
+- Destino materializado de agregações (parâmetro `out`).
 
-### Criar Objeto
-**Método:** POST
-**Endpoint:** `/v3/database/<nome>__c`
+**Relação com outros módulos (verificada por chamadas reais):**
+- `TriggerManager.execute(...)` é chamado em **todos** os eventos CRUD → dispara scripts Groovy configurados na coleção `trigger` para a combinação `(entity=collection, event)`.
+- `AuditManager.log(...)` é chamado em POST/PUT/DELETE (mas o registro é **condicional** — ver §6).
+- `CryptManager`/`AesCrypt` encriptam/decriptam campos configurados por coleção (AES-256 ECB).
+- O `aggregate` com `out` é o mecanismo que materializa relatórios em coleções `__c`.
 
-**Exemplo (coleção car__c):**
+---
+
+## 2. Arquitetura e Fluxos
+
+### 2.1 Pipeline de escrita — POST (`insert`) e PUT (`update`)
+
+Sequência real (`DatabaseRest.java:169-247` para POST; `:290-388` para PUT):
+
+1. **[Guard]** `authBean.getScope().indexOf("database") != -1` **e** `collection.length() > 3`. Se falhar → retorna `null` com **HTTP 201** (corpo vazio, sem erro).
+2. **[Auto-`_id`]** Se `_id` ausente ou `null` → `object.put("_id", Guid.newShortGuid())`.
+3. **[Trigger]** `triggerManager.execute(null, object, collection, before_create|before_update, player, null)`. O objeto é passado **por referência**; o script Groovy pode mutá-lo (a mutação persiste). Exceções no script são **engolidas** (não abortam — ver §6).
+4. **[Encriptação — opcional]** Somente se `authBean.checkReadEncryptedValues()` for verdadeiro **e** existir config em `crypt_object_field` para a coleção **e** existir secret ativa:
+   - `JsonUtil.toBsonStrictMode(object)` → `fromJson` (normaliza marcações BSON)
+   - `AesCrypt.encryptFields(object, field.fields, secret.secret)`
+   - Se **qualquer** dessas condições falhar, o dado segue **em plaintext** (ver §5.7).
+5. **[Marshalling]** `new JacksonMapper().getMarshaller().marshall(object)` → `BasicDBObject.parse(json)` (suporte a tipos BSON).
+6. **[Player password — só PUT, só coleção `player`]** Se `collection == "player"` e `!checkReadPlayerPassword()`: relê o player atual e, se o objeto enviado **não tem** `password` (ausente ou `null`), reinsere a senha existente (`DatabaseRest.java:358-363`).
+7. **[Persistência]** POST → `collection.insert(o)`; PUT → `collection.save(o)` (**upsert/replace** — não é patch).
+8. **[Trigger]** `execute(..., after_create|after_update, ...)`.
+9. **[Auditoria — condicional]** `auditManager.log(collection, create|update, authBean, o)` (ver §6 para as condições reais).
+10. **[Decriptação de retorno]** Se houve encriptação no passo 4, decripta os campos **apenas para a resposta**.
+11. **[Resposta]** HTTP **201**. `strict=true` → BSON extended JSON; caso contrário `JsonUtil.toJsonRemoveNullFields` (**remove campos `null` do retorno**).
+
+#### Fluxograma — escrita (POST/PUT)
+
+```mermaid
+flowchart TD
+    A["POST/PUT /v3/database/{collection}"] --> B{"scope 'database'<br/>e collection.len > 3?"}
+    B -- Não --> Z["retorna null + HTTP 201<br/>(falha silenciosa)"]
+    B -- Sim --> C{"_id ausente/null?"}
+    C -- Sim --> D["_id = Guid.newShortGuid()"]
+    C -- Não --> E
+    D --> E["trigger before_create / before_update<br/>(mutável; exceção NÃO aborta)"]
+    E --> F{"checkReadEncryptedValues()<br/>+ config crypt + secret ativa?"}
+    F -- Sim --> G["AesCrypt.encryptFields()"]
+    F -- Não --> H["plaintext (sem aviso)"]
+    G --> I["marshall → BasicDBObject.parse"]
+    H --> I
+    I --> J{"PUT + collection=player<br/>+ sem scope password?"}
+    J -- Sim --> K["preserva password atual"]
+    J -- Não --> L
+    K --> L{"POST?"}
+    L -- POST --> M["collection.insert(o)"]
+    L -- PUT --> N["collection.save(o) (upsert/replace)"]
+    M --> O["trigger after_create / after_update"]
+    N --> O
+    O --> P["auditManager.log() (condicional)"]
+    P --> Q{"encriptou?"}
+    Q -- Sim --> R["decryptFields para o retorno"]
+    Q -- Não --> S
+    R --> S["HTTP 201 + objeto"]
+```
+
+### 2.2 Pipeline — leitura por ID (`find`, `DatabaseRest.java:59-118`)
+
+```
+[GET /v3/database/{collection}/{id}]
+  → se id == "me": id = authBean.getPlayerFromTokenIfExist()
+  → guard: scope 'database' + collection.len > 3 + id.len > 0   (senão → null/200)
+  → c.findOne("{_id:#}", id).as(HashMap)
+  → se checkReadEncryptedValues() e result != null e há config+secret:
+        (se strict) toBsonStrictMode → fromJson
+        AesCrypt.decryptFields(result, fields, secret)
+  → strict=true  → toBsonStrictMode(result)
+    strict=false → toJsonRemoveNullFields(result)   ← remove campos null
+  → HTTP 200
+```
+
+### 2.3 Pipeline — listagem paginada (`findAll`, `DatabaseRest.java:120-160`)
+
+```
+[GET /v3/database/{collection}?q=...&max_results=N]
+  → guard: scope 'database' + collection.len > 0   (senão → null/200)
+  → maxResultsParsed = parseInt(max_results) | fallback 100 (silencioso)
+  → pipeline inicial: { $match : { <q> } }   (q injetado cru)
+  → PaginationUtil.getPageResult(a, Range, 0, maxResultsParsed)
+        getRange(): SE header Range presente → skip/limit vêm do header (max_results IGNORADO)
+                    SENÃO                     → skip=0, limit=maxResultsParsed
+        $facet: { result: [{$skip},{$limit}], pagination: [{$group:{_id:null,count:{$sum:1}}}] }
+  → resposta: array (campos null removidos) + header Content-Range "items skip-limit/count"
+```
+
+> **Nota sobre `max_results` vs `Range`:** quando o header `Range` está presente, ele **sobrepõe** `max_results` (`PaginationUtil.getRange` lê `skip-limit` do header). `max_results` só é usado como limite quando **não** há header `Range`.
+>
+> **Divergência do padrão HTTP (importante):** `PaginationUtil.getRange` interpreta `items=0-100` como `skip=0, limit=100`, ou seja `items=<skip>-<limit>` — **não** o padrão HTTP `items=<início>-<fim>`. Para "10 documentos a partir do offset 5", um cliente HTTP padrão escreveria `items=5-14`; aqui o correto é `items=5-10` (skip 5, limit 10). O segundo número é a **quantidade**, não o índice final.
+
+### 2.4 Pipeline — delete (`delete`, `DatabaseRest.java:453-484`)
+
+```
+[DELETE /v3/database/{collection}?q=...]
+  → guard: scope 'database' + collection.len > 0 + q.len >= 3   (senão → null/200)
+  → total = count("{" + q + "}")
+  → SE total <= 20.000:
+        ids = distinct("_id").query("{" + q + "}")
+  → SE ids.size() > 0:
+        trigger before_delete (recebe lista de ids)
+        remove("{" + q + "}")
+        trigger after_delete (recebe lista de ids)
+        auditManager.log(DELETE, ids)   (condicional)
+  → SE total > 20.000: ids fica vazio → NADA é deletado → HTTP 200 (silencioso)
+```
+
+> **Armadilha crítica (confirmada no código):** se `q` casa com **mais de 20.000** documentos, o delete **não executa** e retorna **200 OK** sem erro. O comentário no código diz "menor que 1000" (`DatabaseRest.java:466`), mas a constante real é `20_000` (`:469`) — o comentário está **desatualizado**.
+
+#### Fluxograma — delete
+
+```mermaid
+flowchart LR
+    A["DELETE ?q=..."] --> B{"scope + collection.len>0<br/>+ q.len>=3?"}
+    B -- Não --> Z["null + HTTP 200"]
+    B -- Sim --> C["total = count(q)"]
+    C --> D{"total <= 20.000?"}
+    D -- Não --> Y["ids vazio → NÃO deleta<br/>HTTP 200 (silencioso)"]
+    D -- Sim --> E["ids = distinct(_id)"]
+    E --> F{"ids.size > 0?"}
+    F -- Não --> Z
+    F -- Sim --> G["before_delete(ids)"]
+    G --> H["remove(q)"]
+    H --> I["after_delete(ids)"]
+    I --> J["audit(delete, ids) (condicional)"]
+    J --> K["HTTP 200"]
+```
+
+### 2.5 Pipeline — bulk insert (`insertBulk` → `DatabaseManager.bulkInsert`)
+
+`DatabaseRest.java:252-285` decide entre síncrono e assíncrono; o processamento real está em `DatabaseManager.bulkInsert` (`DatabaseManager.java:29-78`).
+
+```
+[POST /v3/database/{collection}/bulk?async=...]
+  → guard: scope 'database' + collection.len > 3 + list.size() > 0   (senão → {}/201)
+  → readPlayerPassword = (collection == "player" && !checkReadPlayerPassword())
+  → async == "true":
+        cria DatabaseAsyncTask {task:"bulk", collection, list, readPlayerPassword}
+        DatabaseManager.addAsyncTask(task) → fila.offer(task)
+        retorna {"total": N} IMEDIATAMENTE (sem garantir processamento)
+  → async != "true" (padrão):
+        DatabaseManager.bulkInsert(collection, list, readPlayerPassword)  [síncrono]
+```
+
+`DatabaseManager.bulkInsert` (idêntico para sync e async — o worker chama o mesmo método):
+```
+  → trigger before_bulk (recebe a lista inteira)
+  → para cada objeto:
+        marshall → BasicDBObject.parse
+        se _id ausente/null → Guid.newShortGuid()
+        se readPlayerPassword → relê player atual e preserva password
+        trigger before_create (por item)
+        collection.save(object)        ← SAVE (upsert/replace), não insert
+        trigger after_create (por item)
+  → trigger after_bulk (recebe a lista inteira)
+```
+
+> **Diferenças do POST simples (verificadas):** o bulk usa `save()` (upsert), **não** registra auditoria, e **não** aplica encriptação de campos — mesmo que a coleção tenha config em `crypt_object_field`. A preservação de password **é** aplicada quando `readPlayerPassword=true`.
+
+#### Sequência — bulk insert (síncrono)
+
+```mermaid
+sequenceDiagram
+    participant C as Cliente HTTP
+    participant R as DatabaseRest
+    participant DM as DatabaseManager
+    participant T as TriggerManager
+    participant M as MongoDB (Jongo)
+
+    C->>R: POST /{collection}/bulk
+    R->>R: guard scope + collection.len>3 + list>0
+    R->>DM: bulkInsert(collection, list, readPlayerPassword)
+    DM->>T: execute(before_bulk, list)
+    loop para cada objeto da lista
+        DM->>DM: marshall + auto _id + preserva password?
+        DM->>T: execute(before_create, item)
+        DM->>M: collection.save(item)  (upsert)
+        DM->>T: execute(after_create, item)
+    end
+    DM->>T: execute(after_bulk, list)
+    R-->>C: HTTP 201 {"total": N}
+    Note over DM,M: SEM auditoria, SEM encriptação
+```
+
+### 2.6 Pipeline — aggregate com materialização (`aggregate`, `DatabaseRest.java:490-587`)
+
+```mermaid
+flowchart LR
+    A["POST /{collection}/aggregate"] --> B{"scope + collection.len > 2?"}
+    B -- Não --> Z["null + HTTP 200"]
+    B -- Sim --> C{"q presente?"}
+    C -- Sim --> D["estágio inicial { $match : { q } }"]
+    C -- Não --> E["estágios = corpo da requisição"]
+    D --> F["allowDiskUse(true)"]
+    E --> F
+    F --> G{"collection=player<br/>e sem scope password?"}
+    G -- Sim --> H["adiciona {$project:{password:0}}"]
+    G -- Não --> I
+    H --> I{"out termina com '__c'?"}
+    I -- Sim --> J["getRange(Range) → $skip/$limit"]
+    J --> K{"out_operation == 'replace'?"}
+    K -- Sim --> L["collection(out).drop()"]
+    K -- Não --> M["mantém docs existentes"]
+    L --> N["para cada doc: out.save(doc)"]
+    M --> N
+    N --> O["retorna {total, out} + HTTP 200"]
+    I -- Não --> P["getPageResultThrowsException ($facet)<br/>retorno paginado + Content-Range"]
+```
+
+> Síncrono em todos os caminhos. `allowDiskUse(true)` está habilitado em todas as agregações. Se `out` está presente mas **não** termina com `__c`, é **ignorado** e o resultado é retornado paginado normalmente.
+
+---
+
+## 3. Estrutura dos Objetos
+
+### 3.1 Documento customizado — sem schema fixo
+
+Não existe classe Java mapeada para o documento. O corpo é desserializado como `HashMap<String,Object>` e persistido como `BasicDBObject` após `JacksonMapper.marshall`.
+
+| Campo | Tipo | Padrão | Obrigatório | Descrição |
+|---|---|---|---|---|
+| `_id` | String | `Guid.newShortGuid()` | — | Gerado automaticamente se ausente/`null` em POST, PUT e em cada item do bulk |
+| `*` | qualquer | — | — | Todos os demais campos são schemaless e preservados integralmente |
+
+**Comportamento do `_id`:**
+- POST sem `_id`: gera automaticamente.
+- PUT sem `_id`: gera automaticamente → **cria um documento novo** (não atualiza nada).
+- PUT com `_id` existente: `save()` substitui o **documento inteiro** (não é patch — campos ausentes são removidos).
+
+**Campos não-persistidos / computados:**
+- Valores **decriptados** aparecem **apenas na resposta** de GET/POST/PUT; no MongoDB permanecem encriptados.
+
+**Sanitização silenciosa de retorno:**
+- Em modo **não-strict**, toda resposta passa por `JsonUtil.toJsonRemoveNullFields` (Jackson `Include.NON_NULL`) → **campos com valor `null` somem da resposta**. Use `strict=true` para inspecionar tipos BSON e manter a estrutura.
+
+### 3.2 `CryptObjectField` — configuração de criptografia (coleção `crypt_object_field`, banco da gamification)
+
+`com.funifier.engine.crypt.CryptObjectField`:
+
+| Campo | Tipo | Descrição |
+|---|---|---|
+| `_id` | String | **Nome da coleção** a proteger. No Java o atributo chama-se `entity` mas é mapeado para `_id` via `@JsonProperty("_id")` |
+| `fields` | List\<String\> | Lista de **JSONPaths** (sem o prefixo `$.`) a encriptar — ex.: `cpf`, `extra.documento` |
+
+`CryptManager.findObjectField(collection)` busca por `{_id: collection}` (`CryptManager.java:395-398`).
+
+### 3.3 `CryptTenantSecret` — segredo AES (coleção `crypt_tenant_secret`, **banco de SISTEMA**)
+
+| Campo | Tipo | Descrição |
+|---|---|---|
+| `_id` | String | Id do segredo |
+| `status` | String | `active` / `arquived` (`STATUS_ACTIVE` / `STATUS_ARCHIVED`) |
+| `gamification` | String | apiKey do tenant |
+| `secret` | String | Chave AES usada por `AesCrypt` |
+| `created` / `updated` | Date | — |
+
+`CryptManager.findTenantSecretActive()` busca por `{gamification:#, status:'active'}` em `SystemFactory.getInstance()` — ou seja, **o segredo vive no banco de sistema, não no banco do tenant**.
+
+#### Relação entre as coleções de criptografia
+
+```mermaid
+erDiagram
+    CRYPT_OBJECT_FIELD ||--o| TARGET_COLLECTION : "protege (_id = nome da coleção)"
+    CRYPT_TENANT_SECRET ||--o{ CRYPT_OBJECT_FIELD : "fornece chave AES por gamification"
+    CRYPT_OBJECT_FIELD {
+        string _id "nome da coleção (entity)"
+        string[] fields "JSONPaths a encriptar"
+    }
+    CRYPT_TENANT_SECRET {
+        string _id
+        string status "active|arquived"
+        string gamification "apiKey"
+        string secret "chave AES"
+    }
+    TARGET_COLLECTION {
+        string _id
+        object campos_encriptados
+    }
+```
+
+> Banco da gamification: `crypt_object_field`. Banco de sistema: `crypt_tenant_secret`. (`CryptManager` usa `manager.getJongoConnection()` para o primeiro e `SystemFactory.getInstance().getJongoConnection()` para o segundo.)
+
+### 3.4 `DatabaseAsyncTask` — item da fila de bulk assíncrono
+
+| Campo | Tipo | Descrição |
+|---|---|---|
+| `task` | String | Sempre `"bulk"` (`TASK_BULK_INSERT`) |
+| `collection` | String | Coleção destino |
+| `list` | List\<Object\> | Objetos a inserir |
+| `readPlayerPassword` | boolean | Aciona preservação de password do player |
+
+A fila é uma `LinkedBlockingQueue` **por tenant** (`DatabaseAsyncProcessor`), consumida por uma thread `Funifier-Database-Async-<apiKey>` que faz `poll()` em laço (sleep de 100ms quando vazia). Não há persistência da fila — itens pendentes se perdem em restart.
+
+---
+
+## 4. Endpoints
+
+> Convenção de "falha silenciosa": quando o guard de scope/parâmetro falha, a maioria dos métodos chama `Callback.callback(null, status)` → corpo é o literal JSON `null` com o status indicado (200 nos GET/DELETE, 201 nos POST/PUT), **sem mensagem de erro**. Da mesma forma, `GET /{collection}/{id}` para um id inexistente retorna **HTTP 200 com corpo `null`** (não 404).
+
+### `GET /v3/database/{collection}/{id}` — buscar por id
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Busca um documento pelo `_id` |
+| Scope | `database` |
+| Restrições | `collection.length() > 3`, `id.length() > 0` |
+| Falha de guard | `null` + HTTP 200 |
+
+**Query params:** `strict` (`"true"` → BSON extended JSON).
+**Comportamentos especiais:** `id=me` resolve para o player do token; decripta campos se `checkReadEncryptedValues()`; em modo não-strict remove campos `null`.
+
+### `GET /v3/database/{collection}` — listar/filtrar
+
+| Aspecto | Detalhe |
+|---|---|
+| Scope | `database` |
+| Restrição | `collection.length() > 0` |
+
+**Query params:** `q` (filtro MongoDB inline, sem chaves externas), `strict`, `max_results` (default 100, fallback silencioso). **Header:** `Range: items=skip-limit`.
+**Comportamento real:** `{ $match: {<q>} }` + `$facet` (paginação + contagem em uma query). Header de resposta `Content-Range: items skip-limit/total`. `Range` sobrepõe `max_results`.
+
+### `POST /v3/database/{collection}` — criar
+
+| Aspecto | Detalhe |
+|---|---|
+| Scope | `database` · Restrição `collection.length() > 3` · Status **201** · Operação `insert()` |
+
+`strict` aceita/retorna BSON. Dispara `before_create`/`after_create`, encripta (se habilitado), audita (condicional). Ver §2.1.
+
+### `PUT /v3/database/{collection}` — substituir (upsert)
+
+| Aspecto | Detalhe |
+|---|---|
+| Scope | `database` · Restrição `collection.length() > 3` · Status **201** · Operação `save()` (full replace) |
+
+> **Armadilha:** PUT é **replace completo**, não patch. Campos ausentes no body **somem** do documento. Sem `_id`, cria documento novo. Proteção de password aplicada para `collection=player` sem scope de password.
+
+### `POST /v3/database/{collection}/bulk` — inserção em lote
+
+| Aspecto | Detalhe |
+|---|---|
+| Scope | `database` · Restrição `collection.length() > 3` e `list.size() > 0` · Status **201** |
+
+**Query param:** `async` (`"true"` → enfileira e retorna `{"total":N}` imediatamente). Usa `save()` por item. **Sem auditoria, sem encriptação.** Dispara `before_bulk`/(`before_create`+`after_create` por item)/`after_bulk`. Ver §2.5.
+
+### `DELETE /v3/database/{collection}` — remover por filtro
+
+| Aspecto | Detalhe |
+|---|---|
+| Scope | `database` · Restrições `collection.length() > 0` e `q.length() >= 3` · Status **200** |
+
+**Limite 20.000:** se o filtro casa mais de 20.000 docs, **não deleta** e retorna 200. Ver §2.4.
+
+### `POST /v3/database/{collection}/aggregate` — agregação (com materialização opcional)
+
+| Aspecto | Detalhe |
+|---|---|
+| Scope | `database` · Restrição `collection.length() > 2` |
+
+**Query params:** `q` (`$match` inicial), `out` (coleção destino — **deve terminar em `__c`**), `out_operation` (`"replace"` → `drop()` antes), `strict`. **Header:** `Range` (define `$skip`/`$limit` quando há `out`).
+**Comportamentos:** `allowDiskUse(true)`; para `collection=player` sem scope de password adiciona `{$project:{password:0}}`; `out` que não termina em `__c` é ignorado (cai no retorno paginado). Body = `List<Object>` (estágios do pipeline). Ver §2.6.
+
+### `POST /v3/database/{collection}/aggregate_test` — agregação sem paginação
+
+| Aspecto | Detalhe |
+|---|---|
+| Scope | `database` · Restrição `collection.length() > 3` |
+
+**Query param:** `strict`. **Body:** `List<Object>` (estágios). Diferenças de `/aggregate`:
+- **Não** usa `$facet`; retorna **todos** os documentos via `IteratorUtils.toList()` (sem paginação).
+- **Não** suporta `out` (sem materialização).
+- **Não** aceita `q` (não há parâmetro `q` no método; o `$match` inicial nunca é montado).
+- `allowDiskUse(true)`.
+
+> **Correção importante (verificada em `DatabaseRest.java:605-668`):** ao contrário de `/aggregate`, o `aggregate_test` **NÃO** adiciona `{$project:{password:0}}` para a coleção `player`. Logo, um pipeline de teste sobre `player` **pode expor o campo `password`** mesmo sem o scope `read_encrypted_player_password`. Documentações anteriores afirmavam o contrário — está errado.
+
+### `DELETE /v3/database/{collection}/drop` — dropar coleção
+
+| Aspecto | Detalhe |
+|---|---|
+| Scope | **NENHUM** — não verifica `SCOPE_DATABASE` · Restrição `collection.length() > 0` · Status **200** |
+
+> **Risco crítico:** qualquer token autenticado (com apiKey válida) pode dropar **qualquer** coleção, inclusive `player`, `challenge`, `action_log`. Ver §8.
+
+### `GET /v3/database/collections` — listar coleções
+
+| Aspecto | Detalhe |
+|---|---|
+| Scope | **NENHUM** — sem verificação de `SCOPE_DATABASE` |
+
+Retorna `getCollectionNames()` — inclui coleções internas do sistema.
+
+### `GET /v3/database/count` — contar
+
+| Aspecto | Detalhe |
+|---|---|
+| Scope | `database` · `collection.length() > 0` |
+
+**Query params:** `collection`, `q`. **Resposta:** `{"total": N}`.
+
+### `POST /v3/database/{collection}/index` — criar índice(s)
+
+Scope `database`, `collection.length() > 0`. **Body:** `Map<campo, direção>` (ex.: `{"brand":1,"year":-1}`). Retorna `getIndexInfo()`.
+
+### `DELETE /v3/database/{collection}/index/{id}` — remover índice
+
+Scope `database`, `collection.length() > 0`. `dropIndex(id)` (id = nome do índice).
+
+### `GET /v3/database/{collection}/index` — listar índices
+
+Scope `database`, `collection.length() > 0`. Retorna `getIndexInfo()`.
+
+### `GET /v3/database/queue/info` — métricas da fila assíncrona
+
+| Aspecto | Detalhe |
+|---|---|
+| Scope | **NENHUM** |
+
+```json
+{ "size": 0, "remaining_capacity": 2147483647, "last_process_duration_ms": 145, "max_process_duration_ms": 890 }
+```
+
+### `DELETE /v3/database/queue/clear` — esvaziar a fila
+
+| Aspecto | Detalhe |
+|---|---|
+| Scope | **NENHUM** |
+
+`queue.clear()` — descarta tasks de bulk pendentes (perda de dados não processados).
+
+### `DELETE /v3/database/queue/info` — zerar métricas da fila
+
+| Aspecto | Detalhe |
+|---|---|
+| Scope | **NENHUM** |
+
+Reseta `last_process_duration_ms` e `max_process_duration_ms` para 0 (`clearQueueInfo`). **Endpoint distinto de `/queue/clear`** — não esvazia a fila, apenas zera os contadores.
+
+### Endpoints do Sistema — `v3/system/database`
+
+Operam sobre o **banco de sistema** (`SystemFactory.getInstance()`), não o do tenant. Cada um chama `checkSystemPermission("api", "/system/database", <op>)` e lança **HTTP 401** se negado.
+
+| Método | Path | Permissão | Restrição |
+|---|---|---|---|
+| `POST` | `/{collection}/index` | `create` | `collection.length() > 3` |
+| `DELETE` | `/{collection}/index/{id}` | `delete` | `collection.length() > 3` |
+| `GET` | `/{collection}/index` | `read` | `collection.length() > 3` |
+| `GET` | `/collections` | `read` | — |
+
+> Diferença relevante: no banco de sistema o `GET /collections` **exige** permissão; no banco do tenant (`/v3/database/collections`) **não exige** scope.
+
+---
+
+## 5. Regras de Negócio (existem no código, não no schema)
+
+### 5.1 Limiares de validação do nome da coleção (por endpoint)
+
+| Endpoint | Mínimo |
+|---|---|
+| `GET /collections`, `GET/DELETE /queue/*` | não usa collection |
+| `GET /{collection}`, `DELETE /{collection}`, `GET /count`, `POST/DELETE/GET /index` | `> 0` |
+| `GET /{collection}/{id}`, `DELETE /{collection}/drop` | `> 0` (drop) / `> 3` (find) |
+| `POST /aggregate` | `> 2` |
+| `POST /{collection}`, `PUT /{collection}`, `POST /bulk`, `POST /aggregate_test` | `> 3` |
+
+> Os limiares são **inconsistentes entre endpoints** — isso é comportamento real, não erro de documentação. `find` (GET by id) exige `> 3`, mas `delete` exige apenas `> 0`.
+
+### 5.2 Auto-geração de `_id`
+`Guid.newShortGuid()` quando ausente/`null` em POST, PUT e cada item do bulk. Em PUT, isso transforma a operação em criação de documento novo.
+
+### 5.3 PUT é replace completo
+`save()` substitui o documento inteiro. Não há endpoint de patch parcial (o que existia, `/operations`, está comentado — ver §7).
+
+### 5.4 Player password protection
+`collection == "player"` e token sem `read_encrypted_player_password`: em PUT e no bulk (`readPlayerPassword=true`), a senha existente é preservada quando ausente/`null` no objeto enviado. Comentário "SEGURANCA BRADESCO" no código.
+
+### 5.5 Convenção `__c`
+Não é validada no CRUD. Única exigência: `out` do `aggregate` deve terminar em `__c`. O framework usa internamente `csv_config__c`, `csv_log__c`, `csv_format__c`, `find_cache_<id>__c`, `email_code_verifier_log__c`.
+
+### 5.6 Limite de delete (20.000)
+Filtro que casa > 20.000 docs → no-op silencioso com 200. (Comentário do código diz "1000", mas o valor real é 20.000.)
+
+### 5.7 Assimetria de encriptação — risco silencioso
+Encriptação na escrita só ocorre se `checkReadEncryptedValues()` for verdadeiro. Esse método retorna `true` por **dois caminhos** (`AuthBean.java:221-226`): scope `read_encrypted_field_values` **ou** permissão de sistema `api/encrypted_field_values/read`. Se **nenhum** estiver presente, o dado é salvo em **plaintext** na coleção configurada, **sem aviso**. Resultado: a mesma coleção pode acumular documentos encriptados e em plaintext, dependendo de qual token escreveu. Além disso, falhas internas de `AesCrypt.encryptFields` (ex.: JSONPath inválido) são **engolidas** (`printStackTrace`) → o campo permanece plaintext silenciosamente.
+
+### 5.8 Remoção de campos `null` no retorno
+Respostas não-strict passam por `Include.NON_NULL` → campos `null` desaparecem. Não é perda de dados (persistem no Mongo), mas surpreende clientes que esperam o campo.
+
+### 5.9 Isolamento multi-tenant
+Toda operação resolve `FrontController.getInstance(authBean.getApiKey()).getManagerFactory().getJongoConnection()` — conexão isolada por apiKey. Sem acesso cross-tenant acidental.
+
+---
+
+## 6. Comportamentos Automáticos
+
+| Comportamento | Trigger | Impacto | Persistência |
+|---|---|---|---|
+| Auto-`_id` | `_id` ausente em POST/PUT/bulk | Gera `Guid.newShortGuid()` | Sim |
+| Trigger `before_create` | POST e cada item do bulk | Roda Groovy; pode **mutar** o objeto (passado por referência) | Mutação persiste |
+| Trigger `after_create` | POST e cada item do bulk | Efeitos colaterais | — |
+| Trigger `before_update` / `after_update` | PUT | Idem | Mutação em `before_update` persiste |
+| Trigger `before_delete` / `after_delete` | DELETE (apenas se `total <= 20.000` **e** `ids > 0`) | Recebe lista de `_id`s | — |
+| Trigger `before_bulk` / `after_bulk` | POST `/bulk` | Recebe a lista inteira | — |
+| Auditoria | POST/PUT/DELETE | Grava em `audit_log` **somente sob condições** (ver abaixo) | Condicional |
+| Encriptação de campos | POST/PUT **com** capacidade de cripto + config + secret | Encripta JSONPaths configurados | Encriptado no Mongo |
+| Plaintext silencioso | POST/PUT **sem** capacidade de cripto em coleção configurada | Salva sem encriptar, sem aviso | Plaintext no Mongo |
+| Preservação de password | PUT/bulk em `player` sem scope de password | Reinsere a senha atual | Mantida |
+| Ocultar password no aggregate | `/aggregate` em `player` sem scope de password | Adiciona `{$project:{password:0}}` | Só filtra retorno |
+
+> **Trigger NÃO aborta a operação (correção):** em `TriggerManager.execute` (`:48-68`), cada `runner.run(...)` está dentro de `try/catch` que apenas faz `printStackTrace`. Uma exceção no script **não** interrompe o CRUD. Além disso, há **limite diário de execuções** por trigger (`newTriggerExecution`) — ao exceder, o trigger é **silenciosamente pulado** (apenas log em stdout).
+
+> **Auditoria é triplamente condicional (correção):** `AuditManager.log` (`:81-129`) só grava em `audit_log` se **(1)** o token carrega identidade de `studio` (user) **ou** `player`; **(2)** existe um documento `Audit` **ativo** na coleção `audit` casando `{active:true, entity:<collection>, event:<create|update|delete>}`; **(3)** o `type` desse `Audit` (`all`/`studio`/`player`) é compatível com o tipo do chamador. Tokens puramente de aplicação (Basic/api_key, sem user/player) **não geram auditoria**. O `bulk` **nunca** audita.
+
+---
+
+## 7. Suportado vs NÃO Suportado
+
+### ✅ Suportado
+- CRUD genérico em qualquer coleção do tenant.
+- Filtro inline (`?q=field:'value'`) e paginação (`Range` + `Content-Range`, `max_results`).
+- Pipeline de agregação completo com `$facet`, `allowDiskUse`, múltiplos estágios.
+- Materialização de agregação em coleção `__c` (`?out=`, `out_operation=replace`).
+- Bulk insert síncrono e assíncrono (via fila por tenant).
+- Encriptação AES de campos por coleção (JSONPaths), com chave por gamification.
+- Triggers `before`/`after` em todos os eventos CRUD + `before_bulk`/`after_bulk`.
+- Gerenciamento de índices (criar/remover/listar) no banco do tenant e do sistema.
+- BSON extended JSON via `strict=true`; atalho `id=me`.
+- Monitoramento/controle da fila assíncrona.
+
+### ❌ NÃO Suportado / Limitações (confirmadas no código)
+- **Schema/validação:** nenhuma — qualquer JSON é aceito.
+- **PATCH parcial:** PUT é sempre replace via `save()`.
+- **`PUT /{collection}/operations`:** **código morto** comentado em `DatabaseRest.java:393-447` (operações `$inc`/`$set`/`upsert`/`multi`). Implementado, porém **nunca exposto**.
+- **Delete > 20.000 docs:** no-op silencioso (200).
+- **Auditoria no bulk:** inexistente.
+- **Encriptação no bulk e no aggregate:** inexistente (campos não são encriptados/decriptados nesses caminhos).
+- **`aggregate_test` não oculta `password`** da coleção `player` (diferente de `/aggregate`).
+- **Transações ACID** entre operações: inexistentes.
+- **Proteção de coleções internas:** com scope `database` é possível ler/escrever `player`, `action_log`, `trigger`, `security`, etc.; e `drop`/`collections`/`queue/*` **não exigem scope algum**.
+- **Persistência da fila assíncrona:** inexistente — restart perde tasks pendentes; sem confirmação de processamento ao chamador (`async=true`).
+
+---
+
+## 8. Segurança e Permissões
+
+### 8.1 Autenticação (`AuthBean`)
+Aceita `Authorization: Bearer <JWT>` (claims `apiKey`, `scope`, `player`, `user`), `Basic <base64(apiKey:appSecret)>` (scope calculado a partir da `Application`/role `public`), `Account <...>` e `Studio <token>`. O scope para Bearer vem do claim `scope` do JWT.
+
+### 8.2 Scope `database` e capacidades
+- `SCOPE_DATABASE = "database"` — exigido pela maioria das operações CRUD.
+- `SCOPE_READ_CRYPTED = "read_encrypted_field_values"` — habilita encriptar/decriptar campos (ou perm. de sistema `api/encrypted_field_values/read`).
+- `SCOPE_READ_PLAYER_PASSWORD = "read_encrypted_player_password"` — habilita ver/preservar password do player.
+- Falha de scope → **falha silenciosa** (`null`/200 ou 201), sem mensagem de erro.
+
+### 8.3 Superfícies de risco (verificadas no código)
+
+**DROP sem scope (CRÍTICO):** `DatabaseRest.java:590-603` — `drop()` não verifica `SCOPE_DATABASE`. Qualquer token autenticado dropa qualquer coleção.
+
+**`collections` e `queue/*` sem scope:** `findCollectionNames`, `findQueueInfo`, `deleteQueueClear`, `deleteQueueInfo` não verificam scope — expõem nomes de coleções internas e permitem esvaziar a fila/contadores.
+
+**Injeção de query MongoDB:** `q`, `out` e os estágios do pipeline são concatenados/passados **crus** ao Mongo (`s.append(q)` em `findAll`/`count`; `out` em `aggregate`). Qualquer expressão válida (`$where`, `$regex`, etc.) pode ser injetada.
+```java
+// findAll (:143-145)
+s.append("{ $match : {");
+if(q != null && q.trim().length() > 0) { s.append(q); }
+s.append("}}");
+```
+
+**`aggregate_test` expõe password de `player`** (sem o `$project:{password:0}` que `/aggregate` aplica).
+
+**Criptografia AES em modo ECB:** `AesCrypt` usa `AES/ECB/PKCS5Padding` (`AesCrypt.java:49,65`) — modo **determinístico**: plaintexts iguais geram ciphertexts iguais, vazando padrões (não recomendado para dados sensíveis estruturados). Falhas de cripto são engolidas, podendo deixar campos em plaintext.
+
+**Acesso a coleções internas:** o scope `database` não é restrito a coleções `__c`; cobre todas as coleções do tenant.
+
+### 8.4 Isolamento por tenant
+Garantido por `getJongoConnection()` resolvido a partir do `apiKey`. Operações de sistema usam `SystemFactory` + `checkSystemPermission`.
+
+---
+
+## 9. Observabilidade e Troubleshooting
+
+### 9.1 Verificações rápidas
+```
+GET /v3/database/collections                       # banco acessível? lista coleções
+GET /v3/database/count?collection=cars__c&q=       # total de docs
+GET /v3/database/cars__c                           # lista (Range: items=0-10)
+GET /v3/database/queue/info                         # estado da fila assíncrona
+GET /v3/trigger?q=entity:'cars__c'                  # triggers configuradas p/ a coleção
+GET /v3/database/cars__c/index                      # índices da coleção
+```
+
+### 9.2 Erros comuns
+
+| Sintoma | Causa provável | Diagnóstico |
+|---|---|---|
+| Resposta vazia com 200/201 | Token sem scope `database` ou nome de coleção curto demais | Conferir `scope` e o limiar de chars do endpoint (§5.1) |
+| DELETE retorna 200 mas nada some | Filtro casa > 20.000 docs | `GET /count?q=...` antes; paginar o filtro |
+| PUT criou doc novo em vez de atualizar | `_id` ausente no body | Incluir `_id` |
+| Campo volta como string ilegível | Token de leitura sem capacidade de cripto → ciphertext retornado | Usar token com `read_encrypted_field_values` |
+| Coleção com mix encriptado/plaintext | Algum writer escreveu sem capacidade de cripto | Garantir capacidade em **todos** os writers (§5.7) |
+| Password do player virou `null` | Leu sem password e regravou com permissão de password | Reler com mesmo nível de permissão e incluir `password` no PUT |
+| Bulk `async=true` "não gravou" | Sem confirmação/persistência; pode ter falhado no worker | Usar `async=false` para garantir; checar `queue/info` |
+| Auditoria não aparece | Sem `Audit` ativo p/ `{entity,event}`, ou token sem user/player, ou bulk | Conferir coleção `audit` e o tipo do token (§6) |
+| Aggregate lento/timeout | Sem `$match` inicial em coleção grande | Adicionar `?q=...`; `allowDiskUse` já está ligado |
+
+### 9.3 Validar um pipeline antes de produção
+```json
+POST /v3/database/action_log/aggregate_test
+[ {"$group":{"_id":"$extra.product_id","total":{"$sum":1}}}, {"$sort":{"total":-1}}, {"$limit":5} ]
+```
+Retorna o array completo (sem paginação). **Nunca** rode `aggregate_test` sobre `player` sem cuidar do `password` no pipeline.
+
+---
+
+## 10. Exemplos Práticos
+
+### 10.1 Mínimo funcional
 ```json
-{
-  "_id": "car001",
-  "name": "Civic",
-  "brand": "Honda",
-  "price": 50000
-}
+POST /v3/database/products__c
+Authorization: Bearer <token-com-scope-database>
+
+{ "_id": "prod001", "name": "Notebook Dell", "price": 3500.00, "category": "electronics" }
 ```
+Resposta **201** (campos `null` removidos no modo não-strict).
 
-### Atualizar Objeto
-**Método:** PUT
-**Endpoint:** `/v3/database/<nome>__c`
+### 10.2 Avançado — aggregate com materialização
+```json
+POST /v3/database/action_log/aggregate?out=report_sales_by_product__c&out_operation=replace
+Range: items=0-1000
+Authorization: Bearer <token>
 
-### Excluir Objeto
-**Método:** DELETE
-**Endpoint:** `/v3/database/<nome>__c?q=_id:'car001'`
+[
+  {"$match": {"actionId": "purchase", "time": {"$gte": 1700000000000}}},
+  {"$group": {"_id": "$extra.product_id", "total_revenue": {"$sum": "$extra.value"}, "total_units": {"$sum": 1}}},
+  {"$sort": {"total_revenue": -1}}
+]
+```
+Resposta:
+```json
+{ "total": 42, "out": "report_sales_by_product__c" }
+```
+
+### 10.3 Bulk síncrono com triggers
+```json
+POST /v3/database/locations__c/bulk?async=false
+[
+  {"_id": "loc001", "name": "São Paulo"},
+  {"name": "Belo Horizonte"}
+]
+```
+O segundo objeto recebe `_id` automático. Cada item dispara `before_create`/`after_create`; a lista dispara `before_bulk`/`after_bulk`. **Sem auditoria e sem encriptação** mesmo se `locations__c` estiver em `crypt_object_field`.
+
+### 10.4 Anti-pattern — PUT sem `_id`
+```json
+PUT /v3/database/products__c
+{ "name": "Notebook Atualizado", "price": 3200.00 }
+```
+**Resultado:** cria documento NOVO (`_id` gerado). O original não é atualizado. **Sempre** envie `_id` no PUT — e lembre que campos omitidos serão removidos (replace, não patch).
+
+### 10.5 Anti-pattern — DELETE em volume sem checar count
+```
+DELETE /v3/database/logs__c?q=year:2022
+```
+Se houver > 20.000 docs de 2022, retorna **200 sem deletar nada**. Cheque antes:
+```
+GET /v3/database/count?collection=logs__c&q=year:2022
+```
+Se > 20.000, fatie o filtro (ex.: `year:2022,month:{$lte:6}`) ou use `/drop` (com cautela — sem scope).
 
-## Boas Práticas
+### 10.6 Anti-pattern — confiar em encriptação sem a capacidade
+Escrever em coleção com `crypt_object_field` configurado usando token **sem** `read_encrypted_field_values` (nem permissão de sistema) salva os campos em **plaintext silenciosamente**. Garanta a capacidade em todos os writers.
 
-- Sempre usar sufixo `__c` no nome da coleção
-- Definir `_id` único para cada objeto
-- Criar índices para campos usados em consultas frequentes
+---
 
-## Validações e Testes
+## Checklist de Configuração
 
-- [ ] Coleção customizada aparece em GET /v3/database/collections
-- [ ] CRUD funciona corretamente
-- [ ] Triggers com entity `<nome>__c` funcionam
+- [ ] Aplicação com scope `database` (cadastro em `/v3/security`).
+- [ ] Nome da coleção respeita o limiar de chars do endpoint usado (§5.1): `> 3` para POST/PUT/bulk/aggregate_test, `> 2` para aggregate, `> 0` para GET-list/delete/count/index.
+- [ ] `_id` incluído no PUT para atualizar (e ciência de que PUT é replace completo).
+- [ ] Sufixo `__c` no destino `out` do aggregate.
+- [ ] `GET /count` executado antes de DELETE para garantir filtro com ≤ 20.000 docs.
+- [ ] Triggers cadastradas com `entity: '<colecao>'` se há comportamento automático esperado — e ciência de que **exceção no script não aborta** a operação.
+- [ ] `Audit` **ativo** em `{entity, event, type}` se auditoria for necessária (e token com user/player; bulk não audita).
+- [ ] Índices criados (`POST /{collection}/index`) para campos de filtro frequente.
+- [ ] Todos os writers de coleção encriptada possuem a capacidade `read_encrypted_field_values` (scope) ou a permissão de sistema — caso contrário grava plaintext.
+- [ ] `DROP`, `collections` e `queue/*` protegidos por ACL externa/gateway — **não há scope** nesses endpoints.
+- [ ] Para dados sensíveis, ciência de que a cifra é **AES-ECB** (determinística) — avaliar mitigação na aplicação.
+- [ ] Para bulk crítico, preferir `async=false` (sem confirmação/persistência no modo assíncrono).