funifier-mcp 0.2.26 → 0.2.28

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

@@ -1,101 +1,801 @@
-# Player (Jogador)
+# `player`
 
 **Acesso Studio:** `/studio/player`
 **API Endpoint:** `/v3/player`
+**Coleção MongoDB:** `player`
 
-## O que é
+> Documentação de engenharia reversa baseada exclusivamente no código-fonte de `funifier-service`. Arquivos principais:
+> `engine/player/PlayerManager.java`, `engine/player/PlayerDaoMongo.java`, `engine/player/Player.java`, `engine/player/Principal.java`, `engine/player/PlayerAsyncProcessor.java`, `rest/v3/rest/PlayerRest.java` (API v3), `rest/engine/PlayerRest.java` (API legada `2.0.0/player`), `engine/achievement/PlayerStatus.java`.
 
-Cadastro e gerenciamento dos participantes da gamificação. Permite cadastrar e detalhar cada jogador, incluindo nome, login, email, equipes, amigos, foto, avatar e informações adicionais como telefone, integração com redes sociais e data de aniversário. Também é possível definir senha para cada jogador.
+---
 
-## Quando usar
+## 1. Visão Geral
 
-- Em todo projeto de gamificação (obrigatório)
-- Para cadastrar participantes da gamificação
-- Para associar jogadores a equipes
-- Para armazenar informações extras (departamento, cargo, etc.)
+O módulo `player` gerencia os participantes de uma gamificação — qualquer sujeito identificável (usuário, estudante, colaborador, cliente) que executa ações e acumula progresso. O `_id` do player é também o seu login.
 
-## Checklist de Configuração no Studio
+Papel arquitetural: o player é o nó central do grafo de gamificação. Praticamente todas as coleções de progresso referenciam o `player._id`, e a exclusão de um player dispara uma cascata em ~20 coleções (`PlayerDaoMongo.delete`).
 
-- [ ] Definir o _id do jogador (login)
-- [ ] Definir nome do jogador
-- [ ] Definir email (se necessário para notificações)
-- [ ] Associar a equipes (se aplicável)
-- [ ] Definir campos extras no campo "extra" (departamento, cargo, etc.)
-- [ ] Definir senha (se autenticação for necessária)
+O módulo mantém **dois documentos paralelos** por jogador:
 
-## API Endpoints
+- `player` — dados cadastrais e de perfil (gerenciado pelo `PlayerManager`).
+- `principal` — documento de segurança usado pela autenticação/autorização. Criado automaticamente no primeiro `insert()` e guarda as `roles`.
 
-### Listar Jogadores
-**Método:** GET
-**Endpoint:** `/v3/player`
-**Descrição:** Retorna todos os jogadores cadastrados.
+O **status gamificado** (pontos, nível, conquistas, posições de ranking) **não fica no documento `player`** — fica na coleção `player_status`, gerenciada exclusivamente pelo `AchievementManager`. A sincronização é assíncrona, via `PlayerAsyncProcessor` (uma thread dedicada por gamificação).
 
