funifier-mcp 0.2.26 → 0.2.27

package/datasource-funifier-docs/knowledge/modules/csv-data.md

@@ -1,30 +1,655 @@
-# CSV Data (Dados CSV)
+# `csv`
 
-**API Endpoint:** `/v3/csv`
+**API Base:** `/v3/csv`
+**Coleções MongoDB:** `csv_config__c` (configurações de formato/importação), `csv_log__c` (logs de execução), `csv_format__c` (órfã — ver §7)
+**Controller:** `com.funifier.rest.v3.rest.CsvRest`
+**Manager:** `com.funifier.engine.csv.CsvManager` (1981 linhas, sem Repository/Dao dedicado — acesso direto via Jongo)
 
-## O que é
+> Documentação produzida por engenharia reversa do código-fonte de `funifier-service`. Reflete o **comportamento real** das classes, não o schema declarado nem a documentação anterior.
 
-Importação e exportação de dados no formato CSV. Permite importar ou exportar dados de forma fácil e segura, seja via upload manual ou FTP. Suporta arquivos criptografados para segurança no trânsito das informações.
+---
 
-## Quando usar
+## 1. Visão Geral
 
-- Para importar listas de jogadores em massa
-- Para exportar relatórios de desempenho
-- Para migrar dados de sistemas externos
-- Para importação segura via FTP com criptografia
+O módulo `csv` é o **motor de importação e exportação em massa** da plataforma. Ele converte arquivos CSV (texto plano ou upload multipart) em documentos MongoDB e converte resultados de aggregations MongoDB de volta em CSV/Excel.
 
-## API Endpoints
+Papel arquitetural — o módulo abriga **dois subsistemas de importação independentes**, que compartilham apenas utilitários de parsing:
 
-### Importar CSV
-**Método:** POST
-**Endpoint:** `/v3/csv`
+1. **Import como `action_log`** (`POST /v3/csv/import` → `importActionLogRows`): orientado por um documento `csv_config__c` que define mapeamento de colunas (`match`), uma `action` alvo e um script Groovy opcional. Cada linha vira um `ActionLog` rastreado via `ActionManager.trackWithRestrictions`. **Síncrono**, parser ingênuo.
 
-### Exportar CSV
-**Método:** GET
-**Endpoint:** `/v3/csv`
+2. **Bulk/merge em coleção arbitrária** (`POST /v3/csv/{collection}/bulk` e `/merge` → `insertBulk`/`mergeBulk`): orientado pela lista `fields[]` do `csv_config__c` (tipagem de campos). Persiste documentos em **qualquer** coleção nomeada na URL. **Assíncrono por padrão**, processado em lotes, cancelável, com triggers. Usa parser Apache Commons CSV.
 
-## Validações e Testes
+Além disso oferece:
 
