Bug de Pagamento de Multas

Versão afetada: Koha 25.05

Módulos afetados: Circulação → Contabilidade → Pagamento de multas

Destinado a usuários avançados que tenham acesso ao banco de dados e acesso total de administrador.

Impacto: Erro 500 ao pagar multas de livros devolvidos; acúmulo de créditos fantasma

Problema: As multas no Koha são chamadas de overdue, registros de créditos são chamadas de payment. Mas quando o sistema tentar registrar o pagamento de uma multa por atraso (overdue) de um livro já devolvido, ele retorna erro 500 em vez de processar o pagamento normalmente. Esse problema vinha ocorrendo desde a versão 23 do Koha.

Adicionalmente, a cada tentativa de pagamento fracassada se criava um registro de crédito (payment) na conta do usuário com valor negativo, sem que esse crédito fosse aplicado à multa. Com o tempo esses créditos se acumulavam e exibiam um saldo de crédito irreal (exemplo: R$ 20,00 R$ 200,00…) enquanto a multa original permanecia pendente.

2- Causas:

2.1 – Campo issue_id nulo

Quando um livro é devolvido, o registro de empréstimo é movido da tabela issues para a tabela old_issues. No entanto, as linhas de multa na tabela accountlines ficam com issue_id=NULL, mantendo apenas old_issue_id como referência.

Quando um pagamento era processado, o código em Koha/Account/Line.pm (linha 692) tentava verificar o status do item através do empréstimo:

$debit->item->itemlost(...)  # Falha porque $issue é indefinido

Como issue_id é NULL e a foreign key só aceita IDs da tabela issues (empréstimos ativos), o sistema não consegue recuperar o empréstimo e lança exceção com o Erro 500.

Como você sabe que está com o bug?? 

• Erro 500 ao clicar ‘Confirmar’ na tela de pagamento de multas.
• A multa permanece pendente após tentativas de pagamento.
• Saldo de crédito crescente e irreal na conta do usuário.
• Log do Plack com: can’t call method “item” on an undefined value at C4/Circulation.pm line 3176
• Afeta multas de livros devolvidos (status RETURNED no accountlines).

Como nós diagnosticamos?

Acessamos o servidor e checamos o log:

tail -20 /var/log/koha/library/plack-error.log

Procuramos a seguinte mensagem no log:

Can't call method "item" on an undefined value at .../C4/Circulation.pm line 3176

Depois, nós fomos identificar os usuários afetados:

Se conecte ao seu banco de dados e rode a query abaixo para listar todos os usuários com multas afetadas pelo bug:

sudo koha-mysql [SUA INSTANCIA]

SELECT DISTINCT a.borrowernumber, p.surname, p.firstname,
    COUNT(*) as multas_pendentes,
    SUM(a.amountoutstanding) as total_pendente
FROM accountlines a
JOIN borrowers p ON a.borrowernumber = p.borrowernumber
WHERE a.debit_type_code = 'OVERDUE'
AND a.amountoutstanding > 0
AND a.issue_id IS NULL
AND a.old_issue_id IS NOT NULL
GROUP BY a.borrowernumber, p.surname, p.firstname
ORDER BY total_pendente DESC;

Verifique créditos fantasmas de um usuário específico, aqui vamos usar o usuário 944, troque esse número pelo usuário da sua biblioteca que você precisa verificar. Borrowernumber é o “numero do usuário” não é necessariamente o numero da carteirinha, ok?

SELECT accountlines_id, credit_type_code, debit_type_code,
       amount, amountoutstanding, status, description
FROM accountlines
WHERE borrowernumber = 944
ORDER BY date DESC;

Créditos fantasma aparecem como linhas com credit_type_code = ‘PAYMENT’ e amountstanding negativo (exemplo: -1.50, -50.00..)

IMPORTANTE: Antes de prosseguir faça backup do seu banco de dados, só faça isso se você souber o que está fazendo.

Correção do bug para um usuário específico:

Mais uma vez, repetimos: vamos usar o usuário 944, troque esse número pelo usuário da sua biblioteca que você precisa verificar. Borrowernumber é o “numero do usuário” não é necessariamente o numero da carteirinha, ok?

Esse procedimento vai: zerar os créditos fantasmas acumulados e quitar as multas pendentes afetadas pelo bug.

-- Passo 1: Identificar as multas pendentes com bug
SELECT accountlines_id, amount, amountoutstanding, description
FROM accountlines
WHERE borrowernumber = 944
AND debit_type_code = 'OVERDUE'
AND amountoutstanding > 0
AND issue_id IS NULL
AND old_issue_id IS NOT NULL;

-- Passo 2: Zerar créditos fantasma
UPDATE accountlines SET amountoutstanding = 0
WHERE borrowernumber = 944
AND credit_type_code = 'PAYMENT'
AND amountoutstanding < 0;

-- Passo 3: Quitar as multas (use os IDs do Passo 1)
UPDATE accountlines SET amountoutstanding = 0, status = 'PAID'
WHERE borrowernumber = 944
AND debit_type_code = 'OVERDUE'
AND amountoutstanding > 0;

Verificar resultados, após a correção, confirme que tudo está zerado:

SELECT accountlines_id, credit_type_code, debit_type_code,
       amount, amountoutstanding, status
FROM accountlines
WHERE borrowernumber = 944;

Todas as linhas devem ter amountoutstanding = 0.

Abra a conta do usuário no intranet – não deve mostrar cobranças nem créditos pendentes. Tente acessar a tela de pagamento – não deve mais mostrar o erro 500. Verifique o log do plack para confirmar ausência de novos erros:

tail -5 /var/log/koha/library/plack-error.log

IMPORTANTE 2: Multas reais x créditos fantasma: Essa correção quita as multas do banco sem passar pelo código bugado. Se o usuário realmente deve as multas, registre o pagamento manualmente no histórico financeiro para controle interno antes de zerar. (!)

IMPORTANTE 3: Multas com livros não devolvidos: A query de diagnóstico filtra apenas multas com old_issue_id (livros devolvidos). Multas de livros ainda emprestados (issue_id_preenchido) não são afetadas por este bug (até onde testamos) e devem ser pagas normalmente pelo sistema, gerando uma renovação dos itens que podem ser devolvidos posteriormente.

Este bug afeta o pagamento de multas pelo intranet. Enquanto não houver atualização oficial do Koha corrigindo o problema, utilize o procedimento descrito neste documento para corrigir as contas dos usuários afetados. Não é uma solução adequada. Mas foi a solução que nós encontramos. O ideal seria um patch de correção. Criamos um ticket no bugzilla informando…