funifier-mcp 0.2.26 → 0.2.27

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

@@ -1,132 +1,600 @@
-# Swap (Troca)
+# `swap`
 
 **Acesso Studio:** `/studio/swap`
 **API Endpoint:** `/v3/swap`
+**Coleções MongoDB:** `swap`, `swap_counter_offer`
 
-## O que é
+---
 
-Negociação e troca de objetos ou pontos entre jogadores. Permite que jogadores façam ofertas públicas de troca, negociando objetos ou pontos. Outros jogadores podem aceitar ou propor novas condições (contra propostas), incentivando a colaboração e interação.
+## 1. Visão Geral
 
-## Quando usar
+O módulo `swap` implementa **troca peer-to-peer de saldos de gamificação entre jogadores (ou times)**. Um jogador (`seller`) publica uma oferta declarando o que entrega (`rewards`) e o que cobra em retorno (`requires`); outro jogador (`buyer`) adquire a troca pagando os `requires`. Há também um modo de **contra-proposta** (`acceptCounterOffer = true`): o vendedor publica apenas os `rewards` e deixa que interessados registrem contra-propostas (`offer`), escolhendo uma delas para fechar negócio.
 
-- Para criar mercados de troca (ex: figurinhas)
-- Para permitir negociação entre jogadores
-- Para incentivar interação social na gamificação
+Não existe "carteira" persistida por jogador. Todo movimento de saldo é um lançamento na coleção `achievement` (o módulo `achievement` é a fonte da verdade dos totais). O `swap` apenas **gera lançamentos de débito e crédito** marcados com `extra.swap` / `extra.offer` / `extra.swap_role`, e delega o recálculo de saldo a `AchievementManager.updatePlayerStatus`.
 
-## Dependências
+Papel arquitetural:
 
-- **Virtual Good** e/ou **Point**: itens/pontos para troca devem existir
-- **Player**: jogadores devem estar cadastrados
+- **Escrow via achievement negativo**: ao publicar uma troca, os `rewards` do vendedor são imediatamente debitados (lançamento `achievement` negativo marcado com `extra.swap`). Esse débito funciona como caução — se a troca for excluída antes de ser adquirida, os débitos são removidos (estorno).
+- **Liquidação em duas etapas**: a troca não é atômica entre as duas partes. O comprador paga e recebe na operação `acquire`; o vendedor coleta seu pagamento em uma operação separada (`receive`). No modo contra-proposta o vendedor recebe no `accept` e o comprador coleta no `counter/offer/receive`.
+- **Sem isolamento de identidade**: a camada REST resolve `me` para o jogador do token, mas **não exige** que o token seja o vendedor/comprador. Qualquer token autenticado pode operar trocas em nome de terceiros (apenas registra `extra.*_registered_by` quando o autor difere).
 
-## Checklist de Configuração no Studio
+Relação com outros módulos:
 
-- [ ] Verificar se jogadores possuem itens/pontos para troca
-- [ ] Configurar interface de marketplace para os jogadores
+| Módulo | Uso real no código |
+|---|---|
+| `achievement` | Único destino de débitos/créditos. `evaluateRequirements` (elegibilidade) e `updatePlayerStatus` (recálculo de `player_status`). Manipulação direta da coleção via Jongo. |
+| `player` / `team` | `PlayerManager.findById` e, em fallback, `TeamManager.findById` validam a existência de `seller`/`buyer`. Um time pode ser participante de uma troca. |
+| `challenge` (`Requirement`) | `rewards`, `requires` e `offer` são listas de `Requirement` (mesma classe usada por desafios). |
+| `trigger` | Eventos `before_create`/`after_create`, `before_delete`/`after_delete`, `before_win`/`after_win` e o evento customizado `before_acquire_validation`. |
 
-## API Endpoints
+O `swap` **não** dispara notificações nem webhooks próprios (diferente de `achievement`). As notificações só ocorrem se um `trigger` configurado as emitir.
 
-### Listar Trocas
-**Método:** GET
-**Endpoint:** `/v3/database/swap`
+---
 
-### Criar Troca
-**Método:** POST
-**Endpoint:** `/v3/swap`
+## 2. Arquitetura e Fluxos
 
