Add initial docs for Customer Order system features

docs/data/custorders/index.rst

@@ -0,0 +1,19 @@
+
+Customer Orders
+===============
+
+Rattail has a "customer order" system of sorts.  I'm calling it a
+"customer order" system but most folks will probably think of it as
+e.g. a "special order" system or "case order" system etc.
+
+This section describes the "customer order" features of Rattail.
+
+See the online `Theo demo`_ to play around with this concept.  It has
+access to a CORE-POS system, from which it gets customer/product data.
+
+.. _Theo demo: https://demo-theo.rattailproject.org/
+
+.. toctree::
+
+   overview
+   workflows

docs/data/custorders/overview.rst

@@ -0,0 +1,67 @@
+
+Customer Order Overview
+=======================
+
+Here we offer a general overview of the "customer order" features
+provided by Rattail.
+
+
+Rationale
+---------
+
+There are many potential scenarios, where it may be helpful to track a
+customer order.  Basically that's exactly what a POS system does,
+albeit a particular type of order (immediately fulfilled).
+
+Often another particular type of order (case/special orders) is *not*
+tracked very well, if at all, by the POS system.  There may be other
+types of tracking that is needed to help with basket picking and
+curbside delivery, warehouse fulfillment, etc.
+
+So the thinking is that we just call all those "customer orders" and
+use common schema and logic to track them, to the extent possible.
+
+
+Objectives
+----------
+
+Short version:
+
+#. common schema
+#. common logic
+
+The schema for customer orders should be generic and useful enough to
+accommodate the various scenarios needed.  Obviously each order has a
+customer assigned to it, and it has one or more items (products) being
+ordered.  Any new "common" scenarios which require additional
+attributes to be tracked on the order and/or items, should probably
+require the Rattail schema to change.  Any new "esoteric" scenarios
+needing extra attributes should require custom schema extensions.
+
+The logic for customer orders may vary in lots of ways for different
+scenarios, but certain things will likely come up in several places,
+and so the logic should be shared where it makes sense.
+
+
+Strategy
+--------
+
+We assume you already have a POS with customers and products.  It of
+course handles the normal scenario of POS transactions, e.g. a
+customer grabs a root beer from the shelf and then walks to the
+cashier and pays for it.
+
+But when that customer wants to order a case of root beer, and come
+pick it up next week after the truck comes in, is often a different
+story, and that scenario is "handled" by way of post-it notes and
+maybe an Excel spreadsheet thrown in somewhere...
+
+Rattail's customer order system can help with that.  It is generally
+able to talk to other POS systems which means it can present customer
+and product choices for a user entering a new order to the system.
+Once the order is entered, it can be updated as needed via some
+workflow(s).
+
+At this time only the "case/special order" type is supported by
+Rattail proper.  Other types may be supported in the future; however
+any project can establish other types and support them as needed.

docs/data/custorders/workflows.rst

