package FS::part_pkg::prorate_Mixin;
use strict;
-use vars qw(@ISA %info);
-use Time::Local qw(timelocal);
+use vars qw( %info );
+use Time::Local qw( timelocal timelocal_nocheck );
+use Date::Format qw( time2str );
+use List::Util qw( min );
-@ISA = qw(FS::part_pkg);
-%info = ( 'disabled' => 1 );
+%info = (
+ 'disabled' => 1,
+ # define all fields that are referenced in this code
+ 'fields' => {
+ 'add_full_period' => {
+ 'name' => 'When prorating first month, also bill for one full '.
+ 'period after that',
+ 'type' => 'checkbox',
+ },
+ 'prorate_round_day' => {
+ 'name' => 'When prorating, round to the nearest full day',
+ 'type' => 'checkbox',
+ },
+ 'prorate_defer_bill' => {
+ 'name' => 'When prorating, defer the first bill until the '.
+ 'billing day',
+ 'type' => 'checkbox',
+ },
+ 'prorate_verbose' => {
+ 'name' => 'Show prorate details on the invoice',
+ 'type' => 'checkbox',
+ },
+ },
+ 'fieldorder' => [ qw(prorate_defer_bill prorate_round_day
+ add_full_period prorate_verbose) ],
+);
+
+sub fieldorder {
+ @{ $info{'fieldorder'} }
+}
=head1 NAME
=head METHODS
-=item calc_prorate
+=item calc_prorate CUST_PKG SDATE DETAILS PARAM CUTOFF_DAY
-Takes all the arguments of calc_recur, and calculates a prorated charge
-in one of two ways:
+Takes all the arguments of calc_recur. Calculates a prorated charge from
+the $sdate to the cutoff day for this package definition, and sets the $sdate
+and $param->{months} accordingly. base_recur() will be called to determine
+the base price per billing cycle.
-- If 'sync_bill_date' is set: Charge for a number of days to synchronize
- this package to the customer's next bill date. If this is their only
- package (or they're already synchronized), that will take them through
- one billing cycle.
-- If 'cutoff_day' is set: Prorate this package so that its next bill date
- falls on that day of the month.
+Options:
+- add_full_period: Bill for the time up to the prorate day plus one full
+ billing period after that.
+- prorate_round_day: Round the current time to the nearest full day,
+ instead of using the exact time.
+- prorate_defer_bill: Don't bill the prorate interval until the prorate
+ day arrives.
+- prorate_verbose: Generate details to explain the prorate calculations.
=cut
sub calc_prorate {
- my $self = shift;
- my ($cust_pkg, $sdate, $details, $param) = @_;
-
- my $charge = $self->option('recur_fee') || 0;
- my $cutoff_day;
- if( $self->option('sync_bill_date',1) ) {
- my $next_bill = $cust_pkg->cust_main->next_bill_date;
- if( defined($next_bill) and $next_bill != $$sdate ) {
- $cutoff_day = (localtime($next_bill))[3];
- }
- else {
- # don't prorate, assume a full month
- $param->{'months'} = $self->freq;
+ my ($self, $cust_pkg, $sdate, $details, $param, @cutoff_days) = @_;
+ die "no cutoff_day" unless @cutoff_days;
+ die "can't prorate non-monthly package\n" if $self->freq =~ /\D/;
+
+ my $money_char = FS::Conf->new->config('money_char') || '$';
+
+ my $charge = $self->base_recur($cust_pkg, $sdate) || 0;
+
+ my $add_period = $self->option('add_full_period',1);
+
+ my $mnow = $$sdate;
+
+ # if this is the first bill but the bill date has been set
+ # (by prorate_defer_bill), calculate from the setup date,
+ # append the setup fee to @$details, and make sure to bill for
+ # a full period after the bill date.
+ if ( $self->option('prorate_defer_bill',1)
+ && ! $cust_pkg->getfield('last_bill')
+ && $cust_pkg->setup
+ )
+ {
+ #warn "[calc_prorate] #".$cust_pkg->pkgnum.": running deferred setup\n";
+ $param->{'setup_fee'} = $self->calc_setup($cust_pkg, $$sdate, $details);
+ $mnow = $cust_pkg->setup;
+ $add_period = 1;
+ }
+
+ # if the customer already has a billing day-of-month established,
+ # and it's a valid cutoff day, try to respect it
+ my $next_bill_day;
+ if ( my $next_bill = $cust_pkg->cust_main->next_bill_date ) {
+ $next_bill_day = (localtime($next_bill))[3];
+ if ( grep {$_ == $next_bill_day} @cutoff_days ) {
+ # by removing all other cutoff days from the list
+ @cutoff_days = ($next_bill_day);
}
}
- else { # no sync, use cutoff_day or day 1
- $cutoff_day = $self->option('cutoff_day') || 1;
+
+ my ($mend, $mstart);
+ ($mnow, $mend, $mstart) = $self->_endpoints($mnow, @cutoff_days);
+
+ # next bill date will be figured as $$sdate + one period
+ $$sdate = $mstart;
+
+ my $permonth = $charge / $self->freq;
+ my $months = ( ( $self->freq - 1 ) + ($mend-$mnow) / ($mend-$mstart) );
+ # after this, $self->freq - 1 < $months <= $self->freq
+
+ # add a full period if currently billing for a partial period
+ # or periods up to freq_override if billing for an override interval
+ if ( ($param->{'freq_override'} || 0) > 1 ) {
+ $months += $param->{'freq_override'} - 1;
+ # freq_override - 1 correct here?
+ # (probably only if freq == 1, yes?)
+ } elsif ( $add_period && $months < $self->freq ) {
+
+ # 'add_period' is a misnomer.
+ # we add enough to make the total at least a full period
+ $months++;
+ $$sdate = $self->add_freq($mstart, 1);
+ # now $self->freq <= $months <= $self->freq + 1
+ # (note that this only happens if $months < $self->freq to begin with)
+
+ }
+
+ if ( $self->option('prorate_verbose',1) and $months > 0 ) {
+ if ( $months < $self->freq ) {
+ # we are billing a fractional period only
+ # # (though maybe not a fractional month)
+ my $period_end = $self->add_freq($mstart);
+ push @$details,
+ 'Prorated (' . time2str('%b %d', $mnow) .
+ ' - ' . time2str('%b %d', $period_end) . '): ' . $money_char .
+ sprintf('%.2f', $permonth * $months + 0.00000001 );
+
+ } elsif ( $months > $self->freq ) {
+ # we are billing MORE than a full period
+ push @$details,
+
+ 'Prorated (' . time2str('%b %d', $mnow) .
+ ' - ' . time2str('%b %d', $mend) . '): ' . $money_char .
+ sprintf('%.2f', $permonth * ($months - $self->freq + 0.0000001)),
+
+ 'First full period: ' . $money_char .
+ sprintf('%.2f', $permonth * $self->freq);
+ } # else $months == $self->freq, and no prorating has happened
}
- if($cutoff_day) {
- # only works for freq >= 1 month; probably can't be fixed
- my $mnow = $$sdate;
- my ($sec, $min, $hour, $mday, $mon, $year) = (localtime($mnow))[0..5];
- my $mend;
- my $mstart;
- if ( $mday >= $cutoff_day ) {
- $mend =
- timelocal(0,0,0,$cutoff_day,$mon == 11 ? 0 : $mon + 1,$year+($mon==11));
- $mstart =
- timelocal(0,0,0,$cutoff_day,$mon,$year);
+ $param->{'months'} = $months;
+ #so 1.005 rounds to 1.01
+ $charge = sprintf('%.2f', $permonth * $months + 0.00000001 );
+
+ return sprintf('%.2f', $charge);
+}
+
+=item prorate_setup CUST_PKG SDATE
+
+Set up the package. This only has an effect if prorate_defer_bill is
+set, in which case it postpones the next bill to the cutoff day.
+
+=cut
+
+sub prorate_setup {
+ my $self = shift;
+ my ($cust_pkg, $sdate) = @_;
+ my @cutoff_days = $self->cutoff_day($cust_pkg);
+ if ( ! $cust_pkg->bill
+ and $self->option('prorate_defer_bill',1)
+ and @cutoff_days
+ ) {
+ my ($mnow, $mend, $mstart) = $self->_endpoints($sdate, @cutoff_days);
+ # If today is the cutoff day, set the next bill and setup both to
+ # midnight today, so that the customer will be billed normally for a
+ # month starting today.
+ if ( $mnow - $mstart < 86400 ) {
+ $cust_pkg->setup($mstart);
+ $cust_pkg->bill($mstart);
}
else {
- $mend =
- timelocal(0,0,0,$cutoff_day,$mon,$year);
- $mstart =
- timelocal(0,0,0,$cutoff_day,$mon == 0 ? 11 : $mon - 1,$year-($mon==11));
+ $cust_pkg->bill($mend);
}
-
- $$sdate = $mstart;
-
- my $permonth = $self->option('recur_fee', 1) / $self->freq;
- my $months = ( ( $self->freq - 1 ) + ($mend-$mnow) / ($mend-$mstart) );
-
- $param->{'months'} = $months;
- $charge = sprintf('%.2f', $permonth * $months);
+ return 1;
+ }
+ return 0;
+}
+
+=item _endpoints TIME CUTOFF_DAY
+
+Given a current time and a day of the month to prorate to, return three
+times: the start of the prorate interval (usually the current time), the
+end of the prorate interval (i.e. the cutoff date), and the time one month
+before the end of the prorate interval.
+
+=cut
+
+sub _endpoints {
+ my $self = shift;
+ my $mnow = shift;
+ my @cutoff_days = sort {$a <=> $b} @_;
+
+ # only works for freq >= 1 month; probably can't be fixed
+ my ($sec, $min, $hour, $mday, $mon, $year) = (localtime($mnow))[0..5];
+ if( $self->option('prorate_round_day',1) ) {
+ # If the time is 12:00-23:59, move to the next day by adding 18
+ # hours to $mnow. Because of DST this can end up from 05:00 to 18:59
+ # but it's always within the next day.
+ $mnow += 64800 if $hour >= 12;
+ # Get the new day, month, and year.
+ ($mday,$mon,$year) = (localtime($mnow))[3..5];
+ # Then set $mnow to midnight on that day.
+ $mnow = timelocal(0,0,0,$mday,$mon,$year);
+ }
+ my $mend;
+ my $mstart;
+ # select the first cutoff day that's on or after the current day
+ my $cutoff_day = min( grep { $_ >= $mday } @cutoff_days );
+ # if today is after the last cutoff, choose the first one
+ $cutoff_day ||= $cutoff_days[0];
+
+ # then, if today is on or after the selected day, set period to
+ # (cutoff day this month) - (cutoff day next month)
+ if ( $mday >= $cutoff_day ) {
+ $mend =
+ timelocal_nocheck(0,0,0,$cutoff_day,$mon == 11 ? 0 : $mon + 1,$year+($mon==11));
+ $mstart =
+ timelocal_nocheck(0,0,0,$cutoff_day,$mon,$year);
+ }
+ # otherwise, set period to (cutoff day last month) - (cutoff day this month)
+ else {
+ $mend =
+ timelocal_nocheck(0,0,0,$cutoff_day,$mon,$year);
+ $mstart =
+ timelocal_nocheck(0,0,0,$cutoff_day,$mon == 0 ? 11 : $mon - 1,$year-($mon==0));
}
- my $discount = $self->calc_discount(@_);
- return ($charge - $discount);
+ return ($mnow, $mend, $mstart);
}
1;