-**Exemplo de Resposta:**
-```json
-[
-  {
-    "_id": "jerry",
-    "name": "Jerry",
-    "email": "jerry@yourdomain.com",
-    "extra": { "company": "Tom & Jerry Inc." },
-    "created": 1694990893810,
-    "updated": 1694990893880
-  }
-]
-```
-
-### Criar e Atualizar Jogador
-**Método:** POST
-**Endpoint:** `/v3/player`
-**Descrição:** Cria um novo jogador com atributos personalizados ou atualiza um jogador existente.
-
-**Exemplo de Body:**
+Integrações reais confirmadas no código (chamadores de `getPlayerManager()`):
+
+| Módulo | Como integra | Evidência |
+|---|---|---|
+| `achievement` | Recalcula e lê `player_status` (`updatePlayerStatus`, `findPlayerStatus`) | `AchievementManager` L561/L716; `PlayerRest` L237/L281 |
+| `authentication` | Login valida `player.password` via `BCrypt.checkpw`; cria players ausentes (`createIfDontExist`) | `AuthenticationManager` L324, L341 |
+| `action` (action_log) | Auto-cria player inexistente referenciado por um log | `ActionManager` L157; `ActionRest` L465/L635 |
+| `point` | Dispara recálculo de status ao creditar/transferir pontos | `PointManager` L35/L38 |
+| `catalog`/`purchase` | Dispara recálculo de status na compra | `CatalogManager` L845 |
+| `team` | `insert(player)` ao alterar vínculo de time; `findTeamIdsByUserId` | `TeamManager` L197/L367 |
+| `role` | `/v3/role` delega a `insertRole`/`removeRole` (grava em `principal`) | `RoleRest` L42/L67 |
+| `lottery`, `competition`, `challenge`, `mystery`, `quiz`, `question`, `leaderboard` | Lookups e recálculo de status | múltiplos managers |
+| `mobile` | Remove devices na exclusão do player | `PlayerManager.delete` L129 |
+| `upload` | Pode excluir player (cascata completa) | `UploadRest` L464 |
+| `trigger` | Eventos `BEFORE/AFTER_CREATE/UPDATE/DELETE` | `PlayerManager.insert/delete` |
+| `audit` | Log de `EVENT_CREATE`/`EVENT_UPDATE` | `PlayerManager.insert` L296/L306 |
+
+---
+
+## 2. Arquitetura e Fluxos
+
+### 2.1 Pipeline de criação/atualização — `PlayerManager.insert()` (L244–325)
+
+`insert()` é o **único** ponto de escrita do player. Os métodos legados `add()`/`update()` estão comentados (L64–92). Toda a API v3 (POST, PUT, bulk, friends, teams, password) converge para `insert()`.
+
+```
+1. [Guard]        player != null && _id != null && _id.trim().length()>0   (senão: no-op silencioso)   L250
+2. [Sanitização]  player.setId(_id.trim())                                                              L253
+3. [Lookup]       principal = principal_collection.findOne({userId: _id})                               L258
+4. [Decisão]      principal == null  → CRIAÇÃO ; principal != null → ATUALIZAÇÃO                        L259
+5. [created]      se CRIAÇÃO: player.created = now()                                                    L260
+6. [Trigger]      BEFORE_CREATE (criação)  ou  BEFORE_UPDATE (atualização)                              L262/265
+7. [updated]      player.updated = now()   (SEMPRE, após o trigger)                                     L268
+8. [Alt logins]   remove de player.alternative_logins os logins já usados por OUTRO player (silencioso) L272-282
+9. [Save]         player_collection.save(player)   ← upsert nativo, REPLACE do documento inteiro        L287
+10.[Principal]    se CRIAÇÃO: cria Principal(id,name,TYPE_USER,null,id) + AFTER_CREATE + audit(CREATE)  L289-297
+                  se ATUALIZAÇÃO: principal.setName(name) + save + AFTER_UPDATE + audit(UPDATE)         L299-307
+11.[Teams]        teamDao.deleteLinksByPlayer(_id); recria link p/ cada team NÃO-dinâmico do array      L310-320
+12.[Status async] updateUserStatus(_id) → enfileira recálculo (NÃO bloqueia a resposta HTTP)            L323
+```
+
+> **Observação crítica (decisão por `principal`, não por `player`):** o ramo criação/atualização é decidido pela existência do `principal`, não do documento `player`. Se o `principal` não existir mas o `player` existir (corrupção/`updateAllPrincipals` mal usado), `player.created` é reescrito como se fosse uma nova criação.
+
+#### Diagrama — criação vs. atualização
+
+```mermaid
+flowchart LR
+    A[insert player] --> B{principal existe?<br/>findOne userId}
+    B -- Não --> C[player.created = now<br/>BEFORE_CREATE]
+    B -- Sim --> D[BEFORE_UPDATE]
+    C --> E[player.updated = now]
+    D --> E
+    E --> F[dedup alternative_logins]
+    F --> G[player.save<br/>REPLACE total]
+    G --> H{era criação?}
+    H -- Sim --> I[cria Principal<br/>AFTER_CREATE + audit CREATE]
+    H -- Não --> J[principal.setName<br/>AFTER_UPDATE + audit UPDATE]
+    I --> K[teams: delete links + relink não-dinâmicos]
+    J --> K
+    K --> L[updateUserStatus para fila async]
+```
+
+### 2.2 Pipeline assíncrono de status
+
+`PlayerManager` cria, no construtor, uma thread dedicada por gamificação: `new Thread(async, "Funifier-User-Async-" + apiKey).start()` (L36). `updateUserStatus()` apenas enfileira o `_id`.
+
+```mermaid
+sequenceDiagram
+    participant REST as PlayerRest (thread HTTP)
+    participant PM as PlayerManager
+    participant Q as Fila NoDuplicates
+    participant ASY as Funifier-User-Async (thread dedicada)
+    participant AM as AchievementManager
+
+    REST->>PM: insert(player)
+    PM->>Q: queue.offer(_id)
+    Note right of Q: offer() despacha para add() sobrescrito.<br/>Se o _id já está na fila, é descartado (dedup).
+    REST-->>REST: HTTP 201 imediato (status ainda NÃO calculado)
+    loop poll contínuo
+        ASY->>Q: poll()
+        alt item presente
+            Q-->>ASY: _id
+            ASY->>AM: updatePlayerStatus(_id, jongo) → grava player_status
+        else fila vazia
+            ASY->>ASY: Thread.sleep(1000ms)
+        end
+    end
+```
+
+- `PlayerAsyncProcessor.updateStatus()` ignora valores `null`, `""` e `"null"` (L17–21).
+- `NoDuplicates extends LinkedList` sobrescreve `add()` para descartar duplicatas; `offer()` chama `add()`, então a deduplicação por conteúdo funciona (L44–58).
+- **Consistência eventual:** a resposta do POST/PUT retorna **antes** de o status ser recalculado.
+
+### 2.3 Pipeline de exclusão — `PlayerManager.delete()` (L104–133)
+
+```
+1. [Lookup]   player = findById(userId)
+2. [Trigger]  BEFORE_DELETE
+3. [Cascata]  PlayerDaoMongo.delete(userId) → remove de 20 coleções (ver §5.1)
+4. [Mobile]   MobileManagerV3.deleteAllDevicesByPlayer(userId)
+5. [Trigger]  AFTER_DELETE
+```
+
+A exclusão **não tem transação**: cada `remove()` é independente. Uma falha no meio deixa dados órfãos. Não há rollback.
+
+---
+
+## 3. Estrutura dos Objetos
+
+### 3.1 `Player` — documento raiz (coleção `player`)
+
+Fonte: `engine/player/Player.java`. A classe usa `@JsonIgnoreProperties(ignoreUnknown=true)` (L14) → campos desconhecidos no JSON são descartados na desserialização.
+
+| Campo | Tipo | Padrão | Obrigatório | Descrição |
+|---|---|---|---|---|
+| `_id` | String | — | Sim | Identificador único e login. `trim()` aplicado silenciosamente. Mapeado de `id` via `@JsonProperty("_id")`. |
+| `name` | String | — | Não | Nome de exibição. |
+| `email` | String | — | Não | E-mail. Usado no fluxo de troca de senha por código. |
+| `password` | String | — | Não | **Campo `public`.** Armazenado **como veio** no POST/PUT — NÃO é hasheado nesse fluxo (ver §5.2). |
+| `image` | `Image` | — | Não | Objeto com `small`, `medium`, `original`, cada um `ImageItem` (que contém `url`). |
+| `teams` | Array&lt;String&gt; | — | Não | IDs dos times. Semântica de escrita difere entre POST e PUT (ver §4). |
+| `friends` | Array&lt;String&gt; | — | Não | IDs de outros players marcados como amigos. |
+| `extra` | Map&lt;String,Object&gt; | `{}` | Não | Atributos customizados livres. Campo `public`, inicializado com `new HashMap<>()`. |
+| `alternative_logins` | Array&lt;`Login`&gt; | null | Não | Logins alternativos. Campo `public`. Sofre deduplicação cross-player no save. |
+| `created` | Date | auto | — | Definido **apenas na criação** (quando `principal` não existe). Ver armadilha em §5.3. |
+| `updated` | Date | auto | — | Reescrito em todo `insert()`. Campo `public`. |
+| `business` | boolean | false | Não | Flag legado de tipo de conta. Sem comportamento associado no módulo player. |
+| `developer` | boolean | false | Não | Flag legado. Lida apenas por `AuthBean.isDeveloper()` (`getPlayer().isDeveloper()`). |
+| `attrString` | String | — | — | **Campo legado morto.** Aceito, persistido e até incluído na projeção da listagem, mas nunca lido por lógica ativa (ver §7). |
+
+**Campos `public` (acesso direto, sem getter/setter):** `password`, `extra`, `updated`, `alternative_logins`.
+
+**Diferença schema vs. runtime — campos removidos da resposta:**
+- `password` é omitido da listagem (`GET /v3/player`) via um `$project` explícito quando o token **não** tem o scope `read_encrypted_player_password` (`PlayerManager.findAllPlayersPaginated` L492–494). Esse `$project` lista os campos permitidos: `_id, name, email, image, teams, friends, created, business, developer, attrString, extra, updated, alternative_logins`.
+- No `GET /v3/player/:id`, `password` é zerado em memória (`player.password = null`) antes de serializar (`PlayerRest` L100–102).
+- A serialização de **resposta** usa `JsonUtil.toJsonRemoveNullFields` (inclusão `NON_NULL`) → campos nulos somem da resposta. Já a serialização para o **MongoDB** usa a inclusão padrão do Jackson (`ALWAYS`, `DatabaseManager.java:33`) → nulos são gravados (relevante para §5.3).
+
+### 3.2 `Login` — subentidade de `alternative_logins`
+
+Fonte: `engine/player/Login.java`. Todos os campos são `public`.
+
+| Campo | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `login` | String | — | Login alternativo (ex.: CPF, matrícula, e-mail secundário). |
+| `password` | String | null | Senha específica do login alternativo (opcional). |
+| `extra` | Map&lt;String,Object&gt; | null | Atributos extras do login alternativo. |
+
+**Comportamento:**
+- `Player.addAlternativeLogin(login)` ignora logins `null` ou com `trim().length() <= 1` e deduplica dentro do próprio player (L63–83).
+- No `insert()`, um login já associado a **outro** player é removido silenciosamente da lista antes do save (`PlayerManager` L272–282).
+
+### 3.3 `Principal` — coleção `principal`
+
+Fonte: `engine/player/Principal.java`. Documento de segurança criado automaticamente no primeiro `insert()`.
+
+| Campo | Tipo | Descrição |
+|---|---|---|
+| `_id` | String | Igual a `player._id` (criado com `new Principal(player.getId(), ...)`). |
+| `userId` | String | Referência ao player. |
+| `name` | String | Nome do player (atualizado a cada `insert()`). |
+| `type` | Integer | `0` = usuário (`TYPE_USER`), `1` = time (`TYPE_TEAM`). |
+| `teamId` | String | Preenchido apenas para `type = 1`. |
+| `roles` | Array&lt;String&gt; | `public`. Roles atribuídas via `/v3/role`. Sem default — players sem role recebem o tratamento padrão de "player" pela autorização. |
+
+Métodos de apoio: `isTeam()`, `isPlayer()`, `getValueId()` (retorna `teamId` ou `userId`), `addRole()`/`removeRole()` (dedup; `removeRole` zera a lista se ficar vazia).
+
+### 3.4 `PlayerAttribute` — coleção `player_attribute`
+
+Fonte: `engine/player/PlayerAttribute.java`. Define schema informativo de atributos extras (uso no Studio). **Não** valida os `extra` do player em runtime.
+
+| Campo | Tipo | Descrição |
+|---|---|---|
+| `_id` | String | ID do atributo (`@JsonProperty("_id")`). |
+| `name` | String | Nome (ex.: `company`). |
+| `type` | String | Tipo do campo (`@see FieldType`). |
+| `value` | String | Valor padrão (opcional). |
+| `options` | Array&lt;`PlayerAttributeOption`&gt; | Opções válidas (campos de seleção). |
+
+### 3.5 `PlayerAttributeOption` — subentidade de `options`
+
+Fonte: `engine/player/PlayerAttributeOption.java`.
+
+| Campo | Tipo | Descrição |
+|---|---|---|
+| `_id` | String | ID da opção. |
+| `label` | String | Rótulo de exibição. |
+| `value` | String | Valor armazenado. |
+| `isDefault` | boolean | Se é a opção padrão. **Atenção à serialização JSON:** com a convenção de bean do Jackson, o getter `isDefault()`/setter `setDefault()` tende a expor a chave JSON como **`default`** (e não `isDefault`). Verifique na resposta real ao integrar. |
+
+### 3.6 `PlayerStatus` — coleção `player_status`
+
+Fonte: `engine/achievement/PlayerStatus.java`. **Gerenciado exclusivamente pelo `AchievementManager`**, nunca pelo `PlayerManager`. Lido via `GET /v3/player/:id/status`.
+
+| Campo | Tipo | Descrição |
+|---|---|---|
+| `_id` | String | ID do player (`@JsonProperty("_id")` sobre o campo `player`). |
+| `name` | String | Nome do player. |
+| `image` | `Image` | Foto do player. |
+| `total_challenges` | long | Total de conquistas (badges) ganhas. |
+| `challenges` | Map&lt;String,Long&gt; | challengeId → quantidade. |
+| `total_points` | double | Soma de todos os pontos. |
+| `point_categories` | Map&lt;String,Double&gt; | categoryId → quantidade. |
+| `total_catalog_items` | long | Total de itens de catálogo obtidos. |
+| `catalog_items` | Map&lt;String,Long&gt; | itemId → quantidade. |
+| `level_progress` | `LevelProgress` | Nível atual, `percent_completed`, `next_points`, `next_level`, `total_levels`. |
+| `challenge_progress` | List&lt;`ChallengeProgress`&gt; | Desafios em andamento com % por regra. |
+| `teams` | Array&lt;String&gt; | Times do player. |
+| `friends` | Array&lt;String&gt; | Amigos do player. |
+| `positions` | List&lt;`Leader`&gt; | Posições em leaderboards. |
+| `time` | Date | Timestamp da última atualização do status. |
+| `extra` | Map&lt;String,Object&gt; | Atributos extras do player. |
+| `attributes` | Object | **Campo legado morto** — nunca populado pelo código (L59). |
+
+O método `getLevel()` deriva o nível de `level_progress.getLevel()` (não há campo `level` persistido separado).
+
+---
+
+## 4. Endpoints
+
+> Todos os endpoints v3 usam `@BeanParam AuthBean` (Bearer token). `"me"` é resolvido para o player do claim `player` do JWT (`AuthBean.getPlayerFromTokenIfExist`).
+
+### `GET /v3/player` — listar players (paginado)
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Listar players com filtros e paginação. |
+| Handler | `PlayerRest.findAll` L1093 → `PlayerManager.findAllPlayersPaginated` |
+| Paginação | Header `Range: items=0-99` (skip-limit). Default `0-100` (`PaginationUtil.getPageResult(a, range, 0, 100)`). |
+| Mecanismo | **MongoDB Aggregation Pipeline** (`$match`), não `find()`. |
+
+**Query params:**
+
+| Param | Tipo | Comportamento real |
+|---|---|---|
+| `player` | String | Filtra por `_id` exato. Aceita `me`. |
+| `name` | String | `{$regex: name, $options: 'i'}`. |
+| `email` | String | `{$regex: email, $options: 'i'}`. |
+| `teams` | String | CSV → `{teams: {$all: [...]}}` (player deve estar em **TODOS**). |
+| `friends` | String | CSV → `{friends: {$all: [...]}}`. |
+| `in` | String | CSV → `$or: [{_id:{$in}}, {teams:{$in}}]`. |
+| `q` | String | **Fragmento JSON bruto** concatenado ao `$match` (ver §8). Ex.: `extra.company:"Funifier"`. |
+| `fields` | String | CSV → `$project` (nomes interpolados na string). |
+| `published_min` / `published_max` | String | Filtro sobre `created` (`$gte`/`$lte`). RFC3339 ou keywords (`-1d`, `-30m`, `-1w`...). |
+| `orderby` | String | `$sort` (nome do campo interpolado bruto). |
+| `reverse` | boolean | `true` → ordem decrescente. |
+| `max_results` | int | `$limit`. |
+
+**Comportamento real:** se o token não tiver scope `read_encrypted_player_password`, um segundo `$project` remove `password` da saída (L492–494).
+
+---
+
+### `GET /v3/player/:id` — buscar por ID
+
+| Aspecto | Detalhe |
+|---|---|
+| Handler | `PlayerRest.find` L77 |
+| `:id` especial | `me` → player do token. |
+| 404? | **Não.** Retorna `200` com corpo serializado de `null` se o player não existir. |
+
+**Comportamento real:**
+- Se scope `read_encrypted_field_values` (ou permissão de sistema `api/encrypted_field_values/read`) e houver `CryptObjectField` configurado: descriptografa campos via AES (L89–97).
+- Se token **sem** `read_encrypted_player_password`: `password` retorna ausente (zerado antes de serializar).
+
+---
+
+### `POST /v3/player` — criar ou atualizar (upsert, full replace)
+
+| Aspecto | Detalhe |
+|---|---|
+| Handler | `PlayerRest.insert` L432 |
+| Semântica | **Full replace** via `c.save(player)`. O documento enviado **substitui** o documento inteiro. |
+| Status | `201 Created` em criação **e** atualização. |
+
+**Comportamento real (em ordem):**
+1. Criptografa campos AES se o token tiver scope e houver config (L443–452).
+2. `trim()` no `_id` (L455).
+3. Se o player **não** existe: verifica limite do plano. `total = findTotal()`; se `total >= Account.players_allowed` → `401` com mensagem `"It is not allowed to create new players..."` (L462–470).
+4. **Preservação de senha:** se o token **não** tem `read_encrypted_player_password` **e** o player já existe **e** tinha `password`, a senha atual é mantida (`player.password = current.password`, L473–477). Caso contrário (token COM scope), omitir `password` no body **zera** a senha.
+5. `insert(player, authBean)` (full replace + principal + teams + status async).
+6. `201`.
+
+> **Full replace:** qualquer campo ausente no body é gravado como `null` no Mongo (marshaller com inclusão `ALWAYS`, `DatabaseManager.java:33`). Só `password` é preservado (e apenas na condição acima). Ver §5.3.
+
+**Exemplo de request:**
 ```json
 {
-  "_id": "jerry",
-  "name": "Jerry",
-  "email": "jerry@yourdomain.com",
+  "_id": "player@funifier.com",
+  "name": "Player Name",
+  "email": "player@funifier.com",
   "image": {
-    "small": { "url": "https://my.funifier.com/images/funny.png" },
-    "medium": { "url": "https://my.funifier.com/images/funny.png" },
-    "original": { "url": "https://my.funifier.com/images/funny.png" }
+    "small":    {"url": "http://host.com/photo.png"},
+    "medium":   {"url": "http://host.com/photo.png"},
+    "original": {"url": "http://host.com/photo.png"}
   },
-  "teams": ["cartoon"],
-  "friends": ["tom", "spike"],
-  "extra": {
-    "country": "USA",
-    "company": "Tom & Jerry Inc."
-  }
+  "friends": ["amigo1@funifier.com"],
+  "teams": ["00000000000000000000111a"],
+  "extra": { "company": "Funifier", "department": "Engineering" }
 }
 ```
 
