google account export tweaks, #11760
[freeside.git] / FS / FS / cust_refund.pm
1 package FS::cust_refund;
2
3 use strict;
4 use base qw( FS::otaker_Mixin FS::payinfo_transaction_Mixin FS::cust_main_Mixin
5              FS::Record );
6 use vars qw( @encrypted_fields );
7 use Business::CreditCard;
8 use FS::UID qw(getotaker);
9 use FS::Record qw( qsearch qsearchs dbh );
10 use FS::CurrentUser;
11 use FS::cust_credit;
12 use FS::cust_credit_refund;
13 use FS::cust_pay_refund;
14 use FS::cust_main;
15
16 @encrypted_fields = ('payinfo');
17
18 =head1 NAME
19
20 FS::cust_refund - Object method for cust_refund objects
21
22 =head1 SYNOPSIS
23
24   use FS::cust_refund;
25
26   $record = new FS::cust_refund \%hash;
27   $record = new FS::cust_refund { 'column' => 'value' };
28
29   $error = $record->insert;
30
31   $error = $new_record->replace($old_record);
32
33   $error = $record->delete;
34
35   $error = $record->check;
36
37 =head1 DESCRIPTION
38
39 An FS::cust_refund represents a refund: the transfer of money to a customer;
40 equivalent to a negative payment (see L<FS::cust_pay>).  FS::cust_refund
41 inherits from FS::Record.  The following fields are currently supported:
42
43 =over 4
44
45 =item refundnum
46
47 primary key (assigned automatically for new refunds)
48
49 =item custnum
50
51 customer (see L<FS::cust_main>)
52
53 =item refund
54
55 Amount of the refund
56
57 =item reason
58
59 Reason for the refund
60
61 =item _date
62
63 specified as a UNIX timestamp; see L<perlfunc/"time">.  Also see
64 L<Time::Local> and L<Date::Parse> for conversion functions.
65
66 =item payby
67
68 Payment Type (See L<FS::payinfo_Mixin> for valid payby values)
69
70 =item payinfo
71
72 Payment Information (See L<FS::payinfo_Mixin> for data format)
73
74 =item paymask
75
76 Masked payinfo (See L<FS::payinfo_Mixin> for how this works)
77
78 =item paybatch
79
80 text field for tracking card processing
81
82 =item usernum
83
84 order taker (see L<FS::access_user>
85
86 =item closed
87
88 books closed flag, empty or `Y'
89
90 =back
91
92 =head1 METHODS
93
94 =over 4
95
96 =item new HASHREF
97
98 Creates a new refund.  To add the refund to the database, see L<"insert">.
99
100 =cut
101
102 sub table { 'cust_refund'; }
103
104 =item insert
105
106 Adds this refund to the database.
107
108 For backwards-compatibility and convenience, if the additional field crednum is
109 defined, an FS::cust_credit_refund record for the full amount of the refund
110 will be created.  Or (this time for convenience and consistancy), if the
111 additional field paynum is defined, an FS::cust_pay_refund record for the full
112 amount of the refund will be created.  In both cases, custnum is optional.
113
114 =cut
115
116 sub insert {
117   my $self = shift;
118
119   local $SIG{HUP} = 'IGNORE';
120   local $SIG{INT} = 'IGNORE';
121   local $SIG{QUIT} = 'IGNORE';
122   local $SIG{TERM} = 'IGNORE';
123   local $SIG{TSTP} = 'IGNORE';
124   local $SIG{PIPE} = 'IGNORE';
125
126   my $oldAutoCommit = $FS::UID::AutoCommit;
127   local $FS::UID::AutoCommit = 0;
128   my $dbh = dbh;
129
130   if ( $self->crednum ) {
131     my $cust_credit = qsearchs('cust_credit', { 'crednum' => $self->crednum } )
132       or do {
133         $dbh->rollback if $oldAutoCommit;
134         return "Unknown cust_credit.crednum: ". $self->crednum;
135       };
136     $self->custnum($cust_credit->custnum);
137   } elsif ( $self->paynum ) {
138     my $cust_pay = qsearchs('cust_pay', { 'paynum' => $self->paynum } )
139       or do {
140         $dbh->rollback if $oldAutoCommit;
141         return "Unknown cust_pay.paynum: ". $self->paynum;
142       };
143     $self->custnum($cust_pay->custnum);
144   }
145
146   my $error = $self->check;
147   return $error if $error;
148
149   $error = $self->SUPER::insert;
150   if ( $error ) {
151     $dbh->rollback if $oldAutoCommit;
152     return $error;
153   }
154
155   if ( $self->crednum ) {
156     my $cust_credit_refund = new FS::cust_credit_refund {
157       'crednum'   => $self->crednum,
158       'refundnum' => $self->refundnum,
159       'amount'    => $self->refund,
160       '_date'     => $self->_date,
161     };
162     $error = $cust_credit_refund->insert;
163     if ( $error ) {
164       $dbh->rollback if $oldAutoCommit;
165       return $error;
166     }
167     #$self->custnum($cust_credit_refund->cust_credit->custnum);
168   } elsif ( $self->paynum ) {
169     my $cust_pay_refund = new FS::cust_pay_refund {
170       'paynum'    => $self->paynum,
171       'refundnum' => $self->refundnum,
172       'amount'    => $self->refund,
173       '_date'     => $self->_date,
174     };
175     $error = $cust_pay_refund->insert;
176     if ( $error ) {
177       $dbh->rollback if $oldAutoCommit;
178       return $error;
179     }
180   }
181
182
183   $dbh->commit or die $dbh->errstr if $oldAutoCommit;
184
185   '';
186
187 }
188
189 =item delete
190
191 Unless the closed flag is set, deletes this refund and all associated
192 applications (see L<FS::cust_credit_refund> and L<FS::cust_pay_refund>).
193
194 =cut
195
196 sub delete {
197   my $self = shift;
198   return "Can't delete closed refund" if $self->closed =~ /^Y/i;
199
200   local $SIG{HUP} = 'IGNORE';
201   local $SIG{INT} = 'IGNORE';
202   local $SIG{QUIT} = 'IGNORE';
203   local $SIG{TERM} = 'IGNORE';
204   local $SIG{TSTP} = 'IGNORE';
205   local $SIG{PIPE} = 'IGNORE';
206
207   my $oldAutoCommit = $FS::UID::AutoCommit;
208   local $FS::UID::AutoCommit = 0;
209   my $dbh = dbh;
210
211   foreach my $cust_credit_refund ( $self->cust_credit_refund ) {
212     my $error = $cust_credit_refund->delete;
213     if ( $error ) {
214       $dbh->rollback if $oldAutoCommit;
215       return $error;
216     }
217   }
218
219   foreach my $cust_pay_refund ( $self->cust_pay_refund ) {
220     my $error = $cust_pay_refund->delete;
221     if ( $error ) {
222       $dbh->rollback if $oldAutoCommit;
223       return $error;
224     }
225   }
226
227   my $error = $self->SUPER::delete(@_);
228   if ( $error ) {
229     $dbh->rollback if $oldAutoCommit;
230     return $error;
231   }
232
233   $dbh->commit or die $dbh->errstr if $oldAutoCommit;
234
235   '';
236
237 }
238
239 =item replace OLD_RECORD
240
241 You can, but probably shouldn't modify refunds... 
242
243 Replaces the OLD_RECORD with this one in the database, or, if OLD_RECORD is not
244 supplied, replaces this record.  If there is an error, returns the error,
245 otherwise returns false.
246
247 =cut
248
249 sub replace {
250   my $self = shift;
251   return "Can't modify closed refund" if $self->closed =~ /^Y/i;
252   $self->SUPER::replace(@_);
253 }
254
255 =item check
256
257 Checks all fields to make sure this is a valid refund.  If there is an error,
258 returns the error, otherwise returns false.  Called by the insert method.
259
260 =cut
261
262 sub check {
263   my $self = shift;
264
265   $self->usernum($FS::CurrentUser::CurrentUser->usernum) unless $self->usernum;
266
267   my $error =
268     $self->ut_numbern('refundnum')
269     || $self->ut_numbern('custnum')
270     || $self->ut_money('refund')
271     || $self->ut_alphan('otaker')
272     || $self->ut_text('reason')
273     || $self->ut_numbern('_date')
274     || $self->ut_textn('paybatch')
275     || $self->ut_enum('closed', [ '', 'Y' ])
276   ;
277   return $error if $error;
278
279   return "refund must be > 0 " if $self->refund <= 0;
280
281   $self->_date(time) unless $self->_date;
282
283   return "unknown cust_main.custnum: ". $self->custnum
284     unless $self->crednum 
285            || qsearchs( 'cust_main', { 'custnum' => $self->custnum } );
286
287   $error = $self->payinfo_check;
288   return $error if $error;
289
290   $self->SUPER::check;
291 }
292
293 =item cust_credit_refund
294
295 Returns all applications to credits (see L<FS::cust_credit_refund>) for this
296 refund.
297
298 =cut
299
300 sub cust_credit_refund {
301   my $self = shift;
302   map { $_ } #return $self->num_cust_credit_refund unless wantarray;
303   sort { $a->_date <=> $b->_date }
304     qsearch( 'cust_credit_refund', { 'refundnum' => $self->refundnum } )
305   ;
306 }
307
308 =item cust_pay_refund
309
310 Returns all applications to payments (see L<FS::cust_pay_refund>) for this
311 refund.
312
313 =cut
314
315 sub cust_pay_refund {
316   my $self = shift;
317   map { $_ } #return $self->num_cust_pay_refund unless wantarray;
318   sort { $a->_date <=> $b->_date }
319     qsearch( 'cust_pay_refund', { 'refundnum' => $self->refundnum } )
320   ;
321 }
322
323 =item unapplied
324
325 Returns the amount of this refund that is still unapplied; which is
326 amount minus all credit applications (see L<FS::cust_credit_refund>) and
327 payment applications (see L<FS::cust_pay_refund>).
328
329 =cut
330
331 sub unapplied {
332   my $self = shift;
333   my $amount = $self->refund;
334   $amount -= $_->amount foreach ( $self->cust_credit_refund );
335   $amount -= $_->amount foreach ( $self->cust_pay_refund );
336   sprintf("%.2f", $amount );
337 }
338
339 =back
340
341 =head1 CLASS METHODS
342
343 =over 4
344
345 =item unapplied_sql
346
347 Returns an SQL fragment to retreive the unapplied amount.
348
349 =cut 
350
351 sub unapplied_sql {
352   my ($class, $start, $end) = @_;
353   my $credit_start = $start ? "AND cust_credit_refund._date <= $start" : '';
354   my $credit_end   = $end   ? "AND cust_credit_refund._date > $end"   : '';
355   my $pay_start    = $start ? "AND cust_pay_refund._date <= $start"    : '';
356   my $pay_end      = $end   ? "AND cust_pay_refund._date > $end"      : '';
357
358   "refund
359     - COALESCE( 
360                 ( SELECT SUM(amount) FROM cust_credit_refund
361                     WHERE cust_refund.refundnum = cust_credit_refund.refundnum
362                     $credit_start $credit_end )
363                 ,0
364               )
365     - COALESCE(
366                 ( SELECT SUM(amount) FROM cust_pay_refund
367                     WHERE cust_refund.refundnum = cust_pay_refund.refundnum
368                     $pay_start $pay_end )
369                 ,0
370               )
371   ";
372
373 }
374
375 # Used by FS::Upgrade to migrate to a new database.
376 sub _upgrade_data {  # class method
377   my ($class, %opts) = @_;
378   $class->_upgrade_otaker(%opts);
379 }
380
381 =back
382
383 =head1 BUGS
384
385 Delete and replace methods.
386
387 =head1 SEE ALSO
388
389 L<FS::Record>, L<FS::cust_credit>, schema.html from the base documentation.
390
391 =cut
392
393 1;
394