Bug 28412: Add information about supported authentication methods
[koha.git] / Koha / Account / Line.pm
1 package Koha::Account::Line;
2
3 # This file is part of Koha.
4 #
5 # Koha is free software; you can redistribute it and/or modify it
6 # under the terms of the GNU General Public License as published by
7 # the Free Software Foundation; either version 3 of the License, or
8 # (at your option) any later version.
9 #
10 # Koha is distributed in the hope that it will be useful, but
11 # WITHOUT ANY WARRANTY; without even the implied warranty of
12 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 # GNU General Public License for more details.
14 #
15 # You should have received a copy of the GNU General Public License
16 # along with Koha; if not, see <http://www.gnu.org/licenses>.
17
18 use Modern::Perl;
19
20 use Data::Dumper qw( Dumper );
21
22 use C4::Log qw( logaction );
23 use C4::Overdues qw( UpdateFine );
24
25 use Koha::Account::CreditType;
26 use Koha::Account::DebitType;
27 use Koha::Account::Offsets;
28 use Koha::Database;
29 use Koha::DateUtils qw( dt_from_string );
30 use Koha::Exceptions::Account;
31 use Koha::Items;
32
33 use base qw(Koha::Object);
34
35 =encoding utf8
36
37 =head1 NAME
38
39 Koha::Account::Line - Koha accountline Object class
40
41 =head1 API
42
43 =head2 Class methods
44
45 =cut
46
47 =head3 patron
48
49 Return the patron linked to this account line
50
51 =cut
52
53 sub patron {
54     my ( $self ) = @_;
55     my $rs = $self->_result->borrowernumber;
56     return unless $rs;
57     return Koha::Patron->_new_from_dbic( $rs );
58 }
59
60 =head3 manager
61
62 Return the manager linked to this account line
63
64 =cut
65
66 sub manager {
67     my ( $self ) = @_;
68     my $rs = $self->_result->manager;
69     return unless $rs;
70     return Koha::Patron->_new_from_dbic( $rs );
71 }
72
73 =head3 item
74
75 Return the item linked to this account line if exists
76
77 =cut
78
79 sub item {
80     my ( $self ) = @_;
81     my $rs = $self->_result->itemnumber;
82     return unless $rs;
83     return Koha::Item->_new_from_dbic( $rs );
84 }
85
86 =head3 checkout
87
88 Return the checkout linked to this account line if exists
89
90 =cut
91
92 sub checkout {
93     my ( $self ) = @_;
94     return unless $self->issue_id ;
95
96     $self->{_checkout} ||= Koha::Checkouts->find( $self->issue_id );
97     $self->{_checkout} ||= Koha::Old::Checkouts->find( $self->issue_id );
98     return $self->{_checkout};
99 }
100
101 =head3 library
102
103 Returns a Koha::Library object representing where the accountline was recorded
104
105 =cut
106
107 sub library {
108     my ( $self ) = @_;
109     my $rs = $self->_result->library;
110     return unless $rs;
111     return Koha::Library->_new_from_dbic($rs);
112 }
113
114 =head3 credit_type
115
116 Return the credit_type linked to this account line
117
118 =cut
119
120 sub credit_type {
121     my ( $self ) = @_;
122     my $rs = $self->_result->credit_type_code;
123     return unless $rs;
124     return Koha::Account::CreditType->_new_from_dbic( $rs );
125 }
126
127 =head3 debit_type
128
129 Return the debit_type linked to this account line
130
131 =cut
132
133 sub debit_type {
134     my ( $self ) = @_;
135     my $rs = $self->_result->debit_type_code;
136     return unless $rs;
137     return Koha::Account::DebitType->_new_from_dbic( $rs );
138 }
139
140 =head3 credit_offsets
141
142 Return the credit_offsets linked to this account line if some exist
143
144 =cut
145
146 sub credit_offsets {
147     my ( $self, $cond, $attr ) = @_;
148     my $rs = $self->_result->search_related( 'account_offsets_credits', $cond, $attr);
149     return unless $rs;
150     return Koha::Account::Offsets->_new_from_dbic($rs);
151 }
152
153 =head3 debit_offsets
154
155 Return the debit_offsets linked to this account line if some exist
156
157 =cut
158
159 sub debit_offsets {
160     my ( $self, $cond, $attr ) = @_;
161     my $rs = $self->_result->search_related( 'account_offsets_debits', $cond, $attr);
162     return unless $rs;
163     return Koha::Account::Offsets->_new_from_dbic($rs);
164 }
165
166
167 =head3 credits
168
169   my $credits = $accountline->credits;
170   my $credits = $accountline->credits( $cond, $attr );
171
172 Return the credits linked to this account line if some exist.
173 Search conditions and attributes may be passed if you wish to filter
174 the resultant resultant resultset.
175
176 =cut
177
178 sub credits {
179     my ( $self, $cond, $attr ) = @_;
180
181     unless ( $self->is_debit ) {
182         Koha::Exceptions::Account::IsNotDebit->throw(
183             error => 'Account line ' . $self->id . ' is not a debit'
184         );
185     }
186
187     my $cond_m = { map { "credit.".$_ => $cond->{$_} } keys %{$cond}};
188     my $rs =
189       $self->_result->search_related('account_offsets_debits')
190       ->search_related( 'credit', $cond_m, $attr );
191     return unless $rs;
192     return Koha::Account::Lines->_new_from_dbic($rs);
193 }
194
195 =head3 debits
196
197   my $debits = $accountline->debits;
198   my $debits = $accountline->debits( $cond, $attr );
199
200 Return the debits linked to this account line if some exist.
201 Search conditions and attributes may be passed if you wish to filter
202 the resultant resultant resultset.
203
204 =cut
205
206 sub debits {
207     my ( $self, $cond, $attr ) = @_;
208
209     unless ( $self->is_credit ) {
210         Koha::Exceptions::Account::IsNotCredit->throw(
211             error => 'Account line ' . $self->id . ' is not a credit'
212         );
213     }
214
215     my $cond_m = { map { "debit.".$_ => $cond->{$_} } keys %{$cond}};
216     my $rs =
217       $self->_result->search_related('account_offsets_credits')
218       ->search_related( 'debit', $cond_m, $attr );
219     return unless $rs;
220     return Koha::Account::Lines->_new_from_dbic($rs);
221 }
222
223 =head3 void
224
225   $payment_accountline->void({
226       interface => $interface,
227       [ staff_id => $staff_id, branch => $branchcode ]
228   });
229
230 Used to 'void' (or reverse) a payment/credit. It will roll back any offsets
231 created by the application of this credit upon any debits and mark the credit
232 as 'void' by updating it's status to "VOID".
233
234 =cut
235
236 sub void {
237     my ($self, $params) = @_;
238
239     # Make sure it is a credit we are voiding
240     unless ( $self->is_credit ) {
241         Koha::Exceptions::Account::IsNotCredit->throw(
242             error => 'Account line ' . $self->id . 'is not a credit' );
243     }
244
245     # Make sure it is not already voided
246     if ( $self->status && $self->status eq 'VOID' ) {
247         Koha::Exceptions::Account->throw(
248             error => 'Account line ' . $self->id . 'is already void' );
249     }
250
251     # Check for mandatory parameters
252     my @mandatory = ( 'interface' );
253     for my $param (@mandatory) {
254         unless ( defined( $params->{$param} ) ) {
255             Koha::Exceptions::MissingParameter->throw(
256                 error => "The $param parameter is mandatory" );
257         }
258     }
259
260     # More mandatory parameters
261     if ( $params->{interface} eq 'intranet' ) {
262         my @optional = ( 'staff_id', 'branch' );
263         for my $param (@optional) {
264             unless ( defined( $params->{$param} ) ) {
265                 Koha::Exceptions::MissingParameter->throw( error =>
266 "The $param parameter is mandatory when interface is set to 'intranet'"
267                 );
268             }
269         }
270     }
271
272     # Find any applied offsets for the credit so we may reverse them
273     my @account_offsets =
274       Koha::Account::Offsets->search(
275         { credit_id => $self->id, amount => { '<' => 0 }  } );
276
277     my $void;
278     $self->_result->result_source->schema->txn_do(
279         sub {
280
281             # A 'void' is a 'debit'
282             $void = Koha::Account::Line->new(
283                 {
284                     borrowernumber    => $self->borrowernumber,
285                     date              => \'NOW()',
286                     debit_type_code   => 'VOID',
287                     amount            => $self->amount * -1,
288                     amountoutstanding => $self->amount * -1,
289                     manager_id        => $params->{staff_id},
290                     interface         => $params->{interface},
291                     branchcode        => $params->{branch},
292                 }
293             )->store();
294
295             # Record the creation offset
296             Koha::Account::Offset->new(
297                 {
298                     debit_id => $void->id,
299                     type     => 'CREATE',
300                     amount   => $self->amount * -1
301                 }
302             )->store();
303
304             # Link void to payment
305             $self->set({
306                 amountoutstanding => $self->amount,
307                 status => 'VOID'
308             })->store();
309             $self->apply( { debits => [$void] } );
310
311             # Reverse any applied payments
312             foreach my $account_offset (@account_offsets) {
313                 my $fee_paid =
314                   Koha::Account::Lines->find( $account_offset->debit_id );
315
316                 next unless $fee_paid;
317
318                 my $amount_paid = $account_offset->amount * -1; # amount paid is stored as a negative amount
319                 my $new_amount = $fee_paid->amountoutstanding + $amount_paid;
320                 $fee_paid->amountoutstanding($new_amount);
321                 $fee_paid->store();
322
323                 Koha::Account::Offset->new(
324                     {
325                         credit_id => $self->id,
326                         debit_id  => $fee_paid->id,
327                         amount    => $amount_paid,
328                         type      => 'VOID',
329                     }
330                 )->store();
331             }
332
333             if ( C4::Context->preference("FinesLog") ) {
334                 logaction(
335                     "FINES", 'VOID',
336                     $self->borrowernumber,
337                     Dumper(
338                         {
339                             action         => 'void_payment',
340                             borrowernumber => $self->borrowernumber,
341                             amount            => $self->amount,
342                             amountoutstanding => $self->amountoutstanding,
343                             description       => $self->description,
344                             credit_type_code  => $self->credit_type_code,
345                             payment_type      => $self->payment_type,
346                             note              => $self->note,
347                             itemnumber        => $self->itemnumber,
348                             manager_id        => $self->manager_id,
349                             offsets =>
350                               [ map { $_->unblessed } @account_offsets ],
351                         }
352                     )
353                 );
354             }
355         }
356     );
357
358     $void->discard_changes;
359     return $void;
360 }
361
362 =head3 cancel
363
364   $debit_accountline->cancel();
365
366 Cancel a charge. It will mark the debit as 'cancelled' by updating its
367 status to 'CANCELLED'.
368
369 Charges that have been fully or partially paid cannot be cancelled.
370
371 Returns the cancellation accountline.
372
373 =cut
374
375 sub cancel {
376     my ( $self, $params ) = @_;
377
378     # Make sure it is a charge we are reducing
379     unless ( $self->is_debit ) {
380         Koha::Exceptions::Account::IsNotDebit->throw(
381             error => 'Account line ' . $self->id . 'is not a debit' );
382     }
383     if ( $self->debit_type_code eq 'PAYOUT' ) {
384         Koha::Exceptions::Account::IsNotDebit->throw(
385             error => 'Account line ' . $self->id . 'is a payout' );
386     }
387
388     # Make sure it is not already cancelled
389     if ( $self->status && $self->status eq 'CANCELLED' ) {
390         Koha::Exceptions::Account->throw(
391             error => 'Account line ' . $self->id . 'is already cancelled' );
392     }
393
394     # Make sure it has not be paid yet
395     if ( $self->amount != $self->amountoutstanding ) {
396         Koha::Exceptions::Account->throw(
397             error => 'Account line ' . $self->id . 'is already offset' );
398     }
399
400     # Check for mandatory parameters
401     my @mandatory = ( 'staff_id', 'branch' );
402     for my $param (@mandatory) {
403         unless ( defined( $params->{$param} ) ) {
404             Koha::Exceptions::MissingParameter->throw(
405                 error => "The $param parameter is mandatory" );
406         }
407     }
408
409     my $cancellation;
410     $self->_result->result_source->schema->txn_do(
411         sub {
412
413             # A 'cancellation' is a 'credit'
414             $cancellation = Koha::Account::Line->new(
415                 {
416                     date              => \'NOW()',
417                     amount            => 0 - $self->amount,
418                     credit_type_code  => 'CANCELLATION',
419                     status            => 'ADDED',
420                     amountoutstanding => 0 - $self->amount,
421                     manager_id        => $params->{staff_id},
422                     borrowernumber    => $self->borrowernumber,
423                     interface         => 'intranet',
424                     branchcode        => $params->{branch},
425                 }
426             )->store();
427
428             my $cancellation_offset = Koha::Account::Offset->new(
429                 {
430                     credit_id => $cancellation->accountlines_id,
431                     type      => 'CREATE',
432                     amount    => 0 - $self->amount
433                 }
434             )->store();
435
436             # Link cancellation to charge
437             $cancellation->apply( { debits => [$self] } );
438             $cancellation->status('APPLIED')->store();
439
440             # Update status of original debit
441             $self->status('CANCELLED')->store;
442         }
443     );
444
445     $cancellation->discard_changes;
446     return $cancellation;
447 }
448
449 =head3 reduce
450
451   $charge_accountline->reduce({
452       reduction_type => $reduction_type
453   });
454
455 Used to 'reduce' a charge/debit by adding a credit to offset against the amount
456 outstanding.
457
458 May be used to apply a discount whilst retaining the original debit amounts or
459 to apply a full or partial refund for example when a lost item is found and
460 returned.
461
462 It will immediately be applied to the given debit unless the debit has already
463 been paid, in which case a 'zero' offset will be added to maintain a link to
464 the debit but the outstanding credit will be left so it may be applied to other
465 debts.
466
467 Reduction type may be one of:
468
469 * REFUND
470 * DISCOUNT
471
472 Returns the reduction accountline (which will be a credit)
473
474 =cut
475
476 sub reduce {
477     my ( $self, $params ) = @_;
478
479     # Make sure it is a charge we are reducing
480     unless ( $self->is_debit ) {
481         Koha::Exceptions::Account::IsNotDebit->throw(
482             error => 'Account line ' . $self->id . 'is not a debit' );
483     }
484     if ( $self->debit_type_code eq 'PAYOUT' ) {
485         Koha::Exceptions::Account::IsNotDebit->throw(
486             error => 'Account line ' . $self->id . 'is a payout' );
487     }
488
489     # Check for mandatory parameters
490     my @mandatory = ( 'interface', 'reduction_type', 'amount' );
491     for my $param (@mandatory) {
492         unless ( defined( $params->{$param} ) ) {
493             Koha::Exceptions::MissingParameter->throw(
494                 error => "The $param parameter is mandatory" );
495         }
496     }
497
498     # More mandatory parameters
499     if ( $params->{interface} eq 'intranet' ) {
500         my @optional = ( 'staff_id', 'branch' );
501         for my $param (@optional) {
502             unless ( defined( $params->{$param} ) ) {
503                 Koha::Exceptions::MissingParameter->throw( error =>
504 "The $param parameter is mandatory when interface is set to 'intranet'"
505                 );
506             }
507         }
508     }
509
510     # Make sure the reduction isn't more than the original
511     my $original = $self->amount;
512     Koha::Exceptions::Account::AmountNotPositive->throw(
513         error => 'Reduce amount passed is not positive' )
514       unless ( $params->{amount} > 0 );
515     Koha::Exceptions::ParameterTooHigh->throw( error =>
516 "Amount to reduce ($params->{amount}) is higher than original amount ($original)"
517     ) unless ( $original >= $params->{amount} );
518     my $reduced =
519       $self->credits( { credit_type_code => [ 'DISCOUNT', 'REFUND' ] } )->total;
520     Koha::Exceptions::ParameterTooHigh->throw( error =>
521 "Combined reduction ($params->{amount} + $reduced) is higher than original amount ("
522           . abs($original)
523           . ")" )
524       unless ( $original >= ( $params->{amount} + abs($reduced) ) );
525
526     my $status = { 'REFUND' => 'REFUNDED', 'DISCOUNT' => 'DISCOUNTED' };
527
528     my $reduction;
529     $self->_result->result_source->schema->txn_do(
530         sub {
531
532             # A 'reduction' is a 'credit'
533             $reduction = Koha::Account::Line->new(
534                 {
535                     date              => \'NOW()',
536                     amount            => 0 - $params->{amount},
537                     credit_type_code  => $params->{reduction_type},
538                     status            => 'ADDED',
539                     amountoutstanding => 0 - $params->{amount},
540                     manager_id        => $params->{staff_id},
541                     borrowernumber    => $self->borrowernumber,
542                     interface         => $params->{interface},
543                     branchcode        => $params->{branch},
544                 }
545             )->store();
546
547             my $reduction_offset = Koha::Account::Offset->new(
548                 {
549                     credit_id => $reduction->accountlines_id,
550                     type      => 'CREATE',
551                     amount    => 0 - $params->{amount}
552                 }
553             )->store();
554
555             # Link reduction to charge (and apply as required)
556             my $debit_outstanding = $self->amountoutstanding;
557             if ( $debit_outstanding >= $params->{amount} ) {
558
559                 $reduction->apply( { debits => [$self] } );
560                 $reduction->status('APPLIED')->store();
561             }
562             else {
563
564                 # Zero amount offset used to link original 'debit' to
565                 # reduction 'credit'
566                 my $link_reduction_offset = Koha::Account::Offset->new(
567                     {
568                         credit_id => $reduction->accountlines_id,
569                         debit_id  => $self->accountlines_id,
570                         type      => 'APPLY',
571                         amount    => 0
572                     }
573                 )->store();
574             }
575
576             # Update status of original debit
577             $self->status( $status->{ $params->{reduction_type} } )->store;
578         }
579     );
580
581     $reduction->discard_changes;
582     return $reduction;
583 }
584
585 =head3 apply
586
587     my $debits = $account->outstanding_debits;
588     my $credit = $credit->apply( { debits => $debits } );
589
590 Applies the credit to a given debits array reference.
591
592 =head4 arguments hashref
593
594 =over 4
595
596 =item debits - Koha::Account::Lines object set of debits
597
598 =back
599
600 =cut
601
602 sub apply {
603     my ( $self, $params ) = @_;
604
605     my $debits      = $params->{debits};
606
607     unless ( $self->is_credit ) {
608         Koha::Exceptions::Account::IsNotCredit->throw(
609             error => 'Account line ' . $self->id . ' is not a credit'
610         );
611     }
612
613     my $available_credit = $self->amountoutstanding * -1;
614
615     unless ( $available_credit > 0 ) {
616         Koha::Exceptions::Account::NoAvailableCredit->throw(
617             error => 'Outstanding credit is ' . $available_credit . ' and cannot be applied'
618         );
619     }
620
621     my $schema = Koha::Database->new->schema;
622
623     $schema->txn_do( sub {
624         for my $debit ( @{$debits} ) {
625
626             unless ( $debit->is_debit ) {
627                 Koha::Exceptions::Account::IsNotDebit->throw(
628                     error => 'Account line ' . $debit->id . 'is not a debit'
629                 );
630             }
631             my $amount_to_cancel;
632             my $owed = $debit->amountoutstanding;
633
634             if ( $available_credit >= $owed ) {
635                 $amount_to_cancel = $owed;
636             }
637             else {    # $available_credit < $debit->amountoutstanding
638                 $amount_to_cancel = $available_credit;
639             }
640
641             # record the account offset
642             Koha::Account::Offset->new(
643                 {   credit_id => $self->id,
644                     debit_id  => $debit->id,
645                     amount    => $amount_to_cancel * -1,
646                     type      => 'APPLY'
647                 }
648             )->store();
649
650             $available_credit -= $amount_to_cancel;
651
652             $self->amountoutstanding( $available_credit * -1 )->store;
653             $debit->amountoutstanding( $owed - $amount_to_cancel )->store;
654
655             # Attempt to renew the item associated with this debit if
656             # appropriate
657             if ( $self->credit_type_code ne 'FORGIVEN' && $debit->is_renewable ) {
658                 my $outcome = $debit->renew_item( { interface => $params->{interface} } );
659                 $self->add_message(
660                     {
661                         type    => 'info',
662                         message => 'renewal',
663                         payload => $outcome
664                     }
665                 ) if $outcome;
666             }
667             $debit->discard_changes; # Refresh values from DB to clear floating point remainders
668
669             # Same logic exists in Koha::Account::pay
670             if (
671                 C4::Context->preference('MarkLostItemsAsReturned') =~
672                 m|onpayment|
673                 && $debit->debit_type_code
674                 && $debit->debit_type_code eq 'LOST'
675                 && $debit->amountoutstanding == 0
676                 && $debit->itemnumber
677                 && !(
678                        $self->credit_type_code eq 'LOST_FOUND'
679                     && $self->itemnumber == $debit->itemnumber
680                 )
681               )
682             {
683                 C4::Circulation::ReturnLostItem( $self->borrowernumber,
684                     $debit->itemnumber );
685             }
686
687             last if $available_credit == 0;
688         }
689     });
690
691     return $self;
692 }
693
694 =head3 payout
695
696   $credit_accountline->payout(
697     {
698         payout_type => $payout_type,
699         register_id => $register_id,
700         staff_id    => $staff_id,
701         interface   => 'intranet',
702         amount      => $amount
703     }
704   );
705
706 Used to 'pay out' a credit to a user.
707
708 Payout type may be one of any existing payment types
709
710 Returns the payout debit line that is created via this transaction.
711
712 =cut
713
714 sub payout {
715     my ( $self, $params ) = @_;
716
717     # Make sure it is a credit we are paying out
718     unless ( $self->is_credit ) {
719         Koha::Exceptions::Account::IsNotCredit->throw(
720             error => 'Account line ' . $self->id . ' is not a credit' );
721     }
722
723     # Check for mandatory parameters
724     my @mandatory =
725       ( 'interface', 'staff_id', 'branch', 'payout_type', 'amount' );
726     for my $param (@mandatory) {
727         unless ( defined( $params->{$param} ) ) {
728             Koha::Exceptions::MissingParameter->throw(
729                 error => "The $param parameter is mandatory" );
730         }
731     }
732
733     # Make sure there is outstanding credit to pay out
734     my $outstanding = -1 * $self->amountoutstanding;
735     my $amount =
736       $params->{amount} ? $params->{amount} : $outstanding;
737     Koha::Exceptions::Account::AmountNotPositive->throw(
738         error => 'Payout amount passed is not positive' )
739       unless ( $amount > 0 );
740     Koha::Exceptions::ParameterTooHigh->throw(
741         error => "Amount to payout ($amount) is higher than amountoutstanding ($outstanding)" )
742       unless ($outstanding >= $amount );
743
744     # Make sure we record the cash register for cash transactions
745     Koha::Exceptions::Account::RegisterRequired->throw()
746       if ( C4::Context->preference("UseCashRegisters")
747         && defined( $params->{payout_type} )
748         && ( $params->{payout_type} eq 'CASH' )
749         && !defined( $params->{cash_register} ) );
750
751     my $payout;
752     $self->_result->result_source->schema->txn_do(
753         sub {
754
755             # A 'payout' is a 'debit'
756             $payout = Koha::Account::Line->new(
757                 {
758                     date              => \'NOW()',
759                     amount            => $amount,
760                     debit_type_code   => 'PAYOUT',
761                     payment_type      => $params->{payout_type},
762                     amountoutstanding => $amount,
763                     manager_id        => $params->{staff_id},
764                     borrowernumber    => $self->borrowernumber,
765                     interface         => $params->{interface},
766                     branchcode        => $params->{branch},
767                     register_id       => $params->{cash_register}
768                 }
769             )->store();
770
771             my $payout_offset = Koha::Account::Offset->new(
772                 {
773                     debit_id => $payout->accountlines_id,
774                     type     => 'CREATE',
775                     amount   => $amount
776                 }
777             )->store();
778
779             $self->apply( { debits => [$payout] } );
780             $self->status('PAID')->store;
781         }
782     );
783
784     $payout->discard_changes;
785     return $payout;
786 }
787
788 =head3 adjust
789
790 This method allows updating a debit or credit on a patron's account
791
792     $account_line->adjust(
793         {
794             amount    => $amount,
795             type      => $update_type,
796             interface => $interface
797         }
798     );
799
800 $update_type can be any of:
801   - overdue_update
802
803 Authors Note: The intention here is that this method is only used
804 to adjust accountlines where the final amount is not yet known/fixed.
805 Incrementing fines are the only existing case at the time of writing,
806 all other forms of 'adjustment' should be recorded as distinct credits
807 or debits and applied, via an offset, to the corresponding debit or credit.
808
809 =cut
810
811 sub adjust {
812     my ( $self, $params ) = @_;
813
814     my $amount       = $params->{amount};
815     my $update_type  = $params->{type};
816     my $interface    = $params->{interface};
817
818     unless ( exists($Koha::Account::Line::allowed_update->{$update_type}) ) {
819         Koha::Exceptions::Account::UnrecognisedType->throw(
820             error => 'Update type not recognised'
821         );
822     }
823
824     my $debit_type_code = $self->debit_type_code;
825     my $account_status  = $self->status;
826     unless (
827         (
828             exists(
829                 $Koha::Account::Line::allowed_update->{$update_type}
830                   ->{$debit_type_code}
831             )
832             && ( $Koha::Account::Line::allowed_update->{$update_type}
833                 ->{$debit_type_code} eq $account_status )
834         )
835       )
836     {
837         Koha::Exceptions::Account::UnrecognisedType->throw(
838             error => 'Update type not allowed on this debit_type' );
839     }
840
841     my $schema = Koha::Database->new->schema;
842
843     $schema->txn_do(
844         sub {
845
846             my $amount_before             = $self->amount;
847             my $amount_outstanding_before = $self->amountoutstanding;
848             my $difference                = $amount - $amount_before;
849             my $new_outstanding           = $amount_outstanding_before + $difference;
850
851             my $offset_type = $debit_type_code;
852             $offset_type .= ( $difference > 0 ) ? "_INCREASE" : "_DECREASE";
853
854             # Catch cases that require patron refunds
855             if ( $new_outstanding < 0 ) {
856                 my $account =
857                   Koha::Patrons->find( $self->borrowernumber )->account;
858                 my $credit = $account->add_credit(
859                     {
860                         amount      => $new_outstanding * -1,
861                         type        => 'OVERPAYMENT',
862                         interface   => $interface,
863                         ( $update_type eq 'overdue_update' ? ( item_id => $self->itemnumber ) : ()),
864                     }
865                 );
866                 $new_outstanding = 0;
867             }
868
869             # Update the account line
870             $self->set(
871                 {
872                     date              => \'NOW()',
873                     amount            => $amount,
874                     amountoutstanding => $new_outstanding,
875                 }
876             )->store();
877
878             # Record the account offset
879             my $account_offset = Koha::Account::Offset->new(
880                 {
881                     debit_id => $self->id,
882                     type     => $offset_type,
883                     amount   => $difference
884                 }
885             )->store();
886
887             if ( C4::Context->preference("FinesLog") ) {
888                 logaction(
889                     "FINES", 'UPDATE', #undef becomes UPDATE in UpdateFine
890                     $self->borrowernumber,
891                     Dumper(
892                         {   action            => $update_type,
893                             borrowernumber    => $self->borrowernumber,
894                             amount            => $amount,
895                             description       => undef,
896                             amountoutstanding => $new_outstanding,
897                             debit_type_code   => $self->debit_type_code,
898                             note              => undef,
899                             itemnumber        => $self->itemnumber,
900                             manager_id        => undef,
901                         }
902                     )
903                 ) if ( $update_type eq 'overdue_update' );
904             }
905         }
906     );
907
908     return $self;
909 }
910
911 =head3 is_credit
912
913     my $bool = $line->is_credit;
914
915 =cut
916
917 sub is_credit {
918     my ($self) = @_;
919
920     return defined $self->credit_type_code;
921 }
922
923 =head3 is_debit
924
925     my $bool = $line->is_debit;
926
927 =cut
928
929 sub is_debit {
930     my ($self) = @_;
931
932     return !$self->is_credit;
933 }
934
935 =head3 to_api_mapping
936
937 This method returns the mapping for representing a Koha::Account::Line object
938 on the API.
939
940 =cut
941
942 sub to_api_mapping {
943     return {
944         accountlines_id   => 'account_line_id',
945         credit_number     => undef,
946         credit_type_code  => 'credit_type',
947         debit_type_code   => 'debit_type',
948         amountoutstanding => 'amount_outstanding',
949         borrowernumber    => 'patron_id',
950         branchcode        => 'library_id',
951         issue_id          => 'checkout_id',
952         itemnumber        => 'item_id',
953         manager_id        => 'user_id',
954         note              => 'internal_note',
955         register_id       => 'cash_register_id',
956     };
957
958 }
959
960 =head3 is_renewable
961
962     my $bool = $line->is_renewable;
963
964 =cut
965
966 sub is_renewable {
967     my ($self) = @_;
968
969     return (
970         $self->amountoutstanding == 0 &&
971         $self->debit_type_code &&
972         $self->debit_type_code eq 'OVERDUE' &&
973         $self->status &&
974         $self->status eq 'UNRETURNED' &&
975         $self->item &&
976         $self->patron
977     ) ? 1 : 0;
978 }
979
980 =head3 renew_item
981
982     my $renew_result = $line->renew_item;
983
984 Conditionally attempt to renew an item and return the outcome. This is
985 as a consequence of the fine on an item being fully paid off.
986 Caller must call is_renewable before.
987
988 =cut
989
990 sub renew_item {
991     my ($self, $params) = @_;
992
993     my $outcome = {};
994
995     # We want to reject the call to renew if:
996     # - The RenewAccruingItemWhenPaid syspref is off
997     # OR
998     # - The RenewAccruingItemInOpac syspref is off
999     # - There is an interface param passed and it's value is 'opac'
1000
1001     if (
1002         !C4::Context->preference('RenewAccruingItemWhenPaid') ||
1003         (
1004             !C4::Context->preference('RenewAccruingItemInOpac') &&
1005             $params->{interface} &&
1006             $params->{interface} eq 'opac'
1007         )
1008     ) {
1009         return;
1010     }
1011
1012     my $itemnumber = $self->item->itemnumber;
1013     my $borrowernumber = $self->patron->borrowernumber;
1014     my ( $can_renew, $error ) = C4::Circulation::CanBookBeRenewed(
1015         $borrowernumber,
1016         $itemnumber
1017     );
1018     if ( $can_renew ) {
1019         my $due_date = C4::Circulation::AddRenewal(
1020             $borrowernumber,
1021             $itemnumber,
1022             $self->{branchcode},
1023             undef,
1024             undef,
1025             1
1026         );
1027         return {
1028             itemnumber => $itemnumber,
1029             due_date   => $due_date,
1030             success    => 1
1031         };
1032     } else {
1033         return {
1034             itemnumber => $itemnumber,
1035             error      => $error,
1036             success    => 0
1037         };
1038     }
1039
1040 }
1041
1042 =head3 store
1043
1044 Specific store method to generate credit number before saving
1045
1046 =cut
1047
1048 sub store {
1049     my ($self) = @_;
1050
1051     my $AutoCreditNumber = C4::Context->preference('AutoCreditNumber');
1052     my $credit_number_enabled = $self->is_credit && $self->credit_type->credit_number_enabled;
1053
1054     if ($AutoCreditNumber && $credit_number_enabled && !$self->in_storage) {
1055         if (defined $self->credit_number) {
1056             Koha::Exceptions::Account->throw('AutoCreditNumber is enabled but credit_number is already defined');
1057         }
1058
1059         my $rs = Koha::Database->new->schema->resultset($self->_type);
1060
1061         if ($AutoCreditNumber eq 'incremental') {
1062             my $max = $rs->search({
1063                 credit_number => { -regexp => '^[0-9]+$' }
1064             }, {
1065                 select => \'CAST(credit_number AS UNSIGNED)',
1066                 as => ['credit_number'],
1067             })->get_column('credit_number')->max;
1068             $max //= 0;
1069             $self->credit_number($max + 1);
1070         } elsif ($AutoCreditNumber eq 'annual') {
1071             my $now = dt_from_string;
1072             my $prefix = sprintf('%d-', $now->year);
1073             my $max = $rs->search({
1074                 -and => [
1075                     credit_number => { -regexp => '[0-9]{4}$' },
1076                     credit_number => { -like => "$prefix%" },
1077                 ],
1078             })->get_column('credit_number')->max;
1079             $max //= $prefix . '0000';
1080             my $incr = substr($max, length $prefix);
1081             $self->credit_number(sprintf('%s%04d', $prefix, $incr + 1));
1082         } elsif ($AutoCreditNumber eq 'branchyyyymmincr') {
1083             my $userenv = C4::Context->userenv;
1084             if ($userenv) {
1085                 my $branch = $userenv->{branch};
1086                 my $now = dt_from_string;
1087                 my $prefix = sprintf('%s%d%02d', $branch, $now->year, $now->month);
1088                 my $pattern = $prefix;
1089                 $pattern =~ s/([\?%_])/\\$1/g;
1090                 my $max = $rs->search({
1091                     -and => [
1092                         credit_number => { -regexp => '[0-9]{4}$' },
1093                         credit_number => { -like => "$pattern%" },
1094                     ],
1095                 })->get_column('credit_number')->max;
1096                 $max //= $prefix . '0000';
1097                 my $incr = substr($max, length $prefix);
1098                 $self->credit_number(sprintf('%s%04d', $prefix, $incr + 1));
1099             }
1100         }
1101     }
1102
1103     return $self->SUPER::store();
1104 }
1105
1106 =head2 Internal methods
1107
1108 =cut
1109
1110 =head3 _type
1111
1112 =cut
1113
1114 sub _type {
1115     return 'Accountline';
1116 }
1117
1118 1;
1119
1120 =head2 Name mappings
1121
1122 =head3 $allowed_update
1123
1124 =cut
1125
1126 our $allowed_update = { 'overdue_update' => { 'OVERDUE' => 'UNRETURNED' } };
1127
1128 =head1 AUTHORS
1129
1130 Kyle M Hall <kyle@bywatersolutions.com >
1131 Tom├ís Cohen Arazi <tomascohen@theke.io>
1132 Martin Renvoize <martin.renvoize@ptfs-europe.com>
1133
1134 =cut