funifier-mcp 0.2.26 → 0.2.27

package/datasource-funifier-docs/knowledge/modules/virtual-good.md

@@ -1,99 +1,546 @@
-# Virtual Good (Loja Virtual)
+# `virtual-good` (Loja Virtual / Catálogo)
 
 **Acesso Studio:** `/studio/catalog`
 **API Endpoint:** `/v3/virtualgoods`
+**Coleções MongoDB:** `catalog` (catálogos), `catalog_item` (itens) e `achievement` (registros de compra — `type=2`)
 
-## O que é
+> Documentação de engenharia reversa baseada no código real do projeto `funifier-service`:
+> `rest/v3/rest/VirtualGoodsRest.java`, `engine/catalog/CatalogManager.java`, `engine/catalog/CatalogDaoMongo.java`,
+> `engine/catalog/Catalog.java`, `engine/catalog/CatalogItem.java`, `engine/catalog/PurchaseAsyncProcessor.java`,
+> `engine/challenge/Requirement.java`, `engine/action/Limit.java`, `engine/technique/GameTechniqueManager.java`.
 
-Cadastro e gestão de objetos e benefícios que podem ser adquiridos pelos jogadores. Permite cadastrar produtos físicos, virtuais ou benefícios, estipular preços, quantidades, limites de compra e atributos. Os jogadores trocam pontos ou itens por objetos na loja.
+---
 
-## Quando usar
+## 1. Visão Geral
 
-- Para criar sistema de recompensas tangíveis
-- Para monetizar pontos/moedas virtuais
-- Para dar senso de propriedade e escolha ao jogador
-- Exemplos: camisetas, gift cards, itens virtuais, acessórios de avatar
+O módulo `virtual-good` implementa a **loja de troca** da gamificação: cadastra **catálogos** (agrupadores) e **itens** que o jogador pode adquirir gastando pontos/itens e recebendo recompensas. Ele **não possui modelo de compra próprio** — toda compra é gravada como um `Achievement` do tipo `catalog_item` (`type=2`) na coleção `achievement`. Em consequência, "estoque", "limite por período", "histórico de compras" e o campo `owned` são todos **calculados sobre a coleção `achievement`**, não sobre uma coleção de pedidos.
 
-## Dependências
+Papel arquitetural:
 
-- **Point**: moeda para compra deve existir
+- **Catálogo** (`catalog`) é puramente organizacional — agrupa itens por `catalogId`.
+- **Item** (`catalog_item`) carrega o preço (`requires`), as recompensas (`rewards`), as regras de disponibilidade (`active`, `start`/`end`, `limit`, `amount`, `principals`) e a integração com gatilhos/notificações.
+- **Compra** reaproveita o motor de `Achievement`: debita os `requires`, credita os `rewards` e o próprio item, dispara triggers e notificações, e recalcula o status do jogador.
 
-## Checklist de Configuração no Studio
+Relação com outros módulos:
 
-- [ ] Criar catálogo (ex: "gifts", "rewards")
-- [ ] Criar itens dentro do catálogo
-- [ ] Definir preço (requires: tipo de ponto + quantidade)
-- [ ] Definir quantidade em estoque (amount, -1 = ilimitado)
-- [ ] Definir limite de compras por jogador
-- [ ] Ativar item (active: true)
+- **Point / Challenge / Catalog Item** — únicos tipos efetivamente debitados/creditados na compra (ver §6).
+- **Achievement / Player Status** — toda compra recalcula o status do jogador (`updatePlayerStatus`).
+- **Trigger** — três eventos disparados na entidade `catalog_item` (§2.2).
+- **Notification** — notificações `EVENT_WIN` configuradas no item.
+- **Tango Card** — integração externa quando `item.extra.provider == "tango"`.
+- **Game Technique** — itens recebem a técnica `GT08` (virtual good) via backfill (§3.4).
 
-## API Endpoints
+---
 
-### Listar Catálogos
-**Método:** GET
-**Endpoint:** `/v3/virtualgoods/catalog`
+## 2. Arquitetura e Fluxos
 
-### Criar Catálogo
-**Método:** POST
-**Endpoint:** `/v3/virtualgoods/catalog`
+### 2.1 Pipeline principal de compra — `CatalogManager.purchase(Achievement, boolean async)`
 
