FS/FS/Commission_Mixin.pm

   1 package FS::Commission_Mixin;
   2
   3 use strict;
   4 use FS::Record 'qsearch';
   5
   6 =head1 NAME
   7
   8 FS::Commission_Mixin - Common interface for entities that can receive
   9 sales commissions.
  10
  11 =head1 INTERFACE
  12
  13 =over 4
  14
  15 =item commission_where
  16
  17 Returns an SQL WHERE fragment to search for commission credits belonging
  18 to this entity.
  19
  20 =item sales_where
  21
  22 Returns an SQL WHERE fragment to search for sales records
  23 (L<FS::cust_bill_pkg>) that would be assigned to this entity for commission.
  24
  25 =cut
  26
  27 sub commission_where { ... }
  28
  29 =head1 METHODS
  30
  31 =over 4
  32
  33 =item cust_credit_search START, END, OPTIONS
  34
  35 Returns a qsearch hashref for the commission credits given to this entity.
  36 START and END are a date range.
  37
  38 OPTIONS may optionally contain "commission_classnum", a package classnum to
  39 limit the commission packages.
  40
  41 =cut
  42
  43 sub cust_credit_search {
  44   my( $self, $sdate, $edate, %search ) = @_;
  45
  46   my @where = ( $self->commission_where );
  47   push @where, "cust_credit._date >= $sdate" if $sdate;
  48   push @where, "cust_credit._date  < $edate" if $edate;
  49
  50   my $classnum_sql = '';
  51   my $addl_from = '';
  52   if ( exists($search{'commission_classnum'}) ) {
  53     my $classnum = delete($search{'commission_classnum'});
  54     push @where, 'part_pkg.classnum '. ( $classnum ? " = $classnum"
  55                                                    : " IS NULL "    );
  56
  57     $addl_from =
  58       ' LEFT JOIN cust_pkg ON ( commission_pkgnum = cust_pkg.pkgnum ) '.
  59       ' LEFT JOIN part_pkg USING ( pkgpart ) ';
  60   }
  61
  62   my $extra_sql = 'WHERE ' . join(' AND ', map {"( $_ )"} @where);
  63
  64   { 'table'     => 'cust_credit',
  65     'addl_from' => $addl_from,
  66     'extra_sql' => $extra_sql,
  67   };
  68 }
  69
  70 =item cust_credit START, END, OPTIONS
  71
  72 Takes the same options as cust_credit_search, and performs the search.
  73
  74 =cut
  75
  76 sub cust_credit {
  77   my $self = shift;
  78   qsearch( $self->cust_credit_search(@_) );
  79 }
  80
  81 =item cust_bill_pkg_search START, END, OPTIONS
  82
  83 Returns a qsearch hashref for the sales for which this entity could receive
  84 commission. START and END are a date range; OPTIONS may contain:
  85 - I<classnum>: limit to this package class (or null, if it's empty)
  86 - I<paid>: limit to sales that have no unpaid balance (as of now)
  87
  88 =cut
  89
  90 sub cust_bill_pkg_search {
  91   my( $self, $sdate, $edate, %search ) = @_;
  92
  93   my @where = $self->sales_where(%search);
  94   push @where, "cust_bill._date >= $sdate" if $sdate;
  95   push @where, "cust_bill._date  < $edate" if $edate;
  96
  97   my $classnum_sql = '';
  98   if ( exists( $search{'classnum'}  ) ) {
  99     my $classnum = $search{'classnum'} || '';
 100     die "bad classnum" unless $classnum =~ /^(\d*)$/;
 101
 102     push @where,
 103       "part_pkg.classnum ". ( $classnum ? " = $classnum " : ' IS NULL ' );
 104   }
 105
 106   if ( $search{'paid'} ) {
 107     push @where, FS::cust_bill_pkg->owed_sql . ' <= 0.005';
 108   }
 109
 110   my $extra_sql = "WHERE ".join(' AND ', map {"( $_ )"} @where);
 111
 112   { 'table'     => 'cust_bill_pkg',
 113     'select'    => 'cust_bill_pkg.*',
 114     'addl_from' => ' LEFT JOIN cust_bill USING ( invnum ) '.
 115                    ' LEFT JOIN cust_pkg  USING ( pkgnum ) '.
 116                    ' LEFT JOIN part_pkg  USING ( pkgpart ) '.
 117                    ' LEFT JOIN cust_main ON ( cust_pkg.custnum = cust_main.custnum )',
 118     'extra_sql' => $extra_sql,
 119  };
 120 }
 121
 122 =item cust_bill_pkg START, END, OPTIONS
 123
 124 Same as L</cust_bill_pkg_search> but then performs the search.
 125
 126 =back
 127
 128 =head1 SEE ALSO
 129
 130 L<FS::cust_credit>
 131
 132 =cut
 133
 134 1;