funifier-mcp 0.2.26 → 0.2.27

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

@@ -1,28 +1,751 @@
-# Staging (Staging)
+# `staging`
 
-**Acesso Studio:** `/studio/integration/staging`
+**Acesso Studio:** `/studio/integration/staging` (rótulo de UI — ver nota arquitetural)
+**API Endpoint:** `/v3/gamification` (sub-rotas `/clone/*` e `/data/*`)
+**Coleção MongoDB:** não existe coleção `staging`. As operações atuam sobre a coleção `game` (banco do sistema Funifier) e sobre os bancos individuais por gamification (cada banco é nomeado pelo `apiKey` da gamification).
 
-## O que é
+> **Nota arquitetural — confirmada no código:** não existe rota `/v3/staging` no backend `funifier-service`. A busca por `staging` em `src/main/**.java` retorna **uma única ocorrência de produção**: o comentário `//staging : send selected data` em `GamificationRest.java:340`, imediatamente acima do endpoint `POST /v3/gamification/data/copy`. O módulo Studio chamado `staging` é, do ponto de vista do backend, um subconjunto de endpoints do recurso `/v3/gamification` (`clone/{id}`, `clone/remote`, `data/copy`, `data/diff`). O caminho `/studio/integration/staging` é o rótulo da UI do Studio (frontend) e **não é derivável deste repositório**.
 
-Gerenciamento de ambientes de homologação e produção, com clonagem e migração de dados. Permite criar e gerenciar ambientes de homologação (staging) separados do ambiente de produção. Possibilita clonar o ambiente produtivo para testes e migrar dados entre servidores.
+**Arquivos-fonte analisados:**
 
-## Quando usar
+| Arquivo | Papel |
+| --- | --- |
+| `src/main/java/com/funifier/rest/v3/rest/GamificationRest.java` | Resource JAX-RS (`@Path("v3/gamification")`) |
+| `src/main/java/com/funifier/engine/game/GameManager.java` | Manager — clone, copy, diff, copyDatabase, delete |
+| `src/main/java/com/funifier/engine/game/GameDaoMongo.java` | DAO Mongo da coleção `game` |
+| `src/main/java/com/funifier/engine/game/Game.java` | Entidade raiz (gamification) |
+| `src/main/java/com/funifier/engine/game/GameDataCopy.java` | DTO de payload para copy/diff |
+| `src/main/java/com/funifier/engine/packages/Component.java` | DTO de item individual de copy/diff |
+| `src/main/java/com/funifier/engine/game/GameUsage.java` | Subentidade de métricas de uso |
+| `src/main/java/com/funifier/rest/v3/AuthBean.java` | Resolução de credenciais, proxy e scope |
+| `src/main/java/com/funifier/engine/util/Entity.java` | Mapeamento enum → nome de coleção |
+| `src/main/java/com/funifier/engine/player/Principal.java` | `TYPE_USER = 0` |
+| `src/main/java/com/funifier/engine/account/Account.java` | Lista `games[]` e `games_allowed` |
 
-- Para testar novas funcionalidades sem impactar produção
-- Para validar atualizações antes do go-live
-- Para migrar dados entre servidores de diferentes regiões
-- Para criar ambientes espelho de produção
+> **NÃO localizado no código** (documentado na seção 7): não há Service dedicado (`StagingService`), Repository próprio, Scheduler/Job, enum de status, nem pipeline de aggregation específico de `staging`. Toda a lógica vive em `GamificationRest` + `GameManager`.
 
-## Checklist de Configuração no Studio
+---
 
-- [ ] Criar ambiente de staging
-- [ ] Clonar dados de produção para staging
-- [ ] Testar novas funcionalidades em staging
-- [ ] Migrar alterações aprovadas para produção
+## 1. Visão Geral
 
-## Validações e Testes
+O módulo `staging` fornece operações para tratar gamifications como **ambientes** (produção, homologação, backup) e mover configuração/dados entre eles. São quatro operações reais, todas no recurso `/v3/gamification`:
 