-**Exemplo de Body:**
-```json
-{
-  "seller": "tom",
-  "rewards": [
-    {
-      "total": 1,
-      "type": 2,
-      "item": "DTj7lVn"
+### 2.1 Classes envolvidas
+
+| Classe | Caminho | Papel |
+|---|---|---|
+| `SwapRest` | `com.funifier.rest.v3.rest.SwapRest` | Controller REST v3 (`/v3/swap`). 8 métodos. |
+| `SwapManager` | `com.funifier.engine.swap.SwapManager` | Toda a lógica de negócio. Métodos `synchronized`. Único consumidor: `SwapRest` (via `ManagerFactory.getSwapManager()`). |
+| `Swap` | `com.funifier.engine.swap.Swap` | Documento raiz, coleção `swap`. |
+| `SwapCounterOffer` | `com.funifier.engine.swap.SwapCounterOffer` | Documento de contra-proposta, coleção `swap_counter_offer`. |
+| `Requirement` | `com.funifier.engine.challenge.Requirement` | Item de troca (`total`/`type`/`item`/`operation`/`period`). |
+| `Achievement` | `com.funifier.engine.achievement.Achievement` | Lançamento de saldo gerado pelas operações. |
+
+Não há `Repository`/`Dao` dedicado. A persistência é feita por Jongo direto sobre as coleções `swap`, `swap_counter_offer` e `achievement`. Não há scheduler/job que processe trocas — todo o fluxo é síncrono e disparado por chamadas REST.
+
+### 2.2 Os dois fluxos do módulo
+
+Existem **dois fluxos mutuamente exclusivos**, decididos pelo campo `acceptCounterOffer` no momento do `insert`:
+
+- **Fluxo direto** (`acceptCounterOffer` ausente/`false`): vendedor define `requires` (preço fixo). Comprador paga via `acquire`. Usa o campo `acquired`.
+- **Fluxo de contra-proposta** (`acceptCounterOffer = true`): vendedor **não** define `requires`. Compradores registram `offer`. Vendedor escolhe uma via `accept`. Usa os campos `accepted` / `counterOffer`, **nunca** `acquired`.
+
+#### Fluxo direto — pipeline
+
+```
+[POST /v3/swap]            → insert(swap, author)
+  ├─ valida seller/rewards/requires
+  ├─ before_create (trigger)
+  ├─ DEBITA rewards do seller        (achievement negativo, extra.swap_role="seller")
+  ├─ salva swap
+  ├─ after_create (trigger)
+  └─ updatePlayerStatus(seller)
+
+[POST /v3/swap/acquire]    → buyerAcquire(id, buyer, author, extra)
+  ├─ valida swap não adquirido + buyer existe
+  ├─ before_acquire_validation (trigger)
+  ├─ evaluateRequirements(requires, buyer)   → "insufficient_requirements" se faltar saldo
+  ├─ before_win (trigger)
+  ├─ DEBITA requires do buyer        (extra.swap_role="buyer")
+  ├─ CREDITA rewards ao buyer        (extra.swap_role="buyer")
+  ├─ salva swap (buyer, acquired)
+  ├─ after_win (trigger)
+  └─ updatePlayerStatus(buyer)
+
+[POST /v3/swap/receive]    → sellerReceive(id)
+  ├─ valida swap adquirido (acquired != null OU buyer != null)
+  ├─ CREDITA requires ao seller      (extra.swap_role="seller")
+  ├─ before_delete (trigger)
+  ├─ REMOVE o documento swap
+  ├─ after_delete (trigger)
+  └─ updatePlayerStatus(seller)
+```
+
+### Fluxo direto — pipeline de troca
+
+```mermaid
+flowchart LR
+    A[POST /v3/swap<br/>insert] -->|debita rewards do seller| B[(swap salvo)]
+    B --> C[POST /v3/swap/acquire<br/>buyerAcquire]
+    C -->|debita requires + credita rewards ao buyer| D[(swap.acquired set)]
+    D --> E[POST /v3/swap/receive<br/>sellerReceive]
+    E -->|credita requires ao seller| F[swap removido]
+    B -.->|antes de adquirir| G[DELETE /v3/swap/:id<br/>estorna débito do seller]
+```
+
+#### Fluxo de contra-proposta — pipeline
+
+```
+[POST /v3/swap (acceptCounterOffer:true)]  → insert
+  └─ DEBITA rewards do seller (escrow). requires NÃO é exigido.
+
+[POST /v3/swap/counter/offer]              → counterOfferInsert(offer, author)
+  ├─ valida buyer/offer/swap
+  ├─ offer != rewards do swap                → "swap_rewards_and_counter_offer_must_be_different"
+  ├─ evaluateRequirements(offer, buyer)      → "insufficient_funds"
+  ├─ before_create (trigger, coleção swap_counter_offer)
+  ├─ DEBITA offer do buyer  (extra.offer=offerId, extra.swap=swapId, extra.swap_role="buyer")
+  ├─ salva counter offer
+  ├─ after_create (trigger)
+  └─ updatePlayerStatus(buyer)
+
+[POST /v3/swap/counter/offer/accept]       → counterOfferSellerAccept(offerId, extra)
+  ├─ swap.requires := offer.offer ; swap.buyer := offer.buyer
+  ├─ swap.accepted := now ; swap.counterOffer := offerId
+  ├─ CREDITA requires(=offer) ao seller
+  ├─ ESTORNA débitos das OUTRAS contra-propostas (remove achievements extra.offer != aceito)
+  ├─ REMOVE todos os documentos counter offer do swap
+  ├─ salva swap
+  └─ updatePlayerStatus(seller)             ⚠ nenhum trigger é disparado aqui
+
+[POST /v3/swap/counter/offer/receive]      → counterOfferBuyerReceive(swapId)
+  ├─ valida swap.accepted != null OU swap.buyer != null
+  ├─ CREDITA rewards ao buyer
+  ├─ before_delete (trigger)
+  ├─ REMOVE o documento swap
+  ├─ after_delete (trigger)
+  └─ updatePlayerStatus(buyer)
+```
+
+### Interação entre módulos — `acquire` (fluxo direto)
+
+```mermaid
+sequenceDiagram
+    participant Buyer
+    participant SwapRest
+    participant SwapManager
+    participant AchievementManager
+    participant Mongo as MongoDB
+    Buyer->>SwapRest: POST /v3/swap/acquire {swap, buyer}
+    SwapRest->>SwapManager: buyerAcquire(id, buyer, author, extra)
+    SwapManager->>Mongo: find swap por _id
+    SwapManager->>AchievementManager: evaluateRequirements(requires, buyer)
+    alt saldo insuficiente
+        AchievementManager-->>SwapManager: false
+        SwapManager-->>SwapRest: restrictions=[insufficient_requirements]
+        SwapRest-->>Buyer: 401 UNAUTHORIZED
+    else saldo ok
+        SwapManager->>Mongo: salva achievements (debita requires, credita rewards)
+        SwapManager->>Mongo: salva swap (buyer, acquired)
+        SwapManager->>AchievementManager: updatePlayerStatus(buyer)
+        SwapManager-->>SwapRest: status=OK
+        SwapRest-->>Buyer: 200 OK
+    end
+```
+
+### 2.3 Características de concorrência e transação
+
+- Todos os métodos de mutação de `SwapManager` são `synchronized` **a nível de instância**. Como existe uma instância de `SwapManager` por `ManagerFactory` (resolvida por `FrontController.getInstance(apiKey)`), a serialização é **por tenant** — operações de trocas de um mesmo tenant são serializadas; tenants diferentes correm em paralelo.
+- **Não há transação MongoDB.** As operações salvam múltiplos `achievement` e o documento `swap` em chamadas separadas. Uma falha no meio (ex.: exceção após debitar mas antes de salvar o swap) deixa lançamentos órfãos. Não há rollback.
+
+---
+
+## 3. Estrutura dos Objetos
+
+### 3.1 `Swap` — documento raiz (coleção `swap`)
+
+| Campo | Tipo | Padrão | Obrigatório | Descrição |
+|---|---|---|---|---|
+| `_id` | String | auto (`Guid.newShortGuid()`) | — | Gerado no servidor. Enviar `_id` no POST gera restrição `swap_id_not_allowed`. |
+| `seller` | String | — | Sim | ID do jogador **ou** time que oferta. Aceita `"me"` (resolvido para o jogador do token). |
+| `buyer` | String | null | Não (sistema) | Preenchido no `acquire` (direto) ou no `accept` (contra-proposta). |
+| `rewards` | `Requirement[]` | `[]` | Sim | O que o vendedor entrega. Debitado do vendedor no `insert`. |
+| `requires` | `Requirement[]` | `[]` | Sim no fluxo direto; **não exigido** se `acceptCounterOffer=true` | O que o comprador paga. No fluxo de contra-proposta é **sobrescrito** pela `offer` aceita. |
+| `acceptCounterOffer` | Boolean | null | Não | `true` ativa o modo contra-proposta. |
+| `extra` | Object | `{}` | Não | Atributos livres. O sistema grava `seller_registered_by` / `buyer_registered_by` quando o autor difere do participante. |
+| `created` | Date | `now()` no insert | — | Data de criação. |
+| `acquired` | Date | null | — | Data da aquisição (**somente fluxo direto**, set em `buyerAcquire`). |
+| `accepted` | Date | null | — | Data do aceite de contra-proposta (**somente fluxo contra-proposta**, set em `counterOfferSellerAccept`). |
+| `counterOffer` | String | null | — | ID da `SwapCounterOffer` aceita (set no `accept`). |
+
+> Não há campos computados nem campos removidos silenciosamente no save de `Swap` — o documento é persistido como recebido (com `@JsonIgnoreProperties(ignoreUnknown=true)`, campos desconhecidos são descartados na desserialização). Não há campo de status textual: o "estado" é inferido pela presença de `acquired` / `accepted` / `buyer`.
+
+### 3.2 `SwapCounterOffer` — contra-proposta (coleção `swap_counter_offer`)
+
+| Campo | Tipo | Padrão | Obrigatório | Descrição |
+|---|---|---|---|---|
+| `_id` | String | auto | — | Enviar `_id` gera `counter_offer_id_not_allowed`. |
+| `swap` | String | — | Sim | ID do `swap` alvo. |
+| `buyer` | String | — | Sim | Jogador que propõe. Aceita `"me"`. |
+| `offer` | `Requirement[]` | `[]` | Sim | O que o comprador oferece pelos `rewards` do swap. Debitado no insert. |
+| `created` | Date | `now()` | — | Data de criação. |
+| `extra` | Object | `{}` | Não | Grava `buyer_registered_by` quando o autor difere. |
+
+### 3.3 `Requirement` — item de troca (subentidade de `rewards`/`requires`/`offer`)
+
+| Campo | Tipo | Padrão | Usado pelo swap? | Descrição |
+|---|---|---|---|---|
+| `total` | int | 0 | Sim | Quantidade. `total == 0` é **ignorado** no débito/crédito. |
+| `type` | int | 0 | Parcial | Ver enum abaixo. **Apenas 0, 1 e 2 são debitados/creditados.** |
+| `item` | String | null | Sim | ID do ponto / item de catálogo / desafio. |
+| `operation` | int | 0 | **Não** (ignorado pelo swap) | `0=VERIFY`, `1=DEDUCT`. Irrelevante no swap (ver §5). |
+| `period` | String | null | Sim (na elegibilidade) | Expressão de período (ex.: `-5h;-0h`) aplicada ao calcular o saldo em `evaluateRequirements`. |
+| `extra` | Object | `{}` | Não | Ignorado pelo swap. |
+| `folder` | String | null | **Não** | Ignorado pelo swap. |
+| `restrict` | boolean | false | **Não** | Ignorado pelo swap. |
+| `perPlayer` | boolean | false | **Não** | Ignorado pelo swap. |
+
+**Enum `type` (`Requirement` / `Achievement`):**
+
+| Valor | Constante | Debitado/creditado pelo swap? |
+|---|---|---|
+| 0 | `TYPE_POINT` | ✅ Sim |
+| 1 | `TYPE_CHALLENGE` | ✅ Sim |
+| 2 | `TYPE_CATALOG_ITEM` | ✅ Sim |
+| 3 | `TYPE_LEVEL` | ❌ Verificado na elegibilidade, mas **nunca** debitado/creditado |
+| 4 | `TYPE_CROWN` | ❌ idem |
+| 5 | `TYPE_LOTTERY` | ❌ idem |
+| 6 | `TYPE_MYSTERY_BOX` | ❌ idem |
+| 7 | `TYPE_CHARACTER_STAR_STAT` | ❌ idem |
+| 50 | `TYPE_LOTTERY_TICKET` | ❌ idem |
+
+> **Comportamento silencioso crítico:** os loops de débito/crédito em todos os métodos do `SwapManager` filtram por `type ∈ {0,1,2}`. Um `Requirement` de tipo 3–7/50 é **aceito** no documento e **conta na verificação de elegibilidade** (`evaluateRequirements` soma todos os tipos), mas **nenhum lançamento de saldo é gerado** para ele. Resultado: o jogador precisa possuir o item para passar na validação, porém não o perde nem o recebe na troca.
+
+### 3.4 Ciclo de vida do `Swap`
+
+```mermaid
+stateDiagram-v2
+    [*] --> Publicado: insert (debita rewards do seller)
+    Publicado --> Removido: delete (estorna débito)
+
+    state "Fluxo direto" as Direto {
+        Publicado --> Adquirido: buyerAcquire (acquired set)
+        Adquirido --> Liquidado: sellerReceive (credita seller, remove swap)
     }