-**Exemplo de Body:**
+A compra é processada pelo método **`purchase(...)`**, declarado `synchronized` (serializa compras por tenant — ver §5). O endpoint monta um `Achievement(guid, player, total, TYPE_CATALOG_ITEM, item, time)` e chama o manager.
+
+Sequência exata (linhas reais de `CatalogManager.purchase`):
+
+```
+[entrada]      purchase.time = now se nulo
+[lookup item]  findOne catalog_item {_id: item}      → se null: restrictions += "item_does_not_exist"
+[lookup player] findById(player)                     → se null: findById team; se ambos null: "player_does_not_exist"
+[trigger]      triggerManager.execute(item, "catalog_item", "before_purchase_validation")
+[validação]    async=true  → isValid(...)  (rápida, para na 1ª falha) → se falha: "restrictions"
+               async=false → checkRestrictions(...) (lista completa de restrições)
+[se restrictions vazio]:
+   [tango]     se item.extra.provider == "tango" → tangoCardManager.purchase(item, player)
+                                                    → extra.tango_order_id = order.referenceOrderID
+   [trigger]   triggerManager.execute(item, "catalog_item", "before_win")
+   [se restrictions ainda vazio]:
+      [débito]    para cada requires r:  se r.operation==DEDUCT && r.total!=0 && r.type∈{0,1,2}
+                     → Achievement(total negativo × purchase.total, r.type, r.item) com extra.origin=purchase.id → save
+      [crédito]   para cada rewards r:   se r.total!=0 && r.type∈{0,1,2}
+                     → Achievement(total positivo × purchase.total, r.type, r.item) com extra.origin=purchase.id
+                     → trigger before_win/after_win na coleção do tipo → save
+      [item]      save do Achievement da própria compra (type=2, item=itemId)
+      [trigger]   triggerManager.execute(item, "catalog_item", "after_win")
+      [status]    async=true  → playerManager.updateUserStatus(player)
+                  async=false → achievementManager.updatePlayerStatus(player) (achievements somados ao retorno)
+      [notif]     para cada NotificationDefinition EVENT_WIN do item → notificationManager.send(...)
+      [owned]     item.owned = count achievement {type:2, item:id}  → catalog_item.save(item)
+[retorno]      { restrictions, achievements, milliseconds, status: "OK"|"UNAUTHORIZED" }
+```
+
+Característica importante: **só os tipos `0` (point), `1` (challenge) e `2` (catalog_item)** são debitados/creditados. Tipos `3`–`7`/`50` em `requires`/`rewards` são **silenciosamente ignorados** na movimentação (ver §6 e §7).
+
+```mermaid
+flowchart TD
+    A["POST /purchase — monta Achievement type=2"] --> B{"item existe?"}
+    B -- não --> R0["restrictions += item_does_not_exist"]
+    B -- sim --> C{"player/team existe?"}
+    C -- não --> R1["restrictions += player_does_not_exist"]
+    C -- sim --> T0["trigger: before_purchase_validation"]
+    T0 --> V{"async?"}
+    V -- "sim (quick)" --> Vq["isValid() — para na 1ª falha"]
+    V -- "não (full)" --> Vf["checkRestrictions() — lista completa"]
+    Vq --> D{"restrictions vazio?"}
+    Vf --> D
+    D -- não --> OUT["status = UNAUTHORIZED"]
+    D -- sim --> TG{"extra.provider == tango?"}
+    TG -- sim --> TC["tangoCardManager.purchase → extra.tango_order_id"]
+    TG -- não --> T1
+    TC --> T1["trigger: before_win"]
+    T1 --> DB["débito dos requires (type 0,1,2 & operation=DEDUCT)"]
+    DB --> CR["crédito dos rewards (type 0,1,2)"]
+    CR --> SV["save Achievement da compra"]
+    SV --> T2["trigger: after_win"]
+    T2 --> ST["updatePlayerStatus / updateUserStatus"]
+    ST --> NT["notificações EVENT_WIN"]
+    NT --> OW["recalcula item.owned = count(achievement type=2)"]
+    OW --> OK["status = OK"]
+```
+
+### 2.2 Síncrono vs Assíncrono — `VirtualGoodsRest.insertPurchase`
+
+O endpoint decide o modo de execução nesta ordem:
+
+1. Se o **query param `async`** não foi informado, lê o **default do item** (`CatalogItem.async`); se o item tiver `async=true`, a compra vira assíncrona.
+2. Se `async == "true"` → enfileira via `catalogManager.asyncPurchase(_purchase)` e retorna **imediatamente** `status: "ASYNC"`.
+3. Caso contrário (default) → executa `catalogManager.purchase(_purchase, false)` e retorna o resultado processado.
+
+```mermaid
+sequenceDiagram
+    participant Cli as Cliente
+    participant Rest as VirtualGoodsRest
+    participant Mgr as CatalogManager
+    participant Q as PurchaseAsyncProcessor (thread/tenant)
+    Cli->>Rest: POST /purchase {item, player, total}
+    Rest->>Rest: async ausente? → lê CatalogItem.async
+    alt async == true
+        Rest->>Mgr: asyncPurchase(achievement)
+        Mgr->>Q: queue.offer(achievement)  (fila em memória)
+        Rest-->>Cli: 200 { status: "ASYNC", achievements:[...] }
+        Q->>Mgr: purchase(achievement, true)  (processa depois)
+    else síncrono (default)
+        Rest->>Mgr: purchase(achievement, false)
+        Mgr-->>Rest: { restrictions, achievements, status }
+        Rest-->>Cli: 200 { resultado processado }
+    end
+```
+
+> A fila assíncrona (`PurchaseAsyncProcessor`) é um `LinkedBlockingQueue` **em memória**, com **uma thread por tenant** iniciada no construtor do `CatalogManager`. Compras enfileiradas e ainda não processadas são **perdidas em caso de restart** (não há durabilidade). Ver §7.
+
+---
+
+## 3. Estrutura dos Objetos
+
+### 3.1 `Catalog` — documento raiz (coleção `catalog`)
+
+| Campo     | Tipo                          | Padrão        | Obrigatório | Descrição |
+| --------- | ----------------------------- | ------------- | ----------- | --------- |
+| `_id`     | String                        | auto (`Guid.shortTimeMillis()`) | — | Gerado se ausente no `add`. |
+| `catalog` | String                        | —             | Não (lógico) | Nome de exibição do catálogo. |
+| `itens`   | CatalogItem[]                 | —             | Não | Ver comportamento híbrido abaixo. |
+| `extra`   | Map<String,Object>            | `{}`          | Não | Atributos customizados. |
+| `created` | Date                          | `now` no `add`| —           | Setado automaticamente se ausente. |
+| `image`   | Image                         | —             | Não | Imagens (`small`/`medium`/`original`). |
+| `i18n`    | Map<String,Map<String,String>>| `{}`          | Não | Internacionalização. |
+
+**Comportamento do campo `itens`:**
+- No `POST /catalog`, se `itens` vier preenchido, cada item é também persistido na coleção `catalog_item` (via `addItem`), **além** de o objeto `catalog` ser salvo inteiro (com o array embutido) por `c.save(catalog)`.
+- No `GET /catalog/{id}` (`findById`), `itens` é **recalculado** a partir da coleção `catalog_item` (`findAllItemsByCatalogId`), sobrescrevendo o que estiver embutido.
+- No `GET /catalog` (lista, via `aggregate`), `itens` retorna **a cópia embutida** no documento `catalog` (não recalculada) — pode divergir de `findById`. Ver §7.
+
+### 3.2 `CatalogItem` — item (coleção `catalog_item`)
+
+| Campo           | Tipo                          | Padrão  | Obrigatório | Descrição |
+| --------------- | ----------------------------- | ------- | ----------- | --------- |
+| `_id`           | String                        | auto (`Guid.shortTimeMillis()`) | — | Gerado se ausente. |
+| `catalogId`     | String                        | `"default"` | Não | Catálogo dono. Se ausente vira `"default"`; se o catálogo não existir, é criado automaticamente. |
+| `name`          | String                        | —       | Não (lógico) | Nome do item. |
+| `description`   | String                        | —       | Não | Descrição. |
+| `amount`        | int                           | `0`     | Não | Estoque global. `-1` = ilimitado. `0` ⇒ sempre esgotado (ver §6). |
+| `active`        | boolean                       | `false` | Não | Item desativado bloqueia a compra (`item_disabled`). |
+| `start`         | Date                          | —       | Não | Início da janela de disponibilidade. |
+| `end`           | Date                          | —       | Não | Fim da janela de disponibilidade. |
+| `created`       | Date                          | `now` no `add` | — | Setado se ausente. |
+| `updated`       | Date                          | —       | —           | **Declarado mas nunca preenchido** pelo código (ver §7). |
+| `image`         | Image                         | —       | Não | Imagens do item. |
+| `limit`         | Limit                         | —       | Não | Limite de compras por período (§3.3). |
+| `extra`         | Map<String,Object>            | `{}`    | Não | Atributos extras. `extra.provider="tango"` ativa integração Tango. |
+| `requires`      | List<Requirement>             | `[]`    | Não | "Preço" — débitos/verificações para comprar (§3.5). |
+| `rewards`       | List<Requirement>             | `[]`    | Não | Recompensas creditadas além do item (§3.5). |
+| `notifications` | List<NotificationDefinition>  | `[]`    | Não | Notificações disparadas na compra (`EVENT_WIN`). |
+| `restrictions`  | List<String>                  | `null`  | —           | **Computado, não persistido** (ver abaixo). |
+| `principals`    | List<String>                  | `null`  | Não | IDs de player/team com acesso restrito ao item. Vazio/`null` = liberado a todos. |
+| `i18n`          | Map<String,Map<String,String>>| `{}`    | Não | Internacionalização. |
+| `techniques`    | List<String>                  | `null`  | Não | Técnicas de jogo; backfill atribui `GT08` (§3.4). |
+| `owned`         | long                          | `0`     | —           | Total de compras do item — recalculado pós-compra. |
+| `async`         | Boolean                       | `null`  | Não | Default de modo de compra (força compra assíncrona). |
+
+**Campo computado (não persiste no documento de leitura/cadastro):**
+- `restrictions` — só é preenchido em `GET /item` **quando o query param `player` é informado** (chama `checkRestrictions` por item). `GET /item/{id}` (por id) **nunca** preenche `restrictions`.
+
+**Campos deprecated/legados aceitos mas ignorados** (comentados no código, `@JsonIgnoreProperties(ignoreUnknown=true)` faz a desserialização silenciosamente descartar qualquer campo desconhecido enviado):
+- `points` (`RewardPoint[]`), `triggerURL`, `maxPerUser`, `levelId`, `real`, `statusPurchaseIntent` — todos comentados em `CatalogItem.java`. Enviá-los no JSON **não gera erro e não tem efeito**.
+
+### 3.3 `Limit` — limite de compras por período (`engine/action/Limit.java`)
+
+| Campo   | Tipo            | Descrição |
+| ------- | --------------- | --------- |
+| `total` | Object (Number ou String) | Quantidade máxima no período. Se `String`, é tratada como expressão Mustache + exp4j (ex.: `{{player.extra.max_buys}}`). |
+| `per`   | String          | `"player"`, `"team"` ou `"gamification"`. |
+| `every` | String          | Janela de tempo (`1d`, `10h`, `1w`...). Ausente ⇒ janela de `10y` (praticamente "sempre"). |
+| `query` | String          | **Declarado mas NÃO usado** em `checkIsInLimit` (ver §7). |
+
+> Unidades aceitas em `every` (via `DateUtil.fromKeyword`): `y` (ano), `M` (mês), `w` (semana), `d` (dia), `h` (hora), `m` (minuto).
+> **`per: "team"` não é avaliado** — `checkIsInLimit` só trata `player` e `gamification`. Ver §7.
+
+### 3.4 Técnicas de jogo (`techniques`)
+
+| Código | Constante (`GameTechniqueManager`) | Significado |
+| ------ | ---------------------------------- | ----------- |
+| `GT08` | `VIRTUALGOOD_CODE`                 | Identifica o item como **Virtual Good**. |
+
+Atribuição automática (`autoConfigureMissingTechniqueFields`): itens cujo `techniques` esteja **ausente ou vazio** (filtro Mongo `{$or:[{techniques:{$exists:true,$size:0}},{techniques:{$exists:false}}]}`) recebem `GT08` em backfill e são re-salvos. É um job de migração — não roda a cada compra.
+
+### 3.5 `Requirement` — usado por `requires` e `rewards` (`engine/challenge/Requirement.java`)
+
+| Campo       | Tipo               | Descrição |
+| ----------- | ------------------ | --------- |
+| `total`     | int                | Quantidade. No débito é forçado a negativo, no crédito a positivo, e multiplicado por `purchase.total`. |
+| `type`      | int                | Tipo do achievement (tabela abaixo). |
+| `item`      | String             | Id do ponto/desafio/item alvo. |
+| `operation` | int                | `0` verify, `1` deduct. **Só usado em `requires`** (em `rewards` é ignorado — sempre crédito). |
+| `extra`     | Map<String,Object> | Controle extra. |
+| `period`    | String             | Expressão de período (legado de challenge). |
+| `folder`    | String             | Filtro de catálogo (V4 — não usado no fluxo de compra). |
+| `restrict`  | boolean            | (V4) só credita se item disponível — não usado no fluxo de compra. |
+| `perPlayer` | boolean            | (V4) — não usado no fluxo de compra. |
+
+**Enum de `type` (compartilhado com `Achievement`):**
+
+| Valor | Tipo | Debitável/Creditável na compra? |
+| ----- | ---- | ------------------------------- |
+| `0`   | point | ✅ Sim |
+| `1`   | challenge | ✅ Sim |
+| `2`   | catalog_item | ✅ Sim |
+| `3`   | level | ❌ Ignorado |
+| `4`   | crown | ❌ Ignorado |
+| `5`   | lottery | ❌ Ignorado |
+| `6`   | mystery_box | ❌ Ignorado |
+| `7`   | character_star_stat | ❌ Ignorado |
+| `8`   | bonus | ❌ Ignorado |
+| `50`  | lottery_ticket | ❌ Ignorado |
+| `99`  | custom | ❌ Ignorado |
+
+`operation`: `0` = verify (apenas valida, não debita), `1` = deduct (valida e debita).
+
+---
+
+## 4. Endpoints
+
+Todos sob `@Path("v3/virtualgoods")`, autenticação **Bearer token** (`AuthBean`), respostas com `null` removido (`JsonUtil.toJsonRemoveNullFields`).
+
+### 4.1 Catálogos
+
+**`GET /v3/virtualgoods/catalog/{id}`** — `findCatalog`
+Retorna o catálogo com `itens` recalculados a partir de `catalog_item`.
+
+**`GET /v3/virtualgoods/catalog`** — `findAllCatalogs`
+
+| Param | Tipo | Descrição |
+| ----- | ---- | --------- |
+| `id` | String | Filtro por `_id` exato. |
+| `catalog` | String | Filtro por nome (`$regex`, case-insensitive). |
+| `q` | String | **Concatenado cru** no `$match` do pipeline (ver §8). |
+| `fields` | String | Projeção (`campo1,campo2`). |
+| `published_min`/`published_max` | String (RFC 3339) | Faixa sobre `created`. |
+| `orderby` | String | Campo de ordenação. |
+| `reverse` | boolean | `true` = descendente. |
+| `max_results` | int | Default/limite **100** quando ≤ 0. |
+
+**`POST /v3/virtualgoods/catalog`** — `insertCatalog` — corpo: objeto `Catalog`. Retorna `201`. Gera `_id` e `created` se ausentes. Se `itens` vier preenchido, persiste cada item em `catalog_item`.
+
+**`DELETE /v3/virtualgoods/catalog/{id}`** — `deleteCatalog`
+**Cascade:** remove o catálogo **e todos** os `catalog_item` com `catalogId == id`.
+
+### 4.2 Itens
+
+**`GET /v3/virtualgoods/item/{id}`** — `findItem` — por id. Não preenche `restrictions`.
+
+**`GET /v3/virtualgoods/item`** — `findAllItems`
+
+| Param | Tipo | Descrição |
+| ----- | ---- | --------- |
+| `id` | String | Filtro por `_id`. |
+| `catalog` | String | Filtro por `catalogId` (igualdade exata, apesar do nome). |
+| `name` | String | `$regex` case-insensitive. |
+| `description` | String | `$regex` case-insensitive. |
+| `player` | String | Se informado, adiciona o array `restrictions` a cada item (avaliação de elegibilidade). `me` = jogador do token. |
+| `q`, `fields`, `published_min/max`, `orderby`, `reverse`, `max_results` | — | Igual a catálogos (`max_results` default 100). |
+
+**`POST /v3/virtualgoods/item`** — `insertItem` — corpo: objeto `CatalogItem`. Retorna `201`.
+**Atenção:** é um `save` por `_id` (full replace). Reenviar um item com `_id` existente **substitui o documento inteiro**; campos ausentes voltam ao default — incluindo `owned` (→ `0`) e `created` (regerado). Ver checklist.
+
+### 4.3 Compra
+
+**`POST /v3/virtualgoods/purchase`** — `insertPurchase`
+
+| Param | Tipo | Descrição |
+| ----- | ---- | --------- |
+| `async` (query) | String | `"true"` força modo assíncrono. Ausente ⇒ usa `CatalogItem.async`. |
+
+Corpo (`Map`, não há DTO tipado):
+
+| Campo | Tipo | Comportamento |
+| ----- | ---- | ------------- |
+| `player` | String | `me` resolve para o jogador do token. |
+| `item` | String | Id do `catalog_item`. |
+| `total` | int | **Mínimo forçado a 1**; valores < 1 ou não numéricos viram 1. Multiplica débitos e créditos. |
+| `extra` | Map | Anexado ao achievement da compra. |
+
+Resposta síncrona:
 ```json
 {
-  "catalog": "Gifts",
-  "extra": {},
-  "i18n": {},
-  "_id": "gifts"
+  "achievements": [ { "player":"tom", "total":-10, "type":0, "item":"points", "time":1700000000000, "extra":{"origin":"<purchaseId>"}, "_id":"..." }, { "player":"tom", "total":1, "type":2, "item":"DTj7lVn", "time":1700000000000, "_id":"<purchaseId>" } ],
+  "restrictions": [],
+  "milliseconds": { "trigger":2, "verify":5, "debits":1, "credits":1, "status":3, "notify":0, "init":0 },
+  "status": "OK"
 }
 ```
 
