funifier-mcp 0.2.26 → 0.2.27

package/datasource-funifier-docs/knowledge/guides/aggregates.md

@@ -1,96 +1,211 @@
 # Aggregates Funifier
 
-A plataforma Funifier utiliza o MongoDB como banco de dados, permitindo consultas avançadas por meio de **aggregates**. Esta funcionalidade é fundamental para extrair relatórios, gerar indicadores personalizados e construir dashboards.
+## 1. Visão Geral
 
-## Como Executar
+### 1.1 O que é este documento
 
-**Método:** POST
-**Endpoint:** `/v3/database/{collection}/aggregate`
-**Body:** Pipeline JSON com comandos aggregate
+Este documento descreve como executar pipelines de aggregate MongoDB na Funifier e a sintaxe das **expressões de data Funifier** — para relatórios, indicadores e rankings customizados. É o dono único das expressões de data.
 
-## Principais Coleções
+### 1.2 Quando consultar
 
-### player
-Jogadores da gamificação.
-```json
-{"_id": "john", "name": "John Travolta", "email": "john@funifier.com", "teams": ["sales"], "extra": {"country": "USA", "department": "IT"}, "created": {"$date": "2023-07-05T20:57:25.776Z"}}
-```
+- Consulte ao construir **relatórios/dashboards** (top N, médias, contagens) via `$group`/`$sort`.
+- Consulte ao precisar **juntar coleções** com `$lookup` (e por isso precisar das relações entre coleções).
+- Consulte ao precisar de **filtros por data relativa** (`-0M-`, `-1d+`) em queries ou código.
 
-### action
-Configurações dos tipos de ações.
-```json
-{"_id": "sell", "action": "Sell", "attributes": [{"name": "product", "type": "String"}, {"name": "price", "type": "Number"}], "active": true}
-```
+### 1.3 Quando NÃO consultar
 
-### action_log
-Ações executadas pelos jogadores. Campo `userId` → `player._id`. Campo `actionId` → `action._id`.
-```json
-{"_id": "64a5d92", "actionId": "sell", "userId": "john", "time": {"$date": "2023-07-05T20:57:33.303Z"}, "attributes": {"product": "book", "price": 120}}
-```
+- **NÃO** consulte para o **CRUD/mecânica geral** de `/v3/database` — use `datasource-funifier-docs/knowledge/guides/database-access.md`.
+- **NÃO** consulte para os **métodos Java de `DateUtil`** (`fromKeyword`, `add`, escalas) — use `java-libraries.md` §4. Aqui fica a *semântica* das expressões.
+- **NÃO** consulte para os **campos completos** das coleções — use `java-entities.md`. Aqui ficam só as relações relevantes a `$lookup`.
 
-### achievement
-Conquistas dos jogadores. Campo `type`: 0=Point, 1=Challenge, 2=Virtual Good, 3=Level. Campo `player` → `player._id`.
-```json
-{"_id": "64a5d2", "player": "john", "total": 25.0, "type": 0, "item": "xp", "time": {"$date": "2023-07-05T20:57:33.303Z"}}
-```
+### 1.4 Índice de decisão
 
-### challenge
-Desafios da gamificação.
-```json
-{"challenge": "Watch Video", "active": true, "_id": "DTo8dS3", "rules": [{"actionId": "watch_video", "operator": 5, "total": 0}], "points": [{"total": 10.0, "category": "xp", "operation": 0}]}
-```
+| Problema / Situação | O que fazer | Seção |
+|---|---|---|
+| Executar um pipeline | `POST /v3/database/:collection/aggregate` | §2 |
+| Saber qual campo liga duas coleções (`$lookup`) | Ver relações entre coleções | §3 |
+| Filtrar por "mês atual", "ontem", "este ano" | Expressões de data Funifier | §4 |
+| Saber quais operadores são aceitos | Ver operadores suportados | §5 |
+| Ver um pipeline pronto (top N, média, distintos) | Ver exemplos práticos | §6 |
 
