funifier-mcp 0.3.20 → 0.3.22

package/datasource-funifier-docs/knowledge/index.md

@@ -103,9 +103,11 @@ A Funifier funciona como um **backend de aplicações**. Independentemente do ti
 | Triggers | `guides/triggers-guide.md` | Guia completo de triggers | Referência de eventos, entidades, managers e exemplos de código Java |
 | Trigger Examples | `guides/trigger-examples.md` | Exemplos de produção de triggers | Código Groovy pronto para padrões reais: atualizar coleção relacionada, criar achievement, inicializar jogador, normalizar/rejeitar `__c`, processar lote, registrar ação via `track` |
 | Database Access | `guides/database-access.md` | Acesso ao banco de dados | Referência de acesso via API REST e via código Java (Jongo) |
+| Explain / Diagnóstico | `guides/explain-diagnostics.md` | Plano de consulta real (`explain`) do MongoDB | Diagnosticar query lenta / timeout de `DELETE`: obter `winningPlan`, `IXSCAN` vs `COLLSCAN`, `totalDocsExamined` via scheduler (`runCommand explain`), já que o endpoint REST só executa a query. Inclui alternativa `$indexStats`/`$collStats` sem scheduler |
 | Java Managers | `guides/java-managers.md` | Referência de managers Java | Métodos disponíveis em cada manager (PlayerManager, ActionManager, etc.) para uso em triggers, schedulers e public endpoints |
 | Java Entities | `guides/java-entities.md` | Referência de entidades Java | Campos e tipos dos objetos (Player, Achievement, ActionLog, etc.) e mapeamento para coleções MongoDB |
 | Java Libraries | `guides/java-libraries.md` | Bibliotecas e utilitários Java | JsonUtil, Guid, DateUtil, Unirest, EmailBuilder, Jongo — métodos e exemplos de uso |
+| Server-side Utils | `guides/server-utils.md` | Classes utilitárias do pacote `com.funifier.engine.util` | CpfUtil, AesCrypt, BCrypt, PgpCrypt, OtpAuthUtil, DiffUtil, ExpressionUtils, MustacheUtils, StringUtil, FormatterUtil, ParserUtil, HttpUtil, UrlUtil, ExcelUtil, PaginationUtil, FileUtil — use quando precisar validar CPF, criptografar campo, renderizar template, comparar objetos, gerar Excel ou fazer HTTP em código server-side |
 | Permission Audit | `guides/permission-audit.md` | Auditoria de permissões de API | Cross-check código↔Funifier: manifest de chamadas → missing scopes, excess tokens, danger findings; gramática de scope (SecurityFilter), keyword `database`, auth context, remediação |
 
 ---
@@ -123,4 +125,6 @@ Para **relatórios e queries avançadas**, consulte `guides/aggregates.md` — d
 
 Para **lógica customizada com código**, consulte `guides/triggers-guide.md` (conceitos e referência de eventos) e `guides/trigger-examples.md` (exemplos Groovy prontos), além de `guides/database-access.md`.
 
+Para **diagnosticar queries lentas ou timeout de `DELETE`** (ver se bate no índice), consulte `guides/explain-diagnostics.md` — obtém o plano real (`explain`) do MongoDB via scheduler, já que o endpoint REST só executa a query.
+
 Para **referência completa de recursos Java** (managers, entidades, bibliotecas), consulte `guides/java-managers.md`, `guides/java-entities.md` e `guides/java-libraries.md`.

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

@@ -137,6 +137,8 @@ flowchart TD
 
 > **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**.
 
