funifier-mcp 0.2.26 → 0.2.27

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

@@ -1,155 +1,528 @@
-# Upload (Upload)
+# `upload`
 
+**Acesso Studio:** sem rota/página dedicada no backend — o módulo é consumido via API REST (ex.: seletores de imagem/arquivo do Studio chamam `/v3/upload`).
 **API Endpoint:** `/v3/upload`
+**Coleção MongoDB:** `upload` (schemaless — mapeada para `HashMap.class` em `Entity.UPLOAD`, sem entidade tipada)
 
-## O que é
+> Engenharia reversa baseada exclusivamente no código-fonte de `funifier-service` (commit `830037e`). Classe principal: `com.funifier.rest.v3.rest.UploadRest` (605 linhas). Os exemplos de resposta no Javadoc da própria classe estão **desatualizados** (vide seção 7) — esta documentação descreve o comportamento real do runtime.
 
-Upload de arquivos para uso na gamificação. Permite enviar imagens, documentos e outros tipos de arquivos para utilização em avatares, desafios, recursos visuais ou qualquer outra funcionalidade.
+---
+
+## 1. Visão Geral
+
+O módulo `upload` é o ponto de entrada para **persistência de arquivos binários** (imagens, documentos, qualquer mídia) em armazenamento de objetos em nuvem, mantendo um **registro de metadados** de cada arquivo na coleção MongoDB `upload`.
+
+Papel arquitetural:
+
+- **Dois artefatos por upload**: (1) o arquivo físico enviado ao provedor de nuvem (S3 / Azure Blob / Google Cloud Storage) e (2) um documento de metadados na coleção `upload`. Os dois são gravados em sequência dentro do mesmo handler; não há transação entre eles.
+- **Abstração multi-cloud**: o provedor é escolhido em tempo de execução por `Configuration.getCloud()` (`"azure"`, `"google"`, ou qualquer outro valor → Amazon S3, que é o default). A escolha é **por servidor/configuração**, não por requisição.
+- **Multi-tenant por apiKey**: todo arquivo é armazenado sob o prefixo `games/{apiKey}/{session}`. O `apiKey` identifica a gamificação dona do arquivo e também determina qual banco MongoDB recebe o registro (`FrontController.getInstance(apiKey)`).
+- **Schemaless**: `Entity.UPLOAD` mapeia para `HashMap.class` — não existe POJO/entidade tipada. O documento gravado é exatamente o `Map` montado no handler. Não há validação de schema; qualquer campo dentro de `extra` é aceito e persistido verbatim.
+
+Problemas que resolve:
+
+- Upload de avatares, logos, capas, documentos e mídia genérica usada por outros módulos (player, catalog, challenge, etc.) através da URL pública retornada.
+- Geração automática de **thumbnails** e **transformações de imagem** (resize / mudança de formato) no endpoint `/image`.
+- Catálogo consultável dos arquivos enviados por gamificação (endpoint `GET /v3/upload`).
+
+Relação com outros módulos:
+
+- **`trigger`** — o endpoint `/file` dispara as triggers `before_create` e `after_create` da entidade `upload` (`Trigger.ENTITY_UPLOAD`). **O endpoint `/image` NÃO dispara triggers** (vide seção 6).
+- **`player`** — a URL retornada é tipicamente copiada para `Player.image` (`{ small, medium, original }`). Não há referência forte (FK); é apenas cópia de string de URL.
+- **AI (`AIRest`)** — o módulo de geração de imagens por IA (`AIRest.java:2234`) também grava na coleção `upload`: baixa a imagem da URL da OpenAI, reenvia via `S3Service.create(..., session="image")` e salva um documento `upload`. Esse caminho usa **S3 diretamente** (ignora `getCloud()`).
+- **`static`** — módulo distinto (coleção `static`); usa o mesmo `S3Service`/`StaticManager` mas **não** compartilha a coleção `upload`.
+
+---
+
+## 2. Arquitetura e Fluxos
+
+### 2.1 Classes envolvidas
+
+| Classe | Papel |
+|---|---|
+| `com.funifier.rest.v3.rest.UploadRest` | Controller REST v3 (`/v3/upload`) — todos os 5 endpoints |
+| `com.funifier.engine.aws.service.s3.S3Service` | Provedor **default** (Amazon S3) — `create` / `delete` / `deleteURL` |
+| `com.funifier.engine.cloud.azure.AzureService` | Provedor Azure Blob Storage (quando `cloud="azure"`) |
+| `com.funifier.engine.cloud.google.GoogleService` | Provedor Google Cloud Storage (quando `cloud="google"`) |
+| `com.funifier.controller.Configuration` | `getCloud()` resolve o provedor ativo |
+| `com.funifier.engine.guid.Guid` | `newShortGuid()` → `new org.bson.types.ObjectId().toString()` (hex de 24 chars) |
+| `com.funifier.engine.integration.trigger.Trigger` | Constantes `ENTITY_UPLOAD`, `EVENT_BEFORE_CREATE`, `EVENT_AFTER_CREATE` |
+| `com.funifier.rest.v3.AuthBean` | Resolução de credenciais (`getApiKey()`) |
+| `net.coobird.thumbnailator.Thumbnails` | Biblioteca de resize/conversão de imagem (endpoint `/image`) |
+
+Não há `Service`/`Repository`/`Manager`/`Scheduler` dedicado ao módulo `upload`. A persistência MongoDB é feita diretamente via Jongo: `manager.getJongoConnection().getCollection(Entity.UPLOAD.collection)`.
+
+### 2.2 Pipeline principal — `POST /v3/upload/file` (`uploadFile`)
+
+Sequência real de execução (linhas 106-214 de `UploadRest.java`):
+
+1. **[Auth/Tenant]** `FrontController.getInstance(authBean.getApiKey()).getManagerFactory()` — resolve o tenant **pelo apiKey** (sem `.check()` de access_token; vide seção 8).
+2. **[Validação]** lê a parte `extra` do multipart. Se ausente/vazia → `400 BAD_REQUEST` com `{"message":"Field extra is required..."}`.
+3. **[Sanitização silenciosa]** `ex = ex.substring(0, ex.lastIndexOf("}")+1)` — **trunca tudo após a última `}`** antes de fazer parse JSON (vide seção 5).
+4. **[Default]** `session = extra.session ?? "upload"`.
+5. **[Loop por arquivo]** para cada `InputPart` da parte `file`:
+   1. `getFileName(header)` extrai o nome do `Content-Disposition` (fallback `"unknown"`).
+   2. lê os bytes via `IOUtils.toByteArray`.
+   3. monta o `Map upload` com `_id` (novo `ObjectId`), `extra`, `size`, `filename` (nome original), `content_type`, `time` (`new Date()`), e `bytes`.
+   4. **[Trigger BEFORE]** `triggerManager.execute(guid, upload, ENTITY_UPLOAD, EVENT_BEFORE_CREATE, ...)` — a trigger pode **mutar** `upload.bytes` e `upload.filename`; após ela o código relê `bytes`/`filename` e recalcula `size`.
+   5. **[Upload nuvem]** conforme `getCloud()`: `S3Service.create` | `AzureService.create` | `GoogleService.create` → retorna `{filename_unique, bucket, extension, url}`, mesclado via `upload.putAll(after)`.
+   6. **[Limpeza]** `upload.remove("bytes")` — os bytes **não** são persistidos no Mongo.
+   7. **[Persistência]** `getCollection("upload").save(upload)`.
+   8. **[Trigger AFTER]** `triggerManager.execute(..., EVENT_AFTER_CREATE, ...)`.
+   9. adiciona ao array `uploads`.
+6. **[Resposta]** `201 CREATED` com `{"uploads":[...], "status":"OK"}`.
+
+```mermaid
+flowchart TD
+    A["POST /v3/upload/file"] --> B{"extra presente?"}
+    B -->|"não"| E400["400 Field extra is required"]
+    B -->|"sim"| C["parse extra (trunca após última }) + session ?? upload"]
+    C --> D["para cada file part"]
+    D --> F["lê bytes + filename + content_type"]
+    F --> G["monta Map: _id, extra, size, filename, content_type, time, bytes"]
+    G --> H["trigger before_create (pode mutar bytes/filename)"]
+    H --> I{"getCloud()"}
+    I -->|"azure"| J1["AzureService.create"]
+    I -->|"google"| J2["GoogleService.create"]
+    I -->|"default"| J3["S3Service.create"]
+    J1 --> K["putAll(filename_unique, bucket, extension, url)"]
+    J2 --> K
+    J3 --> K
+    K --> L["remove(bytes)"]
+    L --> M["save() na coleção upload"]
+    M --> N["trigger after_create"]
+    N --> D
+    D --> O["201 CREATED uploads + status OK"]
+```
+
+> **Síncrono.** Todo o pipeline roda na thread da requisição. **Sem transação**: se o `save()` no Mongo falhar após o upload na nuvem, o arquivo físico fica órfão (e vice-versa). `IOException` no loop é capturada e apenas logada (`printStackTrace`) — a resposta ainda retorna `201` com os uploads que conseguiram completar.
+
+### 2.3 Pipeline `POST /v3/upload/image` (`uploadImage`)
+
+Difere de `/file` (linhas 250-420):
+
+1. `session = extra.session ?? "image"` (default diferente).
+2. lê `extra.thumbnails` (lista) e `extra.transform` (lista) — ambos opcionais.
+3. **[Transform]** se `transform` tem itens, aplica em sequência sobre os bytes originais via Thumbnailator: estágio `"size"` (`{width,height}`) e estágio `"outputFormat"` (`{format}`). Outros estágios são ignorados.
+4. grava o documento da **versão original** com `thumb="original"` (o arquivo físico é prefixado `original_` antes do guid da nuvem).
+5. **[Thumbnails]** para cada item de `thumbnails` (`{name,width,height}`): redimensiona, faz upload (prefixo `{name}_`) e grava **um documento `upload` separado** com `thumb={name}`.
+6. **NÃO dispara triggers.** **NÃO** adiciona/remove campo `bytes`.
+7. resposta `201 CREATED` com `uploads` contendo o original **+ um item por thumbnail**.
+
+```mermaid
+flowchart TD
+    A["POST /v3/upload/image"] --> B{"extra presente?"}
+    B -->|"não"| E["400 Field extra is required"]
+    B -->|"sim"| C["session ?? image; lê thumbnails[] e transform[]"]
+    C --> D{"transform tem itens?"}
+    D -->|"sim"| T["aplica size / outputFormat (Thumbnailator)"]
+    D -->|"não"| U["bytes inalterados"]
+    T --> V["upload original (thumb=original, prefixo original_)"]
+    U --> V
+    V --> W["save() original"]
+    W --> X{"thumbnails tem itens?"}
+    X -->|"sim"| Y["para cada thumb: resize + upload (prefixo nome_) + save()"]
+    X -->|"não"| Z["fim do loop"]
+    Y --> Z
+    Z --> R["201 CREATED uploads[original + N thumbs]"]
+```
+
+### 2.4 Interação entre módulos (upload de arquivo)
+
+```mermaid
+sequenceDiagram
+    participant C as Cliente
+    participant R as UploadRest
+    participant T as TriggerManager
+    participant S as Cloud (S3/Azure/Google)
+    participant M as MongoDB (coleção upload)
+    C->>R: POST /v3/upload/file (multipart: file, extra)
+    R->>R: valida extra, monta Map
+    R->>T: execute(before_create) [só /file]
+    T-->>R: upload (bytes/filename possivelmente mutados)
+    R->>S: create(bytes, filename, apiKey, session)
+    S-->>R: {filename_unique, bucket, extension, url}
+    R->>M: save(upload sem bytes)
+    R->>T: execute(after_create) [só /file]
+    R-->>C: 201 {uploads, status}
+```
+
+### 2.5 Pipeline de exclusão e consulta
+
+- **`DELETE /v3/upload/{id}`** (`delete`, linhas 437-466): `findOne({_id})` → `remove({_id})` → lê `filename_unique` e `bucket` → **se** `url` contém o `apiKey`, apaga o arquivo físico no provedor → **sempre** chama `playerManager.delete(id)` no final (efeito colateral, vide seção 5).
+- **`DELETE /v3/upload`** (corpo JSON, `delete`, linhas 482-504): **se** `url` contém o `apiKey`, apaga o arquivo no provedor e remove **todos** os documentos com aquele `url` (`remove({url:#})`).
+- **`GET /v3/upload`** (`findAll`, linhas 529-590): monta aggregation MongoDB com `$match` (injetando `q` cru), filtro de data em `time`, `$sort` e `$limit`. Vide seção 4.
+
+---
+
+## 3. Estrutura dos Objetos
+
+### 3.1 Documento `upload` — coleção `upload`
+
+Não há entidade tipada. Os campos abaixo são os efetivamente gravados pelo código (variam por endpoint).
+
+| Campo | Tipo | Padrão | Origem | Descrição |
+|---|---|---|---|---|
+| `_id` | String | auto | `Guid.newShortGuid()` | Hex de `ObjectId` (24 chars). Gerado no handler. **≠** do guid usado no `filename_unique`. |
+| `extra` | Object | — (obrigatório) | request | JSON arbitrário enviado na parte `extra`. Persistido verbatim em **todos** os documentos (inclusive em cada thumbnail). |
+| `size` | int | — | runtime | Tamanho em bytes após triggers/transformações. |
+| `filename` | String | `"unknown"` | `Content-Disposition` | **Nome original** do arquivo (não o nome único na nuvem). |
+| `content_type` | String | — | header `Content-Type` da parte | MIME do arquivo enviado. |
+| `time` | Date | `new Date()` | runtime | Momento do upload. Serializado como epoch em millis no JSON. |
+| `filename_unique` | String | — | provedor (`create`) | Nome único no storage. **S3/Azure:** `{guid}_{filename}`. **Google:** caminho completo `games/{apiKey}/{session}/{guid}_{filename}`. |
+| `bucket` | String | — | provedor | **S3:** `{bucketRegion}/games/{apiKey}/{session}`. **Azure:** `games/{apiKey}/{session}`. **Google:** apenas o nome do bucket. |
+| `extension` | String | — | provedor | `"." + filename.split("\\.")[1]` — **segundo** token (vide seção 5, bug de extensão). |
+| `url` | String | — | provedor | URL pública direta do arquivo. |
+| `thumb` | String | ausente em `/file` | runtime (`/image`) | `"original"` ou o `name` do thumbnail. **Só existe nos documentos de `/image`.** |
+| `exception` | Object | ausente | provedor (em falha) | Quando o upload na nuvem falha, `create()` retorna `{exception:{...}}` e o documento é salvo **mesmo assim**, sem `url`/`bucket` (vide seção 5). |
 
