funifier-mcp 0.2.26 → 0.2.27

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

@@ -1,28 +1,493 @@
-# Avatar (Avatar)
+# `avatar`
 
-## O que é
+**Acesso Studio:** não identificado neste repositório (`funifier-service` é o backend; não há UI de Studio para avatar aqui)
+**Endpoint base API:** `/v3/avatar`
+**Coleção MongoDB:** `avatar` (`Entity.AVATAR`, mapeada para `HashMap.class` — sem classe de entidade dedicada)
 
-Criação e customização de avatares para os jogadores. Permite aos jogadores criarem avatares personalizados, desbloqueando acessórios e itens de acordo com o desempenho na gamificação ou por compras na loja. Pode ser usado em ambientes 2D ou 3D.
+> **Aviso de engenharia reversa.** Esta documentação foi reescrita a partir do código-fonte real de `funifier-service` (`AvatarRest.java`, `AvatarManager.java`, `Entity.java`, `PlayerManager.java`). A documentação anterior descrevia recursos (acessórios desbloqueáveis, integração com Virtual Good/loja, ambientes 2D/3D, avatar padrão para novos jogadores) que **não têm nenhuma sustentação no código** — ver Seção 7.
 
-## Quando usar
+---
 
-- Para personalização visual dos jogadores
-- Para criar senso de identidade e pertencimento
-- Para vincular recompensas a itens visuais
-- Para ambientes virtuais com representação do jogador
+## 1. Visão Geral
 
-## Dependências
+O módulo `avatar` é um **armazenamento de imagem de perfil por jogador** com um documento de chave‑valor livre por jogador. Ele faz duas coisas concretas:
 
-- **Virtual Good** (opcional): acessórios podem ser vendidos na loja
+1. **Persiste um documento arbitrário** (`HashMap`) na coleção `avatar`, cujo `_id` é o id do jogador. O schema é totalmente livre — qualquer campo enviado pelo cliente é gravado verbatim.
+2. **Recebe uma imagem PNG em base64**, faz upload para o storage de nuvem (S3, Azure ou Google), e grava a URL resultante **tanto** no documento `avatar` (`png_url`) **quanto** no campo `extra.avatar` do jogador.
 
