funifier-mcp 0.2.26 → 0.2.28

package/datasource-funifier-docs/knowledge/guides/java-entities.md

@@ -1,332 +1,388 @@
 # Java Entities — Referência
 
-As entidades são os objetos Java (POJOs) que representam os dados armazenados no MongoDB. Cada entidade mapeia para uma coleção no banco de dados.
+## 1. Visão Geral
 
----
+### 1.1 O que é este documento
 
-## Entidades Principais
+Este documento descreve as entidades Java (POJOs) da plataforma Funifier — campos, tipos, coleção MongoDB de cada uma e constantes associadas — para uso em código server-side (triggers, schedulers e public endpoints).
 
-### Player
+### 1.2 Quando consultar
 
-**Coleção MongoDB:** `player`
-**Classe:** `com.funifier.engine.player.Player`
+- Consulte ao precisar dos **campos e tipos** de um objeto manipulado em código (ex: o `entity` de um trigger).
+- Consulte ao precisar saber em **qual coleção MongoDB** uma entidade é persistida.
+- Consulte ao precisar das **constantes de `Achievement`** (`TYPE_POINT`, `TYPE_CHALLENGE`, etc.).
+- Consulte ao decidir entre **entidade nativa** e **coleção customizada (`__c`)**.
 
-```java
-// Campos principais
-String _id;          // ID do jogador (ex: "john")
-String name;         // Nome do jogador
-String email;        // Email
-String password;     // Senha (hash)
-Map<String, Object> extra;  // Campos customizados (ex: department, country)
-List<String> teams;  // IDs das equipes
-List<String> friends; // IDs dos amigos
-ImageSet image;      // Imagens (small, medium, original)
-Date created;        // Data de cadastro
-```
+### 1.3 Quando NÃO consultar
 
-```json
-{"_id": "john", "name": "John Travolta", "email": "john@funifier.com", "teams": ["sales"], "extra": {"country": "USA", "department": "IT"}, "image": {"small": {"url": "..."}, "medium": {"url": "..."}, "original": {"url": "..."}}}
-```
+- **NÃO** consulte para os **métodos** que operam sobre estas entidades — use `datasource-funifier-docs/knowledge/guides/java-managers.md`.
+- **NÃO** consulte para a **mecânica de triggers** (assinatura, eventos, acesso a `entity`) — use `datasource-funifier-docs/knowledge/guides/triggers-guide.md`.
+- **NÃO** consulte para **acesso ao banco** (Jongo, `/v3/database`) — use `datasource-funifier-docs/knowledge/guides/database-access.md`.
 
----
+### 1.4 Índice de decisão
 
-### Achievement
+| Problema / Situação | O que fazer | Seção |
+|---|---|---|
+| Preciso dos campos do jogador | Ver entidade Player | §2 |
+| Preciso entender o que é uma conquista (ponto, desafio, compra, nível) | Ver entidade Achievement + constantes | §3 |
+| Preciso ler atributos de uma ação executada | Ver entidade ActionLog | §4 |
+| Preciso da definição de um tipo de ação | Ver entidade Action | §5 |
+| Preciso das regras/recompensas de um desafio | Ver entidade Challenge | §6 |
+| Preciso dos campos de um item de loja | Ver entidade CatalogItem | §7 |
+| Preciso de Point/Level/Team | Ver entidades de configuração | §8 |
+| Preciso de Lottery/Mystery/Competition/Question/Quiz/Swap/Notification | Ver entidades de engajamento | §9 |
+| Preciso de Trigger/Scheduler/PublicEndpoint/Webhook | Ver entidades de infraestrutura | §10 |
+| Não sei em qual coleção a entidade vive | Ver mapeamento completo | §11 |
+| Preciso de uma estrutura de dados própria | Ver Custom Objects (`__c`) | §12 |
 
-**Coleção MongoDB:** `achievement`
-**Classe:** `com.funifier.engine.achievement.Achievement`
+### 1.5 Restrições globais críticas
 