-### point_category
-Tipos de pontos.
-```json
-{"_id": "xp", "category": "Experience Points", "shortName": "XP", "extra": {}}
+### 1.5 Restrições globais críticas
+
+> ⚠️ **O GET de listagem (`/v3/database`) não ordena.** Consequência de usar `_sort`: ignorado (`patterns.md` §1.5). → Para ordenar, use `$sort` num pipeline de aggregate.
+
+> ⚠️ **Em escrita/leitura tipada, use `strict=true` (`?strict=true` na URL do aggregate).** Consequência de omitir: `Date` degrada para número e o `$match` por data falha (`patterns.md` §9).
+
+> ⚠️ **`$` precisa de escape em código Groovy de Public Endpoint.** Consequência: operadores Mongo (`$match`, `$group`) quebram. → Ver o padrão de escape em `database-access.md` §3.
+
+### 1.6 Documentos relacionados
+
+> 📄 `datasource-funifier-docs/knowledge/guides/database-access.md` — mecânica de acesso e execução via API/Jongo
+> 📄 `datasource-funifier-docs/knowledge/guides/java-libraries.md` §4 — métodos Java de `DateUtil`
+> 📄 `datasource-funifier-docs/knowledge/guides/java-entities.md` — campos completos das coleções
+
+---
+
+## 2. Execução de Aggregate
+
+Quando usar: rodar um pipeline de agregação sobre uma coleção.
+Não usar quando: precisar só de um filtro simples → `GET ?q=` (`database-access.md` §2).
+Depende de: token autenticado com `database` no scope.
+Disponível em: API REST e código (Jongo).
+
+### Descrição
+
+Um aggregate aplica uma sequência de estágios (`$match`, `$group`, etc.) sobre os documentos de uma coleção e retorna o resultado transformado.
+
+### Uso
+
+**Via API REST:**
+```
+POST /v3/database/{collection}/aggregate?strict=true
+[
+  { "$match": { "player": "john", "type": 0, "item": "xp" } },
+  { "$group": { "_id": null, "totalXP": { "$sum": "$total" } } }
+]
+→ [{ "totalXP": 250 }]
 ```
 
-### catalog_item
-Itens da loja virtual.
-```json
-{"_id": "prd1", "catalogId": "gifts", "name": "T-shirt", "amount": 100, "active": true, "requires": [{"total": 15, "type": 0, "item": "coin", "operation": 1}]}
+**Via Jongo (código):** cada estágio é um argumento de `.and(...)`:
+```java
+Iterable<Map> result = database.getCollection("achievement")
+    .aggregate("{$match: {type: 0, item: 'xp'}}")
+    .and("{$group: {_id: '$player', total: {$sum: '$total'}}}")
+    .and("{$sort: {total: -1}}")
+    .and("{$limit: 10}")
+    .as(Map.class);
 ```
 
-## Expressões de Data (Funifier Syntax)
+### Armadilhas conhecidas
+
+- **Esperar ordenação do GET** → não ordena (§1.5). Correção: `$sort` no pipeline.
+- **Pipeline sem `strict=true` lendo datas** → `$match` por data falha (§1.5).
+
+---
+
+## 3. Coleções e Relações (para `$lookup`)
+
+Quando usar: ao escrever `$lookup` e precisar saber qual campo liga as coleções.
+Não usar quando: precisar de todos os campos da coleção → `java-entities.md`.
+Depende de: `java-entities.md` (campos completos).
+Disponível em: —
+
+### Descrição
+
+Relações que importam ao juntar coleções. Os exemplos mostram o documento mínimo; campos completos em `java-entities.md`.
 