+> **Segunda armadilha — TIMEOUT (independente do no-op):** mesmo **abaixo** de 20.000, o delete é **síncrono num único request HTTP** e faz **3 varreduras** na coleção (`count` → `distinct(_id)` materializando **todos** os ids em memória → `remove`). Casar **milhares** de docs (ex.: ~10.000) sobre campo **não indexado** estoura o **timeout do request**. → Apague em **lotes de 1.000 por chamada, sobre campo indexado** (o número 1.000 é a intenção original do comentário do código); particione o `q` (o DELETE não aceita `$limit`) e repita até zerar. Se houver delete-trigger/audit na coleção, o lote seguro cai abaixo de 1.000. Ver §5.6 e §10.
+
 #### Fluxograma — delete
 
 ```mermaid
@@ -507,8 +509,8 @@ Operam sobre o **banco de sistema** (`SystemFactory.getInstance()`), não o do t
 ### 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.6 Limite de delete (20.000) e timeout
+**Duas armadilhas independentes** (ver §2.4): filtro que casa **> 20.000** docs → **no-op silencioso** com 200 (comentário do código diz "1000", mas o valor real é 20.000); filtro que casa **milhares ≤ 20.000** → **timeout** (operação síncrona: 3 varreduras + materializa todos os ids num único request). Mitigação: apague em **lotes de 1.000 sobre campo indexado** (§10).
 
 ### 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.
@@ -562,6 +564,7 @@ Toda operação resolve `FrontController.getInstance(authBean.getApiKey()).getMa
 - **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).
+- **Delete de milhares de docs (≤ 20.000):** timeout HTTP — síncrono, 3 varreduras + materializa todos os ids num único request. Apague em lotes de 1.000 sobre campo indexado (§5.6, §10).
 - **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`).
@@ -625,6 +628,7 @@ GET /v3/database/cars__c/index                      # índices da coleção
 |---|---|---|
 | 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 |
+| DELETE dá timeout / 504 / conexão cai | Filtro casa milhares de docs (≤ 20.000): síncrono, 3 varreduras + materializa ids | Apague em lotes de 1.000 sobre campo indexado (§5.6, §10); se houver delete-trigger/audit, lotes menores |
 | 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) |
@@ -687,15 +691,16 @@ PUT /v3/database/products__c
 ```
 **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
+### 10.5 Anti-pattern — DELETE em volume sem fatiar
 ```
 DELETE /v3/database/logs__c?q=year:2022
 ```
-Se houver > 20.000 docs de 2022, retorna **200 sem deletar nada**. Cheque antes:
+**Duas armadilhas** (ver §2.4): se houver **> 20.000** docs de 2022, retorna **200 sem deletar nada** (no-op); se houver **milhares ≤ 20.000**, **dá timeout** (síncrono: 3 varreduras + materializa todos os ids num único request). Cheque antes e **fatie em lotes de ≤ 1.000 sobre campo indexado**:
 ```
-GET /v3/database/count?collection=logs__c&q=year:2022
+GET /v3/database/count?collection=logs__c&q=year:2022,month:1   # confirme ≤ 1.000
+DELETE /v3/database/logs__c?q=year:2022,month:1                 # repita por mês/dia até zerar
 ```
-Se > 20.000, fatie o filtro (ex.: `year:2022,month:{$lte:6}`) ou use `/drop` (com cautela — sem scope).
+O DELETE REST **não aceita `$limit`** — "lote" = montar `q` que case ≤ 1.000 por chamada (janelas de data, prefixos de `_id`) e repetir. O número 1.000 vem do comentário original do código. Filtre sempre por **campo indexado** (senão as 3 varreduras continuam O(coleção)). Se a coleção inteira pode ir embora → `/drop` (cautela: sem scope). Para volume massivo sem o timeout do REST, mova a deleção para **trigger/scheduler/public endpoint** (`remove` em laço server-side).
 
 ### 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.
@@ -708,7 +713,7 @@ Escrever em coleção com `crypt_object_field` configurado usando token **sem**
 - [ ] 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.
+- [ ] `GET /count` executado antes de DELETE: filtro casa **≤ 20.000** (acima = no-op) **e cada chamada ≤ 1.000 sobre campo indexado** (acima = risco de timeout — fatie em lotes; §10.5).
 - [ ] 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.

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

@@ -93,6 +93,16 @@ Síncrono. Idêntico ao POST exceto:
 
 **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.
 
