funifier-mcp 0.2.26 → 0.2.28

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

@@ -1,27 +1,698 @@
-# Marketplace (Mercado)
+# `marketplace`
 
 **Acesso Studio:** `/market`
+**API Endpoint:** `/v3/package` (+ `/v3/partner/package`, `/v3/system/package`)
+**Coleções MongoDB:** `package`, `installed_package`, `package_install_log`
 
-## O que é
+> Não existe nenhuma classe `Marketplace` no código. O "marketplace" é a **face pública/cross-gamificação do recurso `Package`**. Toda a funcionalidade vive no módulo `com.funifier.engine.packages` (gerência por gamificação), `com.funifier.engine.system.packages` (gerência global) e `com.funifier.engine.system.checkout` (cobrança). Os endpoints `/v3/package/marketplace/*` apenas expõem os mesmos pacotes sem o filtro de `apikey`. Esta documentação descreve o recurso `Package` por inteiro, que é o que sustenta o marketplace.
 
-Compartilhamento e reutilização de componentes prontos para gamificações. Disponibiliza um catálogo de componentes já configurados — como desafios, rankings, widgets, modelos de gamificação — que podem ser reutilizados em diferentes projetos, acelerando a implementação.
+---
 
-## Quando usar
+## 1. Visão Geral
 
-- Para reutilizar modelos de gamificação validados
-- Para compartilhar componentes entre departamentos
-- Para acelerar implementação com templates prontos
-- Para padronizar gamificações na organização
+O recurso `package` empacota componentes prontos de uma gamificação (challenges, widgets, levels, leaderboards, triggers, mystery boxes, lotteries, point categories, actions, etc.) em um único objeto `Pack` reutilizável e instalável em **outras** gamificações.
 