-Formato: `[sinal][quantidade][unidade][ajuste opcional]`
+### Uso
+
+| Coleção | Relação-chave | Exemplo |
+|---|---|---|
+| `player` | `_id` é a ponta de `userId`/`player` | `{"_id":"john","name":"John","extra":{"department":"IT"}}` |
+| `action_log` | `userId` → `player._id`; `actionId` → `action._id` | `{"actionId":"sell","userId":"john","attributes":{"price":120}}` |
+| `achievement` | `player` → `player._id`; `item` → coleção do `type` | `{"player":"john","total":25.0,"type":0,"item":"xp"}` |
+| `challenge` | `_id` é referenciado por `achievement.item` (type 1) | `{"_id":"DTo8dS3","challenge":"Watch Video"}` |
+| `catalog_item` | `_id` é referenciado por `achievement.item` (type 2) | `{"_id":"prd1","name":"T-shirt"}` |
+| `point_category` | `_id` é referenciado por `achievement.item` (type 0) | `{"_id":"xp","category":"Experience Points"}` |
+
+> `achievement.type`: `0`=Point, `1`=Challenge, `2`=Virtual Good, `3`=Level, `5`=Lottery, `9`=Competition (`java-entities.md` §3). O `item` aponta para a coleção correspondente ao `type`.
+
+### Armadilhas conhecidas
+
+- **`$lookup` com `localField` errado** → resultado vazio. Correção: conferir a relação acima (ex: em `achievement`, juntar por `player` e não `_id`).
+
+---
+
+## 4. Expressões de Data Funifier
+
+Quando usar: filtrar por períodos relativos ("mês atual", "ontem") em `$match` ou em código.
+Não usar quando: a data é absoluta e conhecida → use ISO-8601 (`{"$date": "2023-08-01T00:00:00.000Z"}`).
+Depende de: —
+Disponível em: filtros de aggregate (`{"$date": "..."}`) e `DateUtil.fromKeyword(...)` (`java-libraries.md` §4).
+
+### Descrição
+
+Sintaxe própria da Funifier para datas relativas, resolvida no servidor. Formato: `[sinal][quantidade][unidade][ajuste]`.
+
+- **Unidades:** `y`=ano, `M`=mês, `w`=semana, `d`=dia, `h`=hora, `m`=minuto, `s`=segundo
+- **Ajuste:** `-` = início da unidade (floor), `+` = fim da unidade (ceil), sem ajuste = instante exato
+
+### Uso
 
 | Expressão | Significado |
 |-----------|------------|
 | `-0d` | Agora |
 | `-0d-` | Início do dia atual (00:00:00) |
 | `-0d+` | Fim do dia atual (23:59:59) |
-| `-1d` | Exatamente um dia atrás |
-| `-1d-` | Início do dia anterior (00:00:00) |
-| `-1d+` | Fim do dia anterior (23:59:59) |
+| `-1d` | Exatamente 1 dia atrás |
+| `-1d-` | Início do dia anterior |
+| `-1d+` | Fim do dia anterior |
+| `+1d` | Exatamente 1 dia no futuro |
+| `+1d-` | Início do dia seguinte |
 | `-0w-` | Início da semana atual |
 | `-0w+` | Fim da semana atual |
-| `-1w` | Exatamente uma semana atrás |
-| `-0M-` | Início do mês atual |
-| `-0M+` | Fim do mês atual |
-| `-1M` | Exatamente um mês atrás |
-| `-1M-` | Início do mês anterior |
-| `-0y-` | Início do ano atual |
-| `-0y+` | Fim do ano atual |
+| `-1w` | Exatamente 1 semana atrás |
+| `-0M-` | Primeiro dia do mês (00:00:00) |
+| `-0M+` | Último dia do mês (23:59:59) |
+| `-1M` | Exatamente 1 mês atrás |
+| `-1M-` | Primeiro dia do mês anterior |
+| `-0y-` | 1 de janeiro do ano atual |
+| `-0y+` | 31 de dezembro do ano atual |
 
-**Unidades:** `m`=minuto, `h`=hora, `d`=dia, `w`=semana, `M`=mês, `y`=ano
+**Encadeamento com `|`** (ajustes e fuso):
+```
+-1d+|GMT+3            → fim do dia anterior no fuso GMT+3
+-0d-|+5h|+30m|GMT-3   → início do dia + 5h30m no fuso GMT-3
+```
 