-  ],
-  "requires": [
-    {
-      "total": 2,
-      "type": 0,
-      "item": "coin"
+
+    state "Fluxo contra-proposta" as Counter {
+        Publicado --> Aceito: counterOfferSellerAccept (accepted+buyer set, credita seller)
+        Aceito --> Coletado: counterOfferBuyerReceive (credita buyer, remove swap)
     }
-  ]
-}
+
+    Liquidado --> [*]
+    Coletado --> [*]
+    Removido --> [*]
 ```
 
-### Deletar Troca
-**Método:** DELETE
-**Endpoint:** `/v3/swap/:id`
+> O documento `swap` **deixa de existir** ao final de ambos os fluxos (`sellerReceive` / `counterOfferBuyerReceive` removem o documento). Não há estado "concluído" persistido — uma troca finalizada simplesmente some da coleção. O histórico permanece apenas nos lançamentos `achievement`.
+
+### 3.5 Marcadores gravados no `Achievement`
+
+Cada débito/crédito gerado pelo swap grava no `Achievement.extra`:
+
+| Marcador | Onde | Significado |
+|---|---|---|
+| `extra.swap` | Todos | ID do `swap` que originou o lançamento. Usado para estorno em `delete`. |
+| `extra.offer` | Contra-proposta | ID da `SwapCounterOffer`. Usado para estorno em `counterOfferDelete` e na limpeza do `accept`. |
+| `extra.swap_role` | Todos | `"seller"` ou `"buyer"` — identifica de qual lado foi o movimento. |
+
+---
+
+## 4. Endpoints
+
+Todos exigem `Authorization: Bearer <token>`. Respostas seguem o mesmo envelope: `{ status, restrictions[], achievements[], swap|offer }`. `status="OK"` → HTTP 200; `status="UNAUTHORIZED"` (qualquer restrição) → HTTP 401. Campos `null` são removidos da resposta (`JsonUtil.toJsonRemoveNullFields`).
 
-### Realizar Troca (Adquirir)
-**Método:** POST
-**Endpoint:** `/v3/swap/acquire`
+### `POST /v3/swap` — criar troca
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Publica uma oferta e debita os `rewards` do vendedor (escrow). |
+| Body | Objeto `Swap`. `_id` proibido. |
+| `me` | `seller="me"` → jogador do token. |
+
+**Comportamento real:** valida que `seller`, `rewards` e (no fluxo direto) `requires` estão preenchidos; que `requires` não é idêntico a `rewards` (mesmo `item`+`total`+`type`); e que o vendedor possui os `rewards` ofertados (`evaluateRequirements`). Em seguida debita os `rewards`.
 
-**Exemplo de Body:**
 ```json
 {
-  "buyer": "jerry",
-  "swap": "650c67f88325771ffaa78a24"
+  "seller": "tom",
+  "rewards": [ { "total": 1, "type": 2, "item": "DTj7lVn" } ],
+  "requires": [ { "total": 2, "type": 0, "item": "coin" } ]
 }
 ```
 
-### Receber Recompensas da Troca
-**Método:** POST
-**Endpoint:** `/v3/swap/receive`
+### `DELETE /v3/swap/{id}` — excluir troca
+
+Só remove se `acquired == null && buyer == null` (troca ainda não negociada); caso contrário retorna `swap_have_being_acquired`. Ao remover, **estorna** os achievements com `extra.swap == id` (incluindo o débito de escrow do vendedor) e dispara `before_delete`/`after_delete`.
+
+### `POST /v3/swap/acquire` — adquirir (fluxo direto)
+
+| Aspecto | Detalhe |
+|---|---|
+| Body | `{ swap, buyer, extra? }` |
+| `me` | `buyer="me"` → jogador do token. |
+
+Valida que a troca existe e não foi adquirida, e que o comprador possui os `requires`. Debita `requires` do comprador, credita `rewards` ao comprador, marca `buyer`/`acquired`. Dispara `before_acquire_validation` → `before_win` → `after_win`.
 
-**Exemplo de Body:**
 ```json
