funifier-mcp 0.2.26 → 0.2.27

package/datasource-funifier-docs/knowledge/modules/studio-page.md

@@ -1,180 +1,506 @@
-# Studio Page (Página Customizada do Studio)
+# `studio-page`
 
 **Acesso Studio:** `/studio/page`
+**API Endpoint:** `/v3/database/studio_page` (CRUD genérico — **não há** endpoint dedicado `/v3/studio_page`)
+**Coleção MongoDB:** `studio_page`
 
-## O que é
+---
 
-Páginas customizadas dentro do Funifier Studio para atender necessidades específicas dos administradores. Permitem criar dashboards, CRUDs, gráficos, relatórios — tudo com AngularJS + Bootstrap.
+## 1. Visão Geral
 
-## Configuração
+O módulo `studio-page` representa **páginas customizadas** criadas dentro do Funifier Studio: blocos de `html` + `script` (JavaScript) servidos sob um `slug`, usados por administradores para montar dashboards, CRUDs, gráficos e relatórios próprios sobre os dados da gamificação.
 
-Cada página é um JSON com:
-- `_id` — Identificador único (auto-gerado se omitido)
-- `display` — `true` para aparecer no menu do Studio, `false` para páginas internas
-- `title` — Nome exibido no menu
-- `slug` — Caminho relativo (ex: `studio/custom/hello`). Suporta parâmetros: `studio/custom/car/form/:id`
-- `html` — Código HTML (usa Bootstrap CSS)
-- `script` — Código JavaScript (roda no contexto AngularJS)
+Papel arquitetural — três fatos centrais que governam todo o resto:
 
-## Contexto JavaScript
+1. **Não existe Resource/Service/Manager/Repository/DAO dedicado.** A persistência é feita inteiramente pelo CRUD **genérico** `DatabaseRest` (`com.funifier.rest.v3.rest.DatabaseRest`, `@Path("v3/database")`) sobre a coleção `studio_page`. Toda a semântica REST de `studio_page` é, portanto, a semântica genérica de `/v3/database/{collection}`.
+2. **O `DatabaseRest` opera sobre `HashMap`/`BasicDBObject`, nunca sobre a classe `StudioPage`.** A entidade `com.funifier.engine.studio.page.StudioPage` é apenas um **contrato de leitura** — ela só é desserializada num único ponto do servidor (`GameTechniqueManager.findComponentsRelationship`). Na escrita, a coleção aceita **qualquer campo** sem validação de schema.
+3. **O backend trata `html`, `script` e `slug` como strings opacas.** `funifier-service` não interpreta, valida ou renderiza nenhum desses campos. Toda a semântica de AngularJS, do objeto `Marketplace`, das diretivas (`<image-picker>`, etc.) e do roteamento por `slug` é responsabilidade do **frontend do Studio** — ver seção 2.5 e 7.
 
-Dentro do `script`, você tem acesso a:
-- `$scope` — Scope do AngularJS
-- `$http` — Para requisições HTTP
-- `$location` — Para navegação entre páginas (`$location.path("/studio/custom/...")`)
-- `$routeParams` — Para ler parâmetros do slug (ex: `$routeParams.id`)
-- `Marketplace` — Objeto utilitário (ver abaixo)
+Relação com outros módulos:
 
-### Marketplace API
+- **`database`** — único caminho de CRUD (`DatabaseRest`). Tudo que vale para `/v3/database/{collection}` vale aqui.
+- **`trigger`** — toda escrita em `studio_page` dispara o pipeline genérico de triggers (`before_create`/`after_create`/`before_update`/`after_update`/`before_delete`/`after_delete`).
+- **`audit`** — toda mutação é registrada pelo `AuditManager`.
+- **`technique` (mapa de estratégia)** — `GameTechniqueManager.findComponentsRelationship` (exposto em `GET /v3/technique/relationship`) lê todas as páginas como `StudioPage` e as transforma em nós/arestas do grafo de estratégia, usando `display`, `style`, `title`, `id` e `references`.
+- **`folder`** — o campo `folder` é uma referência organizacional consumida pelo módulo Folder; o código de `studio_page` não o processa.
+- **`ai`** — `AIRest.buildStudioPage` (`POST /v3/ai/build/studio_page`) gera `html`/`script`/`title`/`slug` via OpenAI, mas **não persiste** — apenas devolve o JSON gerado.
 
-| Método | Descrição | Exemplo de retorno |
-|--------|-----------|-------------------|
-| `Marketplace.auth.getService()` | URL da API Funifier | `https://service2.funifier.com` |
-| `Marketplace.auth.getAuthorization()` | Token de acesso do usuário logado no Studio | Bearer token |
-| `Marketplace.range.parse(content_range)` | Analisa header `content-range` para paginação | `{page, pages, count, ...}` |
-| `Marketplace.range.paginate(page, content_range)` | Gera header `Range` para ir a uma página | `items=0-100` |
+Problemas que resolve: permitir telas administrativas arbitrárias dentro do Studio sem alterar o produto, reutilizando o CRUD genérico de banco como mecanismo de armazenamento.
 
-## Diretivas Disponíveis
+---
 
-- `<image-picker>` — Seletor de imagem (URL, local, galeria). Atributos: `on-change`, `show-picker-url`, `show-picker-local`, `show-picker-gallery`, `upload-max-size`, `transform`
-- `<principal-picker>` — Seletor de jogadores/equipes. Atributos: `title`, `model`, `show-picker-player`, `black-list`, `max`
-- `<input-extra>` — Campos extras dinâmicos. Atributos: `title`, `show-inline`, `model`
+## 2. Arquitetura e Fluxos
 