-**Uso em filtros:**
+**Em filtro de aggregate:**
 ```json
-{"$date": "-0M-"}
+{ "$match": { "time": { "$gte": { "$date": "-0M-" }, "$lte": { "$date": "-0M+" } } } }
 ```
 
-## Operadores Suportados
+**Em código:** `DateUtil.fromKeyword("-0M-")` (`java-libraries.md` §4).
+
+### Armadilhas conhecidas
+
+- **Esquecer o ajuste** (`-0M` em vez de `-0M-`) → instante exato, não início do mês. Correção: incluir `-`/`+` conforme o limite desejado.
+- **`$gte` sem `$lte`** → janela aberta inclui o futuro. Correção: par `-0M-`/`-0M+`.
+
+---
+
+## 5. Operadores Suportados
+
+Quando usar: ao montar o pipeline.
+Não usar quando: —
+Depende de: —
+Disponível em: API REST e Jongo.
+
+### Descrição
+
+Operadores de pipeline aceitos.
+
+### Uso
 
 `$match`, `$group`, `$sort`, `$limit`, `$lookup`, `$project`, `$unwind`, `$addFields`, `$count`
 
-## Exemplos Práticos
+### Armadilhas conhecidas
+
+- **Usar operador fora desta lista** → pode não ser suportado. Valide em homologação antes.
+
+---
+
+## 6. Exemplos Práticos
+
+Quando usar: como ponto de partida para relatórios comuns.
+Não usar quando: a necessidade é um CRUD simples → `database-access.md`.
+Depende de: §3 (relações) e §4 (datas).
+Disponível em: API REST.
 
-### Exemplo 1: Top 10 jogadores com mais pontos XP no mês atual
+### Descrição
 
+Pipelines prontos para os relatórios mais frequentes.
+
+### Uso
+
+**Top 10 jogadores com mais XP no mês atual** (`POST /v3/database/achievement/aggregate`):
 ```json
-// POST /v3/database/achievement/aggregate
 [
   {"$match": {"type": 0, "item": "xp", "time": {"$gte": {"$date": "-0M-"}, "$lte": {"$date": "-0M+"}}}},
   {"$group": {"_id": "$player", "total": {"$sum": "$total"}}},
@@ -102,10 +217,8 @@ Formato: `[sinal][quantidade][unidade][ajuste opcional]`
 ]
 ```
 
-### Exemplo 2: Quantos jogadores distintos completaram um desafio
-
+**Jogadores distintos que completaram um desafio:**
 ```json
-// POST /v3/database/achievement/aggregate
 [
   {"$match": {"type": 1, "item": "DTo8dS3"}},
   {"$group": {"_id": "$player", "challenge": {"$first": "$item"}}},
@@ -115,20 +228,16 @@ Formato: `[sinal][quantidade][unidade][ajuste opcional]`
 ]
 ```
 
-### Exemplo 3: Média de pontos XP por jogador em um mês específico
-
+**Média de XP por jogador em mês específico:**
 ```json
-// POST /v3/database/achievement/aggregate
 [
   {"$match": {"type": 0, "item": "xp", "time": {"$gte": {"$date": "2023-08-01T00:00:00.000Z"}, "$lte": {"$date": "2023-08-31T23:59:59.999Z"}}}},
   {"$group": {"_id": "$player", "averageXP": {"$avg": "$total"}}}
 ]
 ```
 
-### Exemplo 4: Top 3 itens mais vendidos na loja virtual este ano
-
+**Top 3 itens mais vendidos este ano:**
 ```json
-// POST /v3/database/achievement/aggregate
 [
   {"$match": {"type": 2, "time": {"$gte": {"$date": "-0y-"}, "$lte": {"$date": "-0y+"}}}},
   {"$group": {"_id": "$item", "totalSold": {"$sum": "$total"}}},
@@ -139,10 +248,8 @@ Formato: `[sinal][quantidade][unidade][ajuste opcional]`
 ]
 ```
 