-Representa qualquer conquista do jogador: pontos ganhos, desafios completados, itens comprados, níveis alcançados.
+> ⚠️ **O campo é `_id`, mas em Groovy o acesso é `entity.id`.** Em código Groovy de trigger/endpoint, `entity._id` **não** resolve a propriedade (`patterns.md` §10). Consequência: `null` silencioso ao ler o ID. → Use `entity.id` em Groovy; `_id` aparece apenas no JSON/documento MongoDB. Detalhe em `datasource-funifier-docs/knowledge/guides/triggers-guide.md`.
 
-```java
-// Campos principais
-String _id;       // ID da conquista
-String player;    // ID do jogador
-double total;     // Quantidade (pontos, unidades)
-int type;         // Tipo (0=Point, 1=Challenge, 2=VirtualGood, 3=Level)
-String item;      // ID do item (point_category, challenge, catalog_item, level)
-Date time;        // Data da conquista
-
-// Constantes de tipo
-static final int TYPE_POINT = 0;
-static final int TYPE_CHALLENGE = 1;
-static final int TYPE_VIRTUAL_GOOD = 2;
-static final int TYPE_LEVEL = 3;
-```
+> ⚠️ **`password` do Player é gravado sem hash no `POST/PUT /v3/player`.** Consequência: senha em texto plano. → Hashear via BCrypt em trigger antes de `insert` (`patterns.md` §2 e §11).
 
-```json
-{"_id": "64a5d2", "player": "john", "total": 25.0, "type": 0, "item": "xp", "time": {"$date": "2023-07-05T20:57:33.303Z"}}
-```
+> ⚠️ **Salvar Player parcial apaga campos não enviados.** Consequência: `name`/`email`/`extra` somem. → Read-merge-write com objeto completo (`patterns.md` §10).
+
+> ⚠️ **Nomes totalmente qualificados (`com.*`/`org.*`) são bloqueados no sandbox de Public Endpoint.** Instanciar POJO (`new Player()`) funciona nos três runtimes; referenciar `com.funifier.engine.player.Player` por extenso só funciona em Trigger/Scheduler. → Tabela do sandbox em `patterns.md` §1.5.
+
+### 1.6 Documentos relacionados
+
+> 📄 `datasource-funifier-docs/knowledge/guides/java-managers.md` — métodos que operam sobre estas entidades
+> 📄 `datasource-funifier-docs/knowledge/guides/triggers-guide.md` — como `entity` é exposta e manipulada em triggers
+> 📄 `datasource-funifier-docs/knowledge/guides/database-access.md` — leitura/escrita das coleções correspondentes
 
 ---
 
-### ActionLog
+## 2. Player
+
+Quando usar: ao ler/escrever dados de jogador em código, ou manipular o `entity` de um trigger de `player`.
+Não usar quando: precisar dos métodos de gestão (CRUD, roles) → `java-managers.md` §PlayerManager.
+Depende de: `ImageSet` (campo `image`).
+Disponível em: Todos.
+
+### Descrição
 
-**Coleção MongoDB:** `action_log`
-**Classe:** `com.funifier.engine.action.ActionLog`
+Representa um usuário da aplicação. Coleção MongoDB `player`, classe `com.funifier.engine.player.Player`. É entidade **nativa** — escrita via `POST /v3/player` ou `PlayerManager.insert`, nunca via `/v3/database/player`.
 
-Registo de uma ação executada por um jogador.
+### Uso
 
 ```java
-// Campos principais
-String _id;       // ID do log
-String actionId;  // ID da ação (ex: "sell")
-String userId;    // ID do jogador (ex: "john")
-Date time;        // Data da execução
-Map<String, Object> attributes; // Atributos da ação (ex: product, price)
+String _id;                  // ID do jogador (ex: "john") — em Groovy: player.id
+String name;                 // Nome
+String email;                // Email
+String password;             // Senha (hash BCrypt; gravado sem hash se vier do POST/PUT — ver §1.5)
+Map<String, Object> extra;   // Campos customizados (ex: department, country, plan)
+List<String> teams;          // IDs das equipes
+List<String> friends;        // IDs dos amigos
+ImageSet image;              // Imagens: getSmall()/getMedium()/getOriginal() → getUrl()
+Date created;                // Data de cadastro
 ```
 
 ```json
-{"_id": "64a5d92", "actionId": "sell", "userId": "john", "time": {"$date": "2023-07-05T20:57:33.303Z"}, "attributes": {"product": "book", "price": 120}}
+{"_id": "john", "name": "John Travolta", "email": "john@funifier.com", "teams": ["sales"], "extra": {"country": "USA", "department": "IT"}, "image": {"small": {"url": "..."}, "medium": {"url": "..."}, "original": {"url": "..."}}}
 ```
 