-## Quando usar
+### 3.2 Campos NÃO persistidos / computados
 
-- Para upload de imagens de avatares
-- Para enviar documentos para treinamentos
-- Para adicionar recursos visuais a desafios e itens
+- **`bytes`** (`byte[]`) — adicionado ao `Map` apenas no fluxo `/file` para passar pela trigger e pelo provedor; **removido com `upload.remove("bytes")` antes do `save()`**. Nunca chega ao Mongo. (No `/image` o campo `bytes` nunca é adicionado ao `Map`.)
 
-## API Endpoints
+### 3.3 Campos legados / desatualizados (apenas no Javadoc, NÃO no runtime)
 
-### Upload de Imagem
-**Método:** POST
-**Endpoint:** `/v3/upload/image`
-**Content-Type:** multipart/form-data
+O Javadoc de `uploadFile`/`uploadImage` mostra campos que **o código não grava**:
 
-**Campos do FormData:**
-- `file`: conteúdo da imagem (ex: profile-pic.jpg)
-- `extra`: `{ "session": "images" }`
+- `filename_original` — **não existe** no runtime; o nome original fica em `filename`.
+- `bucket: "funifier/games/..."` — formato **antigo**; o código atual usa `{bucketRegion}/games/...` (S3) — vide comentários `//OLD VERSION` / `//NEW VERSION : COM BUCKET` em `S3Service`.
+- O bloco comentado de thumbnail em `uploadFile` (linhas 157-164) é **código morto** (geração de thumb 160×160 no `/file`), desabilitado. O `/file` não gera thumbnails.
 