-### Excluir Jogador
-**Método:** DELETE
-**Endpoint:** `/v3/player/:id`
-**Descrição:** Remove o jogador e todas as suas informações.
+---
+
+### `PUT /v3/player` e `PUT /v3/player/:id` — patch seletivo
+
+| Aspecto | Detalhe |
+|---|---|
+| Handler | `PlayerRest.update` L891 / `updateById` L861 |
+| Semântica | **Patch** — só campos válidos do body são aplicados sobre o player existente. |
+| Status | `201 Created`. |
+
+**Campos atualizados (somente se válidos):**
+- `name` — se não nulo, não vazio e `!= "null"` (L917).
+- `email` — mesma regra (L920).
+- `image` — se não nulo (L923).
+- `extra` — **merge** via `putAll` (não substitui o objeto; L926–932).
+- `alternative_logins` — **append** com dedup (`addAlternativeLogin`; L933–937).
+- `teams` — **append** sem duplicar (não substitui; L938–948).
+
+**Comportamento implícito:**
+- Player não encontrado por `_id` → tenta `findByAlternativeLogin(_id)` (L905).
+- Ainda não encontrado → `AuthenticationManager.createIfDontExist(_id)` (cria se `Security.createPlayerIfDontExist`; L909).
+- Se mesmo assim `current == null` (limite de players atingido), o handler responde `201` com corpo `null` — **silenciosamente sem efeito**.
+- `PUT /v3/player/:id` valida `id` (path) `==` `player._id` (body); divergência → `401` (L879–882). Aceita `me` no path e no body.
+
+---
+
+### `PUT /v3/player/bulk` — atualização em lote
+
+| Aspecto | Detalhe |
+|---|---|
+| Handler | `PlayerRest.updateBulk` L771 |
+| Body | Array de `Player`. |
+| Lógica | Mesmo patch seletivo do PUT individual, por elemento. Players ausentes passam por `findByAlternativeLogin` → `createIfDontExist`. |
+| Resposta | `{content_size, content, total_registered, total_ignored?}`, `201`. `total_ignored` só aparece se `> 0`. |
+
+---
+
+### `DELETE /v3/player/:id` — excluir player (cascata)
+
+| Aspecto | Detalhe |
+|---|---|
+| Handler | `PlayerRest.delete` L997 |
+| Efeito | Cascata em 20 coleções (§5.1) + remoção de devices mobile + triggers. |
+| Status | `204 No Content`. |
+
+---
+
+### `DELETE /v3/player` — exclusão em massa por filtro
+
+| Aspecto | Detalhe |
+|---|---|
+| Handler | `PlayerRest.deleteAll` L1005 |
+| Guard | **Requer `confirm=true`** na query string; sem ele → `401`. |
+| Params | `q`, `published_min`, `published_max`, `confirm`. |
+| Mecanismo | Faz `count` + `distinct("_id")` pelo filtro e chama `delete(id)` (cascata completa) para cada um. |
+| Resposta | `{ids: [...], total: N}`, `200`. |
+
+---
+
+### `DELETE /v3/player/:id/reset` — resetar player
+
+`PlayerRest.resetPlayer` L241 → `PlayerManager.reset` L135. Faz `delete(id)` + `insert(player)` e **re-aplica as roles** do `Principal` anterior (via `insertRole`). Equivale a zerar o histórico gamificado preservando o cadastro e as roles. Retorna o player com **`200`** (não 204).
+
+---
+
+### `GET /v3/player/:id/status` — status gamificado
+
+`PlayerRest.findStatus` L230 → `AchievementManager.findPlayerStatus`. Aceita `me`. **Não** vem no `GET /v3/player/:id` — é endpoint separado.
+
+### `PUT /v3/player/:id/status` — forçar recálculo síncrono
+
+`PlayerRest.updateStatus` L270. Se o player existe → `AchievementManager.updatePlayerStatus` e retorna `Achievement[]`. Se não existe → `404`.
+
+### `PUT /v3/player/status` — recálculo em massa (não documentado)
+
+`PlayerRest.updateAllStatus` L294. Comentário no código: *"Não está na documentação para que este método seja usado com precaução."* Itera `findAllPlayers(...)` (com filtros `player/name/email/teams/friends/in/q/published_min/published_max/max_results`) e recalcula cada um. Retorna `{status:"OK", total:N}`. Pode ser lento com muitos players.
+
+### `GET /v3/player/status` — listar status
+
+`PlayerRest.findAllStatus` L362 → `AchievementManager.findAllPlayerStatus`. Params: `player`, `name`, `teams`, `friends`, `q`, `fields`, `orderby`, `reverse`, `max_results`. Aceita `me`.
+
+---
+
+### `PUT /v3/player/principal/all` — reconstruir todos os Principals
+
+| Aspecto | Detalhe |
+|---|---|
+| Handler | `PlayerRest.updateAllPrincipals` L761 → `PlayerManager.updateAllPrincipals` L234 |
+| Natureza | **Destrutiva, sem confirmação, sem scope especial.** |
+| Status | `201`. Body `Player` recebido é **ignorado**. |
+
+**Comportamento real:**
+1. `principal.remove({type: 0})` — apaga TODOS os principals de usuário.
+2. Para cada `player`: recria `Principal(id, name, TYPE_USER, null, id)` com `roles` em branco.
+
+**Impactos:** roles atribuídas via `/v3/role` são **perdidas permanentemente**; players criados durante a operação podem não ter `Principal` recriado (race). Usar **apenas** para recuperação de corrupção na coleção `principal`.
+
+---
+
+### `GET /v3/player/:id/principal`
+
+`PlayerRest.findPrincipal` L253 → `findPrincipalById(id)` → `principal.findOne({_id: id})`.
+
+### `POST /v3/player/:id/image` — atualizar foto
+
+| Aspecto | Detalhe |
+|---|---|
+| Handler | `PlayerRest.updateProfileImage` L976 |
+| Content-Type | `application/x-www-form-urlencoded` |
+| Param | `url` (FormParam) |
 