-## Checklist de Configuração
+Papel arquitetural:
+
+- Um `Pack` é um **snapshot** dos componentes no momento da publicação — não uma referência viva. Ao publicar via `/v3/package`, o conteúdo JSON completo de cada componente é serializado e armazenado em `Pack.components[].content` (`engine.packages.PackageManager.insert`, linhas 84-152).
+- A **instalação** (`install`) reidrata cada componente gravando seu JSON de volta na coleção de destino (nomeada por `Component.type`), preservando o `_id` original.
+- O marketplace é apenas a leitura global desses pacotes: `/v3/package/marketplace/{id}` lê o `Pack` da coleção global `package` (sem escopo de `apikey`) e enriquece com dados do publicador.
+- Pacotes pagos têm um fluxo de checkout (Stripe/PayPal) com comissão da Funifier de 15% (`CheckoutManager.FUNIFIER_COMISSION`).
+- Pacotes `managed` propagam atualizações automaticamente para todas as instalações ativas quando republicados.
+
+Problemas que resolve:
+
+- Reuso e distribuição de configurações de gamificação entre gamificações/contas distintas.
+- Monetização de pacotes (one-time e subscription) com split de pagamento via contas Stripe conectadas.
+- Catálogo de widgets disponível para a IA (`PackAI`) sugerir e instalar componentes automaticamente.
+
+Relação com outros módulos:
+
+- `trigger` — componentes do tipo `trigger` são **re-registrados** (`triggerManager.add`) na instalação. Isto compila/registra código server-side do trigger na gamificação que instala (vide seção 8).
+- `lottery` — único componente com tratamento especial na instalação/remoção (usa `lotteryManager` em vez de gravação raw).
+- `checkout` / `account` / `game` / `partner` — fluxo de cobrança, identificação de vendedor/comprador e publicação por parceiros.
+- `widget` (Widget_V3) — alvo principal dos pacotes de IA (`findPackagesByArtificialIntelligenceModule("widget")` em `AIRest`).
+- `technique_field` — fonte dos códigos GT em `Pack.techniques`.
+
+---
+
+## 2. Arquitetura e Fluxos
+
+### 2.1 Classes envolvidas
+
+| Classe | Papel |
+|---|---|
+| `com.funifier.engine.packages.Pack` | Entidade raiz — documento da coleção `package` / `installed_package` |
+| `com.funifier.engine.packages.Component` | Subentidade — um componente snapshotado (`type` + `content` JSON) |
+| `com.funifier.engine.packages.PackMedia` | Subentidade — mídia de apresentação (image/video) |
+| `com.funifier.engine.packages.PackAI` | Subentidade — marca o pacote como utilizável pela IA |
+| `com.funifier.engine.packages.PackCheckout` | Subentidade — referência ao checkout + lista de preços |
+| `com.funifier.engine.packages.PackageManager` | Manager **por gamificação** (via `ManagerFactory`): insert (com snapshot), install, uninstall, find, findAll, delete, findInstalled, findOptionsByEntity |
+| `com.funifier.engine.system.packages.PackageManager` | Manager **global** (via `SystemFactory`): insert (sem snapshot), find/delete sem escopo, aggregates, queries por conta/IA, instalações ativas |
+| `com.funifier.engine.system.packages.PackageInstallationLog` | Entidade da coleção `package_install_log` |
+| `com.funifier.engine.system.checkout.Checkout` | Config de provedor de pagamento (stripe/paypal/pagarme) |
+| `com.funifier.engine.system.checkout.CheckoutPricing` | Definição de preço (one_time/subscription, unit, currency, interval) |
+| `com.funifier.engine.system.checkout.CheckoutManager` | Sessões de checkout, callbacks, faturas, cancelamento, uso medido |
+| `com.funifier.rest.v3.rest.PackageRest` | Controller principal `/v3/package` (gamificação) |
+| `com.funifier.rest.v3.rest.partner.PackageRest` | Controller `/v3/partner/package` (parceiros) |
+| `com.funifier.rest.v3.rest.system.PackageRest` | Controller `/v3/system/package` (admin) |
+
+Não há `Dao`/`Repository` dedicado — toda manipulação MongoDB é feita diretamente via Jongo dentro dos managers.
+
+### 2.2 Pipeline de publicação — `POST /v3/package` → `engine.packages.PackageManager.insert(Pack)`
+
+Sequência exata (linhas 84-151):
+
+```
+[1] Se pack.id vazio:
+      pack.id = Guid.newShortGuid()
+      pack.creation = now
+[2] pack.updated = now
+[3] pack.apikey = manager.getApiKey()      ← FORÇADO; ignora qualquer apikey enviado pelo cliente
+[4] Materializa componentes (substitui pack.components inteiro):
+      para cada item em pack.components com id e type não-vazios:
+        se item.id == "*":
+            copia até 1000 docs da coleção item.type:
+              cria Component { id, title=getTitleByEntity(...), type, content=BSON strict do doc }
+        senão:
+            busca 1 doc por _id na coleção item.type
+            se existe: item.content = BSON strict do doc; adiciona à lista
+      (exceções por item são engolidas → System.out.println, item é descartado silenciosamente)
+[5] pack.components = lista materializada
+[6] salva na coleção `package` (Jongo save → upsert por _id)
+```
+
+Pseudocódigo da derivação de título (`getTitleByEntity`, linhas 41-80) — usado só no caso `"*"`:
+
+```
+se type == action            → title = doc.action
+senão se type == point_category → title = doc.category
+senão se type == challenge   → title = doc.challenge
+senão se type ∈ {widget_v3, leaderboard, mystery_box, lottery} → title = doc.title
+senão se type == level       → title = doc.level
+senão se type == trigger     → title = doc.name
+senão                        → primeiro existente entre doc.title, doc.name, doc.label, ou "_id"
+```
+
+Após o `insert`, o controller (`PackageRest.insert`, linhas 113-128) executa a propagação `managed` (vide seção 2.7).
+
+### 2.3 Pipeline de instalação — `GET /v3/package/install/{id}` → `engine.packages.PackageManager.install(id)`
+
+```mermaid
+flowchart LR
+    A["install(id)"] --> B{"existe em<br/>installed_package?"}
+    B -->|sim| C["operation = update<br/>se pre.apikey != installer:<br/>remove componentes antigos"]
+    B -->|não| D["operation = install"]
+    C --> E["carrega Pack da<br/>coleção `package`"]
+    D --> E
+    E --> F{"pack.apikey ==<br/>installer apikey?"}
+    F -->|sim| G["throw UNAUTHORIZED<br/>'só instala pacotes de<br/>outras gamificações'"]
+    F -->|não| H["para cada component:<br/>insertContentByComponent"]
+    H --> I["grava PackageInstallationLog<br/>(install ou update)"]
+    I --> J["salva Pack em<br/>installed_package (log=logId)"]
+    J --> K{"?session= presente?"}
+    K -->|sim| L["applyStripePackageCheckoutCallback<br/>→ grava subscription no log"]
+    K -->|não| M["fim"]
+    L --> M
+```
+
+Detalhamento (linhas 161-221):
+
+1. Busca registro anterior em `installed_package` por `_id`. Se existe → `operation = update`; e se `pre.apikey != installer` → remove todos os componentes antigos via `deleteContentByComponent` (cleanup de referências removidas em versões anteriores).
+2. Carrega o `Pack` da coleção global `package`.
+3. **Guard de propriedade**: se `pack.apikey == installer.apikey` → lança `FunifierException` UNAUTHORIZED. Só é possível instalar pacotes criados em **outra** gamificação.
+4. Para cada `Component`, chama `insertContentByComponent` (síncrono).
+5. Cria `PackageInstallationLog` e salva em `package_install_log`.
+6. Salva o `Pack` na coleção `installed_package` com `pack.log = log.id`.
+
+`insertContentByComponent` (linhas 416-469):
+
+```
+doc = BasicDBObject.parse(component.content)
+collection(component.type).save(doc)      ← upsert por _id; sobrescreve doc local de mesmo _id
+se component.type == trigger:
+    triggerManager.add( triggerManager.findById(component.id) )   ← re-registra o trigger
+```
+
+`deleteContentByComponent` (linhas 471-513):
+
+```
+se component.type == lottery:
+    lotteryManager.delete(component.id)
+senão:
+    collection(component.type).remove("{_id:#}", component.id)    ← remoção raw por _id
+```
+
+### 2.4 Pipeline de desinstalação — `DELETE /v3/package/uninstall/{id}` → `uninstall(id)`
+
+```
+[1] carrega Pack de installed_package por _id (se null → no-op)
+[2] para cada component: deleteContentByComponent
+[3] tenta cancelStripePackageSubscription (try/catch engolido)
+[4] remove Pack de installed_package
+[5] grava PackageInstallationLog operation=uninstall
+```
+
+Não há verificação de integridade: se outro pacote ou configuração local compartilhar o mesmo `_id` de um componente, ele é removido junto (seções 5 e 8).
+
+### 2.5 Marketplace / descoberta
+
+- `GET /v3/package/marketplace/{id}` → `system.packages.PackageManager.find(id)` (coleção `package`, **sem escopo de apikey**). Em seguida, se `pack.apikey != null`, enriquece `pack.provider` com `account.extra` do publicador (`PackageRest.findMarketplace`, linhas 246-256). Retorna o `Pack` completo, incluindo `components` (todo o JSON snapshotado) e o hash `password`.
+- `POST /v3/package/marketplace/aggregate` → `system.packages.PackageManager.findAllAggregate(aggregations, range)`. Executa um **pipeline de agregação fornecido cru pelo cliente** sobre a coleção `package`, **sem nenhum filtro server-side** (`PackageRest.findAllAggregate`, linhas 258-272 + `system PackageManager.findAllAggregate`, linhas 75-102). Paginação via header `Range` (default `0-100`).
+
+A descoberta do catálogo é inteiramente dirigida pelo cliente: o frontend do `/market` envia seu próprio `$match` (ex.: `visibility: globally`, `status: approved`). O servidor não impõe esses filtros (vide seção 7).
+
+### 2.6 Fluxo de checkout de pacote pago
+
+```mermaid
+sequenceDiagram
+    participant C as Cliente (/market)
+    participant API as PackageRest
+    participant CM as CheckoutManager
+    participant S as Stripe (conta conectada)
+    C->>API: GET /v3/package/checkout?pack&price
+    API->>CM: createStripePackageCheckoutSession(checkout, pack, pricing, seller, buyer)
+    CM->>S: Session.create(line_items|subscription_data, application_fee, connected acct)
+    S-->>CM: session (url, id)
+    CM-->>C: session + pk + CONNECTED_STRIPE_ACCOUNT_ID
+    C->>S: paga na sessão Stripe
+    S-->>C: redirect success_url ...?session_id={ID}
+    C->>API: GET /v3/package/install/{id}?session={ID}
+    API->>API: install(id)  (instala componentes + cria install log)
+    API->>CM: applyStripePackageCheckoutCallback(checkout, pack, session, logId, buyer)
+    CM->>S: Session.retrieve(session)
+    CM->>CM: grava PartnerSubscription no install log
+    CM-->>C: payment=OK
+```
+
+Notas (`CheckoutManager`, linhas 155-355):
+
+- `one_time` → `line_items` com `amount = price.price * 100` e `application_fee_amount = 15%` (linhas 170-186).
+- `subscription` → `subscription_data` com `application_fee_percent = 15` (linhas 190-201).
+- `success_url`/`cancel_url` apontam para `https://my.funifier.com/market/install/{id}/payment/...` (linhas 208-209) — confirma o Studio em `/market`.
+- Uso medido (`updateStripePackageTotalUsage`): reporta ao Stripe o total de jogadores ativos (`unit=player`) ou de requests (`unit=request`) da conta.
+
+### 2.7 Propagação de pacote `managed`
+
+```mermaid
+flowchart LR
+    A["POST /v3/package<br/>(managed=true)"] --> B["insert()"]
+    B --> C["findPackageActiveInstalls(pack.id)"]
+    C --> D{"para cada install ativo"}
+    D --> E["gameManager.findByApiKey(install.apikey)"]
+    E --> F{"game existe?"}
+    F -->|sim| G["FrontController(install.apikey)<br/>.getPackageManager().install(pack.id)"]
+    F -->|não| D
+    G --> D
+```
+
+`PackageRest.insert` (linhas 113-128): se `pack.managed`, após salvar, busca todas as instalações ativas (`system.PackageManager.findPackageActiveInstalls` — agrega `package_install_log`, pega o último `operation` por (pack, account, apikey) e filtra `install|update`) e re-instala o pacote em cada gamificação que ainda existe. **Síncrono**, com `try/catch` que engole exceções e um `//TODO colocar atualizacao para ser feita assincronamente`.
+
+---
+
+## 3. Estrutura dos Objetos
+
+### 3.1 `Pack` — documento raiz (coleções `package` e `installed_package`)
+
+| Campo | Tipo | Padrão | Obrigatório | Descrição |
+|---|---|---|---|---|
+| `_id` | String | short GUID auto | — | Gerado em `insert` se vazio (campo Java `id`, `@JsonProperty("_id")`) |
+| `title` | String | — | sim (comentário) | Título do pacote. Não validado server-side |
+| `image` | String | — | não | Ícone do pacote |
+| `screenshot` | String | — | não | Screenshot |
+| `medias` | List<PackMedia> | `[]` | não | Imagens/vídeos de apresentação |
+| `description` | String | — | sim (comentário) | Descrição. Não validado server-side |
+| `tags` | List<String> | `[]` | não | Tags livres |
+| `techniques` | List<String> | `[]` | não | Códigos GT (técnicas de jogo) — vide 3.7 |
+| `apikey` | String | forçado | sim | ApiKey da gamificação que criou o pacote. **Sobrescrito** no `insert` de `/v3/package`; **não** sobrescrito nos endpoints partner/system |
+| `priority` | int | `0` | não | Quanto maior, maior a prioridade; 0 = nenhuma |
+| `instructions` | String | — | não | Instruções de uso |
+| `instructions_url` | String | — | não | URL de instruções |
+| `password` | String | — | não | Hash BCrypt. Definido só via `/password`. **Não é verificado em find/install** e **vaza** na resposta do marketplace (seção 8) |
+| `visibility` | String | `"private"` | não | `private` ou `globally`. **Não lido pelo servidor** |
+| `status` | String | `null` | não | `waiting` / `approved` / `denied`. **Não lido pelo servidor** |
+| `components` | List<Component> | `[]` | não | Componentes snapshotados. Substituído na publicação via `/v3/package` |
+| `creation` | Date | now no insert | — | Data de criação |
+| `updated` | Date | now no insert | — | Última atualização |
+| `managed` | boolean | `false` | não | Se `true`, atualizações se propagam às instalações ativas |
+| `provider` | Map<String,String> | runtime | — | `account.extra` do publicador. **Só preenchido em tempo de execução** no `findMarketplace`; não persiste |
+| `ai` | PackAI | `null` | não | Marca o pacote como utilizável pela IA |
+| `price_type` | String | `null` | não | `free` ou `checkout` |
+| `checkout` | PackCheckout | `null` | não | Config de cobrança (pacotes pagos) |
+| `log` | String | `null` | — | Id do `PackageInstallationLog` da instalação corrente (preenchido em `install`) |
+
+**Campos computados (não persistem):** `provider` (preenchido só no `findMarketplace`).
+
+**Campos sobrescritos silenciosamente no save:** `apikey` (forçado para a gamificação corrente no `insert` de `/v3/package`), `id`/`creation`/`updated` (gerados), `components` (substituído pela materialização).
+
+**Campos aceitos mas ignorados pelo runtime:** `visibility`, `status`, `password` (no fluxo de leitura/instalação), `priority` (armazenado mas não usado em nenhuma ordenação server-side; ordenação fica a cargo do pipeline do cliente).
+
+#### Enums / constantes do `Pack`
+
+| Constante | Valor | Significado |
+|---|---|---|
+| `VISIBILITY_PRIVATE` | `private` | Visibilidade privada (convenção de cliente) |
+| `VISIBILITY_GLOBALLY` | `globally` | Visível no marketplace global (convenção de cliente) |
+| `STATUS_WAITING` | `waiting` | Aguardando aprovação (não enforçado) |
+| `STATUS_APPROVED` | `approved` | Aprovado (não enforçado) |
+| `STATUS_DENIED` | `denied` | Negado (não enforçado) |
+| `PRICE_TYPE_FREE` | `free` | Pacote gratuito |
+| `PRICE_TYPE_CHECKOUT` | `checkout` | Pacote pago (usa `checkout`) |
+
+### 3.2 `Component` — componente snapshotado
+
+| Campo | Tipo | Padrão | Obrigatório | Descrição |
+|---|---|---|---|---|
+| `_id` | String | — | sim | Id do documento de origem; preservado na reidratação (campo Java `id`) |
+| `type` | String | — | sim | **Nome da coleção MongoDB** de destino (ex.: `challenge`, `widget_v3`, `trigger`). Aceita `"*"` na publicação para copiar a coleção inteira (até 1000 docs) |
+| `title` | String | — | não | Título legível (derivado por `getTitleByEntity` no caso `"*"`) |
+| `content` | String | — | sim (após publicação) | JSON (BSON strict-mode) completo do documento. Gerado server-side na publicação via `/v3/package` |
+
+> Na publicação via `/v3/package`, o cliente envia apenas `{ _id, type }` (ou `{ _id: "*", type }`); o `content` é preenchido pelo servidor. Nos endpoints partner/system, o `content` **não** é materializado — o cliente deve fornecê-lo.
+
+### 3.3 `PackMedia`
+
+| Campo | Tipo | Descrição |
+|---|---|---|
+| `title` | String | Título da mídia |
+| `type` | String | `image` ou `video` |
+| `url` | String | URL do conteúdo |
+
+### 3.4 `PackAI`
+
+| Campo | Tipo | Descrição |
+|---|---|---|
+| `module` | String | Módulo-alvo da IA (ex.: `widget`) |
+| `info` | String | Texto auxiliar fornecido à IA |
+
+> Comentário no código: pacotes de IA devem ser **gratuitos** e ter **apenas um componente** (ex.: 1 widget). Não há validação que imponha isso. Consumido por `findPackagesByArtificialIntelligenceModule(module)`, que projeta `{_id, title, info, module}`.
+
+### 3.5 `PackCheckout` / `CheckoutPricing`
+
+`PackCheckout`:
+
+| Campo | Tipo | Descrição |
+|---|---|---|
+| `_id` | String | Id da configuração `Checkout` (provedor) |
+| `pricing` | List<CheckoutPricing> | Lista de preços; `getPricing(id)` retorna o item por `id` |
+
+`CheckoutPricing`:
+
+| Campo | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `id` | String | `null` | Id do preço (ex.: id de Plan Stripe para subscription) |
+| `model` | String | `null` | `one_time` ou `subscription` |
+| `unit` | String | `null` | `gamification` ou `player` (e `request` no cálculo de uso) |
+| `currency` | String | `null` | Moeda |
+| `price` | double | `0` | Valor (multiplicado por 100 para centavos no Stripe) |
+| `interval` | String | `null` | Ex.: `month` |
+
+`Checkout` (config de provedor): constantes `PROVIDER_STRIPE` (`stripe`), `PROVIDER_PAYPAL` (`paypal`), `PROVIDER_PAGARME` (`pagarme`). No fluxo de pacote só stripe e paypal são roteados (`PackageRest.createCheckoutSession`).
+
+### 3.6 `PackageInstallationLog` (coleção `package_install_log`)
+
+| Campo | Tipo | Descrição |
+|---|---|---|
+| `_id` | String | short GUID (campo Java `id`) |
+| `pack` | String | Id do pacote |
+| `account` | String | Conta que solicitou a instalação |
+| `apikey` | String | Gamificação onde o pacote foi instalado |
+| `operation` | String | `install` / `update` / `uninstall` |
+| `time` | Date | Quando a operação ocorreu |
+| `subscription` | PartnerSubscription | Assinatura do gateway (preenchida no callback de pagamento); `null` para pacotes gratuitos |
+
+### 3.7 Técnicas de jogo (`techniques`)
+
+`Pack.techniques` é uma `List<String>` de **códigos GT** (game techniques, Octalysis). As opções vêm da coleção `technique_field` (`Entity.GAME_TECHNIQUE_FIELD`), expostas via `GET /v3/package/component/type/technique_field` → `findOptionsByEntity` (linhas 340-344), que retorna cada `_id` como value e label. Os códigos são armazenados como texto livre; não há validação server-side de que pertençam ao catálogo.
+
+---
+
+## 4. Endpoints
+
+> Autenticação em todos: **Bearer token** (`AuthBean`). Os endpoints `/partner/*` e `/system/*` exigem ainda permissão de sistema (`checkSystemPermission`).
+
+### Controller principal `/v3/package` (escopo: gamificação)
 