+### Armadilhas conhecidas
+
+- **`entity._id` em Groovy retorna `null`** → use `entity.id` (§1.5). Causa: o getter da propriedade Groovy não mapeia `_id`.
+- **Salvar `{_id, extra}` sem `name`/`email`** → campos apagados. Causa: o save persiste o objeto enviado. Correção: read-merge-write (`patterns.md` §10).
+- **`image` parcial** → rejeitada. Causa: exige `size`/`width`/`height`/`depth` em cada tamanho (mesmo `0`). Correção: estrutura completa (`patterns.md` §10).
+
 ---
 
-### Action
+## 3. Achievement
+
+Quando usar: ao criar conquistas programaticamente, ou ler o `entity` de um trigger de `achievement`/`point_category`.
+Não usar quando: precisar somar/consultar conquistas → `java-managers.md` §AchievementManager.
+Depende de: constantes `TYPE_*` (abaixo).
+Disponível em: Todos.
+
+### Descrição
 
-**Coleção MongoDB:** `action`
-**Classe:** `com.funifier.engine.action.Action`
+Representa qualquer conquista do jogador: pontos ganhos, desafios completados, itens comprados, níveis alcançados, sorteios e competições. Coleção `achievement`, classe `com.funifier.engine.achievement.Achievement`.
 
-Definição de um tipo de ação.
+### Uso
 
 ```java
-// Campos principais
-String _id;       // ID da ação (ex: "sell")
-String action;    // Nome da ação (ex: "Sell")
-boolean active;   // Se está ativa
-List<ActionAttribute> attributes; // Definição dos atributos (name, type)
+String _id;                  // ID da conquista — em Groovy: .id
+String player;               // ID do jogador
+double total;                // Quantidade (pontos, unidades)
+int type;                    // Tipo — ver tabela de constantes
+String item;                 // ID do item (point_category, challenge, catalog_item, level)
+Date time;                   // Data da conquista
+Map<String, Object> extra;   // Campos extras (ex: origem da conquista)
 ```
 
 ```json
-{"_id": "sell", "action": "Sell", "attributes": [{"name": "product", "type": "String"}, {"name": "price", "type": "Number"}], "active": true}
+{"_id": "64a5d2", "player": "john", "total": 25.0, "type": 0, "item": "xp", "time": {"$date": "2023-07-05T20:57:33.303Z"}}
 ```
 
+**Constantes de tipo** (lista reconciliada — `0`–`3` da classe Java; `5`/`9` confirmadas em `trigger-examples.md`):
+
+| Constante Java | Valor `int` | Significado |
+|---|---|---|
+| `Achievement.TYPE_POINT` | `0` | Ponto acumulado |
+| `Achievement.TYPE_CHALLENGE` | `1` | Desafio completado |
+| `Achievement.TYPE_VIRTUAL_GOOD` | `2` | Item de catálogo comprado |
+| `Achievement.TYPE_LEVEL` | `3` | Nível alcançado |
+| `Achievement.TYPE_LOTTERY` | `5` | Sorteio |
+| `Achievement.TYPE_COMPETITION` | `9` | Competição |
+
+### Armadilhas conhecidas
+
+- **Comparar `entity.type` com literal inteiro** → frágil. Use a constante (`entity.type == Achievement.TYPE_POINT`).
+- **Criar `Achievement` sem `_id`/`time`** → registro inconsistente. Correção: `a.id = Guid.newShortGuid(); a.time = new Date();` (`java-libraries.md` §Guid).
+- **Assumir só os tipos 0–3** → tipos `5` (lottery) e `9` (competition) também ocorrem; trate o `default`.
+
 ---
 
-### Challenge
+## 4. ActionLog
+
+Quando usar: ao ler o `entity` de um trigger de `action`, ou registrar uma ação programaticamente.
+Não usar quando: precisar disparar a ação (track) → `java-managers.md` §ActionManager.
+Depende de: `Action` (definição correspondente, §5).
+Disponível em: Todos.
 