-## Bibliotecas Disponíveis
+### 2.1 Classes envolvidas
 
-- **Highcharts** — Gráficos (pizza, barra, linhas, etc.)
-- **Bootstrap** — CSS framework (classes `btn`, `table`, `form-control`, etc.)
-- **Glyphicons** — Ícones via `glyphicon glyphicon-*`
-- Traduções: `{{'SAVE'|translate}}`, `{{'CANCEL'|translate}}`, `{{'BACK'|translate}}`, `{{'NEW'|translate}}`, `{{'SEARCH_FOR'|translate}}`
+| Classe | Papel |
+|---|---|
+| `com.funifier.engine.studio.page.StudioPage` | POJO/contrato de leitura — documento raiz. **Não** é usado na escrita |
+| `com.funifier.engine.util.Entity` | Registro `STUDIO_PAGE("studio_page", StudioPage.class)` (linha 240) — mapeia tipo → coleção/classe |
+| `com.funifier.rest.v3.rest.DatabaseRest` | Controller REST genérico (`/v3/database/{collection}`) que serve **toda** a CRUD de `studio_page` |
+| `com.funifier.engine.technique.GameTechniqueManager` | Único consumidor da classe `StudioPage` no servidor — monta o mapa de relacionamento (`findComponentsRelationship`) |
+| `com.funifier.rest.v3.rest.AIRest` | `buildStudioPage` — geração assistida por IA (`POST /v3/ai/build/studio_page`) |
+| `com.funifier.engine.integration.trigger.ObjectStyle` | Sub-objeto `style` (`background`, `visible`) — estilização de nó no mapa de estratégia |
+| `com.funifier.engine.integration.trigger.Reference` | Item de `references` — aresta no mapa de estratégia |
 
