funifier-mcp 0.2.25 → 0.2.27

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

@@ -1,42 +1,628 @@
-# Widget (Widget)
+# `widget`
 
 **Acesso Studio:** `/studio/widget`
 **API Endpoint:** `/v3/widget`
+**Coleção MongoDB:** `widget_v3` (instâncias e catálogo) + `widget_log` (registro de consumo)
 
-## O que é
+> Documentação de engenharia reversa baseada no código real de `funifier-service`. O módulo `/v3/widget` é implementado por `Widget_V3` / `WidgetManagerV3` / `WidgetManagerSystem` (pacote `com.funifier.engine.octalysis`). **Não confundir** com o subsistema legado de widgets (`engine.widget.Widget`, `engine.integration.html.WidgetHtml`, `engine.studio.widget`) que serve os endpoints legados de injeção HTML inline — esse é outro módulo, descrito na seção 7.
 
-Criação de componentes visuais para exibir técnicas de jogo. Permite criar e configurar widgets gráficos — como rankings, listas de desafios, status do jogador, lojas virtuais — para apresentar informações gamificadas de maneira clara e motivadora. Podem ser integrados em sistemas web existentes (intranets, CRMs, LMS).
+---
 
-## Quando usar
+## 1. Visão Geral
 
-- Para exibir rankings em intranets
-- Para mostrar lista de desafios ativos
-- Para exibir status do jogador
-- Para integrar gamificação visualmente em sistemas existentes
+O módulo `widget` armazena **componentes de UI da gamificação**: blocos auto-contidos de HTML + CSS + JavaScript, com internacionalização (`i18n`) e recursos externos (`resources`), que um frontend consome para renderizar uma técnica de jogo (ranking, status do jogador, lista de desafios, loja, etc.).
 
-## Checklist de Configuração no Studio
+Cada documento `Widget_V3` carrega quatro tipos de informação:
 
-- [ ] Definir tipo do widget
-- [ ] Configurar dados a exibir
-- [ ] Personalizar estilo visual
-- [ ] Gerar código de embed
+- **Apresentação:** `html`, `css`, `script`, `resources` (URIs de JS/CSS externos), `i18n`.
+- **Metadados de catálogo:** `title`, `description`, `image` (ícone), `screenshot`.
+- **Vínculo de gamificação:** `techniques` (códigos de técnica de jogo "GT…") e `references` (ligações a outros componentes da estratégia).
+- **Estilo de grafo:** `style` (`background`, `visible`) — usado na visualização de relacionamento de componentes.
 
-## API Endpoints
+Papel arquitetural:
 
-### Listar Widgets
-**Método:** GET
-**Endpoint:** `/v3/widget`
+- Existe em **dois escopos**, ambos na coleção `widget_v3`, mas em bancos diferentes:
+  - **Catálogo do sistema** (global, singleton `SystemFactory` → `WidgetManagerSystem`): widgets prontos, instaláveis por qualquer gamificação.
+  - **Instâncias do tenant** (por `api_key`, `ManagerFactory` → `WidgetManagerV3`): a cópia editável de cada gamificação.
+  - `POST /v3/widget/install/{id}` copia um widget do catálogo do sistema para o tenant.
+- É um **repositório de conteúdo passivo**: o save é um upsert de substituição total por `_id`; o módulo **não dispara triggers, webhooks ou notificações** em nenhuma operação de escrita ou exclusão.
+- Registra consumo em `widget_log` (`GET /v3/widget/{id}?player=…`), agregado por jogador + widget + **dia**.
 
-### Criar Widget
-**Método:** POST
-**Endpoint:** `/v3/widget`
+Relação com outros módulos:
 
-### Deletar Widget
-**Método:** DELETE
-**Endpoint:** `/v3/widget/:id`
+- `inline` (`InlineRest`) — serve `widget.script` e `widget.css` como arquivos `.js`/`.css` para embute em páginas externas.
+- `game-technique` (`GameTechniqueManager`) — lê `widget_log` + `widget_v3.techniques` para calcular o **uso de cada técnica de jogo**; e usa `widget.style` / `widget.references` para montar o grafo de relacionamento de componentes (`findComponentsRelationship`).
+- `analytics` / `statistic` — `widget_log` entra na contagem de **jogadores ativos** (`StatisticManager`) e na contagem bruta de eventos (`AnalyticsRest`).
+- `packages` (`PackageManager`) — widgets são exportados/importados como componentes (`type = widget_v3`).
+- `player` (`PlayerDaoMongo`) — exclusão de um jogador remove seus registros em `widget_log`.
 
-## Validações e Testes
+---
 
