rattail-manual/docs/data/custorders/workflows.rst

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.