+**Edição parcial segura (read-modify-write):** não existe merge — enviar `{_id, campoX}` para "mudar só o campoX" **apaga** todos os demais campos. Para editar um único campo de um documento existente, faça o ciclo completo:
+
+```
+1. query   → busque o documento por _id                (funifier_database action=query, query={"_id": "<id>"})
+2. edite   → altere o campo desejado no objeto retornado (mantendo todos os outros campos)
+3. update  → reenvie o DOCUMENTO COMPLETO               (funifier_database action=update, data=<doc inteiro>)
+```
+
+O agente é quem faz o read-modify-write, explicitamente — a tool `funifier_database action=update` não relê nem mescla. O mesmo vale para os módulos que usam `POST` como upsert (`player`, `point`, `level`, `mystery`): sempre reenvie o objeto completo.
+
 ### 2.4 Pipeline — `delete()` (DELETE por filtro)
 
 ```
@@ -113,6 +123,20 @@ Síncrono. Idêntico ao POST exceto:
 >
 > O comentário no código diz "menor que 1000", mas o limite real codificado é `<= 20_000`.
 
+> ⚠️ **TIMEOUT — segunda armadilha (independente do no-op):** mesmo **abaixo** de 20.000, o `delete()` é **síncrono e pesado num único request HTTP**. Para `1 ≤ total ≤ 20.000` ele faz, em sequência, **três varreduras na coleção** mais a materialização de **todos** os `_id`s casados em memória:
+>
+> | Passo | Operação | Custo |
+> |---|---|---|
+> | 1 | `count("{q}")` | varredura (scan #1) |
+> | 2 | `distinct("_id").query("{q}")` | varredura (scan #2) **+ materializa todos os N `_id`s** num `List<String>` |
+> | 3 | `executeStrict(before_delete, ids)` | itera sobre `ids` (O(1) só sem delete-trigger registrado) |
+> | 4 | `remove("{q}")` | varredura (scan #3) + N deleções |
+> | 5 | `execute(after_delete, ids)` + `auditManager.log(..., ids)` | itera sobre `ids` |
+>
+> Para N na casa dos **milhares** (ex.: ~10.000) sobre um campo de filtro **não indexado**, cada varredura é O(tamanho da coleção); a soma das três + materialização **estoura o timeout do request/gateway**. Ou seja, há **duas cliffs distintas**: `> 20.000` = **no-op silencioso** (correção); milhares `≤ 20.000` = **timeout** (performance). Mitigação: §10.5 (lotes de **1.000** sobre **campo indexado**).
+>
+> ⚠️ Se a coleção tiver **delete-trigger** registrado ou **audit** configurado, os passos 3/5 rodam **por `_id`** — o custo multiplica e o lote seguro cai abaixo de 1.000.
+
 #### Fluxo de exclusão — `delete()`
 
 ```mermaid
@@ -363,7 +387,7 @@ Diferenças do REST padrão: é **full replace** (campos ausentes somem); sem `_
 | 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`.
+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`. **E mesmo abaixo de 20.000**, casar **milhares** de docs faz a operação síncrona (count + distinct/materializa ids + remove = 3 varreduras) **estourar o timeout** — apague em **lotes de 1.000 sobre campo indexado** (§2.4, §10.5).
 
 ### 4.6 `POST /v3/database/{collection}/bulk`
 
@@ -576,6 +600,7 @@ Não há transação multi-documento. Bulk e aggregate-`out` gravam item a item;
 
 - **`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).
+- **DELETE de milhares de documentos (≤ 20.000)** — **timeout HTTP**: operação síncrona com 3 varreduras + materialização de todos os `_id`s num único request (ver 2.4). Apague em **lotes de 1.000 sobre campo indexado** (§10.5).
 - **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.
@@ -656,6 +681,7 @@ GET /v3/database/{collection}/index   # índices de uma coleção
 | 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 |