-**Coleção MongoDB:** `challenge`
-**Classe:** `com.funifier.engine.challenge.Challenge`
+### Descrição
 
-Definição de um desafio.
+Registro de uma ação executada por um jogador. Coleção `action_log`, classe `com.funifier.engine.action.ActionLog`. É o `entity` recebido em triggers de `action`.
+
+### Uso
 
 ```java
-// Campos principais
-String _id;          // ID do desafio
-String challenge;    // Nome do desafio
-boolean active;      // Se está ativo
-List<Rule> rules;    // Regras (ação, operador, total)
-List<Reward> points; // Recompensas (pontos, operação)
+String _id;                       // ID do log — em Groovy: .id
+String actionId;                  // ID da ação (ex: "sell")
+String userId;                    // ID do jogador
+Date time;                        // Momento da execução
+Map<String, Object> attributes;   // Atributos da ação (ex: product, price)
 ```
 
 ```json
-{"_id": "DTo8dS3", "challenge": "Watch Video", "active": true, "rules": [{"actionId": "watch_video", "operator": 5, "total": 0}], "points": [{"total": 10.0, "category": "xp", "operation": 0}]}
+{"_id": "64a5d92", "actionId": "sell", "userId": "john", "time": {"$date": "2023-07-05T20:57:33.303Z"}, "attributes": {"product": "book", "price": 120}}
 ```
 
+### Armadilhas conhecidas
+
+- **`log._id = Guid.newShortGuid()` em Groovy** → não atribui. Use `log.id` (§1.5; confirmado em `trigger-examples.md`).
+- **Ler `attributes` de chave inexistente** → `null`. Correção: `String.valueOf(entity.attributes.get("k"))` e checar `"null"`.
+
 ---
 
-### CatalogItem
+## 5. Action
+
+Quando usar: ao consultar a definição de um tipo de ação (atributos esperados, se está ativa).
+Não usar quando: precisar do registro de execução → ActionLog (§4).
+Depende de: `ActionAttribute` (lista `attributes`).
+Disponível em: Todos.
 
-**Coleção MongoDB:** `catalog_item`
-**Classe:** `com.funifier.engine.catalog.CatalogItem`
+### Descrição
 
-Item da loja virtual.
+Definição de um tipo de ação que jogadores podem executar. Coleção `action`, classe `com.funifier.engine.action.Action`.
+
+### Uso
 
 ```java
-// Campos principais
-String _id;           // ID do item
-String catalogId;     // ID do catálogo
-String name;          // Nome do item
-int amount;           // Quantidade disponível
-boolean active;       // Se está ativo
-Requirement[] requires; // Requisitos para compra (pontos necessários)
+String _id;                          // ID da ação (ex: "sell")
+String action;                       // Nome (ex: "Sell")
+boolean active;                      // Se está ativa
+List<ActionAttribute> attributes;    // Definição dos atributos (name, type)
 ```
 
 ```json
-{"_id": "prd1", "catalogId": "gifts", "name": "T-shirt", "amount": 100, "active": true, "requires": [{"total": 15, "type": 0, "item": "coin", "operation": 1}]}
+{"_id": "sell", "action": "Sell", "attributes": [{"name": "product", "type": "String"}, {"name": "price", "type": "Number"}], "active": true}
 ```
 
----
+### Armadilhas conhecidas
 
-### Team
+- **Confundir `Action` (definição) com `ActionLog` (execução)** → coleções e propósitos distintos. `action.attributes` é a *especificação*; `actionLog.attributes` são os *valores*.
 
-**Coleção MongoDB:** `team`
-**Classe:** `com.funifier.engine.team.Team`
+---
 
-```java
-String _id;     // ID da equipe
-String name;    // Nome da equipe
-```
+## 6. Challenge
 
----
+Quando usar: ao ler regras/recompensas de um desafio.
+Não usar quando: precisar criar/atualizar desafios → `java-managers.md` §ChallengeManager.
+Depende de: `Rule`, `Reward`.
+Disponível em: Todos.
+
+### Descrição
 
-### Level
+Definição de um desafio: regras de ação que o completam e recompensas concedidas. Coleção `challenge`, classe `com.funifier.engine.challenge.Challenge`.
 