-## Exemplos
+**Não há `Manager`/`Service`/`Dao`/`Repository` dedicado a `studio_page`.** A manipulação do MongoDB é feita diretamente via `Jongo` dentro de `DatabaseRest`.
+
+### 2.2 Pipeline de escrita (POST / PUT) — `DatabaseRest.insert` / `DatabaseRest.update`
+
+Sequência real para `PUT /v3/database/studio_page` (`update`, linhas 290-388) e `POST` (`insert`, linhas 169-247):
+
+```
+[Auth]          → verifica authBean.getScope() contém SCOPE_DATABASE ("database")
+                  (sem scope → retorna 200 com corpo vazio, NÃO 403)
+[Guard]         → collection.trim().length() > 3  ("studio_page" = 11, passa)
+[_id]           → se "_id" ausente ou null → object.put("_id", Guid.newShortGuid())
+[Trigger BEFORE]→ triggerManager.execute(BEFORE_CREATE | BEFORE_UPDATE, "studio_page", player)
+[Crypt]         → se CryptObjectField configurado p/ studio_page → criptografa campos
+[Marshal]       → JacksonMapper.marshall(object) → BasicDBObject (modo BSON tipado)
+[Persist]       → POST: collection("studio_page").insert(o)
+                  PUT : collection("studio_page").save(o)   ← SUBSTITUI o documento inteiro (upsert por _id)
+[Trigger AFTER] → triggerManager.execute(AFTER_CREATE | AFTER_UPDATE, "studio_page", player)
+[Audit]         → auditManager.log("studio_page", EVENT_CREATE | EVENT_UPDATE, authBean, o)
+[Response]      → 201 CREATED. strict=true → BSON strict; senão → JSON sem campos null
+```
+
+Pontos não-triviais (todos confirmados no código):
+
+- **PUT é _full replace_, não _patch_.** `jongo.save(o)` substitui o documento inteiro. Campos omitidos no corpo **somem** do documento.
+- **PUT sem `_id` cria um documento novo.** Como `_id` é auto-gerado quando ausente, um `PUT` que pretendia atualizar mas esqueceu o `_id` resulta em **duplicata** com id aleatório — não em `404`.
+- **Sem `_id` no POST** → também é auto-gerado via `Guid.newShortGuid()` (SHORT GUID, não ObjectId do Mongo).
+- O fluxo é **síncrono** e **sem transação** entre persistência, triggers e auditoria.
+
+```mermaid
+sequenceDiagram
+    participant C as Cliente (Studio)
+    participant R as DatabaseRest
+    participant T as TriggerManager
+    participant M as MongoDB (Jongo)
+    participant A as AuditManager
+    C->>R: PUT /v3/database/studio_page {json}
+    R->>R: scope contém SCOPE_DATABASE? len(collection) > 3?
+    R->>R: _id ausente/null? → Guid.newShortGuid()
+    R->>T: execute(BEFORE_UPDATE, "studio_page", player)
+    R->>M: collection("studio_page").save(o)  // full replace / upsert
+    R->>T: execute(AFTER_UPDATE, "studio_page", player)
+    R->>A: log("studio_page", EVENT_UPDATE, authBean, o)
+    R-->>C: 201 Created {documento}
+```
+
+### 2.3 Pipeline de leitura
+
+- **`GET /v3/database/studio_page/{id}`** (`find`, linhas 59-118): `findOne("{_id:#}", id)`. **Quirk:** se `id == "me"`, o id é resolvido para o jogador do token (`authBean.getPlayerFromTokenIfExist()`) — comportamento herdado do CRUD genérico, sem sentido para páginas. `strict=true` → saída BSON strict (preserva `$date`, `$oid`); senão remove campos null.
+- **`GET /v3/database/studio_page?q=...`** (`findAll`, linhas 120-160): monta um pipeline `{$match:{ <q> }}`, pagina via header `Range` (padrão página de 100; `max_results` default 100) e devolve resultado paginado com header `Content-Range`.
+
+### 2.4 Participação no mapa de estratégia — `GameTechniqueManager.findComponentsRelationship`
+
+Exposto em **`GET /v3/technique/relationship`** (`GameTechniqueRest`, `@Path("v3/technique")` + `/relationship`). É o **único** lugar do servidor que desserializa `StudioPage`:
+
+1. Carrega **todas** as páginas: `jongo.getCollection("studio_page").find().as(StudioPage.class)` (linha 225).
+2. **Nós** (linhas 276-280): para cada página, `if(page.display)` → `addNode(page.id, page.title, page.style)`. `addNode` (linha 667) omite o nó se `style.visible == false`; usa `style.background` como cor.
+3. **Arestas** (linhas 565-588): para cada página com `display == true` e `references` não-vazio, cada `Reference` vira uma aresta:
+   - `reference.type == "player"` → liga ao nó `player`; `== "notification"` → nó `notification`; senão usa `reference.id`.
+   - `reference.way == "from"` → aresta `referência → página` (consome);
+   - `reference.way == "to"` → aresta `página → referência` (produz);
+   - rótulo da aresta = `reference.getLinkLabel()`.
+
+> ⚠️ **Bug confirmado:** `if(page.display)` (linhas 277 e 566) faz _unboxing_ de `Boolean`. Uma página persistida **sem** o campo `display` (valor `null`) lança `NullPointerException` e **derruba o endpoint inteiro** `GET /v3/technique/relationship` para o tenant — não apenas aquela página. Ver seção 5 e 7.
+
+```mermaid
+flowchart LR
+    DOCS[coleção studio_page] -->|find as StudioPage| GTM[findComponentsRelationship]
+    GTM -->|page.display == true| NODE["addNode(id, title, style)"]
+    GTM -->|reference.way = from| LFROM[aresta ref → página]
+    GTM -->|reference.way = to| LTO[aresta página → ref]
+    NODE --> OUT[nodes + links]
+    LFROM --> OUT
+    LTO --> OUT
+    GTM -.->|display == null| NPE[NullPointerException → 500]
+```
+
+### 2.5 Geração assistida por IA — `AIRest.buildStudioPage`
+
+`POST /v3/ai/build/studio_page` (`AIRest`, `@Path("v3/ai")` + `/build/studio_page`, linha 1130):
+
+- Recebe `{ "content": "<pedido>", "script"?, "html"? }`.
+- Garante a existência do prompt `intro_build_studio_page` (cria via `IAManager.insertPrompt` se ausente — o texto do prompt é a própria documentação do recurso embutida no código, linha 1140).
+- Chama OpenAI (modelo `gpt-3.5`) com a function `build_studio_page` que retorna `script`, `html`, `title`, `slug` (todos obrigatórios).
+- **Devolve o JSON gerado e não persiste.** A gravação efetiva continua sendo um `PUT /v3/database/studio_page` feito pelo frontend.
+
+---
+
+## 3. Estrutura dos Objetos
+
+### 3.1 `StudioPage` — documento raiz (coleção `studio_page`)
+
+`@JsonIgnoreProperties(ignoreUnknown=true)`. **Importante:** essa anotação só atua na **leitura** por `GameTechniqueManager`. Na escrita via `DatabaseRest` (que usa `HashMap`), **campos desconhecidos são persistidos**.
+
+| Campo | Tipo | Padrão | Obrigatório | Descrição |
+|---|---|---|---|---|
+| `_id` | String | `Guid.newShortGuid()` se ausente/null | Não (auto) | Identificador SHORT GUID. **Não** é ObjectId do Mongo |
+| `title` | String | — | Não (em runtime) | Nome exibido no menu do Studio e como rótulo do nó no mapa de estratégia |
+| `slug` | String | — | Não (em runtime) | Caminho relativo da página no Studio (ex.: `studio/custom/hello`). String opaca para o backend; suporta parâmetros (`:id`) interpretados **pelo frontend** |
+| `script` | String | — | Não | Código JavaScript da página. **String opaca** — armazenado e executado pelo frontend (AngularJS), nunca pelo backend |
+| `html` | String | — | Não | Código HTML da página. **String opaca** — renderizado pelo frontend (Bootstrap) |
+| `display` | Boolean | — | **Sim, na prática** | `true` = aparece no menu do Studio e vira nó no mapa de estratégia. **Se `null` quebra `GET /v3/technique/relationship`** (ver seção 5) |
+| `created` | Date | — | Não | **Nunca preenchido automaticamente** (ver abaixo) |
+| `updated` | Date | — | Não | **Nunca preenchido automaticamente** (ver abaixo) |
+| `folder` | String | — | Não | Id de pasta (módulo Folder). Referência organizacional; não processado pelo código de `studio_page` |
+| `extra` | Map<String,Object> | `{}` | Não | Atributos arbitrários. Persistido; não consumido pelo backend de `studio_page` (usado pela diretiva frontend `<input-extra>`) |
+| `techniques` | List<String> | `[]` | Não | Códigos de técnica de jogo (GT…). Ver 3.4 |
+| `style` | ObjectStyle | `null` | Não | Estilização do nó no mapa de estratégia (ver 3.2) |
+| `references` | List<Reference> | `null` | Não | Arestas do mapa de estratégia (ver 3.3) |
+
+#### Campos computados / não persistidos
+
+Nenhum. Todos os campos da entidade são persistidos.
+
+#### Campos preenchidos automaticamente
+
+**Nenhum** — exceto `_id` (no `DatabaseRest`). Em particular, `created` e `updated` **não são setados por nenhum código** (confirmado por busca em `src/main/java/com/funifier/engine/studio/`). Eles existem na entidade mas só serão gravados se o **cliente** os enviar; caso contrário permanecem `null` para sempre.
+
+#### Campos removidos silenciosamente
+
+Nenhum na escrita — o `DatabaseRest` persiste o documento como recebido (`HashMap`). Não há sanitização de campos.
+
+#### Campos legados / código comentado
+
+```java
+// public List<String> tags = new ArrayList<>();   // StudioPage.java linha 45
+```
+
+- O campo **`tags`** está **comentado** na entidade — não existe em runtime na leitura. Como a escrita é via `HashMap`, um `tags` enviado pelo cliente **é gravado no Mongo**, mas é **silenciosamente ignorado** por `GameTechniqueManager` (não está mapeado no POJO + `ignoreUnknown=true`).
+- Os Javadocs da entidade referem-se a **"widget"** ("*Tags related to this widget*" linha 44; "*All game techniques related to this widget*" linha 48), indicando que `StudioPage` foi **clonada de `Widget_V3`**. `style`, `references`, `techniques` e `extra` são herança desse molde e só fazem sentido no contexto do mapa de estratégia / técnicas de jogo.
+
+### 3.2 `ObjectStyle` — sub-objeto `style`
+
+`com.funifier.engine.integration.trigger.ObjectStyle`, `@JsonIgnoreProperties(ignoreUnknown=true)`.
+
+| Campo | Tipo | Descrição |
+|---|---|---|
+| `background` | String | Cor de fundo do nó no mapa de estratégia (`GameTechniqueManager.node`, linha 677) |
+| `visible` | Boolean | `false` → o nó é **omitido** do mapa de estratégia (`addNode`, linha 668). `null`/`true` → visível |
+
+### 3.3 `Reference` — item de `references`
+
+`com.funifier.engine.integration.trigger.Reference`, `@JsonIgnoreProperties(ignoreUnknown=true)`.
+
+| Campo | Tipo | Obrigatório | Descrição |
+|---|---|---|---|
+| `_id` | String | Sim | Id do componente referenciado |
+| `type` | String | Sim | Coleção/tipo do alvo (ex.: `point`, `player`, `notification`, `challenge`). `player`/`notification` recebem tratamento especial nos links |
+| `title` | String | Sim | Título do alvo |
+| `way` | String | — | `"from"` (consome: alvo → página) ou `"to"` (produz: página → alvo). Constantes `Reference.WAY_FROM`/`WAY_TO` |
+| `linkLabel` | String | — | Texto sobre a aresta. `getLinkLabel()` retorna `""` quando vazio |
+
+### 3.4 Técnicas de jogo (`techniques`)
+
+`techniques` é uma `List<String>` de **códigos de técnica de jogo** (GT…). O backend de `studio_page` **não** define nem consome esses códigos diretamente. Eles só passam a ter efeito **se** existir um `GameTechniqueField` mapeando `entity=studio_page` / `field=techniques` — nesse caso `GameTechniqueManager.findConfiguredTechniques` (linha 701) os agrega na contagem de uso por técnica (com teto de 20 itens por técnica, linha 718).
+
+> O catálogo operacional de cada código GT vive na coleção `technique` (`Entity.GAME_TECHNIQUE`), **não** é hard-coded para `studio_page`. Esta documentação não enumera os códigos para não inventar comportamento.
+
+### 3.5 Relações entre objetos
+
+```mermaid
+erDiagram
+    STUDIO_PAGE ||--o| OBJECT_STYLE : "style"
+    STUDIO_PAGE ||--o{ REFERENCE : "references"
+    REFERENCE }o--|| COMPONENTE : "type + _id (player/notification/...)"
+```
+
+---
+
+## 4. Endpoints
+
+Todos abaixo são do CRUD genérico `DatabaseRest` com `{collection}` = `studio_page`. **Autenticação:** `Authorization: Bearer <token>`; o token precisa do scope **`database`** (`Application.SCOPE_DATABASE`). Sem o scope, o endpoint retorna **`200` com corpo vazio/null** (silencioso) — não `403`.
+
+### 4.1 `POST /v3/database/studio_page` — criar
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Inserir nova página |
+| Full replace ou patch | Insert direto |
+| `_id` | Auto-gerado se ausente/null (`Guid.newShortGuid()`) |
+| Side effects | Triggers `before_create`/`after_create`; auditoria `EVENT_CREATE` |
+| Resposta | `201 CREATED` com o documento |
+| Query params | `strict=true` → BSON strict na resposta |
+
+### 4.2 `PUT /v3/database/studio_page` — criar ou substituir
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Substituir página existente (upsert por `_id`) |
+| Full replace ou patch | **FULL REPLACE** (`jongo.save`) — campos omitidos são perdidos |
+| `_id` | Auto-gerado se ausente → **cria duplicata** em vez de atualizar |
+| Side effects | Triggers `before_update`/`after_update`; auditoria `EVENT_UPDATE` |
+| Resposta | `201 CREATED` com o documento |
+
+### 4.3 `GET /v3/database/studio_page/{id}` — buscar por id
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | `findOne({_id:id})` |
+| Quirk | `id == "me"` → resolve para o jogador do token |
+| Query params | `strict=true` → BSON strict; senão remove campos null |
+| Guard | `collection.length > 3` e `id` presente |
+
+### 4.4 `GET /v3/database/studio_page` — listar / consultar
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | `{$match:{ <q> }}` paginado |
+| `q` (query) | Filtro MongoDB cru (ex.: `display:true`) — concatenado direto (ver seção 8) |
+| `Range` (header) | Paginação (ex.: `items=0-100`); padrão página de 100 |
+| `max_results` | Default 100 |
+| `strict` | `true` → BSON strict |
+| Resposta | Lista paginada + header `Content-Range` |
+
+### 4.5 `DELETE /v3/database/studio_page?q=...` — excluir
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | `remove({ <q> })` |
+| Guard | `q.length >= 3` (sem `q` válido, **não apaga nada**) |
+| Side effects | Coleta ids (se `count <= 20000`) e dispara triggers `before_delete`/`after_delete`; auditoria `EVENT_DELETE` |
+| Resposta | `200 OK`, corpo null |
+
+### 4.6 Demais operações genéricas (aplicam-se à coleção)
+
+`POST /v3/database/studio_page/bulk` (insert em lote, `async=true` opcional), `POST /v3/database/studio_page/aggregate` (pipeline de agregação), `POST|DELETE|GET /v3/database/studio_page/index` (índices), `GET /v3/database/count?collection=studio_page&q=...`, `DELETE /v3/database/studio_page/drop`.
+
+### 4.7 `POST /v3/ai/build/studio_page` — geração por IA
+
+Gera `script`/`html`/`title`/`slug` via OpenAI. **Não persiste** (ver 2.5).
+
+**Exemplo de request (PUT):**
 
