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