Add documentation for reconciliation related Workflow classes

Author: ehuelsmann

lib/LedgerSMB/Workflow/Action/Reconciliation.pm

@@ -22,6 +22,41 @@ LedgerSMB::Workflow::Action::Reconciliation - Collection of actions for reconcil
 
 =head1 DESCRIPTION
 
+This action holds all functionality required to run a (basic) reconciliation
+process: matching of (bank) statement lines against what is recorded in the
+books.
+
+=head2 Book-side algorithm
+
+In some cases, it's required or desirable to combine multiple journal lines
+into a single line to be matched with the (bank) statement.  One case concerns
+payments; these are recorded as multiple journal lines when they are used to
+clear multiple invoices, however in practice there's only a single payment.
+
+A special case is where a payment is combined with transaction costs; the payment
+is recorded in the cash screen and the transaction costs (or other correction) is
+recorded using a general journal, using the same C< source >.
+
+Last, all general journal lines with the same C< source > are combined into a
+single line; except where the C< source > is an empty string or C< NULL > value.
+
+
+=head2 Reconciliation algorithm
+
+Items are taken from the C< _stmt_todo > context parameter in the order given.
+Handling of items differs between the cases where the statement item has a
+C< source > specified or not.
+
+If there B<is> a C<source>, the algorithm finds items in the books which have
+the same posting date I<and> C<source> value. If there is only one, it's a
+match. If there are multiple, the search is repeated; this time the C<amount>
+is included. If there is exactly one resulting item, it's a match. Otherwise
+the algorithm fails.
+
+If there is B<no> C<source>, the algorithm searches items in the books where
+C<amount> and C<post_date> match and the book item does not have a C<source>
+value. The first of all matching items is considered a match.
+
 =head1 PROPERTIES
 
 =head2 entrypoint
@@ -34,12 +69,24 @@ Available values:
 
 =item * add_pending_items
 
+Processes payments and general journal lines, combining them into
+lines which are eligible for inclusion into the reconciliation report.
+
+The C<_book_todo> context parameter is modified to include the result.
+
 =item * approve
 
 =item * delete
 
 =item * reconcile
 
+Processes the items in the C<_book_todo> and C<_stmt_todo> context
+parameters. Matched items are moved to the C<_recon_done> context
+parameter.
+
+The C<_stmt_todo> parameter needs to be set up in the context based
+on an imported statement file before invoking this action.
+
 =item * reject
 
 =item * submit

lib/LedgerSMB/Workflow/Persister/Reconciliation.pm

@@ -11,6 +11,56 @@ This module provides e-mail attachment metadata to e-mail workflow.
 The class inherits from LedgerSMB::Workflow::Persister::ExtraData; users are
 expected to declare the email table and fields as "ExtraData" configuration.
 
+=head1 CONTEXT VARIABLES
+
+=head2 Persisted variables
+
+=over 8
+
+=item * account_id
+
+=item * ending_balance
+
+=item * end_date
+
+=item * recon_fx
+
+=back
+
+=head2 Non-persisted variables
+
+=over 8
+
+=item * _book_todo
+
+An array of items (payments, journal lines) represented as hashes with
+keys C<source>, C<post_date>, C<amount>, C<links>; where C<links> is
+an array of journal lines.
+
+=item * _pending_items
+
+An array of journal lines before the report end date which are available
+for merging into the report (that is, lines which are not already part of
+the report).
+
+=item * _preceeding_draft_count
+
+Number of draft transactions before the end date of the report.
+
+=item * _recon_done
+
+An array of hashes with the keys C<book> and C<stmt>; each a hash with
+the same content as described under C<book_todo> and C<stmt_todo> respectively.
+
+=item * _starting_cleared_balance
+
+=item * _stmt_todo
+
+An array of statement lines that have not been matched; hashes with at least
+the keys C<post_date>, C<amount>, C<source>.
+
+=back
+
 =head1 METHODS
 
 =cut