-### 1. Hello World
 ```json
 {
-    "_id": "hello1",
-    "display": true,
-    "title": "Hello World!",
-    "slug": "studio/custom/hello",
-    "html": "<button ng-click=\"hello()\" class=\"btn btn-warning\">Hello</button>",
-    "script": "$scope.hello = function(){ alert('Hello World!'); }"
+  "_id": "minha_pagina",
+  "display": true,
+  "title": "Minha Página",
+  "slug": "studio/custom/minha-pagina",
+  "html": "<h1>Oi</h1>",
+  "script": "$scope.x = 1;"
 }
 ```
 
-### 2. Lista Simples (Desafios)
-```javascript
-/* "display": true, "title": "Quest List", "slug": "studio/custom/challenge" */
-$scope.all = [];
-$scope.list = function () {
-  $http({method: 'GET', url:Marketplace.auth.getService() + '/v3/database/challenge',
-         headers: {"Authorization": Marketplace.auth.getAuthorization(), "content-type": "application/json"}
-  }).then(function(data){
-    $scope.all = data.data;
-  });
-};
-$scope.list();
+**Exemplo de response (201):** o próprio documento, com `_id` preenchido.
+
+---
+
+## 5. Regras de Negócio
+
+Regras que existem **no código** e não no schema:
+
+- **Sem validação de schema na escrita.** `DatabaseRest` grava o `HashMap` recebido como veio. Qualquer campo extra é persistido; nenhum campo é obrigatório do ponto de vista do backend (o `StudioPage` POJO só restringe a **leitura** em `GameTechniqueManager`).
+- **`display` deve ser sempre booleano.** Páginas com `display == null` provocam `NullPointerException` em `findComponentsRelationship` (linhas 277 e 566), derrubando `GET /v3/technique/relationship` para **todo o tenant**. Sempre envie `display: true` ou `display: false`.
+- **`PUT` é full-replace e upsert.** Omitir um campo o remove; omitir `_id` cria um novo registro.
+- **`created`/`updated` não são gerenciados.** Se você precisa de timestamps, é responsabilidade do cliente preenchê-los — o servidor nunca o faz.
+- **Scope obrigatório `database`.** Sem ele, leituras e escritas retornam vazio/`null` com `200`, sem erro explícito.
+- **`DELETE` exige `q` com `length >= 3`.** Um delete sem filtro válido é silenciosamente um no-op.
+- **Multi-tenant físico.** A conexão Mongo é resolvida por `FrontController.getInstance(apiKey)`. Não há campo de tenant no documento `studio_page`; o isolamento é por base de dados.
+- **`techniques`/`style`/`references`/`extra`** só têm efeito no contexto do mapa de estratégia (e técnicas de jogo, quando configuradas). Não afetam a renderização da página.
+
+---
+
+## 6. Comportamentos Automáticos
+
+| Comportamento | Trigger | Impacto | Persistência |
+|---|---|---|---|
+| Auto `_id` | POST/PUT sem `_id`/`null` | `Guid.newShortGuid()` | Sim |
+| Triggers de escrita | POST → `before/after_create`; PUT → `before/after_update`; DELETE → `before/after_delete` | Executa triggers configuradas na coleção `studio_page` | Conforme a trigger |
+| Auditoria | Toda criação/atualização/exclusão | `AuditManager.log(EVENT_CREATE/UPDATE/DELETE)` com o usuário logado no Studio | `audit`/`audit_log` |
+| Criptografia de campos | Se `CryptObjectField` existir p/ `studio_page` e token autorizado | Campos cifrados/decifrados | Sim |
+| Full replace | PUT (`jongo.save`) | Documento inteiro substituído | Sim |
+| Nó/arestas no mapa de estratégia | Leitura em `GET /v3/technique/relationship` | `display`/`style`/`references` viram nós e arestas | Não (computado) |
+| Auto-criação do prompt de IA | 1º `POST /v3/ai/build/studio_page` sem prompt | Cria `intro_build_studio_page` | `ai_prompt` |
+
+```mermaid
+flowchart LR
+    W[POST/PUT/DELETE studio_page] --> SC{scope database?}
+    SC -->|não| EMPTY[200 vazio]
+    SC -->|sim| ID[auto _id se ausente]
+    ID --> BEF[trigger BEFORE_*]
+    BEF --> DB[(insert/save/remove)]
+    DB --> AFT[trigger AFTER_*]
+    AFT --> AUD[AuditManager.log]
+    AUD --> RESP[201/200]
 ```
 
-### 3. Lista Paginada (Players)
+---
+
+## 7. Suportado vs NÃO Suportado
+
+### ✅ Suportado
+
+- CRUD completo via `/v3/database/studio_page` (POST, PUT, GET por id, GET lista, DELETE, bulk, aggregate, índices, count, drop).
+- Persistência de `html`/`script`/`slug`/`title`/`display`/`folder`/`extra`/`techniques`/`style`/`references` e de **quaisquer campos extras** enviados.
+- Disparo de triggers e registro de auditoria em toda mutação.
+- Participação no mapa de estratégia (`GET /v3/technique/relationship`) via `display`/`style`/`references`.
+- Geração assistida por IA do conteúdo (`POST /v3/ai/build/studio_page`) — sem persistência.
+- Paginação por header `Range` e modo BSON strict (`?strict=true`).
+
+### ❌ NÃO Suportado
+
+- **Endpoint REST dedicado** (`/v3/studio_page`, `/v3/studio/page`): **não existe**. Só o CRUD genérico de `database`.
+- **Validação de schema na escrita**: inexistente — qualquer payload é gravado.
+- **Rejeição de campos desconhecidos na escrita**: não ocorre (apenas na leitura pelo POJO). Ex.: `tags` é gravado mas ignorado.
+- **Atualização parcial (PATCH)**: não há — `PUT` sempre substitui o documento inteiro.
+- **Timestamps automáticos** (`created`/`updated`): nunca preenchidos pelo servidor.
+- **Campo `tags`**: comentado na entidade (`StudioPage.java:45`) — sem efeito em runtime.
+- **Interpretação de `html`/`script`/`slug` pelo backend**: o `funifier-service` não parseia, valida nem executa nada disso. AngularJS, `Marketplace`, diretivas (`<image-picker>`, `<principal-picker>`, `<input-extra>`), Highcharts, Bootstrap e roteamento por `slug` são **contrato do frontend do Studio** — só aparecem no servidor como texto dentro do prompt de IA `intro_build_studio_page` (`AIRest:1140`), não como código executável.
+- **Tratamento de `display == null`**: não tratado — provoca `NullPointerException` no mapa de estratégia (limitação confirmada).
+
+---
+
+## 8. Segurança e Permissões
+
+### Autenticação e autorização
+
+- Exige `Authorization: Bearer <token>` resolvido em `AuthBean`.
+- Exige o scope **`database`** (`Application.SCOPE_DATABASE`). Não há granularidade por página: qualquer token com scope `database` lista, cria, edita e apaga **qualquer** `studio_page` do tenant.
+- Falta de scope **não** gera `403` — retorna `200` vazio (falha silenciosa).
+
+### Isolamento multi-tenant
+
+Conexão Mongo própria por tenant via `FrontController.getInstance(apiKey)`. Sem campo de tenant no documento — isolamento físico por base.
+
+### Superfície de XSS / execução de código (por design)
+
+`html` e `script` são strings arbitrárias armazenadas e posteriormente **executadas pelo frontend do Studio** (AngularJS). Portanto, qualquer usuário com scope `database` que escreva em `studio_page` consegue **injetar JavaScript que roda no contexto administrativo do Studio** de outros operadores que abrirem a página. É um vetor de **stored XSS / execução de código** inerente ao recurso — o backend não sanitiza nem poderia, pois não interpreta o conteúdo.
+
+### Injeção MongoDB
+
+`GET /v3/database/studio_page` e `/aggregate` concatenam o parâmetro `q` e o array `aggregations` diretamente no pipeline (`s.append(q)`, `DatabaseRest` linhas 144, 516-533). Um cliente autenticado pode injetar `$where`, `$lookup` para outras coleções, etc. **Não há whitelist nem sanitização** — o modelo de segurança assume que tokens autenticados são confiáveis.
+
+---
+
+## 9. Observabilidade e Troubleshooting
+
+### Diagnóstico básico
+
+| Sintoma | Verificar |
+|---|---|
+| Página não aparece no menu do Studio | `display` é `true`? `db.studio_page.findOne({_id:"X"}).display` |
+| `GET /v3/technique/relationship` retornando 500 | Alguma página com `display` ausente/`null` → `db.studio_page.find({display:{$exists:false}})` ou `{display:null}` |
+| "Atualizei mas criou outra página" | `PUT` enviado **sem** `_id` → duplicata. Conferir `db.studio_page.find({slug:"..."})` |
+| Campos "somem" após salvar | `PUT` é full-replace — campos omitidos são removidos |
+| `created`/`updated` sempre null | Esperado — não são automáticos |
+| Página não salva / lista vazia inesperada | Token tem scope `database`? (sem ele, `200` vazio) |
+
+### Queries úteis (mongosh)
+
 ```javascript
