funifier-mcp 0.2.0 → 0.2.3

package/datasource-funifier-docs/knowledge/index.md

@@ -1,121 +1,121 @@
-# Funifier Knowledge Base — Index
-
-Este ficheiro serve como **router** para localizar o módulo ou guia correto na base de conhecimento Funifier. Cada entrada indica o ficheiro, uma descrição curta e quando usar.
-
----
-
-## Recursos Fundacionais da Plataforma
-
-A Funifier funciona como um **backend de aplicações**. Independentemente do tipo de projeto (gamificação, app, portal, integração), os módulos abaixo são os recursos base disponíveis para construir qualquer aplicação:
-
-| Recurso | Ficheiro | Para que serve |
-|---------|----------|----------------|
-| **Auth** | `modules/auth.md` | Login de jogadores, geração de tokens JWT, autenticação via API |
-| **Player** | `modules/player.md` | Cadastro e gestão de utilizadores da aplicação |
-| **Database** | `modules/database.md` | CRUD em qualquer coleção, queries MongoDB, aggregates |
-| **Custom Object** | `modules/custom-object.md` | Criar tabelas/coleções próprias (sufixo `__c`) para dados de negócio |
-| **Upload** | `modules/upload.md` | Upload de imagens e ficheiros (avatar, documentos, etc.) |
-| **Trigger** | `modules/trigger.md` | Escrever funções Java que executam no servidor quando eventos acontecem |
-| **Scheduler** | `modules/scheduler.md` | Agendar tarefas automáticas (cron jobs, rotinas periódicas) |
-| **Public Endpoint** | `modules/public.md` | Criar APIs REST customizadas acessíveis sem autenticação |
-| **Webhook** | `modules/webhook.md` | Enviar dados para sistemas externos quando eventos acontecem |
-| **Patterns** | `modules/patterns.md` | Design patterns de implementação (signup, etc.) baseados em experiência real |
-
-> **Nota para o agente:** Estes recursos estão sempre disponíveis. Ao planear qualquer funcionalidade, considere-os como ferramentas que pode combinar livremente — não são exclusivos de gamificação.
-
----
-
-## Módulos Essenciais (Core)
-
-| Módulo | Ficheiro | Descrição | Quando usar |
-|--------|----------|-----------|-------------|
-| Player | `modules/player.md` | Cadastro e gestão de jogadores | Criar, listar, atualizar ou remover jogadores; gerir campos extra e imagens |
-| Action | `modules/action.md` | Definição de tipos de ações | Criar ações que os jogadores podem executar (ex: vender, assistir vídeo) |
-| Action Log | `modules/action-log.md` | Registro de ações executadas | Registrar (track) que um jogador executou uma ação; consultar histórico |
-| Point | `modules/point.md` | Categorias de pontos | Criar moedas/pontos (XP, coins, estrelas); configurar tipos de pontuação |
-| Achievement | `modules/achievement.md` | Conquistas e recompensas | Consultar pontos ganhos, desafios completados, itens comprados; entender a estrutura de recompensas |
-| Challenge | `modules/challenge.md` | Desafios e missões | Criar desafios com regras de ação e recompensas automáticas |
-| Level | `modules/level.md` | Níveis de progressão | Configurar sistema de níveis baseado em pontos acumulados |
-| Leaderboard | `modules/leaderboard.md` | Rankings e classificações | Criar rankings por pontos, ações ou atributos; rankings por período |
-| Team | `modules/team.md` | Equipes e grupos | Organizar jogadores em equipes; rankings por equipe |
-| Virtual Good | `modules/virtual-good.md` | Loja virtual e catálogo | Criar itens para compra com pontos; gerir catálogo e compras |
-
-## Módulos de Engajamento
-
-| Módulo | Ficheiro | Descrição | Quando usar |
-|--------|----------|-----------|-------------|
-| Lottery | `modules/lottery.md` | Sorteios e rifas | Criar sorteios com tickets; executar sorteios automáticos ou manuais |
-| Competition | `modules/competition.md` | Competições entre jogadores | Criar competições temporárias com rankings e prémios para os melhores |
-| Mystery Box | `modules/mystery.md` | Caixas surpresa | Configurar prémios aleatórios com probabilidades definidas |
-| Swap | `modules/swap.md` | Troca entre jogadores | Permitir que jogadores troquem itens ou pontos entre si |
-| Question | `modules/question.md` | Perguntas e respostas | Criar perguntas com alternativas; registrar respostas dos jogadores |
-| Quiz | `modules/quiz.md` | Questionários completos | Montar questionários agrupando múltiplas perguntas; avaliar desempenho |
-| Crossword | `modules/crossword.md` | Palavras cruzadas | Criar jogos de palavras cruzadas como mecânica de engajamento |
-| Story | `modules/story.md` | Narrativas e storytelling | Criar histórias interativas com cenas e escolhas do jogador |
-| Avatar | `modules/avatar.md` | Avatares personalizáveis | Permitir que jogadores personalizem avatares com itens desbloqueáveis |
-| Last Mile | `modules/lastmile.md` | Incentivo à conclusão | Criar mecânicas que incentivam jogadores a completar tarefas pendentes |
-
-## Módulos Técnicos e Infraestrutura
-
-| Módulo | Ficheiro | Descrição | Quando usar |
-|--------|----------|-----------|-------------|
-| Trigger | `modules/trigger.md` | Código Java em eventos | Executar lógica customizada quando eventos acontecem (before/after create, win, etc.) |
-| Scheduler | `modules/scheduler.md` | Tarefas agendadas | Executar código Java em intervalos regulares (cron jobs) |
-| Webhook | `modules/webhook.md` | Notificações HTTP externas | Enviar dados para sistemas externos quando eventos acontecem na gamificação |
-| Notification | `modules/notification.md` | Notificações push e in-app | Enviar notificações para jogadores via push, email ou in-app |
-| WebSocket | `modules/websocket.md` | Comunicação em tempo real | Receber atualizações em tempo real no frontend via WebSocket |
-| Public Endpoint | `modules/public.md` | APIs públicas customizadas | Criar endpoints REST customizados sem autenticação (para integrações) |
-| Widget | `modules/widget.md` | Componentes visuais embeddáveis | Incorporar leaderboards, perfis e outros componentes em páginas externas |
-| Studio Page | `modules/studio-page.md` | Páginas customizadas no Studio | Criar páginas HTML/JS dentro do painel administrativo |
-| KPI Formulas | `modules/kpi-formulas.md` | Fórmulas e indicadores | Criar campos calculados e KPIs derivados de dados da gamificação |
-
-## Módulos de Dados e Armazenamento
-
-| Módulo | Ficheiro | Descrição | Quando usar |
-|--------|----------|-----------|-------------|
-| Database | `modules/database.md` | Acesso direto ao MongoDB | Operações CRUD em coleções; executar aggregates via API |
-| Custom Object | `modules/custom-object.md` | Coleções customizadas (`__c`) | Criar coleções de dados próprias (ex: `car__c`, `email__c`) |
-| CSV Data | `modules/csv-data.md` | Importação/exportação CSV | Importar jogadores ou dados em massa via CSV; exportar relatórios |
-| Upload | `modules/upload.md` | Upload de ficheiros | Fazer upload de imagens e ficheiros para o repositório Funifier |
-| Static Repo | `modules/static-repo.md` | Repositório de ficheiros estáticos | Hospedar ficheiros estáticos (HTML, CSS, JS, imagens) na plataforma |
-
-## Módulos de Administração
-
-| Módulo | Ficheiro | Descrição | Quando usar |
-|--------|----------|-----------|-------------|
-| Auth | `modules/auth.md` | Autenticação e tokens | Gerar tokens de acesso; configurar API keys; autenticação OAuth |
-| Folder | `modules/folder.md` | Organização em pastas | Organizar módulos (ações, desafios, etc.) em pastas no Studio |
-| Backup | `modules/backup.md` | Backup e restauração | Criar backups da gamificação; restaurar configurações |
-| Compact | `modules/compact.md` | Compactação de dados | Compactar dados históricos para otimizar performance |
-| Staging | `modules/staging.md` | Ambiente de homologação | Testar configurações em ambiente separado antes de produção |
-| Marketplace | `modules/marketplace.md` | Templates de gamificação | Importar templates prontos do marketplace Funifier |
-
----
-
-## Guias Transversais
-
-| Guia | Ficheiro | Descrição | Quando usar |
-|------|----------|-----------|-------------|
-| Aggregates | `guides/aggregates.md` | Consultas avançadas MongoDB | Criar relatórios, dashboards, rankings customizados; usar expressões de data Funifier |
-| Triggers | `guides/triggers-guide.md` | Guia completo de triggers | Referência de eventos, entidades, managers e exemplos de código Java |
-| Database Access | `guides/database-access.md` | Acesso ao banco de dados | Referência de acesso via API REST e via código Java (Jongo) |
-| Java Managers | `guides/java-managers.md` | Referência de managers Java | Métodos disponíveis em cada manager (PlayerManager, ActionManager, etc.) para uso em triggers, schedulers e public endpoints |
-| Java Entities | `guides/java-entities.md` | Referência de entidades Java | Campos e tipos dos objetos (Player, Achievement, ActionLog, etc.) e mapeamento para coleções MongoDB |
-| Java Libraries | `guides/java-libraries.md` | Bibliotecas e utilitários Java | JsonUtil, Guid, DateUtil, Unirest, EmailBuilder, Jongo — métodos e exemplos de uso |
-
----
-
-## Como usar este index
-
-1. **Identifique a necessidade** do utilizador (ex: "quero criar um ranking")
-2. **Localize o módulo** na tabela acima (ex: Leaderboard)
-3. **Carregue o ficheiro** correspondente (ex: `modules/leaderboard.md`)
-4. **Siga o checklist** de configuração e use os exemplos de API
-
-Para consultas que envolvem **múltiplos módulos**, carregue cada ficheiro individualmente conforme necessário.
-
-Para **relatórios e queries avançadas**, consulte `guides/aggregates.md`.
-
-Para **lógica customizada com código**, consulte `guides/triggers-guide.md` e `guides/database-access.md`.
-
-Para **referência completa de recursos Java** (managers, entidades, bibliotecas), consulte `guides/java-managers.md`, `guides/java-entities.md` e `guides/java-libraries.md`.
+# Funifier Knowledge Base — Index
+
+Este ficheiro serve como **router** para localizar o módulo ou guia correto na base de conhecimento Funifier. Cada entrada indica o ficheiro, uma descrição curta e quando usar.
+
+---
+
+## Recursos Fundacionais da Plataforma
+
+A Funifier funciona como um **backend de aplicações**. Independentemente do tipo de projeto (gamificação, app, portal, integração), os módulos abaixo são os recursos base disponíveis para construir qualquer aplicação:
+
+| Recurso | Ficheiro | Para que serve |
+|---------|----------|----------------|
+| **Auth** | `modules/auth.md` | Login de jogadores, geração de tokens JWT, autenticação via API |
+| **Player** | `modules/player.md` | Cadastro e gestão de utilizadores da aplicação |
+| **Database** | `modules/database.md` | CRUD em qualquer coleção, queries MongoDB, aggregates |
+| **Custom Object** | `modules/custom-object.md` | Criar tabelas/coleções próprias (sufixo `__c`) para dados de negócio |
+| **Upload** | `modules/upload.md` | Upload de imagens e ficheiros (avatar, documentos, etc.) |
+| **Trigger** | `modules/trigger.md` | Escrever funções Java que executam no servidor quando eventos acontecem |
+| **Scheduler** | `modules/scheduler.md` | Agendar tarefas automáticas (cron jobs, rotinas periódicas) |
+| **Public Endpoint** | `modules/public.md` | Criar APIs REST customizadas acessíveis sem autenticação |
+| **Webhook** | `modules/webhook.md` | Enviar dados para sistemas externos quando eventos acontecem |
+| **Patterns** | `modules/patterns.md` | Design patterns de implementação (signup, etc.) baseados em experiência real |
+
+> **Nota para o agente:** Estes recursos estão sempre disponíveis. Ao planear qualquer funcionalidade, considere-os como ferramentas que pode combinar livremente — não são exclusivos de gamificação.
+
+---
+
+## Módulos Essenciais (Core)
+
+| Módulo | Ficheiro | Descrição | Quando usar |
+|--------|----------|-----------|-------------|
+| Player | `modules/player.md` | Cadastro e gestão de jogadores | Criar, listar, atualizar ou remover jogadores; gerir campos extra e imagens |
+| Action | `modules/action.md` | Definição de tipos de ações | Criar ações que os jogadores podem executar (ex: vender, assistir vídeo) |
+| Action Log | `modules/action-log.md` | Registro de ações executadas | Registrar (track) que um jogador executou uma ação; consultar histórico |
+| Point | `modules/point.md` | Categorias de pontos | Criar moedas/pontos (XP, coins, estrelas); configurar tipos de pontuação |
+| Achievement | `modules/achievement.md` | Conquistas e recompensas | Consultar pontos ganhos, desafios completados, itens comprados; entender a estrutura de recompensas |
+| Challenge | `modules/challenge.md` | Desafios e missões | Criar desafios com regras de ação e recompensas automáticas |
+| Level | `modules/level.md` | Níveis de progressão | Configurar sistema de níveis baseado em pontos acumulados |
+| Leaderboard | `modules/leaderboard.md` | Rankings e classificações | Criar rankings por pontos, ações ou atributos; rankings por período |
+| Team | `modules/team.md` | Equipes e grupos | Organizar jogadores em equipes; rankings por equipe |
+| Virtual Good | `modules/virtual-good.md` | Loja virtual e catálogo | Criar itens para compra com pontos; gerir catálogo e compras |
+
+## Módulos de Engajamento
+
+| Módulo | Ficheiro | Descrição | Quando usar |
+|--------|----------|-----------|-------------|
+| Lottery | `modules/lottery.md` | Sorteios e rifas | Criar sorteios com tickets; executar sorteios automáticos ou manuais |
+| Competition | `modules/competition.md` | Competições entre jogadores | Criar competições temporárias com rankings e prémios para os melhores |
+| Mystery Box | `modules/mystery.md` | Caixas surpresa | Configurar prémios aleatórios com probabilidades definidas |
+| Swap | `modules/swap.md` | Troca entre jogadores | Permitir que jogadores troquem itens ou pontos entre si |
+| Question | `modules/question.md` | Perguntas e respostas | Criar perguntas com alternativas; registrar respostas dos jogadores |
+| Quiz | `modules/quiz.md` | Questionários completos | Montar questionários agrupando múltiplas perguntas; avaliar desempenho |
+| Crossword | `modules/crossword.md` | Palavras cruzadas | Criar jogos de palavras cruzadas como mecânica de engajamento |
+| Story | `modules/story.md` | Narrativas e storytelling | Criar histórias interativas com cenas e escolhas do jogador |
+| Avatar | `modules/avatar.md` | Avatares personalizáveis | Permitir que jogadores personalizem avatares com itens desbloqueáveis |
+| Last Mile | `modules/lastmile.md` | Incentivo à conclusão | Criar mecânicas que incentivam jogadores a completar tarefas pendentes |
+
+## Módulos Técnicos e Infraestrutura
+
+| Módulo | Ficheiro | Descrição | Quando usar |
+|--------|----------|-----------|-------------|
+| Trigger | `modules/trigger.md` | Código Java em eventos | Executar lógica customizada quando eventos acontecem (before/after create, win, etc.) |
+| Scheduler | `modules/scheduler.md` | Tarefas agendadas | Executar código Java em intervalos regulares (cron jobs) |
+| Webhook | `modules/webhook.md` | Notificações HTTP externas | Enviar dados para sistemas externos quando eventos acontecem na gamificação |
+| Notification | `modules/notification.md` | Notificações push e in-app | Enviar notificações para jogadores via push, email ou in-app |
+| WebSocket | `modules/websocket.md` | Comunicação em tempo real | Receber atualizações em tempo real no frontend via WebSocket |
+| Public Endpoint | `modules/public.md` | APIs públicas customizadas | Criar endpoints REST customizados sem autenticação (para integrações) |
+| Widget | `modules/widget.md` | Componentes visuais embeddáveis | Incorporar leaderboards, perfis e outros componentes em páginas externas |
+| Studio Page | `modules/studio-page.md` | Páginas customizadas no Studio | Criar páginas HTML/JS dentro do painel administrativo |
+| KPI Formulas | `modules/kpi-formulas.md` | Fórmulas e indicadores | Criar campos calculados e KPIs derivados de dados da gamificação |
+
+## Módulos de Dados e Armazenamento
+
+| Módulo | Ficheiro | Descrição | Quando usar |
+|--------|----------|-----------|-------------|
+| Database | `modules/database.md` | Acesso direto ao MongoDB | Operações CRUD em coleções; executar aggregates via API |
+| Custom Object | `modules/custom-object.md` | Coleções customizadas (`__c`) | Criar coleções de dados próprias (ex: `car__c`, `email__c`) |
+| CSV Data | `modules/csv-data.md` | Importação/exportação CSV | Importar jogadores ou dados em massa via CSV; exportar relatórios |
+| Upload | `modules/upload.md` | Upload de ficheiros | Fazer upload de imagens e ficheiros para o repositório Funifier |
+| Static Repo | `modules/static-repo.md` | Repositório de ficheiros estáticos | Hospedar ficheiros estáticos (HTML, CSS, JS, imagens) na plataforma |
+
+## Módulos de Administração
+
+| Módulo | Ficheiro | Descrição | Quando usar |
+|--------|----------|-----------|-------------|
+| Auth | `modules/auth.md` | Autenticação e tokens | Gerar tokens de acesso; configurar API keys; autenticação OAuth |
+| Folder | `modules/folder.md` | Organização em pastas | Organizar módulos (ações, desafios, etc.) em pastas no Studio |
+| Backup | `modules/backup.md` | Backup e restauração | Criar backups da gamificação; restaurar configurações |
+| Compact | `modules/compact.md` | Compactação de dados | Compactar dados históricos para otimizar performance |
+| Staging | `modules/staging.md` | Ambiente de homologação | Testar configurações em ambiente separado antes de produção |
+| Marketplace | `modules/marketplace.md` | Templates de gamificação | Importar templates prontos do marketplace Funifier |
+
+---
+
+## Guias Transversais
+
+| Guia | Ficheiro | Descrição | Quando usar |
+|------|----------|-----------|-------------|
+| Aggregates | `guides/aggregates.md` | Consultas avançadas MongoDB | Criar relatórios, dashboards, rankings customizados; usar expressões de data Funifier |
+| Triggers | `guides/triggers-guide.md` | Guia completo de triggers | Referência de eventos, entidades, managers e exemplos de código Java |
+| Database Access | `guides/database-access.md` | Acesso ao banco de dados | Referência de acesso via API REST e via código Java (Jongo) |
+| Java Managers | `guides/java-managers.md` | Referência de managers Java | Métodos disponíveis em cada manager (PlayerManager, ActionManager, etc.) para uso em triggers, schedulers e public endpoints |
+| Java Entities | `guides/java-entities.md` | Referência de entidades Java | Campos e tipos dos objetos (Player, Achievement, ActionLog, etc.) e mapeamento para coleções MongoDB |
+| Java Libraries | `guides/java-libraries.md` | Bibliotecas e utilitários Java | JsonUtil, Guid, DateUtil, Unirest, EmailBuilder, Jongo — métodos e exemplos de uso |
+
+---
+
+## Como usar este index
+
+1. **Identifique a necessidade** do utilizador (ex: "quero criar um ranking")
+2. **Localize o módulo** na tabela acima (ex: Leaderboard)
+3. **Carregue o ficheiro** correspondente (ex: `modules/leaderboard.md`)
+4. **Siga o checklist** de configuração e use os exemplos de API
+
+Para consultas que envolvem **múltiplos módulos**, carregue cada ficheiro individualmente conforme necessário.
+
+Para **relatórios e queries avançadas**, consulte `guides/aggregates.md`.
+
+Para **lógica customizada com código**, consulte `guides/triggers-guide.md` e `guides/database-access.md`.
+
+Para **referência completa de recursos Java** (managers, entidades, bibliotecas), consulte `guides/java-managers.md`, `guides/java-entities.md` e `guides/java-libraries.md`.

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