-- [ ] Acessar o marketplace via /market
-- [ ] Selecionar componente desejado
-- [ ] Importar para a gamificação atual
-- [ ] Customizar conforme necessidade
+**`GET /v3/package/{id}`** — `find`
 
-## Validações e Testes
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Retorna 1 pacote por id |
+| Escopo | **Global, sem filtro de apikey** (lê coleção `package` via `SystemFactory`). Qualquer gamificação lê qualquer pacote por id |
+| Resposta | `Pack` com `null` fields removidos (inclui `components` e `password`) |
+
+**`GET /v3/package`** — `findAll`
+Lista apenas pacotes da gamificação corrente (`find("{apikey:#}", apiKey)`).
+
+**`POST /v3/package`** — `insert`
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Publica/atualiza um pacote |
+| Body | `Pack` (componentes como `{_id, type}` ou `{_id:"*", type}`) |
+| Full replace | `Pack` inteiro; `components` é re-materializado (substituição total) |
+| Comportamento | Força `apikey`, gera `id/creation/updated`, snapshota componentes; se `managed`, propaga às instalações ativas (síncrono) |
+
+**`DELETE /v3/package/{id}`** — `delete`
+Remove só se `_id` **e** `apikey` baterem (`remove("{_id:#, apikey:#}", ...)`). Não toca em `installed_package`.
+
+**`PUT /v3/package/password`** — `changePassword`
+Body `{ pack, password }`. Só o dono (`pack.apikey == apiKey`) altera; grava hash BCrypt.
+
+**`POST /v3/package/password/verify`** — `verifyPassword`
+Body `{ pack, password }`. Retorna `{authorized:true}` se o BCrypt bater. **Endpoint isolado** — não é chamado por `find`/`install`.
+
+**`GET /v3/package/component/type/{type}`** — `findOptionsByType`
+Retorna `[{_id, label}]` de uma coleção (action, point_category, challenge, widget_v3, level, leaderboard, trigger, mystery_box, lottery, technique_field, ou genérico). Alimenta o seletor de componentes do Studio.
+
+**`GET /v3/package/marketplace/{id}`** — `findMarketplace`
+Lê pacote global + enriquece `provider`. Retorna o `Pack` completo (componentes + hash de senha). Sem gate de visibility/status/password.
+
+**`POST /v3/package/marketplace/aggregate`** — `findAllAggregate`
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Lista/filtra pacotes do marketplace |
+| Body | Pipeline de agregação MongoDB **cru** (array) |
+| Escopo | **Nenhum filtro server-side** — opera sobre toda a coleção `package` |
+| Paginação | Header `Range` (default `0-100`) |
+
+**`GET /v3/package/installed/{id}`** / **`GET /v3/package/installed`** / **`GET /v3/package/installedIds`**
+Leem da coleção `installed_package` (escopo da conexão da gamificação).
+
+**`GET /v3/package/install/{id}?session={sid}`** — `install`
+Instala os componentes na gamificação corrente. Com `session`, dispara o callback de pagamento Stripe que grava a `subscription` no install log.
+
+**`DELETE /v3/package/uninstall/{id}`** — `uninstall`
+Remove componentes, tenta cancelar assinatura, remove de `installed_package`, grava log `uninstall`.
+
+**`GET /v3/package/checkout?pack={id}&price={priceId}`** — `createCheckoutSession`
+Cria sessão Stripe ou PayPal para compra do pacote.
+
+**`GET /v3/package/{id}/plan/billing`** — faturas Stripe da assinatura do pacote instalado.
+**`DELETE /v3/package/{id}/plan/subscription`** — cancela a assinatura.
+**`GET /v3/package/{id}/plan/usage`** — reporta uso medido (jogadores/requests) ao Stripe.
+**`GET /v3/package/install/{id}/log`** — retorna o `PackageInstallationLog` da instalação.
+
+#### Exemplo — publicar pacote (snapshot de componentes)
+
+```http
+POST /v3/package
+Authorization: Bearer <token>
+Content-Type: application/json
+```
+```json
+{
+  "title": "Pacote de Onboarding",
+  "description": "Challenges + widget de boas-vindas",
+  "visibility": "globally",
+  "status": "approved",
+  "price_type": "free",
+  "components": [
+    { "_id": "welcome_challenge", "type": "challenge" },
+    { "_id": "*", "type": "widget_v3" }
+  ]
+}
+```
+Resposta (201) — note `apikey`/`creation`/`updated` preenchidos e `components[].content` materializado pelo servidor.
+
+#### Exemplo — listar marketplace (pipeline do cliente)
+
+```http
+POST /v3/package/marketplace/aggregate
+Range: items=0-49
+```
+```json
+[
+  { "$match": { "visibility": "globally", "status": "approved" } },
+  { "$sort": { "priority": -1, "updated": -1 } },
+  { "$project": { "title": 1, "image": 1, "description": 1, "price_type": 1, "techniques": 1 } }
+]
+```
+
+### Controller `/v3/partner/package` (escopo: parceiro)
+
+Exige `checkSystemPermission("api", "/partner/package", op)`. Resolve o `Partner` pelo claim `account` do token.
+
+- `GET /{id}` — `find`: só se o `accountId` do `game` do pacote == `accountId` do parceiro.
+- `POST /` — `insert`: valida o mesmo match de conta; usa `system.PackageManager.insert` → **não materializa componentes nem força apikey** (o cliente fornece `content` e `apikey`).
+- `DELETE /{id}` — `delete`: valida match de conta.
+- `POST /aggregate` — `findAllAggregate` **com escopo**: prepende `{$match:{_id:{$in:[ids da conta]}}}` antes do pipeline do cliente.
+- `PUT /password` — altera senha (sem checagem de dono).
+- `GET /stripe/plan`, `GET /stripe/product` — lista planos/produtos Stripe do vendedor.
+
+### Controller `/v3/system/package` (escopo: admin)
+
+Exige `checkSystemPermission("api", "/system/package", op)`.
+
+- `GET /{id}` — find global.
+- `POST /` — insert global (sem materialização/forçar apikey).
+- `POST /install` `{apikey, pack}` — instala em uma gamificação arbitrária.
+- `POST /uninstall` `{apikey, pack}` — desinstala de uma gamificação arbitrária.
+- `DELETE /{id}` — delete global.
+- `POST /aggregate` — `findAllAggregate` **sem escopo**.
+- `POST /install/log/aggregate` — agregação crua sobre `package_install_log`.
+- `PUT /password` — altera senha.
+
+---
+
+## 5. Regras de Negócio
+
+Regras que existem no código mas não no schema:
+
+- **Snapshot na publicação (`/v3/package`)**: o pacote captura o JSON dos componentes no momento da publicação. Mudanças posteriores nos componentes originais **não** refletem no pacote até nova publicação.
+- **`apikey` forçado (`/v3/package`)**: qualquer `apikey` no body é sobrescrito pela gamificação autenticada. Os endpoints partner/system **não** forçam isso.
+- **Não pode instalar o próprio pacote**: `install` lança UNAUTHORIZED se `pack.apikey == installer.apikey`. Pacotes só instalam em gamificações diferentes da criadora.
+- **Instalação reidrata por `_id` preservado**: `insertContentByComponent` faz `save` do doc com o `_id` original → **sobrescreve** qualquer documento local de mesmo `_id` na coleção de destino (upsert).
+- **Desinstalação remove por `_id`**: `deleteContentByComponent` apaga o doc por `_id` sem checar proveniência → pode apagar configuração local que coincida no `_id`.
+- **Update limpa a versão anterior**: ao reinstalar (operation=update) com `pre.apikey != installer`, todos os componentes da versão anterior são removidos antes de instalar os novos.
+- **Componentes `trigger` re-registram código**: instalar um pacote com componente `trigger` executa `triggerManager.add`, registrando o trigger (e seu script) na gamificação.
+- **Componentes `lottery` têm caminho próprio**: instalação grava raw como qualquer outro, mas remoção usa `lotteryManager.delete`.
+- **Cópia em massa (`"*"`)**: limitada a **1000 documentos** por coleção (`.find().limit(1000)`).
+- **Comissão da plataforma**: 15% (`FUNIFIER_COMISSION`) aplicada como `application_fee_amount` (one_time) ou `application_fee_percent` (subscription).
+- **`managed` propaga atualizações**: republicar um pacote `managed` reinstala em todas as instalações ativas (síncrono, exceções engolidas).
+- **Multi-tenant fraco no marketplace**: leitura por id e o `aggregate` do marketplace são globais — qualquer gamificação autenticada vê qualquer pacote, independentemente de `visibility`/`status`.
+
+---
+
+## 6. Comportamentos Automáticos
+
+| Comportamento | Trigger | Impacto | Persistência |
+|---|---|---|---|
+| Geração de `_id` curto | `insert` com `id` vazio | Define `pack.id` | `package` |
+| `creation` / `updated` automáticos | `insert` | Timestamps | `package` |
+| `apikey` forçado | `insert` (`/v3/package`) | Sobrescreve apikey do body | `package` |
+| Materialização de componentes (snapshot) | `insert` (`/v3/package`) | `components[].content` preenchido; lista substituída | `package` |
+| Cópia em massa `"*"` | componente com `_id == "*"` | Até 1000 docs viram componentes | `package` |
+| Propagação `managed` | `insert` com `managed=true` | Reinstala em instalações ativas | `installed_package`, coleções de destino |
+| Re-registro de trigger | `install` de componente `trigger` | `triggerManager.add` (registra código) | coleção `trigger` + runtime |
+| Limpeza de versão antiga | `install` quando já instalado (update) | Remove componentes anteriores | coleções de destino |
+| Cancelamento de assinatura | `uninstall` | Tenta cancelar subscription Stripe | gateway externo |
+| Gravação de install log | `install` / `uninstall` | Registro de auditoria | `package_install_log` |
+| Callback de pagamento | `install?session=` | Grava `subscription` no log | `package_install_log` |
+| Enriquecimento `provider` | `findMarketplace` | Adiciona `account.extra` à resposta | nenhuma (runtime) |
+
+```mermaid
+flowchart LR
+    A["install component"] --> B{"type?"}
+    B -->|trigger| C["save raw +<br/>triggerManager.add()"]
+    B -->|lottery| D["save raw<br/>(remoção usa lotteryManager)"]
+    B -->|outros| E["save raw (upsert por _id)"]
+```
+
+---
+
+## 7. Suportado vs NÃO Suportado
+
+### ✅ Suportado
+
+- Publicação de pacotes com snapshot automático de componentes (`/v3/package`).
+- Cópia de coleção inteira via `"*"` (até 1000 docs).
+- Instalação/desinstalação cross-gamificação com log de auditoria.
+- Atualização automática de instalações para pacotes `managed`.
+- Pacotes pagos (one-time e subscription) via Stripe e PayPal, com comissão de 15%, faturas, cancelamento e uso medido.
+- Marketplace por agregação crua dirigida pelo cliente (listagem/filtro/projeção).
+- Pacotes para IA (`PackAI`) consumidos pelo módulo de IA (widgets).
+- Senha de pacote (definição/verificação via endpoints dedicados).
+- Publicação/gestão por parceiros (escopo de conta) e por admin (global).
+
+### ❌ NÃO Suportado / comportamento ausente
+
+- **Aprovação/visibilidade enforçada**: `status` (`waiting/approved/denied`) e `visibility` (`private/globally`) são **declarados mas nunca lidos** pelo servidor. Não há fluxo de moderação server-side; o filtro é 100% do cliente.
+- **Proteção por senha real**: `password` **não** é verificado em `find`/`findMarketplace`/`install`. O hash inclusive é retornado na resposta. A verificação só existe no endpoint isolado `/password/verify`, que nada bloqueia.
+- **Isolamento multi-tenant na leitura**: `GET /v3/package/{id}` e `/v3/package/marketplace/*` não filtram por `apikey` — leitura global de qualquer pacote.
+- **Webhooks de instalação**: nenhum webhook é disparado em publish/install/uninstall (confirmado — sem referências a `WebhookManager` no módulo).
+- **Eventos de gamificação (`before_win`/`after_win`/`fireAction`)**: não são disparados pelo pacote.
+- **Scheduler/job**: nenhum job processa as coleções `package`/`installed_package`/`package_install_log`. A propagação `managed` é síncrona no `insert`, não agendada.
+- **Materialização de componentes nos endpoints partner/system**: o `system.PackageManager.insert` **não** snapshota componentes nem força `apikey` — o cliente deve fornecer `content`.
+- **Ordenação por `priority`**: o campo existe mas não há ordenação server-side; depende do pipeline do cliente.
+- **Versionamento de pacote**: não há histórico de versões; `install` de uma versão atualizada sobrescreve a anterior.
+- **Código legado / morto**:
+  - `engine.packages.PackageManager.findContentByEntity` (linhas 366-414): só tem chamadores comentados → **código morto**.
+  - Blocos comentados grandes em `insertContentByComponent`/`deleteContentByComponent` (tratamento tipado por entidade) — substituídos por gravação/remoção raw genérica.
+  - Loop comentado no início do `insert` (linhas 95-99).
+
+---
+
+## 8. Segurança e Permissões
+
+- **Autenticação**: Bearer token (`AuthBean`) em todos os endpoints. `/partner/*` e `/system/*` exigem permissão de sistema adicional (`checkSystemPermission`); `/v3/package` (gamificação) **não** exige permissão extra além do token.
+- **Isolamento por tenant — fraco no marketplace**:
+  - `GET /v3/package/{id}` lê a coleção `package` global sem filtro de `apikey`.
+  - `POST /v3/package/marketplace/aggregate` roda pipeline cru sobre **todos** os pacotes, sem `$match` de escopo. Qualquer gamificação autenticada lê qualquer pacote (inclusive pagos/privados) e todo o conteúdo snapshotado dos componentes.
+- **Injeção de agregação (NoSQL)**: `findAllAggregate` (marketplace, partner e system) e `findAllInstallLogAggregate` recebem o pipeline diretamente do cliente e o executam via Jongo. A variante partner mitiga prependendo `$match _id $in [ids da conta]`; a do marketplace e a do system **não** mitigam. Estágios como `$lookup`, `$out`/`$merge` ou expressões `$where` ficam a depender apenas do que o servidor MongoDB permite.
+- **Execução de código via componente `trigger`**: instalar um pacote de terceiros que contenha um componente `trigger` re-registra o trigger (`triggerManager.add`, linha 427), introduzindo script server-side (Groovy/Java) na gamificação que instala. Risco de supply-chain: trate pacotes de origem desconhecida como código não confiável.
+- **Sobrescrita/remoção por `_id`**: instalação faz upsert por `_id` (pode clobберar config local de mesmo `_id`); desinstalação remove por `_id` sem checar proveniência (pode apagar config local homônima).
+- **Vazamento de hash de senha**: `findMarketplace`/`find` retornam `Pack` via `toJsonRemoveNullFields`, que só remove nulos — o campo `password` (hash BCrypt) é exposto na resposta. Não há `@JsonIgnore`.
+- **Pagamentos**: chaves Stripe da Funifier (`StripeUtil.getFunifierSecretKey`) são usadas server-side; a conta conectada do vendedor (`stripe.stripe_user_id`) recebe o pagamento menos 15% de comissão. URLs de retorno são fixas em `my.funifier.com`.
+
+---
+
+## 9. Observabilidade e Troubleshooting
+
+Diagnóstico rápido:
+
+```http
+# O pacote existe na coleção global?
+GET /v3/package/marketplace/{id}
+
+# Está instalado nesta gamificação?
+GET /v3/package/installed/{id}
+GET /v3/package/installedIds
+
+# Histórico de instalação (admin)
+POST /v3/system/package/install/log/aggregate
+Range: items=0-99
+[ { "$match": { "pack": "<packId>" } }, { "$sort": { "time": -1 } } ]
+```
+
+Queries MongoDB úteis:
+
+```js
+// Pacotes publicados por uma gamificação
+db.package.find({ apikey: "<APIKEY>" })
+
+// Instalações ativas de um pacote (último install/update por gamificação)
+db.package_install_log.aggregate([
+  { $match: { pack: "<packId>" } },
+  { $sort: { time: 1 } },
+  { $group: { _id: { pack: "$pack", apikey: "$apikey" }, operation: { $last: "$operation" }, time: { $max: "$time" } } },
+  { $match: { operation: { $in: ["install", "update"] } } }
+])
+
+// Pacotes de IA por módulo
+db.package.aggregate([ { $match: { "ai.module": "widget" } } ])
+```
+
+Erros comuns e causas:
+
+| Sintoma | Causa provável |
+|---|---|
+| `This package was created in this gamification...` (UNAUTHORIZED) | Tentou instalar pacote da própria gamificação. Só instala de outra |
+| Componente "some" do pacote não foi instalado | Item sem `_id`/`type`, ou exceção engolida na materialização (`System.out.println`); confira logs do servidor |
+| Atualização de pacote `managed` não chegou em uma instalação | Gamificação inexistente (`findByApiKey == null`) ou exceção engolida na propagação síncrona |
+| Config local sumiu após instalar pacote | Componente do pacote tinha o mesmo `_id` e sobrescreveu/removeu o doc local |
+| Pacote "privado" aparece para terceiros | `visibility`/`status` não são enforçados; só o pipeline do cliente filtra |
+| Cobrança não registrou assinatura | `install` chamado sem `?session=`, ou falha no `applyStripePackageCheckoutCallback` (Stripe) |
+
+O que verificar quando algo não funciona:
+- Existência do pacote em `package` (global) vs `installed_package` (local).
+- `pack.apikey` (criador) vs apikey que está instalando.
+- Tipos de componente apontam para coleções válidas (`Component.type` == nome da coleção).
+- Para pagos: `price_type == "checkout"`, `checkout._id` válido e provedor `stripe`/`paypal`.
+
+---
+
+## 10. Exemplos Práticos
+
+### Mínimo funcional — pacote gratuito com 1 challenge
+
+```http
+POST /v3/package
+Authorization: Bearer <token>
+```
+```json
+{
+  "title": "Desafio Diário",
+  "description": "Um challenge de login diário",
+  "price_type": "free",
+  "components": [ { "_id": "daily_login", "type": "challenge" } ]
+}
+```
+
+### Avançado — pacote `managed` pago, com mídia, técnicas e cópia em massa
+
+```http
+POST /v3/package
+Authorization: Bearer <token>
+```
+```json
+{
+  "title": "Suite de Engajamento Pro",
+  "description": "Challenges, widgets e triggers de engajamento",
+  "image": "https://cdn.exemplo.com/icon.png",
+  "screenshot": "https://cdn.exemplo.com/shot.png",
+  "medias": [ { "title": "Demo", "type": "video", "url": "https://youtu.be/xyz" } ],
+  "tags": ["engajamento", "onboarding"],
+  "techniques": ["GT01", "GT08"],
+  "visibility": "globally",
+  "status": "approved",
+  "managed": true,
+  "priority": 10,
+  "price_type": "checkout",
+  "checkout": {
+    "_id": "<checkoutConfigId>",
+    "pricing": [
+      { "id": "<stripePlanId>", "model": "subscription", "unit": "player", "currency": "usd", "price": 0.5, "interval": "month" }
+    ]
+  },
+  "components": [
+    { "_id": "*", "type": "challenge" },
+    { "_id": "welcome_widget", "type": "widget_v3" },
+    { "_id": "engagement_trigger", "type": "trigger" }
+  ]
+}
+```
+
+Compra + instalação:
+
+```http
+GET /v3/package/checkout?pack=<packId>&price=<stripePlanId>   # cria sessão Stripe
+# ... pagamento ... redireciona com session_id
+GET /v3/package/install/<packId>?session=<stripeSessionId>     # instala + registra subscription
+```
+
+### Anti-pattern — o que NÃO fazer
+
+```json
+// ❌ NÃO confie em `password`/`visibility`/`status` como segurança
+{
+  "title": "Pacote Confidencial",
+  "visibility": "private",
+  "status": "waiting",
+  "password": "ignorado-pelo-servidor",
+  "components": [ { "_id": "config_secreta", "type": "trigger" } ]
+}
+```
+Por quê: o servidor **não** lê `visibility`/`status`/`password` na leitura. Qualquer gamificação autenticada lê este pacote via `/v3/package/marketplace/{id}` ou pelo `aggregate`, incluindo o `content` completo do componente `trigger` (que pode conter código/segredos) e o próprio hash de senha. Não publique conteúdo sensível em pacotes.
+
+Outros anti-patterns:
+- Empacotar componentes cujo `_id` colide com config crítica de quem instala → sobrescrita silenciosa na instalação e remoção na desinstalação.
+- Esperar moderação automática antes de o pacote ficar visível → não existe; a moderação é do frontend.
+- Publicar pacote pesado com vários `"*"` → cada `"*"` copia até 1000 docs e infla `components` (e o documento `package`).
+
+---
+
+## Checklist de Configuração
 