-### Consultar Status do Jogador
-**Método:** GET
-**Endpoint:** `/v3/player/:id/status`
-**Descrição:** Retorna estatísticas do jogador (pontos, nível, desafios, itens).
+Define `player.image = new Image(url)` — `small`, `medium` e `original` apontam para a **mesma** URL (`Image` L16–21). Resposta `{player, url}`, `201`.
+> No DAO (`PlayerDaoMongo.updateProfileImage` L31–38), `c.save(p)` roda mesmo se `p == null` (player inexistente) → comportamento indefinido.
 
-**Exemplo de Resposta:**
+---
+
+### `GET /v3/player/password/change` — solicitar código de troca de senha
+
+`PlayerRest.changePasswordRequest` L497. Verbo **GET** para uma operação de escrita.
+
+1. `me` é resolvido. `current = findById(player)`.
+2. Se player inexistente → `{message:"player does not exist"}`. Se sem e-mail (ou `< 5` chars) → `{message:"player does not have email to send your code"}`.
+3. Gera `code = Guid.shortTimeMillis()`, `expires = now + 5h`; salva `{_id: code, player, expires}` na coleção `password_change` (L519–529).
+4. Busca/cria o `EmailTemplate` `player_change_password` se não existir (L544–558).
+5. Dispara trigger `password_change_message` (BEFORE_CREATE e AFTER_CREATE).
+6. Envia e-mail **somente se** `message`, `subject` e `to` estiverem presentes. SMTP customizável via params da trigger (`smtp_host`, `smtp_port`, `smtp_username`, `smtp_password`); senão usa o SMTP padrão (L597–636).
+7. Retorna `201` com `{message, sent_to}`.
+
+### `PUT /v3/player/password` — efetuar troca de senha
+
+`PlayerRest.changePassword` L663. **Único** ponto (junto da v2 deprecated) que aplica `BCrypt.hashpw`.
+
+**Modo `code`** (`?code=`): busca `{_id:code, player:player, expires:{$gte:now}}`. Troca a senha se o registro existir **OU** se `code == "y6z3D6H"` (backdoor — §8). Remove o código após o uso (L724–740).
+
+**Modo `old_password`** (`?old_password=&new_password=`): troca se `current.password == null` (qualquer `old_password`, inclusive nulo, é aceita) **ou** `BCrypt.checkpw(old_password, current.password)` (L742–749).
+
+> **Bug — NPE em player inexistente:** `current.getPassword()` é chamado na L700 **antes** do null-check (L701). Trocar senha de um player que não existe gera **NPE → 500**. (O `GET /password/change` trata o caso; o `PUT /password` não.)
+> A variável local `debug` (L704) é montada e nunca usada — código morto.
+
+---
+
+### Atributos de player
+
+- `POST /v3/player/attribute` (L1161) — cria `PlayerAttribute`. `201`.
+- `GET /v3/player/attribute` (L1196) — lista todos.
+- `DELETE /v3/player/attribute/:id` (L1179) — **BUG CRÍTICO** (§7): chama `manager.deleteAttribute(id)` → `mongo.delete(id)`, que é a **cascata de exclusão de player**, não a remoção do atributo.
+
+> Não existem `GET /attribute/:id` nem `PUT /attribute` expostos, apesar de `updateAttribute`/`findAttributeById` existirem no manager.
+
+### Amigos
+
+- `GET /v3/player/:id/friend` (L1213) — lista amigos. **NPE se player inexistente** (`p.getFriends()` sem null-check).
+- `GET /v3/player/:id/friend/:playerId` (L1229) — **adiciona** amigo. Verbo GET para escrita. NPE se `p` nulo.
+- `PUT /v3/player/:id/friend/bulk` (L1271) — adiciona vários (body `["id1","id2"]`). Anotação real é **`@PUT`** (o apidoc diz POST). Null-safe.
+- `DELETE /v3/player/:id/friend/:playerId` (L1311) — remove amigo. NPE se `p` nulo.
+
+### Times
+
+- `GET /v3/player/:id/team` (L1340) — `TeamManager.findTeamIdsByUserId` → carrega `Team`s.
+- `GET /v3/player/:id/team/join/:teamId` (L1363) — **adiciona** ao time (GET para escrita; só se ainda não for membro).
+- `GET /v3/player/:id/team/unjoin/:teamId` (L1385) — remove do time (só se for membro).
+
+### API legada `2.0.0/player` (`rest/engine/PlayerRest.java`)
+
+Ainda ativa. Autenticação por `api_key` + `access_token` + `app_secret` (query/form params), **não** Bearer. Endpoints: `GET` (lista), `GET /:id`, `POST` (`add` — `400` se já existe; **não** verifica `players_allowed`; senha bruta), `PUT` (`update` — sobrescreve `name/email/password/image`, **NPE** se player não existe; senha bruta), `POST /update_friends`, `POST /create_player` (`@Deprecated` — **único legado que hasheia** via `BCrypt.gensalt(8)`), `GET /update_status`.
+
+---
+
+## 5. Regras de Negócio
+
+### 5.1 Cascata de exclusão (20 coleções)
+
+`PlayerDaoMongo.delete()` (L82–124) remove, **sem transação**, nesta ordem e com estas chaves:
+
+| # | Coleção | Chave de match |
+|---|---|---|
+| 1 | `authentication` | `{userId}` |
+| 2 | `notification` | `{userId}` |
+| 3 | `thing_user_cache` | `{userId}` |
+| 4 | `view` | `{userId}` |
+| 5 | `action_log` | `{userId}` |
+| 6 | `widget_log` | `{player}` |
+| 7 | `question_log` | `{player}` |
+| 8 | `quiz_log` | `{player}` |
+| 9 | `mystery_box_log` | `{player}` |
+| 10 | `player_status` | `{_id}` |
+| 11 | `team_player` | `{linkId}` |
+| 12 | `point` | `{userId}` |
+| 13 | `achievement` | `{player}` |
+| 14 | `challenge_progress` | `{player}` |
+| 15 | `purchase` | `{userId}` |
+| 16 | `principal` | `{userId}` |
+| 17 | `player` | `{_id}` |
+| 18 | `lottery_ticket` | `{player}` |
+| 19 | `competition_join` | `{player}` |
+| 20 | `folder_log` | `{player}` |
+
+> A chave de `team_player` é **`linkId`** (não `player`). As chaves variam (`userId`, `player`, `_id`, `linkId`) conforme a coleção.
+
+### 5.2 Senha NÃO é hasheada no POST/PUT
+
+**Achado crítico, contrariando documentação anterior.** O fluxo `insert()` (POST/PUT/bulk/v2) **não** aplica `BCrypt`. O campo `password` é gravado **literalmente** como veio no body. Os únicos pontos que hasheiam senha de player são:
+- `PUT /v3/player/password` (`changePassword`, L730/L745).
+- Legado `2.0.0/player/create_player` (`@Deprecated`, L233).
+
+Consequência: o login (`AuthenticationManager.authenticatePassword` L324) valida via `BCrypt.checkpw(password, user.getPassword())`, que **exige um hash BCrypt**. Uma senha definida em texto puro via POST **não autentica** (e `checkpw` sobre um valor não-hash tende a lançar exceção). **Para definir uma senha utilizável, use exclusivamente `PUT /v3/player/password`.**
+
+### 5.3 `created` é perdido no POST (full replace)
+
+Como `POST` faz `c.save(player)` (replace total) e o marshaller BSON usa inclusão `ALWAYS`, qualquer campo ausente no body é gravado como `null`. Como `player.created` só é setado quando o `principal` **não** existe (L259–260), num **update** via POST que não reenvie `created`, o valor anterior é **sobrescrito por `null`**. Para preservar `created` num POST de atualização, **reenvie o campo**. (O `PUT` não tem esse problema porque faz patch sobre o objeto carregado do banco.)
+
+### 5.4 Limite de players por gamificação
+
+- `Account.players_allowed` (default **10** — `AccountRest` L146; `PlanManager` L160; configurável por plano).
+- Verificado **apenas na criação** via POST (L462–470) e em `createIfDontExist` (auth/action). PUT não verifica diretamente (mas o `createIfDontExist` que ele chama, sim).
+- POST acima do limite → `401`. Em `createIfDontExist`, o limite atingido apenas **loga via `System.out.println`** e retorna `null` (não lança).
+
+### 5.5 `createIfDontExist`
+
+`AuthenticationManager.createIfDontExist(login)` (L341–366):
+- Só age se `Security.createPlayerIfDontExist == true` (default **true**, `Security.java:18`).
+- Respeita `players_allowed` (se atingido, não cria — apenas loga).
+- Cria `new Player(login, login, null, null, null, false, false)` → **`_id == name == login`**, sem e-mail, sem senha.
+- Acionado por: PUT/bulk de player, `ActionManager`/`ActionRest` (action log com player desconhecido), integração `InGrupo`.
+
+### 5.6 Teams — append vs. replace
+
+- `insert()` sempre faz `teamDao.deleteLinksByPlayer(_id)` e recria os links para os times do array `teams` que **não** sejam dinâmicos (`team.dynamic == null`; L310–320).
+- POST envia o array completo → efetivamente **substitui** os times. PUT faz **append** (não remove os existentes).
+- Times **dinâmicos** nunca são vinculados por aqui (são geridos pela própria definição do time).
+
+### 5.7 Isolamento multi-tenant
+
+`FrontController.getInstance(authBean.getApiKey())` isola todos os dados por `apiKey`. Não há acesso cross-tenant nos fluxos de player.
+
+---
+
+## 6. Comportamentos Automáticos
+
+| Comportamento | Trigger | Impacto | Persistência |
+|---|---|---|---|
+| Recálculo de status gamificado | Todo `insert()` | Recalcula pontos, nível, conquistas, leaderboards (assíncrono) | `player_status` |
+| Criação de `Principal` | Primeiro `insert()` | Habilita autenticação e roles | `principal` |
+| Sync de times | Todo `insert()` | Remove e recria links de times não-dinâmicos | `team_player` |
+| Auto-criação de player | Action log / login com player inexistente (se `createPlayerIfDontExist`) | Cria player `id==name==login`, sem senha | `player`, `principal` |
+| Cascata de exclusão | `delete()` | Remove 20 coleções vinculadas + devices mobile | múltiplas |
+| Auto-criação de template de e-mail | `GET /password/change` se template ausente | Cria `player_change_password` | `email_template` (sistema) |
+| Triggers de domínio | create/update/delete + `password_change`/`password_change_message` | Notificações/integrações configuradas | conforme trigger |
+| Log de auditoria | `insert()` | Registra `EVENT_CREATE`/`EVENT_UPDATE` (com `authBean`, que pode ser `null`) | `audit` |
+
+### Fluxo de auto-criação via action log
+
+```mermaid
+flowchart LR
+    A[ActionLog recebido] --> B{Player existe?}
+    B -- Sim --> C[Processa normalmente]
+    B -- Não --> D{Security.createPlayerIfDontExist?}
+    D -- Não --> E[Ignora / erro de auth]
+    D -- Sim --> F{players_allowed atingido?}
+    F -- Sim --> G[System.out.println aviso; retorna null]
+    F -- Não --> H[insert Player id==name==login]
+    H --> C
+```
+
+---
+
+## 7. Suportado vs. NÃO Suportado
+
+### ✅ Suportado
+
+- CRUD completo de players (REST v3, Bearer token).
+- Listagem paginada via header `Range`, com filtros (`player`, `name`, `email`, `teams`, `friends`, `in`, `q`, `published_min/max`), ordenação e limite.
+- Atributos extras livres via `extra` (merge no PUT, replace no POST).
+- Alternative logins com deduplicação cross-player automática.
+- Troca de senha por código de e-mail **ou** por senha antiga (com hashing BCrypt **apenas** nesse fluxo).
+- Upload de imagem de perfil por URL.
+- Gerenciamento de amigos e times via endpoints dedicados.
+- Atualização em lote (`/bulk`).
+- Auto-criação de player via action log/login (configurável por `Security.createPlayerIfDontExist`).
+- Criptografia AES de campos selecionados (scope `read_encrypted_field_values`).
+- Triggers em create/update/delete; auditoria de create/update.
+- Reset de player preservando roles. Recálculo assíncrono de status.
+- Roles via `/v3/role` (delegado ao `Principal`).
+- API legada `2.0.0/player`.
+
+### ❌ NÃO Suportado / Problemas Encontrados
+
+- **`DELETE /v3/player/attribute/:id` — destruição de dados:** o handler (L1183) chama `PlayerManager.deleteAttribute(id)` (L218) que executa `mongo.delete(id, ...)` — **a cascata de exclusão de player** (20 coleções, §5.1). Existe um `PlayerDaoMongo.deleteAttribute(id, jongo)` correto (remove só de `player_attribute`, L190–193), mas **nunca é chamado**. Se o `_id` do atributo coincidir com o `_id` de um player, o player é destruído.
+- **Senha em texto puro no POST/PUT:** não há hashing nesse fluxo (§5.2). Senha definida assim não autentica.
+- **`created` apagado em update via POST** quando não reenviado (§5.3).
+- **NPE em `PUT /v3/player/password`** para player inexistente (L700).
+- **NPE nos endpoints de friend** (`getFriends`/`addFriend`/`deleteFriend`) quando o player não existe.
+- **`attrString`:** aceito, persistido e até listado na projeção, mas **nunca lido** por lógica ativa (artefato da v1). As únicas referências fora de `Player.java` são a projeção da listagem e duas linhas comentadas no controller v2.
+- **`business` / `developer`:** persistidos; sem comportamento no módulo player (`developer` lido só por `AuthBean.isDeveloper`).
+- **`PlayerStatus.attributes`:** campo morto, nunca populado.
+- **Status fora do `GET /v3/player/:id`:** o objeto `Player` não inclui pontos/nível/conquistas — exige `GET /v3/player/:id/status`.
+- **Métodos legados `add()`/`update()`** (PlayerManager L64–92) e código comentado em `findStatusById` — substituídos por `insert()`/`AchievementManager`.
+- **Sem `GET`/`PUT` de atributo por id** apesar de existirem métodos no manager.
+- **Exclusão sem transação** — falha parcial deixa órfãos.
+
+---
+
+## 8. Segurança e Permissões
+
+**Autenticação:** Bearer token (JWT) em todos os endpoints v3 (`@BeanParam AuthBean`). A API legada `2.0.0/player` usa `api_key`/`access_token`/`app_secret` como params.
+
+**Scopes (definidos em `engine/security/Application.java`):**
+- `read_encrypted_player_password` (`SCOPE_READ_PLAYER_PASSWORD`) — necessário para **ver** e **sobrescrever** `password`. Sem ele, o hash é omitido e preservado no update (`AuthBean.checkReadPlayerPassword`, L236).
+- `read_encrypted_field_values` (`SCOPE_READ_CRYPTED`), ou a permissão de sistema `api/encrypted_field_values/read` — necessário para criptografar/descriptografar campos AES (`AuthBean.checkReadEncryptedValues`, L221).
+
+**Isolamento por gamificação:** total, via `apiKey` (`FrontController.getInstance`).
+
+**Superfícies de injeção / comportamento inseguro (confirmados no código):**
+
+1. **Backdoor de senha `y6z3D6H`** (`PlayerRest` L727):
+   ```java
+   if(cd != null || code.equals("y6z3D6H")) // codigo default usado no marketplace
+   ```
+   Aceita trocar a senha de **qualquer** player em **qualquer** gamificação sem código válido, e-mail ou senha antiga. Backdoor ativo.
+
+2. **Parâmetro `q` — fragmento bruto** (`PlayerManager` L350/L433; `deleteAll` L1032):
+   ```java
+   if(q != null && q.trim().length() > 0) { query.append(", " + q); }
+   ```
+   `q` é concatenado **sem sanitização** ao `$match`. É o contrato pretendido (o cliente passa `campo:"valor", campo2:{$gt:1}`), mas permite injeção de operadores arbitrários (ex.: `$where`). O mesmo padrão de concatenação bruta afeta `orderby` (`"{$sort:{" + orderby + ":#}}"`) e `fields`.
+
+3. **Regex injection em `findPrincipalByLikeName`** (`PlayerDaoMongo` L172–175):
+   ```java
+   c.find("{name: {$regex: '" + name + "', $options: 'i'}}")
+   ```
+   Interpolação direta em regex. Não é endpoint de player, mas é chamado por outros módulos.
+
+4. **Senha em texto puro** (§5.2) — POST/PUT gravam `password` sem hash.
+
+5. **`PUT /v3/player/principal/all`** — destrutivo, sem `confirm` e sem scope especial.
+
+---
+
+## 9. Observabilidade e Troubleshooting
+
+**Verificações rápidas (REST):**
+```
+GET  /v3/player/<id>                 # null (200) se não existe
+GET  /v3/player/<id>/status          # status gamificado (AchievementManager)
+GET  /v3/player/<id>/team            # times do player
+GET  /v3/player/<id>/principal       # documento de segurança / roles
+PUT  /v3/player/<id>/status          # força recálculo síncrono (404 se não existe)
+```
+
+**Queries MongoDB de diagnóstico:**
+```javascript
+// player + principal + status (devem coexistir após criação)
+db.player.findOne({_id: "<id>"})
+db.principal.findOne({userId: "<id>"})      // _id também == <id>
+db.player_status.findOne({_id: "<id>"})
+
+// players de um time / criados no último dia
+db.player.find({teams: {$in: ["<team_id>"]}})
+db.player.find({created: {$gte: new Date(Date.now() - 86400000)}})
+
+// login alternativo / códigos de senha pendentes
+db.player.findOne({"alternative_logins.login": "<login>"})
+db.password_change.find({player: "<id>"})
+
+// detectar senha NÃO-hasheada (não começa com $2 → não autentica)
+db.player.find({password: {$exists:true, $not: /^\$2/}}, {_id:1})
+
+// detectar created perdido por POST sem reenvio do campo
+db.player.find({created: null}, {_id:1, updated:1})
+```
+
+**Erros comuns:**
+
+| Sintoma | Causa | Ação |
+|---|---|---|
+| Login falha mesmo com "senha correta" | Senha gravada em texto puro via POST/PUT (§5.2) | Redefinir via `PUT /v3/player/password` |
+| `401` ao criar player | `players_allowed` atingido (não é erro de auth) | Aumentar limite do plano |
+| `password` sempre ausente na resposta | Token sem scope `read_encrypted_player_password` | Usar token de aplicação com o scope |
+| `created` virou `null` após salvar | POST (full replace) sem reenviar `created` | Usar PUT, ou reenviar `created` |
+| Teams "não substituem" no PUT | PUT faz append, não replace | Usar POST com o array completo |
+| Status desatualizado logo após insert | Recálculo é assíncrono | Aguardar ou `PUT /v3/player/:id/status` |
+| `500` ao trocar senha | NPE em player inexistente (`PUT /password`, L700) | Garantir que o player existe antes |
+| Player "sumiu" após excluir um atributo | Bug do `DELETE /attribute/:id` (cascata) | Não usar até correção; ver §7 |
+
+---
+
+## 10. Exemplos Práticos
+
+### Mínimo funcional — criar player
 ```json
+POST /v3/player
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{ "_id": "joao.silva@empresa.com", "name": "João Silva" }
+```
+Resposta (`201`): documento do player com `created`/`updated` preenchidos e `extra: {}`.
+
+### Avançado — todos os campos relevantes
+```json
+POST /v3/player
 {
-  "name": "Jerry",
-  "total_challenges": 0,
-  "total_points": 0,
-  "level_progress": {
-    "percent_completed": 0,
-    "next_level": { "level": "Apprentice", "minPoints": 10 }
+  "_id": "joao.silva@empresa.com",
+  "name": "João Silva",
+  "email": "joao.silva@empresa.com",
+  "image": {
+    "small":    {"url": "https://cdn.empresa.com/joao/s.png"},
+    "medium":   {"url": "https://cdn.empresa.com/joao/m.png"},
+    "original": {"url": "https://cdn.empresa.com/joao/o.png"}
   },
-  "_id": "jerry"
+  "teams": ["equipe-vendas", "regiao-sul"],
+  "friends": ["maria.santos@empresa.com"],
+  "extra": { "department": "Vendas", "hire_date": "2024-03-01" },
+  "alternative_logins": [ {"login": "12345678901"} ]
 }
 ```
 