-**Headers:**
-- `Authorization: {token}`
-- `Content-Type: undefined` (gerenciado pelo FormData)
+### 3.4 Estrutura de `extra` no endpoint `/image`
 
-**⚠️ O campo `extra` é obrigatório.** Sem ele, a API retorna erro `Field extra is required`.
+`extra` pode conter, além de `session`:
+
+| Campo de `extra` | Tipo | Significado |
+|---|---|---|
+| `thumbnails` | `[{name, width, height}]` | Cada item gera um documento/arquivo adicional redimensionado. `name` vira o valor de `thumb`. |
+| `transform` | `[{stage, ...}]` | Pipeline aplicado **à imagem original**. Estágios reconhecidos: `{"stage":"size","width":W,"height":H}` e `{"stage":"outputFormat","format":"png"}`. Demais estágios são ignorados. |
+
+> `width`/`height` são lidos com cast direto `(int) map.get("width")` — exige inteiro JSON. Valor fracionário (ex.: `160.0`) gera `ClassCastException` → `500` (vide seção 5).
+
+### 3.5 Enum de provedor (`Configuration.getCloud()`)
+
+| Valor de `cloud` | Provedor | Observação |
+|---|---|---|
+| `"azure"` | `AzureService` | — |
+| `"google"` | `GoogleService` | — |
+| qualquer outro / vazio | `S3Service` (Amazon) | `getCloud()` retorna `"amazon"` como default quando vazio. |
+
+### 3.6 Ciclo de vida
+
+O documento `upload` **não possui campo de status/estado**; é criado e (eventualmente) removido. Não há máquina de estados — por isso nenhum `stateDiagram` é aplicável. As únicas variações de "tipo" de documento são via `thumb` (`original` vs. nome do thumbnail) no fluxo `/image`.
+
+---
+
+## 4. Endpoints
+
+> **Atenção:** o `@Produces` no nível dos métodos de upload é `text/plain`, embora o corpo seja JSON. Os métodos de consulta/exclusão usam `application/json`.
+
+### 4.1 `POST /v3/upload/file`
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Upload de **qualquer tipo de arquivo** (1 ou N arquivos). |
+| Autenticação | Header `Authorization` (Bearer/Basic/Studio/Account) ou `X-Api-Key` / `?api_key` — resolve apiKey. |
+| Content-Type | `multipart/form-data` |
+| Dispara triggers | **Sim** (`before_create` + `after_create`). |
+| Status sucesso | `201 CREATED` |
+
+**Partes do multipart:**
+
+| Parte | Obrigatória | Descrição |
+|---|---|---|
+| `file` | Sim | Conteúdo binário. Pode repetir para múltiplos arquivos. |
+| `extra` | **Sim** | String JSON. Ausência → `400`. `session` define o subdiretório (default `"upload"`). |
+
+**Comportamento real:** parse de `extra` trunca tudo após a última `}`. Falha de upload na nuvem **não** retorna erro HTTP — grava documento com `exception`. `IOException` no loop é silenciada.
+
+**Exemplo (S3 / default), `extra = {"session":"images","name":"arquivo"}`, arquivo `funifier.png`:**
 