@@ -0,0 +1,157 @@
+
+Customer Order Workflows
+========================
+
+At time of writing Rattail only supports one workflow for customer
+orders, and that is the "case / special" order scenario.  We expect at
+some point there may be others, e.g. to assist with basket picking and
+curbside delivery etc.
+
+
+Case/Special Orders
+-------------------
+
+To be clear, this is the sort of scenario we're talking about here:
+
+* Customer walks up to the cashier and says they'd like to order a
+  case of root beer.
+* Cashier says yep we can probably get that in by late next week.
+* Cashier jots down a note etc. to inform the buyer of need to add a
+  case of root beer on their next order to the vendor.
+* Truck arrives next week and case of root beer is set aside, customer
+  is notified via phone call or possibly email.
+* Customer comes in and picks up the root beer.
+
+Now, *somewhere* in there the customer needs to pay for the case of
+root beer.  More on that later.
+
+
+Entering a New Order
+~~~~~~~~~~~~~~~~~~~~
+
+Entering a new order is essentially the same regardless of order type:
+
+* initiate a new order
+* select customer record, or enter new one
+* select one or more items, and/or enter new ones
+* submit the new order
+
+Initiating the order is done automatically when user visits the New
+Customer Order page.
+
+User then must select an existing customer record, or enter minimal
+details for a new one to be added to the system.  Note that an
+"unknown customer" (i.e. one not yet in the system) is not considered
+a "problem" and will (generally) not inhibit the order from advancing
+in its workflow.
+
+Products work the same way, user either selects existing or can enter
+minimal details for new one(s) to be added to the system.  Note
+however that in many cases, an "unknown product" *is* considered a
+"problem" and *may* inhibit the order from advancing in its workflow.
+
+
+Batch Implementation
+~~~~~~~~~~~~~~~~~~~~
+
+Rattail internally uses a batch to track the new order.  When that
+batch is executed, it becomes "real" by way of conversion to a proper
+customer order.
+
+So when the new order is "initiated" (as mentioned in previous
+section), really a new batch is created.  When user selects customer
+and products etc.  the batch is updated.  When user clicks "Submit
+this Order" button then the batch is executed.
+
+Note that the batch makes it possible to use the New Customer Order
+screen to build an order which in fact will be submitted to some
+*other* (e.g. non-Rattail) system for further tracking.  One need only
+configure a custom batch handler and override the ``execute()`` method
+to do whatever is needed with the final order data.
+
+
+Order Item Status
+~~~~~~~~~~~~~~~~~
+
+When the order is first submitted, each item on the order will be
+given "initiated" status.
+
+The item's status should be updated as its workflow progresses.  It
+generally should be possible to manually change status for an item,
+but certain workflow-specific interfaces (web pages) may provide tools
+to make some status changes more convenient etc.
+
+See the :mod:`rattail:rattail.enum` module, specifically
+``CUSTORDER_ITEM_STATUS``, for all possible values, unless you've
+overridden that for your project.  Here are some of the more common
+status values an item may go through in its life:
+
+* ``CUSTORDER_ITEM_STATUS_INITIATED``
+* ``CUSTORDER_ITEM_STATUS_PLACED``
+* ``CUSTORDER_ITEM_STATUS_RECEIVED``
+* ``CUSTORDER_ITEM_STATUS_CONTACTED``
+* ``CUSTORDER_ITEM_STATUS_DELIVERED``
+
+
+Receiving Payment
+~~~~~~~~~~~~~~~~~
+
+We've mostly avoided talk of payment thus far, but it needs to happen.
+Some stores will have different perspectives on this but they can
+probably be boiled down to just two types: either payment is required
+up-front (e.g. before buyer will order the product from vendor), or
+it's required at the end when customer picks up product.
+
+To work well, this requires that Rattail have access to the POS
+transaction data, so it can check transactions for customer order
+payments.  This of course also requires such customer order payments
+to be "marked" in some way within the POS transaction, to make it
+clear which order is being paid for etc.
+
+
+Payment Required Up-Front
++++++++++++++++++++++++++
+
+If payment is required up-front then probably that means, after the
+order is first submitted, its status remains "initiated" until payment
+is confirmed to have been received, at which point the buyer is
+cleared to add the item onto their next vendor order.
+
+In this case we can make use of the ``CUSTORDER_ITEM_STATUS_PAID``
+status, which logically sits between ``INITIATED`` and ``PLACED``.
+Buyers then would only "see" the orders with paid status, when looking
+for things to add on their vendor order.
+
+To work well, this requires that Rattail have "real-time" access to
+the POS transaction data.  If a customer places new order at 1pm, and
+pays for it, and buyer is placing vendor order at 4pm, it would be a
+shame if they didn't "see" the new order b/c payment hadn't yet been
+processed...
+
+This also poses the problem of, how to accurately ring up the various
+items on the customer order, in a POS transaction.  If payment happend
+at the end then cashier can simply scan the product which is
+physically present.  Whereas "pre-payment" may require a paper
+printout of the item scancodes needed, which is then scanned at POS by
+the cashier when taking payment.
+
+
+Payment Required at the End
++++++++++++++++++++++++++++
+
+If payment is required at the end then things get simpler, compared to
+payment up-front.
+
+After the order is first submitted it will still remain "initiated"
+but in this case that is precisely what the buyer will see when doing
+their vendor order thing.
+
+Rattail will still need access to POS transaction data, but it doesn't
+have to be real-time, it can process the day's transactions overnight
+if that's easier, because there is no urgency to the final status
+update.
+
+A payment within a POS transaction will still need to be marked
+clearly so that it is attributed to the correct order etc.  But as
+mentioned above, the cashier can simply scan the physical items
+present, so there is no question of "how" to ring up the items.

docs/data/index.rst

@@ -13,6 +13,7 @@ Data Layer
    sync
    versioning
    batch/index
+   custorders/index
    reports/index
    problems
    multinode