API Reference: Conquistas

Base URL: /api/conquistas. Todos requerem autenticacao.

Endpoints

Metodo	Endpoint	Permissao	Descricao
GET	`/api/conquistas`	Autenticado	Listar todas as conquistas do nucleo
GET	`/api/conquistas/minhas`	Autenticado	Minhas conquistas (desbloqueadas + bloqueadas com progresso)
POST	`/api/conquistas`	Admin	Criar nova conquista
PATCH	`/api/conquistas/:id`	Admin	Editar conquista existente
POST	`/api/conquistas/verificar`	Admin	Verificar e conceder conquistas a um usuario

Regras Dinamicas

Cada conquista possui uma regra dinamica definida por campos na tabela conquistas:

Campo	Tipo	Descricao
`regra_tipo`	enum	Tipo da regra que define o criterio de desbloqueio
`regra_quantidade`	integer	Meta numerica a ser atingida (ex: 5 eventos, 10 tarefas)
`regra_campo_extra`	text	Campo adicional para regras que precisam de parametro extra (ex: nome do plano)
`progresso_visivel`	boolean	Se a barra de progresso e visivel para o membro (default: true)
`regra_codigo`	text	Codigo legado para conquistas padrao (ex: ENGAJADO, VETERANO). Mantido para compatibilidade.

Tipos de Regra (regra_tipo)

regra_tipo	Descricao	regra_quantidade	regra_campo_extra
`eventos`	Participar de N eventos (check-in PRESENTE)	N eventos	--
`tarefas`	Completar N tarefas aprovadas	N tarefas	--
`saldo`	Atingir saldo de N moedas do nucleo	N moedas	--
`indicacoes`	Ter N indicacoes aprovadas	N indicacoes	--
`projetos`	Participar de N projetos	N projetos	--
`plano`	Assinar plano especifico	--	Nome do plano (ex: ONCA)
`personalizada`	Concedida manualmente pelo admin	--	--

Progresso (getProgresso)

O metodo getProgresso(usuarioId, conquistaId) retorna o progresso do usuario em direcao a uma conquista:

{
  "atual": 3,
  "meta": 5,
  "percentual": 60
}

atual: valor atual do usuario para o criterio da regra
meta: valor de regra_quantidade da conquista
percentual: Math.min(100, Math.round((atual / meta) * 100))

Barra de Progresso na UI

Na pagina de conquistas do membro (/dashboard/conquistas), cada conquista bloqueada exibe:

Barra de progresso visual com percentual (quando progresso_visivel = true)
Texto indicativo: "3 de 5 eventos"
Conquistas desbloqueadas exibem o badge completo com data de desbloqueio
Conquistas com progresso_visivel = false exibem apenas o icone bloqueado sem barra

Conquistas Padrao (Legacy)

Conquistas migradas do sistema antigo que utilizam regra_codigo. Novas conquistas devem usar o sistema de regras dinamicas.

Badge	Regra Codigo	Equivalente Dinamico
Primeiro Passo	PRIMEIRO_PASSO	personalizada (cadastro completo)
Engajado	ENGAJADO	eventos, quantidade: 5
Veterano	VETERANO	eventos, quantidade: 20
Mao na Massa	MAO_NA_MASSA	tarefas, quantidade: 50
Recrutador	RECRUTADOR	indicacoes, quantidade: 5
Formador de Opiniao	FORMADOR_OPINIAO	tarefas, quantidade: 10
Onca Pintada	ONCA_PINTADA	plano, campo_extra: ONCA

Motor de Regras

O metodo verificarConquistas() avalia todas as regras pendentes para um usuario. E chamado automaticamente apos eventos relevantes (aprovar tarefa, check-in evento, aprovar cadastro, assinar plano). Ao desbloquear, gera notificacao e entrada no feed.

Verifica primeiro pelo regra_tipo dinamico
Fallback para regra_codigo legado se regra_tipo nao estiver definido
Conquistas do tipo personalizada sao ignoradas pelo motor automatico (concedidas manualmente)

Admin UI: Formulario Expandido

A tela de administracao de conquistas (/dashboard/admin/conquistas) possui um formulario expandido:

Select para regra_tipo com todas as opcoes disponiveis
Campo numerico para regra_quantidade (exibido condicionalmente para tipos que usam quantidade)
Campo texto para regra_campo_extra (exibido condicionalmente para tipos que usam campo extra)
Toggle para progresso_visivel
Upload de icone/badge da conquista
Preview visual do card da conquista antes de salvar