funifier-mcp 0.2.26 → 0.2.27

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

@@ -1,241 +1,807 @@
-# Database (Database)
+# `database`
 
-**API Endpoint:** `/v3/database`
+**Acesso Studio:** `/studio/database`
+**API Endpoint (tenant):** `/v3/database`
+**API Endpoint (system):** `/v3/system/database`
+**Coleção MongoDB:** não possui coleção própria — opera diretamente sobre **qualquer** coleção do banco da gamificação (tenant) ou do banco de sistema.
 
-## O que é
+---
 
-Acesso direto à base de dados para operações avançadas. Oferece ferramentas para criar índices, executar comandos aggregate (MongoDB), importar dados em lote, e muito mais. Permite extrair relatórios personalizados e realizar manipulações complexas diretamente no banco de dados da gamificação. Cada gamificação tem seu próprio banco de dados.
+## 1. Visão Geral
 
-## ⚠️ Requisito de Permissão Especial
+O módulo `database` é uma API de acesso direto ao MongoDB. Diferente dos demais módulos da plataforma, ele **não tem schema, Entity, Repository nem DAO próprios**: os documentos trafegam como `HashMap<String, Object>` (entrada) e `BasicDBObject` (persistência), e qualquer JSON é aceito e gravado sem validação.
 
-O endpoint `/v3/database` exige que a palavra **`database`** esteja presente no scope da Role do token, **além** das permissões padrão (`read_all`, `write_all`, `delete_all`). Sem ela:
+Papel arquitetural:
 
-- **POST** retorna `201` mas **NÃO persiste os dados**
-- **GET** retorna `200` com **corpo vazio**
-- **Nenhuma mensagem de erro** é exibida
+- Expõe operações CRUD, MongoDB Aggregation Framework, gestão de índices, contagem, drop de coleção e bulk insert sobre coleções nativas (ex.: `player`, `action_log`, `achievement`) e coleções customizadas (convenção de sufixo `__c`).
+- É o mecanismo de **bulk insert assíncrono** usado por pipelines de importação, com uma thread dedicada por tenant.
+- Permite gravar o resultado de uma aggregation em outra coleção (`out`), funcionando como motor de materialização de relatórios.
 
-**Scope mínimo para usar database:** `read_all, write_all, delete_all, database`
+Relação com outros módulos:
 
-Configurar em: `Studio > Security > Roles`
+- **Triggers** (`com.funifier.engine.integration.trigger.TriggerManager`) são disparados em todas as operações de escrita (`before_create`, `after_create`, `before_update`, `after_update`, `before_delete`, `after_delete`, e os literais `before_bulk` / `after_bulk`).
+- **Audit log** (`com.funifier.engine.audit.AuditManager`) registra POST, PUT e DELETE — mas **não** registra bulk insert.
+- **Criptografia de campos AES v4.0** (`com.funifier.engine.crypt.CryptManager` + `com.funifier.engine.util.AesCrypt`) atua em POST, PUT e GET por `_id` quando o token está autorizado.
+- Usa a mesma conexão `Jongo`/`MongoClient` compartilhada pela plataforma (`ManagerFactory.getJongoConnection()` no tenant; `SystemFactory.getInstance().getJongoConnection()` no sistema).
 
-> **Nota:** O jogador precisa fazer login novamente após alteração da Role para obter um token com as novas permissões.
+Problema que resolve: dar a aplicações externas e a integrações um canal direto de leitura/escrita sobre o banco da gamificação, sem precisar de um endpoint REST dedicado por tipo de dado, ao custo de transferir para o cliente a responsabilidade por consistência, validação e segurança de query.
 
-## Quando usar
+---
 
-- Para consultas avançadas com aggregates MongoDB
-- Para criar/gerenciar índices de performance
-- Para operações CRUD em qualquer coleção
-- Para inserção em massa (bulk)
-- Para acessar coleções customizadas (sufixo __c)
+## 2. Arquitetura e Fluxos
 
-## API Endpoints
+### 2.1 Classes envolvidas
 
-### Listar Coleções
-**Método:** GET
-**Endpoint:** `/v3/database/collections`
-**Descrição:** Lista todas as coleções existentes no banco.
+| Classe | Papel |
+|---|---|
+| `com.funifier.rest.v3.rest.DatabaseRest` | Controller REST tenant (`/v3/database`) — todos os endpoints CRUD/aggregate/index/queue |
+| `com.funifier.rest.v3.rest.system.DatabaseRest` | Controller REST sistema (`/v3/system/database`) — só índices e listagem de coleções |
+| `com.funifier.engine.database.DatabaseManager` | Orquestra bulk insert (`bulkInsert`) e gerencia o processador assíncrono |
+| `com.funifier.engine.database.DatabaseAsyncProcessor` | `Runnable` — thread dedicada por tenant que consome a fila de bulk |
+| `com.funifier.engine.database.DatabaseAsyncTask` | DTO de task assíncrona (`task`, `collection`, `list`, `readPlayerPassword`) |
+| `com.funifier.engine.util.PaginationUtil` | Paginação via estágio `$facet`; `getPageResult` (silencioso) vs `getPageResultThrowsException` |
+| `com.funifier.engine.util.AesCrypt` | Criptografia AES de campos por JSONPath |
+| `com.funifier.engine.crypt.CryptManager` | Resolve `CryptObjectField` (config de campos) e `CryptTenantSecret` (segredo) |
+| `com.funifier.controller.database.ConnectionPool` | Pool `MongoClient`; cria índices nativos no startup do tenant (`createIndexes`) |
+| `com.funifier.controller.database.ConnectionContext` | Parâmetros da conexão (URI, host, user, password, pool) |
 
-### Buscar Registro por ID
-**Método:** GET
-**Endpoint:** `/v3/database/:collection/:id`
-**Query Params:**
-- `strict=true` — Preserva tipos BSON (datas como `{ $date }`, etc.)
-- Use `me` como ID para buscar dados do player autenticado
+> **Atenção (legado comentado):** existe um endpoint `PUT /{collection}/operations` (método `updateOperations`) que aplicaria operadores MongoDB (`$inc`, `$set`, upsert, multi) a vários documentos. Ele está **inteiramente comentado** em `DatabaseRest` (linhas ~393–447) e **não existe em runtime**. Ver seção 7.
 
-### Listar Dados de uma Coleção (com filtro)
-**Método:** GET
-**Endpoint:** `/v3/database/:collection`
-**Query Params:**
-- `q` — Filtro MongoDB (sintaxe Mongo, NÃO JSON). Inserido dentro de `{ $match: { <q> } }`
-- `strict=true` — Preserva tipos BSON
-- `max_results` — Máximo de resultados (default: 100)
+### 2.2 Pipeline — `insert()` (POST, insert puro)
 
-**Header:**
-- `Range: items=0-19` — Paginação (Range-based)
+Síncrono. Citando os métodos reais de `DatabaseRest.insert`:
 