-**Exemplo de Resposta:**
 ```json
 {
   "uploads": [
     {
-      "bucket": "funifier/games/{apiKey}/images",
-      "extension": ".jpg",
-      "filename": "profile-pic.jpg",
-      "filename_unique": "{id}_original_profile-pic.jpg",
-      "size": 5559,
-      "content_type": "image/jpeg",
-      "thumb": "original",
-      "extra": { "session": "images" },
-      "_id": "6998ecbc434ba010175f4dd1",
-      "time": 1771629756465,
-      "url": "https://s3.amazonaws.com/funifier/games/{apiKey}/images/{id}_original_profile-pic.jpg"
+      "_id": "5926104c8517667bbdf63c33",
+      "extra": { "session": "images", "name": "arquivo" },
+      "size": 3622,
+      "filename": "funifier.png",
+      "content_type": "image/png",
+      "time": 1495666764893,
+      "filename_unique": "5926104c8517667bbdf63c32_funifier.png",
+      "bucket": "funifier-na1/games/57bde3635e1c92c50b3ce6ff/images",
+      "extension": ".png",
+      "url": "https://s3.amazonaws.com/funifier-na1/games/57bde3635e1c92c50b3ce6ff/images/5926104c8517667bbdf63c32_funifier.png"
     }
   ],
   "status": "OK"
 }
 ```
 
-### Exclusão de Arquivo por ID
-**Método:** DELETE
-**Endpoint:** `/v3/upload/{id}`
+### 4.2 `POST /v3/upload/image`
 