-- [ ] Ambiente de staging é criado corretamente
-- [ ] Dados são clonados sem perda
-- [ ] Alterações em staging não afetam produção
-- [ ] Migração para produção funciona
+1. **Clone** (`POST /clone/{id}`) — cópia integral de uma gamification (banco MongoDB inteiro), em três modos: mesma conta, conta diferente no mesmo servidor, ou servidor remoto.
+2. **Clone remoto — recepção** (`POST /clone/remote`) — endpoint interno chamado pelo servidor de origem durante o clone remoto.
+3. **Cópia seletiva de dados** (`POST /data/copy`) — copia documentos ou coleções inteiras de uma gamification para outra, na mesma conta.
+4. **Diff de dados** (`POST /data/diff`) — compara documentos entre duas gamifications da mesma conta e devolve um JSON Patch (RFC 6902).
+
+**Papel arquitetural:**
+- `clone` opera **no nível do banco MongoDB** (cópia de banco inteiro via `copydb` ou `$merge` por coleção).
+- `data/copy` e `data/diff` operam **coleção-a-coleção** e são restritos à **mesma conta** (`accountId`).
+- **Não há entidade "ambiente" persistida.** Não existe modelo de staging no banco. A relação origem→destino é informada em cada requisição (`source`/`target` ou path param + body).
+
+**Casos de uso típicos:**
+- Criar uma gamification de homologação a partir da produção.
+- Promover configurações específicas (`action`, `challenge`, `level`) entre ambientes.
+- Inspecionar diferenças de configuração antes de uma migração.
+- Migrar uma gamification para outro servidor/região Funifier.
+
+**Módulos/dependências relacionados:** `AccountManager` (validação de credenciais e limite de gamifications), `ManagerFactory` (obtém a conexão Jongo de cada gamification), `SchedulerManager`/`StaticManager`/`S3Service` (apenas no `delete`), `Guid` (geração de apiKey).
+
+---
+
+## 2. Arquitetura e Fluxos
+
+### 2.1 Pipeline — Clone local, mesma conta
+
+`GamificationRest.clone()` (linha 272) → `GameManager.clone()` (linha 184):
+
+```
+1. [Auth]   AccountManager.isAppSecretAllowed(apiKey, appSecret)        GamificationRest.java:276
+2. [Guard]  proxyEndpoint == null/vazio  → modo LOCAL                    GamificationRest.java:281
+3. [Guard]  gamification.accountId == null || == conta atual  → mesma conta   :285
+4. [Limit]  AccountManager.allowCreateMoreGamifications(account)         :286  (senão 401)
+5. GameManager.clone(id, gamification, removeLogs)                       :287
+     5.1  source = findByApiKey(id)                                      GameManager.java:185
+     5.2  gamification.accountId = accountId ?: source.accountId         :188
+     5.3  gamification.apiKey    = apiKey    ?: Guid.newShortGuid()      :189
+     5.4  add(gamification)   → salva em `game` + atualiza Account       :190
+     5.5  copyDatabase(source.apiKey, gamification.apiKey)               :194
+     5.6  se removeLogs == true (default): drop de coleções de runtime   :196-214
+6. HTTP 201 com a nova Game                                             GamificationRest.java:288
+```
+
+**`copyDatabase()` (linha 582) — detecção de versão do MongoDB:**
+
+```
+v = versão do MongoDB via comando admin "buildinfo"        GameManager.java:589-593
+se v[0] < 4 OU (v[0] == 4 E v[1] < 2):
+    comando admin "copydb" {fromdb, todb}      ← deprecated  :603-607
+senão:
+    para cada coleção do banco origem:
+        aggregate "{ $merge: { into: { db: toApiKey, coll: <col> } }}"  :616
+```
+
+> **Comportamento silencioso / falha:** se o `buildinfo` lançar exceção, `v` permanece `null` (capturado em try/catch vazio, `GameManager.java:594-596`) e a linha `if(v[0] < 4 ...)` (`:599`) lança **NullPointerException**. Não há fallback.
+
+### 2.2 Pipeline — Clone local, conta diferente
+
+Mesma rota, com header `X-Proxy-Authorization` e `gamification.accountId` diferente da conta atual (`GamificationRest.java:296-312`):
+
+```
+1. [Auth] isAppSecretAllowed(apiKey, appSecret)              ← conta de ORIGEM   :276
+2. [Auth] isAppSecretAllowed(proxyApiKey, proxyAppSecret)    ← conta de DESTINO  :298
+3. [Limit] allowCreateMoreGamifications(proxyAccount)        :301  (senão 401)
+4. GameManager.clone(id, gamification, removeLogs)           :302  (mesmo pipeline 2.1)
+```
+
+> As credenciais de proxy são extraídas do header `X-Proxy-Authorization` por `AuthBean.getProxyApiKey()` / `getProxyAppSecret()` (`AuthBean.java:127-160`).
+
+### 2.3 Pipeline — Clone remoto (outro servidor)
+
+Mesma rota, com `X-Proxy-Authorization` **e** `X-Proxy-Endpoint` (`GamificationRest.java:315-318`) → `GameManager.cloneRemoteSend()` (linha 231):
+
+```
+1. gamification.apiKey = apiKey ?: source.apiKey   ← mantém o MESMO apiKey da origem!   GameManager.java:244
+2. PASSO 1 — registrar a gamification remota:                                          :245
+     cloneRemoteRegisterGamificationHelper()  → POST {endpoint}/v3/gamification/clone/remote
+        body: { operation: "create_gamification", data: <Game> }                       :367-395
+3. PASSO 2 — enviar coleções de estrutura:                                             :249-280
+     blacklist = ["system.indexes"]  (+ coleções de log se removeLogs)                 :251-267
+     para cada coleção NÃO blacklistada:
+        cloneRemoteSaveCollectionHelper()  → lê em lotes e POSTa por lote               :275
+           buffer flush quando list.size() > 500  (ou seja, a cada 501 docs)           :302
+           POST {endpoint}/v3/gamification/clone/remote
+              body: { operation: "save_collection", apikey, collection, data: [...] }   :304-317
+4. Retorna { all: [coleções], out: [respostas OK], err: [erros] }                       :282-284
+```
+
+> **Acumulação de erros:** cada lote é envolto em try/catch (`:312`, `:345`); falhas vão para `err[]` e o processo **continua**. Nenhuma exceção interrompe o clone remoto — falhas parciais são silenciosas exceto pelo array `err`.
+
+#### Diagrama — Interação no clone remoto (`cloneRemoteSend`)
+
+```mermaid
+sequenceDiagram
+    participant C as Cliente
+    participant S as Servidor Origem<br/>(cloneRemoteSend)
+    participant R as Servidor Remoto<br/>(cloneRemoteReceive)
+    C->>S: POST /clone/{id}<br/>X-Proxy-Endpoint + X-Proxy-Authorization
+    S->>R: POST /clone/remote<br/>{operation: create_gamification, data}
+    R-->>S: {status: OK} ou 401
+    loop Para cada coleção não-blacklistada
+        loop Lotes de até 501 documentos
+            S->>R: POST /clone/remote<br/>{operation: save_collection, apikey, collection, data[]}
+            R-->>S: resposta (OK → out[], erro → err[])
+        end
+    end
+    S-->>C: 201 { all, out, err }
+```
+
+### 2.4 Pipeline — Recepção de clone remoto (`/clone/remote`)
+
+`GamificationRest.cloneRemote()` (linha 330) → `GameManager.cloneRemoteReceive()` (linha 400):
+
+```
+[Auth] isAppSecretAllowed(apiKey, appSecret)                            GamificationRest.java:331
+System.out.println(JsonUtil.toJson(source))   ← LOGA O PAYLOAD INTEIRO  GameManager.java:402
+operation == "create_gamification":                                     :405-420
+    gamification.accountId = accountId ?: account_da_requisicao         :409
+    current = findByApiKey(gamification.apiKey)                         :412
+    se current != null E current.accountId != account  → 401           :413-415
+    add(gamification)                                                    :417
+operation == "save_collection":                                         :421-451
+    current = findByApiKey(apikey)                                       :431
+    se current != null E current.accountId != account  → 401            :432-434
+    [!] collection é lida como String crua (source.get("collection"))   :427  (sem validação)
+    para cada doc: marshaller.marshall(o) → BasicDBObject.parse → c.save(doc)  :441-447
+```
+
+### 2.5 Pipeline — Cópia seletiva (`/data/copy`)
+
+`GamificationRest.dataCopy()` (linha 344) → `GameManager.copy()` (linha 457):
+
+```
+1. [Auth]  isAppSecretAllowed                                          GamificationRest.java:347
+2. [Guard] proxyEndpoint == null/vazio  (senão NO-OP, retorna {})      :350
+3. sourceGame = findByApiKey(data.source); targetGame = findByApiKey(data.target)   :352-353
+4. [Guard] source != null E target != null E target.accountId == source.accountId   :356
+           (senão NO-OP: retorna {} com HTTP 201, sem copiar nada)
+5. GameManager.copy(data)                                              :357
+     para cada Component item em data.items (que tenha id E type não-vazios):   GameManager.java:462-463
+        item.id == "*"  → aggregate "{ $merge: { into: { db: target, coll: type }}}"   :466
+        item.id != "*"  → obj = source.findOne({_id: id}); target.save(obj)            :471-472
+6. result.put("status","OK")  → HTTP 201                               GamificationRest.java:358
+```
+
+> **Sem try/catch no loop de `copy()`** (`GameManager.java:462-476`). Se um `item.id` específico não existir na origem, `findOne(...).as(Object.class)` retorna `null` e `target.save(null)` (`:472`) lança exceção — a requisição inteira falha **no meio da iteração**, deixando os itens anteriores já copiados. Diferente de `diff()`, não há proteção por item.
+
+### 2.6 Pipeline — Diff (`/data/diff`)
+
+`GamificationRest.dataDiff()` (linha 376) → `GameManager.diff()` (linha 481):
+
+```
+1-4. Mesmos guards de auth e mesma conta de data/copy   GamificationRest.java:379-388
+5. GameManager.diff(data)                               :389
+     para cada Component item (id E type não-vazios):                  GameManager.java:492-493
+        item.id == "*"  → source.find().limit(100)   ← LIMITE FIXO 100  :496
+            para cada doc: target.findOne({_id}); diffObjects(...)       :497-507
+        item.id != "*"  → source.findOne; target.findOne; diffObjects(...)  :512-516
+     cada chamada a diffObjects() é envolta em try/catch  :502-506, 515-519
+        → exceção apenas faz e.printStackTrace() e o item é DESCARTADO
+6. Retorna { source, target, diff: [...] }              :524
+```
+
+**`diffObjects(type, id, source, target)` (linha 533):**
+
+```
+resolve título (depende do type):                       GameManager.java:540-562
+    action          → source.get("action")
+    point_category  → source.get("category")
+    challenge       → source.get("challenge")
+    level           → source.get("level")
+    outros          → "title" ?: "name" ?: "label" ?: "_id"
+se source != null E target == null  → operations = "[op: create]"        :565-566
+senão                                → JsonDiff.asJsonPatch(target, source)  :571-577
+                                       (RFC 6902; só inclui se != "[]")
+```
+
+> **Deletions nunca são reportadas.** O bloco `else if(source == null && target != null) { "[op: delete]" }` está **comentado** (`GameManager.java:568-570`). Além disso, mesmo que fosse reativado, é **inalcançável**: quando `source == null` a resolução de título no topo (`source.get("action")`, `source.containsKey(...)`) lança NullPointerException antes de chegar lá; a exceção é capturada em `diff()` e o item é silenciosamente descartado. Documentos presentes só no `target` jamais aparecem no resultado.
+
+### 2.7 Diagrama — Modos de operação do clone
+
+```mermaid
+flowchart LR
+    A["POST /v3/gamification/clone/{id}"] --> AUTH{isAppSecretAllowed?}
+    AUTH -- não --> X401[401 UNAUTHORIZED]
+    AUTH -- sim --> B{X-Proxy-Endpoint?}
+    B -- "vazio (LOCAL)" --> C{accountId do body}
+    C -- "null ou conta atual" --> L1{allowCreateMore?}
+    L1 -- sim --> D["GameManager.clone()<br/>copyDatabase local"]
+    L1 -- não --> X401
+    C -- "conta diferente" --> E{Proxy auth válido?}
+    E -- sim --> L2{allowCreateMore proxy?}
+    L2 -- sim --> D
+    L2 -- não --> X401
+    E -- não --> X401
+    B -- "URL remota" --> G["GameManager.cloneRemoteSend()<br/>lotes HTTP de 501 docs"]
+    G --> H["POST remoto<br/>/v3/gamification/clone/remote"]
+```
+
+---
+
+## 3. Estrutura dos Objetos
+
+### 3.1 `Game` — documento raiz (coleção `game`)
+
+Mapeada por `Game.java`. `@JsonIgnoreProperties(ignoreUnknown=true)` — campos desconhecidos no JSON são silenciosamente ignorados na desserialização.
+
+| Campo | Tipo | Padrão | Obrigatório | Descrição |
+| --- | --- | --- | --- | --- |
+| `_id` | String | gerado | — | `apiKey` (anotado `@JsonProperty("_id")`). Também é o **nome do banco MongoDB** da gamification |
+| `created_at` | Date | servidor | — | Definido no primeiro save; preservado em updates via `add()` (`GameManager.java:95`) |
+| `updated_at` | Date | servidor | — | Sempre sobrescrito em cada save (`:99`) |
+| `templateId` | String | — | — | Referência a template de criação |
+| `inlineEditable` | boolean | `false` | — | Flag de edição inline no Studio |
+| `description` | String | — | — | Descrição livre |
+| `name` | String | — | — | Nome da gamification (não há validação de obrigatoriedade no backend) |
+| `accountId` | String | — | ✓* | Conta proprietária. *Definido pelo servidor em `insert`/`clone`; `add()` ignora a Game se `accountId == null` (`GameManager.java:77`) |
+| `image` | `Image` | — | — | Objeto com `small`, `medium`, `original` (cada um `ImageItem`) |
+| `extra` | `Map<String,Object>` | `{}` | — | Metadados extras livres |
+| `i18n` | `Map<String,Map<String,String>>` | `{}` | — | Strings de internacionalização |
+| `paying` | boolean | `false` | — | Flag de conta pagante |
+| `usage` | `List<GameUsage>` | `[]` | — | Configurações de métricas de uso |
+
+**Campos computados (não persistem como campo próprio):**
+- `getImageUrl()` (`Game.java:80-82`) — retorna `image.small.url`, ou `null`. É um getter derivado, não um campo armazenado.
+
+**Campos legados comentados no código-fonte (`Game.java:33-36, 84-100`):**
+- `imageUrl` (String) — substituído por `image`.
+- `timeZone` (String) — removido; getter/setter comentados.
+
+> Por estarem comentados, esses campos **não são desserializados nem persistidos**. Enviá-los no JSON é inócuo (ignorados por `@JsonIgnoreProperties`).
+
+### 3.2 `GameDataCopy` — payload de `data/copy` e `data/diff`
+
+`GameDataCopy.java`. `@JsonIgnoreProperties(ignoreUnknown=true)`.
+
+| Campo | Tipo | Obrigatório | Descrição |
+| --- | --- | --- | --- |
+| `source` | String | ✓ | apiKey da gamification de origem |
+| `target` | String | ✓ | apiKey da gamification de destino |
+| `items` | `List<Component>` | ✓ | Itens a copiar/comparar (default `[]`) |
+
+### 3.3 `Component` — item de copy/diff
+
+`Component.java`. `@JsonIgnoreProperties(ignoreUnknown=true)`.
+
+| Campo | Tipo | Obrigatório (runtime) | Descrição |
+| --- | --- | --- | --- |
+| `_id` | String | ✓ | ID do documento, ou `*` para a coleção inteira (`@JsonProperty("_id")`) |
+| `type` | String | ✓ | **Nome da coleção MongoDB** (ex.: `action`, `challenge`, `level`) |
+| `title` | String | — | Apenas rótulo — **ignorado** por `copy()` e `diff()` |
+| `content` | String | — | Apenas rótulo — **ignorado** por `copy()` e `diff()` |
+
+> Os javadocs em `Component.java` marcam todos os 4 campos como "required", mas o runtime só usa `id` e `type`: o loop em `copy()`/`diff()` exige `id` e `type` não-vazios (`GameManager.java:463`, `:493`) e ignora `title`/`content`. São aceitos pelo desserializador e servem apenas de label na UI.
+
+### 3.4 `GameUsage` — subentidade de métricas (`Game.usage[]`)
+
+`GameUsage.java`.
+
+| Campo | Tipo | Descrição |
+| --- | --- | --- |
+| `_id` | String | Identificador (`@JsonProperty("_id")`) |
+| `title` | String | Título da métrica |
+| `type` | String | `custom` ou `players_with_action_logs` (constantes `TYPE_CUSTOM`, `TYPE_PLAYERS_WITH_ACTION_LOGS`) |
+| `collection` | String | Coleção MongoDB onde o aggregate é executado (ex.: `player`) |
+| `aggregate` | String | Pipeline de aggregation; deve retornar um campo `total` |
+
+### 3.5 Coleções de runtime removidas no `clone` com `removeLogs=true`
+
+Nomes reais resolvidos via `Entity.java`. **11 coleções são dropadas** + remoção parcial em `principal`. A coleção `team` **NÃO** é removida (linha comentada).
+
+| Constante `Entity` | Coleção | Ação no clone LOCAL (`GameManager.java:199-213`) |
+| --- | --- | --- |
+| `PLAYER` | `player` | `drop()` |
+| `PLAYER_STATUS` | `player_status` | `drop()` |
+| `ACHIEVEMENT` | `achievement` | `drop()` |
+| `ACTION_LOG` | `action_log` | `drop()` |
+| `NOTIFICATION` | `notification` | `drop()` |
+| `LEADER` | `leader` | `drop()` |
+| `TEAM` | `team` | **não removida** (comentada, `:206`) |
+| `TEAM_PLAYER` | `team_player` | `drop()` |
+| `PRINCIPAL` | `principal` | `remove("{type:#}", 0)` — remove só `type == 0` (`TYPE_USER`); mantém os demais principals |
+| `LOTTERY_TICKET` | `lottery_ticket` | `drop()` |
+| `PROGRESS_LOG` | `progress_log` | `drop()` |
+| `CHALLENGE_PROGRESS` | `challenge_progress` | `drop()` |
+| `GAMIFICATION_STATUS` | `game_status` | `drop()` (enum `GAMIFICATION_STATUS` → coleção `game_status`, `Entity.java:140`) |
+
+> **`Principal.TYPE_USER = 0` é um inteiro** (`Principal.java:25`). A query real é `{type: 0}`, **não** `{type: "user"}`. Principals com `type != 0` (ex.: tipos de máquina/serviço) são preservados no clone local.
+
+> **Divergência local × remoto:** no clone **remoto** (`cloneRemoteSend`, `:262`) a coleção `principal` é colocada **inteira** na blacklist (não é enviada de jeito nenhum quando `removeLogs=true`), enquanto no clone **local** apenas `type == 0` é removido. Resultado: clone remoto com `removeLogs` perde **todos** os principals; clone local mantém os não-usuário.
+
+---
+
+## 4. Endpoints
+
+Todos sob `@Path("v3/gamification")` (`GamificationRest.java:35`), `Produces: application/json; charset=UTF-8`. As respostas passam por `JsonUtil.toJsonRemoveNullFields(...)` — **campos nulos são omitidos** do JSON de saída.
+
+### `GET /v3/gamification` — listar gamifications
+
+| Aspecto | Detalhe |
+| --- | --- |
+| Finalidade | Lista gamifications da conta autenticada (`findAllGamifications`, `:59`) |
+| Autenticação | `isAppSecretAllowed` (credenciais de conta); senão 401 |
+| Status sucesso | 200 OK |
+
+**Query params** (`GameManager.findAllByAccountId`, linha 647):
+
+| Param | Tipo | Comportamento real |
+| --- | --- | --- |
+| `name` | String | `{name: {$regex: <valor>}}` — match por regex |
+| `published_min` | String | RFC 3339 **ou** keyword (`-1d`, `-30m`, unidades `y M w d h m s`) → `created_at >= valor` (inclusivo) |
+| `published_max` | String | RFC 3339 ou keyword → `created_at <= valor` |
+| `orderby` | String | Campo de ordenação concatenado **cru** na query (`name`, `description`, `created_at`) |
+| `reverse` | boolean | `true` → `-1` (DESC); default ASC. Parse tolerante a erro (`:71`) |
+| `max_results` | int | `<= 0` ⇒ default **100** (`GameManager.java:660`) |
+
+### `GET /v3/gamification/{id}` — buscar por apiKey
+
+| Aspecto | Detalhe |
+| --- | --- |
+| Finalidade | `find()` (`:102`) |
+| Autenticação | Dois caminhos: (1) `isAppSecretAllowed` → **200 OK**; (2) Bearer de marketplace com claim `account` igual ao `gamification.accountId` → **201 CREATED** |
+
+> **Quirk confirmado:** o caminho de marketplace retorna `Response.Status.CREATED` (201) para um GET (`GamificationRest.java:112`). Não é o convencional 200. Se nenhum caminho casar → 401.
+
+### `POST /v3/gamification` — criar
+
+| Aspecto | Detalhe |
+| --- | --- |
+| Finalidade | `insert()` (`:158`) |
+| Autenticação | `isAppSecretAllowed` (conta) **ou** Bearer marketplace com claim `account` válido |
+| Full replace ou patch | Criação. `accountId` é **sempre sobrescrito** pelo servidor (`:161` ou `:173`) |
+| Status sucesso | 201 CREATED |
+
+**Comportamento real (via `GameManager.add()`, linha 75):**
+- `apiKey` ausente ⇒ gera `Guid.newShortGuid()` e define `created_at` (`:83-86`).
+- `apiKey` presente e já existe ⇒ **preserva o `created_at` antigo** (`:95`).
+- `updated_at` sempre sobrescrito (`:99`).
+- Adiciona o apiKey em `Account.games[]` se ausente (`:106-108`).
+- Chama `calculateStatisticsByAccount(accountId)` (`:113`).
+- Antes, verifica `allowCreateMoreGamifications` (`:160`) → 401 "account is not allowed to create more gamifications" se o limite for atingido.
+
+### `DELETE /v3/gamification/{id}` — excluir (cascade)
+
+| Aspecto | Detalhe |
+| --- | --- |
+| Finalidade | `delete()` (`:196`) |
+| Autenticação | `isAppSecretAllowed` E (a gamification é da conta **ou** o scope contém `CROSSDOMAIN`) |
+| Status | 200 OK; 401 com mensagem se não autorizado |
+
+**Cascade real (ordem em `GameManager.delete()`, linha 135):**
+1. `ManagerFactory.getInstance(apiKey).getSchedulerManager().deleteAll()` (`:141`)
+2. `StaticManager.deleteByApiKey(apiKey)` (`:144`)
+3. `ManagerFactory.stopInstance(apiKey)` (`:147`)
+4. `MONGO.dropDatabase(apiKey)` — **destrói o banco MongoDB inteiro da gamification** (`:151`)
+5. `game` collection: `remove({_id: apiKey})` (`:157`)
+6. Remove o apiKey de `Account.games[]` (`:162`)
+7. `S3Service.deleteAllFilesByApiKey(apiKey)` (`:167`)
+
+> **Irreversível e não-transacional.** Não há soft-delete nem rollback. Os 7 passos rodam em sequência sem transação: se um passo intermediário falhar (ex.: `dropDatabase`, atualização de `Account`, S3), a gamification fica em **estado inconsistente** (banco já dropado mas registro ainda em `game`, ou vice-versa).
+
+### `POST /v3/gamification/clone/{id}` — clonar
+
+| Aspecto | Detalhe |
+| --- | --- |
+| Finalidade | `clone()` (`:272`) — local mesma conta, local outra conta, ou remoto |
+| Autenticação | `isAppSecretAllowed` (conta de origem); proxy auth se conta destino diferir |
+| Status sucesso | 201 CREATED |
+
+**Path param:** `id` — apiKey da gamification **origem**.
+
+**Query param:**
+
+| Param | Tipo | Comportamento real |
+| --- | --- | --- |
+| `removeLogs` | String | `remove = !"false".equals(removeLogs)` (`:278`). Ou seja: **somente** a string literal `"false"` mantém os logs; ausente ou qualquer outro valor ⇒ `removeLogs=true` (remove) |
+
+**Headers especiais:**
+
+| Header | Uso |
+| --- | --- |
+| `X-Proxy-Authorization` | Credenciais da conta de destino (clone entre contas) ou do servidor remoto |
+| `X-Proxy-Endpoint` | URL do servidor remoto; **define o modo remoto** (`:281`) |
+
+**Body (`Game`):** `name`, `description`, `accountId` (opcional), `image`, `_id`/`apiKey` (opcional).
+
+**Comportamento real:**
+- Clone local sem `apiKey` no body ⇒ gera novo GUID (`GameManager.java:189`).
+- Clone **remoto** sem `apiKey` no body ⇒ usa o **mesmo apiKey da origem** (`:244`).
+- Clone remoto retorna `{ all, out, err }`; erros acumulados sem falhar.
+
+### `POST /v3/gamification/clone/remote` — recepção interna
+
+| Aspecto | Detalhe |
+| --- | --- |
+| Finalidade | `cloneRemote()` (`:330`) — recebe dados do `cloneRemoteSend` do servidor origem |
+| Autenticação | `isAppSecretAllowed` (conta) |
+| Body | `{ operation: "create_gamification" \| "save_collection", ... }` |
+
+> Endpoint interno. Não destinado a uso direto. **Loga o payload inteiro em `System.out`** (`GameManager.java:402`) e **não valida** o nome da coleção (`:427`) — ver seção 8.
+
+### `POST /v3/gamification/data/copy` — cópia seletiva
+
+| Aspecto | Detalhe |
+| --- | --- |
+| Finalidade | `dataCopy()` (`:344`) — comentário `//staging : send selected data` (`:340`) |
+| Autenticação | `isAppSecretAllowed` (conta) |
+| Restrição | **Apenas local** (`proxyEndpoint` deve ser vazio) e **mesma conta** |
+| Status | 201 CREATED |
+
+**Body:** `GameDataCopy` (ver 3.2).
+
+**Comportamento real:**
+- `_id: "*"` ⇒ `$merge` da coleção inteira da origem no destino (`GameManager.java:466`). Sem `whenMatched`/`whenNotMatched` explícitos → padrão MongoDB: `whenMatched: "merge"`, `whenNotMatched: "insert"`. Documentos com `_id` coincidente têm campos **mesclados** (não substituídos); documentos só do destino são **mantidos**.
+- `_id` específico ⇒ `findOne` na origem + `save` no destino (`:471-472`).
+- Sem retorno detalhado de itens copiados — só `{ "status": "OK" }`.
+
+### `POST /v3/gamification/data/diff` — comparação
+
+| Aspecto | Detalhe |
+| --- | --- |
+| Finalidade | `dataDiff()` (`:376`) |
+| Autenticação | `isAppSecretAllowed` (conta) |
+| Restrição | Apenas local e mesma conta |
+| Status | 201 CREATED |
+
+**Body:** mesmo `GameDataCopy`.
+
+**Comportamento real:**
+- `_id: "*"` ⇒ **limita a 100 documentos** da origem (`.limit(100)`, hardcoded, `GameManager.java:496`).
+- Retorna operações em **RFC 6902 JSON Patch** (`[{op, path, value}]`) como string no campo `operations`.
+- Item presente só na origem ⇒ `operations: "[op: create]"`.
+- Item presente só no destino (deletion) ⇒ **nunca reportado** (ver 2.6).
+- Source e target em contas diferentes (ou alguma gamification inexistente) ⇒ retorna `{}` sem erro.
+
+---
+
+## 5. Regras de Negócio
+
+**Clone — isolamento de conta (`GamificationRest.java:285-312`):** o clone local só prossegue se `gamification.accountId` for nulo, igual à conta atual, ou — se diferente — acompanhado de `X-Proxy-Authorization` válido para a conta destino. Caso contrário, 401.
+
+**Clone — preservação de apiKey no remoto (`GameManager.java:244`):** sem `apiKey` no body, a gamification remota recebe o **mesmo apiKey da origem**. Intencional para migração de ambiente, mas colide se o servidor destino já tiver gamification com esse apiKey de **outra** conta (→ 401 em `cloneRemoteReceive`).
+
+**Copy/Diff — mesma conta obrigatória (`GamificationRest.java:356`, `:388`):** verificação `target.accountId.equals(source.accountId)`. Se falhar (ou alguma gamification não existir, ou `proxyEndpoint` estar preenchido), o handler simplesmente cai para o `return` final com `result` vazio → **HTTP 201 com `{}`**, sem mensagem de erro.
+
+**Limite de gamifications por conta (`Account.games_allowed` / `games[]`):** `insert` e `clone` chamam `allowCreateMoreGamifications`. Atingido o limite → 401 (na conta de origem ou, no clone entre contas, na conta de destino proxy).
+
+**Versionamento do MongoDB (`copyDatabase`, `:599`):** versão detectada em runtime via `buildinfo`. `< 4.2` usa `copydb` (deprecated); `>= 4.2` usa `$merge` por coleção. Falha na detecção ⇒ NPE.
+
+**Diff — resolução de título (`diffObjects`, `:540-562`):** por tipo (`action`→`action`, `point_category`→`category`, `challenge`→`challenge`, `level`→`level`); demais tipos: `title` > `name` > `label` > `_id`.
+
+**`add()` ignora Game sem conta (`GameManager.java:77`):** se `accountId == null`, `add()` não faz nada (sem erro). Nos fluxos REST isso não ocorre porque o servidor preenche `accountId` antes.
+
+---
+
+## 6. Comportamentos Automáticos
+
+| Comportamento | Trigger | Impacto | Persistência |
+| --- | --- | --- | --- |
+| Geração de apiKey | `add()`/`clone()` local sem apiKey | `Guid.newShortGuid()` | Persistido em `game._id` |
+| Preservação de `created_at` | `add()` em apiKey existente | Mantém data original | Persistido em `game` |
+| Sobrescrita de `updated_at` | Todo `add()`/save | Atualiza para `now()` | Persistido em `game` |
+| Atualização de `Account.games[]` | `add()` (create/clone) | Adiciona apiKey à lista da conta | Persistido em `account` |
+| Recálculo de estatísticas | `add()` | `calculateStatisticsByAccount(accountId)` | Persistido (stats da conta) |
+| Remoção de coleções de runtime | `clone()` com `removeLogs=true` (default) | 11 coleções dropadas no destino | Irreversível |
+| Remoção de principals usuário | `clone()` local com `removeLogs=true` | `remove({type:0})` em `principal` | Irreversível (clone local) |
+| Log de payload | `cloneRemoteReceive()` | `System.out.println` do payload | Não persistido (stdout) |
+
+#### Diagrama — `clone()` local com `removeLogs=true`
+
+```mermaid
+flowchart LR
+    A["clone(id, gamification, true)"] --> B["source = findByApiKey(id)"]
+    B --> C["add(gamification)<br/>(grava em game + Account)"]
+    C --> D["copyDatabase(from, to)"]
+    D --> E{MongoDB >= 4.2?}
+    E -- sim --> F["$merge por coleção"]
+    E -- não --> G["comando admin copydb"]
+    F --> H["drop de 11 coleções de runtime"]
+    G --> H
+    H --> I["principal.remove({type:0})"]
+    I --> J["retorna nova Game (201)"]
+```
+
+---
+
+## 7. Suportado vs NÃO Suportado
+
+### ✅ Suportado
+
+- Clone local na mesma conta (`POST /clone/{id}` sem proxy).
+- Clone local entre contas (com `X-Proxy-Authorization`).
+- Clone para servidor remoto (com `X-Proxy-Authorization` + `X-Proxy-Endpoint`).
+- Cópia de documento individual entre gamifications (`data/copy` com `_id` específico).
+- Cópia de coleção inteira via `$merge` (`data/copy` com `_id: "*"`).
+- Diff de documento individual (`data/diff` com `_id` específico).
+- Diff de coleção (máx. 100 docs) (`data/diff` com `_id: "*"`).
+- Clone com/sem dados de runtime (`removeLogs`).
+- Detecção automática de versão do MongoDB.
+- Acumulação de erros no clone remoto (não interrompe no primeiro erro).
+- Exclusão em cascade (`DELETE`) incluindo drop do banco e arquivos S3.
+
+### ❌ NÃO Suportado / armadilhas confirmadas no código
+
+- **Rota `/v3/staging`** — não existe. Não há Service, Repository, Scheduler, enum de status nem coleção `staging`.
+- **`data/copy` / `data/diff` cross-server** — o guard `proxyEndpoint == null` faz a operação virar **no-op silencioso** (retorna `{}`) quando há `X-Proxy-Endpoint`.
+- **`data/copy` / `data/diff` cross-account** — retornam `{}` (201) sem copiar/comparar e sem erro.
+- **Detecção de deletions no diff** — bloco `[op: delete]` comentado (`GameManager.java:568-570`) **e** inalcançável por NPE quando `source == null`. Documentos só no target são ignorados.
+- **`data/diff` além de 100 docs por coleção** — `.limit(100)` hardcoded (`:496`). Coleções maiores são truncadas sem aviso.
+- **`data/copy` resiliente a id inexistente** — não há try/catch no loop; `target.save(null)` aborta a requisição no meio (`:472`).
+- **Validação do nome da coleção em `cloneRemoteReceive`** — qualquer string é aceita como `collection` (`:427`).
+- **Rollback de clone ou de delete** — inexistente; ambos são irreversíveis e o `delete` é não-transacional.
+- **Campos `title`/`content` de `Component`** — aceitos no JSON mas ignorados pelo runtime.
+- **Campos legados `imageUrl`/`timeZone` de `Game`** — comentados; não desserializados nem persistidos.
+- **Transacionalidade no clone remoto** — falhas parciais por lote vão para `err[]`; não há atomicidade nem retry.
+
+---
+
+## 8. Segurança e Permissões
+
+**Autenticação:** todas as operações de staging exigem `isAppSecretAllowed(apiKey, appSecret)` — credenciais de **nível de conta** (header `Authorization: Account ...` ou `Basic`). Para auth `Account`, `AuthBean.getApiKey()` retorna na verdade o **accountId** (`AuthBean.java:64-65`) — daí o uso de `authBean.getApiKey()` como conta nos handlers. Bearer de player **não** habilita clone/copy/diff.
+
+**Isolamento por conta:** `data/copy` e `data/diff` comparam `accountId` de origem e destino; `clone` entre contas exige credenciais de proxy da conta destino; `cloneRemoteReceive` rejeita (401) gravação em gamification de outra conta.
+
+**Scope `CROSSDOMAIN` no delete (`GamificationRest.java:201-202`):** com `Application.SCOPE_CROSSDOMAIN` no scope, um token pode **excluir gamifications de outra conta**. Documentado explicitamente: `authBean.getScope().indexOf(Application.SCOPE_CROSSDOMAIN) != -1`.
+
+**`cloneRemoteReceive` aceita coleção arbitrária (`GameManager.java:427`):** o campo `collection` é lido como String crua e usado direto em `jongo.getCollection(collection)` sem validar contra `Entity`. Um cliente com credenciais válidas da conta poderia gravar documentos em coleções internas (`principal`, `security`, etc.). A barreira é apenas a posse de credenciais de conta + a checagem de `accountId`.
+
+**Sequestro de metadados via `clone` na mesma conta (`GameManager.java:189-190`):** se o body informar um `apiKey` de gamification **já existente da mesma conta**, `clone()` mantém esse apiKey e chama `add()`, que **preserva `created_at` mas sobrescreve nome/descrição/imagem/etc.**; em seguida `copyDatabase` faz `$merge` no banco existente. Quem tiver o app secret da conta pode sobrescrever metadados e mesclar dados em uma gamification existente.
+
+**Vazamento de dados em log (`GameManager.java:402`):** `cloneRemoteReceive` imprime o payload completo recebido em `System.out`. Em ambientes que coletam stdout, dados de todas as coleções clonadas ficam expostos nos logs.
+
+**Colisão de apiKey no clone remoto (`:244`, `:413`):** sem `apiKey` no body, a gamification remota herda o apiKey da origem. Se o destino já tiver esse apiKey em outra conta → 401; se for da mesma conta → **sobrescreve** via `add()`.
+
+**Injeção em `orderby` (`GameManager.java:683`):** o valor de `orderby` é concatenado **cru** na string de aggregation (`"{$sort : {" + orderby + " : #}}"`). Não há allowlist no backend; valores inesperados podem alterar/quebrar o estágio `$sort`.
+
+---
+
+## 9. Observabilidade e Troubleshooting
+
+**Verificar se a gamification existe / inspecionar:**
+```
+GET /v3/gamification/{apiKey}
+Authorization: Account <token>
+```
+
+**Listar gamifications da conta:**
+```
+GET /v3/gamification
+Authorization: Account <token>
+```
+
+**Verificar resultado do clone local:** após o 201, buscar a nova gamification pelo `_id` retornado.
+
+**Diagnosticar clone remoto:** o retorno `{ all, out, err }` (`GameManager.java:282-284`) lista todas as coleções (`all`), respostas OK (`out`) e falhas (`err`). Verifique `err[]` para coleções/lotes que falharam — o processo **não** para no primeiro erro.
+
+**Erros comuns:**
+
+| Sintoma | Causa provável |
+| --- | --- |
+| `401 UNAUTHORIZED_CLIENT` | Credenciais inválidas, ou conta destino sem proxy auth válido no clone entre contas |
+| `401 account is not allowed to create more gamifications` | Limite `games_allowed` atingido |
+| `401 gamification dont belong to this account` | Clone remoto: apiKey já pertence a outra conta (`cloneRemoteReceive`, `:414`) |
+| `401 you dont have permission to save data in this gamification` | Clone remoto: tentou salvar coleção em gamification de outra conta (`:433`) |
+| Resposta `{}` (201) em `data/copy` ou `data/diff` | Contas diferentes, gamification inexistente, ou `X-Proxy-Endpoint` preenchido |
+| `data/diff` retorna menos itens que o esperado | `.limit(100)` por coleção; ou item lançou exceção e foi descartado (ver stdout) |
+| `data/copy` falha no meio | `_id` específico inexistente na origem → `save(null)` aborta o loop |
+| `NullPointerException` em `copyDatabase` | `buildinfo` falhou ao detectar a versão do MongoDB |
+| Deletions não aparecem no diff | Comportamento esperado — diff não reporta documentos ausentes na origem |
+
+**O que verificar quando "o staging não funciona":**
+1. As credenciais são de **conta** (não Bearer de player)?
+2. Source e target são da **mesma conta**? (copy/diff)
+3. Há `X-Proxy-Endpoint` indevidamente setado tornando copy/diff um no-op?
+4. Para clone remoto: o `apiKey` foi informado para evitar colisão no destino?
+5. Coleções > 100 docs no diff: o resultado está truncado.
+
+---
+
+## 10. Exemplos Práticos
+
+### Exemplo mínimo — clonar (mesmo servidor, mesma conta, sem logs)
+
+```
+POST /v3/gamification/clone/minha_gamification_api_key
+Authorization: Account NTQwZjE0YjAwZmZlZWI4YzJmZT
+Content-Type: application/json
+
+{ "name": "Staging - Cópia de Produção" }
+```
+Resposta `201`:
+```json
+{
+  "_id": "a1b2c3d4e5f6",
+  "name": "Staging - Cópia de Produção",
+  "accountId": "540f14b00ffeeb8c2xx00000",
+  "created_at": 1700000000000,
+  "updated_at": 1700000000000
+}
+```
+Internamente: banco MongoDB copiado integralmente; `player`, `action_log`, `achievement`, etc. (11 coleções) dropadas; `principal` com `type:0` removidos.
+
+### Exemplo — clonar preservando dados de runtime
+
+```
+POST /v3/gamification/clone/minha_gamification_api_key?removeLogs=false
+Authorization: Account NTQwZjE0YjAwZmZlZWI4YzJmZT
+
+{ "name": "Backup Completo" }
+```
+> Lembre: **somente** `removeLogs=false` preserva os logs. `removeLogs=0`, `removeLogs=no` ou ausência ⇒ remove.
+
+### Exemplo — copiar actions e challenges específicos entre ambientes (mesma conta)
+
+```
+POST /v3/gamification/data/copy
+Authorization: Account NTQwZjE0YjAwZmZlZWI4YzJmZT
+Content-Type: application/json
+
+{
+  "source": "staging_api_key",
+  "target": "producao_api_key",
+  "items": [
+    { "_id": "action_id_novo", "type": "action" },
+    { "_id": "*", "type": "challenge" }
+  ]
+}
+```
+Resposta `201`: `{ "status": "OK" }`
+
+### Exemplo avançado — diff de todos os actions
+
+```
+POST /v3/gamification/data/diff
+Authorization: Account NTQwZjE0YjAwZmZlZWI4YzJmZT
+Content-Type: application/json
+
+{
+  "source": "staging_api_key",
+  "target": "producao_api_key",
+  "items": [ { "_id": "*", "type": "action" } ]
+}
+```
+Resposta:
+```json
+{
+  "source": "staging_api_key",
+  "target": "producao_api_key",
+  "diff": [
+    {
+      "type": "action",
+      "_id": "login_action",
+      "title": "login",
+      "operations": "[{\"op\":\"replace\",\"path\":\"/points\",\"value\":10}]"
+    },
+    {
+      "type": "action",
+      "_id": "nova_action_so_no_staging",
+      "title": "boas_vindas",
+      "operations": "[op: create]"
+    }
+  ]
+}
+```
+> Limitado a 100 docs da origem. Actions presentes só em produção (deletados no staging) **não** aparecem.
+
+### Exemplo — clone para servidor remoto
+
+```
+POST /v3/gamification/clone/minha_gamification_api_key
+Authorization: Account TokenDaContaOrigem
+X-Proxy-Authorization: Account TokenDaContaNoServidorRemoto
+X-Proxy-Endpoint: https://eu1.service.funifier.com
+Content-Type: application/json
+
+{ "name": "Gamification EU", "apiKey": "minha_gamification_eu" }
+```
+Resposta:
+```json
+{ "all": ["action","challenge","level","point_category"], "out": ["{...}"], "err": [] }
+```
+> Sempre informe `apiKey` no body: sem ele, o destino herda o apiKey da origem e pode colidir (`GameManager.java:244`).
+
+### Anti-pattern 1 — `data/copy` entre contas diferentes
+
+```
+POST /v3/gamification/data/copy
+Authorization: Account token_conta_A
+
+{ "source": "game_da_conta_A", "target": "game_da_conta_B", "items": [ ... ] }
+```
+**Resultado:** `201` com `{}` — **nada é copiado, sem erro**. Para mover entre contas use `POST /clone/{id}` com `X-Proxy-Authorization`.
+
+### Anti-pattern 2 — `data/copy` de `_id` inexistente na origem
+
+```json
+{ "source": "stg", "target": "prod", "items": [ { "_id": "id_que_nao_existe", "type": "action" } ] }
+```
+**Resultado:** `findOne` retorna null → `target.save(null)` lança exceção → a requisição inteira falha; itens anteriores da lista já foram copiados (sem rollback). Sempre confirme a existência do `_id` na origem antes.
+
+### Anti-pattern 3 — confiar no diff para detectar exclusões
+
+Usar `data/diff` esperando ver itens "a remover" no destino **não funciona**: deletions nunca são reportadas. Para sincronizar exclusões, compare manualmente as listas de `_id` de cada lado.
+
+---
+
+## Checklist de Configuração
+
+- [ ] Credenciais de **conta** (`Authorization: Account ...`) — Bearer de player não habilita staging.
+- [ ] Limite `games_allowed` da conta não atingido antes de `clone`/`insert`.
+- [ ] Clone entre contas: `X-Proxy-Authorization` com credenciais válidas da conta destino.
+- [ ] Clone remoto: `X-Proxy-Endpoint` com a URL do servidor destino.
+- [ ] Clone remoto: **definir `apiKey` no body** para evitar colisão (senão herda o da origem).
+- [ ] `data/copy`/`data/diff`: confirmar que `source` e `target` são da **mesma conta** (senão `{}` silencioso).
+- [ ] `data/copy`/`data/diff`: **não** enviar `X-Proxy-Endpoint` (vira no-op).
+- [ ] `data/copy` com `_id` específico: confirmar que o documento **existe na origem** (senão a requisição aborta).
+- [ ] `data/diff` com `"_id": "*"`: ciente do limite fixo de **100 docs** por coleção.
+- [ ] Armadilha: `removeLogs` default é `true`; só `removeLogs=false` preserva runtime.
+- [ ] Armadilha: `data/copy` com `"_id": "*"` faz `$merge` — não apaga documentos extras no destino.
+- [ ] Armadilha: clone remoto com `removeLogs` **descarta toda** a coleção `principal` (≠ clone local).
+- [ ] Armadilha: diff não reporta deletions (itens só no destino).