-/* "display": true, "title": "Player List", "slug": "studio/custom/player" */
-$scope.range = { request: "items=0-100" };
-$scope.gotopage = function(page){
-  $scope.range.request = Marketplace.range.paginate(page, $scope.range.response);
-  $scope.list();
-};
-$scope.paginate = function (total) {
-  var to = $scope.range.page + total;
-  $scope.range.request = Marketplace.range.paginate(to, $scope.range.response);
-  $scope.list();
-};
-$scope.all = [];
-$scope.list = function () {
-  $http({method: 'GET', url:Marketplace.auth.getService() + '/v3/database/player',
-    headers: {"Authorization": Marketplace.auth.getAuthorization(), "Range": $scope.range.request, "content-type": "application/json"}
-  }).then(function(data){
-    $scope.all = data.data;
-    $scope.range = Marketplace.range.parse(data.headers(["content-range"]));
-  });
-};
-$scope.list();
-```
-HTML de paginação:
-```html
-<div>
-  Page <input type="number" ng-model="range.page" ng-change="gotopage(range.page)" style="width:40px;" /> of {{range.pages}}
-  <button ng-click="paginate(-1)" class="btn btn-default"><span class="glyphicon glyphicon-chevron-left"></span></button>
-  <button ng-click="paginate(+1)" class="btn btn-default"><span class="glyphicon glyphicon-chevron-right"></span></button>
-</div>
+// Páginas que quebram o mapa de estratégia (display null/ausente)
+db.studio_page.find({ $or: [ {display: null}, {display: {$exists: false}} ] }, {title:1, slug:1})
+
+// Corrigir em massa páginas sem display
+db.studio_page.updateMany({ display: {$exists: false} }, { $set: {display: false} })
+
+// Listar páginas visíveis no menu
+db.studio_page.find({ display: true }, { title:1, slug:1 })
+
+// Detectar slugs duplicados (sintoma de PUT sem _id)
+db.studio_page.aggregate([{ $group: { _id:"$slug", n:{$sum:1} } }, { $match: { n:{$gt:1} } }])
 ```
 
-### 4. CRUD Completo (Carros)
-**Lista** (`display: true`, slug: `studio/custom/car/list`): Lista + busca + paginação + botões editar/excluir + botão "NEW"
-- DELETE: `$http({method: 'DELETE', url: API + "/v3/database/car__c?q=_id:'" + id + "'", ...})`
-- Navegação: `$location.path("/studio/custom/car/form/" + id)` ou `"/studio/custom/car/form/new"`
+### Comandos HTTP úteis
 
-**Formulário** (`display: false`, slug: `studio/custom/car/form/:id`):
-- Carrega via GET: `/v3/database/car__c?strict=true&q=_id:'ID'`
-- Salva via PUT: `/v3/database/car__c`
-- Usa `$routeParams.id` para saber se é edição ou criação (`"new"` = novo)
-- `<image-picker on-change="setImage" ...>` para upload de imagem
+```bash
+# Buscar por id (BSON strict para preservar tipos)
+GET /v3/database/studio_page/minha_pagina?strict=true
 