-Remove o registro do banco de dados e exclui o arquivo físico do storage (S3/Azure/Google Cloud).
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Upload de imagem com transformação e geração de thumbnails. |
+| Autenticação | igual a 4.1 |
+| Content-Type | `multipart/form-data` |
+| Dispara triggers | **Não** |
+| Status sucesso | `201 CREATED` |
 
-**Headers:**
-- `Authorization: {token}`
+**Comportamento real:** `session` default `"image"`. Gera **N+1 documentos** (1 original + N thumbnails). O campo `filename` permanece o nome original; o nome físico recebe prefixo `original_`/`{thumbName}_` mais o guid do provedor.
 
-**Resposta:** `204 No Content`
-
-**Exemplo:**
+**Request (cURL):**
+```bash
+curl -X POST "{server}/v3/upload/image" \
+  -H "Authorization: Bearer {token}" \
+  -F 'file=@./funifier.png;type=image/png' \
+  -F 'extra={"session":"images","transform":[{"stage":"size","width":640,"height":640},{"stage":"outputFormat","format":"png"}],"thumbnails":[{"name":"small","width":160,"height":160},{"name":"medium","width":260,"height":260}]}'
 ```
-DELETE /v3/upload/6998ecbc434ba010175f4dd1
-Authorization: Bearer eyJhbGciOiJIUzUxMiIs...
+
+**Response (resumido):**
+```json
+{
+  "uploads": [
+    { "_id": "...", "thumb": "original", "filename": "funifier.png", "filename_unique": "..._original_funifier.png", "url": "...", "extension": ".png", "size": 50123 },
+    { "_id": "...", "thumb": "small",    "filename": "funifier.png", "filename_unique": "..._small_funifier.png",    "url": "...", "size": 5559 },
+    { "_id": "...", "thumb": "medium",   "filename": "funifier.png", "filename_unique": "..._medium_funifier.png",   "url": "...", "size": 9871 }
+  ],
+  "status": "OK"
+}
 ```
 
-**Observação:** A exclusão só é feita se o arquivo pertencer ao mesmo `apiKey` da autorização (verificado pela URL do arquivo).
+### 4.3 `DELETE /v3/upload/{id}`
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Remover registro por `_id` e (condicionalmente) o arquivo físico. |
+| Path param | `id` — `_id` do documento `upload`. |
+| Status sucesso | `204 NO_CONTENT` |
+
+**Comportamento real:**
+- O documento é **sempre** removido do Mongo se existir (`remove({_id})`), **antes** de qualquer checagem de propriedade.
+- O arquivo físico só é apagado **se** `url != null && url.length > 10 && url.contains(apiKey)`.
+- **Efeito colateral:** ao final, `playerManager.delete(id)` é chamado **incondicionalmente** (vide seção 5).
+- Sempre retorna `204`, mesmo se o `id` não existir.
+
+### 4.4 `DELETE /v3/upload` (corpo JSON)
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Remover arquivo e registros por `url`. |
+| Content-Type | `application/json` |
+| Body | `{ "url": "https://.../arquivo.ext" }` |
+| Status sucesso | `204 NO_CONTENT` |
+
+**Comportamento real:** só age **se** `url.contains(apiKey)`. Apaga o arquivo no provedor e remove **todos** os documentos com aquele `url` exato. Se a URL não contém o apiKey, **nada acontece** (e ainda assim retorna `204`).
+
+### 4.5 `GET /v3/upload`
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Listar/consultar documentos `upload` do tenant. |
+| Status sucesso | `200 OK` |
+
+**Query params:**
+
+| Param | Tipo | Default | Descrição |
+|---|---|---|---|
+| `q` | String (fragmento Mongo) | — | **Injetado cru** no `$match` (vide seção 8). Ex.: `extra.session:"images"`. |
+| `published_min` | String | — | Limite inferior em `time` (RFC 3339 ou keyword `-1d`, `-30m`, etc.). Inclusivo (`$gte`). |
+| `published_max` | String | — | Limite superior em `time`. (`$lte`). |
+| `orderby` | String | — | Campo de ordenação. **Injetado cru** no `$sort`. |
+| `reverse` | boolean | `false` | `true` → ordem decrescente (`-1`). |
+| `max_results` | int | `100` | `$limit`. Valores `<= 0` são forçados para `100`. |
+
+**Pipeline gerado (real):**
+```
+{ $match : { _id: {$exists:true} [, <q>] [, time: {$gte:#, $lte:#}] } }
+[ { $sort  : { <orderby> : 1|-1 } } ]
+[ { $limit : <max_results> } ]
+```
+Campos nulos são removidos da resposta (`JsonUtil.toJsonRemoveNullFields`).
 
 ---
 
-### Exclusão de Arquivo por URL
-**Método:** DELETE
-**Endpoint:** `/v3/upload`
-**Content-Type:** application/json
+## 5. Regras de Negócio (no código, fora do schema)
 