-{
-  "swap": "650c67f88325771ffaa78a24"
-}
+{ "buyer": "jerry", "swap": "650c67f88325771ffaa78a24" }
+```
+
+### `POST /v3/swap/receive` — vendedor coleta (fluxo direto)
+
+| Aspecto | Detalhe |
+|---|---|
+| Body | `{ swap }` |
+
+Credita os `requires` ao vendedor e **remove** o documento `swap`. ⚠ Não valida que o token é o vendedor. ⚠ Ver §7/§8 sobre uso indevido no fluxo de contra-proposta (duplo crédito).
+
+```json
+{ "swap": "650c67f88325771ffaa78a24" }
 ```
 
-### Listar Contra Propostas
-**Método:** POST
-**Endpoint:** `/v3/database/swap_counter_offer/aggregate`
+### `POST /v3/swap/counter/offer` — criar contra-proposta
+
+| Aspecto | Detalhe |
+|---|---|
+| Body | Objeto `SwapCounterOffer` (`{ swap, buyer, offer[] }`). |
+| `me` | `buyer="me"` → jogador do token. |
 
-### Criar Contra Proposta
-**Método:** POST
-**Endpoint:** `/v3/swap/counter/offer`
+Valida `buyer`/`offer`/`swap`, que `offer` difere dos `rewards` do swap, e que o comprador possui a `offer`. Debita a `offer` do comprador. **Não verifica** se o swap tem `acceptCounterOffer=true` (ver §7).
 
-**Exemplo de Body:**
 ```json
 {
   "swap": "650c683c8325771ffaa78a3f",
   "buyer": "jerry",
-  "offer": [
-    {
-      "total": 1,
-      "type": 0,
-      "item": "coin"
-    }
-  ]
+  "offer": [ { "total": 1, "type": 0, "item": "coin" } ]
 }
 ```
 
-### Deletar Contra Proposta
-**Método:** DELETE
-**Endpoint:** `/v3/swap/counter/offer/:id`
+### `POST /v3/swap/counter/offer/accept` — vendedor aceita
+
+| Aspecto | Detalhe |
+|---|---|
+| Body | `{ offer, extra? }` (`offer` = `_id` da contra-proposta) |
 
-### Aceitar Contra Proposta
-**Método:** POST
-**Endpoint:** `/v3/swap/counter/offer/accept`
+Sobrescreve `swap.requires` com a `offer` aceita, credita a `offer` ao vendedor, **estorna os débitos das demais contra-propostas**, remove todas as contra-propostas do swap e marca `accepted`/`buyer`/`counterOffer`. ⚠ **Não dispara nenhum trigger** e **não valida** que o token é o vendedor.
 
-**Exemplo de Body:**
 ```json
