funifier-mcp 0.2.23 → 0.2.25

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

@@ -5,55 +5,103 @@
 
 ## O que é
 
-Cadastro das diferentes ações que os jogadores podem realizar na gamificação. Permite criar e configurar todas as ações possíveis dentro da experiência gamificada, como "vender", "comprar", "comentar", "compartilhar", entre outras. As ações são a base da estratégia de engajamento, pois definem o que é possível fazer na gamificação e servem para disparar regras e recompensas. É possível adicionar atributos extras a cada ação, por exemplo, "produto" e "valor" na ação de venda.
+Cadastro das diferentes ações que os jogadores podem realizar na gamificação. As ações são a base da estratégia de engajamento — definem o que pode ser feito e servem para disparar desafios e recompensas. É possível adicionar atributos extras para detalhar o contexto (ex: `produto`, `valor` numa ação de venda).
 
 ## Quando usar
 
 - Em todo projeto de gamificação (obrigatório)
 - Para definir os comportamentos que serão rastreados
-- Para criar a base de eventos que disparam desafios e recompensas
+- Para criar a base de eventos que disparam challenges e recompensas
 
-## Checklist de Configuração no Studio
+## Ação simples vs ação com atributos
 
-- [ ] Definir o _id da ação (letras minúsculas, sem espaços ou acentos)
-- [ ] Definir o nome amigável da ação (inicial maiúscula)
-- [ ] Definir atributos extras se necessário (name + type: String, Number ou Boolean)
-- [ ] Ativar a ação (active: true)
-- [ ] Boas práticas: criar ações genéricas e usar atributos para detalhar contexto
+**Ação simples** — sem atributos. Use quando o contexto não importa, só o fato de ter ocorrido:
+
+```json
+{
+  "_id": "watch_video",
+  "action": "Watch Video",
+  "active": true,
+  "attributes": []
+}
+```
+
+Exemplos típicos: `login`, `acessar_feed`, `assistir_video`, `jogar_mini`, `compartilhar`.
+
+**Ação com atributos** — adicione atributos quando precisar filtrar ou acumular valores dentro de um challenge. Tipos disponíveis: `String`, `Number`, `Boolean`.
+
+```json
+{
+  "_id": "sell",
+  "action": "Sell",
+  "active": true,
+  "attributes": [
+    { "name": "product", "type": "String" },
+    { "name": "price", "type": "Number" }
+  ]
+}
+```
+
+Use atributos quando quiser criar challenges como "vender 10 livros" (filtro por `product = "book"`) ou "vender R$500 em eletrônicos" (soma de `price`).
+
+## Imagem
+
+Actions podem ter uma imagem associada via campo `image` com três tamanhos:
+
+```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 }
+}
+```
+
+Na prática basta preencher `url` nos três tamanhos com a mesma URL se não houver versões distintas.
+
+## Comportamento de `_id` duplicado (upsert)
+
+O endpoint POST faz **upsert**: se o `_id` já existir, a ação é **atualizada**; se não existir, é **criada**. Não retorna erro em caso de duplicata.
+
+Isso significa que é seguro reenviar a mesma ação para atualizar atributos ou o nome — os challenges existentes que referenciam esse `_id` continuam funcionando.
+
+## Boas Práticas
+
+- `_id`: letras minúsculas, sem espaços ou acentos — use `_` como separador (`watch_video`, não `Watch Video`)
+- Crie ações **genéricas** e use atributos para detalhar: prefira `comprar` com atributo `produto` a criar `comprar_sapato` e `comprar_camisa`
+- Omita `attributes` (ou envie `[]`) quando o contexto não for necessário para nenhum challenge
 
 ## API Endpoints
 
 ### Listar Ações
-**Método:** GET
+**Método:** GET  
 **Endpoint:** `/v3/action`
-**Descrição:** Retorna a lista de ações configuradas na gamificação.
 