-## Checklist de Configuração
+Arquiteturalmente o módulo é mínimo:
+
+- `AvatarRest` (`com.funifier.rest.v3.rest.AvatarRest`) — recurso JAX‑RS em `@Path("v3/avatar")`.
+- `AvatarManager` (`com.funifier.engine.avatar.AvatarManager`) — manager fino sobre Jongo/MongoDB. CRUD direto na coleção, sem regras de negócio.
+- Sem entidade, sem DTO, sem scheduler, sem aggregate dedicado, sem enums.
+
+**Relação com outros módulos:** praticamente nenhuma. `Entity.AVATAR` é referenciada **exclusivamente** dentro de `AvatarManager.java`; `getAvatarManager()` é chamado apenas por `ManagerFactory` (definição) e `AvatarRest`. O único acoplamento real é com o módulo **Player**: o upload de imagem dispara `PlayerManager.insert(player)` (ver Seção 6), com todos os efeitos colaterais de uma atualização de jogador.
+
+**Problema que resolve:** guardar a imagem/representação visual de um jogador e disponibilizá‑la via URL pública. Nada além disso está implementado.
+
+---
+
+## 2. Arquitetura e Fluxos
+
+### 2.1 Pipeline principal — `POST /v3/avatar` → `AvatarRest.save()`
+
+Sequência exata (`AvatarRest.save`, linhas 191‑282):
+
+```
+[Trigger]        POST /v3/avatar  com  Map<String,Object> avatar (JSON)
+[Resolve player] player = avatar.get("_id")
+                 se "me" → player = authBean.getPlayerFromTokenIfExist();  avatar.put("_id", player)
+[Carrega player] p = PlayerManager.findById(player)
+[Normaliza nome] name = Normalizer NFD + remove acentos/não‑alfanuméricos + lowercase + trim
+[Lê imagem]      png = (String) avatar.get("png")        // svg NÃO é lido (linha comentada)
+[Cloud]          cloud = Configuration.getCurrentConfiguration().getCloud()   // global, não por‑tenant
+[Limpa antiga]   current = AvatarManager.findById(player)
+                 se current != null e current.png_url tem >5 chars → delete na nuvem (azure/google/s3)
+[Processa png]   se png != null E png.length() > 20:
+                     valida prefixo "data:image/png" + "base64"
+                     se válido:  bytes = Base64.decode(...)
+                                 url = <Cloud>Service.put(bytes, name+".png", apiKey, "avatar")
+                                 p.extra.put("avatar", url)
+                                 PlayerManager.insert(p)        // ← efeito colateral pesado (ver 2.2)
+                                 avatar.put("png_url", url)
+                                 avatar.put("status", "saved")
+                     senão:      avatar.put("status", "error")
+[Persiste avatar] AvatarManager.save(avatar)  → Jongo c.save(avatar)   // upsert/replace por _id
+[Resposta]       201 CREATED  +  JSON do avatar (campos null removidos)
+```
+
+Pseudocódigo do gate de processamento de imagem (note os silêncios):
+
+```
+se png == null OU png.length() <= 20:
+    não processa imagem (status NÃO é setado, png_url NÃO é setado)
+senão se png não casa "data:image/png" + "base64":
+    avatar.status = "error"   (nenhuma imagem é enviada)
+senão:
+    faz upload, seta player.extra.avatar, insert(player), avatar.png_url, avatar.status = "saved"
+```
+
+#### Fluxo de avaliação — `POST /v3/avatar`
+
+```mermaid
+flowchart TD
+    A[POST /v3/avatar - JSON] --> B{_id == 'me'?}
+    B -- sim --> C[_id = player do token]
+    B -- nao --> D[usa _id do payload]
+    C --> E[PlayerManager.findById _id]
+    D --> E
+    E --> F[cloud = Configuration.getCloud - global]
+    F --> G{avatar atual tem png_url > 5 chars?}
+    G -- sim --> H[deleteURL imagem antiga - azure/google/s3]
+    G -- nao --> I{png != null E length > 20?}
+    H --> I
+    I -- nao --> M[AvatarManager.save - documento]
+    I -- sim --> J{"prefixo data:image/png;base64 valido?"}
+    J -- nao --> K[avatar.status = error]
+    J -- sim --> L[upload name.png -> png_url<br/>player.extra.avatar = url<br/>PlayerManager.insert p<br/>avatar.status = saved]
+    K --> M
+    L --> M
+    M --> N[201 CREATED + JSON sem campos null]
+```
+
+> **Síncrono.** Todo o fluxo é síncrono, sem transação. Se `AvatarManager.save` falhar **depois** de `PlayerManager.insert(p)`, o jogador já terá sido atualizado e a imagem já estará na nuvem — não há rollback.
+
+### 2.2 Efeito colateral oculto — `PlayerManager.insert(p)`
+
+Esta é a parte **não óbvia**. Salvar uma imagem de avatar **não** apenas grava uma URL: ela re‑persiste o jogador inteiro através de `PlayerManager.insert(player)` (linhas 244‑313 de `PlayerManager.java`), que dispara triggers, auditoria e sincronização de principal/times. Importante: `insert` é chamado **sem `AuthBean`**, então o log de auditoria fica com contexto de usuário nulo.
+
+#### Cascata de efeitos — `PlayerManager.insert(p)`
+
+```mermaid
+sequenceDiagram
+    participant R as AvatarRest.save
+    participant PM as PlayerManager.insert
+    participant TM as TriggerManager
+    participant DB as MongoDB
+    participant AM as AuditManager
+    R->>PM: insert(player)  [authBean = null]
+    PM->>DB: findOne principal {userId}
+    alt principal existe (update)
+        PM->>TM: execute(PLAYER, before_update)
+        PM->>DB: save(player) na colecao player
+        PM->>DB: save(principal)
+        PM->>TM: execute(PLAYER, after_update)
+        PM->>AM: log(player, EVENT_UPDATE, authBean=null)
+    else principal inexistente (create)
+        PM->>TM: execute(PLAYER, before_create)
+        PM->>DB: save(player)
+        PM->>DB: save(principal novo)
+        PM->>TM: execute(PLAYER, after_create)
+        PM->>AM: log(player, EVENT_CREATE, authBean=null)
+    end
+    PM->>DB: recalcula links de time do jogador
+    PM->>DB: player.updated = now
+```
+
+### 2.3 Endpoints legados (form‑urlencoded e download)
+
+`save_temp_image`, `save_ready_image` e `download_temp_image` são endpoints antigos que **não tocam a coleção `avatar`** — eles operam apenas sobre `player.extra.avatar`. Ver Seções 4 e 7. Há ainda três métodos **totalmente comentados** no fim de `AvatarRest.java` (linhas 409‑588): uma versão antiga de `saveTempImage`/`saveReadyImage` que escrevia no filesystem local e um `downloadReadyImage`. Não estão ativos.
+
+---
+
+## 3. Estrutura dos Objetos
+
+### 3.1 Documento `avatar` — coleção `avatar`
+
+**Não existe classe de entidade.** `Entity.AVATAR` é mapeada para `HashMap.class`; o documento é um mapa livre. A tabela abaixo lista apenas os campos que o **código** conhece explicitamente. Qualquer outro campo enviado pelo cliente é persistido verbatim, sem validação.
+
+| Campo     | Tipo   | Padrão | Obrigatório | Descrição |
+| --------- | ------ | ------ | ----------- | --------- |
+| `_id`     | String | —      | **Sim**     | Id do jogador. É a chave do documento (1 avatar por jogador). Se ausente, `AvatarManager.save` **não faz nada silenciosamente** (sem erro, sem log). |
+| `png`     | String | —      | Não         | Imagem em data‑URI base64. Só é processada se `length > 20` e casar `data:image/png;base64,...`. **Não é removida antes de persistir** — fica gravada no documento (ver abaixo). |
+| `png_url` | String | —      | Não (server) | URL pública gerada após o upload. **Adicionada pelo servidor** durante o `save` quando a imagem é processada com sucesso. |
+| `status`  | String | —      | Não (server) | `"saved"` (upload OK) ou `"error"` (data‑URI inválido). **Adicionada pelo servidor**. Não é setada quando `png` é nulo/curto. |
+| `svg`     | String | —      | Não         | **Aceito no payload mas IGNORADO** no endpoint JSON (`String svg = avatar.get("svg")` está comentado, linha 211). Persiste verbatim se enviado, mas nunca é processado. |
+| *(livre)* | qualquer | —    | Não         | Qualquer chave adicional é gravada como veio. Sem schema, sem coerção de tipo. |
+
+**Campos adicionados pelo servidor (não enviados pelo cliente):** `png_url`, `status`.
+
+**Campo gravado de forma indesejada (legado):** `png`. O `avatar.remove("png")` está **comentado** (linhas 267‑268), então o **data‑URI base64 inteiro fica armazenado no MongoDB** ao lado de `png_url`. Isso infla o documento e duplica o conteúdo da imagem dentro do banco.
+
+**Sem enums, sem subentidades, sem técnicas de jogo (GT).** O módulo não possui nenhuma estrutura aninhada nem catálogo de itens.
+
+### 3.2 Campo relacionado em `Player` — `extra.avatar`
+
+| Campo (em `player`) | Tipo | Origem | Descrição |
+| ------------------- | ---- | ------ | --------- |
+| `extra.avatar`      | String (URL) | gravado por todos os endpoints de upload | URL da última imagem de avatar enviada. **Escrito mas nunca lido** pelo backend — nenhum outro código em `funifier-service` lê `player.extra.get("avatar")`. |
+
+---
+
+## 4. Endpoints
+
+### `POST /v3/avatar`
+
+| Aspecto               | Detalhe |
+| --------------------- | ------- |
+| Método handler        | `AvatarRest.save` |
+| Consumes              | `application/json` |
+| Finalidade            | Cria/atualiza o documento de avatar do jogador e, opcionalmente, faz upload da imagem PNG. |
+| Autenticação          | Bearer token (ou Basic/Studio/Account, ou `api_key`+`access_token`) |
+| Full replace ou patch | **Full replace.** Jongo `c.save(map)` substitui o documento inteiro pelo `_id`. Campos omitidos no payload **somem** do documento. |
+| Resolução `_id`       | `"me"` → id do player extraído do token |
+
+**Comportamento real:**
+
+- O `_id` define o jogador; não há geração automática de id.
+- Quando `png` é processado, há um **efeito colateral em `player`** (Seção 2.2) e um **delete da imagem anterior** na nuvem.
+- O servidor injeta `png_url` e `status` no documento retornado.
+- A resposta passa por `JsonUtil.toJsonRemoveNullFields` — campos com valor `null` **não aparecem** no JSON de retorno.
+- Se o jogador não existir (`PlayerManager.findById` retorna `null`) **e** `png` for válido, ocorre **NullPointerException** em `p.extra.put(...)` (não há null‑check). Sem `png`, o jogador nunca é desreferenciado.
+
+**Exemplo de request:**
+
+```json
+{
+  "_id": "player123",
+  "png": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJ..."
+}
+```
+
+**Exemplo de response (201):**
+
+```json
+{
+  "_id": "player123",
+  "png": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJ...",
+  "png_url": "https://<storage-do-tenant>/avatar/player123.png",
+  "status": "saved"
+}
+```
+
+> Note que `png` (o data‑URI inteiro) é devolvido **e** persistido, ao lado de `png_url`.
+
+---
+
+### `GET /v3/avatar/{id}`
+
+| Aspecto      | Detalhe |
+| ------------ | ------- |
+| Método handler | `AvatarRest.find` → `AvatarManager.findById` |
+| Produces     | `application/json` |
+| Finalidade   | Retorna o documento de avatar de um jogador. |
+| Autenticação | Bearer token |
+
+**Path params:**
+
+| Param | Tipo | Descrição |
+| ----- | ---- | --------- |
+| `id`  | String | Id do jogador. `"me"` → id do token. |
+
+**Comportamento real:** `c.findOne("{_id:#}", id)`. Retorna o documento (com campos null removidos no JSON). Se não existir, retorna `null` serializado.
+
+---
+
+### `GET /v3/avatar`
+
+| Aspecto      | Detalhe |
+| ------------ | ------- |
+| Método handler | `AvatarRest.findAll` → `AvatarManager.findAll` |
+| Produces     | `application/json` |
+| Finalidade   | Lista documentos de avatar via pipeline de agregação MongoDB. |
+| Autenticação | Bearer token |
+
+**Query params:**
+
+| Param         | Tipo    | Padrão | Descrição |
+| ------------- | ------- | ------ | --------- |
+| `id`          | String  | —      | Filtra por `_id` exato. |
+| `q`           | String  | —      | **Fragmento de filtro Mongo concatenado cru** dentro do `$match` (ver Seção 8 — superfície de injeção). |
+| `fields`      | String  | —      | Lista separada por vírgula; vira `$project { campo:1, ... }`. |
+| `orderby`     | String  | —      | Campo de ordenação; vira `$sort { orderby: ±1 }`. |
+| `reverse`     | boolean | false  | `true` → ordem decrescente (`-1`); senão `1`. Parse tolerante (exceção engolida). |
+| `max_results` | int     | 100    | `$limit`. `<= 0` ou não numérico → cai para **100**. |
+
+**Query MongoDB real construída:**
+
+```
+{ $match : { _id: {$exists:true} [, _id: <id>] [, <q literal>] } }
+[ { $project : { <campo>:1, ... } } ]
+[ { $sort : { <orderby> : 1|-1 } } ]
+{ $limit : <max_results | 100> }
+```
+
+---
+
+### `DELETE /v3/avatar/{id}`
+
+| Aspecto      | Detalhe |
+| ------------ | ------- |
+| Método handler | `AvatarRest.delete` → `AvatarManager.delete` |
+| Finalidade   | Remove o documento de avatar e, se houver, a imagem na nuvem. |
+| Autenticação | Bearer token |
+| Resposta     | `204 NO_CONTENT` |
+
+**Path params:** `id` (String) — `"me"` → id do token.
+
+**Comportamento real (inconsistência confirmada):** se o avatar tiver `png_url`, o delete da imagem é feito **apenas via `S3Service.deleteURL`** — **não é cloud‑aware**, diferente do `save` (que escolhe azure/google/s3). Em tenants Azure/Google a imagem **não é removida** da nuvem. Em seguida `c.remove("{_id:#}", id)` apaga o documento.
+
+---
+
+### `POST /v3/avatar/save_temp_image`  *(legado)*
 
