funifier-mcp 0.2.25 → 0.2.27

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

@@ -1,138 +1,435 @@
-# Point (Ponto)
+# `point`
 
 **Acesso Studio:** `/studio/point`
 **API Endpoint:** `/v3/point`
+**Endpoint Legado:** _(não existe — não há controller de point em `rest/engine`)_
+**Coleção MongoDB:** `point_category` (config). Existe ainda uma coleção `point` de saldos por jogador — **legada/inerte** (vide §3.4 e §7).
 
-## O que é
+---
+
+## 1. Visão Geral
+
+O módulo `point` é o **catálogo de tipos de ponto** de uma gamificação. Cada documento define um "tipo de moeda" do jogo — XP, Karma, Coins, Reputação, etc. — com nome amigável, abreviação, imagem e tags de técnica de jogo.
+
+Papel arquitetural (confirmado no código):
+
+- O módulo `point` armazena **apenas a configuração/metadados** do tipo de ponto na coleção `point_category` (`Entity.java:228` → `POINT_CATEGORY("point_category", PointCategory.class)`). Ele **não** guarda saldo de jogador.
+- O **saldo de pontos do jogador é derivado da coleção `achievement`** (registros `type=0 / TYPE_POINT`, `item=<_id do ponto>`), somando `total` via aggregation. Esta é a fonte da verdade — vide o módulo `achievement`. O `_id` do `PointCategory` é exatamente o valor usado no campo `item` desses achievements.
+- O `PointCategory` é consumido por outros módulos **só para resolver nome/imagem** a partir do `_id`:
+  - `challenge` — `ChallengeManager` (linhas 401, 421, 445) faz `findById(point.category)` para montar a descrição textual da recompensa (`RewardPoint.category` carrega o `_id` do ponto).
+  - `achievement` — `AchievementManager.findOptionsByType` (2841-2843) e `findOptionByTypeAndItem` (2903-2907) resolvem `_id → category/image` para dropdowns do Studio e decoração de respostas.
+  - `package` — `PackageManager` (301, 380, 438, 488) exporta/importa pontos como parte de um pacote (`findAll`, `findById`, `add`, `delete`).
+  - `technique` — `GameTechniqueManager` faz backfill da tag `techniques` e calcula analytics de uso (mapa Octalysis).
+
+Problemas que resolve:
+
+- Declarar os tipos de ponto que existem na gamificação e dar a eles nome de exibição (`category`), abreviação (`shortName`) e imagem.
+- Servir como tabela de lookup `_id → metadados` para os módulos que geram/consomem pontos (challenge, action, achievement, level, leaderboard, catalog).
+
+> ⚠️ **Correção em relação à documentação anterior:** o módulo **não** decide acúmulo, troca ou gasto de pontos. Ele é puramente declarativo. A lógica de crédito/débito/saldo vive em `achievement`. Vide §7 para o detalhamento das funcionalidades que a doc anterior atribuía erroneamente ao campo `techniques`.
+
+---
+
+## 2. Arquitetura e Fluxos
+
+### 2.1 Classes envolvidas
+
+| Classe | Arquivo | Papel |
+|---|---|---|
+| `PointCategory` | `engine/point/PointCategory.java` | **Entidade de config** (documento raiz da coleção `point_category`) |
+| `Point` | `engine/point/Point.java` | Entidade de **saldo por jogador** (coleção `point`) — **legada/inerte**, vide §3.4 |
+| `PointDaoMongo` | `engine/point/PointDaoMongo.java` | DAO Jongo das duas coleções |
+| `PointManager` | `engine/point/PointManager.java` | Manager (delega ao DAO; resolvido via `ManagerFactory.getPointManager()`) |
+| `PointRest` | `rest/v3/rest/PointRest.java` | Controller REST v3 (`@Path("v3/point")`) |
+| `Image` / `ImageItem` | `engine/image/` | Sub-entidade de imagem (small/medium/original) |
+
+Não há `Repository`/`Service` separado — `PointManager` chama `PointDaoMongo` diretamente, que usa `Jongo` sobre a conexão do tenant (`manager.getJongoConnection()`).
+
+### 2.2 Pipeline — CRUD de tipo de ponto (caminho vivo)
+
+Toda chamada REST entra pelo `FrontController.getInstance(authBean.getApiKey())`, que resolve o `ManagerFactory` (e a conexão Mongo) **do tenant dono daquele apiKey**. A partir daí:
+
+```
+GET  /v3/point        → PointRest.findAll  → PointManager.findAll  → PointDaoMongo.findAll(point_category)      → JsonUtil.toJsonRemoveNullFields(list)
+GET  /v3/point/{id}   → PointRest.find     → PointManager.findById → PointDaoMongo.findById(point_category)     → toJsonRemoveNullFields(obj)
+POST /v3/point        → PointRest.insert   → PointManager.add      → PointDaoMongo.add(point_category)          → toJsonRemoveNullFields(obj), 201
+DELETE /v3/point/{id} → PointRest.delete   → PointManager.delete   → PointDaoMongo.delete(point_category)       → 204
+```
+
+Algoritmo de `add` (= o que o POST executa) — `PointDaoMongo.java:44-48`:
+
+```
+se point._id é null OU vazio:
+    point._id = Guid.newShortGuid()        # gera id curto automaticamente
+collection("point_category").save(point)   # Jongo save = upsert por _id
+```
+
+Consequência: **POST é create-or-replace por `_id`** (não há PATCH). Se você enviar um `_id` já existente, o documento é **substituído por inteiro** (full replace), não mesclado. Campos omitidos no body somem do documento.
+
+> Tudo é **síncrono**, sem transação. Não há disparo de trigger/webhook no CRUD de `point` (o módulo não chama `before_win`/`after_win` nem registra `*_created`).
+
+### 2.3 Como um jogador realmente ganha pontos (integração entre módulos)
+
+O módulo `point` só fornece metadados nesse fluxo. O crédito acontece em `achievement`:
+
+### Sequência — jogador ganha pontos
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant ActionMgr as ActionManager
+    participant AchMgr as AchievementManager
+    participant PointCfg as point_category (config)
+    participant Ach as achievement (coleção)
+
+    Client->>ActionMgr: POST /v3/action/log (actionId, userId)
+    ActionMgr->>AchMgr: fireAction(actionLog)
+    Note over AchMgr: avalia RewardPoints da action/challenge
+    AchMgr->>AchMgr: addAchievement(type=0, item=<pointId>, total=N)
+    AchMgr->>Ach: insert { player, type:0, item:<pointId>, total:N }
+    Note over PointCfg: point_category NÃO é alterado<br/>(usado só p/ nome/imagem em respostas)
+    Client->>Ach: saldo = aggregate $match{type:0,item:<pointId>} + $sum:$total
+```
+
+O `point` (config) entra apenas quando a UI precisa exibir o nome/imagem do ponto (`AchievementManager.findOptionByTypeAndItem`, linha 2903). **Mudar um `PointCategory` não recalcula nada** — apenas troca o rótulo exibido dali pra frente.
+
+---
+
+## 3. Estrutura dos Objetos
+
+### 3.1 `PointCategory` — documento raiz (coleção `point_category`)
+
+Definição: `engine/point/PointCategory.java`. Anotada com `@JsonIgnoreProperties(ignoreUnknown=true)` (linha 11) — **campos desconhecidos no POST são silenciosamente ignorados**.
+
+| Campo | Tipo | Padrão | Obrigatório | Descrição |
+|---|---|---|---|---|
+| `_id` | String | auto (GUID curto se vazio) | não* | Identificador do ponto. Mapeado de `_id` via `@JsonProperty`. Se ausente/vazio no POST, `add()` gera `Guid.newShortGuid()`. |
+| `category` | String | null | recomendado | Nome amigável exibido nas interfaces (ex.: `"Experience Points"`). |
+| `shortName` | String | null | recomendado | Abreviação curta (ex.: `"XP"`). |
+| `image` | `Image` | null | não | Imagem do ponto (3 tamanhos — §3.2). |
+| `extra` | `Map<String,Object>` | `{}` (HashMap vazio) | não | Campos customizados livres. Inicializado como mapa vazio, não null. |
+| `techniques` | `List<String>` | null | não | Tags de técnica de jogo (códigos GT). **Apenas categorização** — vide §3.3 e §7. |
+
+\* Nenhum campo é validado como obrigatório no servidor. O `add()` aceita `category`/`shortName` nulos sem erro. **Não há validação de formato do `_id`** (espaços e maiúsculas não são rejeitados pelo backend — "minúsculas sem espaços" é convenção, não regra de código).
+
+#### Campos legados / silenciosamente ignorados
+
+- **`icon` (String)** — declarado em `PointCategory.java:19`, mas getter/setter estão **comentados** (linhas 62-70) e o campo é package-private. Com a visibilidade padrão do Jackson (apenas getters/setters/atributos públicos), o **REST não desserializa `icon`** mesmo que você o envie no POST — o valor permanece `null`. É um campo morto, resquício de versão antiga (substituído por `image`).
+- **`apiKey`** — havia um campo `apiKey` na entidade (comentado em `PointCategory.java:16,32`). Não existe mais. Se enviado no POST, cai na regra `ignoreUnknown=true` e é descartado.
+
+#### Comportamento de serialização da resposta
+
+Todas as respostas passam por `JsonUtil.toJsonRemoveNullFields(...)` (`PointRest.java:42,60,93`): **campos `null` são removidos do JSON de resposta**. Logo, um ponto sem `image`/`techniques` retorna sem essas chaves. O `extra` (mapa vazio, não null) tende a aparecer como `{}`.
+
+### 3.2 `Image` / `ImageItem` — sub-entidade de imagem
+
+`Image` (`engine/image/Image.java`) tem três variações de tamanho, cada uma um `ImageItem`:
+
+| Campo de `Image` | Tipo |
+|---|---|
+| `small` | `ImageItem` |
+| `medium` | `ImageItem` |
+| `original` | `ImageItem` |
+
+`ImageItem` (`engine/image/ImageItem.java`):
+
+| Campo | Tipo | Observação |
+|---|---|---|
+| `_id` | String | id do arquivo (usado em operações de upload/exclusão) |
+| `type` | String | |
+| `name` | String | |
+| `url` | String | URL pública da imagem |
+| `size` | int | default 0 |
+| `width` | int | default 0 |
+| `height` | int | default 0 |
+| `depth` | int | default 0 |
+| `format` | String | |
+
+Na prática basta preencher `url` nos três tamanhos. Os campos numéricos default `0` são aceitos.
+
+### 3.3 Técnicas de jogo (`techniques`)
+
+`techniques` é uma `List<String>` livre de **códigos GT** (catálogo Octalysis). O catálogo-mestre fica em `system/technique/GameTechniqueManager.java`. Os códigos relevantes para pontos:
+
+| Código | Nome (catálogo) | Core Drive | Descrição (pt) |
+|---|---|---|---|
+| `GT01` | Status Points | CD2 (Desenvolvimento & Realização) | "Unidades de medição do status do jogador. Pontos de consumo podem ser usados para comprar coisas." (`GameTechniqueManager.java:130`) |
+| `GT75` | Exchangeable Points | CD4 (Posse & Propriedade) | "Pontos que podem ser trocados e podem fazer rodar a economia." (`GameTechniqueManager.java:204`) |
+
+**Como `techniques` é preenchido (backfill automático):** `engine/technique/GameTechniqueManager.autoConfigureMissingTechniqueFields()` procura documentos em `point_category` **sem techniques** (query `notechniques`, linha 63: `techniques` ausente OU array vazio) e adiciona **apenas `GT01`** (linhas 67, 78-87). **`GT75` nunca é atribuído automaticamente.**
+
+**O que `techniques` realmente faz:** serve só de **tag de categorização** para o mapa de técnicas do Studio (`GameTechniqueManager.findConfiguredTechniques` agrega o uso por técnica/core-drive). **Não há nenhum efeito comportamental no módulo `point`** — vide §7.
+
+### 3.4 `Point` — saldo por jogador (coleção `point`) — LEGADO
+
+`engine/point/Point.java`. Documento da coleção `point` (constante `PointDaoMongo.COLLECTION = "point"`, linha 10), distinta de `point_category`.
+
+| Campo | Tipo | Descrição |
+|---|---|---|
+| `_id` | String | GUID curto (gerado em `creditPoints`/`debitPoints`) |
+| `categoryId` | String | id do `PointCategory` |
+| `category` | String | nome da categoria (copiado de `PointCategory.getCategory()`) |
+| `userId` | String | jogador dono do saldo |
+| `points` | int | pontos obtidos (acumulado) — só incrementado em `creditPoints` |
+| `balance` | int | saldo disponível para troca — incrementado no crédito, decrementado no débito |
+
+> **Esta coleção/entidade é inerte no engine atual.** Os métodos que a manipulam (`creditPoints`, `debitPoints`, `transferPoints`, `findByUserId`) **não têm nenhum chamador** (vide §7). O saldo real do jogador vem de `achievement`, não daqui. A classe `Point` é apenas **exposta a scripts server-side** (Groovy/Java) via `import com.funifier.engine.point.Point` injetado pelos runners (`TriggerRunner`, `SchedulerRunner`, `AuthRunner`, `LastMileManager`, `CsvManager`, `PublicManager`, `PreparedManager`, `WebSocketManager`) — mas o core nunca a usa.
+
+---
+
+## 4. Endpoints
+
+Controller: `PointRest` (`@Path("v3/point")`, `@Produces(application/json; charset=UTF-8)`). Todos exigem `Authorization: Bearer <token>`.
+
+### `GET /v3/point`
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Lista todos os tipos de ponto (`point_category`) do tenant |
+| Autenticação | Bearer token |
+| Resposta | Array de `PointCategory`, campos null removidos |
+| Código | 200 |
+
+### `GET /v3/point/{id}`
+
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Busca um tipo de ponto por `_id` |
+| Autenticação | Bearer token |
+| Resposta | Objeto `PointCategory` (null se inexistente) |
+| Código | 200 |
+
+**Path params:**
 
-Configuração dos diferentes tipos de pontuação que os jogadores podem conquistar. Os pontos são fundamentais para recompensar ações, mensurar desempenho e alimentar rankings, lojas virtuais e desafios.
+| Param | Tipo | Descrição |
+|---|---|---|
+| `id` | String | `_id` do ponto |
+
+> Observação: o apidoc inline desse método está rotulado como "Find Action" (`PointRest.java:48`) — é erro de copy-paste; o método retorna `PointCategory`.
 
-## Os dois tipos de ponto
+### `POST /v3/point`
 
-A escolha da técnica (`techniques`) define o comportamento do ponto no sistema:
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Cria **ou substitui** um tipo de ponto |
+| Autenticação | Bearer token |
+| Full replace ou patch | **Full replace** por `_id` (Jongo `save`). Não é patch. |
+| Resposta | O `PointCategory` salvo (com `_id` gerado, se aplicável) |
+| Código | 201 CREATED |
 
-### Ponto Normal — `GT01`
+**Comportamento real:**
+- `_id` ausente/vazio ⇒ GUID curto gerado automaticamente.
+- `_id` presente ⇒ upsert: substitui o documento inteiro. Campos omitidos são apagados.
+- Campos desconhecidos no body ⇒ ignorados (`@JsonIgnoreProperties`).
+- `icon` no body ⇒ ignorado (sem setter público — §3.1).
+- Sem validação de obrigatoriedade ou de formato de `_id`.
 
-Pontos de progressão acumulativa. Usados para XP, score, karma, métricas de desempenho. Ambos os tipos podem ser usados na loja virtual.
+**Exemplo:**
 
 ```json