-**Coleção MongoDB:** `level`
-**Classe:** `com.funifier.engine.level.Level`
+### Uso
 
 ```java
-String _id;     // ID do nível
-String level;   // Nome do nível
-int position;   // Posição (ordem)
+String _id;            // ID do desafio
+String challenge;      // Nome
+boolean active;        // Se está ativo
+List<Rule> rules;      // Regras (actionId, operator, total)
+List<Reward> points;   // Recompensas (total, category, operation)
 ```
 
----
-
-### PointCategory
+```json
+{"_id": "DTo8dS3", "challenge": "Watch Video", "active": true, "rules": [{"actionId": "watch_video", "operator": 5, "total": 0}], "points": [{"total": 10.0, "category": "xp", "operation": 0}]}
+```
 
-**Coleção MongoDB:** `point_category`
-**Classe:** `com.funifier.engine.point.PointCategory`
+### Armadilhas conhecidas
 
-```java
-String _id;       // ID da categoria (ex: "xp")
-String category;  // Nome (ex: "Experience Points")
-String shortName; // Abreviação (ex: "XP")
-Map extra;        // Campos extras
-```
+- **Editar `rules`/`points` direto via `/v3/database`** → `challenge` é nativa; use `ChallengeManager` ou `/v3/challenge`.
 
 ---
 
-### Lottery
+## 7. CatalogItem
 
-**Coleção MongoDB:** `lottery`
-**Classe:** `com.funifier.engine.lottery.Lottery`
+Quando usar: ao ler campos de um item de loja (preço, estoque, requisitos).
+Não usar quando: precisar processar compra → `java-managers.md` §CatalogManager.
+Depende de: `Requirement` (campo `requires`).
+Disponível em: Todos.
 
-```java
-String _id;     // ID do sorteio
-String title;   // Título
-boolean active; // Se está ativo
-```
+### Descrição
 
----
+Item da loja virtual. Coleção `catalog_item`, classe `com.funifier.engine.catalog.CatalogItem`.
 
-### LotteryTicket
-
-**Coleção MongoDB:** `lottery_ticket`
-**Classe:** `com.funifier.engine.lottery.LotteryTicket`
+### Uso
 
 ```java
-String _id;      // ID do ticket
-String lottery;  // ID do sorteio
-String player;   // ID do jogador
+String _id;                 // ID do item
+String catalogId;           // ID do catálogo
+String name;                // Nome
+int amount;                 // Quantidade disponível
+boolean active;             // Se está ativo
+Requirement[] requires;     // Requisitos para compra (total, type, item, operation)
 ```
 
----
-
-### MysteryBox
+```json
+{"_id": "prd1", "catalogId": "gifts", "name": "T-shirt", "amount": 100, "active": true, "requires": [{"total": 15, "type": 0, "item": "coin", "operation": 1}]}
+```
 
-**Coleção MongoDB:** `mystery_box`
-**Classe:** `com.funifier.engine.mystery.MysteryBox`
+### Armadilhas conhecidas
 
-```java
-String _id;     // ID da caixa
-String title;   // Título
-boolean active; // Se está ativa
-```
+- **Comprar ignorando `requires`** → use `CatalogManager.isValid(...)`/`findMissingRequirements(...)` antes (`java-managers.md`).
 
 ---
 
-### Competition
-
-**Coleção MongoDB:** `competition`
-**Classe:** `com.funifier.engine.competition.Competition`
+## 8. Entidades de Configuração (Point, Level, Team)
 
-```java
-String _id;     // ID da competição
-boolean active; // Se está ativa
-```
+Quando usar: ao ler campos de categorias de ponto, níveis ou equipes.
+Não usar quando: precisar dos métodos correspondentes → `java-managers.md` (§PointManager, §LevelManager, §TeamManager).
+Depende de: —
+Disponível em: Todos.
 
----
+### Descrição
 
-### Question
+Entidades de configuração das mecânicas. Estruturas simples, manipuladas majoritariamente via managers.
 
-**Coleção MongoDB:** `question`
-**Classe:** `com.funifier.engine.question.Question`
+### Uso
 
+**PointCategory** — coleção `point_category`, classe `com.funifier.engine.point.PointCategory`
 ```java
-String _id;      // ID da pergunta
-String question; // Texto da pergunta
+String _id;        // ID da categoria (ex: "xp")
+String category;   // Nome (ex: "Experience Points")
+String shortName;  // Abreviação (ex: "XP")
+Map extra;         // Campos extras
 ```
 