-- [ ] Importação processa arquivo corretamente
-- [ ] Dados importados aparecem nas coleções corretas
-- [ ] Exportação gera arquivo CSV válido
+- **Exportação** (`POST /v3/csv/{collection}/aggregate` e `/aggregate/to_excel`): executa um pipeline de aggregation arbitrário sobre uma coleção e devolve CSV (`text/plain`) ou planilha `.xls` (`application/octet-stream`).
+- **Parsing/preview** (`/read`, `/split`, `/split/file`): converte CSV em linhas JSON sem persistir.
+- **Descriptografia PGP** de uploads (campo `upload_encrypted` no config + `CryptTransferKey`).
+
+Problemas que resolve: carga inicial de jogadores/times, ingestão recorrente de eventos como `action_log`, migração de sistemas externos, e geração de relatórios CSV/Excel a partir de aggregations.
+
+Relação com outros módulos:
+
+- `action` — `/import` chama `ActionManager.findActionById` (resolve a action e o tipo de cada atributo) e `ActionManager.trackWithRestrictions`; bulk em `action_log` usa `ActionManager.track`.
+- `trigger` — bulk/merge dispara `csv_before_bulk`/`csv_after_bulk`; saves em coleções comuns disparam `before_create`/`after_create`.
+- `crypt` — `CryptManager.findTransferKeyActive` + `decryptTransfer` (PGP) para uploads criptografados.
+- Qualquer coleção — bulk grava, e aggregate lê, **qualquer** coleção nomeada na URL (sem allowlist). Ver §8.
+
+> **Não há FTP.** A documentação anterior afirmava "importação via FTP" — não existe nenhum código de FTP no módulo. As únicas classes que referenciam `CsvManager` são `CsvRest`, `CsvAsyncProcessor` e `ManagerFactory`.
+
+---
+
+## 2. Arquitetura e Fluxos
+
+### 2.1 Classes envolvidas
+
+| Classe | Papel |
+|---|---|
+| `com.funifier.rest.v3.rest.CsvRest` | Controller REST v3 (`/v3/csv`) — 12 endpoints |
+| `com.funifier.engine.csv.CsvManager` | Manager monolítico: parsing, import, bulk, export, Groovy, criptografia |
+| `com.funifier.engine.csv.CsvAsyncProcessor` | `Runnable` de thread única que drena uma fila de jobs `insertBulk`/`mergeBulk` assíncronos |
+| `com.funifier.engine.csv.CsvConfig` | POJO da configuração (`csv_config__c`) — **modela só parte** do documento (ver §3.1) |
+| `com.funifier.engine.csv.CsvLog` | POJO do log de execução (`csv_log__c`) |
+
+### 2.2 Os dois parsers de CSV (divergência crítica)
+
+O módulo tem **dois parsers diferentes**, e o caminho escolhido depende do endpoint:
+
+| Aspecto | `readRows` (linha 278) | `splitCsv` (linha 945) |
+|---|---|---|
+| Usado por | `/read`, `/import` | `/split`, `/split/file`, todo bulk/merge (via `convertCsvInObjects`) |
+| Engine | `line.split(delimiter)` manual | Apache Commons CSV (`CSVParser`) |
+| Aspas / escape | **Não suporta** (split cego) | Suporta (`withQuote('"')`) |
+| Cabeçalho | Controlado por `header` (param/config) | **Sempre** `withFirstRecordAsHeader()` — `header` é ignorado |
+| Normalização do header | NFD → remove não-ASCII → remove não-`[0-9a-zA-Z_]` → `toLowerCase().trim()` | Nenhuma — usa o nome literal |
+| Delimitadores | `comma`, `semicolon`, `tab` (**sem pipe**) | `comma`, `semicolon`, `tab`, `pipe` |
+| Linha curta (menos colunas que o header) | **Descartada silenciosamente** (`fields.length >= names.length`) | Tratada pelo Commons CSV |
+
+> Consequência prática: `/import` e `/read` quebram com valores que contêm o delimitador entre aspas; bulk/merge não. E `pipe` só funciona em bulk/merge/split.
+
+### 2.3 Pipeline — `POST /v3/csv/import` (import como action_log)
+
+Método-raiz: `importActionLogRows(String id, String content)` (linha 119). **Sempre síncrono** — o query param `async` é aceito e **ignorado** (o caminho assíncrono está comentado em `CsvRest.java:69-78`).
+
+```
+[1] config = find(id)                         // lê csv_config__c[id]
+[2] cria CsvLog(collection="action_log", status="started")
+    if(config.log) insertLog()                // só persiste log se config.log == true
+[3] if(config.script.length > 10):
+        script = getScript(config); clazz = compile(script)   // Groovy sandbox (§2.6)
+[4] keys = config.match.keySet()
+    if(config.action) action = ActionManager.findActionById(config.action)
+[5] rows = readRows(config.delimiter, config.header, -1, content)   // parser ingênuo (§2.2)
+[6] para cada row:
+    [6.1] if(config.log && config.log_field): row[log_field] = importlog._id
+    [6.2] monta `match` (de→para):
+          para cada key em config.match:
+            coluna = config.match[key]         // valor do match = NOME da coluna CSV
+            val = row[coluna]
+            se action e attribute(key).type == "Number": val = Double.parseDouble(val)
+            // exceção de parse → engolida em `err`, a linha continua
+            match[key] = val
+    [6.3] if(clazz): executor(clazz, config, row, match)   // Groovy prepare(), timeout 5s
+    [6.4] if(config.action):
+            log = new ActionLog()
+            log.actionId = config.action
+            log.time     = match["time"]   (se Date)
+            log.userId   = match["userId"] (se String)
+            log.id       = match["_id"]    (se String)
+            match.remove("time"); match.remove("userId"); match.remove("_id")
+            log.attributes = match
+            ActionManager.trackWithRestrictions(log, null)
+[7] importlog.status="finished"; rows=totalrows
+    if(config.log) insertLog()
+    return { action, log, all (sempre vazio), err }
+```
+
+> Se `config.action` for nulo, **nada é persistido**: as linhas são lidas e o script roda, mas não há `ActionLog` criado. `/import` só sabe importar `action_log`.
+
+```mermaid
+flowchart LR
+  A[POST /v3/csv/import<br/>body = CSV] --> B[find csv_config__c]
+  B --> C[readRows<br/>parser ingenuo]
+  C --> D{para cada linha}
+  D --> E[match de->para<br/>via config.match]
+  E --> F{config.script?}
+  F -- sim --> G[Groovy prepare<br/>timeout 5s]
+  F -- nao --> H
+  G --> H{config.action?}
+  H -- sim --> I[ActionLog +<br/>trackWithRestrictions]
+  H -- nao --> J[nada persistido]
+  I --> K[CsvLog finished]
+  J --> K
+```
+
+### 2.4 Pipeline — `POST /v3/csv/{collection}/bulk` e `/merge`
+
+`insertBulk`/`mergeBulk` (linhas 613/647) criam o `CsvLog` (status `started`) e então:
+
+- `async=false` → executa `insertBulkSync` **na thread da requisição** (síncrono).
+- qualquer outro valor (inclusive ausente) → enfileira na fila de `CsvAsyncProcessor` (**assíncrono é o padrão**).
+
+> A fila do `CsvAsyncProcessor` é **única por instância de `CsvManager`**, drenada por **uma só thread** com poll de 1s. Imports assíncronos concorrentes da mesma gamificação são **serializados**.
+
+`insertBulkSync(collection, format, delimiter, csv, values, logId)` (linha 690):
+
+```
+[1] log = findLog(logId)
+[2] dispara trigger "csv_before_bulk" (context.extra["log"] = log)
+[3] modo merge: se csv vazio e values presente:
+       csv   = values["source"]
+       merge = getFieldsPathAndValue(values["upsert"])   // campos-folha do upsert
+[4] guard: log != null && collection.length > 3 && csv.length > 0
+[5] linhas = contagem total (para percent)
+[6] formats = reverseFormats(collection)   // infere tipos de UM doc amostra (findOne)
+            ⊕ getFormats(format)           // fields[] do csv_config__c[format] (override)
+    config  = find(format)
+[7] LOTE = 100 linhas por vez (o comentario "1000" esta desatualizado):
+      acumula linhas, re-prepende o cabecalho a cada lote;
+      a cada lote:
+        insertBulkSyncHelper(lote)
+        se findLog(logId).status == "canceled":
+            log.status = "canceled"; finaliza; RETURN
+        percent = (total*100)/linhas   // divisao inteira -> truncado
+        insertLog(log)
+[8] log.status = "finished"; percent = 100
+[9] dispara trigger "csv_after_bulk"     // só no caminho de sucesso
+```
+
+`insertBulkSyncHelper` (linha 828) por documento convertido:
+
+```
+- se nao tem _id -> _id = Guid.newShortGuid()
+- se collection == "action_log":
+      converte em ActionLog (time = now se nulo) -> ActionManager.track(a)
+- senao:
+      trigger before_create -> collection.save(object) -> trigger after_create
+      (exceptions -> e.printStackTrace(), NAO gravadas no CsvLog)
+```
+
+```mermaid
+flowchart LR
+  A[POST /{collection}/bulk] --> B[CsvLog started]
+  B --> C{async?}
+  C -- false --> D[insertBulkSync<br/>thread da request]
+  C -- padrao --> E[fila CsvAsyncProcessor<br/>1 thread]
+  E --> D
+  D --> F[trigger csv_before_bulk]
+  F --> G[lotes de 100 linhas]
+  G --> H[convertCsvInObjects<br/>Apache Commons CSV]
+  H --> I{collection == action_log?}
+  I -- sim --> J[ActionManager.track]
+  I -- nao --> K[before_create -> save -> after_create]
+  J --> L{status == canceled?}
+  K --> L
+  L -- sim --> M[CsvLog canceled<br/>RETURN]
+  L -- nao --> N[atualiza percent]
+  N --> G
+  G --> O[CsvLog finished]
+  O --> P[trigger csv_after_bulk]
+```
+
+### 2.5 Pipeline — exportação (`/aggregate`, `/aggregate/to_excel`)
+
+`aggregate` (linha 410) / `aggregateExcel` (linha 498):
+
+```
+[1] guard: collection != null && collection.length > 3
+[2] roda o pipeline (body = lista de stages) na coleção, com allowDiskUse(true)
+    se body vazio -> usa {$match:{}} (todos os documentos)
+[3] pagina via header Range (default offset 0, page 100) -> PaginationUtil
+[4] achata cada doc em pares path/valor (getFieldsPathAndValue)
+[5] formats = reverseFormats(collection) ⊕ getFormats(format)
+[6] convertObjectFieldsToSampleCsv(...) -> CSV (cabeçalho ordenado alfabeticamente)
+[7a] aggregate     -> devolve text/plain + header Content-Range
+[7b] aggregateExcel-> csvToExcel (Apache POI XSSF) -> arquivo .xls temporário
+                      delimitador FORÇADO para vírgula; nome da planilha = name|collection
+```
+
+### 2.6 Sandbox Groovy (`/import` com `config.script`)
+
+`getScript` (linha 1776) envolve `config.script` numa classe `FunifierCsv` com:
+
+- `@TimedInterrupt(value = 5L, unit = SECONDS)` — interrupção dura no bytecode.
+- Imports pré-carregados de entidades Funifier (`Player`, `Team`, `Achievement`, `ActionLog`, etc.) e utilitários (`JsonUtil`, `HttpUtil`, `DateUtil`...).
+- Injeção de `manager` (`ManagerFactory` completo) e `database` (`GameDao`).
+- `println(msg)` redirecionado para uma lista `output`.
+
+`compile` (linha 1872) usa `SecureASTCustomizer` com **whitelist de tokens** (operadores aritméticos, comparações, lógicos, colchetes) + `TriggerExpressionChecker`. `executor` (linha 1921) roda em `ExecutorService` de thread única com `future.get(5, SECONDS)`.
+
+**O script do usuário deve definir o método `prepare(config, row, match)`** — é o que `executor` invoca. Exceções de compilação/execução/timeout são adicionadas à lista `err` e **a linha continua sendo processada**.
+
+---
+
+## 3. Estrutura dos Objetos
+
+### 3.1 `csv_config__c` — documento de configuração
+
+Modelado **parcialmente** por `CsvConfig` (`@JsonIgnoreProperties(ignoreUnknown=true)`). O runtime lê campos adicionais direto do `HashMap` que **não existem no POJO**.
+
+| Campo | Tipo | Padrão | Usado em runtime | Descrição |
+|---|---|---|---|---|
+| `_id` | String | — | sim | Id do config; é o valor passado em `config=`/`format=` |
+| `delimiter` | String | `comma` | `/import` | `comma`/`semicolon`/`tab` (pipe **não** vale aqui) |
+| `header` | String | — | `/import` | `"true"` → primeira linha é cabeçalho (comparação textual com `"true"`) |
+| `action` | String | — | `/import` | Id da `action`; define o tipo de import como `action_log` |
+| `match` | Map | — | `/import` | de→para: **chave** = campo destino do ActionLog, **valor** = nome da coluna CSV |
+| `script` | String | — | `/import` | Corpo Groovy; só compila se `length > 10` |
+| `log` | boolean | `false` | ambos | Liga a gravação de `csv_log__c` e a injeção de `log_field` |
+| `log_field` | String | — | ambos | Nome do campo onde o `_id` do log é injetado em cada linha |
+| `title` | String | — | **não** | Declarado no POJO, nunca lido — rótulo de UI |
+| `sample` | Map | — | **não** | Declarado no POJO, nunca lido — preview de UI |
+
+**Campos lidos como HashMap cru (fora do POJO `CsvConfig`):**
+
+| Campo | Tipo | Lido por | Descrição |
+|---|---|---|---|
+| `fields` | Array de objetos | `getFormats` (linha 1088) | Definições de tipagem/cabeçalho para bulk/merge/export (ver §3.2) |
+| `upload_encrypted` | boolean (string-parseado) | `isEncrypted` (linha 1072) | Se `true`, uploads multipart são descriptografados via PGP |
+
+> **Não existe endpoint de CRUD para `csv_config__c` neste módulo.** Os documentos de config são criados pela API genérica de banco/custom object gravando na coleção `csv_config__c`. O endpoint `/format` grava em outra coleção (ver §7).
+
+### 3.2 `fields[]` — definição de formato (subentidade do config)
+
+Cada item do array `fields` descreve uma coluna para os fluxos de bulk/merge/export:
+
+| Chave | Tipo | Descrição |
+|---|---|---|
+| `path` | String | Caminho do campo no documento (`a.b`, `lista[0].x`) — usado para montar/ler o objeto |
+| `name` | String | Nome "amigável" no cabeçalho CSV; mapeado para/desde `path` por `getPathFromName`/`getNameFromPath` |
+| `type` | String | `string` (default), `integer`, `double`, `boolean`, `date` |
+| `format` | String | Padrão de data quando `type=date` (default `yyyy-MM-dd HH:mm:ss`) |
+| `default` | qualquer | Valor padrão aplicado quando a coluna está ausente/`null` (tipado conforme `type`) |
+
+Coerção de tipo (linhas 1281-1297): `integer`→`Integer.parseInt`, `double`→`Double.parseDouble`, `boolean`→`Boolean.parseBoolean`, `date`→`SimpleDateFormat.parse`. Falha de parse → `printStackTrace`, o campo daquela linha fica sem valor convertido.
+
+`reverseFormats` (linha 1025) **infere** tipos lendo **um único** documento amostra (`findOne`) da coleção destino; `getFormats` (definições explícitas do `fields[]`) **sobrescreve** a inferência.
+
+### 3.3 `csv_log__c` — log de execução
+
+POJO `CsvLog`. Persistido somente quando aplicável (import: só se `config.log`; bulk/merge: sempre).
+
+| Campo | Tipo | Descrição |
+|---|---|---|
+| `_id` | String | `Guid.shortTimeMillis()` — devolvido na resposta como `log` |
+| `config` | String | Id do config/format usado |
+| `collection` | String | Coleção destino (`action_log` no import) |
+| `status` | String | `started` → `finished` \| `canceled` |
+| `start` | Date | Início |
+| `finish` | Date | Fim (em sucesso ou cancelamento) |
+| `percent` | Double | Progresso 0–100, **truncado** (divisão inteira `total*100/linhas`) |
+| `rows` | long | Total de linhas processadas |
+| `extra` | Map | Campo livre (não preenchido pelo fluxo padrão) |
+
+Constantes: `STATUS_STARTED="started"`, `STATUS_CANCELED="canceled"`, `STATUS_FINISHED="finished"`. O status intermediário `"running"` aparece **comentado** no código e nunca é gravado.
+
+```mermaid
+stateDiagram-v2
+  [*] --> started: insertBulk / importActionLogRows
+  started --> finished: todos os lotes processados
+  started --> canceled: status set p/ "canceled" entre lotes
+  finished --> [*]
+  canceled --> [*]
+```
+
+---
+
+## 4. Endpoints
+
+Todos sob `/v3/csv`, autenticação **Bearer token** (`AuthBean`). Não há checagem de papel/permissão adicional no controller.
+
+### `POST /v3/csv/read`
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Faz preview/parse de um CSV em linhas JSON. **Não persiste.** |
+| Consumes | `text/plain` (CSV no corpo) |
+| Query | `delimiter` (`comma`/`semicolon`/`tab`), `header` (`true`/`false`), `rows` (limite de linhas; default −1 = todas) |
+| Parser | `readRows` (ingênuo, normaliza nomes de cabeçalho) |
+| Resposta | `201` com a lista de linhas (campos `field1..N` se sem cabeçalho) |
+
+### `POST /v3/csv/import`
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Importa linhas como `action_log` segundo o config |
+| Consumes | `text/plain` |
+| Query | `config` (= `_id` em `csv_config__c`), `async` (**aceito e ignorado**) |
+| Comportamento | Sempre síncrono; só persiste se `config.action` estiver setado; descriptografia **não** se aplica aqui |
+| Resposta | `201` com `{ action, log, all:[], err:[] }` |
+
+### `POST /v3/csv/format`
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Salva um objeto de formato — **grava em `csv_format__c`** (não em `csv_config__c`) |
+| Consumes | `application/json` |
+| Comportamento | Gera `_id` se ausente; salva como BSON tipado. **Coleção órfã** — nenhum fluxo de leitura a consulta (ver §7) |
+
+### `POST /v3/csv/{collection}/aggregate`
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Exporta o resultado de um pipeline de aggregation como CSV |
+| Consumes | `application/json` (lista de stages do pipeline) |
+| Query | `format` (config para `fields[]`), `delimiter` |
+| Header | `Range` (paginação; default page 100) |
+| Resposta | `text/plain` (CSV) + header `Content-Range` |
+
+### `POST /v3/csv/{collection}/aggregate/to_excel`
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Igual ao acima, mas devolve planilha `.xls` (Apache POI) |
+| Query | `format`, `name` (nome da planilha; default = nome da coleção) |
+| Comportamento | Delimitador **forçado** para vírgula; arquivo temporário gerado |
+| Resposta | `application/octet-stream` + `Content-Disposition: attachment; filename=<name>.xls` |
+
+### `POST /v3/csv/split`  /  `POST /v3/csv/split/file`
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Quebra o CSV em arrays de colunas (preview estruturado). Não persiste. |
+| Consumes | `text/plain` / `multipart/form-data` (parte `file`) |
+| Query | `format`, `delimiter`, `total` (linhas a processar), `encoding` (só na variante file) |
+| Comportamento | Usa `splitCsv` (Commons CSV); a variante `file` descriptografa se `upload_encrypted` |
+| Resposta | `201` com lista de linhas (primeira linha = cabeçalho) |
+
+### `POST /v3/csv/{collection}/bulk`  /  `POST /v3/csv/{collection}/bulk/file`
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Importa o CSV como documentos na coleção `{collection}` |
+| Consumes | `text/plain` / `multipart/form-data` (parte `file`) |
+| Query | `format` (config para `fields[]`), `delimiter`, `async`, `encoding` (só file) |
+| Padrão | **Assíncrono** (somente `async=false` é síncrono) |
+| Resposta | `201` com `{ config, log }` — use `log` para acompanhar via `/log/{log}` |
+
+### `POST /v3/csv/{collection}/merge`  /  `POST /v3/csv/{collection}/merge/file`
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Igual ao bulk, porém aplica campos constantes (`upsert`) a **todas** as linhas |
+| Consumes | `application/json` (`{ source, upsert }`) / `multipart/form-data` (parte `file` + parte `upsert`) |
+| Query | `format`, `delimiter`, `async`, `encoding` (só file) |
+| Comportamento | "merge" **não** é upsert de Mongo — ver §5. Na variante file, ausência da parte `upsert` → `400` |
+| Resposta | `201` com `{ config, log }` |
+
+### `GET /v3/csv/log/{log}`
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Consulta o status/progresso de uma importação |
+| Resposta | `200` com o documento `CsvLog` (`status`, `percent`, `rows`, `start`, `finish`) |
+
+**Exemplo — `/import` (request/response):**
+
+```
+POST /v3/csv/import?config=import_players
+Content-Type: text/plain
+
+userId;points;time
+user01;100;2026-05-20 10:00:00
+user02;250;2026-05-20 10:05:00
+```
+
+```json
+{
+  "action": { "_id": "import_action", "...": "..." },
+  "log": { "_id": "1716200000abc", "config": "import_players",
+           "status": "finished", "rows": 2, "collection": "action_log" },
+  "all": [],
+  "err": []
+}
+```
+
+**Exemplo — `/{collection}/bulk` (assíncrono):**
+
+```
+POST /v3/csv/player/bulk?format=player_format&delimiter=semicolon
+
+_id;name
+user01;Maria
+user02;João
+```
+
+```json
+{ "config": "player_format", "log": "1716200111xyz" }
+```
+
+---
+
+## 5. Regras de Negócio
+
+Regras presentes no código mas ausentes do schema:
+
+- **`match` é de→para invertido:** a **chave** do `match` é o campo destino do `ActionLog`; o **valor** é o nome da coluna CSV (`config.match.get(key)` → `row.get(valor)`). Errar essa ordem é a armadilha de configuração nº 1.
+- **Campos especiais do ActionLog:** `time`, `userId` e `_id` são **extraídos** de `match` para os campos próprios do `ActionLog` e **removidos** de `attributes`. `time` só é aceito se for `Date`; `userId`/`_id` só se forem `String`.
+- **Tipagem só com `action`:** a conversão de coluna para `Double` no import só ocorre quando há uma `action` e o atributo correspondente é do tipo `"Number"`. Sem action, tudo entra como string.
+- **`/import` só persiste com `action`:** sem `config.action`, nenhuma linha é gravada (vira leitura + script).
+- **"merge" = campos constantes, não upsert:** o objeto `upsert` é achatado em pares path/valor e aplicado a **cada** linha antes do `save`. Não há `$set`/upsert no Mongo — é `collection.save(object)` (substitui por `_id`, ou insere com `_id` novo).
+- **Validação de `upsert` assimétrica:** só a variante multipart (`/merge/file`) valida a presença de `upsert` e retorna `400` se faltar. Na variante JSON (`/merge`), `upsert` ausente não é validado no controller — falha mais tarde dentro de `insertBulkSync`.
+- **`collection.length > 3`:** bulk e aggregate ignoram silenciosamente coleções cujo nome tenha ≤ 3 caracteres (guard `collection.trim().length() > 3`).
+- **Lote fixo de 100:** bulk processa 100 linhas por lote, re-prependendo o cabeçalho a cada lote. O comentário do código menciona "1000" — está desatualizado.
+- **`header` ignorado em bulk:** o parser de bulk (`splitCsv`) sempre trata a primeira linha como cabeçalho, independentemente do config.
+- **Injeção de `log_field`:** com `config.log` ligado e `log_field` definido, o `_id` do log é injetado em todas as linhas (no import via `row`, no bulk via `merge`).
+- **Isolamento multi-tenant:** todo acesso usa `manager.getJongoConnection()`/`manager.getApiKey()` resolvido a partir do `apiKey` do token — a separação é por conexão de gamificação.
+- **Consistência eventual:** imports assíncronos retornam `201` imediatamente; o resultado real só existe quando `csv_log__c.status == finished`.
+
+---
+
+## 6. Comportamentos Automáticos
+
+| Comportamento | Trigger | Impacto | Persistência |
+|---|---|---|---|
+| Trigger `csv_before_bulk` | Início de `insertBulkSync` (bulk/merge) | Executa código de trigger custom com `log` no contexto | Depende do trigger |
+| Trigger `csv_after_bulk` | Fim de `insertBulkSync` **(só em sucesso)** | Idem; **não dispara** se cancelado | Depende do trigger |
+| Trigger `before_create`/`after_create` | Cada `save` em coleção ≠ `action_log` | Hooks por documento | Depende do trigger |
+| Rastreio de `action_log` | Linha cujo destino é `action_log` (bulk) ou `/import` | `ActionManager.track`/`trackWithRestrictions` — dispara toda a engine de gamificação (achievements, níveis, etc.) | Sim |
+| Geração de `_id` | Documento sem `_id` no bulk | `Guid.newShortGuid()` | Sim |
+| Injeção de `log_field` | `config.log` + `log_field` | Adiciona o id do log a cada linha | Sim |
+| Valores `default` | Coluna ausente/`null` com `default` no `fields[]` | Preenche o campo com o default tipado | Sim |
+| Coerção de tipo | `fields[].type` ∈ {integer,double,boolean,date} | Converte a string da coluna | Sim |
+| Descriptografia PGP | Upload multipart + `upload_encrypted=true` | `decryptTransfer` antes do parse | Não (em memória) |
+
+> Os nomes `csv_before_bulk`/`csv_after_bulk` são **literais de string** passados a `TriggerManager.execute` (não constantes em `Trigger.java`). `before_create`/`after_create` são `Trigger.EVENT_BEFORE_CREATE`/`EVENT_AFTER_CREATE`.
+
+---
+
+## 7. Suportado vs NÃO Suportado
+
+### ✅ Suportado
+
+- Import como `action_log` orientado por config (`match`, `action`, `script` Groovy, `log`).
+- Bulk/merge em **qualquer** coleção, síncrono ou assíncrono, em lotes, com cancelamento.
+- Exportação de aggregation para CSV e Excel (`.xls`), com paginação por `Range`.
+- Parsing/preview (`/read`, `/split`, `/split/file`).
+- Upload multipart com descriptografia PGP (`upload_encrypted` + `CryptTransferKey`).
+- Tipagem de campos (`integer`/`double`/`boolean`/`date`), valores default e campos aninhados/listas (`a.b`, `lista[0].x`).
+- Acompanhamento de progresso via `csv_log__c` e `GET /log/{log}`.
+- Cancelamento de import (alterando `csv_log__c.status` para `canceled`).
+
+### ❌ NÃO Suportado / Inconsistências confirmadas no código
+
+- **FTP** — não existe nenhum código de FTP no módulo (alegação da doc anterior é falsa).
+- **`POST /v3/csv/format` é um beco sem saída** — grava em `csv_format__c`, mas todo fluxo de leitura (`find`, `getFormats`, `isEncrypted`) usa `csv_config__c`. O que é salvo ali nunca é lido.
+- **Query param `async` em `/import`** — aceito e ignorado; o caminho assíncrono está comentado.
+- **`pipe` em `/read` e `/import`** — `readRows` só conhece `comma`/`semicolon`/`tab`.
+- **Aspas/escape em `/read` e `/import`** — `line.split` não trata aspas; valores com delimitador embutido quebram.
+- **`header` em bulk/merge** — ignorado; a primeira linha é sempre cabeçalho.
+- **Descriptografia em `/import`, `/read`, `/split`(texto), `/bulk`(texto), `/merge`(json)** — só os endpoints **multipart** chamam `getCsv`/`decryptTransfer`.
+- **Endpoint de CRUD de config** — inexistente neste módulo; configs são criados/atualizados pela API genérica de banco (ex.: `POST /v3/database/csv_config__c`).
+- **Endpoint de cancelamento** — inexistente; cancela-se via update direto em `csv_log__c`.
+- **Status `running`** — comentado no código; nunca é gravado.
+- **Campos `title` e `sample` do `CsvConfig`** — declarados, nunca lidos em runtime.
+- **`merge` como upsert do Mongo** — não é; é aplicação de campos constantes + `save`.
+- **Erros de `save` em bulk** — apenas `printStackTrace`, **não** refletidos no `CsvLog` nem na resposta.
+- **`converCsvInObjectsOld` / segundo `convertObjectFieldsToSampleCsv`** — código legado morto/comentado, mantido no arquivo.
+
+---
+
+## 8. Segurança e Permissões
+
+- **Autenticação:** Bearer token via `AuthBean`; resolução de tenant por `apiKey` em `FrontController.getInstance(apiKey)`. **Sem** checagem de papel/escopo no `CsvRest`.
+- **Isolamento multi-tenant:** por conexão Jongo da gamificação (`manager.getJongoConnection()`); chaves de criptografia filtradas por `gamification == apiKey`.
+- **Superfície de leitura arbitrária:** `/{collection}/aggregate` e `/aggregate/to_excel` executam um **pipeline de aggregation arbitrário** (corpo da requisição) sobre **qualquer** coleção (`collection.length > 3`). Um chamador autenticado pode ler qualquer coleção da gamificação, inclusive `$lookup` entre coleções. Não há allowlist de coleções nem de stages.
+- **Superfície de escrita arbitrária:** `/{collection}/bulk` e `/merge` gravam em **qualquer** coleção nomeada na URL, disparando `before_create`/`after_create`. Não há restrição de coleções destino.
+- **Execução de código (Groovy):** `/import` com `config.script` executa Groovy. Há sandbox (`SecureASTCustomizer` com whitelist de tokens + `TriggerExpressionChecker` + `@TimedInterrupt 5s`), mas o script recebe `manager` (ManagerFactory completo) e `database` (GameDao) — superfície ampla. A criação do config (que carrega o script) deve ser tratada como operação privilegiada.
+- **Criptografia em trânsito:** PGP assimétrico via `CryptTransferKey` (par publicKey/secretKey + passphrase, status `ACTIVE`). **Falha de descriptografia retorna `null`** → NPE no parser subsequente (falha silenciosa do ponto de vista do log).
+- **Concorrência:** a fila assíncrona é única por instância e drenada por uma única thread — sem isolamento entre jobs além da serialização.
+
+---
+
+## 9. Observabilidade e Troubleshooting
+
+**Diagnóstico — o módulo está funcionando?**
+
+```
+# status/progresso de uma importação
+GET /v3/csv/log/{log}
+
+# config existe e está completo?
+GET /v3/database/csv_config__c/{id}        # via API genérica de banco
+
+# os documentos chegaram na coleção destino?
+GET /v3/database/{collection}?q={...}
+```
+
+**Queries MongoDB úteis:**
+
+```js
+// imports presos em "started" (travados/cancelados sem finalizar)
+db.csv_log__c.find({ status: "started" })
+
+// últimos logs de uma coleção
+db.csv_log__c.find({ collection: "player" }).sort({ start: -1 })
+
+// cancelar um import assíncrono em andamento
+db.csv_log__c.updateOne({ _id: "<log>" }, { $set: { status: "canceled" } })
+```
+
+**Erros comuns e causas:**
+
+| Sintoma | Causa provável |
+|---|---|
+| `/import` retorna `log` mas nada é importado | `config.action` ausente — `/import` só grava `action_log` |
+| Linhas faltando após import | Parser ingênuo descartou linhas com menos colunas que o cabeçalho; ou valores com delimitador embutido sem suporte a aspas |
+| Colunas trocadas no import | `match` invertido (chave = destino, valor = coluna CSV) |
+| `pipe` não funciona em `/import` | `readRows` não suporta pipe; use bulk |
+| Datas viram string | `fields[].type` não é `date`, ou o `format` não bate com o valor |
+| Upload criptografado falha sem erro claro | Endpoint não-multipart (não descriptografa) ou `CryptTransferKey` ativo ausente → `null` → NPE |
+| Bulk "concluiu" mas faltam docs | Erros de `save` só vão para `printStackTrace`, não para o `CsvLog`; verifique os logs do servidor |
+| Formato salvo via `/format` não tem efeito | Vai para `csv_format__c` (órfã); use `csv_config__c` |
+| `percent` nunca chega a valores intermediários precisos | Divisão inteira trunca; só `100.0` é exato no fim |
+
+**O que verificar quando algo não funciona:**
+
+1. O `csv_config__c[id]` existe e tem `fields[]`/`match` corretos?
+2. O delimitador do arquivo bate com o `delimiter` enviado?
+3. Para bulk: a coleção destino existe e tem um doc amostra (afeta `reverseFormats`)?
+4. Para criptografia: existe `CryptTransferKey` com `status=ACTIVE` para a gamificação?
+5. Logs do servidor (`stdout`) — o módulo loga via `System.out.println` e `printStackTrace`.
+
+---
+
+## 10. Exemplos Práticos
+
+### Exemplo mínimo funcional — bulk de times (semicolon)
+
+Config `csv_config__c`:
+
+```json
+{
+  "_id": "team_format",
+  "fields": [
+    { "path": "_id",  "name": "id" },
+    { "path": "name", "name": "nome", "type": "string" }
+  ]
+}
+```
+
+Requisição:
+
+```
+POST /v3/csv/team/bulk?format=team_format&delimiter=semicolon&async=false
+
+id;nome
+rh;Recursos Humanos
+com;Equipe Comercial
+```
+
+→ cria dois documentos em `team` (`_id` = `rh`/`com`), síncrono.
+
+### Exemplo avançado — import de action_log com tipagem, script e log
+
+Config `csv_config__c`:
+
+```json
+{
+  "_id": "import_sales",
+  "delimiter": "semicolon",
+  "header": "true",
+  "action": "registrar_venda",
+  "match": {
+    "userId": "vendedor",
+    "time":   "data",
+    "valor":  "total"
+  },
+  "log": true,
+  "log_field": "import_ref",
+  "script": "void prepare(config, row, match){ if(match.valor == null){ match.valor = 0 } }"
+}
+```
+
+Requisição:
+
+```
+POST /v3/csv/import?config=import_sales
+Content-Type: text/plain
+
+vendedor;data;total
+user01;2026-05-20 10:00:00;1500.50
+user02;2026-05-20 11:00:00;980.00
+```
+
+→ cada linha vira um `ActionLog` da action `registrar_venda`, com `userId`/`time` extraídos, `valor` no `attributes`, `import_ref` = id do log, e o script garante `valor` não-nulo.
+
+### Exemplo de exportação — relatório CSV de pontos por jogador
+
+```
+POST /v3/csv/achievement/aggregate?delimiter=comma
+Content-Type: application/json
+Range: items=0-999
+
+[
+  { "$match": { "type": 0 } },
+  { "$group": { "_id": "$player", "total": { "$sum": "$total" } } },
+  { "$sort": { "total": -1 } }
+]
+```
+
+→ devolve `text/plain` CSV com cabeçalho `_id,total`.
+
+### Anti-pattern — o que NÃO fazer
+
+```jsonc
+// ERRADO: match com chave/valor invertidos
+{ "match": { "vendedor": "userId" } }   // grava o literal "userId" no campo "vendedor"
+
+// ERRADO: confiar em async para ter o resultado na resposta
+POST /v3/csv/player/bulk?format=f      // 201 imediato; dados ainda não existem
+
+// ERRADO: usar /format esperando configurar o import
+POST /v3/csv/format                    // vai para csv_format__c, nunca é lido
+
+// ERRADO: CSV com vírgula dentro do valor em /import
+//   "Silva, João" quebra (sem suporte a aspas no parser ingênuo)
+//   → use /bulk (Apache Commons CSV) ou troque o delimitador
+```
+
+---
+
+## Checklist de Configuração
+
+- [ ] `csv_config__c[id]` criado via API de banco (não existe endpoint dedicado).
+- [ ] `match` no sentido correto: **chave = campo destino**, **valor = coluna CSV**.
+- [ ] Para `/import`: `action` definida (sem ela, nada é gravado).
+- [ ] `delimiter` da requisição = delimitador real do arquivo.
+- [ ] `pipe` apenas em bulk/merge/split — nunca em `/read`/`/import`.
+- [ ] `fields[].type`/`format` corretos para datas e números (bulk/export).
+- [ ] Para bulk síncrono: passar `async=false` explicitamente (o padrão é assíncrono).
+- [ ] Para upload criptografado: usar endpoint **multipart** + `upload_encrypted=true` + `CryptTransferKey` ativo.
+- [ ] Acompanhar imports assíncronos por `GET /log/{log}` até `status=finished`.
+- [ ] Armadilha: erros de `save` em bulk **não** aparecem no `CsvLog` — conferir logs do servidor.
+- [ ] Armadilha: `header` é ignorado em bulk (1ª linha sempre é cabeçalho).
+- [ ] Armadilha: `merge` aplica campos constantes a todas as linhas — não é upsert de Mongo.