-- [ ] Componente é importado com sucesso
-- [ ] Configurações importadas estão corretas
-- [ ] Componente funciona na gamificação atual
+- [ ] `title` e `description` preenchidos (não validados server-side, mas exigidos pela UI).
+- [ ] Cada `component` tem `_id` e `type` válidos; `type` == nome real da coleção MongoDB.
+- [ ] Os documentos referenciados pelos componentes **existem** no momento da publicação (senão são descartados silenciosamente).
+- [ ] Para publicar via `/v3/package`: não confie no `apikey` enviado — ele será forçado para a gamificação autenticada.
+- [ ] Para pacote pago: `price_type == "checkout"`, `checkout._id` aponta para um `Checkout` válido, e há ao menos um `CheckoutPricing` com `model`/`currency`/`price`.
+- [ ] Para pacote `managed`: ciente de que republicar reinstala em todas as instalações ativas (síncrono).
+- [ ] Para componentes `trigger`: ciente de que a instalação registra/executa o trigger na gamificação de destino.
+- [ ] **Armadilha**: `_id` de componente coincidente sobrescreve/remove config local de quem instala.
+- [ ] **Armadilha**: `visibility`/`status`/`password` NÃO protegem o pacote — não coloque conteúdo sensível.
+- [ ] **Armadilha**: instalar exige que o pacote seja de **outra** gamificação (não a criadora).
+- [ ] Após instalar pacote pago, chame `install?session=<id>` para registrar a assinatura no log.