Merge branch 'master' of git.freeside.biz:/home/git/freeside
[freeside.git] / FS / FS / cust_main_county.pm
index 87c1ca7..9582334 100644 (file)
@@ -1,8 +1,10 @@
 package FS::cust_main_county;
 package FS::cust_main_county;
+use base qw( FS::Record );
 
 use strict;
 
 use strict;
-use vars qw( @ISA @EXPORT_OK $conf
+use vars qw( @EXPORT_OK $conf
              @cust_main_county %cust_main_county $countyflag ); # $cityflag );
              @cust_main_county %cust_main_county $countyflag ); # $cityflag );
+use Carp qw( croak );
 use Exporter;
 use FS::Record qw( qsearch qsearchs dbh );
 use FS::cust_bill_pkg;
 use Exporter;
 use FS::Record qw( qsearch qsearchs dbh );
 use FS::cust_bill_pkg;
@@ -11,8 +13,9 @@ use FS::cust_pkg;
 use FS::part_pkg;
 use FS::cust_tax_exempt;
 use FS::cust_tax_exempt_pkg;
 use FS::part_pkg;
 use FS::cust_tax_exempt;
 use FS::cust_tax_exempt_pkg;
+use FS::Log;
+use FS::upgrade_journal;
 
 
-@ISA = qw( FS::Record );
 @EXPORT_OK = qw( regionselector );
 
 @cust_main_county = ();
 @EXPORT_OK = qw( regionselector );
 
 @cust_main_county = ();
@@ -78,6 +81,9 @@ currently supported:
 
 =item recurtax - if 'Y', this tax does not apply to recurring fees
 
 
 =item recurtax - if 'Y', this tax does not apply to recurring fees
 
+=item source - the tax lookup method that created this tax record. For records
+created manually, this will be null.
+
 =back
 
 =head1 METHODS
 =back
 
 =head1 METHODS