-**⚠️ IMPORTANTE:** O parâmetro correto de filtro é `q`, **NÃO** `_filter`. Parâmetros como `_filter`, `_sort`, `_limit` **NÃO existem** neste endpoint e são silenciosamente ignorados.
+```
+[1] gson = "true".equalsIgnoreCase(strict)
+[2] Guarda: getScope().indexOf("database") != -1  E  collection.trim().length() > 3
+    → se falso: NÃO entra no bloco; retorna 201 com body null (sem erro, sem log)
+[3] Se _id ausente ou null → object.put("_id", Guid.newShortGuid())   // ObjectId.toString(), 24 hex
+[4] player = authBean.getPlayerFromTokenIfExist()                      // claim "player" do JWT; null em Basic
+[5] triggerManager.execute(null, object, collection, "before_create", player, null)
+[6] CRIPTOGRAFIA (só se authBean.checkReadEncryptedValues() == true):
+      field  = cryptManager.findObjectField(collection)               // coleção crypt_object_field (tenant)
+      secret = cryptManager.findTenantSecretActive()                  // coleção crypt_tenant_secret (system)
+      se field.fields não vazio E secret ativa:
+        object = JsonUtil.fromJson(JsonUtil.toBsonStrictMode(object))  // preserva marcações BSON
+        object = AesCrypt.encryptFields(object, field.fields, secret.secret)
+        encrypted = true
+[7] o = BasicDBObject.parse( marshaller.marshall(object).toString() )  // JacksonMapper → tipo BSON
+[8] jongo.getCollection(collection).insert(o)                          // INSERT puro — falha se _id já existe
+[9] triggerManager.execute(null, o, collection, "after_create", player, null)
+[10] auditManager.log(collection, "create", authBean, o)
+[11] Se encrypted → AesCrypt.decryptFields(o, ...) para a resposta sair em claro
+[12] Retorna 201 com o documento (decriptado se aplicável)
+```
+
+> **Comportamento silencioso crítico:** a criptografia de escrita é condicionada a `checkReadEncryptedValues()`. Um token **sem** o scope `read_encrypted_field_values` que grava em uma coleção com campos configurados em `crypt_object_field` armazena o valor **em texto puro**, lado a lado com documentos criptografados. Uma leitura posterior com a permissão tentará `AesCrypt.decrypt` sobre texto puro → exceção interna → o campo retorna **`null`**. Isso corrompe dados silenciosamente.
+
+### 2.3 Pipeline — `update()` (PUT, full replace / upsert)
+
+Síncrono. Idêntico ao POST exceto:
 
-**Exemplos de `q`:**
 ```
-?q=userId:"ricardo@funifier.com"
-?q=userId:"ricardo@funifier.com", type:"daily"
-?q=status:"active", price:{$gte:100}
-?q=_id:"abc123"
+[5'] eventos before_update / after_update (em vez de create)
+[6'] mesmo bloco de criptografia
+[7'] o = BasicDBObject.parse(...)
+[SEGURANÇA "BRADESCO" — só coleção player E !authBean.checkReadPlayerPassword()]:
+      current = jongo.getCollection("player").findOne("{_id:#}", object.get("_id")).as(Player.class)
+      se current != null E (object.get("password") == null OU !object.containsKey("password")):
+        o.put("password", current.password)   // restaura senha existente
+[8'] jongo.getCollection(collection).save(o)   // UPSERT por _id — substitui o documento inteiro
+[10'] auditManager.log(collection, "update", authBean, o)
 ```
 
-**⚠️ Limitação:** O `GET` não suporta `$sort`. Internamente ele executa `{ $match: { <q> } }` via aggregate, sem estágios adicionais. Para queries com ordenação, use o endpoint `aggregate`.
+**PUT é full replace, não PATCH:** campos ausentes no corpo são removidos do documento. Como `_id` é gerado quando ausente (passo [3]), um PUT sem `_id` **cria** um documento novo a cada chamada.
 
-### Contar Registros
-**Método:** GET
-**Endpoint:** `/v3/database/count?collection=:collection&q=:query`
-**Descrição:** Retorna `{ total: N }`.
+### 2.4 Pipeline — `delete()` (DELETE por filtro)
 
-### Criar Registro (Upsert)
-**Método:** POST
-**Endpoint:** `/v3/database/:collection`
-**Query Params:**
-- `strict=true` — Para preservar tipos BSON na resposta
+```
+[1] Guarda: scope database E collection.trim().length() > 0 E q != null E q.trim().length() >= 3
+[2] total = jongo.getCollection(collection).count("{" + q + "}")
+[3] Se total <= 20.000:
+      ids = jongo.getCollection(collection).distinct("_id").query("{" + q + "}").as(String.class)
+    Senão: ids permanece lista vazia (não é populada)
+[4] Se ids != null E ids.size() > 0:
+      triggerManager.execute(null, ids, collection, "before_delete", null, null)
+      jongo.getCollection(collection).remove("{" + q + "}")
+      triggerManager.execute(null, ids, collection, "after_delete", null, null)
+      auditManager.log(collection, "delete", authBean, ids)
+[5] Retorna sempre 200 com body null
+```
 
-**Descrição:** Se `_id` não for fornecido, gera automaticamente um GUID curto. Executa triggers `before_create` e `after_create`.
+> **CORREÇÃO DE COMPORTAMENTO (contra-intuitivo e não documentado antes):** o `remove()` está **dentro** do `if(ids.size() > 0)`. Quando `total > 20.000`, `ids` nunca é populada → o bloco inteiro é pulado → **nada é excluído**. Ou seja, **um DELETE cujo filtro casa mais de 20.000 documentos é um no-op silencioso**: retorna 200, não dispara triggers, não audita e não apaga nada. Só há exclusão quando `1 ≤ casados ≤ 20.000`.
+>
+> O comentário no código diz "menor que 1000", mas o limite real codificado é `<= 20_000`.
+
+#### Fluxo de exclusão — `delete()`
+
+```mermaid
+flowchart TD
+    A[DELETE /v3/database/collection?q=...] --> B{"scope, collection>0 e q>=3 chars?"}
+    B -- nao --> Z[200 body null - nada acontece]
+    B -- sim --> C["total = count({q})"]
+    C --> D{"total <= 20.000?"}
+    D -- nao --> E[ids fica vazia]
+    E --> F{"ids.size > 0?"}
+    D -- sim --> G["ids = distinct _id where {q}"]
+    G --> F
+    F -- nao --> Z2[200 body null - NO-OP SILENCIOSO]
+    F -- sim --> H[before_delete trigger]
+    H --> I["remove({q})"]
+    I --> J[after_delete trigger]
+    J --> K[auditManager.log delete]
+    K --> L[200 body null]
+```
 