-### 5. Gráfico Highcharts (Active Players)
-```javascript
-/* "display": true, "title": "Daily Active Players", "slug": "studio/custom/kpi/players" */
-$scope.load = function () {
-    $http({
-        method: 'POST', url: Marketplace.auth.getService() + '/v3/database/action_log/aggregate',
-        headers: { Authorization: Marketplace.auth.getAuthorization(), 'content-type': 'application/json'},
-        data: [
-            {"$match": { "time": { "$gte": { "$date": "-1y" } } } },
-            {"$addFields": { "day": { "$dayOfYear": "$time" } } },
-            {"$group": { "_id": { "player": "$userId", "day": "$day" }, "time": { "$max": "$time" }}},
-            {"$group": { "_id": "$_id.day", "total_users": { "$sum": 1 }, "time": { "$max": "$time" }}},
-            {"$project": { "_id": 0, "day_of_year": '$_id', "total": '$total_users', "time": 1}},
-            {"$sort": { "day_of_year": 1 } }
-        ]
-    }).then(function (data) {
-        var transformedData = data.data.map(function (d) { return [d.time, d.total]; });
-        new Highcharts.Chart({
-            chart: { renderTo: 'chart', type: 'line' },
-            title: { text: 'Daily Active Players' },
-            xAxis: { type: 'datetime' },
-            yAxis: { title: { text: 'Total' } },
-            series: [{ name: 'Total over time', data: transformedData }],
-            credits: { enabled: false }
-        });
-    });
-};
-$scope.load();
+# Listar páginas exibidas no menu
+GET /v3/database/studio_page?q=display:true
+
+# Excluir (q obrigatório, length >= 3)
+DELETE /v3/database/studio_page?q=_id:'minha_pagina'
 ```
 
