checkpoint taqua
[freeside.git] / FS / FS / tax_rate.pm
1 package FS::tax_rate;
2
3 use strict;
4 use vars qw( @ISA $DEBUG $me
5              %tax_unittypes %tax_maxtypes %tax_basetypes %tax_authorities
6              %tax_passtypes );
7 use Date::Parse;
8 use FS::Record qw( qsearchs dbh );
9 use FS::tax_class;
10 use FS::cust_bill_pkg;
11
12 @ISA = qw( FS::Record );
13
14 $DEBUG = 0;
15 $me = '[FS::tax_rate]';
16
17 =head1 NAME
18
19 FS::tax_rate - Object methods for tax_rate objects
20
21 =head1 SYNOPSIS
22
23   use FS::tax_rate;
24
25   $record = new FS::tax_rate \%hash;
26   $record = new FS::tax_rate { 'column' => 'value' };
27
28   $error = $record->insert;
29
30   $error = $new_record->replace($old_record);
31
32   $error = $record->delete;
33
34   $error = $record->check;
35
36 =head1 DESCRIPTION
37
38 An FS::tax_rate object represents a tax rate, defined by locale.
39 FS::tax_rate inherits from FS::Record.  The following fields are
40 currently supported:
41
42 =over 4
43
44 =item taxnum
45
46 primary key (assigned automatically for new tax rates)
47
48 =item geocode
49
50 a geographic location code provided by a tax data vendor
51
52 =item data_vendor
53
54 the tax data vendor
55
56 =item location
57
58 a location code provided by a tax authority
59
60 =item taxclassnum
61
62 a foreign key into FS::tax_class - the type of tax
63 referenced but FS::part_pkg_taxrate
64 eitem effective_date
65
66 the time after which the tax applies
67
68 =item tax
69
70 percentage
71
72 =item excessrate
73
74 second bracket percentage 
75
76 =item taxbase
77
78 the amount to which the tax applies (first bracket)
79
80 =item taxmax
81
82 a cap on the amount of tax if a cap exists
83
84 =item usetax
85
86 percentage on out of jurisdiction purchases
87
88 =item useexcessrate
89
90 second bracket percentage on out of jurisdiction purchases
91
92 =item unittype
93
94 one of the values in %tax_unittypes
95
96 =item fee
97
98 amount of tax per unit
99
100 =item excessfee
101
102 second bracket amount of tax per unit
103
104 =item feebase
105
106 the number of units to which the fee applies (first bracket)
107
108 =item feemax
109
110 the most units to which fees apply (first and second brackets)
111
112 =item maxtype
113
114 a value from %tax_maxtypes indicating how brackets accumulate (i.e. monthly, per invoice, etc)
115
116 =item taxname
117
118 if defined, printed on invoices instead of "Tax"
119
120 =item taxauth
121
122 a value from %tax_authorities
123
124 =item basetype
125
126 a value from %tax_basetypes indicating the tax basis
127
128 =item passtype
129
130 a value from %tax_passtypes indicating how the tax should displayed to the customer
131
132 =item passflag
133
134 'Y', 'N', or blank indicating the tax can be passed to the customer
135
136 =item setuptax
137
138 if 'Y', this tax does not apply to setup fees
139
140 =item recurtax
141
142 if 'Y', this tax does not apply to recurring fees
143
144 =item manual
145
146 if 'Y', has been manually edited
147
148 =back
149
150 =head1 METHODS
151
152 =over 4
153
154 =item new HASHREF
155
156 Creates a new tax rate.  To add the tax rate to the database, see L<"insert">.
157
158 =cut
159
160 sub table { 'tax_rate'; }
161
162 =item insert
163
164 Adds this tax rate to the database.  If there is an error, returns the error,
165 otherwise returns false.
166
167 =item delete
168
169 Deletes this tax rate from the database.  If there is an error, returns the
170 error, otherwise returns false.
171
172 =item replace OLD_RECORD
173
174 Replaces the OLD_RECORD with this one in the database.  If there is an error,
175 returns the error, otherwise returns false.
176
177 =item check
178
179 Checks all fields to make sure this is a valid tax rate.  If there is an error,
180 returns the error, otherwise returns false.  Called by the insert and replace
181 methods.
182
183 =cut
184
185 sub check {
186   my $self = shift;
187
188   foreach (qw( taxbase taxmax )) {
189     $self->$_(0) unless $self->$_;
190   }
191
192   $self->ut_numbern('taxnum')
193     || $self->ut_text('geocode')
194     || $self->ut_textn('data_vendor')
195     || $self->ut_textn('location')
196     || $self->ut_foreign_key('taxclassnum', 'tax_class', 'taxclassnum')
197     || $self->ut_numbern('effective_date')
198     || $self->ut_float('tax')
199     || $self->ut_floatn('excessrate')
200     || $self->ut_money('taxbase')
201     || $self->ut_money('taxmax')
202     || $self->ut_floatn('usetax')
203     || $self->ut_floatn('useexcessrate')
204     || $self->ut_numbern('unittype')
205     || $self->ut_floatn('fee')
206     || $self->ut_floatn('excessfee')
207     || $self->ut_floatn('feemax')
208     || $self->ut_numbern('maxtype')
209     || $self->ut_textn('taxname')
210     || $self->ut_numbern('taxauth')
211     || $self->ut_numbern('basetype')
212     || $self->ut_numbern('passtype')
213     || $self->ut_enum('passflag', [ '', 'Y', 'N' ])
214     || $self->ut_enum('setuptax', [ '', 'Y' ] )
215     || $self->ut_enum('recurtax', [ '', 'Y' ] )
216     || $self->ut_enum('manual', [ '', 'Y' ] )
217     || $self->SUPER::check
218     ;
219
220 }
221
222 =item taxclass_description
223
224 Returns the human understandable value associated with the related
225 FS::tax_class.
226
227 =cut
228
229 sub taxclass_description {
230   my $self = shift;
231   my $tax_class = qsearchs('tax_class', {'taxclassnum' => $self->taxclassnum });
232   $tax_class ? $tax_class->description : '';
233 }
234
235 =item unittype_name
236
237 Returns the human understandable value associated with the unittype column
238
239 =cut
240
241 %tax_unittypes = ( '0' => 'access line',
242                    '1' => 'minute',
243                    '2' => 'account',
244 );
245
246 sub unittype_name {
247   my $self = shift;
248   $tax_unittypes{$self->unittype};
249 }
250
251 =item maxtype_name
252
253 Returns the human understandable value associated with the maxtype column
254
255 =cut
256
257 %tax_maxtypes = ( '0' => 'receipts per invoice',
258                   '1' => 'receipts per item',
259                   '2' => 'total utility charges per utility tax year',
260                   '3' => 'total charges per utility tax year',
261                   '4' => 'receipts per access line',
262                   '9' => 'monthly receipts per location',
263 );
264
265 sub maxtype_name {
266   my $self = shift;
267   $tax_maxtypes{$self->maxtype};
268 }
269
270 =item basetype_name
271
272 Returns the human understandable value associated with the basetype column
273
274 =cut
275
276 %tax_basetypes = ( '0'  => 'sale price',
277                    '1'  => 'gross receipts',
278                    '2'  => 'sales taxable telecom revenue',
279                    '3'  => 'minutes carried',
280                    '4'  => 'minutes billed',
281                    '5'  => 'gross operating revenue',
282                    '6'  => 'access line',
283                    '7'  => 'account',
284                    '8'  => 'gross revenue',
285                    '9'  => 'portion gross receipts attributable to interstate service',
286                    '10' => 'access line',
287                    '11' => 'gross profits',
288                    '12' => 'tariff rate',
289                    '14' => 'account',
290 );
291
292 sub basetype_name {
293   my $self = shift;
294   $tax_basetypes{$self->basetype};
295 }
296
297 =item taxauth_name
298
299 Returns the human understandable value associated with the taxauth column
300
301 =cut
302
303 %tax_authorities = ( '0' => 'federal',
304                      '1' => 'state',
305                      '2' => 'county',
306                      '3' => 'city',
307                      '4' => 'local',
308                      '5' => 'county administered by state',
309                      '6' => 'city administered by state',
310                      '7' => 'city administered by county',
311                      '8' => 'local administered by state',
312                      '9' => 'local administered by county',
313 );
314
315 sub taxauth_name {
316   my $self = shift;
317   $tax_authorities{$self->taxauth};
318 }
319
320 =item passtype_name
321
322 Returns the human understandable value associated with the passtype column
323
324 =cut
325
326 %tax_passtypes = ( '0' => 'separate tax line',
327                    '1' => 'separate surcharge line',
328                    '2' => 'surcharge not separated',
329                    '3' => 'included in base rate',
330 );
331
332 sub passtype_name {
333   my $self = shift;
334   $tax_passtypes{$self->passtype};
335 }
336
337 =item taxline CUST_BILL_PKG, ...
338
339 Returns a listref of a name and an amount of tax calculated for the list
340 of packages.  If an error occurs, a message is returned as a scalar.
341
342 =cut
343
344 sub taxline {
345   my $self = shift;
346   my @cust_bill_pkg = @_;
347
348   if ($self->passflag eq 'N') {
349     return "fatal: can't (yet) handle taxes not passed to the customer";
350   }
351
352   if ($self->maxtype != 0 && $self->maxtype != 9) {
353     return qq!fatal: can't (yet) handle tax with "!. $self->maxtype_name. 
354       '" threshold';
355   }
356
357   if ($self->maxtype == 9) {
358     return qq!fatal: can't (yet) handle tax with "!. $self->maxtype_name. 
359       '" threshold';  # "texas" tax
360   }
361
362   if ($self->basetype != 0 && $self->basetype != 1 &&
363       $self->basetype != 6 && $self->basetype != 7 &&
364       $self->basetype != 14
365   ) {
366     return qq!fatal: can't (yet) handle tax with "!. $self->basetype_name. 
367       '" basis';
368   }
369
370   my $name = $self->taxname;
371   $name = 'Other surcharges'
372     if ($self->passtype == 2);
373   my $amount = 0;
374   
375   my $taxable_charged = 0;
376   unless ($self->setuptax =~ /^Y$/i) {
377     $taxable_charged += $_->setup foreach @cust_bill_pkg;
378   }
379   unless ($self->recurtax =~ /^Y$/i) {
380     $taxable_charged += $_->recur foreach @cust_bill_pkg;
381   }
382
383   my $taxable_units = 0;
384   unless ($self->recurtax =~ /^Y$/i) {
385     $taxable_units += $_->units foreach @cust_bill_pkg;
386   }
387
388   #
389   # XXX insert exemption handling here
390   #
391   # the tax or fee is applied to taxbase or feebase and then
392   # the excessrate or excess fee is applied to taxmax or feemax
393   #
394
395   $amount += $taxable_charged * $self->tax;
396   $amount += $taxable_units * $self->fee;
397   
398   return [$name, $amount];
399
400 }
401
402 =back
403
404 =head1 SUBROUTINES
405
406 =over 4
407
408 =item batch_import
409
410 =cut
411
412 sub batch_import {
413   my $param = shift;
414
415   my $fh = $param->{filehandle};
416   my $format = $param->{'format'};
417
418   my @fields;
419   my $hook;
420   if ( $format eq 'cch' ) {
421     @fields = qw( geocode inoutcity inoutlocal tax location taxbase taxmax
422                   excessrate effective_date taxauth taxtype taxcat taxname
423                   usetax useexcessrate fee unittype feemax maxtype passflag
424                   passtype basetype );
425     $hook = sub {
426       my $hash = shift;
427
428       $hash->{'effective_date'} = str2time($hash->{'effective_date'});
429
430       my $taxclassid =
431         join(':', map{ $hash->{$_} } qw(taxtype taxcat) );
432
433       my %tax_class = ( 'data_vendor'  => 'cch', 
434                         'taxclass' => $taxclassid,
435                       );
436
437       my $tax_class = qsearchs( 'tax_class', \%tax_class );
438       return "Error inserting tax rate: no tax class $taxclassid"
439         unless $tax_class;
440
441       $hash->{'taxclassnum'} = $tax_class->taxclassnum;
442
443       foreach (qw( inoutcity inoutlocal taxtype taxcat )) {
444         delete($hash->{$_});
445       }
446
447       my %passflagmap = ( '0' => '',
448                           '1' => 'Y',
449                           '2' => 'N',
450                         );
451       $hash->{'passflag'} = $passflagmap{$hash->{'passflag'}}
452         if exists $passflagmap{$hash->{'passflag'}};
453
454       foreach (keys %$hash) {
455         $hash->{$_} = substr($hash->{$_}, 0, 80)
456           if length($hash->{$_}) > 80;
457       }
458
459       '';
460
461     };
462
463   } elsif ( $format eq 'extended' ) {
464     die "unimplemented\n";
465     @fields = qw( );
466     $hook = sub {};
467   } else {
468     die "unknown format $format";
469   }
470
471   eval "use Text::CSV_XS;";
472   die $@ if $@;
473
474   my $csv = new Text::CSV_XS;
475
476   my $imported = 0;
477
478   local $SIG{HUP} = 'IGNORE';
479   local $SIG{INT} = 'IGNORE';
480   local $SIG{QUIT} = 'IGNORE';
481   local $SIG{TERM} = 'IGNORE';
482   local $SIG{TSTP} = 'IGNORE';
483   local $SIG{PIPE} = 'IGNORE';
484
485   my $oldAutoCommit = $FS::UID::AutoCommit;
486   local $FS::UID::AutoCommit = 0;
487   my $dbh = dbh;
488   
489   my $line;
490   while ( defined($line=<$fh>) ) {
491     $csv->parse($line) or do {
492       $dbh->rollback if $oldAutoCommit;
493       return "can't parse: ". $csv->error_input();
494     };
495
496     warn "$me batch_import: $imported\n" 
497       if (!($imported % 100) && $DEBUG);
498
499     my @columns = $csv->fields();
500
501     my %tax_rate = ( 'data_vendor' => $format );
502     foreach my $field ( @fields ) {
503       $tax_rate{$field} = shift @columns; 
504     }
505     my $error = &{$hook}(\%tax_rate);
506     if ( $error ) {
507       $dbh->rollback if $oldAutoCommit;
508       return $error;
509     }
510
511     my $tax_rate = new FS::tax_rate( \%tax_rate );
512     $error = $tax_rate->insert;
513
514     if ( $error ) {
515       $dbh->rollback if $oldAutoCommit;
516       return "can't insert tax_rate for $line: $error";
517     }
518
519     $imported++;
520   }
521
522   $dbh->commit or die $dbh->errstr if $oldAutoCommit;
523
524   return "Empty file!" unless $imported;
525
526   ''; #no error
527
528 }
529
530 =back
531
532 =head1 BUGS
533
534 regionselector?  putting web ui components in here?  they should probably live
535 somewhere else...
536
537 =head1 SEE ALSO
538
539 L<FS::Record>, L<FS::cust_main>, L<FS::cust_bill>, schema.html from the base
540 documentation.
541
542 =cut
543
544 1;
545