+POST /v3/point
 {
   "_id": "xp",
   "category": "Experience Points",
-  "shortName": "XP",
-  "techniques": ["GT01"]
+  "shortName": "XP"
 }
 ```
 
-Use quando: o ponto representa progresso, conquista ou ranking.
+### `DELETE /v3/point/{id}`
 
-### Ponto Trocável entre jogadores — `GT75`
+| Aspecto | Detalhe |
+|---|---|
+| Finalidade | Remove o tipo de ponto da coleção `point_category` |
+| Autenticação | Bearer token |
+| Código | 204 NO_CONTENT |
 
-Pontos que podem ser transferidos entre jogadores (troca/presente entre usuários). Usados para moedas sociais, tokens de reconhecimento entre pares.
+**Comportamento real:** remove apenas o documento de `point_category`. **Não** remove achievements (`type=0, item=<id>`) já gerados, nem referências em `challenge`/`action`/`level`. O histórico/saldo derivado do ponto **continua existindo** em `achievement` após o delete.
 
-```json
-{
-  "_id": "coin",
-  "category": "Coins",
-  "shortName": "Coins",
-  "techniques": ["GT75"]
-}
-```
+> **Não existe `PUT`/`PATCH`.** O método `PointManager.update()` (remove-then-save full replace, `PointDaoMongo.java:50-54`) **não é exposto por nenhum endpoint** e não tem chamadores — é código morto (§7).
 
-Use quando: jogadores podem enviar ou transferir pontos uns para os outros.
+---
+
+## 5. Regras de Negócio
+
+Regras presentes no código mas ausentes do schema:
+
+- **`_id` como chave de negócio:** o `_id` do ponto é o identificador usado em todos os outros módulos: `RewardPoint.category` (recompensa de action/challenge), `Requirement.item` (custo na loja), `achievement.item` (lançamento de saldo), `levelConfig.pointCategory` e `level.point` (gatilho de level up). Renomear/excluir um ponto **quebra silenciosamente** essas referências por id.
+- **Saldo é eventual e calculado:** não há campo de saldo no módulo `point`. Qualquer total é uma aggregation sobre `achievement` (consistência eventual; sem cache no módulo).
+- **Multi-tenant rígido por apiKey:** cada requisição opera sobre a base do tenant resolvido por `FrontController.getInstance(apiKey)`. Pontos de um projeto nunca enxergam os de outro. Não há isolamento adicional por usuário dentro do tenant — qualquer token válido do tenant pode listar/criar/excluir pontos (não há checagem de role no `PointRest`).
+- **POST destrutivo:** por ser full-replace, reenviar um ponto sem um campo previamente salvo o remove. Para "editar", releia o objeto, altere e reenvie completo.
+- **`techniques` não é regra de negócio:** apesar de `GT01`/`GT75` sugerirem comportamentos distintos, o módulo trata `techniques` como lista opaca de tags. Não há ramificação de lógica por técnica.
 
 ---
 
-**Regra:** se jogadores podem transferir/trocar o ponto entre si, use `GT75`. Para tudo o mais, use `GT01`. Qualquer tipo de ponto pode ser usado na loja virtual.
+## 6. Comportamentos Automáticos
 
-## Imagem
+| Comportamento | Trigger | Impacto | Persistência |
+|---|---|---|---|
+| Geração de `_id` | POST com `_id` vazio | `Guid.newShortGuid()` gravado como `_id` | `point_category` |
+| Upsert/full-replace | POST com `_id` existente | Documento substituído por inteiro | `point_category` |
+| Remoção de campos null na resposta | Qualquer GET/POST | `JsonUtil.toJsonRemoveNullFields` | — (só resposta) |
+| Descarte de campos desconhecidos | POST | `@JsonIgnoreProperties(ignoreUnknown=true)` | — |
+| Backfill de `techniques=["GT01"]` | Rotina de manutenção `autoConfigureMissingTechniqueFields()` | Adiciona `GT01` a pontos sem techniques + grava `game_technique_field` | `point_category`, `game_technique_field` |
 
-Points podem ter uma imagem associada via campo `image` com três tamanhos:
+> Não há comportamento encadeado de behaviors/triggers no CRUD de point. O backfill de techniques é uma rotina administrativa do sistema, não disparada pelo CRUD.
+
+---
+
+## 7. Suportado vs NÃO Suportado
+
+### ✅ Suportado
+
+- CRUD de tipos de ponto via `/v3/point` (list, find, create/replace, delete).
+- Geração automática de `_id` quando omitido.
+- Imagem em 3 tamanhos (`image.small/medium/original`).
+- Campos customizados via `extra`.
+- Tag de técnica `techniques` (categorização para o mapa Octalysis do Studio).
+- Uso do `_id` do ponto como referência por outros módulos (challenge, action, achievement, level, leaderboard, catalog, package).
+- Crédito de pontos ao jogador via `achievement` (feito pelo módulo `achievement`, não por este).
+
+### ❌ NÃO Suportado
+
+- **Transferência de pontos entre jogadores (player-to-player).** `PointManager.transferPoints` (linhas 26-38) existe, mas tem **zero chamadores** — não é exposto por REST nem chamado por nenhum manager. É código morto.
+- **Crédito/débito direto de saldo (`creditPoints`/`debitPoints`).** Existem em `PointManager`/`PointDaoMongo` (18-42) mas **sem chamadores no engine**. A chamada que os usaria em compras está **comentada** em `PurchaseManager.java:115` (`//manager.getPointManager().debitPoints(...)`) — evidência de que o sistema de saldo na coleção `point` foi **descontinuado** em favor da aggregation de `achievement`.
+- **A coleção `point` (entidade `Point`) como fonte de saldo.** Inerte no core; apenas importável em scripts customizados.
+- **`PUT`/`PATCH` (edição parcial).** Não há endpoint. POST é full-replace. `PointManager.update()` é código morto (zero chamadores).
+- **Endpoint legado `/2.0.0/point`.** Não existe controller de point em `rest/engine`.
+- **Campo `icon`.** Aceito no schema da classe, mas o REST não o desserializa (sem setter público) — sempre `null`.
+- **Validação de `_id`/campos obrigatórios.** O backend não rejeita `_id` com espaços/maiúsculas nem `category`/`shortName` ausentes.
+
+> ### Correção importante sobre `techniques` (GT01 × GT75)
+>
+> A documentação anterior afirmava: _"se jogadores podem transferir/trocar o ponto entre si, use `GT75`; para o resto use `GT01`; qualquer ponto pode ser usado na loja"_. Confrontando com o código:
+>
+> - `GT75` ("Exchangeable Points", CD4) **é uma técnica real do catálogo** (`system/technique/GameTechniqueManager.java:204`) — não foi inventada. Mas **marcar um ponto com `GT75` não habilita transferência alguma**: o mecanismo de troca (`transferPoints`) é código morto.
+> - `techniques` **não altera o comportamento do módulo point**. É só tag de analytics/Octalysis. Não existe ramificação de lógica por GT no engine de pontos.
+> - O **gasto na loja** funciona para **qualquer ponto**, independente de `techniques`, via `Requirement` com `OPERATION_DEDUCT` em `catalog_item` (gera achievement negativo). Não é o `GT75` que "habilita a loja".
+> - O backfill automático só aplica `GT01`. Um ponto sem técnica recebe `GT01` ("Status Points").
+>
+> **Conclusão:** trate `techniques` como rótulo descritivo opcional. Não dependa dele para nenhum comportamento.
+
+---
+
+## 8. Segurança e Permissões
+
+- **Autenticação:** `Authorization: Bearer <token>` em todos os métodos (`@BeanParam AuthBean`).
+- **Isolamento por tenant:** `FrontController.getInstance(authBean.getApiKey())` direciona toda operação à base do tenant dono do apiKey. Não há vazamento entre projetos.
+- **Autorização intra-tenant:** o `PointRest` **não** faz checagem de papel/escopo — qualquer token válido do tenant pode criar e **excluir** tipos de ponto. Operações de escrita devem ser restritas a tokens administrativos por convenção operacional (não há enforcement no controller).
+- **Superfície de injeção:** as queries Mongo do módulo são **parametrizadas** via placeholders Jongo (`"{_id:#}"`, `"{userId:#}"`, `"{categoryId:#, userId:#}"`) — sem concatenação de string com input do usuário. Não há superfície de injeção NoSQL no módulo `point` em si. (Atenção: aggregations livres do tenant via `/v3/database/...` são outra superfície, fora deste módulo.)
+- **DELETE não-transacional e sem cascata:** excluir um ponto não limpa referências; pode deixar challenges/levels apontando para um `_id` inexistente (NPE potencial em `ChallengeManager` ao montar descrição — `cat.getCategory()` com `cat == null`).
+
+---
+
+## 9. Observabilidade e Troubleshooting
+
+### Diagnóstico rápido
 