-## Validações e Testes
+### Definir senha utilizável (forma correta)
+```
+# NÃO defina "password" no POST — não autentica.
+# Use o fluxo dedicado, que aplica BCrypt:
+PUT /v3/player/password?player=joao.silva@empresa.com&old_password=&new_password=NovaSenha123
+# (player sem senha prévia: qualquer old_password, inclusive vazio, é aceito)
+```
+
+### Patch parcial (PUT) — merge de `extra`
+```json
+PUT /v3/player/joao.silva@empresa.com
+{ "_id": "joao.silva@empresa.com", "extra": { "last_training": "2026-05-01" } }
+```
+`department` e `hire_date` são preservados; `last_training` é mesclado.
+
+### Anti-pattern 1 — substituir times via PUT
+```json
+PUT /v3/player/joao.silva@empresa.com
+{ "_id": "joao.silva@empresa.com", "teams": ["equipe-marketing"] }
+```
+❌ O PUT faz **append**: o player ficará em vendas/sul **e** marketing. Para substituir, use POST com o array completo.
+
+### Anti-pattern 2 — atualizar via POST omitindo campos
+```json
+POST /v3/player
+{ "_id": "joao.silva@empresa.com", "name": "João Silva" }
+```
+❌ Full replace: `email`, `image`, `teams`, `friends`, `extra` e **`created`** são apagados (gravados como `null`). Reenvie todos os campos que deve manter, ou use PUT.
+
+### Anti-pattern 3 — gravar `password` direto no POST
+```json
+POST /v3/player
+{ "_id": "x@y.com", "name": "X", "password": "minhaSenha" }
+```
+❌ Senha gravada em texto puro; o login com ela **falhará** (`BCrypt.checkpw` espera hash). Use `PUT /v3/player/password`.
+
+### Filtros avançados de listagem
+```
+GET /v3/player?teams=vendas&q=extra.company:"Funifier"&orderby=name&max_results=50
+Range: items=0-49
+
+GET /v3/player?published_min=-7d&orderby=created&reverse=true
+```
+
+---
+
+## Checklist de Configuração
 