+| **DELETE dá timeout / 504 / conexão cai** | Filtro casa **milhares de docs (≤ 20.000)**: operação síncrona (3 varreduras + materializa ids) estoura o timeout. → Apague em **lotes de 1.000 sobre campo indexado** (§10.5); se houver delete-trigger/audit, lotes menores |
 | 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 |
@@ -663,7 +689,7 @@ GET /v3/database/{collection}/index   # índices de uma coleção
 ### 9.3 Queries úteis (mongosh / via aggregate)
 
 ```javascript
-// quantos documentos um DELETE tentaria apagar (cheque o limite de 20.000!)
+// quantos documentos um DELETE tentaria apagar (>20.000 = no-op; milhares = timeout — apague em lotes de 1.000)
 db.minha__c.countDocuments({ status: "active" })
 
 // ver índices reais de uma coleção
@@ -687,7 +713,7 @@ POST /v3/database/action_log/aggregate
 
 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?
+3. No DELETE: o filtro casa **entre 1 e 20.000** documentos (acima = no-op)? E **cada chamada** casa **≤ 1.000** sobre **campo indexado** (acima = risco de timeout)?
 4. Há `CryptObjectField` + `CryptTenantSecret` ativa coerentes com o que foi gravado?
 5. A fila async está drenando (`/queue/info`)?
 
@@ -780,7 +806,24 @@ Sem `_id`, cada PUT **cria** um documento novo (ObjectId gerado). Sempre inclua
 DELETE /v3/database/logs__c?q=ttl:1
 ```
 
-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.
+Um filtro amplo cai numa de **duas armadilhas** (ver §2.4):
+
+- **> 20.000 docs → no-op silencioso** (200, nada apagado).
+- **Milhares ≤ 20.000 → timeout HTTP**: o `delete()` é síncrono e faz 3 varreduras na coleção + materializa todos os `_id`s em memória, tudo num único request.
+
+**Apague em lotes de 1.000 documentos por chamada, sobre um campo de filtro indexado.** O número 1.000 vem do próprio comentário do código (`DatabaseRest.delete`: *"…se o número de registros for menor que 1000…"*) — é a intenção original de lote seguro, não um limite da plataforma; ajuste conforme a latência observada.
+
+> ⚠️ O `DELETE` REST **não aceita `$limit`/`max_results`** — não dá para "apagar 1.000 por vez" sem particionar o filtro. "Lote" aqui = montar `q` que **case ≤ 1.000** por chamada (janelas de data, prefixos de `_id`, faixas de uma chave) e **repetir** até zerar. Cada chamada deve filtrar por **campo indexado** — senão as 3 varreduras continuam O(coleção inteira) e o timeout volta.
+
+```http
+# ✅ Em lotes, por janela de tempo (campo `time` indexado), repetindo até zerar:
+GET    /v3/database/logs__c/count?q=ttl:1,time:{$lt:1704067200000}   # confirme ≤ 1.000
+DELETE /v3/database/logs__c?q=ttl:1,time:{$lt:1704067200000}
+```
+
+**Alternativas:**
+- Se a coleção **inteira** pode ir embora → `DELETE /v3/database/logs__c/drop` (uma operação, sem as 3 varreduras; ⚠️ não checa scope — §8.2).
+- Para exclusão massiva sem o timeout do REST → mova a deleção para **trigger/scheduler/public endpoint** (`manager.getJongoConnection().getCollection(...).remove(...)` em laço server-side, fora do request HTTP).
 
 **NÃO FAÇA — ler dados sensíveis por GET list ou aggregate esperando decriptação:**
 
@@ -800,7 +843,7 @@ O valor vai em **texto puro** e a leitura futura (com o scope) retorna `null`. U
 
 - [ ] 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).
+- [ ] DELETE: o filtro `q` tem ≥ 3 chars **e** casa **no máximo 20.000** documentos (acima disso é no-op) **e cada chamada casa ≤ 1.000 sobre campo indexado** (acima disso, risco de timeout — apague em lotes; §10.5).
 - [ ] 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.