-**Exemplo de Resposta:**
-```json
-[
-  {
-    "action": "Sell",
-    "attributes": [
-      { "name": "product", "type": "String" },
-      { "name": "price", "type": "Number" }
-    ],
-    "active": true,
-    "_id": "sell"
-  }
-]
+**Busca múltipla com funifier_list:** o parâmetro `search` aceita termos separados por vírgula (OR):
+```
+funifier_list type=action search="assistir video, jogar mini, acessar feed"
 ```
 
-### Criar Ação
-**Método:** POST
+### Criar / Atualizar Ação
+**Método:** POST  
 **Endpoint:** `/v3/action`
-**Descrição:** Cria uma nova ação com nome, atributos e status de ativação.
 
-**Exemplo de Body:**
+POST com `_id` existente = update (upsert). POST sem `_id` = cria com ID gerado.
+
+**Ação simples:**
+```json
+{
+  "_id": "watch_video",
+  "action": "Watch Video",
+  "active": true
+}
+```
+
+**Ação com atributos:**
 ```json
 {
   "_id": "sell",
-  "active": true,
   "action": "Sell",
+  "active": true,
   "attributes": [
     { "name": "product", "type": "String" },
     { "name": "price", "type": "Number" }
@@ -62,19 +110,28 @@ Cadastro das diferentes ações que os jogadores podem realizar na gamificação
 ```
 
 ### Excluir Ação
-**Método:** DELETE
+**Método:** DELETE  
 **Endpoint:** `/v3/action/:id`
-**Descrição:** Remove uma ação da gamificação.
 
-## Boas Práticas
+> ⚠ Deletar uma ação que é referenciada em challenges ativos pode causar inconsistências. Verifique antes quais challenges usam essa ação:
+> ```
+> funifier_database action=aggregate collection=challenge pipeline='[{"$match": {"rules.actionId": "<action_id>"}}]'
+> ```
+
+## Validação após criar
+
+Use `funifier_list` para confirmar que a ação foi criada:
+
+```
+funifier_list type=action search=<_id ou nome>
+```
 
-- Crie ações genéricas como "comprar", "vender", "responder", "visitar"
-- Use os atributos para detalhar o contexto da ação (ex: produto, local, valor)
-- Evite criar uma ação diferente para cada variação. Exemplo errado: "comprar sapato", "comprar camisa". Exemplo certo: ação "comprar" com atributo "produto"
+Não use `funifier_logs` para validar actions — esse comando é específico para triggers e schedulers.
 
-## Validações e Testes
+## Checklist
 
-- [ ] Ação aparece na lista GET /v3/action
-- [ ] Ação tem _id único e sem caracteres especiais
-- [ ] Atributos estão com tipos corretos (String, Number, Boolean)
-- [ ] Ação está ativa (active: true)
+- [ ] `_id` definido: minúsculas, sem espaços (`watch_video`, não `Watch Video`)
+- [ ] `action` (nome amigável) preenchido
+- [ ] `active: true`
+- [ ] Atributos com tipos corretos: `String`, `Number` ou `Boolean`
+- [ ] Confirmado com `funifier_list type=action search=<_id>`

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

@@ -19,73 +19,310 @@ Configuração de desafios a serem completados por jogadores ou equipes. Permite
 - **Point**: tipos de ponto devem existir antes de criar challenges que os recompensam
 - **Action**: ações devem existir antes de criar challenges que as referenciam
 
-## Checklist de Configuração no Studio
+## Campos Obrigatórios vs Opcionais
 
-- [ ] Definir título e descrição do desafio
-- [ ] Definir regras (rules): qual ação, quantas vezes, filtros por atributo
-- [ ] Definir recompensas (points): tipo de ponto e quantidade
-- [ ] Definir frequência (uma vez, diário, semanal, ilimitado)
-- [ ] Definir desbloqueio (quando fica disponível)
-- [ ] Configurar notificações de conclusão
-- [ ] Vincular técnicas de jogo (techniques)
+| Campo | Obrigatório | Descrição |
+|---|---|---|
+| `challenge` | sim | Nome/título do desafio |
+| `techniques` | sim | Array com pelo menos um código GT (ex: `["GT35"]`) |
+| `rules` | sim | Regras que definem o que o jogador deve fazer |
+| `points` | recomendado | Recompensas em pontos ao completar |
+| `description` | não | Descrição exibida ao jogador |
+| `active` | não | `true` por padrão |
+| `_id` | não | Gerado automaticamente se omitido |
+| `range` | não | Obrigatório quando há múltiplas rules; padrão `0` |
+| `teamChallenge` | não | `true` para desafios de equipe |
+| `limitTotal` | não | Limite de vezes que pode ser completado |
+| `limitPerType` | não | A quem se aplica o limite |
+| `limitTimeAmount` | não | Número de períodos para o limite |
+| `limitTimeScale` | não | Escala de tempo do limite |
+| `notifications` | não | Notificações ao completar/criar/alterar |
+| `requirements` | não | Pré-requisitos para desbloquear |
+| `rewards` | não | Recompensas adicionais (itens de catálogo) |
+| `when` | não | Restrição de data/hora de disponibilidade |
+| `principals` | não | Restringe o desafio a jogadores/equipes específicos |
+| `trackFullProgress` | não | Rastrear progresso completo de cada rule |
+| `extra` | não | Campos customizados livres |
+| `i18n` | não | Traduções do título/descrição |
+
+## Imagem (badge)
+
+Challenges usam o campo `badge` (não `image`) para a imagem do desafio:
+
+```json
+"badge": {
+  "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 }
+}
+```
+
+Na prática basta preencher `url` nos três tamanhos com a mesma URL se não houver versões distintas.
+
+## Técnicas de Jogo (techniques)
+
+`techniques` é **obrigatório**. Cada código GT representa uma mecânica de gamificação. Para challenges, os códigos válidos são:
+
+`GT35`, `GT22`, `GT02`, `GT07`, `GT17`, `GT14`, `GT48`, `GT12`, `GT40`, `GT89`, `GT68`, `GT66`, `GT67`, `GT21`, `GT30`, `GT86`
+
+O mais comum para challenges é **`GT35` (Quest List)** — exibe uma lista de tarefas/missões para o jogador cumprir.
+
+```json
+"techniques": ["GT35"]
+```
+
+## Tabela de Referência dos Enums
+
+### `range` — como as rules são avaliadas
+
+| Valor | Label |
+|---|---|
+| `0` | Complete All (completar todas as rules) |
+| `1` | Complete Any (completar qualquer uma) |
+| `2` | Complete All in Order (completar todas em ordem) |
+
+Padrão: `0` (Complete All). Necessário quando há mais de uma rule.
+
+### `rules[].operator` — critério de contagem da rule
+
+| Valor | Label | Uso |
+|---|---|---|
+| `5` | `>=` (Greater Than or Equal) | Padrão — contar N ou mais vezes |
+| `1` | `=` (Equal) | Exatamente N vezes |
+| `40` | `%` (Percentage) | Percentual |
+
+Exemplo: `operator: 5, total: 3` = executar a ação 3 ou mais vezes.
+
+### `rules[].filters[].operator` — operador dos filtros de atributo
+
+| Valor | Label |
+|---|---|
+| `1` | Is (igual a) |
+| `3` | Contains (contém) |
+| `4` | Greater Than (maior que) |
+| `5` | Greater Than or Equal To |
+| `6` | Less Than (menor que) |
+| `7` | Less Than or Equal To |
+| `8` | Is Not (diferente de) |
+| `9` | Exists (campo existe) |
+| `10` | Does Not Exist (campo não existe) |
+| `20` | Near in Meters (geolocalização) |
+
+### `points[].operation` — operação sobre atributo numérico da ação
+
+| Valor | Label | Uso |
+|---|---|---|
+| `0` | None | Pontos fixos (padrão) |
+| `1` | Multiply By | Multiplica `total` pelo valor do atributo da ação |
+| `2` | Divide By | Divide `total` pelo valor do atributo da ação |
+
+`operation > 0` só faz sentido quando a rule tem exatamente 1 action com atributo numérico. Nesse caso, `points[].value` deve conter o nome do atributo.
+
+### `limitPerType` — a quem o limite se aplica
+
+| Valor | Label |
+|---|---|
+| `0` | Player |
+| `1` | Team |
+| `2` | Gamification (global) |
+
+### `limitTimeScale` — escala de tempo do limite
+
+| Valor | Label |
+|---|---|
+| `0` | None (sem janela de tempo) |
+| `2` | Second |
+| `3` | Minute |
+| `4` | Hour |
+| `5` | Day |
+| `6` | Week |
+| `7` | Month |
+| `8` | Year |
+
+### `notifications[].event`
+
+| Valor | Label |
+|---|---|
+| `0` | On Win (ao completar o desafio) |
+| `1` | On Create (ao criar o progresso) |
+| `2` | On Change (ao avançar no progresso) |
+
+### `notifications[].scope`
+
+| Valor | Label |
+|---|---|
+| `0` | Private (apenas o jogador) |
+| `1` | Newsfeed (visível no feed) |
+| `99` | Custom |
+
+### `requirements[].type` / `rewards[].type`
+
+| Valor | Label |
+|---|---|
+| `0` | Point |
+| `1` | Challenge |
+| `2` | Catalog Item |
+| `3` | Level |
+| `5` | Lottery |
+| `9` | Competition |
+| `50` | Lottery Ticket (apenas em rewards) |
 
 ## API Endpoints
 
 ### Listar Desafios
-**Método:** GET
+**Método:** GET  
 **Endpoint:** `/v3/challenge`
 
-**Exemplo de Resposta:**
-```json
-[
-  {
-    "challenge": "Sell 10 books",
-    "description": "Sell 10 books to earn 25 xp and 5 coins",
-    "rules": [
-      {
-        "actionId": "sell",
-        "filters": [
-          { "value": "book", "operator": 1, "param": "product" }
-        ],
-        "total": 10
-      }
-    ],
-    "points": [
-      { "total": 25, "category": "xp" },
-      { "total": 5, "category": "coin" }
-    ],
-    "_id": "DTkhJHV"
-  }
-]
-```
+### Buscar por ID
+**Método:** GET  
+**Endpoint:** `/v3/challenge/:id`
 
-### Criar Desafio
-**Método:** POST
+### Criar / Atualizar Desafio
+**Método:** POST  
 **Endpoint:** `/v3/challenge`
 
-**Exemplo de Body:**
+Criar e atualizar usam o mesmo endpoint POST. Se `_id` for enviado e o documento existir, é atualizado.
+
+### Excluir Desafio
+**Método:** DELETE  
+**Endpoint:** `/v3/challenge/:id`
+
+## Exemplos
+
+### Challenge simples — executar uma ação N vezes
+
 ```json
 {
   "challenge": "Watch Video",
-  "description": "Complete this challenge by watching a video, and earn 10 xp",
+  "description": "Watch a video to earn 10 xp",
+  "techniques": ["GT35"],
+  "rules": [
+    { "actionId": "watch_video", "operator": 5, "total": 1 }
+  ],
+  "points": [
+    { "total": 10, "category": "xp", "operation": 0 }
+  ]
+}
+```
+
+### Challenge com filtro de atributo
+
+```json
+{
+  "challenge": "Sell 10 Books",
+  "description": "Sell 10 books to earn 25 xp",
+  "techniques": ["GT35"],
+  "rules": [
+    {
+      "actionId": "sell",
+      "operator": 5,
+      "total": 10,
+      "filters": [
+        { "param": "product", "operator": 1, "value": "book" }
+      ]
+    }
+  ],
+  "points": [
+    { "total": 25, "category": "xp", "operation": 0 }
+  ]
+}
+```
+
+### Challenge com múltiplas rules (completar todas)
+
+```json
+{
+  "challenge": "Daily Routine",
+  "techniques": ["GT35"],
+  "range": 0,
   "rules": [
-    { "actionId": "watch_video", "operator": 5, "total": 0 }
+    { "actionId": "login", "operator": 5, "total": 1 },
+    { "actionId": "comment", "operator": 5, "total": 3 }
   ],
   "points": [
-    { "total": 10.0, "category": "xp", "operation": 0 }
+    { "total": 50, "category": "xp", "operation": 0 }
+  ]
+}
+```
+
+### Challenge com limite de frequência (1x por dia por jogador)
+
+```json
+{
+  "challenge": "Daily Check-in",
+  "techniques": ["GT35"],
+  "rules": [
+    { "actionId": "checkin", "operator": 5, "total": 1 }
   ],
-  "techniques": ["GT35"]
+  "points": [{ "total": 5, "category": "xp", "operation": 0 }],
+  "limitTotal": 1,
+  "limitPerType": 0,
+  "limitTimeAmount": 1,
+  "limitTimeScale": 5
 }
 ```
 
-### Excluir Desafio
-**Método:** DELETE
-**Endpoint:** `/v3/challenge/:id`
+### Challenge com notificação ao completar
+
+```json
+{
+  "challenge": "First Comment",
+  "techniques": ["GT35"],
+  "rules": [{ "actionId": "comment", "operator": 5, "total": 1 }],
+  "points": [{ "total": 10, "category": "xp", "operation": 0 }],
+  "notifications": [
+    {
+      "event": 0,
+      "type": 0,
+      "scope": 0,
+      "content": "{{player.name}} completed {{item.name}}"
+    }
+  ]
+}
+```
+
+### Challenge com pré-requisito (desbloqueia após completar outro desafio)
+
+```json
+{
+  "challenge": "Advanced Task",
+  "techniques": ["GT35"],
+  "rules": [{ "actionId": "upload", "operator": 5, "total": 5 }],
+  "points": [{ "total": 100, "category": "xp", "operation": 0 }],
+  "requirements": [
+    { "type": 1, "total": 1, "item": "first_comment_challenge_id" }
+  ]
+}
+```
+
+## Como Validar se foi Criado Corretamente
+
+Após salvar com `funifier_save`, confirme com `funifier_get`:
+
+```
+funifier_get type=challenge id=<id_retornado>
+```
+
+Ou liste e filtre:
+
+```
+funifier_list type=challenge search=<nome_do_challenge>
+```
+
+Para testar se o challenge está funcionando, registre a ação e verifique o progresso do jogador:
+
+```
+POST /v3/action/log  { "actionId": "...", "player": "player_id" }
+GET /v3/challenge/progress?player=player_id
+```
 
-## Validações e Testes
+## Checklist de Configuração
 
-- [ ] Desafio aparece na lista GET /v3/challenge
-- [ ] Ações referenciadas nas rules existem (GET /v3/action)
-- [ ] Pontos referenciados nas recompensas existem (GET /v3/point)
-- [ ] Ao registrar ação (POST /v3/action/log), o desafio progride corretamente
-- [ ] Ao completar o desafio, jogador recebe os pontos definidos
+- [ ] `challenge` (nome) preenchido
+- [ ] `techniques` com pelo menos um código GT (ex: `["GT35"]`)
+- [ ] `rules` com `actionId` existente, `operator` e `total` definidos
+- [ ] `range` definido quando há mais de uma rule
+- [ ] `points` com `category` existente
+- [ ] Ações referenciadas nas rules existem (`funifier_list type=action`)
+- [ ] Pontos referenciados existem (`funifier_list type=point`)
+- [ ] Validado com `funifier_get` após salvar