API Reference: Tarefas

Tarefas podem ser de projeto (projeto_id preenchido) ou avulsas (projeto_id = null). Tarefas avulsas pertencem diretamente ao nucleo e aparecem na lista geral. Base URL: /api/tarefas. Todos requerem autenticacao.

Tarefas Avulsas vs Projeto

Caracteristica	Tarefa de Projeto	Tarefa Avulsa
projeto_id	UUID do projeto	`null`
nucleo_id	Herdado do projeto	Obrigatorio
Visibilidade	Dentro do projeto	Lista geral de tarefas do nucleo
Candidaturas	Sim	Sim
Recompensa CC	Sim	Sim

Sistema de Candidaturas

Membros podem se candidatar a tarefas abertas (status PENDENTE, sem responsavel). O coordenador/admin seleciona um candidato, que vira o responsavel_id da tarefa. Cada usuario pode se candidatar apenas uma vez por tarefa. Apos candidatura, a tarefa mostra status "Candidatado" para aquele usuario em vez de desaparecer da lista.

Metodo	Endpoint	Permissao	Descricao
POST	`/api/tarefas/:id/candidatar`	Autenticado	Candidatar-se a uma tarefa
GET	`/api/tarefas/:id/candidaturas`	Admin	Listar candidatos de uma tarefa
POST	`/api/tarefas/:id/selecionar/:usuarioId`	Admin	Selecionar candidato como responsavel

Fluxo de Status

PENDENTE → EM_ANDAMENTO → AGUARDANDO_VALIDACAO → APROVADA
                                                   → REJEITADA

PENDENTE: Tarefa criada, sem responsavel ou aguardando inicio
EM_ANDAMENTO: Responsavel atribuido e trabalhando
AGUARDANDO_VALIDACAO: Responsavel marcou como concluida, aguarda aprovacao do admin
APROVADA: Admin aprovou — recompensa em CC creditada automaticamente
REJEITADA: Admin rejeitou — tarefa volta para revisao ou e cancelada

Recompensa ao Aprovar

Ao aprovar uma tarefa (status → APROVADA), o sistema automaticamente:

Cria uma transacao CREDITO em transacoes_moeda com origem TAREFA
O valor e o recompensa_cc definido na tarefa
O trigger trg_atualizar_saldo atualiza o cache em usuarios.saldo_capixacoins
Verifica conquistas relacionadas (ex: FORMADOR_OPINIAO, MAO_NA_MASSA)
Gera entrada no feed e notificacao para o responsavel

Dificuldade

O campo dificuldade e agora opcional (nullable). Quando nao informado, assume MEDIAcomo default no frontend. Valores possiveis: FACIL, MEDIA, DIFICIL.

Endpoints

Metodo	Endpoint	Permissao	Descricao
GET	`/api/tarefas`	Autenticado	Listar tarefas avulsas do nucleo
POST	`/api/tarefas`	Admin	Criar tarefa avulsa (projeto_id = null)
GET	`/api/tarefas/:id`	Autenticado	Detalhe de uma tarefa
PUT	`/api/tarefas/:id`	Admin	Atualizar tarefa
PUT	`/api/tarefas/:id/status`	Admin/Responsavel	Alterar status da tarefa
POST	`/api/tarefas/:id/candidatar`	Autenticado	Candidatar-se
GET	`/api/tarefas/:id/candidaturas`	Admin	Listar candidaturas
POST	`/api/tarefas/:id/selecionar/:usuarioId`	Admin	Selecionar candidato

Tarefas de Projeto

Tarefas dentro de projetos sao gerenciadas via /api/projetos/:id/tarefas. Veja a documentacao de Projetos e Tarefas para detalhes desses endpoints. O comportamento de candidatura e status e identico ao das tarefas avulsas.

Exemplo: Criar Tarefa Avulsa

POST /api/tarefas
{
  "titulo": "Distribuir panfletos na praca",
  "descricao": "Entregar 200 panfletos no centro",
  "recompensa_cc": 50,
  "dificuldade": "FACIL",
  "data_limite": "2026-04-15T18:00:00Z"
}