1 package FS::Report::Tax;
5 use FS::Record qw(dbh qsearch qsearchs);
6 use Date::Format qw( time2str );
12 =item report_internal OPTIONS
14 Constructor. Generates a tax report using the internal tax rate system
15 (L<FS::cust_main_county>).
19 - beginning, ending: the date range as Unix timestamps.
20 - taxname: the name of the tax (corresponds to C<cust_bill_pkg.itemdesc>).
21 - country: the country code.
24 - agentnum: limit to this agentnum.num.
25 - breakdown: hashref of the fields to group by. Keys can be 'city', 'district',
26 'pkgclass', or 'taxclass'; values should be true.
27 - debug: sets the debug level. 1 will warn the data collected for the report;
28 2 will also warn all of the SQL statements.
36 $DEBUG ||= $opt{debug};
38 my $conf = new FS::Conf;
40 my($beginning, $ending) = @opt{'beginning', 'ending'};
42 my ($taxname, $country, %breakdown);
44 # purify taxname properly here, as we're going to include it in lots of
45 # SQL statements using single quotes only
46 if ( $opt{taxname} =~ /^([\w\s]+)$/ ) {
49 die "taxname required"; # UI prevents this
52 if ( $opt{country} =~ /^(\w\w)$/ ) {
55 die "country required";
58 # %breakdown: short name => field identifier
60 'taxclass' => 'cust_main_county.taxclass',
61 'pkgclass' => 'part_pkg.classnum',
62 'city' => 'cust_main_county.city',
63 'district' => 'cust_main_county.district',
64 'state' => 'cust_main_county.state',
65 'county' => 'cust_main_county.county',
67 foreach (qw(taxclass pkgclass city district)) {
68 delete $breakdown{$_} unless $opt{breakdown}->{$_};
71 my $join_cust = ' JOIN cust_bill USING ( invnum )
72 LEFT JOIN cust_main USING ( custnum ) ';
74 my $join_cust_pkg = $join_cust.
75 ' LEFT JOIN cust_pkg USING ( pkgnum )
76 LEFT JOIN part_pkg USING ( pkgpart ) ';
78 my $from_join_cust_pkg = " FROM cust_bill_pkg $join_cust_pkg ";
80 # all queries MUST be linked to both cust_bill and cust_main_county
82 # Either or both of these can be used to link cust_bill_pkg to
83 # cust_main_county. This one links a taxed line item (billpkgnum) to a tax rate
84 # (taxnum), and gives the amount of tax charged on that line item under that
85 # rate (as tax_amount).
86 my $pkg_tax = "SELECT SUM(amount) as tax_amount, taxnum, ".
87 "taxable_billpkgnum AS billpkgnum ".
88 "FROM cust_bill_pkg_tax_location JOIN cust_bill_pkg USING (billpkgnum) ".
89 "GROUP BY taxable_billpkgnum, taxnum";
91 # This one links a tax-exempted line item (billpkgnum) to a tax rate (taxnum),
92 # and gives the amount of the tax exemption. EXEMPT_WHERE should be replaced
93 # with a real WHERE clause to further limit the tax exemptions that will be
95 my $pkg_tax_exempt = "SELECT SUM(amount) AS exempt_charged, billpkgnum, taxnum ".
96 "FROM cust_tax_exempt_pkg EXEMPT_WHERE GROUP BY billpkgnum, taxnum";
98 # This just calculates the sum of credit applications to a line item.
99 my $pkg_credited = "SELECT SUM(amount) AS credited, billpkgnum ".
100 "FROM cust_credit_bill_pkg GROUP BY billpkgnum";
102 my $where = "WHERE cust_bill._date >= $beginning AND cust_bill._date <= $ending ".
103 "AND COALESCE(cust_main_county.taxname,'Tax') = '$taxname' ".
104 "AND cust_main_county.country = '$country'";
105 # SELECT/GROUP clauses for first-level queries
106 my $select = "SELECT ";
107 my $group = "GROUP BY ";
108 foreach (qw(pkgclass taxclass state county city district)) {
109 if ( $breakdown{$_} ) {
110 $select .= "$breakdown{$_} AS $_, ";
111 $group .= "$breakdown{$_}, ";
113 $select .= "NULL AS $_, ";
116 $select .= "array_to_string(array_agg(DISTINCT(cust_main_county.taxnum)), ',') AS taxnums, ";
119 # SELECT/GROUP clauses for second-level (totals) queries
120 # breakdown by package class only, if anything
121 my $select_all = "SELECT NULL AS pkgclass, ";
123 if ( $breakdown{pkgclass} ) {
124 $select_all = "SELECT $breakdown{pkgclass} AS pkgclass, ";
125 $group_all = "GROUP BY $breakdown{pkgclass}";
127 $select_all .= "array_to_string(array_agg(DISTINCT(cust_main_county.taxnum)), ',') AS taxnums, ";
130 if ( $opt{agentnum} and $opt{agentnum} =~ /^(\d+)$/ ) {
132 my $agent = qsearchs('agent', { 'agentnum' => $agentnum } );
133 die "agent not found" unless $agent;
134 $where .= " AND cust_main.agentnum = $agentnum";
138 '(cust_bill_pkg.pkgnum != 0 OR cust_bill_pkg.feepart IS NOT NULL)';
140 # one query for each column of the report
141 # plus separate queries for the totals row
144 # SALES QUERIES (taxable sales, all types of exempt sales)
148 my $exempt = "$select SUM(exempt_charged)
149 FROM cust_main_county
150 JOIN ($pkg_tax_exempt) AS pkg_tax_exempt
152 JOIN cust_bill_pkg USING (billpkgnum)
153 $join_cust_pkg $where AND $nottax
156 my $all_exempt = "$select_all SUM(exempt_charged)
157 FROM cust_main_county
158 JOIN ($pkg_tax_exempt) AS pkg_tax_exempt
160 JOIN cust_bill_pkg USING (billpkgnum)
161 $join_cust_pkg $where AND $nottax
164 # sales to tax-exempt customers
165 $sql{exempt_cust} = $exempt;
166 $sql{exempt_cust} =~ s/EXEMPT_WHERE/WHERE exempt_cust = 'Y' OR exempt_cust_taxname = 'Y'/;
167 $all_sql{exempt_cust} = $all_exempt;
168 $all_sql{exempt_cust} =~ s/EXEMPT_WHERE/WHERE exempt_cust = 'Y' OR exempt_cust_taxname = 'Y'/;
170 # sales of tax-exempt packages
171 $sql{exempt_pkg} = $exempt;
172 $sql{exempt_pkg} =~ s/EXEMPT_WHERE/WHERE exempt_setup = 'Y' OR exempt_recur = 'Y'/;
173 $all_sql{exempt_pkg} = $all_exempt;
174 $all_sql{exempt_pkg} =~ s/EXEMPT_WHERE/WHERE exempt_setup = 'Y' OR exempt_recur = 'Y'/;
176 # monthly per-customer exemptions
177 $sql{exempt_monthly} = $exempt;
178 $sql{exempt_monthly} =~ s/EXEMPT_WHERE/WHERE exempt_monthly = 'Y'/;
179 $all_sql{exempt_monthly} = $all_exempt;
180 $all_sql{exempt_monthly} =~ s/EXEMPT_WHERE/WHERE exempt_monthly = 'Y'/;
183 # (sale - exemptions - credits, except not negative)
184 $sql{taxable} = "$select
186 cust_bill_pkg.setup + cust_bill_pkg.recur
187 - COALESCE(exempt_charged, 0)
188 - COALESCE(credited, 0)
191 LEFT JOIN ($pkg_tax) AS pkg_tax
192 ON (cust_bill_pkg.billpkgnum = pkg_tax.billpkgnum)
193 LEFT JOIN ($pkg_tax_exempt) AS pkg_tax_exempt
194 ON (cust_bill_pkg.billpkgnum = pkg_tax_exempt.billpkgnum)
195 LEFT JOIN ($pkg_credited) AS pkg_credited
196 ON (cust_bill_pkg.billpkgnum = pkg_credited.billpkgnum)
197 LEFT JOIN cust_main_county
198 ON (COALESCE(pkg_tax.taxnum, pkg_tax_exempt.taxnum) = cust_main_county.taxnum)
199 $join_cust_pkg $where AND $nottax
202 $all_sql{taxable} = "$select_all
204 cust_bill_pkg.setup + cust_bill_pkg.recur
205 - COALESCE(exempt_charged, 0)
206 - COALESCE(credited, 0)
209 LEFT JOIN ($pkg_tax) AS pkg_tax
210 ON (cust_bill_pkg.billpkgnum = pkg_tax.billpkgnum)
211 LEFT JOIN ($pkg_tax_exempt) AS pkg_tax_exempt
212 ON (cust_bill_pkg.billpkgnum = pkg_tax_exempt.billpkgnum)
213 LEFT JOIN ($pkg_credited) AS pkg_credited
214 ON (cust_bill_pkg.billpkgnum = pkg_credited.billpkgnum)
215 LEFT JOIN cust_main_county
216 ON (COALESCE(pkg_tax.taxnum, pkg_tax_exempt.taxnum) = cust_main_county.taxnum)
217 $join_cust_pkg $where AND $nottax
220 $sql{taxable} =~ s/EXEMPT_WHERE//; # unrestricted
221 $all_sql{taxable} =~ s/EXEMPT_WHERE//;
223 # estimated tax (taxable * rate)
224 $sql{estimated} = "$select
225 SUM(cust_main_county.tax / 100 *
226 ( cust_bill_pkg.setup + cust_bill_pkg.recur
227 - COALESCE(exempt_charged, 0)
228 - COALESCE(credited, 0)
232 LEFT JOIN ($pkg_tax) AS pkg_tax
233 ON (cust_bill_pkg.billpkgnum = pkg_tax.billpkgnum)
234 LEFT JOIN ($pkg_tax_exempt) AS pkg_tax_exempt
235 ON (cust_bill_pkg.billpkgnum = pkg_tax_exempt.billpkgnum)
236 LEFT JOIN ($pkg_credited) AS pkg_credited
237 ON (cust_bill_pkg.billpkgnum = pkg_credited.billpkgnum)
238 LEFT JOIN cust_main_county
239 ON (COALESCE(pkg_tax.taxnum, pkg_tax_exempt.taxnum) = cust_main_county.taxnum)
240 $join_cust_pkg $where AND $nottax
243 $all_sql{estimated} = "$select_all
244 SUM(cust_main_county.tax / 100 *
245 ( cust_bill_pkg.setup + cust_bill_pkg.recur
246 - COALESCE(exempt_charged, 0)
247 - COALESCE(credited, 0)
251 LEFT JOIN ($pkg_tax) AS pkg_tax
252 ON (cust_bill_pkg.billpkgnum = pkg_tax.billpkgnum)
253 LEFT JOIN ($pkg_tax_exempt) AS pkg_tax_exempt
254 ON (cust_bill_pkg.billpkgnum = pkg_tax_exempt.billpkgnum)
255 LEFT JOIN ($pkg_credited) AS pkg_credited
256 ON (cust_bill_pkg.billpkgnum = pkg_credited.billpkgnum)
257 LEFT JOIN cust_main_county
258 ON (COALESCE(pkg_tax.taxnum, pkg_tax_exempt.taxnum) = cust_main_county.taxnum)
259 $join_cust_pkg $where AND $nottax
262 # there isn't one for 'sales', because we calculate sales by adding up
263 # the taxable and exempt columns.
265 # TAX QUERIES (billed tax, credited tax)
269 # join cust_bill_pkg to cust_main_county via cust_bill_pkg_tax_location
270 my $taxfrom = " FROM cust_bill_pkg
272 LEFT JOIN cust_bill_pkg_tax_location USING ( billpkgnum )
273 LEFT JOIN cust_main_county USING ( taxnum )";
275 if ( $breakdown{pkgclass} ) {
276 # If we're not grouping by package class, this is unnecessary, and
277 # probably really expensive.
279 LEFT JOIN cust_bill_pkg AS taxable
280 ON (cust_bill_pkg_tax_location.taxable_billpkgnum = taxable.billpkgnum)
281 LEFT JOIN cust_pkg ON (taxable.pkgnum = cust_pkg.pkgnum)
282 LEFT JOIN part_pkg USING (pkgpart)";
285 my $istax = "cust_bill_pkg.pkgnum = 0";
287 $sql{tax} = "$select SUM(cust_bill_pkg_tax_location.amount)
292 $all_sql{tax} = "$select_all SUM(cust_bill_pkg_tax_location.amount)
297 # sum of credits applied against billed tax
298 # ($creditfrom includes join of taxable item to part_pkg if with_pkgclass
300 my $creditfrom = $taxfrom .
301 ' JOIN cust_credit_bill_pkg USING (billpkgtaxlocationnum)' .
302 ' JOIN cust_credit_bill USING (creditbillnum)';
303 my $creditwhere = $where .
304 ' AND billpkgtaxratelocationnum IS NULL';
306 # if the credit_date option is set to application date, change
307 # $creditwhere accordingly
308 if ( $opt{credit_date} eq 'cust_credit_bill' ) {
309 $creditwhere =~ s/cust_bill._date/cust_credit_bill._date/g;
312 $sql{credit} = "$select SUM(cust_credit_bill_pkg.amount)
314 $creditwhere AND $istax
317 $all_sql{credit} = "$select_all SUM(cust_credit_bill_pkg.amount)
319 $creditwhere AND $istax
324 # note that we use keys(%sql) here and keys(%all_sql) later. nothing
325 # obligates us to use the same set of variables for the total query
326 # as for the individual category queries
327 foreach my $k (keys(%sql)) {
329 warn "\n".uc($k).":\n".$stmt."\n" if $DEBUG;
330 my $sth = dbh->prepare($stmt);
331 # eight columns: pkgclass, taxclass, state, county, city, district
332 # taxnums (comma separated), value
334 or die "failed to execute $k query: ".$sth->errstr;
335 while ( my $row = $sth->fetchrow_arrayref ) {
337 {$row->[0]} # pkgclass
338 {$row->[1] # taxclass
339 || ($breakdown{taxclass} ? 'Unclassified' : '')}
341 {$row->[3] ? $row->[3] . ' County' : ''} # county
343 {$row->[5]} # district
345 push @$bin, [ $k, $row->[6], $row->[7] ];
348 warn "DATA:\n".Dumper(\%data) if $DEBUG > 1;
350 foreach my $k (keys %all_sql) {
351 warn "\nTOTAL ".uc($k).":\n".$all_sql{$k}."\n" if $DEBUG;
352 my $sth = dbh->prepare($all_sql{$k});
353 # three columns: pkgclass, taxnums (comma separated), value
355 or die "failed to execute $k totals query: ".$sth->errstr;
356 while ( my $row = $sth->fetchrow_arrayref ) {
357 my $bin = $total{$row->[0]} ||= [];
358 push @$bin, [ $k, $row->[1], $row->[2] ];
361 warn "TOTALS:\n".Dumper(\%total) if $DEBUG > 1;
363 # $data{$pkgclass}{$taxclass}{$state}{$county}{$city}{$district} = [
364 # [ 'taxable', taxnums, amount ],
365 # [ 'exempt_cust', taxnums, amount ],
368 # non-requested grouping levels simply collapse into key = ''
370 # the much-maligned "out of taxable region"...
371 # find sales that are not linked to any tax with this name
372 # but are still inside the date range/agent criteria.
374 # This doesn't use $select_all/$group_all because we want a single number,
375 # not a breakdown by pkgclass. Unless someone needs that eventually,
376 # in which case we'll turn it into an %all_sql query.
379 "WHERE cust_bill._date >= $beginning AND cust_bill._date <= $ending";
381 $outside_where .= " AND cust_main.agentnum = $agentnum";
383 my $sql_outside = "SELECT SUM(cust_bill_pkg.setup + cust_bill_pkg.recur)
389 SELECT 1 FROM cust_tax_exempt_pkg
390 JOIN cust_main_county USING (taxnum)
391 WHERE cust_tax_exempt_pkg.billpkgnum = cust_bill_pkg.billpkgnum
392 AND COALESCE(cust_main_county.taxname,'Tax') = '$taxname'
395 SELECT 1 FROM cust_bill_pkg_tax_location
396 JOIN cust_main_county USING (taxnum)
397 WHERE cust_bill_pkg_tax_location.taxable_billpkgnum = cust_bill_pkg.billpkgnum
398 AND COALESCE(cust_main_county.taxname,'Tax') = '$taxname'
401 warn "\nOUTSIDE:\n$sql_outside\n" if $DEBUG;
402 my $total_outside = FS::Record->scalar_sql($sql_outside);
406 qsearch('cust_main_county', {
408 tax => { op => '>', value => 0 }
411 $taxrates{$tax->taxnum} = $tax->tax;
419 'taxrates' => \%taxrates,
420 'outside' => $total_outside,
434 # sub fetchall_array...
438 my @columns = (qw(pkgclass taxclass state county city district));
439 # taxnums, field headings, and amounts
443 # de-treeify this thing
446 my ($tree, $level) = @_;
447 if ( ref($tree) eq 'HASH' ) {
448 foreach my $k ( sort {
449 -1*($b eq '') # sort '' to the end
450 or ($a eq '') # sort '' to the end
451 or ($a <=> $b) # sort numbers as numbers
452 or ($a cmp $b) # sort alphabetics as alphabetics
455 $row_template{ $columns[$level] } = $k;
456 &{ $descend }($tree->{$k}, $level + 1);
458 # then insert the total row for the pkgclass
459 $row_template{'total'} = 1; # flag it as a total
460 &{ $descend }($self->{total}->{$k}, 1);
461 $row_template{'total'} = 0;
464 } elsif ( ref($tree) eq 'ARRAY' ) {
465 # then we've reached the bottom; elements of this array are arrayrefs
466 # of [ field, taxnums, amount ].
467 # start with the inherited location-element fields
468 my %this_row = %row_template;
470 foreach my $x (@$tree) {
472 foreach (split(',', $x->[1])) {
476 $this_row{ $x->[0] } = $x->[2];
478 # store combined taxnums
479 $this_row{taxnums} = join(',', sort { $a cmp $b } keys %taxnums);
480 # and calculate row totals
481 $this_row{sales} = sprintf('%.2f',
483 $this_row{exempt_cust} +
484 $this_row{exempt_pkg} +
485 $this_row{exempt_monthly}
487 # and give it a label
488 if ( $this_row{total} ) {
489 $this_row{label} = 'Total';
491 $this_row{label} = join(', ', grep $_,
494 $this_row{county}, # already has ' County' suffix
499 # and indicate the tax rate, if any
501 foreach (keys %taxnums) {
502 $rate ||= $self->{taxrates}->{$_};
503 if ( $rate != $self->{taxrates}->{$_} ) {
508 if ( $rate eq 'variable' ) {
509 $this_row{rate} = 'variable';
510 } elsif ( $rate > 0 ) {
511 $this_row{rate} = sprintf('%.2f', $rate);
513 push @rows, \%this_row;
517 &{ $descend }($self->{data}, 0);
519 warn "TABLE:\n".Dumper(\@rows) if $self->{opt}->{debug};
531 if ( $self->{opt}->{agentnum} ) {
532 my $agent = qsearchs('agent', { agentnum => $self->{opt}->{agentnum} });
533 $string .= $agent->agent . ' ';
535 $string .= 'Tax Report: '; # XXX localization
536 if ( $self->{opt}->{beginning} ) {
537 $string .= time2str('%h %o %Y ', $self->{opt}->{beginning});
539 $string .= 'through ';
540 if ( $self->{opt}->{ending} and $self->{opt}->{ending} < 4294967295 ) {
541 $string .= time2str('%h %o %Y', $self->{opt}->{ending});
545 $string .= ' - ' . $self->{opt}->{taxname};