-### Listar Itens
-**Método:** GET
-**Endpoint:** `/v3/virtualgoods/item`
+Resposta assíncrona:
+```json
+{ "achievements": [ { "player":"tom", "item":"DTj7lVn", "type":2, "total":1 } ], "restrictions": [], "status": "ASYNC" }
+```
+
+Resposta bloqueada:
+```json
+{ "achievements": [], "restrictions": ["insufficient_requirements","limit_exceeded"], "status": "UNAUTHORIZED" }
+```
+
+**`POST /v3/virtualgoods/purchase_by_player/{player}`** — `insertPurchaseByPlayer` — idêntico ao `/purchase`, mas o `player` vem no path (corpo `player` é ignorado).
+
+**`DELETE /v3/virtualgoods/purchase`** — `undoPurchase` — corpo `{ "_id": "<achievementId>" }`. Estorna a compra (ver §6).
+
+**`GET /v3/virtualgoods/evaluate/{id}`** — `evaluate` — diagnóstico de elegibilidade (não compra).
+
+| Param | Tipo | Descrição |
+| ----- | ---- | --------- |
+| `player` | String | Jogador a avaliar. |
+| `time` | String | Instante de referência (ms, RFC 3339 ou keyword). Default: agora. |
+
+Retorna `{ params, exists, limit_purchases, limit_amount, who, requirements, milliseconds }`.
+
+---
+
+## 5. Regras de Negócio
+
+Regras que existem **no código** e não são óbvias pelo schema:
+
+- **`total` mínimo = 1.** Frações ou valores ≤ 0 são normalizados para 1 (não há compra fracionada).
+- **Compra serializada por tenant.** `purchase(...)` é `synchronized` no `CatalogManager`. Há um `CatalogManager` por `apiKey`, então compras concorrentes do mesmo tenant são processadas **uma de cada vez**.
+- **Estoque é global e histórico.** `amount` é comparado contra `count(achievement {type:2, item:id})` — soma de **todas as compras de todos os jogadores, sem janela de tempo**. `amount = -1` ⇒ ilimitado. `amount = 0` ⇒ sempre esgotado.
+- **Limite por período** (`limit`): `per:"player"` conta achievements do jogador; `per:"gamification"` conta de todos; **`per:"team"` não é avaliado** (nunca bloqueia).
+- **Elegibilidade por principal** (`principals`): vazio/`null` libera a todos; senão exige que o `principalId` do jogador esteja na lista, ou que o jogador pertença a um team listado.
+- **Tipos movimentados.** Apenas `type ∈ {0,1,2}` são debitados/creditados. Demais tipos são aceitos no cadastro mas ignorados na compra (ver §6/§7).
+- **Consistência eventual no modo assíncrono.** A resposta `ASYNC` retorna antes do processamento; restrições/recompensas só são aplicadas quando a thread consome a fila.
+- **Multi-tenant.** Todo acesso é resolvido por `FrontController.getInstance(apiKey)`; cada tenant tem suas coleções e sua thread de processamento assíncrono.
+
+---
+
+## 6. Comportamentos Automáticos
+
+| Comportamento | Trigger | Impacto | Persistência |
+| ------------- | ------- | ------- | ------------ |
+| Geração de `_id`/`created` | `add`/`addItem` sem `_id`/`created` | IDs `Guid.shortTimeMillis()`; `created=now` | `catalog`/`catalog_item` |
+| Auto-criação de catálogo | `addItem` com `catalogId` inexistente | Cria `Catalog{_id=catalogId}` | `catalog` |
+| Default `catalogId="default"` | `addItem` sem `catalogId` | Item vai para catálogo `default` | `catalog_item` |
+| Cascade delete | `DELETE /catalog/{id}` | Remove todos os itens daquele catálogo | `catalog_item` |
+| Débito dos `requires` | `purchase` (sem restrições) | Achievement negativo p/ type 0/1/2 com `operation=DEDUCT`, `extra.origin=purchaseId` | `achievement` |
+| Crédito dos `rewards` | `purchase` | Achievement positivo p/ type 0/1/2, `extra.origin=purchaseId` | `achievement` |
+| Crédito do item | `purchase` | Achievement `type=2` da compra | `achievement` |
+| Triggers de compra | `purchase` | `before_purchase_validation`, `before_win`, `after_win` na entidade `catalog_item` | — |
+| Integração Tango | `extra.provider=="tango"` | Cria pedido externo; grava `extra.tango_order_id` | `achievement` |
+| Notificações | `purchase` | Envia `NotificationDefinition` `EVENT_WIN` do item | módulo notification |
+| Recalcular `owned` | fim de `purchase` | `owned = count(achievement type=2, item)` | `catalog_item` |
+| Recalcular status do jogador | `purchase` | `updatePlayerStatus` (sync) / `updateUserStatus` (async) | módulo player |
+| Estorno | `DELETE /purchase` | Remove achievement da compra + achievements `extra.origin=id`; recalcula status | `achievement` |
+
+```mermaid
+flowchart LR
+    A[Avaliar item para jogador] --> B{active?}
+    B -- não --> RB[item_disabled]
+    B -- sim --> C{requires OK?}
+    C -- não --> RC[insufficient_requirements]
+    C -- sim --> D{dentro de start/end?}
+    D -- não --> RD[item_out_of_time]
+    D -- sim --> E{limit por periodo OK?}
+    E -- não --> RE[limit_exceeded]
+    E -- sim --> F{amount/estoque OK?}
+    F -- não --> RF[item_sold_out]
+    F -- sim --> G{principal permitido?}
+    G -- não --> RG[principal_not_allowed]
+    G -- sim --> OK[elegível]
+```
+
+> **Estorno não recalcula `owned`.** `undoPurchase` remove os achievements e atualiza o status do jogador, mas **não atualiza o campo `owned`** do item — ele fica defasado até a próxima compra recalculá-lo. As checagens de `amount`/`limit` usam `count()` ao vivo, então a disponibilidade real é correta; apenas o número exibido em `owned` pode divergir temporariamente.
+
+> **Recompensas de tipo não suportado entram na resposta mas não são gravadas.** No laço de `rewards`, o `Achievement` é adicionado à lista `achievements` retornada **antes** do teste de coleção; o `save` só ocorre se o tipo for 0/1/2. Para tipos 3–7/50, a API responde como se a recompensa tivesse sido creditada, mas **nada é persistido**.
+
+---
+
+## 7. Suportado vs NÃO Suportado
+
+### ✅ Suportado
+
+- CRUD de catálogos (`/catalog`) e itens (`/item`) com filtros, projeção, paginação e ordenação.
+- Compra síncrona e assíncrona (`/purchase`, `/purchase_by_player/{player}`), com débito de `requires` e crédito de `rewards` para **point/challenge/catalog_item**.
+- Restrições de disponibilidade: `active`, janela `start`/`end`, `limit` (`player`/`gamification`), `amount` (estoque global), `principals`.
+- Estorno de compra (`DELETE /purchase`) com remoção dos achievements derivados.
+- Diagnóstico de elegibilidade (`GET /evaluate/{id}`).
+- Triggers (`before_purchase_validation`, `before_win`, `after_win`) e notificações `EVENT_WIN`.
+- Integração Tango Card (`extra.provider="tango"`).
+- Internacionalização (`i18n`) em catálogo e item.
+
+### ❌ NÃO Suportado / Limitações confirmadas no código
+
+- **`requires`/`rewards` de tipos 3–7/50** (level, crown, lottery, mystery_box, character_star_stat, lottery_ticket) — aceitos no cadastro, **ignorados** na movimentação. Em `rewards`, ainda aparecem na resposta sem serem gravados.
+- **`limit.per = "team"`** — constante existe (`Limit.PER_TEAM`), mas `checkIsInLimit` só trata `player`/`gamification`; limite por team **nunca é aplicado**.
+- **`limit.query`** — campo declarado, **nunca usado** em `checkIsInLimit`.
+- **`CatalogItem.updated`** — campo declarado, **nunca preenchido** por `add`/`update`.
+- **Fila assíncrona não-durável** — `PurchaseAsyncProcessor` é `LinkedBlockingQueue` em memória; compras pendentes são perdidas em restart.
+- **`owned` defasado após estorno** — não recalculado em `undoPurchase`.
+- **Divergência `findAll` vs `findById`** — lista de catálogos retorna `itens` embutidos; `findById` recalcula de `catalog_item`.
+- **Item inexistente na compra** — `purchase` adiciona `item_does_not_exist`, porém `checkRestrictions(null,...)` desreferencia o item → tende a lançar `NullPointerException` (HTTP 500) antes de devolver a resposta `UNAUTHORIZED`. Valide a existência do item antes.
+- **Campos legados de `CatalogItem`** (`points`, `triggerURL`, `maxPerUser`, `levelId`, `real`, `statusPurchaseIntent`) — comentados; ignorados silenciosamente se enviados.
+- **Endpoints legados v2** — `2.0.0/catalog` (`CatalogRest`) e `2.0.0/catalog_item` (`CatalogItemRest`) usam a entidade `Purchase` (coleção `purchase`) e `PurchaseManager.buy`/`get_purchases`. **Não fazem parte do módulo `/v3/virtualgoods`** e não compartilham a coleção de compras (que para o v3 é `achievement`). A entidade `Purchase` também carrega campos comentados (`price`, `pointCategoryId`, `delivered`, `deliveredTime`).
+
+---
+
+## 8. Segurança e Permissões
+
+- **Autenticação:** Bearer token resolvido por `AuthBean` em todos os endpoints; o tenant é determinado por `apiKey` (`FrontController.getInstance`).
+- **Isolamento multi-tenant:** coleções e thread de processamento assíncrono são por tenant.
+- **Injeção NoSQL — superfície confirmada:** o parâmetro **`q`** de `GET /catalog` e `GET /item` é **concatenado diretamente** na string do estágio `$match` do pipeline de agregação (`query.append(", " + q)` em `findAllCatalogs`/`findAllItems`), sem sanitização. Idem para `orderby`, interpolado em `{$sort:{<orderby>:...}}`. Operadores Mongo arbitrários enviados em `q` são executados. Restrinja/valide esses parâmetros na borda (gateway) e nunca exponha-os a entrada não confiável.
+- **`@JsonIgnoreProperties(ignoreUnknown=true)`** em todas as entidades faz campos desconhecidos serem descartados silenciosamente — não há rejeição de payload malformado.
+
+---
 