-```json
-"image": {
-  "small":    { "url": "https://...", "size": 0, "width": 0, "height": 0, "depth": 0 },
-  "medium":   { "url": "https://...", "size": 0, "width": 0, "height": 0, "depth": 0 },
-  "original": { "url": "https://...", "size": 0, "width": 0, "height": 0, "depth": 0 }
-}
 ```
+# O ponto existe?
+GET /v3/point/<id>
 
-Na prática basta preencher `url` nos três tamanhos com a mesma URL se não houver versões distintas.
+# Listar todos os tipos de ponto do projeto
+GET /v3/point
+```
 
-## Campos
+### Saldo do jogador (vem de achievement, não de point)
 
-| Campo | Obrigatório | Descrição |
-|---|---|---|
-| `_id` | sim | Identificador único — minúsculas, sem espaços (`xp`, `coin`, `karma`) |
-| `category` | sim | Nome amigável exibido na interface |
-| `shortName` | sim | Abreviação curta exibida em rankings e conquistas |
-| `techniques` | sim | `["GT01"]` para normal, `["GT75"]` para trocável |
-| `extra` | não | Campos customizados livres |
+```
+# Total de um ponto para um jogador (fonte da verdade)
+POST /v3/database/achievement/aggregate
+[
+  { "$match": { "player": "<userId>", "type": 0, "item": "<pointId>" } },
+  { "$group": { "_id": null, "total": { "$sum": "$total" } } }
+]
+```
 
-## Exemplos completos
+### Investigações úteis
+
+```
+# Quais challenges referenciam este ponto (antes de excluir)?
+POST /v3/database/challenge/aggregate
+[ { "$match": { "points.category": "<pointId>" } } ]
+
+# Algum level usa este ponto como gatilho?
+POST /v3/database/level/aggregate
+[ { "$match": { "point": "<pointId>" } } ]
+
+# Conferir/limpar a coleção legada de saldos (deveria estar vazia/inerte)
+POST /v3/database/point/aggregate
+[ { "$match": { "categoryId": "<pointId>" } } ]
+```
+
+### Erros comuns e causas
+
+| Sintoma | Causa provável |
+|---|---|
+| "Editei um ponto e sumiram campos" | POST é full-replace — releia, altere, reenvie completo. |
+| "Mandei `icon` e não persistiu" | `icon` é campo morto, não desserializado. Use `image`. |
+| "Marquei `GT75` e os pontos não transferem" | Transferência é código morto; `techniques` não muda comportamento (§7). |
+| "Saldo não bate com o esperado" | Saldo vem de `achievement` (`type:0,item:<id>`), não do módulo point. Verifique os lançamentos. |
+| "Excluí o ponto e o ranking quebrou" | DELETE não faz cascata; challenges/levels ficam apontando para `_id` inexistente. |
+| Resposta sem `techniques`/`image` | Campos null são removidos pelo `toJsonRemoveNullFields`; não significa erro. |
+
+---
+
+## 10. Exemplos Práticos
+
+### Mínimo funcional
 
-**XP (ponto normal):**
 ```json