-Remove o arquivo pelo campo `url`.
+- **`extra` é obrigatório** em `/file` e `/image`. Ausência → `400`.
+- **Truncamento silencioso de `extra`**: `ex.substring(0, ex.lastIndexOf("}")+1)` descarta qualquer conteúdo após a última `}`. Se a string não contém `}`, `lastIndexOf` retorna `-1` → `substring(0,0)` → string vazia → parse vazio. Conteúdo extra (ex.: múltiplos objetos concatenados) é silenciosamente cortado.
+- **`session` define o caminho** de armazenamento (`games/{apiKey}/{session}`). Defaults divergentes: `"upload"` (`/file`) vs `"image"` (`/image`).
+- **Bug de extensão**: `"." + filename.split("\\.")[1]` usa o **segundo** token, não o último. `arquivo.tar.gz` → `extension = ".tar"`. **Arquivo sem ponto** → `ArrayIndexOutOfBoundsException` não tratada → `500`.
+- **Falha de upload é silenciosa**: em erro de S3/Azure/Google, `create()` retorna `{exception:{...}}` (sem `url`), e o handler **mescla e salva o documento mesmo assim**, retornando `201`. Resultado: documento `upload` sem `url` e com campo `exception`.
+- **Sem transação / sem rollback**: arquivo na nuvem e documento Mongo são independentes. Falha parcial deixa órfãos.
+- **Propriedade por URL**: exclusão física só ocorre quando `url.contains(apiKey)`. Como a URL contém `games/{apiKey}/`, isso normalmente é verdadeiro para arquivos próprios; URLs de outras gamificações não são apagadas.
+- **Efeito colateral em `DELETE /{id}`**: `playerManager.delete(id)` é chamado com o `_id` do upload. Como `_id` de upload é um `ObjectId` aleatório, normalmente **não** corresponde a nenhum player (no-op), mas é uma chamada não óbvia e potencialmente destrutiva se houver colisão de id. Comportamento legado.
+- **`findAll` sem escopo de usuário/tenant interno**: a query roda no banco da própria gamificação (resolvido por apiKey), retornando **todos** os uploads daquela gamificação — não há filtro por usuário, sessão ou propriedade além do que vier em `q`.
+- **`extra` redundante**: o objeto `extra` inteiro (inclusive `thumbnails`/`transform`) é persistido em cada documento gerado, incluindo cada thumbnail.
 