-### Criar Item
-**Método:** POST
-**Endpoint:** `/v3/virtualgoods/item`
+## 9. Observabilidade e Troubleshooting
 
-**Exemplo de Body:**
+**Diagnóstico de elegibilidade (sem comprar):**
+```
+GET /v3/virtualgoods/evaluate/{itemId}?player=tom
+```
+Retorna `exists`, `limit_purchases` (com `total_allowed`/`total_done`/`end_date`), `limit_amount`, `who` e `requirements` — cada um com `status: OK|UNAUTHORIZED`.
+
+**Verificar restrições de um item para um jogador na listagem:**
+```
+GET /v3/virtualgoods/item?player=tom&q=_id:"DTj7lVn"
+```
+O array `restrictions` virá preenchido por item.
+
+**Por que a compra retornou `UNAUTHORIZED`?** Consulte o array `restrictions`. Strings possíveis:
+
+| Restrição | Causa |
+| --------- | ----- |
+| `item_does_not_exist` | `item` não existe (pode acompanhar erro 500 — ver §7). |
+| `player_does_not_exist` | `player` não é player nem team. |
+| `item_disabled` | `active=false`. |
+| `insufficient_requirements` | jogador não atende aos `requires`. |
+| `item_out_of_time` | fora da janela `start`/`end`. |
+| `limit_exceeded` | excedeu `limit` no período. |
+| `item_sold_out` | `count(achievement type=2,item) >= amount`. |
+| `principal_not_allowed` | jogador/team fora de `principals`. |
+| `restrictions` | falha genérica no modo assíncrono (validação rápida). |
+| (mensagem Tango) | erro retornado pela integração Tango Card. |
+
+**Investigar compras direto no banco (coleção `achievement`):**
+```
+// quantas vezes o item foi comprado (= owned real)
+db.achievement.count({ type: 2, item: "DTj7lVn" })
+// compras de um jogador
+db.achievement.find({ type: 2, item: "DTj7lVn", player: "tom" }).sort({ time: -1 })
+// movimentações derivadas de uma compra (débitos/créditos)
+db.achievement.find({ "extra.origin": "<purchaseId>" })
+```
+
+**Erros comuns:**
+- "Comprei mas não debitou pontos" → o `requires` está com `operation=0` (verify) em vez de `1` (deduct), ou o `type` não é 0/1/2.
+- "Recompensa não apareceu no saldo" → `reward.type` fora de {0,1,2} (ignorado), ou `total=0`.
+- "Limite por equipe não funciona" → `limit.per="team"` não é avaliado.
+- "Estoque não bate com `owned`" → houve estorno; `owned` só recalcula na próxima compra (use `count()` ao vivo).
+- "Item sumiu ao re-salvar" → `POST /item` com `_id` existente faz full replace; reenvie todos os campos.
+
+---
+
+## 10. Exemplos Práticos
+
+### 10.1 Mínimo funcional
+
+Criar item gratuito e comprá-lo:
+```json
+// POST /v3/virtualgoods/item
+{ "_id": "badge_basic", "name": "Badge Básico", "active": true, "amount": -1 }
+```
+```json
+// POST /v3/virtualgoods/purchase
+{ "player": "tom", "item": "badge_basic" }
+```
+
+### 10.2 Avançado (todos os campos relevantes)
+
+Item pago com requisito, recompensa, limite, janela e notificação:
 ```json
+// POST /v3/virtualgoods/item
 {
+  "_id": "DTj7lVn",
   "catalogId": "gifts",
-  "name": "Bike",
-  "description": "Electric bike",
-  "amount": -1,
+  "name": "Caneca",
+  "description": "Caneca da campanha",
   "active": true,
-  "extra": {},
-  "requires": [],
-  "rewards": [],
-  "notifications": [],
-  "i18n": {},
+  "amount": 100,
+  "start": 1709251200000,
+  "end": 1735689600000,
+  "limit": { "total": 1, "per": "player", "every": "1d" },
+  "requires": [ { "total": 50, "type": 0, "item": "coins", "operation": 1 } ],
+  "rewards":  [ { "total": 1,  "type": 2, "item": "badge_basic" } ],
+  "notifications": [ { "event": 0, "type": 0, "scope": 99, "content": "Você comprou: {{item.name}}" } ],
   "techniques": ["GT08"],
-  "_id": "DTj7lVn"
+  "extra": { "provider": "wecare" }
 }
 ```
