Merge pull request #719 from eileenmcnaughton/financial_entities

Flesh out information about financial items

docs/financial/financialentities.md

@@ -61,3 +61,28 @@ Negative payments (or refunds) will have the bank or processor account on the **
 
 Financial items exist to track how much has been paid against the various line items within an order / contribution.
 In an accounting system this might be called credit-matching.
+
+Each line item will have one or more financial items denoting payments made against it. On creation of the order there
+will be a financial item for each line item and an additional item for every fee amount. Where the preferred flow is used
+this item will have a status of 'Unpaid'.
+
+!!! note
+    For historical reasons this may not always be true but [it's the goal](https://github.com/civicrm/civicrm-dev-docs/issues/712).
+
+When a payment is made it might either pay off the line items, or a specific line item, in full. In that case the line item
+status is updated to Paid and an `EntityFinancialTrxn` record is created in the `civicrm_entity_financial_trxn` table linking
+the line item to the payment and specifying the amount paid.
+
+If the line item is paid in part then the status is not updated and the `EntityFinancialTrxn` record specifies the portion
+of the line item that has been paid by that payment.
+
+If the line items change then the items financial items have to be updated. Generally the rule is to alter the zero out the
+old line item, reverse the financial items and then create a new line item with new financial items. However, this is not
+always  possible as there are some scenarios where the schema does not permit this. The has led to
+adjustment line items being created in these cases. The issue is that the `civicrm_line_item` table has a unique index for
+`entity_table + entity_id + contribution_id + price_field_value_id + price_field_id`.
+
+This means that if a line item with no `price_field_values` (i.e: a text / enter quantity line item) is altered it is not possible
+to create a reversal line and a new line within the schema. The same problem occurs when changing a line item with `price_field_values`
+***back*** to a `price_field_value` it previously held. In both these scenarios the work around is to have more than one *valid* `financial_item`
+against the resulting line item with an *adjustment* entry -  i.e: an additional `financial_item`.