@@ -1,46 +1,46 @@
-# Achievement (Conquista)
-
-**API Endpoint:** `/v3/achievement`
-
-## O que é
-
-Registro das conquistas dos jogadores ao atingirem marcos relevantes. Todas as conquistas — como completar desafios, subir de nível, ganhar pontos ou adquirir itens — são registradas neste módulo. Ele automatiza o reconhecimento dos marcos alcançados, mas permite ajustes manuais.
-
-## Quando usar
-
-- Para consultar conquistas dos jogadores
-- Para criar relatórios de desempenho
-- Para usar em aggregates e dashboards
-- Para triggers que reagem a conquistas
-
-## Estrutura do Objeto
-
-```json
-{
-  "_id": "64a5d2",
-  "player": "john",
-  "total": 25.0,
-  "type": 0,
-  "item": "xp",
-  "time": {"$date": "2023-07-05T20:57:33.303Z"}
-}
-```
-
-**Tipos de Achievement (campo type):**
-- `0` = Point (ponto ganho)
-- `1` = Challenge (desafio completado)
-- `2` = Virtual Good (item comprado)
-- `3` = Level (nível atingido)
-
-## API Endpoints
-
-### Listar Conquistas
-**Método:** GET
-**Endpoint:** `/v3/achievement`
-
-## Validações e Testes
-
-- [ ] Ao completar desafio, achievement tipo 1 é criado
-- [ ] Ao ganhar pontos, achievement tipo 0 é criado
-- [ ] Ao comprar item, achievement tipo 2 é criado
-- [ ] Ao subir de nível, achievement tipo 3 é criado
+# Achievement (Conquista)
+
+**API Endpoint:** `/v3/achievement`
+
+## O que é
+
+Registro das conquistas dos jogadores ao atingirem marcos relevantes. Todas as conquistas — como completar desafios, subir de nível, ganhar pontos ou adquirir itens — são registradas neste módulo. Ele automatiza o reconhecimento dos marcos alcançados, mas permite ajustes manuais.
+
+## Quando usar
+
+- Para consultar conquistas dos jogadores
+- Para criar relatórios de desempenho
+- Para usar em aggregates e dashboards
+- Para triggers que reagem a conquistas
+
+## Estrutura do Objeto
+
+```json
+{
+  "_id": "64a5d2",
+  "player": "john",
+  "total": 25.0,
+  "type": 0,
+  "item": "xp",
+  "time": {"$date": "2023-07-05T20:57:33.303Z"}
+}
+```
+
+**Tipos de Achievement (campo type):**
+- `0` = Point (ponto ganho)
+- `1` = Challenge (desafio completado)
+- `2` = Virtual Good (item comprado)
+- `3` = Level (nível atingido)
+
+## API Endpoints
+
+### Listar Conquistas
+**Método:** GET
+**Endpoint:** `/v3/achievement`
+
+## Validações e Testes
+
+- [ ] Ao completar desafio, achievement tipo 1 é criado
+- [ ] Ao ganhar pontos, achievement tipo 0 é criado
+- [ ] Ao comprar item, achievement tipo 2 é criado
+- [ ] Ao subir de nível, achievement tipo 3 é criado

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