+```json
+// POST /v3/virtualgoods/purchase?async=true
+{ "player": "me", "item": "DTj7lVn", "total": 2, "extra": { "endereco": "casa" } }
+```
 
-### Realizar Compra
-**Método:** POST
-**Endpoint:** `/v3/virtualgoods/purchase`
+### 10.3 Anti-pattern (o que NÃO fazer)
 
-**Exemplo de Body:**
 ```json
-{
-  "player": "tom",
-  "item": "DTj7lVn",
-  "total": 1
-}
+// ❌ ERRADO — recompensa de tipo não suportado: aparece na resposta mas NÃO é gravada
+{ "_id": "x", "name": "x", "active": true, "amount": -1,
+  "rewards": [ { "total": 1, "type": 3, "item": "level_master" } ] }   // type=3 (level) é ignorado
+
+// ❌ ERRADO — limite por equipe nunca é aplicado
+"limit": { "total": 5, "per": "team", "every": "1w" }
+
+// ❌ ERRADO — requisito como "verify" não debita o jogador
+"requires": [ { "total": 50, "type": 0, "item": "coins", "operation": 0 } ]  // operation=0 não debita
+
+// ❌ ERRADO — re-POST sem 'owned'/'created' faz full replace e zera esses campos
+{ "_id": "DTj7lVn", "name": "Caneca (novo nome)" }   // perde amount, requires, rewards, owned...
 ```
 