+POST /v3/point
 {
   "_id": "xp",
   "category": "Experience Points",
-  "shortName": "XP",
-  "techniques": ["GT01"],
-  "extra": {}
+  "shortName": "XP"
 }
 ```
 
-**Coin (ponto trocável):**
+### Avançado (todos os campos relevantes)
+
 ```json
+POST /v3/point
 {
   "_id": "coin",
   "category": "Coins",
-  "shortName": "Coins",
+  "shortName": "C$",
+  "image": {
+    "small":    { "url": "https://cdn.exemplo.com/coin.png" },
+    "medium":   { "url": "https://cdn.exemplo.com/coin.png" },
+    "original": { "url": "https://cdn.exemplo.com/coin.png" }
+  },
   "techniques": ["GT75"],
-  "extra": {}
+  "extra": { "color": "#FFD700", "decimals": 0 }
 }
 ```
 
-**Múltiplos pontos num projeto típico:**
-```json
-[
-  { "_id": "xp",    "category": "Experience Points", "shortName": "XP",    "techniques": ["GT01"] },
-  { "_id": "coin",  "category": "Coins",             "shortName": "Coins", "techniques": ["GT75"] },
-  { "_id": "karma", "category": "Karma",             "shortName": "K",     "techniques": ["GT01"] }
-]
-```
+> Aqui `techniques: ["GT75"]` é apenas rótulo descritivo ("ponto de economia/troca") para o mapa do Studio. Não habilita transferência nem comportamento especial.
 
-## API Endpoints
+### Anti-pattern — o que NÃO fazer
 
-### Listar Pontos
-**Método:** GET  
-**Endpoint:** `/v3/point`
-
-### Criar / Atualizar Ponto
-**Método:** POST  
-**Endpoint:** `/v3/point`
-
-POST com `_id` existente = update (upsert).
-
-### Excluir Ponto
-**Método:** DELETE  
-**Endpoint:** `/v3/point/:id`
-
-> ⚠ Não delete um ponto referenciado em challenges ativos. Verifique com:
-> ```
-> funifier_database action=aggregate collection=challenge pipeline='[{"$match": {"points.category": "<point_id>"}}]'
-> ```
+```json
+// ❌ Esperar que GT75 ative troca entre jogadores
+{ "_id": "social", "category": "Social Coin", "techniques": ["GT75"] }
+// Não há transferência player-to-player no engine. transferPoints é código morto.
 