-### Exemplo 5: Jogadores que executaram ações ontem
-
+**Jogadores que executaram ações ontem** (`POST /v3/database/action_log/aggregate`):
 ```json
-// POST /v3/database/action_log/aggregate
 [
   {"$match": {"time": {"$gte": {"$date": "-1d-"}, "$lte": {"$date": "-1d+"}}}},
   {"$group": {"_id": "$userId"}},
@@ -150,3 +257,8 @@ Formato: `[sinal][quantidade][unidade][ajuste opcional]`
   {"$project": {"_id": 1, "playerName": {"$first": "$p.name"}}}
 ]
 ```
+
+### Armadilhas conhecidas
+
+- **`$lookup` em `achievement` por `_id`** → resultado vazio; junte por `$player`/`$item` conforme o caso (§3).
+- **`$project` esperando `$p.name` sem `$unwind`** → `$p` é array. Correção: `$unwind` ou `{"$first": "$p.name"}`.

package/datasource-funifier-docs/knowledge/guides/database-access.md

@@ -1,132 +1,218 @@
 # Acesso ao Banco de Dados Funifier
 
-A plataforma Funifier oferece duas formas principais de acessar e manipular os dados da gamificação:
+## 1. Visão Geral
 
-1. **Via API REST** — endpoint `/v3/database`
-2. **Via código Java** — objeto `manager` em triggers, schedulers e public endpoints
+### 1.1 O que é este documento
 
-Ambas utilizam **MongoDB** como banco de dados.
+Este documento descreve as duas formas de acessar o MongoDB da Funifier — via API REST (`/v3/database`) e via código Java/Groovy (Jongo) — para operações CRUD, filtros e índices. É o dono único da mecânica de acesso ao banco.
+
+### 1.2 Quando consultar
+
+- Consulte ao **ler/escrever coleções** via API REST ou código.
+- Consulte ao precisar dos **placeholders seguros** (`#`) do Jongo.
+- Consulte ao **filtrar** uma listagem (`q`) ou gerir **índices**.
+- Consulte ao escolher entre **`database.getCollection(...)`** (trigger) e **`manager.getJongoConnection()`** (scheduler/endpoint).
+
+### 1.3 Quando NÃO consultar
+
+- **NÃO** consulte para **pipelines de aggregate** (`$match`/`$group`/`$sort`) nem **expressões de data** — use `datasource-funifier-docs/knowledge/guides/aggregates.md`. Aqui fica só o endpoint/mecânica.
+- **NÃO** consulte para escrita de **entidades nativas** (`player`, `action`, etc.) — use o endpoint nativo (`patterns.md` §10); `/v3/database` é para coleções genéricas/`__c`.
+- **NÃO** consulte para **tipos BSON e strict mode em detalhe** — use `patterns.md` §9.
+
+### 1.4 Índice de decisão
+
+| Problema / Situação | O que fazer | Seção |
+|---|---|---|
+| Listar coleções existentes | `GET /v3/database/collections` | §2 |
+| CRUD numa coleção genérica/`__c` | `/v3/database/:collection` | §2 |
+| Filtrar uma listagem | `?q=campo:"valor"` (não `_filter`) | §2 |
+| Ordenar resultados | `POST .../aggregate` com `$sort` (o GET não ordena) | §2 → `aggregates.md` |
+| Ler/escrever em código (trigger) | `database.getCollection(...)` | §3 |
+| Ler/escrever em código (scheduler/endpoint) | `manager.getJongoConnection()...` | §3 |
+| Evitar injeção em query | placeholder `#` | §4 |
+| Criar/listar/excluir índice | `/v3/database/:collection/index` | §5 |
+
+### 1.5 Restrições globais críticas
+
+> ⚠️ **O parâmetro de filtro é `q` (sintaxe Mongo), não `_filter`.** Consequência: `_filter`/`_sort`/`_limit` são **silenciosamente ignorados** e a query retorna todos os registros (`patterns.md` §1.5, `modules/database.md` §4.2). → Use `?q=campo:"valor"&strict=true`. Para ordenar, use `POST .../aggregate` com `$sort`.
+
+> ⚠️ **`PUT /v3/database/:collection` é replace total.** Consequência: campos não enviados são apagados. → Envie o objeto completo (read-merge-write).
+
+> ⚠️ **`POST /v3/database/:collection` (sem `/aggregate`) cria um documento.** Consequência de enviar um filtro esperando busca: cria lixo na coleção (`patterns.md` §10). → Para filtrar, use `GET ?q=`; para pipeline, `POST .../aggregate`.
+
+> ⚠️ **Nunca use `/v3/database/player`.** `player` é entidade nativa; `GET` dá 404 e `PUT` faz replace perdendo campos (`patterns.md` §10). → Use `/v3/player`.
+
+> ⚠️ **Use `strict=true` em todo GET/escrita de campos tipados.** Consequência de omitir: `Date` é lido como número e regravado com tipo errado, quebrando queries por data (`patterns.md` §9).
+
+### 1.6 Documentos relacionados
+
+> 📄 `datasource-funifier-docs/knowledge/guides/aggregates.md` — pipelines de aggregate e expressões de data
+> 📄 `datasource-funifier-docs/knowledge/guides/java-libraries.md` §Jongo — ponteiro para este documento
+> 📄 `datasource-funifier-docs/knowledge/modules/patterns.md` §9–§10 — strict mode, `q` vs `_filter`, Player nativo
 
 ---
 