@@ -1,88 +1,88 @@
-# Action Log (Registro de Ação)
-
-**API Endpoint:** `/v3/action/log`
-
-## O que é
-
-Registro detalhado de todas as ações executadas pelos jogadores. Armazena cada ação realizada, com detalhes como quem executou, qual ação foi feita e quando ocorreu. Esse registro alimenta todos os outros módulos da plataforma.
-
-## Quando usar
-
-- Para registrar que um jogador executou uma ação
-- Para alimentar desafios, rankings e recompensas
-- Para importar ações em lote de sistemas externos
-- Para rastrear comportamento dos jogadores
-
-## Dependências
-
-- **Action**: a ação referenciada deve existir
-- **Player**: o jogador referenciado deve existir
-
-## API Endpoints
-
-### Listar ActionLogs
-**Método:** GET
-**Endpoint:** `/v3/action/log`
-
-**Exemplo de Resposta:**
-```json
-[
-  {
-    "_id": "6509e4e28325771ffaa4506e",
-    "actionId": "sell",
-    "userId": "jerry",
-    "time": 1695147234712,
-    "attributes": {
-      "product": "bike",
-      "price": 1200
-    }
-  }
-]
-```
-
-### Registrar ActionLog
-**Método:** POST
-**Endpoint:** `/v3/action/log`
-
-**Exemplo de Body:**
-```json
-{
-  "actionId": "sell",
-  "userId": "jerry",
-  "attributes": {
-    "product": "bike",
-    "price": 1200
-  }
-}
-```
-
-### Registrar Múltiplos ActionLogs
-**Método:** POST
-**Endpoint:** `/v3/action/log/bulk`
-
-**Exemplo de Body:**
-```json
-[
-  {
-    "actionId": "sell",
-    "userId": "jerry",
-    "attributes": { "product": "bike", "price": 1200 }
-  },
-  {
-    "actionId": "sell",
-    "userId": "tom",
-    "attributes": { "product": "book", "price": 25 }
-  }
-]
-```
-
-### Excluir ActionLog
-**Método:** DELETE
-**Endpoint:** `/v3/action/log/:id`
-
-## Validações e Testes
-
-- [ ] ActionLog aparece na lista com dados corretos
-- [ ] Ao registrar action log, desafios relacionados progridem
-- [ ] Bulk insert registra múltiplas ações corretamente
-- [ ] Atributos são armazenados conforme definido na ação
+# Action Log (Registro de Ação)
+
+**API Endpoint:** `/v3/action/log`
+
+## O que é
+
+Registro detalhado de todas as ações executadas pelos jogadores. Armazena cada ação realizada, com detalhes como quem executou, qual ação foi feita e quando ocorreu. Esse registro alimenta todos os outros módulos da plataforma.
+
+## Quando usar
+
+- Para registrar que um jogador executou uma ação
+- Para alimentar desafios, rankings e recompensas
+- Para importar ações em lote de sistemas externos
+- Para rastrear comportamento dos jogadores
+
+## Dependências
+
+- **Action**: a ação referenciada deve existir
+- **Player**: o jogador referenciado deve existir
+
+## API Endpoints
+
+### Listar ActionLogs
+**Método:** GET
+**Endpoint:** `/v3/action/log`
+
+**Exemplo de Resposta:**
+```json
+[
+  {
+    "_id": "6509e4e28325771ffaa4506e",
+    "actionId": "sell",
+    "userId": "jerry",
+    "time": 1695147234712,
+    "attributes": {
+      "product": "bike",
+      "price": 1200
+    }
+  }
+]
+```
+
+### Registrar ActionLog
+**Método:** POST
+**Endpoint:** `/v3/action/log`
+
+**Exemplo de Body:**
+```json
+{
+  "actionId": "sell",
+  "userId": "jerry",
+  "attributes": {
+    "product": "bike",
+    "price": 1200
+  }
+}
+```
+
+### Registrar Múltiplos ActionLogs
+**Método:** POST
+**Endpoint:** `/v3/action/log/bulk`
+
+**Exemplo de Body:**
+```json
+[
+  {
+    "actionId": "sell",
+    "userId": "jerry",
+    "attributes": { "product": "bike", "price": 1200 }
+  },
+  {
+    "actionId": "sell",
+    "userId": "tom",
+    "attributes": { "product": "book", "price": 25 }
+  }
+]
+```
+
+### Excluir ActionLog
+**Método:** DELETE
+**Endpoint:** `/v3/action/log/:id`
+
+## Validações e Testes
+
+- [ ] ActionLog aparece na lista com dados corretos
+- [ ] Ao registrar action log, desafios relacionados progridem
+- [ ] Bulk insert registra múltiplas ações corretamente
+- [ ] Atributos são armazenados conforme definido na ação