API Reference: Economia (Moeda Virtual)

Base URL: /api/economia. Todos os endpoints requerem autenticacao (AuthGuard).

Cada nucleo configura o nome e sigla da sua moeda virtual (ex: Capixacoins/CC). Os exemplos abaixo usam CC mas a sigla varia por nucleo.

Resumo de Endpoints

GET /api/economia/extrato

Retorna o historico de transacoes (ledger) do usuario logado, ordenado do mais recente ao mais antigo.

Query Params

Response 200

{
  "data": [
    {
      "id": "uuid",
      "valor": 150,
      "tipo": "CREDITO",
      "origem": "TAREFA",
      "descricao": "Tarefa aprovada: ...",
      "referencia_id": "uuid | null",
      "criado_em": "2026-04-01T12:00:00Z"
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 47, "totalPages": 3 }
}

GET /api/economia/saldo

Retorna o saldo atual do usuario no nucleo corrente.

Comportamento (multi-membership)

• O nucleoId e injetado automaticamente via @CurrentUser (extraido do JWT).
• O saldo e lido de membros_nucleos.saldo_capixacoins (filtrado por usuario_id + nucleo_id).
• Se o usuario nao tiver membership nesse nucleo, retorna saldo 0.
• Caso nucleoId nao esteja presente no token, faz fallback para o cache legacy em usuarios.saldo_capixacoins.

Response 200

{ "saldo": 3500 }

GET /api/economia/painel

Painel anti-inflacao com metricas agregadas da economia do nucleo.

Permissao: ADMINISTRADOR

Comportamento

• totalEmitido: soma de todas as transacoes do tipo CREDITO no nucleo.
• totalGasto: soma de todas as transacoes do tipo DEBITO no nucleo.
• emCirculacao: soma de saldo_capixacoins de todos os membros ATIVOS via membros_nucleos (1 linha por usuario/nucleo).
• multiplicador: multiplicador global configurado no nucleo (default 1.0).
• tetoMensal: teto mensal ou null se nao configurado.

Response 200

{
  "totalEmitido": 150000,
  "totalGasto": 45000,
  "emCirculacao": 105000,
  "multiplicador": 1.5,
  "tetoMensal": 5000
}

POST /api/economia/ajuste-manual

Credita ou debita moeda de um usuario. Requer justificativa (min. 5 caracteres).

Permissao: ADMINISTRADOR

Validacoes

• Justificativa obrigatoria com minimo de 5 caracteres.
• Para DEBITO: verifica saldo do usuario neste nucleo especifico via membros_nucleos.saldo_capixacoins. Se insuficiente, retorna 400.
• A transacao e inserida com origem: MANUAL e descricao [Ajuste Admin] justificativa.

Body

{
  "usuarioId": "uuid",
  "valor": 500,
  "tipo": "CREDITO",
  "justificativa": "Bonus por participacao especial no evento X"
}

Response 200

{ "message": "Credito de 500 CC realizado" }

PATCH /api/economia/multiplicador

Define o multiplicador global de CC do nucleo. Ex: 1.5x faz tarefa de 100 CC pagar 150.

Permissao: ADMINISTRADOR

Validacao

Valor deve estar entre 0.1 e 10.

Body

{ "multiplicador": 1.5 }

Response 200

{ "message": "Multiplicador atualizado para 1.5x" }

PATCH /api/economia/teto-mensal

Define o limite maximo de CC que um membro pode ganhar por mes (creditos automaticos). Null remove o teto.

Permissao: ADMINISTRADOR

Validacao

Deve ser positivo ou null (sem teto). Creditos MANUAL e ESTORNO nao contam para o teto.

Body

{ "teto": 5000 }

Response 200

{ "message": "Teto mensal definido: 5000 CC" }

GET /api/economia/historico-membros

Lista todos os membros ATIVOS do nucleo com saldo, total recebido e total gasto.

Permissao: ADMINISTRADOR

Comportamento

• Membros vem de membros_nucleos (status ATIVO) com JOIN em usuarios.
• Ordenados por saldo_capixacoins desc.
• Totais de recebido/gasto calculados a partir de transacoes_moeda filtradas por nucleo.

Response 200

[
  {
    "id": "uuid",
    "nome": "Joao Silva",
    "email": "joao@email.com",
    "cargo": "COORDENADOR",
    "saldo_capixacoins": 3500,
    "foto_url": "https://...",
    "totalRecebido": 5000,
    "totalGasto": 1500
  }
]

GET /api/economia/extrato/:usuarioId

Extrato de transacoes de um membro especifico, filtrado por nucleo.

Permissao: ADMINISTRADOR

Query Params

Response 200

{
  "data": [
    { "id": "uuid", "valor": 100, "tipo": "CREDITO", "origem": "TAREFA", "descricao": "...", "criado_em": "..." }
  ],
  "pagination": { "page": 1, "limit": 10, "total": 25 }
}

GET /api/economia/rankings

Rankings do nucleo: top saldos (geral), top ganhos do mes e top gastos do mes.

Permissao: ADMINISTRADOR

Comportamento

• topSaldos: top 10 membros com maior saldo_capixacoins via membros_nucleos (status ATIVO, JOIN com usuarios).
• topGanhosMes: top 10 usuarios com mais creditos no mes corrente (transacoes_moeda).
• topGastosMes: top 10 usuarios com mais debitos no mes corrente.

Response 200

{
  "topSaldos": [
    { "id": "uuid", "nome": "Maria", "foto_url": "...", "saldo_capixacoins": 8500 }
  ],
  "topGanhosMes": [
    { "id": "uuid", "nome": "Carlos", "foto_url": "...", "total": 2300 }
  ],
  "topGastosMes": [
    { "id": "uuid", "nome": "Ana", "foto_url": "...", "total": 1800 }
  ]
}

GET /api/economia/distribuicao

Distribuicao de saldos dos membros do nucleo agrupados por faixa.

Permissao: ADMINISTRADOR

Comportamento

Leitura de saldo_capixacoins via membros_nucleos (status ATIVO). Retorna contagem de membros em cada faixa.

Response 200

[
  { "label": "0", "min": 0, "max": 0, "count": 12 },
  { "label": "1-100", "min": 1, "max": 100, "count": 25 },
  { "label": "101-500", "min": 101, "max": 500, "count": 18 },
  { "label": "501-1000", "min": 501, "max": 1000, "count": 8 },
  { "label": "1001-5000", "min": 1001, "max": 5000, "count": 5 },
  { "label": "5000+", "min": 5001, "max": null, "count": 2 }
]

POST /api/economia/bonus-massa

Credita CC em massa para um grupo de membros, filtrado por cargo e/ou plano.

Permissao: ADMINISTRADOR

Body

Comportamento

• Busca usuarios ATIVOS do nucleo que correspondem aos filtros.
• Insere transacoes em lote (batches de 500) com origem: MANUAL.
• Se nenhum usuario corresponder aos filtros, retorna { "aplicados": 0 }.

Response 200

{ "aplicados": 45, "valorPorMembro": 200 }

Metodo Interno: creditarCC

Metodo usado internamente por tarefas e eventos para creditar CC. Nao exposto como endpoint HTTP.

Comportamento

• Aplica o multiplicador_global do nucleo ao valor base (arredondado).
• Respeita o teto_mensal_cc: se o usuario ja atingiu o teto, nao credita. Se creditar passaria do teto, credita apenas a diferenca restante.
• Creditos com origem MANUAL ou ESTORNO nao contam para o calculo do teto.

Notas de Arquitetura

• O saldo e calculado via ledger (transacoes_moeda). O campo saldo_capixacoins em membros_nucleos e um cache atualizado por database trigger.
• Toda query filtra por nucleo_id — multi-tenant com RLS ativo.
• O nome e sigla da moeda sao configuraveis por nucleo (campo em nucleos). A API sempre trabalha com valores numericos; o frontend resolve o nome/sigla.