-## 1. Acesso via API — Endpoint `/v3/database`
+## 2. Acesso via API REST (`/v3/database`)
+
+Quando usar: ler/escrever coleções genéricas ou `__c` a partir do frontend ou de integrações.
+Não usar quando: a coleção é uma entidade nativa (use o endpoint nativo) ou precisa de pipeline (use aggregate).
+Depende de: token de autenticação com `database` no scope (`modules/security.md`).
+Disponível em: API REST (cliente HTTP autenticado).
 
-### 1.1 Listar Coleções Disponíveis
+### Descrição
 
-**Método:** GET
-**Endpoint:** `/v3/database/collections`
+CRUD genérico sobre qualquer coleção via REST. Todas as operações usam **MongoDB** por trás.
 
-**Resposta:**
-```json
-["player", "action_log", "achievement", "challenge", "car__c", "email__c"]
+### Uso
+
+**Listar coleções**
+```
+GET /v3/database/collections
+→ ["player", "action_log", "achievement", "car__c", "email__c"]
 ```
 
-### 1.2 Operações CRUD
+**CRUD**
 
-| Operação | Método | Endpoint | Descrição |
-|----------|--------|----------|-----------|
-| Create | POST | `/v3/database/:collection` | Cria um novo registro |
-| Read | GET | `/v3/database/:collection` | Lista registros da coleção |
-| Update | PUT | `/v3/database/:collection` | Atualiza registro existente (via `_id`) |
-| Delete | DELETE | `/v3/database/:collection?q=...` | Remove registros com filtro |
-| Bulk Insert | POST | `/v3/database/:collection/bulk` | Cria/atualiza múltiplos registros |
+| Operação | Método | Endpoint |
+|----------|--------|----------|
+| Create | POST | `/v3/database/:collection` |
+| Read (lista) | GET | `/v3/database/:collection?q=...&strict=true` |
+| Update | PUT | `/v3/database/:collection` (objeto completo) |
+| Delete | DELETE | `/v3/database/:collection?q=...` |
+| Bulk | POST | `/v3/database/:collection/bulk` |
 
-**Exemplo — Criar item na coleção `car__c`:**
 ```
 POST /v3/database/car__c