-**Exemplo de Body:**
-```json
-{
-  "year": 2010,
-  "fuel": "gasoline",
-  "price": 50000,
-  "name": "Civic",
-  "description": "Honda Civic",
-  "brand": "honda"
-}
+### 2.5 Pipeline — Bulk insert (`insertBulk` → `DatabaseManager.bulkInsert`)
+
+```
+insertBulk (controller):
+[1] Guarda: scope database E collection.trim().length() > 3 E list != null E list.size() > 0
+[2] result.put("total", list.size())
+[3] readPlayerPassword = (collection == "player" E !authBean.checkReadPlayerPassword())
+[4] async == "true" → manager.getDatabaseManager().addAsyncTask(task)  // enfileira e responde já
+    senão           → manager.getDatabaseManager().bulkInsert(collection, list, readPlayerPassword)
+[5] Retorna 201 com {"total": N}   (se a guarda falhar → 201 com {})
+
+DatabaseManager.bulkInsert (síncrono, item a item):
+[a] triggerManager.execute(null, list, collection, "before_bulk", null, null)   // player SEMPRE null
+[b] para cada objeto:
+      object = BasicDBObject.parse( marshaller.marshall(o).toString() )
+      se _id ausente/null → Guid.newShortGuid()
+      se readPlayerPassword E player atual existe E object.password null → object.put("password", current.password)
+      triggerManager.execute(null, object, collection, "before_create", null, null)
+      c.save(object)                                                            // UPSERT, não insert
+      triggerManager.execute(null, object, collection, "after_create", null, null)
+[c] triggerManager.execute(null, list, collection, "after_bulk", null, null)
 ```
 
-### Atualizar Registro (Save/Upsert)
-**Método:** PUT
-**Endpoint:** `/v3/database/:collection`
-**Query Params:**
-- `strict=true` — Para preservar tipos BSON
+Observações reais:
+
+- **Bulk usa `save()` (upsert), não `insert()`** — um `_id` repetido sobrescreve em vez de gerar erro de chave duplicada. Difere do POST simples (`insert()`).
+- **Bulk não gera audit log** (nem síncrono nem assíncrono). Apenas POST/PUT/DELETE auditam.
+- O `player` passado às triggers é **sempre `null`** no bulk (mesmo na variante síncrona), pois `bulkInsert` não recebe o `AuthBean`.
+- `before_bulk` / `after_bulk` são **strings literais**, não constantes em `Trigger` (que só define os eventos create/update/delete).
+
+### 2.6 Processador assíncrono — `DatabaseAsyncProcessor`
+
+Uma thread por tenant, criada no construtor de `DatabaseManager` e nomeada `Funifier-Database-Async-<apiKey>`. Ela é iniciada na primeira vez que o `DatabaseManager` daquele tenant é instanciado.
+
+```mermaid
+sequenceDiagram
+    participant C as Cliente
+    participant R as DatabaseRest.insertBulk
+    participant M as DatabaseManager
+    participant Q as LinkedBlockingQueue
+    participant T as Thread Funifier-Database-Async
+    C->>R: POST /collection/bulk?async=true
+    R->>M: addAsyncTask(task)
+    M->>Q: queue.offer(task)
+    R-->>C: 201 {"total": N} (imediato)
+    loop run() enquanto thread viva
+        T->>Q: queue.poll()
+        alt task de bulk válida
+            T->>M: bulkInsert(collection, list, readPlayerPassword)
+            T->>T: lastDuration / maxDuration
+        else fila vazia
+            T->>T: Thread.sleep(100ms)
+        end
+    end
+```
+
+A fila é uma `LinkedBlockingQueue` **sem capacidade definida** → ilimitada. Logo `remaining_capacity` em `/queue/info` é sempre `Integer.MAX_VALUE` (2147483647) — campo essencialmente decorativo. Não há persistência: tasks pendentes são perdidas em restart do processo.
+
+#### Decisão de criptografia na escrita (POST/PUT)
+
+```mermaid
+flowchart TD
+    A[POST/PUT documento] --> B{checkReadEncryptedValues?}
+    B -- nao --> P[Grava EM TEXTO PURO mesmo se campo for criptografado - corrompe leitura futura]
+    B -- sim --> C{crypt_object_field tem campos p/ a colecao?}
+    C -- nao --> N[Grava sem criptografia]
+    C -- sim --> D{crypt_tenant_secret ativa existe?}
+    D -- nao --> N
+    D -- sim --> E[AesCrypt.encryptFields nos campos]
+    E --> F[Grava criptografado]
+    F --> G[Resposta decriptada em claro]
+```
 
-**Descrição:** Usa `save()` do MongoDB (upsert por `_id`). Executa triggers `before_update` e `after_update`. Se `_id` não existir, gera um novo.
+### 2.7 Paginação interna (GET list e POST aggregate)
 
-**⚠️ Player password safety:** Se a coleção for `player` e o token não tem permissão de ler senha, o PUT automaticamente preserva a senha existente (não sobrescreve com null).
+`PaginationUtil.getPageResult` / `getPageResultThrowsException` anexam ao pipeline:
 
-**Exemplo de Body:**
 ```json