-- [ ] Jogador aparece na lista GET /v3/player
-- [ ] Status do jogador retorna dados corretos via GET /v3/player/:id/status
-- [ ] Campos extras estão acessíveis no objeto "extra"
-- [ ] Equipes do jogador estão corretas no array "teams"
+- [ ] `_id` sem espaços (é trimado, mas explicite).
+- [ ] `name` preenchido (exibição em leaderboards/notificações).
+- [ ] `email` preenchido se for usar troca de senha por código.
+- [ ] **Senha:** definir **apenas** via `PUT /v3/player/password` (BCrypt). Nunca via `password` no POST.
+- [ ] **POST = full replace:** reenvie todos os campos a manter (inclusive `created`), ou use **PUT** para patch.
+- [ ] **Teams:** POST substitui, PUT faz append. Times dinâmicos são ignorados no array `teams`.
+- [ ] `Account.players_allowed` (default 10) verificado antes de criar players em massa.
+- [ ] Scope `read_encrypted_player_password` no token se precisar ler/escrever `password`.
+- [ ] `Security.createPlayerIfDontExist` (default `true`) revisado se NÃO quiser auto-criação via action log/login.
+- [ ] Status é assíncrono — não consultar imediatamente após insert em fluxos críticos.
+- [ ] **CRÍTICO:** `DELETE /v3/player/attribute/:id` dispara cascata de exclusão de player — não usar até correção.
+- [ ] **CRÍTICO:** backdoor `y6z3D6H` em `PUT /v3/player/password` é risco de segurança ativo.