+{ "_id": "car001", "name": "Civic", "brand": "Honda", "price": 50000 }
 ```
-```json
-{
-  "_id": "car001",
-  "name": "Civic",
-  "brand": "Honda",
-  "price": 50000
-}
+
+**Filtrar** (param `q`, sintaxe Mongo — ver §1.5):
 ```
+GET /v3/database/profile__c?strict=true&q=_id:'john'
+```
+> A resposta de um `q=_id:` é um **array** — normalize pegando `[0]` (`patterns.md` §10).
 
-### 1.3 Executar Aggregates
+**Aggregate** (mecânica aqui; pipelines em `aggregates.md`):
+```
+POST /v3/database/:collection/aggregate
+[ { "$match": { "type": 0 } }, { "$group": { "_id": null, "total": { "$sum": "$total" } } } ]
+```
 
-**Método:** POST
-**Endpoint:** `/v3/database/:collection/aggregate`
+### Armadilhas conhecidas
 
-**Body (pipeline JSON):**
-```json
-[
-  { "$match": { "player": "john", "type": 0, "item": "xp" } },
-  { "$group": { "_id": null, "totalXP": { "$sum": "$total" } } }
-]
-```
+- **`_filter`/`_sort`/`_limit`** → ignorados (§1.5). Correção: `q` + aggregate `$sort`.
+- **`PUT` parcial** → replace apaga campos (§1.5). Correção: objeto completo.
+- **`POST` esperando busca** → cria documento (§1.5). Correção: `GET ?q=`.
 
-**Resultado:**
-```json
-[{ "totalXP": 250 }]
-```
+---
 
-**Operadores suportados:** `$match`, `$group`, `$sort`, `$limit`, `$lookup`, `$project`, `$unwind`, `$addFields`, `$count`
+## 3. Acesso via Código (Jongo)
 
-### 1.4 Índices
+Quando usar: ler/escrever coleções dentro de trigger, scheduler ou public endpoint.
+Não usar quando: existir um manager para a operação → `java-managers.md`.
+Depende de: `database` (param do trigger) ou `manager.getJongoConnection()`.
+Disponível em: Todos (em Public Endpoint via `manager.getJongoConnection()` — `patterns.md` §6).
 
-| Operação | Método | Endpoint |
-|----------|--------|----------|
-| Listar | GET | `/v3/database/:collection/index` |
-| Criar | POST | `/v3/database/:collection/index` |
-| Excluir | DELETE | `/v3/database/:collection/index/:index_name` |
+### Descrição
 
-**Exemplo — Criar índice:**
-```json
-{ "fuel": 1 }
+Acesso direto ao MongoDB via driver Jongo. Em **triggers** use o param `database`; em **schedulers/public endpoints** (que não recebem `database`) use `manager.getJongoConnection()`. Ambos retornam o mesmo tipo de coleção.
+
+### Uso
+
+```java
+// --- Obter coleção ---
+database.getCollection("car__c");                          // em trigger
+manager.getJongoConnection().getCollection("car__c");      // em scheduler/endpoint
+
+// --- SAVE (insere ou atualiza se _id existir) ---
+database.getCollection("email__c").save(payload);
+
+// --- FIND ---
+Object one = database.getCollection("player").findOne("{_id: #}", "john").as(Map.class);
+Iterable<Object> many = database.getCollection("action_log").find("{userId: #}", "john").as(Object.class);
+
+// --- FIND com projeção ---
+Object proj = database.getCollection("player")
+    .findOne("{_id: #}", id).projection("{name: 1, email: 1}").as(Object.class);
+
+// --- COUNT ---
+long total = database.getCollection("action_log").count("{userId: #}", "john");
+
+// --- DELETE ---
+database.getCollection("car__c").remove("{_id: #}", "car001");
+
+// --- UPDATE (set parcial) ---
+manager.getJongoConnection().getCollection("player").update("{_id: #}", playerId).with(setCmd);
 ```
 
+> No Public Endpoint, escapar `$` de operadores Mongo (`patterns.md` §6):
+> ```groovy
+> def d = String.valueOf((char)0x24)
+> def setCmd = '{"' + d + 'set": {"extra.plan.type": "premium"}}'
+> ```
+
+Para **aggregate via Jongo**, ver `aggregates.md` (a sintaxe `.aggregate(...).and(...)` é detalhada lá).
+
+### Armadilhas conhecidas
+
+- **`manager.getJongoConnection()` esperado em trigger** → funciona, mas o param `database` é mais curto. Prefira `database` em triggers.
+- **`update(...).with(...)` sem `$set`** → substitui o documento. Correção: usar `$set` para atualização parcial.
+
 ---
 
-## 2. Acesso via Código Java (Triggers, Schedulers, Public Endpoints)
+## 4. Placeholders e Segurança
 
-Módulos que executam código Java têm acesso ao objeto `manager`, que provê conexão direta com o MongoDB através do driver Jongo.
+Quando usar: sempre que a query envolver valores dinâmicos.
+Não usar quando: —
+Depende de: —
+Disponível em: Todos.
 
-### 2.1 Estrutura de Acesso
+### Descrição
 
-```java
-manager.getJongoConnection().getCollection("nome_da_colecao").operacao(...);
-```
+O Jongo usa `#` como placeholder posicional para parâmetros seguros, evitando injeção. Os valores substituem os `#` na ordem.
 
