Add more docs for Feature Layer

not complete, but progress..

docs/features/custorders/cancellation/index.rst

@@ -0,0 +1,6 @@
+
+Cancellations / Other
+=====================
+
+TODO: obviously sometimes a customer may cancel their order before it
+arrives...then what?  i'm sure it depends, as always...

docs/features/custorders/entry/index.rst

@@ -0,0 +1,52 @@
+
+Entry
+=====
+
+Entering a new Customer Order into the system is very likely the most
+complicated part.  Consider:
+
+The "Customer" (or in some cases a "Person") must be identified, whose
+order this will be.  What if they're a new Customer/Person, not yet in
+the system?  Can they be added directly to Rattail and other systems
+will be updated accordingly?  Or must they be first added to the other
+system and then imported back to Rattail?  (For sake of the order, can
+a "Pending Customer" record be created and then sort the rest out
+later?)
+
+One or more "Products" will be added to the Order.  Can they order
+*any* (e.g. unit) amount or is there a "cases only" policy etc.?
+Perhaps also some other restrictions based on Department, e.g. no more
+than X cases of frozen product due to space limitations.
+
+Where does all that Customer and Product data come from anyway?  Is it
+accurate enough to be used for creating "reliable" Order data?  Is the
+Customer to be charged according to whatever price is calculated in
+the Order, or are they charged "whatever the POS rings up" etc.?  Are
+discounts ever quoted in the order, vs. handled only by POS?
+
+Speaking of payments, does the customer need to pay up-front when
+first placing the order?  Or do they pay later when they pick it up?
+
+Wait, what if they want to order a Product which is not yet in the
+system?  Is this allowed, and if so what are the policies surrounding
+that?
+
+So, the Rattail feature tries to accommodate all of the above
+regardless of how you answer.
+
+First of all the Customer/Person and Product data should already be
+*imported* to Rattail from your POS or other system(s), before
+tackling Customer Orders.  This feature assumes the underlying data is
+already squared away and accurate (within reason).
+
+Second, it's worth noting that the New Customer Order tool is
+implemented as a batch (see also :doc:`/data/batch/native/custorder`).
+This is important because it makes it possible to use the New Customer
+Order tool as the entry workflow for a Customer Order *even if* you do
+not track those primarily in Rattail.  In other words when the batch
+is executed, it can "push" the Order data to whatever system is
+needed.
+
+But of course the Rattail DB has its own schema for tracking these
+Customer Orders, so the default "new batch" execution will create the
+Order directly in Rattail.

docs/features/custorders/fulfilment/index.rst

@@ -0,0 +1,20 @@
+
+Fulfilment
+==========
+
+In the context of Customer Orders, "fulfilment" requires that:
+
+* customer has paid for the product
+* customer has possession of the product
+* order data reflects these facts
+
+Some places will require the Customer to pay for the Order when they
+place it, in which case the first is taken care of already.  But if
+not, then the physical product can be rang up at POS when they come to
+pick up.
+
+If the product is paid for upon pick-up then Rattail has a way to
+"automatically detect" that fulfilment has occurred (by monitoring the
+POS Transactions).  But if payment happens up-front then likely some
+User must explicitly indicate to Rattail that fulfilment is complete,
+i.e. product was picked up by Customer.

docs/features/custorders/index.rst

@@ -0,0 +1,32 @@
+
+Customer Orders
+===============
+
+Presumably all retailers sell products to customers.  Most will have a
+dedicated point of sale (POS) system for that.
+
+Additionally, some retailers let customers place orders for product
+which will arrive in store for pickup at a later date.  These are
+often referred to as "special orders" or "case orders" etc.
+
+Rattail offers tools to facilitate entry and tracking for such orders,
+providing visibility and workflows for their full life cycle.
+
+.. note::
+   Now that we all know what "COVID" means, online orders with
+   curbside and delivery options have risen in prominence.  For the
+   moment Rattail does not directly provide features with those in
+   mind.  However this "customer orders" feature is clearly related,
+   and probably a lot of the schema and/or logic could be shared
+   between scenarios.  But so far only the classic "special/case
+   order" scenario is being addressed.
+
+.. toctree::
+   :maxdepth: 1
+
+   entry/index
+   purchasing/index
+   receiving/index
+   fulfilment/index
+   cancellation/index
+   reporting/index

docs/features/custorders/purchasing/index.rst

@@ -0,0 +1,12 @@
+
+Purchasing
+==========
+
+In the context of Customer Orders, our concern here is making sure the
+Buyer knows about them and includes them in the Purchase Order(s)
+which they are already placing to the Vendor per normal procedure.
+
+TODO: this has been implemented a couple of different ways thus far
+but the "best" has yet to be decided...in particular (how) should the
+customer orders and purchase orders be linked?  it is a slight hassle
+up front but then can be leveraged during the receiving process...

docs/features/custorders/receiving/index.rst

@@ -0,0 +1,15 @@
+
+Receiving
+=========
+
+In the context of Customer Orders, our concern here is making sure the
+Receiver knows about them and sets them aside while receiving the
+Purchase Order, once it's arrived from the Vendor.
+
+Another concern is how/when/who should contact the Customer to notify
+them that their order has arrived.  If the Customer account has a
+valid email address on file then perhaps they are emailed
+automatically; otherwise an Employee must call their phone number etc.
+In either case the *attempt* to contact the Customer should be
+recorded somehow, along with notes e.g. indicating if it was
+successful.

docs/features/custorders/reporting/index.rst

@@ -0,0 +1,52 @@
+
+Reporting
+=========
+
+Reporting on Customer Orders data is possible but as of writing is
+still being worked out.
+
+The asumption here is that you want to track "sales" which are
+attributable to Customer Orders.
+
+The "easiest" way, though potentially inaccurate, is simply to query
+the Customer Orders data and assume that if a given Order's "status"
+reflects that e.g. it has been paid for, then include it in the
+report.
+
+On the other hand the precise amount paid by the customer may or may
+not even be in the Customer Order data.  Even if it is there, is it
+correct, or was it just an "estimate" and really a related POS
+Transaction must be consulted for the true price.
+
+However the Order status likely *is* important on some level, to
+detect cancellations etc.  Presumably if a refund is given, the POS
+Transaction would have that amount, but there likely is nothing to tie
+that back to the particular Order which was canceled.
+
+So at the moment the focus is on recording "links" between a given
+Customer Order and POS Transaction.  This is done by way of a
+Trainwreck DB (see also :doc:`../../transactions/importing/index`):
+
+A transaction is imported to Trainwreck as per usual, but in addition
+to the normal stuff, the transaction is inspected for any "indicators"
+of Customer Orders.  (Often the cashier scans or enters some ID for
+the Order when ringing it up.)  Such indicators are then stored in a
+dedicated place within Trainwreck.  This takes care of the "high
+level" meaning we now have links between a POS Transaction and
+Customer Order.
+
+But really, a POS Transaction has "line items" and so does a Customer
+Order.  So we actually need a link between the relevant line items.
+
+The line item links are established in a second phase.  So the first
+phase is focused on importing POS Transaction data, and we've done
+that.  But now Trainwreck has all those line items and so the
+item-level reconciliation can be done "natively".  Again we already
+have the high-level links, so we fetch a linked pair (Transaction and
+Order) and then crawl each to identify item-level links, and record
+any which are found.
+
+Once that is complete, a Customer Orders report can more easily obtain
+accurate payment amounts from the POS Transaction data (although it
+reads from Trainwreck instead for convenience).  And of course it can
+still leverage the Customer Order status etc. as needed.