Bug 21156: Add plural translation capabilities to JS files
[koha.git] / Koha / Account.pm
blobae6bebbb7a74f5858b390d068ee9626aaf2dbe6c
1 package Koha::Account;
3 # Copyright 2016 ByWater Solutions
5 # This file is part of Koha.
7 # Koha is free software; you can redistribute it and/or modify it
8 # under the terms of the GNU General Public License as published by
9 # the Free Software Foundation; either version 3 of the License, or
10 # (at your option) any later version.
12 # Koha is distributed in the hope that it will be useful, but
13 # WITHOUT ANY WARRANTY; without even the implied warranty of
14 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 # GNU General Public License for more details.
17 # You should have received a copy of the GNU General Public License
18 # along with Koha; if not, see <http://www.gnu.org/licenses>.
20 use Modern::Perl;
22 use Carp;
23 use Data::Dumper;
24 use List::MoreUtils qw( uniq );
25 use Try::Tiny;
27 use C4::Circulation qw( ReturnLostItem );
28 use C4::Letters;
29 use C4::Log qw( logaction );
30 use C4::Stats qw( UpdateStats );
32 use Koha::Patrons;
33 use Koha::Account::Lines;
34 use Koha::Account::Offsets;
35 use Koha::Account::DebitTypes;
36 use Koha::DateUtils qw( dt_from_string );
37 use Koha::Exceptions;
38 use Koha::Exceptions::Account;
40 =head1 NAME
42 Koha::Accounts - Module for managing payments and fees for patrons
44 =cut
46 sub new {
47 my ( $class, $params ) = @_;
49 Carp::croak("No patron id passed in!") unless $params->{patron_id};
51 return bless( $params, $class );
54 =head2 pay
56 This method allows payments to be made against fees/fines
58 Koha::Account->new( { patron_id => $borrowernumber } )->pay(
60 amount => $amount,
61 note => $note,
62 description => $description,
63 library_id => $branchcode,
64 lines => $lines, # Arrayref of Koha::Account::Line objects to pay
65 credit_type => $type, # credit_type_code code
66 offset_type => $offset_type, # offset type code
70 =cut
72 sub pay {
73 my ( $self, $params ) = @_;
75 my $amount = $params->{amount};
76 my $description = $params->{description};
77 my $note = $params->{note} || q{};
78 my $library_id = $params->{library_id};
79 my $lines = $params->{lines};
80 my $type = $params->{type} || 'PAYMENT';
81 my $payment_type = $params->{payment_type} || undef;
82 my $credit_type = $params->{credit_type};
83 my $offset_type = $params->{offset_type} || $type eq 'WRITEOFF' ? 'Writeoff' : 'Payment';
84 my $cash_register = $params->{cash_register};
86 my $userenv = C4::Context->userenv;
88 my $patron = Koha::Patrons->find( $self->{patron_id} );
90 my $manager_id = $userenv ? $userenv->{number} : 0;
91 my $interface = $params ? ( $params->{interface} || C4::Context->interface ) : C4::Context->interface;
92 Koha::Exceptions::Account::RegisterRequired->throw()
93 if ( C4::Context->preference("UseCashRegisters")
94 && defined($payment_type)
95 && ( $payment_type eq 'CASH' )
96 && !defined($cash_register) );
98 my @fines_paid; # List of account lines paid on with this payment
100 my $balance_remaining = $amount; # Set it now so we can adjust the amount if necessary
101 $balance_remaining ||= 0;
103 my @account_offsets;
105 # We were passed a specific line to pay
106 foreach my $fine ( @$lines ) {
107 my $amount_to_pay =
108 $fine->amountoutstanding > $balance_remaining
109 ? $balance_remaining
110 : $fine->amountoutstanding;
112 my $old_amountoutstanding = $fine->amountoutstanding;
113 my $new_amountoutstanding = $old_amountoutstanding - $amount_to_pay;
114 $fine->amountoutstanding($new_amountoutstanding)->store();
115 $balance_remaining = $balance_remaining - $amount_to_pay;
117 # Same logic exists in Koha::Account::Line::apply
118 if ( $new_amountoutstanding == 0
119 && $fine->itemnumber
120 && $fine->debit_type_code
121 && ( $fine->debit_type_code eq 'LOST' ) )
123 C4::Circulation::ReturnLostItem( $self->{patron_id}, $fine->itemnumber );
126 my $account_offset = Koha::Account::Offset->new(
128 debit_id => $fine->id,
129 type => $offset_type,
130 amount => $amount_to_pay * -1,
133 push( @account_offsets, $account_offset );
135 if ( C4::Context->preference("FinesLog") ) {
136 logaction(
137 "FINES", 'MODIFY',
138 $self->{patron_id},
139 Dumper(
141 action => 'fee_payment',
142 borrowernumber => $fine->borrowernumber,
143 old_amountoutstanding => $old_amountoutstanding,
144 new_amountoutstanding => 0,
145 amount_paid => $old_amountoutstanding,
146 accountlines_id => $fine->id,
147 manager_id => $manager_id,
148 note => $note,
151 $interface
153 push( @fines_paid, $fine->id );
157 # Were not passed a specific line to pay, or the payment was for more
158 # than the what was owed on the given line. In that case pay down other
159 # lines with remaining balance.
160 my @outstanding_fines;
161 @outstanding_fines = $self->lines->search(
163 amountoutstanding => { '>' => 0 },
165 ) if $balance_remaining > 0;
167 foreach my $fine (@outstanding_fines) {
168 my $amount_to_pay =
169 $fine->amountoutstanding > $balance_remaining
170 ? $balance_remaining
171 : $fine->amountoutstanding;
173 my $old_amountoutstanding = $fine->amountoutstanding;
174 $fine->amountoutstanding( $old_amountoutstanding - $amount_to_pay );
175 $fine->store();
177 if ( $fine->amountoutstanding == 0
178 && $fine->itemnumber
179 && $fine->debit_type_code
180 && ( $fine->debit_type_code eq 'LOST' ) )
182 C4::Circulation::ReturnLostItem( $self->{patron_id}, $fine->itemnumber );
185 my $account_offset = Koha::Account::Offset->new(
187 debit_id => $fine->id,
188 type => $offset_type,
189 amount => $amount_to_pay * -1,
192 push( @account_offsets, $account_offset );
194 if ( C4::Context->preference("FinesLog") ) {
195 logaction(
196 "FINES", 'MODIFY',
197 $self->{patron_id},
198 Dumper(
200 action => "fee_$type",
201 borrowernumber => $fine->borrowernumber,
202 old_amountoutstanding => $old_amountoutstanding,
203 new_amountoutstanding => $fine->amountoutstanding,
204 amount_paid => $amount_to_pay,
205 accountlines_id => $fine->id,
206 manager_id => $manager_id,
207 note => $note,
210 $interface
212 push( @fines_paid, $fine->id );
215 $balance_remaining = $balance_remaining - $amount_to_pay;
216 last unless $balance_remaining > 0;
219 $credit_type ||=
220 $type eq 'WRITEOFF'
221 ? 'WRITEOFF'
222 : 'PAYMENT';
224 $description ||= $type eq 'WRITEOFF' ? 'Writeoff' : q{};
226 my $payment = Koha::Account::Line->new(
228 borrowernumber => $self->{patron_id},
229 date => dt_from_string(),
230 amount => 0 - $amount,
231 description => $description,
232 credit_type_code => $credit_type,
233 payment_type => $payment_type,
234 amountoutstanding => 0 - $balance_remaining,
235 manager_id => $manager_id,
236 interface => $interface,
237 branchcode => $library_id,
238 register_id => $cash_register,
239 note => $note,
241 )->store();
243 foreach my $o ( @account_offsets ) {
244 $o->credit_id( $payment->id() );
245 $o->store();
248 UpdateStats(
250 branch => $library_id,
251 type => lc($type),
252 amount => $amount,
253 borrowernumber => $self->{patron_id},
257 if ( C4::Context->preference("FinesLog") ) {
258 logaction(
259 "FINES", 'CREATE',
260 $self->{patron_id},
261 Dumper(
263 action => "create_$type",
264 borrowernumber => $self->{patron_id},
265 amount => 0 - $amount,
266 amountoutstanding => 0 - $balance_remaining,
267 credit_type_code => $credit_type,
268 accountlines_paid => \@fines_paid,
269 manager_id => $manager_id,
272 $interface
276 if ( C4::Context->preference('UseEmailReceipts') ) {
277 if (
278 my $letter = C4::Letters::GetPreparedLetter(
279 module => 'circulation',
280 letter_code => uc("ACCOUNT_$type"),
281 message_transport_type => 'email',
282 lang => $patron->lang,
283 tables => {
284 borrowers => $self->{patron_id},
285 branches => $library_id,
287 substitute => {
288 credit => $payment,
289 offsets => \@account_offsets,
294 C4::Letters::EnqueueLetter(
296 letter => $letter,
297 borrowernumber => $self->{patron_id},
298 message_transport_type => 'email',
300 ) or warn "can't enqueue letter $letter";
304 return $payment->id;
307 =head3 add_credit
309 This method allows adding credits to a patron's account
311 my $credit_line = Koha::Account->new({ patron_id => $patron_id })->add_credit(
313 amount => $amount,
314 description => $description,
315 note => $note,
316 user_id => $user_id,
317 interface => $interface,
318 library_id => $library_id,
319 payment_type => $payment_type,
320 type => $credit_type,
321 item_id => $item_id
325 $credit_type can be any of:
326 - 'CREDIT'
327 - 'PAYMENT'
328 - 'FORGIVEN'
329 - 'LOST_RETURN'
330 - 'WRITEOFF'
332 =cut
334 sub add_credit {
336 my ( $self, $params ) = @_;
338 # check for mandatory params
339 my @mandatory = ( 'interface', 'amount' );
340 for my $param (@mandatory) {
341 unless ( defined( $params->{$param} ) ) {
342 Koha::Exceptions::MissingParameter->throw(
343 error => "The $param parameter is mandatory" );
347 # amount should always be passed as a positive value
348 my $amount = $params->{amount} * -1;
349 unless ( $amount < 0 ) {
350 Koha::Exceptions::Account::AmountNotPositive->throw(
351 error => 'Debit amount passed is not positive' );
354 my $description = $params->{description} // q{};
355 my $note = $params->{note} // q{};
356 my $user_id = $params->{user_id};
357 my $interface = $params->{interface};
358 my $library_id = $params->{library_id};
359 my $cash_register = $params->{cash_register};
360 my $payment_type = $params->{payment_type};
361 my $credit_type = $params->{type} || 'PAYMENT';
362 my $item_id = $params->{item_id};
364 Koha::Exceptions::Account::RegisterRequired->throw()
365 if ( C4::Context->preference("UseCashRegisters")
366 && defined($payment_type)
367 && ( $payment_type eq 'CASH' )
368 && !defined($cash_register) );
370 my $line;
371 my $schema = Koha::Database->new->schema;
372 try {
373 $schema->txn_do(
374 sub {
376 # Insert the account line
377 $line = Koha::Account::Line->new(
379 borrowernumber => $self->{patron_id},
380 date => \'NOW()',
381 amount => $amount,
382 description => $description,
383 credit_type_code => $credit_type,
384 amountoutstanding => $amount,
385 payment_type => $payment_type,
386 note => $note,
387 manager_id => $user_id,
388 interface => $interface,
389 branchcode => $library_id,
390 register_id => $cash_register,
391 itemnumber => $item_id,
393 )->store();
395 # Record the account offset
396 my $account_offset = Koha::Account::Offset->new(
398 credit_id => $line->id,
399 type => $Koha::Account::offset_type->{$credit_type},
400 amount => $amount
402 )->store();
404 UpdateStats(
406 branch => $library_id,
407 type => lc($credit_type),
408 amount => $amount,
409 borrowernumber => $self->{patron_id},
411 ) if grep { $credit_type eq $_ } ( 'PAYMENT', 'WRITEOFF' );
413 if ( C4::Context->preference("FinesLog") ) {
414 logaction(
415 "FINES", 'CREATE',
416 $self->{patron_id},
417 Dumper(
419 action => "create_$credit_type",
420 borrowernumber => $self->{patron_id},
421 amount => $amount,
422 description => $description,
423 amountoutstanding => $amount,
424 credit_type_code => $credit_type,
425 note => $note,
426 itemnumber => $item_id,
427 manager_id => $user_id,
428 branchcode => $library_id,
431 $interface
437 catch {
438 if ( ref($_) eq 'Koha::Exceptions::Object::FKConstraint' ) {
439 if ( $_->broken_fk eq 'credit_type_code' ) {
440 Koha::Exceptions::Account::UnrecognisedType->throw(
441 error => 'Type of credit not recognised' );
443 else {
444 $_->rethrow;
449 return $line;
452 =head3 add_debit
454 This method allows adding debits to a patron's account
456 my $debit_line = Koha::Account->new({ patron_id => $patron_id })->add_debit(
458 amount => $amount,
459 description => $description,
460 note => $note,
461 user_id => $user_id,
462 interface => $interface,
463 library_id => $library_id,
464 type => $debit_type,
465 item_id => $item_id,
466 issue_id => $issue_id
470 $debit_type can be any of:
471 - ACCOUNT
472 - ACCOUNT_RENEW
473 - RESERVE_EXPIRED
474 - LOST
475 - sundry
476 - NEW_CARD
477 - OVERDUE
478 - PROCESSING
479 - RENT
480 - RENT_DAILY
481 - RENT_RENEW
482 - RENT_DAILY_RENEW
483 - RESERVE
485 =cut
487 sub add_debit {
489 my ( $self, $params ) = @_;
491 # check for mandatory params
492 my @mandatory = ( 'interface', 'type', 'amount' );
493 for my $param (@mandatory) {
494 unless ( defined( $params->{$param} ) ) {
495 Koha::Exceptions::MissingParameter->throw(
496 error => "The $param parameter is mandatory" );
500 # amount should always be a positive value
501 my $amount = $params->{amount};
502 unless ( $amount > 0 ) {
503 Koha::Exceptions::Account::AmountNotPositive->throw(
504 error => 'Debit amount passed is not positive' );
507 my $description = $params->{description} // q{};
508 my $note = $params->{note} // q{};
509 my $user_id = $params->{user_id};
510 my $interface = $params->{interface};
511 my $library_id = $params->{library_id};
512 my $debit_type = $params->{type};
513 my $item_id = $params->{item_id};
514 my $issue_id = $params->{issue_id};
515 my $offset_type = $Koha::Account::offset_type->{$debit_type} // 'Manual Debit';
517 my $line;
518 my $schema = Koha::Database->new->schema;
519 try {
520 $schema->txn_do(
521 sub {
523 # Insert the account line
524 $line = Koha::Account::Line->new(
526 borrowernumber => $self->{patron_id},
527 date => \'NOW()',
528 amount => $amount,
529 description => $description,
530 debit_type_code => $debit_type,
531 amountoutstanding => $amount,
532 payment_type => undef,
533 note => $note,
534 manager_id => $user_id,
535 interface => $interface,
536 itemnumber => $item_id,
537 issue_id => $issue_id,
538 branchcode => $library_id,
540 $debit_type eq 'OVERDUE'
541 ? ( status => 'UNRETURNED' )
542 : ()
545 )->store();
547 # Record the account offset
548 my $account_offset = Koha::Account::Offset->new(
550 debit_id => $line->id,
551 type => $offset_type,
552 amount => $amount
554 )->store();
556 if ( C4::Context->preference("FinesLog") ) {
557 logaction(
558 "FINES", 'CREATE',
559 $self->{patron_id},
560 Dumper(
562 action => "create_$debit_type",
563 borrowernumber => $self->{patron_id},
564 amount => $amount,
565 description => $description,
566 amountoutstanding => $amount,
567 debit_type_code => $debit_type,
568 note => $note,
569 itemnumber => $item_id,
570 manager_id => $user_id,
573 $interface
579 catch {
580 if ( ref($_) eq 'Koha::Exceptions::Object::FKConstraint' ) {
581 if ( $_->broken_fk eq 'debit_type_code' ) {
582 Koha::Exceptions::Account::UnrecognisedType->throw(
583 error => 'Type of debit not recognised' );
585 else {
586 $_->rethrow;
591 return $line;
594 =head3 balance
596 my $balance = $self->balance
598 Return the balance (sum of amountoutstanding columns)
600 =cut
602 sub balance {
603 my ($self) = @_;
604 return $self->lines->total_outstanding;
607 =head3 outstanding_debits
609 my $lines = Koha::Account->new({ patron_id => $patron_id })->outstanding_debits;
611 It returns the debit lines with outstanding amounts for the patron.
613 In scalar context, it returns a Koha::Account::Lines iterator. In list context, it will
614 return a list of Koha::Account::Line objects.
616 =cut
618 sub outstanding_debits {
619 my ($self) = @_;
621 return $self->lines->search(
623 amount => { '>' => 0 },
624 amountoutstanding => { '>' => 0 }
629 =head3 outstanding_credits
631 my $lines = Koha::Account->new({ patron_id => $patron_id })->outstanding_credits;
633 It returns the credit lines with outstanding amounts for the patron.
635 In scalar context, it returns a Koha::Account::Lines iterator. In list context, it will
636 return a list of Koha::Account::Line objects.
638 =cut
640 sub outstanding_credits {
641 my ($self) = @_;
643 return $self->lines->search(
645 amount => { '<' => 0 },
646 amountoutstanding => { '<' => 0 }
651 =head3 non_issues_charges
653 my $non_issues_charges = $self->non_issues_charges
655 Calculates amount immediately owing by the patron - non-issue charges.
657 Charges exempt from non-issue are:
658 * Res (holds) if HoldsInNoissuesCharge syspref is set to false
659 * Rent (rental) if RentalsInNoissuesCharge syspref is set to false
660 * Manual invoices if ManInvInNoissuesCharge syspref is set to false
662 =cut
664 sub non_issues_charges {
665 my ($self) = @_;
667 #NOTE: With bug 23049 these preferences could be moved to being attached
668 #to individual debit types to give more flexability and specificity.
669 my @not_fines;
670 push @not_fines, 'RESERVE'
671 unless C4::Context->preference('HoldsInNoissuesCharge');
672 push @not_fines, ( 'RENT', 'RENT_DAILY', 'RENT_RENEW', 'RENT_DAILY_RENEW' )
673 unless C4::Context->preference('RentalsInNoissuesCharge');
674 unless ( C4::Context->preference('ManInvInNoissuesCharge') ) {
675 my @man_inv = Koha::Account::DebitTypes->search({ is_system => 0 })->get_column('code');
676 push @not_fines, @man_inv;
679 return $self->lines->search(
681 debit_type_code => { -not_in => \@not_fines }
683 )->total_outstanding;
686 =head3 lines
688 my $lines = $self->lines;
690 Return all credits and debits for the user, outstanding or otherwise
692 =cut
694 sub lines {
695 my ($self) = @_;
697 return Koha::Account::Lines->search(
699 borrowernumber => $self->{patron_id},
704 =head3 reconcile_balance
706 $account->reconcile_balance();
708 Find outstanding credits and use them to pay outstanding debits.
709 Currently, this implicitly uses the 'First In First Out' rule for
710 applying credits against debits.
712 =cut
714 sub reconcile_balance {
715 my ($self) = @_;
717 my $outstanding_debits = $self->outstanding_debits;
718 my $outstanding_credits = $self->outstanding_credits;
720 while ( $outstanding_debits->total_outstanding > 0
721 and my $credit = $outstanding_credits->next )
723 # there's both outstanding debits and credits
724 $credit->apply( { debits => [ $outstanding_debits->as_list ] } ); # applying credit, no special offset
726 $outstanding_debits = $self->outstanding_debits;
730 return $self;
735 =head2 Name mappings
737 =head3 $offset_type
739 =cut
741 our $offset_type = {
742 'CREDIT' => 'Manual Credit',
743 'FORGIVEN' => 'Writeoff',
744 'LOST_RETURN' => 'Lost Item',
745 'PAYMENT' => 'Payment',
746 'WRITEOFF' => 'Writeoff',
747 'ACCOUNT' => 'Account Fee',
748 'ACCOUNT_RENEW' => 'Account Fee',
749 'RESERVE' => 'Reserve Fee',
750 'PROCESSING' => 'Processing Fee',
751 'LOST' => 'Lost Item',
752 'RENT' => 'Rental Fee',
753 'RENT_DAILY' => 'Rental Fee',
754 'RENT_RENEW' => 'Rental Fee',
755 'RENT_DAILY_RENEW' => 'Rental Fee',
756 'OVERDUE' => 'OVERDUE',
757 'RESERVE_EXPIRED' => 'Hold Expired'
760 =head1 AUTHORS
762 =encoding utf8
764 Kyle M Hall <kyle.m.hall@gmail.com>
765 Tomás Cohen Arazi <tomascohen@gmail.com>
766 Martin Renvoize <martin.renvoize@ptfs-europe.com>
768 =cut