-{
-  "_id": "6553e49815865a7a732f5fc7",
-  "year": 2010,
-  "fuel": "gasoline",
-  "price": 50000,
-  "name": "Civic",
-  "description": "Honda Civic",
-  "brand": "honda"
-}
+{"$facet": {
+  "result":     [{"$skip": skip}, {"$limit": limit}],
+  "pagination": [{"$group": {"_id": null, "count": {"$sum": 1}}}]
+}}
 ```
 
-### Excluir Registro(s)
-**Método:** DELETE
-**Endpoint:** `/v3/database/:collection?q=:query`
+Toda listagem executa, na mesma passagem, o slice de dados **e** a contagem total. O parse do header `Range` é feito por `getRange`:
+
+- `Range: items=<a>-<b>` → `skip = a`, `limit = b`. **O segundo número é o tamanho da página (`$limit`), não o índice final.**
+- Sem header → `skip = 0`, `limit = 100` (GET list usa `max_results`, padrão 100; aggregate usa 100 fixo).
+
+O `Content-Range` é montado por `getRangeResponse` como `"<chave> <skip>-<limit>/<count>"`.
+
+> **CORREÇÃO:** `Range: items=0-19` retorna **19** documentos (`$skip:0, $limit:19`) e devolve `Content-Range: items 0-19/<total>` — **não** `0-20`. O formato não segue o padrão HTTP `start-end/total`; o segundo número é a quantidade pedida.
+
+**Diferença silenciosa importante:** `getPageResult` (usado no GET list) **engole exceções** e retorna lista vazia em caso de erro de query. `getPageResultThrowsException` (usado no aggregate) **propaga** a exceção → erro 500 para sintaxe inválida de pipeline.
+
+---
+
+## 3. Estrutura dos Objetos
+
+### 3.1 Documentos — schema-less
+
+O módulo não define schema. Qualquer JSON é aceito. Comportamentos implícitos sobre `_id`:
+
+| Situação | Comportamento |
+|---|---|
+| `_id` ausente/`null` no POST | Gerado via `Guid.newShortGuid()` = `new ObjectId().toString()` (24 hex chars) |
+| `_id` ausente/`null` no PUT | Gerado automaticamente → o documento é **inserido**, não atualizado |
+| PUT com `_id` existente | Full replace via `save()` — campos não enviados são removidos |
+| Bulk com `_id` repetido | `save()` (upsert) sobrescreve; não há erro de duplicidade |
+| POST com `_id` já existente | `insert()` → falha (erro Mongo de chave duplicada propaga como 500) |
+
+**Campos com tratamento especial:**
+
+- `password` (coleção `player`): preservado em PUT e bulk quando o token não tem `read_encrypted_player_password` e o campo veio `null`/ausente. Enviar `"password": ""` **sobrescreve** com string vazia (a proteção só age sobre `null`/ausente).
+- Campos listados em `crypt_object_field`: criptografados/decriptados conforme seção 5.4.
+
+Não há campos computados nem campos removidos silenciosamente no save além do comportamento de full-replace do PUT.
+
+### 3.2 `DatabaseAsyncTask`
+
+| Campo | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `task` | String | — | Tipo da task; único valor processado: `"bulk"` (`TASK_BULK_INSERT`) |
+| `collection` | String | — | Coleção alvo |
+| `list` | `List<Object>` | — | Documentos a inserir/upsertar |
+| `readPlayerPassword` | boolean | `false` | Se `true`, preserva `password` do player existente |
+
+O `run()` só processa a task se `task=="bulk"`, `collection` não vazia e `list` não vazia; caso contrário dorme 100ms.
+
+### 3.3 `CryptObjectField` (config de criptografia de campos)
+
+Armazenado na coleção **`crypt_object_field`** do banco **tenant**. (`@JsonIgnoreProperties(ignoreUnknown=true)`.)
+
+| Campo | Tipo | Descrição |
+|---|---|---|
+| `_id` (mapeado para `entity`) | String | Nome da coleção à qual a criptografia se aplica |
+| `fields` | `List<String>` | Caminhos JSONPath dot-notation dos campos a criptografar |
+
+O segredo (`CryptTenantSecret`, campos `secret`/`status`/`gamification`) fica na coleção **`crypt_tenant_secret`** do banco **sistema**, resolvido por `findTenantSecretActive()` filtrando `status = "active"`.
+
+### 3.4 Resposta de `/queue/info`
+
+| Campo | Tipo | Descrição |
+|---|---|---|
+| `size` | int | Tasks pendentes na fila |
+| `remaining_capacity` | int | Capacidade restante — sempre `2147483647` (fila ilimitada) |
+| `last_process_duration_ms` | long | Duração do último bulk processado |
+| `max_process_duration_ms` | long | Maior duração registrada |
+
+---
+
+## 4. Endpoints
+
+Salvo indicação contrária, autenticação é **Bearer token (ou Basic apiKey:secretKey)** e a guarda de scope é `getScope().indexOf("database") != -1`. Quando a guarda de scope/validação falha, a resposta é vazia e **sem erro** (GET → `200 null`; POST/PUT → `201 null`/`{}`; DELETE → `200 null`).
+
+### 4.1 `GET /v3/database/{collection}/{id}`
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Buscar documento por `_id` (`find()`) |
+| `id = me` | Substituído por `getPlayerFromTokenIfExist()` — só funciona em token **Bearer** com claim `player`; em Basic vira `null` e cai na guarda |
+| Validação | `collection.trim().length() > 3` E `id.trim().length() > 0` |
+| Decriptação | Sim, se `checkReadEncryptedValues()` e campo configurado e secret ativa |
+
+**Query params:** `strict=true` → tipos BSON preservados (ex.: datas como `{$date:...}`). Por padrão, campos `null` são removidos da resposta (`toJsonRemoveNullFields`).
+
+### 4.2 `GET /v3/database/{collection}`
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Listar com filtro opcional (`findAll()`) |
+| Validação | `collection.trim().length() > 0` |
+
+**Query params:**
 
-**Descrição:** O `q` precisa ter pelo menos 3 caracteres. Executa triggers `before_delete` e `after_delete` se total ≤ 20.000 registros. IDs são identificados antes da exclusão para passar aos triggers.
+| Param | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `q` | String | — | Inserido cru em `{ $match : { <q> }}` — sintaxe Mongo direta, não JSON strict |
+| `strict` | String | — | `true` → tipos BSON |
+| `max_results` | String | `100` | Limite quando não há header `Range`; parse inválido → 100 silencioso |
 
-**Exemplos:**
+**Header:** `Range: items=<skip>-<limit>` (ver 2.7). Comportamento real:
+
+- **Não ordena** (`$sort`) — use `POST /aggregate`.
+- **Não decripta** campos criptografados (só o GET por `_id` decripta).
+- Erros de query são engolidos → retorna lista vazia (não 500).
+- `Content-Range` no formato não-padrão `items <skip>-<limit>/<total>`.
+
+### 4.3 `POST /v3/database/{collection}`
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Inserir documento novo (`insert()`) |
+| Operação Mongo | `insert()` — falha se `_id` já existe |
+| Validação | `collection.trim().length() > 3` |
+| Retorno | `201` com o documento (decriptado se aplicável) |
+
+**Exemplo:**
+
+```http
+POST /v3/database/car__c
+Authorization: Bearer <token>
+
+{ "brand": "honda", "model": "civic", "year": 2023 }
 ```
-DELETE /v3/database/checkin__c?q=_id:"abc123"
-DELETE /v3/database/signup__c?q=userId:"test@test.com"
+
+```json
+{ "_id": "507f1f77bcf86cd799439011", "brand": "honda", "model": "civic", "year": 2023 }
+```
+
+### 4.4 `PUT /v3/database/{collection}`
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Full replace / upsert por `_id` (`update()`) |
+| Operação Mongo | `save()` — substitui o documento inteiro |
+| Validação | `collection.trim().length() > 3` |
+| Retorno | `201` |
+
+Diferenças do REST padrão: é **full replace** (campos ausentes somem); sem `_id` cria documento novo; campos `null` sobrescrevem (exceto `password` em `player`, ver 5.3).
+
+### 4.5 `DELETE /v3/database/{collection}?q={query}`
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Excluir documentos que casam o filtro (`delete()`) |
+| Operação Mongo | `remove("{" + q + "}")` |
+| Validação | `collection > 0` E `q.trim().length() >= 3` |
+| Retorno | `200` body null (sempre) |
+
+Comportamento real (ver 2.4): `q` < 3 chars → no-op silencioso; **`total > 20.000` → no-op silencioso** (não apaga, não dispara trigger, não audita). A validação de 3 chars é só de comprimento — `q=a:1` (3 chars) apaga tudo onde `a==1`.
+
+### 4.6 `POST /v3/database/{collection}/bulk`
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Inserir/upsertar lista (`insertBulk()`) |
+| Validação | `collection > 3` E `list.size() > 0` |
+| Retorno | `201` com `{"total": N}` |
+
+**Query param:** `async=true` → enfileira no `DatabaseAsyncProcessor` e responde imediatamente. **Body:** array JSON. Comportamento real: upsert por item (`save`), triggers `before_create`/`after_create` por documento + `before_bulk`/`after_bulk` na lista, **sem audit log**, `player` sempre `null` nas triggers.
+
+### 4.7 `POST /v3/database/{collection}/aggregate`
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Executar pipeline de Aggregation (`aggregate()`) |
+| Validação | `collection.trim().length() > 2` |
+| Retorno | `200` paginado, ou `{"total": N, "out": "..."}` se `out` informado |
+
+**Query params:**
+
+| Param | Tipo | Descrição |
+|---|---|---|
+| `q` | String | Vira `{ $match : { <q> }}` como **primeiro** estágio, antes do body |
+| `strict` | String | `true` → tipos BSON |
+| `out` | String | Coleção destino — só efetivada se terminar em `__c` |
+| `out_operation` | String | `replace` → `drop()` na coleção destino antes de gravar |
+
+**Header:** `Range` para paginação (padrão `$limit:100`). Comportamento real:
+
+- `allowDiskUse(true)` sempre ativo.
+- Body é `List<Object>`; cada elemento é um estágio.
+- Coleção `player` + token sem `read_encrypted_player_password` → adiciona `{$project:{password:0}}` ao **final** do pipeline.
+- Com `out` válido: aplica `$skip`/`$limit` (do `Range`) e itera salvando cada doc na coleção destino via `save()`.
+- Erro de pipeline → **500** (usa `getPageResultThrowsException`).
+- **Não decripta** campos criptografados.
+
+### 4.8 `POST /v3/database/{collection}/aggregate_test`
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Rodar pipeline **sem paginação**, retornando a lista completa (`aggregate_test()`) |
+| Validação | `collection.trim().length() > 3` |
+| Diferença vs `/aggregate` | Sem `$facet`, sem `out`, sem param `q`; sem `Content-Range` |
+| Retorno | `200` com array JSON cru |
+
+> **Inconsistência de segurança:** `aggregate_test` **não** adiciona `{$project:{password:0}}`. Um token apenas com scope `database` pode ler o campo `password` da coleção `player` por este endpoint, contornando a proteção que existe em `/aggregate`. Ver seções 7 e 8.
+
+Sem estágios no body, executa `{$match:{}}` (retorna tudo).
+
+### 4.9 `DELETE /v3/database/{collection}/drop`
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Dropar a coleção inteira (`drop()`) |
+| Operação Mongo | `jongo.getCollection(collection).drop()` |
+| Validação | apenas `collection.trim().length() > 0` |
+| ⚠️ Scope | **NÃO verifica o scope `database`** — qualquer token cujo `apiKey` resolva a conexão pode dropar uma coleção |
+| Retorno | `200` body null |
+
+### 4.10 `GET /v3/database/collections`
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Listar nomes de coleções do banco da gamificação (`findCollectionNames()`) |
+| ⚠️ Scope | **NÃO verifica o scope `database`** |
+| Retorno | `200` com array de strings |
+
+### 4.11 `GET /v3/database/count`
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Contar documentos (`count()`) |
+| Validação | scope `database` E `collection > 0` |
+| Retorno | `200` com `{"total": N}` |
+
+**Query params:** `collection` (nome) e `q` (inserido cru em `{ <q> }`).
+
+### 4.12 Índices (tenant)
+
+- `GET /v3/database/{collection}/index` — `getDBCollection().getIndexInfo()`.
+- `POST /v3/database/{collection}/index` — body `Map<campo, direção>` (`{"fuel": 1}`); cria um índice por chave; retorna os índices.
+- `DELETE /v3/database/{collection}/index/{id}` — `dropIndex(id)` pelo nome do índice.
+
+Todos exigem scope `database` e `collection > 0`.
+
+### 4.13 Fila assíncrona
+
+- `GET /v3/database/queue/info` — `getQueueInfo()`.
+- `DELETE /v3/database/queue/clear` — `clearQueue()` (descarta tasks pendentes).
+- `DELETE /v3/database/queue/info` — `clearQueueInfo()` (zera contadores de duração).
+
+> ⚠️ Os três endpoints de fila **não verificam scope** — apenas resolvem o `ManagerFactory` pelo `apiKey`.
+
+### 4.14 System API (`/v3/system/database`)
+
+Opera sobre o **banco de sistema** (`SystemFactory.getInstance().getJongoConnection()`), não o tenant. Autorização por **permissão de sistema**: `checkPermission` → `authBean.checkSystemPermission("api", "/system/database", <operation>)`; se falhar, lança `FunifierRuntimeException` → **401 UNAUTHORIZED** (diferente do silêncio do tenant).
+
+| Endpoint | Método | Operation | Validação |
+|---|---|---|---|
+| `/v3/system/database/{collection}/index` | GET | `read` | `collection > 3` |
+| `/v3/system/database/{collection}/index` | POST | `create` | `collection > 3` |
+| `/v3/system/database/{collection}/index/{id}` | DELETE | `delete` | `collection > 3` |
+| `/v3/system/database/collections` | GET | `read` | — (sem checagem de tamanho) |
+
+> **Assimetria:** o `/v3/system/database/collections` exige permissão de sistema `read`; já o `/v3/database/collections` (tenant) **não exige nada**.
+
+---
+
+## 5. Regras de Negócio
+
+### 5.1 Guarda de scope por substring
+
+A verificação é `getScope().indexOf("database") != -1` — **match de substring**, não de token. Um scope literal como `my_database_tool` satisfaz a guarda de `database`. O scope vem de: app config (Basic), role `public` (Basic só com apiKey), ou claim `scope` do JWT (Bearer). Ausência do scope **não gera erro** — gera resposta vazia (exceto onde não há checagem: `drop`, `collections`, `queue/*`).
+
+### 5.2 Validação de tamanho mínimo da coleção (por endpoint)
+
+| Endpoint | Mínimo de chars |
+|---|---|
+| `GET /{collection}/{id}` | `> 3` |
+| `GET /{collection}` | `> 0` |
+| `POST /{collection}` | `> 3` |
+| `PUT /{collection}` | `> 3` |
+| `POST /{collection}/bulk` | `> 3` |
+| `DELETE /{collection}` | `> 0` (e `q >= 3`) |
+| `POST /{collection}/aggregate` | `> 2` |
+| `POST /{collection}/aggregate_test` | `> 3` |
+| `DELETE /{collection}/drop` | `> 0` |
+| `POST/GET/DELETE .../index` | `> 0` |
+| System `.../index` | `> 3` |
+
+### 5.3 Proteção de senha do player ("SEGURANÇA BRADESCO")
+
+Em PUT e bulk, quando a coleção é `player` e o token **não** tem `read_encrypted_player_password`: o sistema lê o player atual e restaura `password` **se ele veio `null`/ausente** no objeto. Previne apagar a senha em updates parciais (o cliente normalmente lê o player sem ver a senha → vem `null`).
+
+**Armadilhas:**
+- Enviar `"password": ""` sobrescreve com vazio (a proteção só cobre `null`/ausente).
+- A proteção **não existe** no POST simples nem no GET — só PUT e bulk.
+
+### 5.4 Criptografia de campos (v4.0)
+
+Ativa quando **todas** as condições valem:
+1. `checkReadEncryptedValues()` → scope `read_encrypted_field_values` **ou** permissão de sistema `api/encrypted_field_values/read`.
+2. Existe `CryptObjectField` para a coleção (em `crypt_object_field`, banco tenant) com `fields` não vazio.
+3. Existe `CryptTenantSecret` com `status = "active"` (em `crypt_tenant_secret`, banco sistema).
+
+Aplica-se em **POST, PUT e GET por `_id`**. **Não** se aplica em GET list, aggregate nem aggregate_test.
+
+Algoritmo (`AesCrypt`): `AES/ECB/PKCS5Padding`, chave = `SHA-1(secret)` truncado a 16 bytes (**AES-128**), saída Base64. Campos endereçados por **JSONPath dot-notation**; cada path é lido como `String` — apenas valores string são efetivamente criptografados (numéricos/aninhados falham silenciosamente no read do JSONPath).
+
+> Mudanças em `CryptObjectField`/`CryptTenantSecret` (via `CryptManager`) **re-processam todos os documentos** das coleções afetadas de forma síncrona: adicionar campo → criptografa em todos; remover campo/entity → decripta; trocar secret → decripta com a antiga e re-criptografa com a nova. Operação potencialmente longa e sem transação.
+
+### 5.5 Propagação de triggers
+
+| Operação | Eventos | `player` repassado |
+|---|---|---|
+| POST | `before_create`, `after_create` | claim do token |
+| PUT | `before_update`, `after_update` | claim do token |
+| DELETE (1..20.000) | `before_delete`, `after_delete` (payload = lista de `_id`s) | `null` |
+| Bulk (por item) | `before_create`, `after_create` | `null` |
+| Bulk (lista) | `before_bulk`, `after_bulk` | `null` |
+
+### 5.6 Multi-tenant
+
+Cada gamificação tem seu próprio banco MongoDB. A conexão é resolvida por `FrontController.getInstance(authBean.getApiKey()).getManagerFactory().getJongoConnection()` — o `apiKey` define o banco. Não há acesso cross-tenant por esta API. O banco de sistema é separado e só acessível via `/v3/system/database`.
+
+### 5.7 Consistência
+
+Não há transação multi-documento. Bulk e aggregate-`out` gravam item a item; uma falha no meio deixa estado parcial. Triggers rodam de forma síncrona dentro do request (exceto bulk async).
+
+---
+
+## 6. Comportamentos Automáticos
+
+| Comportamento | Trigger | Impacto | Persistência |
+|---|---|---|---|
+| Geração de `_id` | POST/PUT/bulk sem `_id` | `_id` = `ObjectId().toString()` (24 hex) | Persiste |
+| Preservação de `password` | PUT/bulk em `player` sem scope de senha, campo `null`/ausente | Restaura senha atual do banco | Persiste |
+| Full replace | PUT | Campos ausentes no corpo são removidos | Persiste |
+| `$facet` de paginação | GET list e aggregate | Conta total na mesma query | Não persiste |
+| `{$project:{password:0}}` | aggregate em `player` sem scope de senha | Oculta senha (só em `/aggregate`, **não** em `aggregate_test`) | Não persiste |
+| `allowDiskUse(true)` | aggregate / aggregate_test | Permite passar do limite de RAM | Não persiste |
+| Drop de destino | aggregate com `out_operation=replace` | `drop()` da coleção `out` antes de gravar | Persiste |
+| Criação de índices nativos | startup do tenant (`ConnectionPool.createIndexes`) | Índices em ~20 coleções (player, action_log, achievement, etc.) | Persiste |
+| Sleep de 100ms | fila vazia no `DatabaseAsyncProcessor` | Latência até 100ms para bulk async | Não persiste |
+| Texto puro por falta de scope | POST/PUT sem `read_encrypted_field_values` em coleção criptografada | Grava em claro; leitura futura retorna `null` | Persiste (corrompido) |
+
+---
+
+## 7. Suportado vs NÃO Suportado
+
+### ✅ Suportado
+
+- CRUD por `_id` em qualquer coleção (tenant).
+- Listagem com filtro `q` (sintaxe Mongo) e paginação via header `Range`.
+- Aggregation Framework completo com `allowDiskUse(true)`.
+- Aggregation com saída em coleção customizada (`out` terminando em `__c`, `out_operation=replace`).
+- Bulk insert/upsert síncrono e assíncrono.
+- Gestão de índices (criar, listar, remover) no tenant e no sistema.
+- Drop de coleção; contagem; listagem de coleções.
+- Strict mode (tipos BSON preservados).
+- Criptografia AES-128 de campos por coleção (POST/PUT/GET-by-id).
+- Triggers em todas as escritas; audit em POST/PUT/DELETE.
+- `id=me` no GET-by-id (apenas Bearer com claim `player`).
+- Inspeção/índices do banco sistema via `/v3/system/database`.
+
+### ❌ NÃO Suportado / armadilhas
+
+- **`PUT /{collection}/operations`** (update com `$inc`/`$set`/multi/upsert) — **comentado no código**, inexistente em runtime.
+- **DELETE acima de 20.000 documentos** — **no-op silencioso** (não apaga nada; ver 2.4).
+- **Ordenação no GET list** — sem `$sort`; use `/aggregate`.
+- **Decriptação no GET list e no aggregate** — só GET-by-id decripta.
+- **Audit em bulk** — bulk não gera audit log.
+- **`player` real nas triggers de bulk/delete** — sempre `null`.
+- **Projeção `password:0` no `aggregate_test`** — ausente → vaza senha de `player`.
+- **Scope check em `drop`, `collections` (tenant) e `queue/*`** — inexistente.
+- **Validação de schema** — nenhuma; qualquer JSON é gravado.
+- **Transações multi-documento** — nenhuma.
+- **Capacidade de fila** — ilimitada; `remaining_capacity` é decorativo; sem persistência (perde na reinicialização).
+- **Criptografia de campos não-string** — JSONPath lê como `String`; números/objetos aninhados não são criptografados.
+- **Params estilo `_filter`/`_sort`/`_limit`** — não existem; ignorados se enviados.
+
+---
+
+## 8. Segurança e Permissões
+
+### 8.1 Autenticação e scopes
+
+| Scope / permissão | Constante | Efeito |
+|---|---|---|
+| `database` | `Application.SCOPE_DATABASE` | Habilita CRUD/aggregate/index/count (match por substring) |
+| `read_encrypted_field_values` | `Application.SCOPE_READ_CRYPTED` | Habilita criptografia/decriptação de campos (POST/PUT/GET-by-id) |
+| `read_encrypted_player_password` | `Application.SCOPE_READ_PLAYER_PASSWORD` | Desliga a proteção de senha e a projeção `password:0` |
+| `api/encrypted_field_values/read` (sistema) | — | Alternativa a `read_encrypted_field_values` |
+| `api/.../system/database` (sistema) | — | Necessário para a System API |
+
+### 8.2 Endpoints sem checagem de scope
+
+`DELETE /{collection}/drop`, `GET /collections` e os três `/queue/*` (tenant) **não verificam scope `database`**. Qualquer requisição cujo `apiKey` resolva a conexão pode dropar coleções, listar nomes de coleções e manipular a fila assíncrona. Mitigação atual: depende exclusivamente de o `apiKey`/conexão serem válidos.
+
+### 8.3 Injeção de query (NoSQL)
+
+O parâmetro `q` é concatenado **cru** na query Mongo, sem sanitização:
+
+```java
+// GET list:        s.append("{ $match : {"); s.append(q); s.append("}}");
+// aggregate:       query.append("{ $match : { "); query.append(q); query.append("}}");
+// DELETE:          jongo.getCollection(collection).remove("{" + q + "}");
+// count:           total = log.count("{" + ft + "}");
 ```
 
-### Executar Agregações
-**Método:** POST
-**Endpoint:** `/v3/database/:collection/aggregate`
-**Query Params:**
-- `q` — Filtro `$match` inicial (opcional, aplicado antes do pipeline)
-- `strict=true` — Preserva tipos BSON
-- `out` — Coleção destino para gravar resultados (deve terminar em `__c`)
-- `out_operation=replace` — Limpa coleção destino antes de gravar
+Um token com scope `database` pode montar qualquer filtro/expressão Mongo (incluindo `$where`, varreduras totais, contorno de filtros esperados). A proteção é por autenticação/scope, **não** por sanitização. O nome da coleção também é livre (`{collection}` path param), permitindo atingir qualquer coleção do tenant.
+
+### 8.4 Criptografia
+
+`AES/ECB/PKCS5Padding` é **modo ECB**: determinístico, sem IV e sem autenticação (MAC). Ciphertexts iguais revelam plaintexts iguais e os campos são maleáveis. A chave deriva de `SHA-1(secret)[0:16]` (AES-128). Avalie isso ao classificar dados sensíveis armazenados via este módulo.
+
+### 8.5 Vazamento de senha por `aggregate_test`
+
+Como `aggregate_test` não aplica `{$project:{password:0}}`, um token só com `database` lê `player.password` por ele, mesmo sem `read_encrypted_player_password`. A proteção de senha do `/aggregate` é, portanto, contornável.
+
+---
 
-**Header:**
-- `Range: items=0-19` — Paginação
+## 9. Observabilidade e Troubleshooting
 
-**Descrição:** O `q` é aplicado como primeiro `$match`. Os estágios do body são adicionados em sequência após ele. Usa `allowDiskUse(true)` automaticamente.
+### 9.1 Diagnóstico básico
 
-**Exemplo — Query com filtro e ordenação:**
+```http
+GET /v3/database/collections          # lista coleções (não exige scope) — se vazio, conexão/tenant suspeitos
+GET /v3/database/queue/info           # estado da fila de bulk async
+GET /v3/database/{collection}/index   # índices de uma coleção
 ```
-POST /v3/database/body_checkin__c/aggregate?q=userId:"ricardo@funifier.com"&strict=true
-Range: items=0-19
 
-[
-  { "$sort": { "created": -1 } }
-]
+`/queue/info` saudável:
+
+```json
+{ "size": 0, "remaining_capacity": 2147483647, "last_process_duration_ms": 1234, "max_process_duration_ms": 5678 }
 ```
 
-**Exemplo — Agregação completa:**
+`size` crescente indica ingestão mais rápida que o processamento (ou thread travada). Lembre: `remaining_capacity` é sempre `2147483647` (fila ilimitada) — não use como sinal.
+
+### 9.2 Erros comuns
+
+| Sintoma | Causa provável |
+|---|---|
+| POST/PUT retorna 201 mas nada grava | Token sem scope `database` (substring) |
+| GET retorna `null` | Sem scope, ou coleção/`id` inválidos, ou `id=me` em token Basic |
+| GET list retorna `[]` com `q` complexo | Erro de query engolido por `getPageResult` |
+| Aggregate retorna 500 | Sintaxe de pipeline inválida (`getPageResultThrowsException`) |
+| **DELETE não apaga nada** | `q` < 3 chars, **ou filtro casa > 20.000 docs (no-op)**, ou nenhum match |
+| Bulk async: dados somem após restart | Fila em memória, sem persistência |
+| Campo criptografado vem `null` na leitura | Foi gravado em texto puro por token sem `read_encrypted_field_values`, ou secret trocada |
+| Senha do player apagada após PUT | Token com `read_encrypted_player_password` e `password` não enviado |
+
+### 9.3 Queries úteis (mongosh / via aggregate)
+
+```javascript
+// quantos documentos um DELETE tentaria apagar (cheque o limite de 20.000!)
+db.minha__c.countDocuments({ status: "active" })
+
+// ver índices reais de uma coleção
+db.player.getIndexes()
+
+// inspecionar se um campo está criptografado (valor Base64 vs claro)
+db.player.findOne({ _id: "p123" }, { email: 1 })
 ```
-POST /v3/database/action_log/aggregate?strict=true
 
+```http
+GET  /v3/database/count?collection=minha__c&q=status:"active"
+POST /v3/database/action_log/aggregate
 [
-  { "$match": { "actionId": "sell", "userId": "jerry" } },
-  { "$group": { "_id": "$userId", "total": { "$sum": "$attributes.price" } } },
-  { "$sort": { "total": -1 } },
-  { "$limit": 10 }
+  {"$match": {"userId": "player123", "time": {"$gte": 1700000000000}}},
+  {"$group": {"_id": "$actionId", "total": {"$sum": 1}}},
+  {"$sort": {"total": -1}}
 ]
 ```
 
-### Inserção em Massa (Bulk)
-**Método:** POST
-**Endpoint:** `/v3/database/:collection/bulk`
-**Query Params:**
-- `async=true` — Processamento assíncrono (para grandes volumes)
+### 9.4 O que verificar quando algo não funciona
+
+1. O token tem o scope correto? (`database`; e `read_encrypted_*` se aplicável)
+2. O nome da coleção respeita o tamanho mínimo do endpoint (ver 5.2)?
+3. No DELETE: o filtro casa **entre 1 e 20.000** documentos?
+4. Há `CryptObjectField` + `CryptTenantSecret` ativa coerentes com o que foi gravado?
+5. A fila async está drenando (`/queue/info`)?
+
+---
+
+## 10. Exemplos Práticos
+
+### 10.1 Mínimo — inserir em coleção customizada
+
+```http
+POST /v3/database/car__c
+Authorization: Bearer <token_com_scope_database>
+Content-Type: application/json
+
+{ "brand": "honda", "model": "civic", "year": 2023 }
+```
 
-**Exemplo de Body:**
 ```json
+{ "_id": "507f1f77bcf86cd799439011", "brand": "honda", "model": "civic", "year": 2023 }
+```
+
+### 10.2 Listagem paginada com filtro
+
+```http
+GET /v3/database/action_log?q=userId:"player123",actionId:"buy"
+Range: items=0-19
+Authorization: Bearer <token>
+```
+
+Retorna **19** documentos. Header de resposta:
+
+```
+Content-Range: items 0-19/47
+```
+
+(Para 20 documentos peça `items=0-20`. O segundo número é o tamanho da página, não o índice final.)
+
+### 10.3 Avançado — aggregate materializando relatório em `__c`
+
+```http
+POST /v3/database/action_log/aggregate?out=sales_summary__c&out_operation=replace&strict=true
+Range: items=0-9999
+Authorization: Bearer <token>
+
 [
-  { "_id": "car001", "year": 2010, "price": 60000, "name": "Honda Civic", "brand": "honda" },
-  { "_id": "car002", "year": 2012, "price": 70000, "name": "Toyota Corolla", "brand": "toyota" }
+  {"$match": {"actionId": "purchase", "time": {"$gte": 1704067200000}}},
+  {"$group": {"_id": {"player": "$userId"}, "total": {"$sum": "$attributes.amount"}, "count": {"$sum": 1}}},
+  {"$sort": {"total": -1}}
 ]
 ```
 
-### Drop Collection
-**Método:** DELETE
-**Endpoint:** `/v3/database/:collection/drop`
-**⚠️ CUIDADO:** Remove a coleção inteira!
+```json
+{ "total": 128, "out": "sales_summary__c" }
+```
+
+### 10.4 Bulk assíncrono
+
+```http
+POST /v3/database/product__c/bulk?async=true
+Authorization: Bearer <token>
 
-### Listar Índices
-**Método:** GET
-**Endpoint:** `/v3/database/:collection/index`
+[
+  {"_id": "prod001", "name": "Widget A", "price": 29.99},
+  {"_id": "prod002", "name": "Widget B", "price": 49.99}
+]
+```
 
-### Criar Índice
-**Método:** POST
-**Endpoint:** `/v3/database/:collection/index`
+Resposta imediata:
 
-**Exemplo de Body:**
 ```json
-{ "fuel": 1 }
+{ "total": 2 }
 ```
 
-### Excluir Índice
-**Método:** DELETE
-**Endpoint:** `/v3/database/:collection/index/:index_name`
+Depois acompanhe `GET /v3/database/queue/info`. Reenviar o mesmo `_id` faz **upsert** (sobrescreve), não erro.
 
-## Paginação
+### 10.5 Anti-patterns
 
-Usa header `Range` no padrão HTTP Range:
-```
-Range: items=0-9     (primeiros 10)
-Range: items=10-19   (próximos 10)
-Range: items=0-99    (primeiros 100)
+**NÃO FAÇA — PUT sem `_id` esperando atualizar:**
+
+```http
+PUT /v3/database/config__c
+{ "key": "max_players", "value": 100 }
 ```
 
-Resposta inclui header `Content-Range` com total de registros.
+Sem `_id`, cada PUT **cria** um documento novo (ObjectId gerado). Sempre inclua `_id` para atualizar.
 
-Default sem Range: retorna até 100 registros.
+**NÃO FAÇA — DELETE contando com filtro amplo:**
 
-## Strict Mode (BSON Types)
+```http
+DELETE /v3/database/logs__c?q=ttl:1
+```
 
-Quando `strict=true`:
-- **Datas** são retornadas como `{ "$date": "2026-03-06T10:00:00.000Z" }` (ISO-8601)
-- **Sem strict**, datas podem vir como timestamps numéricos ou strings
+Se o filtro casar **mais de 20.000** documentos, **nada é apagado** (no-op silencioso, 200). Apague em lotes (`q` que limite a ≤ 20.000 por chamada) ou use `drop` se a coleção inteira puder ir embora.
 
-Para **gravar** datas tipadas, enviar como:
-```json
-{ "created": { "$date": "2026-03-06T10:00:00.000Z" } }
+**NÃO FAÇA — ler dados sensíveis por GET list ou aggregate esperando decriptação:**
+
+```http
+GET /v3/database/player?q=email:"user@example.com"
 ```
 
-> **Regra:** Sempre use `strict=true` em GETs para preservar tipos BSON. Sem ele, datas viram strings/números e quebram queries.
+GET list e aggregate **não decriptam**. Use `GET /v3/database/player/{id}` com `read_encrypted_field_values`.
+
+**NÃO FAÇA — gravar em coleção criptografada com token sem `read_encrypted_field_values`:**
 
-## Criptografia de Campos (v4.0)
+O valor vai em **texto puro** e a leitura futura (com o scope) retorna `null`. Use sempre o mesmo nível de permissão para ler e gravar a mesma coleção.
 
-Se habilitada (Studio > Security > Field Encryption):
-- Campos marcados são criptografados no POST/PUT e descriptografados no GET
-- Requer token com permissão `readEncryptedValues`
-- Usa AES com chave secreta do tenant
+---
 
-## Validações e Testes
+## Checklist de Configuração
 
-- [ ] Listar coleções retorna resultado
-- [ ] CRUD funciona na coleção alvo
-- [ ] Filtro `q` funciona corretamente
-- [ ] Aggregate com `q` + pipeline retorna dados filtrados e ordenados
-- [ ] Bulk insert registra múltiplos itens
-- [ ] Índices são criados/removidos corretamente
-- [ ] `strict=true` preserva tipos BSON
+- [ ] Token tem o scope `database` (lembre: a checagem é por **substring**).
+- [ ] Coleções customizadas usam sufixo `__c`; `out` de aggregate **deve** terminar em `__c`.
+- [ ] DELETE: o filtro `q` tem ≥ 3 chars **e** casa **no máximo 20.000** documentos (acima disso é no-op).
+- [ ] Para preservar `password` em `player`: garanta o mesmo nível de permissão (`read_encrypted_player_password`) ao ler e gravar.
+- [ ] Para campos criptografados: ler **e** gravar com `read_encrypted_field_values`; `CryptObjectField` (tenant) e `CryptTenantSecret` ativa (sistema) coerentes.
+- [ ] `drop`, `collections` (tenant) e `queue/*` não checam scope — proteja esses tokens de clientes não confiáveis.
+- [ ] Para bulk grande: prefira `async=true` e monitore `/queue/info` (lembrando que a fila não persiste em restart).
+- [ ] Não dependa de `aggregate_test` para dados sensíveis — ele não oculta `password`.
+- [ ] Paginação: o segundo número do `Range`/`Content-Range` é a **quantidade**, não o índice final.