-## API REST para Gerenciar Páginas
+### Erros comuns e causas
+
+- **`500` em `/v3/technique/relationship`** → `display` null em alguma página (NPE).
+- **Duplicatas** → `PUT` sem `_id`.
+- **Perda de campos** → confiar em `PUT` como patch.
+- **`200` sem dados** → token sem scope `database`.
+- **`DELETE` não apaga** → `q` ausente ou com menos de 3 caracteres.
 
-**IMPORTANTE:** As páginas customizadas ficam na collection `studio_page` (NÃO `page`).
+---
+
+## 10. Exemplos Práticos
+
+### 10.1 Exemplo mínimo funcional
 
 ```bash
-# Criar/atualizar página
-curl -X PUT "https://service2.funifier.com/v3/database/studio_page" \
-  -H "Authorization: Bearer TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"_id":"minha_pagina", "display":true, "title":"Minha Página", "slug":"studio/custom/minha-pagina", "html":"<h1>Oi</h1>", "script":"/* js */"}'
-
-# Listar páginas
-curl "https://service2.funifier.com/v3/database/studio_page" \
-  -H "Authorization: Bearer TOKEN"
-
-# Deletar página
-curl -X DELETE "https://service2.funifier.com/v3/database/studio_page?q=_id:'ID'" \
-  -H "Authorization: Bearer TOKEN"
+PUT /v3/database/studio_page
+Authorization: Bearer <token-com-scope-database>
+Content-Type: application/json
+
+{
+  "_id": "hello1",
+  "display": true,
+  "title": "Hello World!",
+  "slug": "studio/custom/hello",
+  "html": "<button ng-click=\"hello()\" class=\"btn btn-warning\">Hello</button>",
+  "script": "$scope.hello = function(){ alert('Hello World!'); }"
+}
 ```
 