-**Body:**
-```json
-{ "url": "https://s3.amazonaws.com/funifier/games/{apiKey}/images/{filename}" }
+---
+
+## 6. Comportamentos Automáticos
+
+| Comportamento | Trigger | Impacto | Persistência |
+|---|---|---|---|
+| Geração de `_id` | toda criação | `ObjectId` hex novo por documento | Sim (`_id`) |
+| Trigger `before_create` (entidade `upload`) | **só** `POST /file` | Pode mutar `bytes` e `filename` antes do upload | Indireta (afeta arquivo/`size`) |
+| Trigger `after_create` (entidade `upload`) | **só** `POST /file` | Pós-processamento (integrações, logs) | Conforme a trigger |
+| Upload na nuvem | toda criação | Cria arquivo físico **público para leitura** | S3/Azure/Google |
+| Transformação de imagem | `/image` com `transform` | Resize / mudança de formato da original | Sim (arquivo transformado) |
+| Geração de thumbnails | `/image` com `thumbnails` | 1 arquivo + 1 documento por thumbnail | Sim (N documentos) |
+| Índice `extra.session` | startup (`ConnectionPool`) | Cria índice na coleção `upload` | Sim (índice MongoDB) |
+| Remoção de player | `DELETE /{id}` | `playerManager.delete(id)` incondicional | Sim (coleção `player`, se colidir) |
+
+```mermaid
+flowchart LR
+    subgraph file["POST /file"]
+      A1["before_create"] --> A2["upload nuvem"] --> A3["save()"] --> A4["after_create"]
+    end
+    subgraph image["POST /image"]
+      B1["transform (opcional)"] --> B2["upload original + save()"] --> B3["thumbnails: resize + upload + save() (N)"]
+    end
 ```
 
-**Resposta:** `204 No Content`
+> **Diferença crítica:** triggers de `upload` (`before_create`/`after_create`) **só** existem no `/file`. Qualquer automação dependente dessas triggers **não** roda para imagens enviadas via `/image`.
 
 ---
 
+## 7. Suportado vs NÃO Suportado
 
-### Uso com Player (Avatar)
+### ✅ Suportado
 
-Para usar a imagem como avatar do jogador, após o upload:
+- Upload de arquivo genérico (1 ou N) via `POST /v3/upload/file`, com triggers.
+- Upload de imagem com `transform` (`size`, `outputFormat`) e `thumbnails` via `POST /v3/upload/image`.
+- Armazenamento multi-cloud (S3 default, Azure, Google) selecionado por `Configuration.getCloud()`.
+- Exclusão por `_id` (`DELETE /v3/upload/{id}`) e por `url` (`DELETE /v3/upload`).
+- Consulta com `q` (Mongo), filtro de data (`published_min`/`published_max`), `orderby`, `reverse`, `max_results`.
+- URLs públicas de leitura para download direto.
+- Índice em `extra.session`.
 
-```json
-POST /v3/player
-{
-  "_id": "player_id",
-  "image": {
-    "small": { "url": "URL_DO_UPLOAD" },
-    "medium": { "url": "URL_DO_UPLOAD" },
-    "original": { "url": "URL_DO_UPLOAD" }
-  }
-}
+### ❌ NÃO Suportado / Pegadinhas
+
+- **`/image` não dispara triggers** (`before_create`/`after_create`) — apenas `/file`.
+- **`filename_original`** — campo do Javadoc que o runtime **não grava**. Use `filename`.
+- **Bloco de thumbnail no `/file`** (linhas 157-164) — **código morto** comentado; `/file` não gera thumbnails.
+- **Validação de schema** — inexistente; coleção é `HashMap` schemaless.
+- **Atualização (PUT/PATCH)** de um upload — **não há** endpoint de update; só create/delete/query.
+- **Endpoint `DELETE /v3/upload/image`** mencionado em docs antigas — **não existe** no código. A exclusão por URL é `DELETE /v3/upload` (sem sufixo `/image`).
+- **Rollback transacional** entre arquivo físico e documento Mongo — inexistente.
+- **Filtro automático por usuário/propriedade** em `GET /v3/upload` — inexistente.
+- **Tratamento de erro de upload** — falha de nuvem não vira erro HTTP; vira documento com `exception`.
+- **Arquivos sem extensão** — quebram (`500`) por `filename.split("\\.")[1]`.
+- **Acesso privado / ACL restrita** — arquivos S3/Google são gravados com leitura pública para `AllUsers`; não há opção de upload privado neste fluxo.
+
+---
+
+## 8. Segurança e Permissões
+
+- **Autenticação por apiKey, sem validação de access_token no handler.** Os handlers chamam `FrontController.getInstance(authBean.getApiKey()).getManagerFactory()` diretamente — **não** chamam `authBean.getManagerFactory()` (que executaria `.check(accessToken)`) nem verificam escopo/permissão. A resolução do tenant depende apenas de extrair o apiKey das credenciais (`AuthBean.getApiKey()`: Bearer/Basic/Studio/Account/`X-Api-Key`/`?api_key`). Se existir validação de token, ela depende de filtro global de request **não presente nesta classe**. Documentado como observado, sem afirmar exploração.
+- **Isolamento multi-tenant** é feito por **banco-por-gamificação** (cada apiKey → conexão MongoDB própria via `FrontController`) e por prefixo de storage `games/{apiKey}/{session}`. Não há campo de tenant filtrado nas queries.
+- **Arquivos públicos por padrão:**
+  - S3: `acl.grantPermission(GroupGrantee.AllUsers, Permission.Read)` em todo `putObject`.
+  - Google: `Acl.of(Acl.User.ofAllUsers(), Acl.Role.READER)`.
+  - Azure: o container `funifier` é criado sem acesso público explícito (a linha `BlobContainerPublicAccessType.BLOB` está **comentada**) — a visibilidade depende da configuração default do container.
+- **Superfície de injeção (`GET /v3/upload`):** os parâmetros `q` e `orderby` são **concatenados crus** na string da aggregation (`query.append(", " + q)` e `"{$sort : {" + orderby + " : #}}"`). Isso permite manipular o `$match`/`$sort` com operadores MongoDB arbitrários (NoSQL injection dentro do escopo do banco do próprio tenant). Não há sanitização. O escopo de dano é limitado ao banco da gamificação autenticada, mas qualquer campo/operador pode ser injetado.
+- **Exclusão guardada por substring de URL:** `url.contains(apiKey)` é uma checagem fraca de propriedade — baseada em substring da URL, não em verificação de ACL/dono real.
+
+---
+
+## 9. Observabilidade e Troubleshooting
+
+**Diagnóstico — o módulo está funcionando?**
+- Confirme o provedor ativo: valor de `cloud` em `Configuration` (`getCloud()` → `amazon`/`azure`/`google`). Logs de startup imprimem `=== FUNIFIER_CLOUD_PROVIDER [...] ===`.
+- Faça um upload de teste e verifique se o `url` retornado é acessível publicamente (GET na URL).
+
+**Queries úteis (banco da gamificação):**
+```
+GET /v3/upload?q=extra.session:"images"&orderby=time&reverse=true&max_results=10
+GET /v3/upload?published_min=-1d&orderby=time&reverse=true
+GET /v3/upload/<id>     # (via q, pois não há rota GET /{id}: use q=_id:"<id>")
 ```
+Índice disponível: **apenas `extra.session`** (`ConnectionPool.java:164`). **`time` NÃO é indexado**, embora `findAll` filtre e ordene por ele — consultas por data em coleções grandes podem ser lentas (collection scan).
+
+**Erros comuns e causas:**
 
-**Nota:** O campo `image` do player deve ter o formato `{ small: { url }, medium: { url }, original: { url } }`. A URL é obtida de `response.uploads[0].url`.
+| Sintoma | Causa provável |
+|---|---|
+| `400 Field extra is required` | parte `extra` ausente ou vazia no multipart. |
+| Documento salvo com campo `exception` e sem `url` | falha no provedor de nuvem (credenciais, região, rede). Upload "passou" (201) mas o arquivo não existe. |
+| `500` ao enviar arquivo | nome de arquivo sem ponto/extensão (`split("\\.")[1]` estoura) ou `width`/`height` fracionário em `transform`/`thumbnails`. |
+| `extension` errada (ex.: `.tar`) | nome com múltiplos pontos — usa o **segundo** token. |
+| Triggers de upload não rodaram | upload foi via `/image` (não dispara triggers) e não via `/file`. |
+| Arquivo não foi apagado no `DELETE` | `url` não contém o `apiKey`, ou `url` ausente/curta no documento. |
+| Player sumiu após deletar upload | efeito colateral `playerManager.delete(id)` (colisão de id). |
 