-## Dependências e ordem de criação
+// ❌ Tentar "editar parcialmente" via POST
+{ "_id": "xp", "shortName": "EXP" }
+// Isto APAGA category/image/etc. do ponto "xp" (full replace). Reenvie o objeto completo.
 
-Points devem ser criados **antes** de challenges e leaderboards que os referenciam.
+// ❌ Usar o campo icon
+{ "_id": "xp", "category": "XP", "icon": "star" }
+// "icon" é ignorado (campo morto). Use "image".
+```
 
-Ordem recomendada: `point` → `action` → `challenge` → `leaderboard`
+---
 
-## Checklist
+## Checklist de Configuração
 
-- [ ] `_id` em minúsculas, sem espaços
-- [ ] `techniques: ["GT01"]` para ponto normal ou `["GT75"]` para trocável
-- [ ] `category` e `shortName` preenchidos
-- [ ] Criado antes dos challenges que o referenciam
-- [ ] Confirmado com `funifier_list type=point search=<_id>`
+- [ ] `_id` definido (ou omitido de propósito para gerar GUID). Convenção: minúsculas, sem espaços (não é validado pelo backend).
+- [ ] `category` e `shortName` preenchidos (não são obrigatórios no servidor, mas a UI depende deles).
+- [ ] Ponto criado **antes** dos challenges/actions/levels que o referenciam por `_id`.
+- [ ] Para editar, reenviar o objeto **completo** (POST é full-replace) — não envie só o campo alterado.
+- [ ] Usar `image` (não `icon` — campo morto).
+- [ ] Não depender de `techniques`/`GT75` para comportamento: é só rótulo. Transferência/saldo não vivem aqui.
+- [ ] Antes de `DELETE`, conferir referências em `challenge.points.category` e `level.point` (delete não faz cascata).
+- [ ] Lembrar que saldo do jogador é calculado de `achievement` (`type:0, item:<_id>`), não do módulo point.