-### 2.2 Operações
+### Uso
 
-#### Salvar (Insert/Update)
 ```java
-manager.getJongoConnection()
-       .getCollection("email__c")
-       .save(payload);
-```
+// Um parâmetro
+database.getCollection("player").findOne("{_id: #}", playerId).as(Object.class);
 
-#### Buscar (Find)
-```java
-Object result = manager.getJongoConnection()
-                       .getCollection("player")
-                       .findOne("{_id: 'john'}")
-                       .as(Map.class);
+// Múltiplos parâmetros (ordem importa)
+database.getCollection("action_log")
+    .find("{userId: #, actionId: #}", "john", "sell").as(Object.class);
 ```
 
-#### Deletar
-```java
-manager.getJongoConnection()
-       .getCollection("car__c")
-       .remove("{_id: 'car001'}");
-```
+### Armadilhas conhecidas
 
-#### Aggregate
-```java
-Iterable<Map> resultado = manager.getJongoConnection()
-    .getCollection("action_log")
-    .aggregate("[{ $match: { item: 'xp' } }, { $group: { _id: '$player', total: { $sum: '$total' } } }]")
-    .as(Map.class);
-```
+- **Concatenar valores na string da query** → injeção. Correção: sempre `#` + argumento.
+- **Número de `#` ≠ número de argumentos** → erro de parsing. Correção: alinhar quantidade e ordem.
 
 ---
 
-## 3. Considerações de Segurança e Boas Práticas
+## 5. Índices
+
+Quando usar: otimizar consultas frequentes numa coleção.
+Não usar quando: a coleção é pequena ou a consulta é pontual.
+Depende de: token autenticado.
+Disponível em: API REST.
+
+### Descrição
+
+Gestão de índices via REST.
+
+### Uso
+
+| Operação | Método | Endpoint |
+|----------|--------|----------|
+| Listar | GET | `/v3/database/:collection/index` |
+| Criar | POST | `/v3/database/:collection/index` |
+| Excluir | DELETE | `/v3/database/:collection/index/:index_name` |
+
+```
+POST /v3/database/car__c/index
+{ "fuel": 1 }
+```
+
+### Armadilhas conhecidas
 
-- As operações via API devem ser protegidas por **token de autenticação**
-- Endpoints públicos não requerem token — usar com cautela
-- Manipulação direta do banco afeta dados em **tempo real**
-- Sempre testar em **ambiente de homologação** antes de aplicar em produção
-- Coleções customizadas usam sufixo `__c` (ex: `car__c`, `email__c`)
+- **Criar índice em ambiente de produção sob carga** → impacto momentâneo. Correção: validar em homologação primeiro (`modules/staging.md`).