-## Checklist
+### 10.2 Exemplo avançado — com estilização e referências (mapa de estratégia)
+
+```json
+{
+  "_id": "kpi_vendas",
+  "display": true,
+  "title": "KPI de Vendas",
+  "slug": "studio/custom/kpi/vendas",
+  "html": "<div id=\"chart\"></div>",
+  "script": "/* monta Highcharts via /v3/database/action_log/aggregate */",
+  "folder": "dashboards",
+  "style": { "background": "#1565C0", "visible": true },
+  "techniques": [],
+  "references": [
+    { "_id": "vendas", "type": "action", "title": "Venda", "way": "from", "linkLabel": "consome ação" },
+    { "_id": "notification", "type": "notification", "title": "Aviso", "way": "to", "linkLabel": "gera aviso" }
+  ]
+}
+```
+
+Isso cria um nó azul "KPI de Vendas" no mapa de estratégia (`GET /v3/technique/relationship`), com uma aresta entrando da ação `vendas` e outra saindo para `notification`.
+
+### 10.3 Anti-pattern — `PUT` sem `_id` para "atualizar"
+
+```json
+// ❌ NÃO faça isso esperando atualizar a página "hello1"
+PUT /v3/database/studio_page
+{ "display": true, "title": "Hello v2", "slug": "studio/custom/hello", "html": "...", "script": "..." }
+```
+
+Sem `_id`, o servidor gera um id novo e **cria uma segunda página** com o mesmo `slug` — não atualiza a original. Sempre inclua `_id` no `PUT`.
+
+### 10.4 Anti-pattern — omitir `display`
+
+```json
+// ❌ Página sem display
+PUT /v3/database/studio_page
+{ "_id": "p1", "title": "Painel", "slug": "studio/custom/p1", "html": "...", "script": "..." }
+```
+
+`display` fica `null` e a próxima chamada a `GET /v3/technique/relationship` lança `NullPointerException`, derrubando o mapa de estratégia do tenant inteiro. Sempre envie `display` explicitamente.
+
+---
+
+## Checklist de Configuração
 
-- [ ] Definir `_id`, `title`, `slug`, `display`
-- [ ] Escrever `html` com Bootstrap
-- [ ] Escrever `script` com AngularJS
-- [ ] Usar `Marketplace.auth.*` para autenticação
-- [ ] Usar `?strict=true` em GETs para preservar tipos BSON
-- [ ] Testar no Studio (navegar até a URL do slug)
-- [ ] Para CRUDs: criar página de lista (display:true) + formulário (display:false)
+- [ ] `_id` **sempre** presente em `PUT` (senão cria duplicata)
+- [ ] `display` **sempre** booleano explícito (`true`/`false`) — nunca omitir (NPE no mapa de estratégia)
+- [ ] `title` e `slug` definidos
+- [ ] `html` e `script` enviados como strings escapadas (o backend não os valida)
+- [ ] Token com scope `database` (senão `200` vazio silencioso)
+- [ ] Ciente de que `PUT` é full-replace: enviar o documento **completo**, não só os campos alterados
+- [ ] `created`/`updated` preenchidos pelo cliente, se necessários (não são automáticos)
+- [ ] `DELETE` sempre com `q` válido (`length >= 3`)
+- [ ] Armadilha: campos extras (ex.: `tags`) são gravados mas ignorados pelo backend
+- [ ] Segurança: `script`/`html` executam no contexto admin do Studio — trate `studio_page` como superfície de execução de código