[Koha-devel] Accounts rewriting - comments wanted.

Ian Walls ian.walls at bywatersolutions.com
Thu Mar 31 16:01:21 CEST 2011


One comment:  $type should be user-definable, not hardcoded values.  More
extensible that way, since libraries are always good at coming up with new
ways of doing things.  This would allow for statistical reports on Accounts
to a library-specific level of granularity; I just know if we do it
hard-coded, someone is going to complain that they can't differentiate fine
types at all get lumped into 'M'.

Otherwise, looks good.  If I have any more comments after re-reading, I'll
post.  Thanks, Robin!


-Ian

2011/3/31 Robin Sheat <robin at catalyst.net.nz>

> I'm in the process of rewriting the accounts system to improve its
> flexibility, and getting rid of some cruft. Also to make it easier to
> work with from a developer point of view. The ability to do things like
> partial payments (which I know have been implemented about three other
> times, but as more putty on the existing system) and other useful things
> is what's aiming to come out of this, as well as having a nicely
> maintainable subsystem.
>
> I'm attaching the perldoc of what I have so far, I'm interested in
> seeing if anyone has any ideas on problems that this design might have
> that I should work around before it gets too much further along. I also
> note that the accounts system seems to handle the returning of lost
> items, which strikes me as the wrong place to put it, so I'll try to
> pull that out to somewhere more sensible, or at the least isolate it.
>
> Mostly I'm just making sure that it'll be able to reproduce all the
> existing functionality, which seems to have accreted in that module, but
> if you have any ideas for other things that can be fitted in naturally
> as part of this, they may be considered too.
>
> $ perldoc -t -T Accounts.pm
> NAME
>    C4::Accounts - Functions for dealing with borrower accounts in Koha
>
> SYNOPSIS
>    use C4::Accounts;
>
> DESCRIPTION
>    The functions here handle the account for a borrower. Adding fines and
>    other charges, paying them off, looking up the information, and keeping
>    it all in sync.
>
>    The account system works by adding every transaction (a fine added, a
>    payment made, a rental charge, etc.) to the "accountlines" table. Once
>    added, this is never modified except to change certain flags (dispute
>    and zeroed in particular.)
>
>    To indicate charges being paid off, a record is added to the
>    "accountoffsets" table that links a payment transaction to a charge
>    transaction, along with the amount that payment contributes to the
>    charge. If a payment is completely consumed, or a charge completely paid
>    off, the 'zeroed' flag on that transaction is set. This is purely to
>    save time when looking for outstanding charges or payments.
>
>    Additionally to this, an "accounttotals" table is maintained that tracks
>    the total outstanding. This is the difference between the payments put
>    in and the charges added. It is used simply to get a quick lookup of how
>    much a borrower owes or is in credit.
>
>    This structure is intended to allow partial payments in particular, but
>    also allows flexibility that will make other things possible, such as
>    tracking what a particular payment is for and providing a clear audit
>    trail of what has happened.
>
> FUNCTIONS
>  charge_borrower
>      $trans_num = charge_borrower($borrowernumber, $itemnumber, $amount,
> $type, $description, $user)
>
>    This is the fundamental function for charging a borrower for something.
>    It will add a record to the accountlines table. If the person is in
>    credit, it may also apply that credit to this charge, if allowed to by
>    the rules for this charge type.
>
>    If this relates to an item, say a rental or fine, that should go into
>    $itemnumber.
>
>    $type is a text flag that indicates what this charge is for:
>
>    N: New card
>    F: Fine
>    A: Account management
>    L: Lost item
>    R: Rental
>    M: Sundry (anything else)
>
>    $user should be the user ID that applied the charge, to aid in auditing.
>    It may also be a text string if an ID doesn't make sense (e.g. cron
>    jobs.)
>
>    In general, this function will be called by something else that handles
>    setting up the specifics but may be called directly if that's all you
>    need.
>
>   RETURNS
>    The transaction number of the newly created transaction.
>
>  add_payment
>       ($trans_num, $credit) = add_payment($borrowernumber, $amount, $type,
> $description, $user, @transactions)
>
>    This adds a payment for a borrower, indicating that they've given you
>    money.
>
>    $type is a text flag that indicates the nature of the payment. Currently
>    this is only 'C' for 'credit'.
>
>    $description is a human-readable description of the payment.
>
>    $user is the borrower ID of the person putting through this payment, to
>    aid in auditing. It may also be a text string if an ID doesn't make
>    sense (e.g. cron jobs.)
>
>    @transactions is a list of transactions that this payment will be used
>    to pay off. It will pay off as many of these as it can. If there is
>    money in the payment left over, then it will be credit for the user. It
>    will not automatically pay off other charges.
>
>    Often this will be called by another accounts function that handles
>    adjusting other values in the system, but it may be called directly for
>    simple cases.
>
>   NOTES
>    The $amount value is the amount that is being paid off. It should be a
>    positive value, but will be converted to a negative value when written
>    to the database.
>
>   RETURNS
>    If called in a scalar context, this returns the transaction number for
>    the added payment. If called in a list context it returns that, and the
>    amount of credit left over from this payment.
>
>  should_use_credit_for
>      should_use_credit_for($type)
>
>    If the type of the charge is one that the system preferences say should
>    be paid off using credit, then we say so by returning true.
>
>  pay_from_credit
>      $credit_left = pay_from_credit($transaction_number, $borrowernumber)
>
>    This takes a particular transaction (that should be a charge), finds all
>    the unused payments in the system for the borrower, and pays off this
>    transaction using them, or as close to that as possible.
>
>    Note: at the moment, $borrowernumber should be the same as the borrower
>    that accrued the charge.
>
>   RETURNS
>    The amount of credit left for this borrower.
>
>  pay
>      $money_left = pay($charge_number, $payment_number)
>
>    This links a charge to a payment, paying off some or all of the charge.
>    It does this by writing an entry to the accountoffsets table that links
>    them together.
>
>    This doesn't support using just part of the payment, that's hopefully
>    not going to happen. The exception to this is if the payment was part
>    used earlier, or if the payment is larger than the charge. So really I'm
>    just saying that it doesn't let you specify the amount.
>
>    $charge_number and $payment_number may be scalars or arrayrefs (or a
>    mix.) If they are arrayrefs, this will use each payment to pay of as
>    much of the charges as it can, basically what you'd expect.
>
>    Every charge that is paid off, or payment that is used up, will get its
>    "zeroed" flag set to true.
>
>    This will update the totals table also.
>
>   RETURNS
>    The amount of the payment(s) left over (from the provided list of
>    payments only), or zero if it was all used up.
>
>  get_transaction_info
>      ($outstanding, $borrowernumber, $amount, $transactionnumber) =
> get_transaction_info($transaction_number)
>
>    This gets information about a transaction, and returns either a scalar
>    with just the amount outstanding on it, or a list containing: amount
>    outstanding, borrowernumber, amount, transactionnumber.
>
>  get_transactions
>      @transactions = get_transactions(%filter_rules)
>
>    This gets a list of transactions that match the supplied filter rules.
>    The rules implmented are:
>
>    "borrowernumber": restrict to a particular borrower number
>    "zeroed": 0/1 - restrict to a particular zeroed status
>    "paymentonly": if 1, this will restrict to entries that are only payment
>    types.
>
>   RETURNS
>    A list of hashes that contain the database fields from the accountlines
>    table.
>
>  update_users_balance
>      update_users_balance($borrowernumber, $adjustment)
>
>    This updates a user's balance in the 'totals' table.
>
>    $borrowernumber is the number of the borrower, $adjustment is the amount
>    to change the total by. Keep in mind that we are tracking debt, so if
>    they incur a fine, then it should be adjusted by a positive amount, and
>    if they make a payment it should be negative.
>
>    This is internal and not exported.
>
>
> --
> Robin Sheat
> Catalyst IT Ltd.
> ✆ +64 4 803 2204
> GPG: 5957 6D23 8B16 EFAB FEF8  7175 14D3 6485 A99C EB6D
>
> _______________________________________________
> Koha-devel mailing list
> Koha-devel at lists.koha-community.org
> http://lists.koha-community.org/cgi-bin/mailman/listinfo/koha-devel
> website : http://www.koha-community.org/
> git : http://git.koha-community.org/
> bugs : http://bugs.koha-community.org/
>



-- 
Ian Walls
Lead Development Specialist
ByWater Solutions
Phone # (888) 900-8944
http://bywatersolutions.com
ian.walls at bywatersolutions.com
Twitter: @sekjal
-------------- next part --------------
An HTML attachment was scrubbed...
URL: </pipermail/koha-devel/attachments/20110331/a3e01227/attachment-0001.htm>


More information about the Koha-devel mailing list