@@ -118,6 +124,9 @@ methods.
 sub check {
   my $self = shift;
 
 sub check {
   my $self = shift;
 
+  $self->trim_whitespace(qw(district city county state country));
+  $self->set('city', uc($self->get('city'))); # also county?
+
   $self->exempt_amount(0) unless $self->exempt_amount;
 
   $self->ut_numbern('taxnum')
   $self->exempt_amount(0) unless $self->exempt_amount;
 
   $self->ut_numbern('taxnum')
@@ -132,38 +141,12 @@ sub check {
     || $self->ut_textn('taxname')
     || $self->ut_enum('setuptax', [ '', 'Y' ] )
     || $self->ut_enum('recurtax', [ '', 'Y' ] )
     || $self->ut_textn('taxname')
     || $self->ut_enum('setuptax', [ '', 'Y' ] )
     || $self->ut_enum('recurtax', [ '', 'Y' ] )
+    || $self->ut_textn('source')
     || $self->SUPER::check
     ;
 
 }
 
     || $self->SUPER::check
     ;
 
 }
 
-sub taxname {
-  my $self = shift;
-  if ( $self->dbdef_table->column('taxname') ) {
-    return $self->setfield('taxname', $_[0]) if @_;
-    return $self->getfield('taxname');
-  }  
-  return '';
-}
-
-sub setuptax {
-  my $self = shift;
-  if ( $self->dbdef_table->column('setuptax') ) {
-    return $self->setfield('setuptax', $_[0]) if @_;
-    return $self->getfield('setuptax');
-  }  
-  return '';
-}
-
-sub recurtax {
-  my $self = shift;
-  if ( $self->dbdef_table->column('recurtax') ) {
-    return $self->setfield('recurtax', $_[0]) if @_;
-    return $self->getfield('recurtax');
-  }  
-  return '';
-}
-
 =item label OPTIONS
 
 Returns a label looking like "Anytown, Alameda County, CA, US".
 =item label OPTIONS
 
 Returns a label looking like "Anytown, Alameda County, CA, US".
@@ -174,13 +157,10 @@ If the taxname field is set, it will look like
 If the taxclass is set, then it will be
 "Anytown, Alameda County, CA, US (International)".
 
 If the taxclass is set, then it will be
 "Anytown, Alameda County, CA, US (International)".
 
-Currently it will not contain the district, even if the city+county+state
-is not unique.
-
-OPTIONS may contain "no_taxclass" (hides taxclass) and/or "no_city"
-(hides city).  It may also contain "out", in which case, if this 
-region (district+city+county+state+country) contains no non-zero 
-taxes, the label will read "Out of taxable region(s)".
+OPTIONS may contain "with_taxclass", "with_city", and "with_district" to show
+those fields.  It may also contain "out", in which case, if this region 
+(district+city+county+state+country) contains no non-zero taxes, the label 
+will read "Out of taxable region(s)".
 
 =cut
 
 
 =cut
 
@@ -202,12 +182,15 @@ sub label {
   my $label = $self->country;
   $label = $self->state.", $label" if $self->state;
   $label = $self->county." County, $label" if $self->county;
   my $label = $self->country;
   $label = $self->state.", $label" if $self->state;
   $label = $self->county." County, $label" if $self->county;
-  if (!$opt{no_city}) {
+  if ($opt{with_city}) {
     $label = $self->city.", $label" if $self->city;
     $label = $self->city.", $label" if $self->city;
+    if ($opt{with_district} and $self->district) {
+      $label = $self->district . ", $label";
+    }
   }
   # ugly labels when taxclass and taxname are both non-null...
   # but this is how the tax report does it
   }
   # ugly labels when taxclass and taxname are both non-null...
   # but this is how the tax report does it
-  if (!$opt{no_taxclass}) {
+  if ($opt{with_taxclass}) {
     $label = "$label (".$self->taxclass.')' if $self->taxclass;
   }
   $label = $self->taxname." ($label)" if $self->taxname;
     $label = "$label (".$self->taxclass.')' if $self->taxclass;
   }
   $label = $self->taxname." ($label)" if $self->taxname;
@@ -258,15 +241,20 @@ sub _list_sql {
 
 =item taxline TAXABLES_ARRAYREF, [ OPTION => VALUE ... ]
 
 
 =item taxline TAXABLES_ARRAYREF, [ OPTION => VALUE ... ]
 
-Returns an hashref of a name and an amount of tax calculated for the 
-line items (L<FS::cust_bill_pkg> objects) in TAXABLES_ARRAYREF.  The line 
-items must come from the same invoice.  Returns a scalar error message 
-on error.
+Takes an arrayref of L<FS::cust_bill_pkg> objects representing taxable
+line items, and returns a new L<FS::cust_bill_pkg> object representing
+the tax on them under this tax rate.
+
+This will have a pseudo-field, "cust_bill_pkg_tax_location", containing 
+an arrayref of L<FS::cust_bill_pkg_tax_location> objects.  Each of these 
+will in turn have a "taxable_cust_bill_pkg" pseudo-field linking it to one
+of the taxable items.  All of these links must be resolved as the objects
+are inserted.
 
 In addition to calculating the tax for the line items, this will calculate
 any appropriate tax exemptions and attach them to the line items.
 
 
 In addition to calculating the tax for the line items, this will calculate
 any appropriate tax exemptions and attach them to the line items.
 
-Options may include 'custnum' and 'invoice_date' in case the cust_bill_pkg
+Options may include 'custnum' and 'invoice_time' in case the cust_bill_pkg
 objects belong to an invoice that hasn't been inserted yet.
 
 Options may include 'exemptions', an arrayref of L<FS::cust_tax_exempt_pkg>
 objects belong to an invoice that hasn't been inserted yet.
 
 Options may include 'exemptions', an arrayref of L<FS::cust_tax_exempt_pkg>
@@ -275,8 +263,7 @@ tax exemption limit if there is one.
 
 =cut
 
 
 =cut
 
-# XXX this should just return a cust_bill_pkg object for the tax,
-# but that requires changing stuff in tax_rate.pm also.
+# XXX change tax_rate.pm to work like this
 
 sub taxline {
   my( $self, $taxables, %opt ) = @_;
 
 sub taxline {
   my( $self, $taxables, %opt ) = @_;
@@ -294,30 +281,35 @@ sub taxline {
   my $dbh = dbh;
 
   my $name = $self->taxname || 'Tax';
   my $dbh = dbh;
 
   my $name = $self->taxname || 'Tax';
-  my $amount = 0;
+  my $taxable_cents = 0;
+  my $tax_cents = 0;
 
   my $cust_bill = $taxables->[0]->cust_bill;
   my $custnum   = $cust_bill ? $cust_bill->custnum : $opt{'custnum'};
 
   my $cust_bill = $taxables->[0]->cust_bill;
   my $custnum   = $cust_bill ? $cust_bill->custnum : $opt{'custnum'};
-  my $invoice_date = $cust_bill ? $cust_bill->_date : $opt{'invoice_date'};
-  my $cust_main = FS::cust_main->by_key($custnum) if $custnum > 0;
-  if (!$cust_main) {
-    # better way to handle this?  should we just assume that it's taxable?
-    die "unable to calculate taxes for an unknown customer\n";
-  }
+  my $invoice_time = $cust_bill ? $cust_bill->_date : $opt{'invoice_time'};
+  my $cust_main = FS::cust_main->by_key($custnum) if $custnum;
+  # (to avoid complications with estimated tax on quotations, assume it's
+  # taxable if there is no customer)
+  #if (!$cust_main) {
+    #die "unable to calculate taxes for an unknown customer\n";
+  #}
 
   # set a flag if the customer is tax-exempt
 
   # set a flag if the customer is tax-exempt
-  my $exempt_cust;
+  my ($exempt_cust, $exempt_cust_taxname);
   my $conf = FS::Conf->new;
   my $conf = FS::Conf->new;
-  if ( $conf->exists('cust_class-tax_exempt') ) {
-    my $cust_class = $cust_main->cust_class;
-    $exempt_cust = $cust_class->tax if $cust_class;
-  } else {
-    $exempt_cust = $cust_main->tax;
-  }
+  if ( $cust_main ) {
+    if ( $conf->exists('cust_class-tax_exempt') ) {
+      my $cust_class = $cust_main->cust_class;
+      $exempt_cust = $cust_class->tax if $cust_class;
+    } else {
+      $exempt_cust = $cust_main->tax;
+    }
 
 
-  # set a flag if the customer is exempt from this tax here
-  my $exempt_cust_taxname = $cust_main->tax_exemption($self->taxname)
-    if $self->taxname;
+    # set a flag if the customer is exempt from this tax here
+    if ( $self->taxname ) {
+      $exempt_cust_taxname = $cust_main->tax_exemption($self->taxname);
+    }
+  }
 
   # Gather any exemptions that are already attached to these cust_bill_pkgs
   # so that we can deduct them from the customer's monthly limit.
 
   # Gather any exemptions that are already attached to these cust_bill_pkgs
   # so that we can deduct them from the customer's monthly limit.
@@ -325,10 +317,24 @@ sub taxline {
   push @existing_exemptions, @{ $_->cust_tax_exempt_pkg }
     for @$taxables;
 
   push @existing_exemptions, @{ $_->cust_tax_exempt_pkg }
     for @$taxables;
 
+  my $tax_item = FS::cust_bill_pkg->new({
+      'pkgnum'    => 0,
+      'recur'     => 0,
+      'sdate'     => '',
+      'edate'     => '',
+      'itemdesc'  => $name,
+  });
+  my @tax_location;
+
   foreach my $cust_bill_pkg (@$taxables) {
   foreach my $cust_bill_pkg (@$taxables) {
+    # careful... may be a cust_bill_pkg or a quotation_pkg
 
     my $cust_pkg  = $cust_bill_pkg->cust_pkg;
     my $part_pkg  = $cust_bill_pkg->part_pkg;
 
     my $cust_pkg  = $cust_bill_pkg->cust_pkg;
     my $part_pkg  = $cust_bill_pkg->part_pkg;
+    my $part_fee  = $cust_bill_pkg->part_fee;
+
+    my $locationnum = $cust_bill_pkg->tax_locationnum
+                      || $cust_main->ship_locationnum;
 
     my @new_exemptions;
     my $taxable_charged = $cust_bill_pkg->setup + $cust_bill_pkg->recur
 
     my @new_exemptions;
     my $taxable_charged = $cust_bill_pkg->setup + $cust_bill_pkg->recur
@@ -354,8 +360,13 @@ sub taxline {
 
     }
 
 
     }
 
-    if ( ($part_pkg->setuptax eq 'Y' or $self->setuptax eq 'Y')
-        and $cust_bill_pkg->setup > 0 and $taxable_charged > 0 ) {
+    my $setup_exempt = ( ($part_fee and not $part_fee->taxable)
+                      or ($part_pkg and $part_pkg->setuptax)
+                      or $self->setuptax );
+
+    if ( $setup_exempt
+        and $cust_bill_pkg->setup > 0
+        and $taxable_charged > 0 ) {
 
       push @new_exemptions, FS::cust_tax_exempt_pkg->new({
           amount => $cust_bill_pkg->setup,
 
       push @new_exemptions, FS::cust_tax_exempt_pkg->new({
           amount => $cust_bill_pkg->setup,
@@ -364,8 +375,14 @@ sub taxline {
       $taxable_charged -= $cust_bill_pkg->setup;
 
     }
       $taxable_charged -= $cust_bill_pkg->setup;
 
     }
-    if ( ($part_pkg->recurtax eq 'Y' or $self->recurtax eq 'Y')
-        and $cust_bill_pkg->recur > 0 and $taxable_charged > 0 ) {
+
+    my $recur_exempt = ( ($part_fee and not $part_fee->taxable)
+                      or ($part_pkg and $part_pkg->recurtax)
+                      or $self->recurtax );
+
+    if ( $recur_exempt
+        and $cust_bill_pkg->recur > 0
+        and $taxable_charged > 0 ) {
 
       push @new_exemptions, FS::cust_tax_exempt_pkg->new({
           amount => $cust_bill_pkg->recur,
 
       push @new_exemptions, FS::cust_tax_exempt_pkg->new({
           amount => $cust_bill_pkg->recur,
@@ -376,23 +393,41 @@ sub taxline {
     }
   
     if ( $self->exempt_amount && $self->exempt_amount > 0 
     }
   
     if ( $self->exempt_amount && $self->exempt_amount > 0 
-      and $taxable_charged > 0 ) {
-      #my ($mon,$year) = (localtime($cust_bill_pkg->sdate) )[4,5];
-      my ($mon,$year) =
-        (localtime( $cust_bill_pkg->sdate || $invoice_date ) )[4,5];
-      $mon++;
-      $year += 1900;
-      my $freq = $cust_bill_pkg->freq;
-      unless ($freq) {
-        $freq = $part_pkg->freq || 1;  # less trustworthy fallback
-      }
-      if ( $freq !~ /(\d+)$/ ) {
-        $dbh->rollback if $oldAutoCommit;
-        return "daily/weekly package definitions not (yet?)".
-               " compatible with monthly tax exemptions";
+      and $taxable_charged > 0
+      and $cust_main ) {
+
+      # XXX monthly exemptions currently don't work on quotations
+
+      # If the billing period extends across multiple calendar months, 
+      # there may be several months of exemption available.
+      my $sdate = $cust_bill_pkg->sdate || $invoice_time;
+      my $start_month = (localtime($sdate))[4] + 1;
+      my $start_year  = (localtime($sdate))[5] + 1900;
+      my $edate = $cust_bill_pkg->edate || $invoice_time;
+      my $end_month   = (localtime($edate))[4] + 1;
+      my $end_year    = (localtime($edate))[5] + 1900;
+
+      # If the partial last month + partial first month <= one month,
+      # don't use the exemption in the last month
+      # (unless the last month is also the first month, e.g. one-time
+      # charges)
+      if ( (localtime($sdate))[3] >= (localtime($edate))[3]
+           and ($start_month != $end_month or $start_year != $end_year)
+      ) { 
+        $end_month--;
+        if ( $end_month == 0 ) {
+          $end_year--;
+          $end_month = 12;
+        }
       }
       }
-      my $taxable_per_month =
-        sprintf("%.2f", $taxable_charged / $freq );
+
+      # number of months of exemption available
+      my $freq = ($end_month - $start_month) +
+                 ($end_year  - $start_year) * 12 +
+                 1;
+
+      # divide equally among all of them
+      my $permonth = sprintf('%.2f', $taxable_charged / $freq);
 
       #call the whole thing off if this customer has any old
       #exemption records...
 
       #call the whole thing off if this customer has any old
       #exemption records...
@@ -405,9 +440,15 @@ sub taxline {
           'run bin/fs-migrate-cust_tax_exempt?';
       }
 
           'run bin/fs-migrate-cust_tax_exempt?';
       }
 
-      foreach my $which_month ( 1 .. $freq ) {
-  
-        #maintain the new exemption table now
+      my ($mon, $year) = ($start_month, $start_year);
+      while ($taxable_charged > 0.005 and 
+             ($year < $end_year or
+               ($year == $end_year and $mon <= $end_month)
+             )
+      ) {
+        # find the sum of the exemption used by this customer, for this tax,
+        # in this month
         my $sql = "
           SELECT SUM(amount)
             FROM cust_tax_exempt_pkg
         my $sql = "
           SELECT SUM(amount)
             FROM cust_tax_exempt_pkg
@@ -421,7 +462,7 @@ sub taxline {
         ";
         my $sth = dbh->prepare($sql) or do {
           $dbh->rollback if $oldAutoCommit;
         ";
         my $sth = dbh->prepare($sql) or do {
           $dbh->rollback if $oldAutoCommit;
-          return "fatal: can't lookup exising exemption: ". dbh->errstr;
+          return "fatal: can't lookup existing exemption: ". dbh->errstr;
         };
         $sth->execute(
           $custnum,
         };
         $sth->execute(
           $custnum,
@@ -430,10 +471,11 @@ sub taxline {
           $mon,
         ) or do {
           $dbh->rollback if $oldAutoCommit;
           $mon,
         ) or do {
           $dbh->rollback if $oldAutoCommit;
-          return "fatal: can't lookup exising exemption: ". dbh->errstr;
+          return "fatal: can't lookup existing exemption: ". dbh->errstr;
         };
         my $existing_exemption = $sth->fetchrow_arrayref->[0] || 0;
 
         };
         my $existing_exemption = $sth->fetchrow_arrayref->[0] || 0;
 
+        # add any exemption we're already using for another line item
         foreach ( grep { $_->taxnum == $self->taxnum &&
                          $_->exempt_monthly eq 'Y'   &&
                          $_->month  == $mon          &&
         foreach ( grep { $_->taxnum == $self->taxnum &&
                          $_->exempt_monthly eq 'Y'   &&
                          $_->month  == $mon          &&
@@ -443,13 +485,15 @@ sub taxline {
         {
           $existing_exemption += $_->amount;
         }
         {
           $existing_exemption += $_->amount;
         }
-        
+
         my $remaining_exemption =
           $self->exempt_amount - $existing_exemption;
         if ( $remaining_exemption > 0 ) {
         my $remaining_exemption =
           $self->exempt_amount - $existing_exemption;
         if ( $remaining_exemption > 0 ) {
-          my $addl = $remaining_exemption > $taxable_per_month
-            ? $taxable_per_month
+          my $addl = $remaining_exemption > $permonth
+            ? $permonth
             : $remaining_exemption;
             : $remaining_exemption;
+          $addl = $taxable_charged if $addl > $taxable_charged;
+
           push @new_exemptions, FS::cust_tax_exempt_pkg->new({
               amount          => sprintf('%.2f', $addl),
               exempt_monthly  => 'Y',
           push @new_exemptions, FS::cust_tax_exempt_pkg->new({
               amount          => sprintf('%.2f', $addl),
               exempt_monthly  => 'Y',
@@ -458,7 +502,6 @@ sub taxline {
             });
           $taxable_charged -= $addl;
         }
             });
           $taxable_charged -= $addl;
         }
-        last if $taxable_charged < 0.005;
         # if they're using multiple months of exemption for a multi-month
         # package, then record the exemptions in separate months
         $mon++;
         # if they're using multiple months of exemption for a multi-month
         # package, then record the exemptions in separate months
         $mon++;
@@ -467,42 +510,90 @@ sub taxline {
           $year++;
         }
 
           $year++;
         }
 
-      } #foreach $which_month
-    } # if exempt_amount
+      }
+    } # if exempt_amount and $cust_main
 
     $_->taxnum($self->taxnum) foreach @new_exemptions;
 
 
     $_->taxnum($self->taxnum) foreach @new_exemptions;
 
-    #if ( $cust_bill_pkg->billpkgnum ) {
-
-      #no, need to do this to e.g. calculate tax credit amounts
-      #die "tried to calculate tax exemptions on a previously billed line item\n";
-
-      # this is unnecessary
-#      foreach my $cust_tax_exempt_pkg (@new_exemptions) {
-#        my $error = $cust_tax_exempt_pkg->insert;
-#        if ( $error ) {
-#          $dbh->rollback if $oldAutoCommit;
-#          return "can't insert cust_tax_exempt_pkg: $error";
-#        }
-#      }
-    #}
-
     # attach them to the line item
     push @{ $cust_bill_pkg->cust_tax_exempt_pkg }, @new_exemptions;
     push @existing_exemptions, @new_exemptions;
 
     # attach them to the line item
     push @{ $cust_bill_pkg->cust_tax_exempt_pkg }, @new_exemptions;
     push @existing_exemptions, @new_exemptions;
 
-    # If we were smart, we'd also generate a cust_bill_pkg_tax_location 
-    # record at this point, but that would require redesigning more stuff.
     $taxable_charged = sprintf( "%.2f", $taxable_charged);
     $taxable_charged = sprintf( "%.2f", $taxable_charged);
-
-    $amount += $taxable_charged * $self->tax / 100;
+    next if $taxable_charged == 0;
+
+    my $this_tax_cents = int($taxable_charged * $self->tax);
+    my $location = FS::cust_bill_pkg_tax_location->new({
+        'taxnum'      => $self->taxnum,
+        'taxtype'     => ref($self),
+        'cents'       => $this_tax_cents,
+        'pkgnum'      => $cust_bill_pkg->pkgnum,
+        'locationnum' => $locationnum,
+        'taxable_cust_bill_pkg' => $cust_bill_pkg,
+        'tax_cust_bill_pkg'     => $tax_item,
+    });
+    push @tax_location, $location;
+
+    $taxable_cents += $taxable_charged;
+    $tax_cents += $this_tax_cents;
   } #foreach $cust_bill_pkg
   } #foreach $cust_bill_pkg
+  
+  # now round and distribute
+  my $extra_cents = sprintf('%.2f', $taxable_cents * $self->tax / 100) * 100
+                    - $tax_cents;
+  # make sure we have an integer
+  $extra_cents = sprintf('%.0f', $extra_cents);
+  if ( $extra_cents < 0 ) {
+    die "nonsense extra_cents value $extra_cents";
+  }
+  $tax_cents += $extra_cents;
+  my $i = 0;
+  foreach (@tax_location) { # can never require more than a single pass, yes?
+    my $cents = $_->get('cents');
+    if ( $extra_cents > 0 ) {
+      $cents++;
+      $extra_cents--;
+    }
+    $_->set('amount', sprintf('%.2f', $cents/100));
+  }
+  $tax_item->set('setup' => sprintf('%.2f', $tax_cents / 100));
+  $tax_item->set('cust_bill_pkg_tax_location', \@tax_location);
+  
+  return $tax_item;
+}
+
+=head1 find_wa_tax_dupes
+
+Return a list of cust_main_county Record objects that are detected
+as duplicate washington state sales tax rows (source=wa_state)
+within their respective tax classes
+
+=cut
 
 
-  return {
-    'name'   => $name,
-    'amount' => $amount,
-  };
+sub find_wa_tax_dupes {
+  my %cust_main_county;
+  my @dupes;
 
 
+  for my $row ( qsearch( cust_main_county => { source => 'wa_sales' } ) ) {
+    my $taxclass = $row->taxclass || 'none';
+    $cust_main_county{$taxclass} ||= {};
+
+    my $district = $row->district || 'none';
+    $cust_main_county{$taxclass}->{$district} ||= [];
+
+    push @{ $cust_main_county{$taxclass}->{$district} }, $row;
+  }
+
+  for my $taxclass ( keys %cust_main_county ) {
+    for my $district ( keys %{ $cust_main_county{$taxclass} } ) {
+      my $tax_rows = $cust_main_county{$taxclass}->{$district};
+      if ( scalar @$tax_rows > 1 ) {
+        push @dupes, @$tax_rows;
+      }
+    }
+  }
+
+  @dupes;
 }
 
 =back
 }
 
 =back
@@ -627,6 +718,226 @@ END
 
 }
 
 
 }
 
+sub _merge_into {
+  # For internal use:
+  #
+  # When given two cust_main_county row objects, rewrite all database foreign
+  # key references referring to $row_to_merge->taxnum as references to
+  # $row_to_keep->taxnum, so $row_to_merge can be safely deleted from
+  # cust_main_county
+  #
+  # Usage (class method):
+  #    $row_to_merge->_merge_into( $row_to_keep )
+  #
+  # Usage (package function):
+  #    FS::cust_main_county::_merge_into( $row_to_merge, $row_to_keep )
+  #
+  # Optionally, allow merge when records don't match
+  #      (useful during tax table update routines)
+  #     $row_to_merge->_merge_info(
+  #       $row_to_keep,
+  #       { identical_record_check => 0 }
+  #     );
+
+  my $row_to_merge = shift;
+  my $row_to_keep  = shift
+    or croak 'record to merge into must be provided';
+
+  my $args = shift || { identical_record_check => 1 };
+  croak 'invalid arguments hashref' unless ref $args;
+
+  my $log = FS::Log->new('FS::cust_main_county');
+
+  my $keep_taxnum  = $row_to_keep->taxnum;
+  my $merge_taxnum = $row_to_merge->taxnum;
+
+  if (
+    $args->{identical_record_check}
+    && (
+      $row_to_keep->tax != $row_to_merge->tax
+      || $row_to_keep->exempt_amount != $row_to_merge->exempt_amount
+    )
+  ) {
+    my $msg = "Found duplicate taxes (#$keep_taxnum and #$merge_taxnum) "
+            . "but they have different rates and can't be merged.";
+    $log->warn( $msg );
+    warn "$msg\n";
+    return;
+  }
+
+  my $msg = "Merging tax #$merge_taxnum into #$keep_taxnum";
+  $log->warn( $msg );
+  warn "$msg\n";
+
+  foreach my $table (qw(
+    cust_bill_pkg_tax_location
+    cust_bill_pkg_tax_location_void
+    cust_tax_exempt_pkg
+    cust_tax_exempt_pkg_void
+  )) {
+    foreach my $row (qsearch($table, { 'taxnum' => $merge_taxnum })) {
+      $row->set('taxnum' => $keep_taxnum);
+      if ( my $error = $row->replace ) {
+        $log->error( $error );
+        die $error;
+      }
+    }
+  }
+
+  if ( my $error = $row_to_merge->delete ) {
+    $log->error( $error );
+    die $error;
+  }
+}
+
+sub _upgrade_data {
+  my $class = shift;
+  # assume taxes in Washington with district numbers, and null name, or 
+  # named 'sales tax', are looked up via the wa_sales method. mark them.
+  my $journal = 'cust_main_county__source_wa_sales_201611';
+  if (!FS::upgrade_journal->is_done($journal)) {
+    my @taxes = qsearch({
+        'table'     => 'cust_main_county',
+        'extra_sql' => " WHERE tax > 0 AND country = 'US' AND state = 'WA'".
+                       " AND district IS NOT NULL AND ( taxname IS NULL OR ".
+                       " taxname ~* 'sales tax' )",
+    });
+    if ( @taxes ) {
+      warn "Flagging Washington state sales taxes: ".scalar(@taxes)." records.\n";
+      foreach (@taxes) {
+        $_->set('source', 'wa_sales');
+        my $error = $_->replace;
+        die $error if $error;
+      }
+    }
+    FS::upgrade_journal->set_done($journal);
+  }
+  my @key_fields = (qw(city county state country district taxname taxclass));
+
+  # trim whitespace and convert to uppercase in the 'city' field.
+  foreach my $record (qsearch({
+    table => 'cust_main_county',
+    extra_sql => " WHERE city LIKE ' %' OR city LIKE '% ' OR city != UPPER(city)",
+  })) {
+    # any with-trailing-space records probably duplicate other records
+    # from the same city, and if we just fix the record in place, we'll
+    # create an exact duplicate.
+    # so find the record this one would duplicate, and merge them.
+    $record->check; # trims whitespace
+    my %match = map { $_ => $record->get($_) } @key_fields;
+    my $other = qsearchs('cust_main_county', \%match);
+    if ($other) {
+      $record->_merge_into($other);
+    } else {
+      # else there is no record this one duplicates, so just fix it
+      my $error = $record->replace;
+      die $error if $error;
+    }
+  } # foreach $record
+
+  # separate wa_sales taxes by tax class as needed
+  my $district_taxname = $conf->config('tax_district_taxname');
+  $journal = 'cust_main_county__district_taxclass';
+  if (!FS::upgrade_journal->is_done($journal)
+      and $conf->exists('enable_taxclasses')) {
+    eval "use FS::part_pkg_taxclass";
+    my @taxes = qsearch({
+        'table'     => 'cust_main_county',
+        'extra_sql' => " WHERE tax > 0 AND country = 'US' AND state = 'WA'".
+                       " AND district IS NOT NULL AND  source = 'wa_sales'".
+                       " AND taxclass IS NULL"
+    });
+    my @classes = FS::part_pkg_taxclass->taxclass_names;
+    if ( @taxes ) {
+      warn "Separating WA sales taxes: ".scalar(@taxes)." records.\n";
+      foreach my $oldtax (@taxes) {
+        my $error;
+        my $taxnum = $oldtax->taxnum;
+        warn "Separating tax #$taxnum into classes\n";
+        foreach my $taxclass (@classes) {
+          # ensure that we end up with a single copy of the tax in this
+          # jurisdiction+class. there may already be one (or more) there.
+          # if so, they all represent the same tax; merge them together.
+          my %newtax_hash = (
+            'country'   => 'US',
+            'state'     => 'WA',
+            'city'      => $oldtax->city,
+            'district'  => $oldtax->district,
+            'taxclass'  => $taxclass,
+            'source'    => 'wa_sales',
+          );
+          my @taxes_in_class = qsearch('cust_main_county', {
+            %newtax_hash,
+            'tax'       => { op => '>', value => 0 },
+            'setuptax'  => '',
+            'recurtax'  => '',
+          });
+          my $newtax = shift @taxes_in_class;
+          if ($newtax) {
+            foreach (@taxes_in_class) {
+              # allow the merge, even if this somehow differs.
+              $_->set('tax', $newtax->tax);
+              $_->_merge_into($newtax);
+            }
+          }
+          $newtax ||= FS::cust_main_county->new(\%newtax_hash);
+          # copy properties from the pre-split tax
+          $newtax->set('tax', $oldtax->tax);
+          $newtax->set('setuptax', $oldtax->setuptax);
+          $newtax->set('recurtax', $oldtax->recurtax);
+          # and assign the defined tax name
+          $newtax->set('taxname', $district_taxname);
+          $error = ($newtax->taxnum ? $newtax->replace : $newtax->insert);
+          die "splitting taxnum ".$oldtax->taxnum.": $error\n" if $error;
+        } # foreach $taxclass
+        $oldtax->set('tax', 0);
+        $error = $oldtax->replace;
+        die "splitting taxnum ".$oldtax->taxnum.": $error\n" if $error;
+      }
+    }
+    FS::upgrade_journal->set_done($journal);
+  }
+
+  # also ensure they all have the chosen taxname now
+  if ($district_taxname) {
+    my @taxes = qsearch('cust_main_county', {
+      'source'  => 'wa_sales',
+      'taxname' => { op => '!=', value => $district_taxname }
+    });
+    if (@taxes) {
+      warn "Renaming WA sales taxes: ".scalar(@taxes)." records.\n";
+      foreach my $tax (@taxes) {
+        $tax->set('taxname', $district_taxname);
+        my $error = $tax->replace;
+        die "renaming taxnum ".$tax->taxnum.": $error\n" if $error;
+      }   
+    }
+  }
+
+  # remove duplicates (except disabled records)
+  my @duplicate_sets = qsearch({
+    table => 'cust_main_county',
+    select => FS::Record::group_concat_sql('taxnum', ',') . ' AS taxnums, ' .
+              join(',', @key_fields),
+    extra_sql => ' WHERE tax > 0
+      GROUP BY city, county, state, country, district, taxname, taxclass
+      HAVING COUNT(*) > 1'
+  });
+  warn "Found ".scalar(@duplicate_sets)." set(s) of duplicate tax definitions\n"
+    if @duplicate_sets;
+  foreach my $set (@duplicate_sets) {
+    my @taxnums = split(',', $set->get('taxnums'));
+    my $first = FS::cust_main_county->by_key(shift @taxnums);
+    foreach my $taxnum (@taxnums) {
+      my $record = FS::cust_main_county->by_key($taxnum);
+      $record->_merge_into($first);
+    }
+  }
+
+  '';
+}
+
 =back
 
 =head1 BUGS
 =back
 
 =head1 BUGS