----
-
-### QuestionLog
-
-**Coleção MongoDB:** `question_log`
-**Classe:** `com.funifier.engine.question.QuestionLog`
+**Level** — coleção `level`, classe `com.funifier.engine.level.Level`
+```java
+String _id;       // ID do nível
+String level;     // Nome do nível
+int position;     // Posição (ordem)
+```
 
+**Team** — coleção `team`, classe `com.funifier.engine.team.Team`
 ```java
-String _id;      // ID do log
-String player;   // ID do jogador
-String question; // ID da pergunta
+String _id;       // ID da equipe
+String name;      // Nome
 ```
 
+### Armadilhas conhecidas
+
+- **Associar jogador a equipe escrevendo `player.teams` direto** → use `TeamManager.linkUser(...)`, que mantém os índices de associação (`java-managers.md`).
+
 ---
 
-### Quiz / QuizLog
+## 9. Entidades de Engajamento
 
-**Coleções:** `quiz` / `quiz_log`
+Quando usar: ao ler os campos básicos de mecânicas de engajamento.
+Não usar quando: precisar executá-las (sortear, abrir caixa, premiar) → managers correspondentes em `java-managers.md`.
+Depende de: managers de cada mecânica.
+Disponível em: Todos.
 
----
+### Descrição
+
+Entidades das mecânicas de engajamento. Os documentos abaixo expõem apenas campos básicos; a lógica de execução vive nos managers.
 
-### Notification
+### Uso
 
-**Coleção MongoDB:** `notification`
-**Classe:** `com.funifier.engine.notify.Notification`
+| Entidade | Coleção | Classe | Campos básicos |
+|---|---|---|---|
+| Lottery | `lottery` | `com.funifier.engine.lottery.Lottery` | `_id`, `title`, `active` |
+| LotteryTicket | `lottery_ticket` | `com.funifier.engine.lottery.LotteryTicket` | `_id`, `lottery`, `player` |
+| MysteryBox | `mystery_box` | `com.funifier.engine.mystery.MysteryBox` | `_id`, `title`, `active` |
+| Competition | `competition` | `com.funifier.engine.competition.Competition` | `_id`, `active` |
+| Question | `question` | `com.funifier.engine.question.Question` | `_id`, `question` |
+| QuestionLog | `question_log` | `com.funifier.engine.question.QuestionLog` | `_id`, `player`, `question` |
+| Quiz / QuizLog | `quiz` / `quiz_log` | — | — |
+| Swap | `swap` | `com.funifier.engine.swap.Swap` | — |
+| Notification | `notification` | `com.funifier.engine.notify.Notification` | `_id`, `player`, `title`, `message`, `time` |
 
 ```java
-String _id;     // ID da notificação
-String player;  // ID do jogador destino
-String title;   // Título
-String message; // Mensagem
-Date time;      // Data
+// Notification — exemplo dos campos principais
+String _id;       // ID da notificação
+String player;    // ID do jogador destino
+String title;     // Título
+String message;   // Mensagem
+Date time;        // Data
 ```
 
----
+### Armadilhas conhecidas
 
-### Swap
-
-**Coleção MongoDB:** `swap`
-**Classe:** `com.funifier.engine.swap.Swap`
+> ⚠️ Documentação pendente: os campos completos de `Quiz`/`QuizLog` e `Swap` não estão detalhados nas fontes atuais. Consultar a API (`GET /v3/database/collections` + `?strict=true`) para inspecionar o documento real antes de manipular.
 
 ---
 
-### Trigger
+## 10. Entidades de Infraestrutura
 
-**Coleção MongoDB:** `trigger`
-**Classe:** `com.funifier.engine.integration.trigger.Trigger`
+Quando usar: ao ler/inspecionar configurações de trigger, scheduler, public endpoint ou webhook.
+Não usar quando: precisar da mecânica de execução desses recursos → `modules/trigger.md`, `modules/scheduler.md`, `modules/public.md`, `modules/webhook.md`.
+Depende de: —
+Disponível em: Todos.
 