-### Excluir Compra
-**Método:** DELETE
-**Endpoint:** `/v3/virtualgoods/purchase`
+---
 
-## Validações e Testes
+## Checklist de Configuração
 
-- [ ] Catálogo e itens aparecem nas respectivas listas
-- [ ] Jogador consegue comprar item com saldo suficiente
-- [ ] Compra debita pontos corretamente
-- [ ] Estoque é decrementado (se não ilimitado)
-- [ ] Limite de compras por jogador é respeitado
+- [ ] Item com `active: true` (senão `item_disabled`).
+- [ ] `amount` definido corretamente: `-1` para ilimitado; lembre-se que `0` ⇒ sempre esgotado.
+- [ ] `requires` com `operation: 1` (deduct) para realmente debitar; `type` ∈ {0,1,2}.
+- [ ] `rewards` com `type` ∈ {0,1,2} — outros tipos são ignorados (e não persistidos).
+- [ ] Itens em `requires`/`rewards` (point category, challenge, catalog_item) existem antes de criar o item.
+- [ ] Se usar `limit`, escolha `per: "player"` ou `"gamification"` — **não** `"team"`.
+- [ ] Janela `start`/`end` coerente com o fuso/relógio do servidor.
+- [ ] **Armadilha:** `POST /item` com `_id` existente substitui o documento inteiro — reenvie todos os campos (incl. `owned` se quiser preservar).
+- [ ] **Armadilha:** modo assíncrono (`async=true` ou `CatalogItem.async=true`) retorna `ASYNC` sem garantir o resultado; não confie na resposta para confirmar débito/crédito.
+- [ ] **Armadilha:** após `DELETE /purchase`, `owned` fica defasado até a próxima compra.
+- [ ] **Segurança:** nunca exponha o parâmetro `q`/`orderby` a entrada não confiável (injeção no pipeline Mongo).