view release on metacpan or  search on metacpan

utilities/totals  view on Meta::CPAN

#!/usr/bin/perl -w
# Extract a 'totals' summary for reconciliation.
#
# - read one or more OCV transaction log/s, creating totals summaries for 
#   the given account/s and settlement day/s
#   - note: you generally shouldn't use an active log (one which is still
#     having entries appended). Buffering will very likely bite you.
#
# - the transaction log may contain entries for a number of different 
#   transaction types: (requests) PURCHASE, REFUND, STATUS, PREAUTH, 
#   COMPLETION; and RESPONSE. To extract the totals information, only
#   the PURCHASE/REFUND and RESPONSE records are required and used by this
#   program.
#
# - the OCV server's totals request 'offset' parameter is an integer number
#   of days from the current period - however 'null' days are transparently
#   skipped. Basically, this makes it difficult to be certain which offset
#   you need to use to get a particular day. This program can use a date
#   offset, but the offset is from today and does not skip 'null' days.
#
# - whilst this program uses the OCV module, it does not actually contact 
#   the server so can be run "off-line"
# - the OCV, and logs thereof, give monetary amounts as integer cents. To 
#   avoid introducing any rounding errors, this is carried through here,
#   the final division to dollars is done at output.
#
# Usage
#
# Generally:
#    totals [options] <accountnum> <date> [<transaction log> ...]
# Where <date> may be an integer offset from today.
#
# There is currently one option allowed, plus an '--' option terminator:
#    --force   force - don't exit on errors
#    --        stop looking for options
#
# There are at least three asynchronous processes affecting the transaction
# logs:
# - the bank cuts over to a new settlement date at some random time of day
# - the transaction logs are rotated at some random time of day
# - live transactions are initiated and completed at random times, and
#   with random and potentially large durations (e.g. if manual intervention
#   is required to complete/query a transaction).
# To avoid such timing dependancies, it is advised that this filter be run
# over a set of 'archived' logs, spanning at least a day either side of the
# desired date (or more, if errors have occured).
#
#
# Failure Modes
#
#  There are a couple of theoretical problems, none of which should occur
# in day-to-day operation:
#
# - the transaction log is missing entries / has extra entries / is corrupt
#
#   A given transaction is expected to follow the following sequence:
#
#    1a) a PURCHASE, REFUND or COMPLETION request (w/ the amount)
#    1b) zero or one RESPONSE responses (w/ settlement date and account no.)
#
#    2a) a STATUS request
#    2b) zero or one RESPONSE responses
#     ... repeat 2)
#
#   If the initial request (1a) is missing, it will not be possible to 
# determine the totals and an error will be raised. Further, at least 
# one RESPONSE message must be found for each PURCHASE/REFUND.
#
# - the transaction log contains duplicate Transaction References
#
#   This program assumes unique TxnRefs, if a duplicate PURCHASE or REFUND
# message is encountered an error is raised.
#
# - account list is modified
#
#  Each transaction is completed against an OCV "account" (which maps
# to a merchant ID/terminal ID and thence a bank account). If the OCV
# server's accounts are modified, the transaction log/s must be divided
# to extract the transactions using the old account list and those with
# the new account list so as to disambiguate the accounts when generating
# the totals.
#  For each account, each unique merchant ID / terminal ID pair used is
# written with the totals summary. Noting these details will both help
# with the financial reconciliation and will also show any account |
# [mt]ID mismatches. (Note that the test server (v1.15) does not return 
# valid data in responses to STATUS requests).
#
# - card description/s modified
#
#  Each response message contains a card type code, plus a text description.
# This program uses the code as the definitive value to allocate purchases 
# and refunds against. It extracts the description, intended solely for 
# easier human consumption of the card list, from the first instance of 
# each code. If these descriptions change during a log span then the results 
# will be erroneous.
#
# - transaction log is too big