-```java
-String _id;      // ID da trigger
-String name;     // Nome
-String entity;   // Entidade (ex: "player", "achievement")
-String event;    // Evento (ex: "before_create", "after_win")
-String script;   // Código Java
-```
+### Descrição
 
----
+Entidades que representam os próprios recursos de extensão da plataforma (são persistidas e configuradas via Studio/API).
 
-### SchedulerConfig
+### Uso
 
-**Coleção MongoDB:** `scheduler`
-**Classe:** `com.funifier.engine.integration.scheduler.SchedulerConfig`
+**Trigger** — coleção `trigger`, classe `com.funifier.engine.integration.trigger.Trigger`
+```java
+String _id;       // ID da trigger
+String name;      // Nome
+String entity;    // Entidade (ex: "player", "achievement")
+String event;     // Evento (ex: "before_create", "after_win")
+String script;    // Código Java/Groovy
+```
 
----
+| Entidade | Coleção | Classe |
+|---|---|---|
+| SchedulerConfig | `scheduler` | `com.funifier.engine.integration.scheduler.SchedulerConfig` |
+| PublicEndpoint | `public_endpoint` | `com.funifier.engine.pub.PublicEndpoint` |
+| Webhook | `webhook` | `com.funifier.engine.webhook.Webhook` |
 
-### PublicEndpoint
+### Armadilhas conhecidas
 
-**Coleção MongoDB:** `public_endpoint`
-**Classe:** `com.funifier.engine.pub.PublicEndpoint`
+- **Atualizar uma Trigger/PublicEndpoint via `POST` parcial** → o `script` pode ser apagado (full replace). Ver a restrição de upsert completo em `patterns.md` §1.5.
 
 ---
 
-### Webhook
+## 11. Mapeamento Completo Entidade → Coleção
 
-**Coleção MongoDB:** `webhook`
-**Classe:** `com.funifier.engine.webhook.Webhook`
+Quando usar: para localizar a coleção MongoDB e a classe Java de qualquer entidade nativa.
+Não usar quando: a coleção é customizada (`__c`) → §12.
+Depende de: —
+Disponível em: Todos.
 
----
-
-## Mapeamento Completo Entidade → Coleção
+### Uso
 
 | Entidade | Coleção MongoDB | Classe Java |
 |----------|----------------|-------------|
@@ -370,4 +426,38 @@ String script;   // Código Java
 | BACKUP | `backup` | Backup |
 | COMPACT | `compact` | Compact |
 
-> **Nota:** Coleções customizadas (Custom Objects) usam o sufixo `__c` (ex: `car__c`, `email__c`) e são acessadas como `HashMap`.
+### Armadilhas conhecidas
+
+- **Coleções de log (`action_log`, `challenge_progress`, `player_status`) não aparecem no dropdown de entidades do Studio** — ver as exclusões em `trigger-examples.md`. Acesse-as por código/`/v3/database`.
+
+---
+
+## 12. Custom Objects (`__c`)
+
+Quando usar: ao criar/manipular estruturas de dados próprias do negócio.
+Não usar quando: a entidade já existe como nativa (§11) → use o endpoint nativo correspondente.
+Depende de: `database-access.md` (CRUD genérico).
+Disponível em: Todos.
+
+### Descrição
+
+Coleções customizadas usam o sufixo `__c` (ex: `car__c`, `email__c`, `signup__c`). São acessadas como `HashMap` em código (não há classe Java tipada) e via `/v3/database/{collection}` na API. O sufixo é apenas convenção sobre o `DatabaseRest` genérico.
+
+### Uso
+
+```java
+// Em trigger/scheduler/endpoint — entity de um __c é um HashMap
+HashMap<String, Object> car = manager.getJongoConnection()
+    .getCollection("car__c")
+    .findOne("{_id:#}", "car001").as(HashMap.class);
+```
+
+```
+POST /v3/database/car__c
+{ "_id": "car001", "name": "Civic", "brand": "Honda", "price": 50000 }
+```
+
+### Armadilhas conhecidas
+
+- **Esperar getters tipados** (`car.getName()`) → é `HashMap`; use `car.get("name")`.
+- **Ler/escrever campos `Date` sem `strict=true`** → tipo degradado (`patterns.md` §9). Detalhe em `database-access.md`.