-- [ ] Widget aparece na lista
-- [ ] Widget exibe dados corretos
-- [ ] Widget funciona integrado em página externa
+## 2. Arquitetura e Fluxos
+
+### 2.1 Classes envolvidas
+
+| Classe | Papel |
+|---|---|
+| `com.funifier.engine.octalysis.Widget_V3` | Entidade/POJO — documento raiz da coleção `widget_v3` |
+| `com.funifier.engine.octalysis.WidgetManagerV3` | Manager do **tenant**: insert, find, findAll, delete, findAllAggregate, **saveLog** |
+| `com.funifier.engine.octalysis.WidgetManagerSystem` | Manager do **sistema** (catálogo global): insert, find, findAll, delete (sem saveLog, sem aggregate) |
+| `com.funifier.engine.octalysis.WidgetLog` | Entidade de consumo — coleção `widget_log` |
+| `com.funifier.rest.v3.rest.WidgetRest` | Controller REST v3 (`/v3/widget`) |
+| `com.funifier.rest.v3.rest.InlineRest` | Serve `script`/`css` do widget como arquivos estáticos (`/v3/inline/widget-…`) |
+| `com.funifier.engine.integration.trigger.ObjectStyle` | Sub-objeto `style` (`background`, `visible`) |
+| `com.funifier.engine.integration.trigger.Reference` | Sub-objeto de `references` (ligação a outro componente) |
+
+Não há `Repository`/`Dao` dedicado para `Widget_V3` — a manipulação MongoDB é feita diretamente via `Jongo` dentro dos managers. (As classes `WidgetDaoMongo` que existem no projeto pertencem ao subsistema **legado**, não ao `/v3/widget` — ver seção 7.)
+
+### 2.2 Pipeline de escrita — `WidgetManagerV3.insert(Widget_V3)`
+
+Caminho de `POST /v3/widget`, `POST /v3/widget/install/{id}`, import de package e `POST /v3/widget/system` (via `WidgetManagerSystem.insert`, que é idêntico):
+
+```
+[1] Se widget != null:
+      [1.1] se widget.id == null      → widget.id = Guid.newShortGuid()   (SHORT GUID, não ObjectId)
+      [1.2] se widget.created == null → widget.created = new Date()
+      [1.3] widget.updated = new Date()                                   (SEMPRE sobrescreve)
+[2] Resolve a coleção Entity.WIDGET_V3.collection ("widget_v3")
+[3] Normalização de i18n: se widget.i18n.size() > 0 → recria o mapa com TODAS as chaves de locale em minúsculas
+[4] c.save(widget)   → upsert por _id (SUBSTITUIÇÃO TOTAL do documento)
+```
+
+**Comportamento real / armadilhas:**
+
+- O passo `[3]` lê `widget.i18n.size()` **fora** do guard `if (widget != null)`. Se `widget` for `null` (corpo vazio) ou se o cliente enviar `"i18n": null` explicitamente, ocorre **`NullPointerException` → HTTP 500**. Ver seção 9.
+- `c.save()` é **substituição total**: campos omitidos no corpo passam a ter o valor default da classe (não há merge/patch). Não existe `PUT`.
+- Nenhuma trigger, webhook ou notificação é disparada. A escrita é silenciosa.
+- `created` é preservado apenas se já vier preenchido no corpo; como o save é full-replace, um update que **não** reenvie `created` recebe `new Date()` (perde a data de criação original).
+
+```mermaid
+flowchart LR
+    A[POST /v3/widget] --> B{widget != null?}
+    B -- não --> N[i18n.size NPE → 500]
+    B -- sim --> C{id == null?}
+    C -- sim --> D[id = ShortGuid]
+    C -- não --> E[mantém id]
+    D --> F{created == null?}
+    E --> F
+    F -- sim --> G[created = now]
+    F -- não --> H[mantém created]
+    G --> I[updated = now]
+    H --> I
+    I --> J{i18n vazio?}
+    J -- não --> K[chaves de locale → minúsculas]
+    J -- sim --> L[save upsert por _id]
+    K --> L
+```
+
+### 2.3 Leitura + registro de consumo — `GET /v3/widget/{id}` e `saveLog`
+
+```
+[1] Resolve player: se ausente, em branco ou "me" → authBean.getPlayerFromTokenIfExist()
+[2] manager.find(id)                              → Widget_V3 (ou null se não existir)
+[3] Se player != null E widget != null            → manager.saveLog(id, player)
+[4] Retorna o widget com campos null removidos (JsonUtil.toJsonRemoveNullFields)
+```
+
+`WidgetManagerV3.saveLog(widget, player)` mantém um **contador diário idempotente** por par jogador+widget:
+
+```
+time = trunca(hoje, "yyyy-MM-dd")     // zera hora/min/seg via reparse do formato de data
+current = widget_log.findOne({ player, widget, time })
+se current existe:
+    log._id   = current._id
+    log.total = current.total + 1      // incrementa
+senão:
+    log._id   = Guid.newShortGuid()
+    log.total = 1                       // primeiro acesso do dia
+widget_log.save(log)                    // upsert por _id
+```
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant WidgetRest
+    participant WidgetManagerV3
+    participant widget_v3 as widget_v3 (Mongo)
+    participant widget_log as widget_log (Mongo)
+
+    Client->>WidgetRest: GET /v3/widget/{id}?player=me
+    WidgetRest->>WidgetRest: resolve player (token se "me"/vazio)
+    WidgetRest->>WidgetManagerV3: find(id)
+    WidgetManagerV3->>widget_v3: findOne({_id:#})
+    widget_v3-->>WidgetManagerV3: Widget_V3 | null
+    alt player != null E widget != null
+        WidgetRest->>WidgetManagerV3: saveLog(id, player)
+        WidgetManagerV3->>widget_log: findOne({player, widget, time=hoje})
+        widget_log-->>WidgetManagerV3: doc | null
+        WidgetManagerV3->>widget_log: save (total+1 ou total=1)
+    end
+    WidgetRest-->>Client: 200 + widget (campos null removidos)
+```
+
+### 2.4 Instalação — `POST /v3/widget/install/{id}`
+
+```
+[1] widget = SystemFactory.getInstance().getWidgetV3Manager().find(id)   // catálogo do sistema
+[2] manager.getWidgetV3Manager().insert(widget)                          // tenant atual
+```
+
+- O widget é inserido no tenant **com o mesmo `_id`** do widget de sistema (o `insert` não regenera `id` porque já está preenchido).
+- Como `insert` faz upsert por `_id`, instalar de novo **sobrescreve** silenciosamente a instância local — incluindo edições que o tenant tenha feito.
+- Se `id` **não existe** no catálogo do sistema → `find` retorna `null` → `insert(null)` → **NPE (500)** no passo `[3]` da seção 2.2.
+
+### 2.5 Listagem agregada — `WidgetManagerV3.findAllAggregate(aggregations, range)`
+
+```
+StringBuilder query = new StringBuilder();   // NUNCA recebe append em nenhum ponto
+...
+se query.length() > 0:          → RAMO MORTO (sempre falso)
+senão se aggregations não vazio: → aggregate(aggregations[0]).and(aggregations[1..n])
+senão:                          → aggregate("{$match:{ }}")    // coleção inteira
+return PaginationUtil.getPageResultThrowsException(a, range, 0, 100)
+```
+
+- O primeiro ramo (`query.toString().length() > 0`) é **código morto** — `query` jamais é preenchido.
+- Sem `aggregations` no corpo → roda `{$match:{}}`, ou seja, **todos os widgets do tenant** paginados pelo header `Range` (default `items=0-100`).
+- Os estágios do corpo são repassados **crus** ao MongoDB (mesma superfície de injeção de pipeline da seção 8).
+
+### 2.6 Consumo de `widget_log` por outros módulos
+
+| Consumidor | O que faz com `widget_log` |
+|---|---|
+| `GameTechniqueManager` (linhas ~822-864) | Agrega `widget_log` por `widget`, faz `$lookup` em `widget_v3` para obter `techniques`, e soma o total por **técnica de jogo** → relatório de uso de técnicas (opcionalmente filtrado por `player`). É a realização concreta do comentário "calcular as motivações que mais influenciam este jogador" do `WidgetRest.find`. |
+| `StatisticManager` (linha ~233) | `$lookup` de `widget_log` unido a `action_log` para o conjunto de **jogadores ativos** (`$setUnion`). |
+| `AnalyticsRest` (linha ~256) | `count()` bruto de documentos em `widget_log`. |
+| `PlayerDaoMongo` (linha ~106) | Ao excluir um jogador, remove `widget_log.remove({player:#})`. |
+| `ConnectionPool` (linha ~149) | Cria índices em `widget_log`: `player`, `widget`, `time`. |
+
+> O contador `widget_log` **é lido** (não é dado órfão). Porém, nenhum desses consumidores produz uma "lista de motivações por jogador" pronta — o que existe é a agregação de uso por técnica (`GameTechniqueManager`) e a contribuição para jogadores ativos.
+
+### 2.7 Conteúdo servido inline — `InlineRest`
+
+| Endpoint | Origem |
+|---|---|
+| `GET /v3/inline/widget-{apikey}-{widget}.js` | `Widget_V3.script` (string crua, `Content-Type: text/javascript`) |
+| `GET /v3/inline/widget-{apikey}-{widget}.css` | `Widget_V3.css` (string crua, `Content-Type: text/css`) |
+
+Ambos retornam corpo vazio se o widget não existir ou se o campo estiver vazio/nulo. **Não há autenticação por token** nesses endpoints — o `api_key` vai no path (ver seção 8).
+
+---
+
+## 3. Estrutura dos Objetos
+
+### 3.1 `Widget_V3` — documento raiz (coleção `widget_v3`)
+
+`@JsonIgnoreProperties(ignoreUnknown=true)` — campos não mapeados enviados no corpo são **descartados silenciosamente**.
+
+| Campo | Tipo | Padrão | Obrigatório | Descrição |
+|---|---|---|---|---|
+| `_id` | String | `Guid.newShortGuid()` se ausente | Não (auto) | SHORT GUID interno do Funifier. **Não** é ObjectId do Mongo. Pode ser definido pelo cliente |
+| `title` | String | — | Comentado como "required", **não validado** | Título do widget |
+| `image` | String | — | Não | URL do ícone |
+| `screenshot` | String | — | Não | URL da captura de tela |
+| `description` | String | — | Comentado como "required", **não validado** | Descrição |
+| `extra` | Map<String,Object> | `{}` | Não | Atributos arbitrários. Persistido, mas **não consumido** por nenhuma regra do core (passthrough). Substitui o antigo `tags` (ver abaixo) |
+| `techniques` | List<String> | `[]` | Não | Códigos de técnica de jogo ("GT…") associados. Lista livre, **sem validação** (ver 3.5) |
+| `style` | `ObjectStyle` | `null` | Não | Estilo do nó no grafo de componentes (ver 3.3) |
+| `references` | List<`Reference`> | `null` | Não | Ligações a outros componentes da gamificação (ver 3.4) |
+| `script` | String | — | Não | JavaScript do widget. Servido cru via `/v3/inline/…js` |
+| `html` | String | — | Não | HTML do widget |
+| `css` | String | — | Não | CSS do widget. Servido cru via `/v3/inline/…css` |
+| `resources` | List<String> | `[]` | Não | URIs externos de JS/CSS (ex.: `https://code.angularjs.org/angular-1.0.1.js`) |
+| `i18n` | Map<String, Map<String,String>> | `{}` | Não | Internacionalização. **Chaves de locale são forçadas a minúsculas no save.** Enviar `null` causa NPE (seção 2.2) |
+| `created` | Date | `new Date()` se ausente no insert | Não (auto) | Data de criação. Serializada como epoch ms |
+| `updated` | Date | `new Date()` **sempre** no insert | Não (auto) | Última atualização. Sempre sobrescrita no save |
+
+#### Campos computados / não persistidos
+
+Nenhum. Todos os campos da classe são persistidos.
+
+#### Campos removidos / sanitizados silenciosamente no save
+
+- **Chaves de `i18n`** → convertidas para minúsculas (`pt_BR` vira `pt_br`). O cliente não é avisado.
+- **`updated`** → sempre substituído por `new Date()`, ignorando qualquer valor enviado.
+- Campos fora do schema → descartados por `@JsonIgnoreProperties(ignoreUnknown=true)`.
+
+#### Campo legado / deprecated
+
+```java
+/** Tags related to this widget */
+//public List<String> tags = new ArrayList<>();
+public Map<String, Object> extra = new HashMap<>();
+```
+
+O campo **`tags`** está **comentado** na entidade (linha 34) e foi substituído por `extra`. Enviar `"tags": [...]` no corpo é aceito pela requisição mas **silenciosamente descartado** (não mapeado → `ignoreUnknown`). Documentos antigos com `tags` no Mongo mantêm o campo, mas o runtime não o lê.
+
+### 3.2 `WidgetLog` — registro de consumo (coleção `widget_log`)
+
+`@JsonIgnoreProperties(ignoreUnknown=true)`.
+
+| Campo | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `_id` | String | `Guid.newShortGuid()` no primeiro acesso do dia | Identificador |
+| `widget` | String | — | Id do widget consumido |
+| `player` | String | — | Jogador que consumiu |
+| `total` | double | 1 no primeiro acesso, incrementa +1 | Quantidade de acessos **no dia** |
+| `time` | Date | hoje truncado a `yyyy-MM-dd` | Bucket diário (hora zerada) |
+
+Um documento por (`player`, `widget`, `dia`). Não há histórico por requisição — apenas o agregado diário. Índices: `player`, `widget`, `time`.
+
+### 3.3 `ObjectStyle` — sub-objeto `style`
+
+| Campo | Tipo | Descrição |
+|---|---|---|
+| `background` | String | Cor de fundo do nó no grafo de componentes |
+| `visible` | Boolean | Se o nó é exibido no grafo |
+
+Usado exclusivamente por `GameTechniqueManager.findComponentsRelationship` para desenhar o widget no grafo de relacionamento. Não afeta a renderização do widget em si.
+
+### 3.4 `Reference` — sub-objeto de `references`
+
+| Campo | Tipo | Descrição |
+|---|---|---|
+| `way` | String | `"from"` (`WAY_FROM`) ou `"to"` (`WAY_TO`) — direção da ligação |
+| `linkLabel` | String | Texto sobre a seta de conexão (vazio se ausente) |
+| `_id` | String | Id do componente referenciado |
+| `type` | String | Tipo/coleção do componente referenciado (ex.: `point_category`) |
+| `title` | String | Título do componente referenciado |
+
+No grafo: `way=from` → seta do componente **para** o widget (consumo); `way=to` → seta do widget **para** o componente (produção).
+
+### 3.5 Técnicas de jogo (`techniques`)
+
+`techniques` é uma `List<String>` livre de códigos "GT…". **Não há validação** contra um catálogo — qualquer string é aceita e persistida. Os códigos canônicos vivem no módulo `game-technique` (`com.funifier.engine.system.technique.GameTechnique`), não no widget.
+
+Códigos observados no código (`GameTechniqueManager`, atribuídos a outros componentes; servem de referência para `techniques`):
+
+| Código | Significado operacional |
+|---|---|
+| `GT01` | Pontos (point_category) |
+| `GT03` | Leaderboard |
+| `GT05` | Blank fills (question) |
+| `GT08` | Virtual good (catalog_item) |
+| `GT13` | Widget (exemplo do apidoc de `WidgetRest`) |
+| `GT26` | Elitism (competition) |
+| `GT35` | Challenge |
+| `GT53` | Last mile |
+| `GT74` | Lottery |
+| `GT85` | Level |
+
+> O `$lookup` de `widget_log` → `widget_v3.techniques` (seção 2.6) só contabiliza uso de técnica para widgets cujo `techniques` esteja preenchido. Widget sem `techniques` não aparece no relatório de uso de técnicas.
+
+---
+
+## 4. Endpoints
+
+Todos sob `@Path("v3/widget")`, `Produces: application/json; charset=UTF-8`. Autenticação: **Bearer token** (OAuth 2.0 `client_credentials`), exceto os endpoints de `InlineRest` (path com `api_key`).
+
+### 4.1 `GET /v3/widget/{id}`
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Buscar um widget e **registrar consumo** |
+| Autenticação | Bearer token |
+| Patch ou full | Leitura |
+
+**Path / Query params:**
+
+| Param | Tipo | Descrição |
+|---|---|---|
+| `id` | path | Id do widget |
+| `player` | query | Jogador que consumiu. `me`, vazio ou ausente → resolvido pelo token. Se resolver para não-nulo, dispara `saveLog` |
+
+**Comportamento real:** retorna o widget com campos `null` removidos. Se o id não existir, retorna `200` com corpo `null` (não 404). `saveLog` só ocorre se `player` e widget forem não-nulos.
+
+### 4.2 `GET /v3/widget`
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Listar **todos** os widgets do tenant |
+| Autenticação | Bearer token |
+
+Sem paginação e sem filtros — `findAll()` materializa a coleção inteira em memória (`IteratorUtils.toList`). Campos `null` removidos na resposta.
+
+### 4.3 `POST /v3/widget/aggregate`
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Aggregation pipeline arbitrário sobre `widget_v3` |
+| Autenticação | Bearer token |
+| Body | `List<Object>` — estágios do pipeline |
+| Paginação | Header `Range` (default `items=0-100`, máx. 100) |
+
+Corpo vazio → `{$match:{}}` (coleção inteira). Ver ramo morto na seção 2.5 e injeção na seção 8.
+
+### 4.4 `POST /v3/widget`
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Criar/substituir um widget do tenant |
+| Autenticação | Bearer token |
+| Patch ou full | **Full replace** (`save` upsert por `_id`) |
+
+**Comportamento real:** gera `_id` se ausente; define `created`/`updated`; força chaves de `i18n` a minúsculas; **NPE 500 se o corpo for vazio ou `i18n: null`**; **não** dispara triggers/webhooks; **não** valida `title`/`description`. Retorna `201 Created` com o widget serializado.
+
+### 4.5 `POST /v3/widget/install/{id}`
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Copiar um widget do **catálogo do sistema** para o tenant |
+| Autenticação | Bearer token |
+
+Reusa o `_id` de origem → **sobrescreve** instância local de mesmo id. Id inexistente no sistema → **NPE 500**. Retorna `201` com o widget instalado.
+
+### 4.6 `DELETE /v3/widget/{id}`
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Remover um widget do tenant |
+| Autenticação | Bearer token |
+
+`remove({_id:#})`. Retorna `200` **sempre**, inclusive quando o id não existe (cliente não distingue "removi" de "não havia nada"). Não remove `widget_log` associado nem dispara triggers.
+
+### 4.7 Endpoints de sistema (catálogo global)
+
+| Método | Path | Comportamento |
+|---|---|---|
+| `GET` | `/v3/widget/system/{id}` | Busca no catálogo do sistema |
+| `GET` | `/v3/widget/system` | Lista todo o catálogo do sistema |
+| `POST` | `/v3/widget/system` | Cria/substitui no catálogo do sistema |
+| `DELETE` | `/v3/widget/system/{id}` | Remove do catálogo do sistema |
+
+Operam via `SystemFactory.getInstance().getWidgetV3Manager()` (`WidgetManagerSystem`) → banco **global**, compartilhado por todos os tenants. **Só exigem autenticação (Bearer), sem guarda de papel/permissão** — ver seção 8.
+
+### 4.8 Endpoints inline (`InlineRest`)
+
+| Método | Path | Produz |
+|---|---|---|
+| `GET` | `/v3/inline/widget-{apikey}-{widget}.js` | `text/javascript` (campo `script`) |
+| `GET` | `/v3/inline/widget-{apikey}-{widget}.css` | `text/css` (campo `css`) |
+
+Sem token; `api_key` no path. Corpo vazio se widget/campo ausente.
+
+### Exemplo de request/response
+
+```
+POST /v3/widget
+Authorization: Bearer eyJhbGciOi...
+Content-Type: application/json
+{
+  "_id": "MY",
+  "title": "My Widget",
+  "description": "Display my widget",
+  "techniques": ["GT13"],
+  "html": "<div>My Widget</div>",
+  "css": "",
+  "script": "",
+  "resources": [],
+  "i18n": {}
+}
+```
+
+```json
+HTTP/1.1 201 Created
+{
+  "_id": "MY",
+  "title": "My Widget",
+  "description": "Display my widget",
+  "techniques": ["GT13"],
+  "html": "<div>My Widget</div>",
+  "resources": [],
+  "i18n": {},
+  "extra": {},
+  "created": 1685011053000,
+  "updated": 1685011053000
+}
+```
+
+---
+
+## 5. Regras de Negócio
+
+Regras presentes no código mas **ausentes do schema**:
+
+### 5.1 Multi-tenant por conexão, não por campo
+
+Não há `apiKey` no documento. O isolamento é **inteiramente** dado pela conexão Jongo (`manager.getJongoConnection()`). Tenant ↔ banco. O catálogo do **sistema** é um banco à parte (singleton `SystemFactory`), comum a todos.
+
+### 5.2 Save é substituição total (não há PUT/patch)
+
+Toda escrita é `c.save()` (upsert por `_id`). Atualizar = reenviar o documento inteiro. Campos omitidos voltam ao default — inclusive `created`, que é regravado com a data atual quando não reenviado.
+
+### 5.3 Sem validação de campos "obrigatórios"
+
+`title` e `description` têm comentário "(required)" no código, mas **não há validação**. É possível criar um widget vazio (desde que o corpo não seja `null` e `i18n` não seja `null`).
+
+### 5.4 Normalização de locale
+
+Chaves de `i18n` são forçadas a minúsculas no save. `pt_BR` e `pt_br` colidem no mesmo bucket.
+
+### 5.5 Contador de consumo é diário e idempotente
+
+`saveLog` não cria um registro por acesso — incrementa o `total` do bucket diário (`yyyy-MM-dd`) do par (player, widget). Acessos no mesmo dia somam no mesmo documento.
+
+### 5.6 Instalação reusa o id de origem
+
+`install` mantém o `_id` do widget de sistema, então reinstalar **sobrescreve** a instância editada do tenant.
+
+### 5.7 Nenhum efeito colateral de gamificação na escrita
+
+Criar/editar/excluir widget **não** dispara triggers (`before_create`/`after_create`/`before_save`/`after_save`), webhooks nem notificações — diferentemente de `achievement`/`action`. Widget é conteúdo passivo.
+
+---
+
+## 6. Comportamentos Automáticos
+
+| Comportamento | Trigger | Impacto | Persistência |
+|---|---|---|---|
+| Atribuição de `_id` (ShortGuid) | `insert` se `_id` é null | Cria id curto interno | Sim |
+| `created = new Date()` | `insert` se `created` é null | Data de criação automática | Sim |
+| `updated = new Date()` | `insert` (sempre) | Sobrescreve qualquer `updated` enviado | Sim |
+| Locale → minúsculas | `insert` se `i18n` não vazio | Reescreve chaves de `i18n` | Sim |
+| Incremento de `widget_log` | `GET /v3/widget/{id}` com player resolvido | Cria/incrementa bucket diário | Sim |
+| Sobrescrita na instalação | `POST /install/{id}` | Substitui instância de mesmo id | Sim |
+| Criação de índices `widget_log` | Bootstrap (`ConnectionPool`) | Índices em player/widget/time | Sim |
+| Exclusão de `widget_log` ao remover player | `PlayerDaoMongo` ao excluir jogador | Limpa consumo do jogador | Sim |
+
+---
+
+## 7. Suportado vs NÃO Suportado
+
+### ✅ Suportado
+
+- CRUD por tenant (`GET /{id}`, `GET`, `POST`, `DELETE /{id}`).
+- Catálogo de sistema (`/v3/widget/system…`) e instalação (`/install/{id}`).
+- Aggregation pipeline arbitrário (`POST /aggregate`) com paginação por `Range`.
+- Registro de consumo diário em `widget_log` e seu uso em uso-de-técnica e jogadores-ativos.
+- Conteúdo `script`/`css` servido inline (`InlineRest`).
+- `i18n`, `resources`, `techniques`, `style`, `references`.
+- Export/import via `packages`.
+
+### ❌ NÃO Suportado
+
+- **Atualização parcial (`PUT`/patch)** — só full replace via `POST`.
+- **Validação de `title`/`description`** — comentados como required, nunca validados.
+- **Triggers/webhooks/notificações** no ciclo de vida do widget — nenhum é disparado.
+- **Guarda de papel nos endpoints de sistema** — qualquer token válido escreve/remove no catálogo global (seção 8).
+- **Campo `tags`** — comentado/removido; enviado é descartado. Use `extra`.
+- **Uso do `extra` pelo core** — é persistido, mas nenhuma regra o lê (passthrough puro).
+- **404 em recurso inexistente** — `GET` retorna `200` com `null`; `DELETE` retorna `200` sempre.
+- **Filtro/paginação no `GET /v3/widget`** — devolve a coleção inteira em memória.
+- **Corpo vazio / `i18n: null`** — provoca `NullPointerException` (500), não erro de validação.
+- **Histórico de consumo por requisição** — `widget_log` agrega por dia; não há granularidade por acesso.
+
+#### Subsistema legado de widgets (não é o `/v3/widget`)
+
+Existem três artefatos com "Widget" no nome que **não** pertencem a este módulo e atendem os endpoints legados `/2.0.0` de injeção HTML inline:
+
+- `com.funifier.engine.widget.Widget` — POJO com `category`/`path`/`image`/`active` (catálogo legado de widgets web/mobile). Gerido por `engine.studio.widget.WidgetManager` (sistema) via `SystemFactory.getWidgetManager()`. Usado por `MobileRest`, `StudioRest` e `InlineRest` legados.
+- `com.funifier.engine.integration.html.WidgetHtml` (implementa `Config`) — vínculo de injeção HTML (`selector`/`page`/`bind`) em páginas externas. Gerido por `engine.widget.WidgetManager` (tenant) via `ManagerFactory.getWidgetManager()`.
+- `WidgetDaoMongo` (em `engine.widget` e `engine.studio.widget`) — DAOs desse subsistema legado.
+
+Esses componentes são independentes de `Widget_V3` e da coleção `widget_v3`. Não são manipulados por `/v3/widget`.
+
+---
+
+## 8. Segurança e Permissões
+
+- **Autenticação:** Bearer token (OAuth 2.0 `client_credentials`) em todos os endpoints de `WidgetRest`. `WidgetRest` **não** declara `@RolesAllowed` nem chama `authBean.checkSystemPermission(...)`.
+- **Isolamento por tenant:** garantido pela conexão Jongo por `api_key`. Sem campo `apiKey` no documento.
+- **Catálogo de sistema sem guarda de papel (achado real):** `POST /v3/widget/system` e `DELETE /v3/widget/system/{id}` escrevem no banco **global** (`SystemFactory`) exigindo apenas um token válido — **sem verificação de admin/permissão**. Qualquer cliente autenticado pode criar/sobrescrever/remover widgets do catálogo compartilhado por todos os tenants.
+- **Injeção de pipeline de aggregation:** `POST /v3/widget/aggregate` repassa os estágios do corpo crus ao MongoDB. Restrito ao banco do tenant, mas permite consultas arbitrárias (inclusive `$lookup` em outras coleções do mesmo tenant).
+- **XSS armazenado / execução de JS arbitrário (achado real):** `script`, `html` e `css` são armazenados **sem sanitização** e servidos **verbatim** — `script` como `text/javascript` e `css` como `text/css` via `InlineRest`. Qualquer frontend que injete esse conteúdo numa página executa código sob controle de quem criou o widget. Os endpoints inline (`/v3/inline/widget-{apikey}-{widget}.js|.css`) **não exigem token** (o `api_key` vai no path), expondo o `script`/`css` publicamente a quem conhecer a URL.
+- **Robustez:** corpo nulo ou `i18n: null` derruba o handler com NPE (500) em vez de retornar erro de validação (negação de serviço trivial por entrada malformada).
+
+---
+
+## 9. Observabilidade e Troubleshooting
+
+### Diagnóstico
+
+```
+GET /v3/widget                 # lista todos os widgets do tenant
+GET /v3/widget/{id}            # confere um widget (cuidado: registra consumo se houver player)
+GET /v3/widget/system          # confere o catálogo de sistema
+```
+
+### Queries úteis (Mongo, banco do tenant)
+
+```js
+// Existe o widget?
+db.widget_v3.findOne({ _id: "MY" })
+
+// Consumo de um widget por dia
+db.widget_log.find({ widget: "MY" }).sort({ time: -1 })
+
+// Consumo de um jogador hoje
+db.widget_log.find({ player: "joao@empresa.com", time: ISODate("2026-05-20T00:00:00Z") })
+
+// Uso por técnica (o que GameTechniqueManager calcula)
+db.widget_log.aggregate([
+  { $group: { _id: "$widget", total: { $sum: "$total" } } },
+  { $lookup: { from: "widget_v3", localField: "_id", foreignField: "_id", as: "p" } },
+  { $unwind: "$p" }, { $unwind: "$p.techniques" },
+  { $group: { _id: "$p.techniques", total: { $sum: "$total" } } }
+])
+```
+
+### Erros comuns e causas
+
+| Sintoma | Causa provável |
+|---|---|
+| `500` ao criar widget | Corpo vazio/`null` ou `"i18n": null` → NPE em `insert` (seção 2.2) |
+| `500` ao instalar | `id` não existe no catálogo de sistema → `insert(null)` → NPE |
+| `GET` retorna `null` com `200` | Widget não existe — não há 404 |
+| `DELETE` "funciona" mas nada muda | `remove` retorna `200` mesmo sem documento |
+| Locale do `i18n` "sumiu" | Chave foi convertida para minúsculas no save |
+| `tags` não persistiu | Campo removido/legado — descartado por `ignoreUnknown`. Use `extra` |
+| Widget editado voltou ao padrão | Reinstalação (`/install/{id}`) sobrescreveu a instância |
+| `created` mudou após editar | Update full-replace sem reenviar `created` regrava a data |
+| Widget não aparece no relatório de técnicas | `techniques` vazio, ou nenhum acesso registrado em `widget_log` |
+
+---
+
+## 10. Exemplos Práticos
+
+### Mínimo funcional
+
+```json
+POST /v3/widget
+{
+  "title": "Ranking",
+  "html": "<div id='rk'></div>"
+}
+```
+
+Gera `_id` automático, `created`/`updated` automáticos. (Atenção: **não** envie corpo vazio nem `"i18n": null`.)
+
+### Avançado (todos os campos relevantes)
+
+```json
+POST /v3/widget
+{
+  "_id": "leaderboard_widget",
+  "title": "Leaderboard",
+  "description": "Top 10 jogadores",
+  "image": "https://cdn.exemplo.com/icon.png",
+  "screenshot": "https://cdn.exemplo.com/shot.png",
+  "techniques": ["GT03"],
+  "style": { "background": "#1e293b", "visible": true },
+  "references": [
+    { "way": "from", "_id": "lb_principal", "type": "leaderboard", "title": "Ranking Geral", "linkLabel": "exibe" }
+  ],
+  "resources": ["https://code.jquery.com/jquery-3.7.1.min.js"],
+  "script": "fetch('/v3/leaderboard/lb_principal/leader/aggregate').then(...)",
+  "css": "#rk{font-family:sans-serif}",
+  "html": "<div id='rk'></div>",
+  "i18n": { "pt_br": { "title": "Ranking" }, "en": { "title": "Leaderboard" } }
+}
+```
+
+### Anti-pattern (o que NÃO fazer)
+
+```json
+POST /v3/widget
+{
+  "title": "Quebrado",
+  "tags": ["ranking", "top"],   // ❌ descartado: 'tags' é legado, use 'extra'
+  "i18n": null                  // ❌ NPE 500: i18n nunca pode ser null
+}
+```
+
+- Esperar **patch**: reenviar só `{ "title": "Novo" }` num widget existente **apaga** os demais campos (full replace).
+- Confiar em `extra` como dado funcional: ele é persistido mas **nenhuma regra do core o lê**.
+- Usar `POST /v3/widget/system` como conveniência: escreve no catálogo **global** de todos os tenants, sem guarda de papel.
+
+---
+
+## Checklist de Configuração
+
+- [ ] Corpo do `POST` **nunca** vazio e `i18n` **nunca** `null` (evita NPE 500).
+- [ ] `title` e `description` preenchidos (o código não valida, mas a UI espera).
+- [ ] Locales de `i18n` já em minúsculas (serão convertidos de qualquer forma).
+- [ ] Para atualizar, reenviar o **documento inteiro** (não há patch); reenviar `created` para preservá-lo.
+- [ ] `techniques` preenchido com códigos GT se o widget deve aparecer no relatório de uso de técnicas.
+- [ ] Conteúdo de `script`/`html`/`css` é confiável — é servido verbatim e executável (XSS).
+- [ ] Escrita em `/v3/widget/system` é intencional (catálogo global, sem guarda de papel).
+- [ ] Reinstalar via `/install/{id}` ciente de que sobrescreve a instância local de mesmo id.

package/dist/cli/init.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/cli/init.ts"],"names":[],"mappings":"AAkJA,wBAA8B,IAAI,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA6CzF"}
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/cli/init.ts"],"names":[],"mappings":"AA2LA,wBAA8B,IAAI,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA8CzF"}