-### Upload de Arquivo Genérico
-**Método:** POST
-**Endpoint:** `/v3/upload/file`
-**Content-Type:** multipart/form-data
+**O que verificar quando algo não funciona:** credenciais do provedor; valor de `cloud`; se a `url` foi realmente preenchida no documento (indica sucesso do upload físico); se o `_id` consultado existe; se `q` está sintaticamente válido como fragmento Mongo.
 
-Suporta **qualquer tipo de arquivo** (não apenas imagens). Aceita múltiplos arquivos.
+---
 
-**Campos:**
-- `file`: arquivo binário (pode repetir para vários)
-- `extra`: string JSON obrigatória (ex: `{"session": "docs"}`)
+## 10. Exemplos Práticos
 
-**cURL:**
+### 10.1 Mínimo funcional (arquivo genérico)
 ```bash
 curl -X POST "{server}/v3/upload/file" \
   -H "Authorization: Bearer {token}" \
   -F 'file=@./documento.pdf;type=application/pdf' \
-  -F 'extra={"session":"docs","name":"manual"}'
+  -F 'extra={"session":"docs"}'
 ```
 
-### Deletar Upload por URL
-**Método:** DELETE
-**Endpoint:** `/v3/upload/image`
-
-**Body:**
+### 10.2 Avançado (imagem com transform + thumbnails)
+```bash
+curl -X POST "{server}/v3/upload/image" \
+  -H "Authorization: Bearer {token}" \
+  -F 'file=@./avatar.png;type=image/png' \
+  -F 'extra={
+        "session":"avatars",
+        "transform":[
+          {"stage":"size","width":640,"height":640},
+          {"stage":"outputFormat","format":"png"}
+        ],
+        "thumbnails":[
+          {"name":"small","width":160,"height":160},
+          {"name":"medium","width":260,"height":260}
+        ]
+      }'
+```
+Resultado: 3 documentos (`thumb`: `original`, `small`, `medium`), cada um com `url` próprio. Para usar como avatar do player:
 ```json
-{ "url": "https://s3.amazonaws.com/funifier/games/{APIKEY}/images/59359e..._logo.png" }
+POST /v3/player
+{
+  "_id": "player_id",
+  "image": {
+    "small":    { "url": "URL_DO_THUMB_small" },
+    "medium":   { "url": "URL_DO_THUMB_medium" },
+    "original": { "url": "URL_DO_ORIGINAL" }
+  }
+}
 ```
 
-### Listar Uploads
-**Método:** GET
-**Endpoint:** `/v3/upload`
+### 10.3 Anti-pattern (o que NÃO fazer)
+```bash
+# RUIM: nome de arquivo sem extensão → 500 (ArrayIndexOutOfBounds em split("\\.")[1])
+curl ... -F 'file=@./arquivo_sem_extensao'
+
+# RUIM: width fracionário → ClassCastException → 500
+-F 'extra={"transform":[{"stage":"size","width":640.0,"height":640.0}]}'
 
-## Triggers de Upload
+# RUIM: assumir que o upload falhou retorna erro HTTP.
+# Se a nuvem falhar, a resposta ainda é 201 e o documento é salvo com "exception" e sem "url".
+# SEMPRE valide a presença de uploads[i].url antes de usar.
 
-O upload dispara triggers `BEFORE_CREATE` e `AFTER_CREATE` na entidade `UPLOAD`. Isso permite:
-- Validar arquivos antes de salvar
-- Processar metadados após upload
-- Integrar com outros módulos
+# RUIM: depender de trigger before/after_create ao usar /image — ela NÃO dispara.
+# Use /file se precisar de triggers.
+```
 
-## Validações e Testes
+---
 
-- [ ] Upload de imagem retorna URL válida
-- [ ] Upload de arquivo genérico funciona
-- [ ] URL da imagem é acessível publicamente
-- [ ] Diferentes formatos são aceitos (jpg, png, pdf, etc.)
-- [ ] Delete por URL remove o arquivo
+## Checklist de Configuração
+
+- [ ] Parte `extra` presente e com JSON válido (sem ela → `400`).
+- [ ] `extra` termina na `}` correta (conteúdo após a última `}` é descartado silenciosamente).
+- [ ] Nome do arquivo **possui extensão** com um único ponto (evita `500` e `extension` errada).
+- [ ] `session` definido conscientemente (define o caminho `games/{apiKey}/{session}`; default `upload`/`image`).
+- [ ] Em `/image`, `width`/`height` são **inteiros** (não use `640.0`).
+- [ ] Validar `uploads[i].url` na resposta antes de usar (presença de `exception` indica falha silenciosa).
+- [ ] Se precisar de automação por trigger, usar `/file` (o `/image` não dispara triggers).
+- [ ] Provedor de nuvem (`Configuration.cloud`) e credenciais configurados; do contrário documentos são salvos com `exception`.
+- [ ] Ciente de que arquivos ficam **públicos para leitura** (S3/Google).
+- [ ] Em `GET /v3/upload`, tratar `q`/`orderby` como entrada confiável (concatenação crua — risco de NoSQL injection).