+{ "offer": "650c69aa8325771ffaa78b1b" }
+```
+
+### `POST /v3/swap/counter/offer/receive` — comprador coleta (contra-proposta)
+
+| Aspecto | Detalhe |
+|---|---|
+| Body | `{ swap }` (ID do **swap**, não da offer) |
+
+Credita os `rewards` ao comprador (`swap.buyer`) e remove o documento `swap`. Dispara `before_delete`/`after_delete`.
+
+### `DELETE /v3/swap/counter/offer/{id}` — excluir contra-proposta
+
+Estorna os achievements com `extra.offer == id` (devolve a `offer` debitada) e remove a contra-proposta. Dispara `before_delete`/`after_delete`. Não há verificação de que a troca já foi aceita.
+
+### Leitura (listagem)
+
+**Não existe `GET /v3/swap`.** A leitura é feita pelos endpoints genéricos de banco:
+
+- `GET /v3/database/swap` — lista trocas.
+- `POST /v3/database/swap/aggregate` — agregação sobre trocas.
+- `GET /v3/database/swap_counter_offer` / `POST /v3/database/swap_counter_offer/aggregate` — contra-propostas.
+
+Estes endpoints são servidos pelo módulo `database` (CRUD genérico), não pelo `SwapManager`. Não há a filtragem por elegibilidade nem a randomização que o comentário legado do código menciona (ver §7).
+
+---
+
+## 5. Regras de Negócio
+
+Regras presentes no código e ausentes do schema:
+
+1. **Escrow imediato.** Publicar uma troca debita os `rewards` do vendedor na hora (`insert`). O vendedor precisa possuí-los — senão `insufficient_rewards`.
+2. **`rewards` ≠ `requires`.** Se algum item coincidir em `item`+`total`+`type`, retorna `rewards_and_requires_must_be_different`. Análogo para contra-proposta vs `rewards` (`swap_rewards_and_counter_offer_must_be_different`).
+3. **Elegibilidade por soma de saldo.** `evaluateRequirements` calcula `sumTotalRewards(player, type, item, period)` e exige `saldo >= total` para **cada** requisito, **de todos os tipos** (não só 0/1/2). Aceita expressão de `period` por requisito.
+4. **`operation` é ignorada no swap.** O swap usa a sobrecarga `evaluateRequirements(all, player, jongo)`, que verifica saldo de todo requisito independentemente de `operation`. Marcar um item como `VERIFY` ou `DEDUCT` não muda nada — todo `requires`/`offer` é sempre debitado de fato (o débito real depende só de `type ∈ {0,1,2}` e `total != 0`).
+5. **`total == 0` é no-op.** Requisitos com `total` zero passam na validação mas não geram lançamento.
+6. **Normalização de sinal.** Débitos são forçados a negativo (`(total>0)?-total:total`); créditos forçados a positivo. Enviar `total` negativo em `rewards` não inverte a operação — o sinal é sempre normalizado pela etapa.
+7. **Participante pode ser time.** `seller`/`buyer` são validados primeiro como `Player`, depois como `Team`. Um time pode participar de trocas.
+8. **Exclusão só antes da negociação** (`delete`): `acquired == null && buyer == null`.
+9. **Contra-proposta sobrescreve `requires`.** No `accept`, `swap.requires := offer.offer`. A partir daí o "preço" do swap passa a ser a oferta aceita.
+10. **Estorno seletivo no aceite.** Ao aceitar uma contra-proposta, os débitos das **outras** contra-propostas são removidos (estorno) via `{extra.swap:#, extra.swap_role:"buyer", extra.offer:{$ne:#}}`. Mas só o `player_status` do **vendedor** é recalculado — os saldos dos demais compradores ficam consistentes apenas eventualmente (ver §9).
+11. **Multi-tenant por database.** O isolamento entre organizações é o database Jongo resolvido por `apiKey` (`FrontController.getInstance(apiKey)`). Não há campo de tenant nos documentos.
+
+---
+
+## 6. Comportamentos Automáticos
+
+| Comportamento | Trigger / origem | Impacto | Persistência |
+|---|---|---|---|
+| Débito de escrow do vendedor | `insert` | Achievement negativo `extra.swap`, `swap_role="seller"` | Coleção `achievement` |
+| Débito da contra-proposta | `counterOfferInsert` | Achievement negativo `extra.offer`+`extra.swap` | `achievement` |
+| Débito do comprador + crédito de rewards | `buyerAcquire` | 2 lançamentos `swap_role="buyer"` | `achievement` |
+| Crédito ao vendedor | `sellerReceive` / `counterOfferSellerAccept` | Achievement positivo `swap_role="seller"` | `achievement` |
+| Crédito ao comprador | `counterOfferBuyerReceive` | Achievement positivo `swap_role="buyer"` | `achievement` |
+| Estorno ao excluir | `delete` (`extra.swap`), `counterOfferDelete` (`extra.offer`) | Remove lançamentos | `achievement` |
+| Estorno das demais ofertas | `counterOfferSellerAccept` | Remove débitos das contra-propostas não aceitas | `achievement` |
+| Recálculo de `player_status` | `updatePlayerStatus(player)` ao fim de cada mutação bem-sucedida | Atualiza snapshot e pode gerar achievements derivados (ex.: level-up) | `player_status` + `achievement` |
+| Triggers de domínio | Ver tabela abaixo | Permite hooks Groovy/Java; podem **adicionar restrições** que abortam a operação | Conforme o trigger |
+
+### Eventos de trigger por operação
+
+| Operação | Eventos disparados (na ordem) |
+|---|---|
+| `insert` | `before_create` → (débitos) → `after_create` |
+| `delete` | `before_delete` → (estorno) → `after_delete` |
+| `buyerAcquire` | `before_acquire_validation` → `before_win` → (débito/crédito) → `after_win` |
+| `sellerReceive` | (crédito) → `before_delete` → (remove) → `after_delete` |
+| `counterOfferInsert` | `before_create` → (débito) → `after_create` |
+| `counterOfferDelete` | `before_delete` → (estorno) → `after_delete` |
+| `counterOfferSellerAccept` | **nenhum** |
+| `counterOfferBuyerReceive` | (crédito) → `before_delete` → (remove) → `after_delete` |
+
+> Os triggers `before_create` / `before_win` podem inserir entradas em `restrictions` (via `TriggerContext`). Se o fizerem, a operação é abortada antes da persistência. `before_acquire_validation` roda **antes** da checagem de saldo do comprador.
+
+### Fluxo de behaviors automáticos no `insert`
+
+```mermaid
+flowchart TD
+    A[insert] --> B{validações de schema}
+    B -->|falha| Z[restrictions → 401]
+    B -->|ok| C[before_create trigger]
+    C --> D{trigger adicionou restrição?}
+    D -->|sim| Z
+    D -->|não| E[debita rewards do seller]
+    E --> F[salva swap]
+    F --> G[after_create trigger]
+    G --> H[updatePlayerStatus seller]
+    H --> I[200 OK]
+```
+
+---
+
+## 7. Suportado vs NÃO Suportado
+
+### ✅ Suportado
+
+- Troca direta com preço fixo (`rewards` por `requires`).
+- Modo contra-proposta (`acceptCounterOffer`).
+- Débito de escrow, estorno na exclusão e estorno das ofertas perdedoras.
+- Participação de **player ou team** como `seller`/`buyer`.
+- Resolução de `"me"` para o jogador do token em `insert`/`acquire`/`counterOfferInsert`.
+- Elegibilidade por saldo com expressão de `period`.
+- Triggers de domínio (`before/after_create`, `before/after_delete`, `before/after_win`, `before_acquire_validation`).
+- Tipos de saldo movimentados: **ponto (0), challenge (1), catalog_item (2)**.
+
+### ❌ NÃO Suportado / comportamento divergente
+
+- **`GET /v3/swap` não existe.** O comentário legado no cabeçalho de `Swap.java`/`SwapManager.java` ("GET swap: filtrar por aqueles que o jogador tem requisitos para comprar, e trazer itens aleatórios") **nunca foi implementado**. Leitura só via `/v3/database/swap`.
+- **Tipos 3–7 e 50** (`level`, `crown`, `lottery`, `mystery_box`, `character_star_stat`, `lottery_ticket`): aceitos no documento e **verificados** na elegibilidade, mas **nunca debitados nem creditados**. Trocar esses tipos não move saldo.
+- **`Requirement.operation` é ignorado** no contexto de swap (todo requisito é tratado como verificação + débito incondicional por tipo).
+- **`Requirement.folder` / `restrict` / `perPlayer`** são aceitos mas **ignorados**.
+- **`counterOfferInsert` não valida `acceptCounterOffer`** — é possível criar contra-proposta contra uma troca de preço fixo (que tem `requires` definidos). A oferta seria debitada e ficaria "presa" até `accept`/`delete`.
+- **`counterOfferSellerAccept` não dispara triggers** — diferente de toda outra mutação. Hooks `after_win`/notificações não rodam no aceite.
+- **Sem atomicidade entre as partes.** A liquidação é em duas etapas separadas; não há garantia de que ambos os lados completem.
+- **Sem transação MongoDB.** Falha no meio de uma operação deixa lançamentos órfãos sem rollback.
+- **Bug de duplo crédito (`sellerReceive` no fluxo de contra-proposta):** após `accept`, o swap fica com `acquired == null` e `buyer != null`. O gate de `sellerReceive` é `acquired == null && buyer == null` (AND) → a restrição **não dispara**. Logo `sellerReceive` prossegue, credita o vendedor **uma segunda vez** com `requires` (= a `offer` já creditada no `accept`) e **remove o swap**, impedindo o comprador de coletar via `counter/offer/receive`. Não chame `receive` em trocas de contra-proposta.
+- **NPE (HTTP 500) com entidades inexistentes**, em vez de restrição limpa:
+  - `sellerReceive(id)`: se o swap não existe, `swap.seller` é acessado sem guarda → NPE.
+  - `counterOfferInsert(offer)`: se `offer.swap` aponta para swap inexistente, `find()` retorna null e `swap.rewards` é acessado sem guarda → NPE.
+  - `counterOfferSellerAccept(id)`: se a offer não existe, `offer.swap` é acessado sem guarda → NPE.
+  - `counterOfferBuyerReceive(swapId)`: se o swap não existe, `swap.buyer` é acessado sem guarda → NPE.
+
+---
+
+## 8. Segurança e Permissões
+
+- **Autenticação:** Bearer token em todos os endpoints. `getPlayerFromTokenIfExist()` extrai o jogador do token (pode ser `null` em tokens administrativos/sem player).
+- **Autorização ausente entre participantes:**
+  - `acquire` **não exige** que o token seja o `buyer` — qualquer token pode adquirir em nome de outro jogador.
+  - `receive` **não exige** que o token seja o `seller`.
+  - `counterOfferSellerAccept` **não exige** que o token seja o vendedor do swap — qualquer token pode aceitar uma contra-proposta alheia.
+  - A única rastreabilidade é `extra.seller_registered_by` / `extra.buyer_registered_by`, gravado quando o autor difere do participante. **Não é um controle de acesso**, apenas auditoria.
+- **Isolamento multi-tenant:** por database, via `apiKey` (`FrontController.getInstance(apiKey)`). Não há campo de tenant nos documentos; o isolamento depende inteiramente do roteamento de conexão.
+- **Superfície de indisponibilidade (DoS leve):** os NPEs do §7 permitem que um cliente provoque HTTP 500 com IDs inexistentes. Não há injeção: as queries Jongo usam binding parametrizado (`"{_id:#}", id`), não concatenação de string.
+- **Concorrência:** mutações são `synchronized` por instância (por tenant). Não há proteção contra reentrância entre tenants distintos (esperado).
+
+---
+
+## 9. Observabilidade e Troubleshooting
+
+Como não há campo de status nem `GET /v3/swap`, o diagnóstico é feito sobre as coleções `swap`, `swap_counter_offer` e `achievement`.
+
+**Estado de uma troca:**
+```
+GET /v3/database/swap?strategy=AGGREGATE   (ou)
+POST /v3/database/swap/aggregate
+[ { "$match": { "_id": "650c67f88325771ffaa78a24" } } ]
+```
+Interprete:
+- `acquired != null` → adquirida (fluxo direto), aguardando `receive` do vendedor.
+- `accepted != null` → contra-proposta aceita, aguardando `counter/offer/receive` do comprador.
+- `buyer == null && acquired == null && accepted == null` → publicada, ainda disponível.
+- Documento ausente → troca finalizada (removida) **ou** nunca existiu.
+
+**Lançamentos de uma troca (auditoria de saldo):**
+```
+POST /v3/database/achievement/aggregate
+[ { "$match": { "extra.swap": "650c67f88325771ffaa78a24" } },
+  { "$group": { "_id": { "player": "$player", "role": "$extra.swap_role", "item": "$item" },
+                "total": { "$sum": "$total" } } } ]
+```
+
+**Contra-propostas de um swap:**
+```
+POST /v3/database/swap_counter_offer/aggregate
+[ { "$match": { "swap": "650c683c8325771ffaa78a3f" } } ]
+```
+
+### Erros comuns e causas
+
+| Sintoma | Causa provável |
+|---|---|
+| `insufficient_rewards` no insert | Vendedor não possui o saldo dos `rewards` ofertados (escrow falha). |
+| `insufficient_requirements` / `insufficient_funds` | Comprador sem saldo para `requires`/`offer`. |
+| `rewards_and_requires_must_be_different` | `requires` idêntico a `rewards` (item+total+type). |
+| `swap_have_being_acquired` no delete/acquire | Troca já tem `buyer`/`acquired`. |
+| HTTP 500 sem `restrictions` | ID inexistente atingiu um dos NPEs do §7. Verifique se o `swap`/`offer` existe antes de chamar. |
+| Saldo "sumiu" sem troca concluir | Escrow debitou no insert/counterOfferInsert e a troca segue pendente. Estorna ao excluir. |
+| Comprador não consegue coletar contra-proposta | O vendedor chamou `receive` (não `counter/offer/receive`) e o swap foi removido — ver bug de duplo crédito (§7). |
+| Saldo de comprador perdedor desatualizado após accept | `updatePlayerStatus` só roda para o vendedor no `accept`; o snapshot do perdedor atualiza eventualmente. |
+
+---
+
+## 10. Exemplos Práticos
+
+### Exemplo mínimo (troca direta)
+
+```http
+POST /v3/swap
+Authorization: Bearer <token>
+
 {
-  "offer": "650c69aa8325771ffaa78b1b"
+  "seller": "tom",
+  "rewards": [ { "total": 1, "type": 2, "item": "card_dragon" } ],
+  "requires": [ { "total": 10, "type": 0, "item": "coin" } ]
 }
 ```
+Em seguida o comprador adquire e o vendedor coleta:
+```http
+POST /v3/swap/acquire   { "buyer": "jerry", "swap": "<id>" }
+POST /v3/swap/receive   { "swap": "<id>" }
+```
+
+### Exemplo avançado (contra-proposta com `me` e período)
+
+```http
+POST /v3/swap
+Authorization: Bearer <token-do-tom>
+{
+  "seller": "me",
+  "acceptCounterOffer": true,
+  "rewards": [ { "total": 1, "type": 2, "item": "card_phoenix" } ],
+  "extra": { "provider": "marketplace" }
+}
+```
+```http
+POST /v3/swap/counter/offer
+Authorization: Bearer <token-do-jerry>
+{
+  "swap": "<swapId>",
+  "buyer": "me",
+  "offer": [ { "total": 50, "type": 0, "item": "coin", "period": "-720h;-0h" } ]
+}
+```
+```http
+POST /v3/swap/counter/offer/accept    { "offer": "<offerId>" }   # vendedor aceita
+POST /v3/swap/counter/offer/receive   { "swap": "<swapId>" }     # comprador coleta
+```
+
+### Anti-pattern (o que NÃO fazer)
+
+```http
+# ❌ ERRADO: usar /receive no fluxo de contra-proposta
+POST /v3/swap/counter/offer/accept    { "offer": "<offerId>" }   # vendedor já é creditado aqui
+POST /v3/swap/receive                 { "swap": "<swapId>" }     # credita o vendedor DE NOVO e
+                                                                 # remove o swap → comprador não coleta
+```
+Por quê: no fluxo de contra-proposta o vendedor é creditado no `accept`. Chamar `receive` aciona o bug de duplo crédito (§7). Use sempre `counter/offer/receive`.
+
+```http
+# ❌ ERRADO: trocar um nível esperando que mude o saldo
+{ "seller": "tom",
+  "rewards": [ { "total": 1, "type": 3, "item": "level_gold" } ],
+  "requires": [ { "total": 5, "type": 0, "item": "coin" } ] }
+```
+Por quê: `type:3 (LEVEL)` não é debitado/creditado (§3.3). O vendedor precisa "ter" o nível para passar na validação do escrow, mas o comprador nunca o recebe.
 
-### Receber Recompensas de Contra Proposta
-**Método:** POST
-**Endpoint:** `/v3/swap/counter/offer/receive`
+---
 
-## Validações e Testes
+## Checklist de Configuração
 
-- [ ] Troca aparece na lista de swaps
-- [ ] Comprador consegue adquirir a troca
-- [ ] Vendedor recebe recompensas após troca
-- [ ] Contra proposta é criada e listada corretamente
-- [ ] Aceitar contra proposta funciona
+- [ ] `seller` existe (player **ou** team) antes de criar.
+- [ ] Vendedor possui os `rewards` ofertados (senão `insufficient_rewards`).
+- [ ] `rewards` e `requires` usam apenas `type ∈ {0,1,2}` se você espera movimento real de saldo.
+- [ ] `rewards` ≠ `requires` (item+total+type) — senão a criação é recusada.
+- [ ] Fluxo escolhido é consistente: **direto** usa `requires` + `acquire` + `receive`; **contra-proposta** usa `acceptCounterOffer:true` + `counter/offer` + `accept` + `counter/offer/receive`.
+- [ ] ⚠ Nunca chamar `/v3/swap/receive` em troca de contra-proposta (duplo crédito + remoção).
+- [ ] Validar IDs (`swap`/`offer`) no cliente antes de chamar — IDs inexistentes podem gerar HTTP 500 (§7).
+- [ ] Lembrar do escrow: publicar uma troca já debita o vendedor; excluir antes da negociação estorna.
+- [ ] Não confiar em `Requirement.operation`/`folder`/`restrict`/`perPlayer` — são ignorados pelo swap.
+- [ ] Autorização de identidade (token = participante) deve ser garantida fora do módulo — o swap não a impõe.