-- [ ] Definir tipos de avatar disponíveis
-- [ ] Criar acessórios e itens desbloqueáveis
-- [ ] Vincular itens a desafios ou loja virtual
+| Aspecto      | Detalhe |
+| ------------ | ------- |
+| Método handler | `AvatarRest.saveTempImage` |
+| Consumes     | `application/x-www-form-urlencoded` |
+| Produces     | `text/plain` |
+| Finalidade   | Upload de imagem (PNG ou SVG) gravando a URL **apenas** em `player.extra.avatar`. |
 
-## Validações e Testes
+**Form params:** `filename`, `imgdata`, `player` (`"me"` suportado).
+
+**Comportamento real:** decodifica PNG base64 ou valida SVG, faz upload (cloud‑aware: azure/google/s3), `p.extra.put("avatar", url)`, `PlayerManager.insert(p)`. **Não grava nada na coleção `avatar`.** Retorna o texto `"saved"` ou `"error"`. O nome do arquivo enviado é usado direto (sem normalização do `save` JSON).
+
+---
+
+### `POST /v3/avatar/save_ready_image`  *(legado)*
+
+| Aspecto      | Detalhe |
+| ------------ | ------- |
+| Método handler | `AvatarRest.saveReadyImage` |
+| Consumes     | `application/x-www-form-urlencoded` |
+| Produces     | `text/plain` |
+| Finalidade   | Igual ao `save_temp_image`, porém **somente S3**. |
+
+**Comportamento real:** idêntico ao `save_temp_image`, mas o upload usa **`S3Service.put` fixo** (não cloud‑aware). Grava só em `player.extra.avatar` + `PlayerManager.insert(p)`. Não toca a coleção `avatar`.
+
+---
+
+### `GET /v3/avatar/download_temp_image`  *(legado / quebrado)*
+
+| Aspecto      | Detalhe |
+| ------------ | ------- |
+| Método handler | `AvatarRest.downloadTempImage` |
+| Produces     | `image/png` |
+| Finalidade   | Lê e devolve um arquivo de imagem do disco local. |
+
+**Query params:** `filename`, `filetype` (`png`/`svg`).
+
+**Comportamento real:** lê `Files.readAllBytes(Paths.get("/home/funifier/xti/projetos/cds/WebContent/avatar/temp-avatars/" + filename))`. **Caminho local fixo** — não funciona em deploys de nuvem (o storage é S3/Azure/Google). Além disso, `filename` é concatenado sem sanitização → **superfície de path traversal** (Seção 8). Em erro de I/O retorna `200 OK` com corpo `"error"`.
+
+---
+
+## 5. Regras de Negócio
+
+Regras que **existem no código** mas não em nenhum schema:
+
+- **Um avatar por jogador.** O `_id` do documento é o id do jogador; não há coleção de itens nem múltiplos avatares.
+- **`_id` obrigatório no `save`.** `AvatarManager.save` faz no‑op silencioso se `_id` estiver ausente — a chamada retorna sucesso aparente mas nada é gravado.
+- **Gate de tamanho da imagem:** `png` só é processado se `length > 20`. Valores menores são ignorados sem erro.
+- **Formato aceito no `save` JSON:** somente `data:image/png;base64,...`. SVG é ignorado neste endpoint.
+- **Limpeza da imagem anterior:** no `save`, se já existe `png_url`, a imagem antiga é deletada da nuvem antes do novo upload (cloud‑aware).
+- **Provedor de nuvem é global, não por tenant:** `Configuration.getCurrentConfiguration().getCloud()` decide entre `azure`/`google`/default(S3) para toda a instância.
+- **Multi‑tenant por API key:** o tenant é resolvido por `FrontController.getInstance(apiKey)`; cada tenant tem sua própria conexão/coleção `avatar`.
+- **Sem consistência transacional:** upload na nuvem, `insert(player)` e `save(avatar)` são passos independentes; falha parcial deixa estado inconsistente.
+
+---
+
+## 6. Comportamentos Automáticos
+
+| Comportamento | Trigger | Impacto | Persistência |
+| ------------- | ------- | ------- | ------------ |
+| Atualização de `player.extra.avatar` | Upload bem‑sucedido em `save`, `save_temp_image`, `save_ready_image` | URL da imagem gravada no jogador | Coleção `player` |
+| `PlayerManager.insert(player)` | Mesmo upload | Re‑persiste o jogador inteiro | Coleção `player` + `principal` + `team_player` |
+| Triggers de Player | Dentro de `insert` | Dispara `before_update`/`after_update` (ou `before_create`/`after_create`) para `ENTITY_PLAYER` | Conforme triggers configurados |
+| Log de auditoria | Dentro de `insert` | `AuditManager.log(player, EVENT_UPDATE/CREATE, authBean=null)` — **sem contexto de usuário** | Coleção `audit_log` |
+| Sincronização de Principal | Dentro de `insert` | Cria/atualiza `principal` do jogador | Coleção `principal` |
+| Recalcula `player.updated` | Dentro de `insert` | Timestamp atualizado | Coleção `player` |
+| Delete da imagem antiga | `save` quando já existe `png_url` | Remove arquivo anterior na nuvem (cloud‑aware) | Storage de nuvem |
+| Inclusão de `png_url` + `status` | `save` | Campos adicionados ao documento | Coleção `avatar` |
+
+> **Atenção:** trocar a foto de avatar de um jogador dispara silenciosamente a cadeia de atualização de Player (triggers + auditoria). Triggers de `after_update` em `ENTITY_PLAYER` serão executados a cada upload de avatar.
+
+---
+
+## 7. Suportado vs NÃO Suportado
+
+### ✅ Suportado (confirmado no código)
+
+- CRUD de um documento livre por jogador na coleção `avatar` (`save`/`find`/`findAll`/`delete`).
+- Upload de imagem **PNG base64** via `POST /v3/avatar` (JSON), com armazenamento em S3/Azure/Google.
+- Upload via endpoints legados form‑urlencoded (`save_temp_image`, `save_ready_image`) gravando em `player.extra.avatar`.
+- Resolução de `"me"` para o jogador do token em todos os endpoints.
+- Listagem com filtro (`q`), projeção (`fields`), ordenação (`orderby`/`reverse`) e limite (`max_results`).
+- Limpeza da imagem anterior na nuvem ao re‑salvar (no `save` JSON).
+
+### ❌ NÃO Suportado (declarado em documentação antiga ou no payload, mas sem implementação)
+
+- **Acessórios / itens desbloqueáveis** — inexistentes no código. Não há catálogo, item, nem desbloqueio.
+- **Integração com Virtual Good / loja** — inexistente. `Entity.AVATAR` é usada **apenas** em `AvatarManager`; nenhum outro manager lê/escreve a coleção `avatar`.
+- **Ambientes 2D/3D** — nenhum conceito de dimensão/cena/modelo no código.
+- **Avatar padrão para novos jogadores** — não há provisionamento automático; um jogador sem documento simplesmente não tem avatar.
+- **Tipos de avatar configuráveis** — não existe enum nem configuração de tipos.
+- **Campo `svg` no endpoint JSON** — aceito no payload mas **ignorado** (linha de leitura comentada). Persiste verbatim sem processamento.
+- **`download_temp_image` em produção/nuvem** — lê de caminho de filesystem local fixo; quebrado em qualquer deploy de nuvem.
+- **DELETE cloud‑aware** — o delete da imagem usa só S3; em Azure/Google a imagem fica órfã na nuvem.
+- **Remoção do `png` antes de persistir** — código comentado; o data‑URI base64 acaba gravado no MongoDB.
+- **Métodos comentados** (`saveTempImage`/`saveReadyImage`/`downloadReadyImage` baseados em filesystem) — código morto, não roteado.
+
+---
+
+## 8. Segurança e Permissões
+
+- **Autenticação:** via `AuthBean` — header `Authorization` (`Bearer`, `Basic`, `Studio`, `Account`) ou `api_key`/`access_token` (query ou headers `X-Api-Key`/`X-Access-Token`).
+- **Validação de token não explícita neste controller:** `AvatarRest` resolve o tenant com `FrontController.getInstance(authBean.getApiKey()).getManagerFactory()` — **não** invoca o caminho `authBean.getManagerFactory()` que chama `.check(accessToken)`. Ou seja, o `apiKey` (extraído/derivado do token) determina o tenant, mas o passo explícito de validação de `access_token` deste recurso não é executado. Não significa "sem autenticação" (o `apiKey` ainda vem do token), mas é uma diferença de rigor frente a recursos que chamam `.check(...)`.
+- **Isolamento multi‑tenant:** garantido pela conexão por `apiKey` (`FrontController.getInstance(apiKey)`); cada tenant acessa sua própria coleção `avatar`.
+- **Injeção em pipeline MongoDB (`findAll`):** os parâmetros `q`, `fields` e `orderby` são **concatenados crus** na string do pipeline de agregação:
+  - `q`: `query.append(", " + q)` dentro do `$match` — permite injetar operadores/condições arbitrárias.
+  - `fields`: split por vírgula e concatenado no `$project`.
+  - `orderby`: concatenado no `$sort`.
+  - Não há allow‑list nem escaping. Trate como **superfície de injeção NoSQL**.
+- **Path traversal em `download_temp_image`:** `filename` é concatenado direto em `Paths.get(".../temp-avatars/" + filename)` sem sanitização → possível leitura de arquivos fora do diretório (`../`). Endpoint legado/quebrado, mas presente.
+- **Vazamento em logs:** vários `System.out.println` imprimem `apiKey`, `player` e um trecho base64 da imagem (`AvatarRest.downloadTempImage`, `saveTempImage`, `save`). Dados sensíveis em log de aplicação.
+- **Auditoria com usuário nulo:** o upload chama `PlayerManager.insert(p)` sem `AuthBean`, então o `audit_log` da atualização do jogador não registra qual usuário disparou a ação.
+
+---
+
+## 9. Observabilidade e Troubleshooting
+
+**Como verificar se o módulo está funcionando**
+
+```
+# Recupera o avatar de um jogador
+GET /v3/avatar/player123
+
+# Recupera o avatar do jogador autenticado
+GET /v3/avatar/me
+
+# Lista avatares com imagem (filtro via q — sintaxe Mongo crua)
+GET /v3/avatar?q={ "png_url" : { "$exists" : true } }&max_results=20
+
+# Projeta apenas campos relevantes
+GET /v3/avatar?fields=_id,png_url,status
+```
+
+**Queries Mongo úteis (investigação direta no banco do tenant):**
+
+```js
+// Avatar de um jogador
+db.avatar.findOne({ _id: "player123" })
+
+// Documentos que ainda guardam o base64 inflado (png presente)
+db.avatar.find({ png: { $exists: true } }, { _id: 1, png_url: 1, status: 1 })
+
+// Avatares com status de erro de upload
+db.avatar.find({ status: "error" })
+
+// Conferir a URL gravada no jogador
+db.player.findOne({ _id: "player123" }, { "extra.avatar": 1 })
+```
+
+**Erros comuns e causas**
+
+| Sintoma | Causa provável |
+| ------- | -------------- |
+| `save` retorna 500 / NPE | `png` presente mas o jogador (`_id`) não existe — `findById` retorna null e `p.extra.put` falha. Crie o jogador antes. |
+| `status: "error"` no retorno | `png` não casa `data:image/png;base64,...` (formato/prefixo inválido). |
+| Documento salvo mas sem `png_url`/`status` | `png` ausente ou `length <= 20` — imagem não foi processada. |
+| Nada é gravado, mas a chamada "passa" | `_id` ausente no payload — `AvatarManager.save` faz no‑op silencioso. |
+| Imagem antiga continua na nuvem após DELETE | Tenant em Azure/Google — DELETE só remove via S3 (não cloud‑aware). |
+| `download_temp_image` sempre retorna "error" | Caminho local fixo inexistente no deploy de nuvem. |
+| Triggers/auditoria de Player disparando "do nada" | Upload de avatar chama `PlayerManager.insert` e dispara o ciclo de atualização do jogador. |
+
+---
+
+## 10. Exemplos Práticos
+
+### 10.1 Exemplo mínimo funcional (documento sem imagem)
+
+Grava metadados de avatar sem upload de imagem. Útil para guardar configuração de avatar gerado no cliente.
+
+```http
+POST /v3/avatar
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{ "_id": "player123", "skin": "default", "hat": "none" }
+```
+
+→ documento `{ _id, skin, hat }` salvo na coleção `avatar`. Sem efeito colateral em `player`.
+
+### 10.2 Exemplo avançado (upload de imagem PNG)
+
+```http
+POST /v3/avatar
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{
+  "_id": "me",
+  "png": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
+}
+```
+
+→ resolve `me` para o player do token, faz upload do PNG, grava `png_url` + `status:"saved"` no documento, escreve `player.extra.avatar` e **dispara `PlayerManager.insert`** (triggers + auditoria do jogador).
+
+### 10.3 Anti‑pattern (o que NÃO fazer)
+
+❌ **Confiar no `save_ready_image`/`save_temp_image` para popular a coleção `avatar`.**
+Esses endpoints gravam **somente** `player.extra.avatar` — `GET /v3/avatar/{id}` retornará vazio. Use `POST /v3/avatar` (JSON) se você precisa do documento na coleção.
+
+❌ **Reenviar o `png` (data‑URI) a cada `GET`/`PUT`.**
+O `png` não é removido antes de persistir; reenviá‑lo incha o documento com a imagem base64 duplicada (já existe `png_url`). Envie `png` apenas quando a imagem mudar; para metadados, omita `png`.
+
+❌ **Esperar atomicidade.**
+Não há transação. Se o `save` do documento falhar após o upload, a imagem na nuvem e a atualização do jogador permanecem. Trate a operação como eventualmente consistente.
+
+❌ **Usar `q`/`orderby`/`fields` com entrada de usuário não confiável.**
+São concatenados crus no pipeline — injeção NoSQL. Valide/allow‑liste no seu backend antes de repassar.
+
+---
+
+## Checklist de Configuração
 
-- [ ] Avatar padrão é exibido para novos jogadores
-- [ ] Acessórios desbloqueados aparecem disponíveis
-- [ ] Personalização do avatar é salva corretamente
+- [ ] **`_id` preenchido** no payload do `POST /v3/avatar` — sem ele o save é um no‑op silencioso.
+- [ ] **Jogador existe** antes de enviar `png` — `png` + jogador inexistente = NPE.
+- [ ] **Formato da imagem** é exatamente `data:image/png;base64,...` (SVG não é processado no endpoint JSON).
+- [ ] **`png` com mais de 20 caracteres** — abaixo disso é ignorado sem erro.
+- [ ] **Ciente do efeito colateral:** salvar imagem dispara `PlayerManager.insert` (triggers + auditoria do Player).
+- [ ] **Provedor de nuvem** (`getCloud()`) configurado corretamente — DELETE só é cloud‑aware para S3.
+- [ ] **Armadilha:** omitir campos no `save` os remove do documento (full replace, não patch).
+- [ ] **Armadilha:** reenviar `png` grava o base64 inteiro no MongoDB ao lado de `png_url`.
+- [ ] **Segurança:** sanitizar/allow‑listar `q`, `fields`, `orderby` antes de expor o `findAll` a clientes não confiáveis.