FS/FS/cust_credit_bill_pkg.pm

   1 package FS::cust_credit_bill_pkg;
   2 use base qw( FS::cust_main_Mixin FS::Record );
   3
   4 use strict;
   5 use FS::Record qw( qsearch qsearchs dbh );
   6 use FS::cust_bill_pkg_tax_location;
   7 use FS::cust_bill_pkg_tax_rate_location;
   8 use FS::cust_tax_exempt_pkg;
   9
  10 =head1 NAME
  11
  12 FS::cust_credit_bill_pkg - Object methods for cust_credit_bill_pkg records
  13
  14 =head1 SYNOPSIS
  15
  16   use FS::cust_credit_bill_pkg;
  17
  18   $record = new FS::cust_credit_bill_pkg \%hash;
  19   $record = new FS::cust_credit_bill_pkg { 'column' => 'value' };
  20
  21   $error = $record->insert;
  22
  23   $error = $new_record->replace($old_record);
  24
  25   $error = $record->delete;
  26
  27   $error = $record->check;
  28
  29 =head1 DESCRIPTION
  30
  31 An FS::cust_credit_bill_pkg object represents application of a credit (see
  32 L<FS::cust_credit_bill>) to a specific line item within an invoice
  33 (see L<FS::cust_bill_pkg>).  FS::cust_credit_bill_pkg inherits from FS::Record.
  34 The following fields are currently supported:
  35
  36 =over 4
  37
  38 =item creditbillpkgnum -  primary key
  39
  40 =item creditbillnum - Credit application to the overall invoice (see L<FS::cust_credit::bill>)
  41
  42 =item billpkgnum - Line item to which credit is applied (see L<FS::cust_bill_pkg>)
  43
  44 =item amount - Amount of the credit applied to this line item.
  45
  46 =item setuprecur - 'setup' or 'recur', designates whether the payment was applied to the setup or recurring portion of the line item.
  47
  48 =item sdate - starting date of recurring fee
  49
  50 =item edate - ending date of recurring fee
  51
  52 =back
  53
  54 sdate and edate are specified as UNIX timestamps; see L<perlfunc/"time">.  Also
  55 see L<Time::Local> and L<Date::Parse> for conversion functions.
  56
  57 =head1 METHODS
  58
  59 =over 4
  60
  61 =item new HASHREF
  62
  63 Creates a new example.  To add the example to the database, see L<"insert">.
  64
  65 Note that this stores the hash reference, not a distinct copy of the hash it
  66 points to.  You can ask the object for a copy with the I<hash> method.
  67
  68 =cut
  69
  70 # the new method can be inherited from FS::Record, if a table method is defined
  71
  72 sub table { 'cust_credit_bill_pkg'; }
  73
  74 =item insert
  75
  76 Adds this record to the database.  If there is an error, returns the error,
  77 otherwise returns false.
  78
  79 =cut
  80
  81 sub insert {
  82   my $self = shift;
  83
  84   local $SIG{HUP} = 'IGNORE';
  85   local $SIG{INT} = 'IGNORE';
  86   local $SIG{QUIT} = 'IGNORE';
  87   local $SIG{TERM} = 'IGNORE';
  88   local $SIG{TSTP} = 'IGNORE';
  89   local $SIG{PIPE} = 'IGNORE';
  90
  91   my $oldAutoCommit = $FS::UID::AutoCommit;
  92   local $FS::UID::AutoCommit = 0;
  93   my $dbh = dbh;
  94
  95   my $error = $self->SUPER::insert;
  96   if ( $error ) {
  97     $dbh->rollback if $oldAutoCommit;
  98     return $error;
  99   }
 100
 101   my $cust_bill_pkg = $self->cust_bill_pkg;
 102   #'payable' is the amount charged (either setup or recur)
 103   # minus any credit applications, including this one
 104   my $payable = $cust_bill_pkg->payable($self->setuprecur);
 105   my $part_pkg = $cust_bill_pkg->part_pkg;
 106   my $freq = $cust_bill_pkg->freq;
 107   unless ($freq) {
 108     $freq = $part_pkg ? ($part_pkg->freq || 1) : 1;#fallback.. assumes unchanged
 109   }
 110   my $taxable_per_month = sprintf("%.2f", $payable / $freq );
 111   my $credit_per_month = sprintf("%.2f", $self->amount / $freq ); #pennies?
 112
 113   if ($taxable_per_month >= 0) {  #panic if its subzero?
 114     my $groupby = join(',',
 115       qw(taxnum year month exempt_monthly exempt_cust
 116          exempt_cust_taxname exempt_setup exempt_recur));
 117     my $sum = 'SUM(amount)';
 118     my @exemptions = qsearch(
 119       {
 120         'select'    => "$groupby, $sum AS amount",
 121         'table'     => 'cust_tax_exempt_pkg',
 122         'hashref'   => { billpkgnum => $self->billpkgnum },
 123         'extra_sql' => "GROUP BY $groupby HAVING $sum > 0",
 124       }
 125     );
 126     # each $exemption is now the sum of all monthly exemptions applied to
 127     # this line item for a particular taxnum and month.
 128     foreach my $exemption ( @exemptions ) {
 129       my $amount = 0;
 130       if ( $exemption->exempt_monthly ) {
 131         # finite exemptions
 132         # $taxable_per_month is AFTER inserting the credit application, so
 133         # if it's still larger than the exemption, we don't need to adjust
 134         next if $taxable_per_month >= $exemption->amount;
 135         # the amount of 'excess' exemption already in place (above the
 136         # remaining charged amount).  We'll de-exempt that much, or the
 137         # amount of the new credit, whichever is smaller.
 138         $amount = $exemption->amount - $taxable_per_month;
 139         # $amount is the amount of 'excess' exemption already existing
 140         # (above the remaining taxable charge amount).  We'll "de-exempt"
 141         # that much, or the amount of the new credit, whichever is smaller.
 142         if ($amount > $credit_per_month) {
 143                "cust_bill_pkg ". $self->billpkgnum. "  Reducing.\n";
 144           $amount = $credit_per_month;
 145         }
 146       } elsif ( $exemption->exempt_setup or $exemption->exempt_recur ) {
 147         # package defined exemptions: may be setup only, recur only, or both
 148         my $method = 'exempt_'.$self->setuprecur;
 149         if ( $exemption->$method ) {
 150           # then it's exempt from the portion of the charge that this
 151           # credit is being applied to
 152           $amount = $self->amount;
 153         }
 154       } else {
 155         # other types of exemptions: always equal to the amount of
 156         # the charge
 157         $amount = $self->amount;
 158       }
 159       next if $amount == 0;
 160
 161       # create a negative exemption
 162       my $cust_tax_exempt_pkg = new FS::cust_tax_exempt_pkg {
 163          $exemption->hash, # for exempt_ flags, taxnum, month/year
 164         'billpkgnum'       => $self->billpkgnum,
 165         'creditbillpkgnum' => $self->creditbillpkgnum,
 166         'amount'           => sprintf('%.2f', 0-$amount),
 167       };
 168
 169       if ( $cust_tax_exempt_pkg->cust_main_county ) {
 170
 171         my $error = $cust_tax_exempt_pkg->insert;
 172         if ( $error ) {
 173           $dbh->rollback if $oldAutoCommit;
 174           return "error inserting cust_tax_exempt_pkg: $error";
 175         }
 176
 177       }
 178
 179     } #foreach $exemption
 180   }
 181
 182   $dbh->commit or die $dbh->errstr if $oldAutoCommit;
 183  '';
 184
 185 }
 186
 187 #helper functions for above
 188 sub _is_taxable {
 189   my $self = shift;
 190   my $part_pkg = $self->cust_bill_pkg->part_pkg;
 191
 192   return 0 unless $part_pkg; #XXX fails for tax on tax
 193
 194   my $method = $self->setuprecur. 'tax';
 195   return 0 if $part_pkg->$method =~ /^Y$/i;
 196
 197   if ($self->billpkgtaxlocationnum) {
 198     my $location_object = $self->cust_bill_pkg_tax_Xlocation;
 199     my $tax_object = $location_object->cust_main_county;
 200     return 0 if $tax_object && $self->tax_object->$method =~ /^Y$/i;
 201   } #elsif ($self->billpkgtaxratelocationnum) { ... }
 202
 203   1;
 204 }
 205
 206 =item delete
 207
 208 Delete this record from the database.
 209
 210 =cut
 211
 212 sub delete {
 213   my $self = shift;
 214
 215   local $SIG{HUP} = 'IGNORE';
 216   local $SIG{INT} = 'IGNORE';
 217   local $SIG{QUIT} = 'IGNORE';
 218   local $SIG{TERM} = 'IGNORE';
 219   local $SIG{TSTP} = 'IGNORE';
 220   local $SIG{PIPE} = 'IGNORE';
 221
 222   my $oldAutoCommit = $FS::UID::AutoCommit;
 223   local $FS::UID::AutoCommit = 0;
 224   my $dbh = dbh;
 225
 226   my @negative_exemptions = qsearch('cust_tax_exempt_pkg', {
 227       'creditbillpkgnum' => $self->creditbillpkgnum
 228   });
 229
 230   # de-anti-exempt those negative exemptions
 231   my $error;
 232   foreach (@negative_exemptions) {
 233     $error = $_->delete;
 234     if ( $error ) {
 235       $dbh->rollback if $oldAutoCommit;
 236       return $error;
 237     }
 238   }
 239
 240   $error = $self->SUPER::delete(@_);
 241   if ( $error ) {
 242     $dbh->rollback if $oldAutoCommit;
 243     return $error;
 244   }
 245
 246   $dbh->commit or die $dbh->errstr if $oldAutoCommit;
 247
 248   '';
 249
 250 }
 251
 252 =item replace OLD_RECORD
 253
 254 Replaces the OLD_RECORD with this one in the database.  If there is an error,
 255 returns the error, otherwise returns false.
 256
 257 =cut
 258
 259 # the replace method can be inherited from FS::Record
 260
 261 =item check
 262
 263 Checks all fields to make sure this is a valid credit applicaiton.  If there is
 264 an error, returns the error, otherwise returns false.  Called by the insert
 265 and replace methods.
 266
 267 =cut
 268
 269 # the check method should currently be supplied - FS::Record contains some
 270 # data checking routines
 271
 272 sub check {
 273   my $self = shift;
 274
 275   my $error =
 276     $self->ut_numbern('creditbillpkgnum')
 277     || $self->ut_foreign_key('creditbillnum', 'cust_credit_bill', 'creditbillnum')
 278     || $self->ut_foreign_key('billpkgnum', 'cust_bill_pkg', 'billpkgnum' )
 279     || $self->ut_foreign_keyn('billpkgtaxlocationnum',
 280                               'cust_bill_pkg_tax_location',
 281                               'billpkgtaxlocationnum')
 282     || $self->ut_foreign_keyn('billpkgtaxratelocationnum',
 283                               'cust_bill_pkg_tax_rate_location',
 284                               'billpkgtaxratelocationnum')
 285     || $self->ut_money('amount')
 286     || $self->ut_enum('setuprecur', [ 'setup', 'recur' ] )
 287     || $self->ut_numbern('sdate')
 288     || $self->ut_numbern('edate')
 289   ;
 290   return $error if $error;
 291
 292   $self->SUPER::check;
 293 }
 294
 295 sub cust_bill_pkg_tax_Xlocation {
 296   my $self = shift;
 297   if ($self->billpkgtaxlocationnum) {
 298     return qsearchs(
 299       'cust_bill_pkg_tax_location',
 300       { 'billpkgtaxlocationnum' => $self->billpkgtaxlocationnum },
 301     );
 302
 303   } elsif ($self->billpkgtaxratelocationnum) {
 304     return qsearchs(
 305       'cust_bill_pkg_tax_rate_location',
 306       { 'billpkgtaxratelocationnum' => $self->billpkgtaxratelocationnum },
 307     );
 308   } else {
 309     return undef;
 310   }
 311 }
 312
 313 =back
 314
 315 =head1 BUGS
 316
 317 B<setuprecur> field is a kludge to compensate for cust_bill_pkg having separate
 318 setup and recur fields.  It should be removed once that's fixed.
 319
 320 B<insert> method used to assume that the frequency of the package associated
 321 with the associated line item remained unchanged during the lifetime of the
 322 system.  That is still used as a fallback.  It may get the tax exemption
 323 adjustments wrong if package definitions change frequency.  The presense of
 324 delete methods in FS::cust_main_county and FS::tax_rate makes crediting of
 325 old "texas tax" unreliable in the presense of changing taxes.  Explicit tax
 326 credit requests?  Carry 'taxable' onto line items?
 327
 328 =head1 SEE ALSO
 329
 330 L<FS::Record>, schema.html from the base documentation.
 331
 332 =cut
 333
 334 1;
 335