Add some more "handler" docs

app handler, batch handlers, native batch types, people handler

docs/base/handlers.rst

@@ -1,8 +0,0 @@
-
-App Handlers
-============
-
-TODO
-
-* :doc:`/data/reports/handler`
-* :doc:`/data/batch/handlers`

docs/base/handlers/app.rst

@@ -0,0 +1,23 @@
+
+App Handler
+===========
+
+There is one handler which corresponds to the app itself, whereas all
+other handlers correspond to some "portion" of the app.  This main app
+handler's primary purpose is to:
+
+- provide a common interface for obtaining all other handlers
+- provide some "global" methods, e.g. for rendering date/time values
+
+You can override the main app handler, with config like:
+
+.. code-block:: ini
+
+   [rattail]
+   app.handler = poser.app:PoserAppHandler
+
+Of course that must point to a valid ``AppHandler`` class, which you
+probably must create.
+
+See also :class:`rattail:rattail.app.AppHandler` which is the default
+and base class.

docs/base/handlers/batch.rst

@@ -0,0 +1,15 @@
+
+Batch Handlers
+==============
+
+There is a handler for each unique "type" of batch which exists in the
+app.  For instance the Pricing Batch has its own handler, and so does
+the Inventory Batch, and the Purchase Batch, and so on.
+
+See :doc:`/data/batch/handlers` for some more background on these.
+
+See :doc:`/data/batch/native/index` for a list of natively-supported
+batch types.  (Again, there is a handler for each type.)
+
+See also :class:`rattail:rattail.batch.handlers.BatchHandler` which is
+the base class for all batch handlers.

docs/base/handlers/import.rst

@@ -0,0 +1,7 @@
+
+Import Handlers
+===============
+
+TODO
+
+* :doc:`/data/importing/index`

docs/base/handlers/index.rst

@@ -0,0 +1,24 @@
+
+Handlers
+========
+
+Rattail uses the concept of a "handler" to allow for two things primarily:
+
+- customization of app logic without "forking" Rattail package(s)
+- keep logic in a "single" place which can be leverage by multiple UIs
+
+The idea is that for various aspects of an app, there will be one and
+only one "handler" which is responsible for the business logic.
+Rattail usually comes with a default handler, which will be used
+unless you've created your own handler and configured it to be used
+instead.
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   app
+   batch
+   import
+   other/index

docs/base/handlers/other/board.rst

@@ -0,0 +1,5 @@
+
+Board Handler
+=============
+
+TODO

docs/base/handlers/other/clientele.rst

@@ -0,0 +1,5 @@
+
+Clientele Handler
+=================
+
+TODO

docs/base/handlers/other/email.rst

@@ -0,0 +1,5 @@
+
+Email Handler
+=============
+
+TODO

docs/base/handlers/other/employment.rst

@@ -0,0 +1,5 @@
+
+Employment Handler
+==================
+
+TODO

docs/base/handlers/other/feature.rst

@@ -0,0 +1,5 @@
+
+Feature Handler
+===============
+
+TODO

docs/base/handlers/other/index.rst

@@ -0,0 +1,20 @@
+
+Other / Misc. Handlers
+======================
+
+Here are some handlers which are specific to various aspects of the
+business logic, or a particular feature etc.
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   board
+   clientele
+   email
+   employment
+   feature
+   people
+   products
+   report

docs/base/handlers/other/people.rst

@@ -0,0 +1,19 @@
+
+People Handler
+==============
+
+This handler is responsible for business logic surrounding the
+:class:`~rattail:rattail.db.model.people.Person` model.
+
+You can obtain a reference to the configured handler via
+:meth:`~rattail:rattail.app.AppHandler.get_people_handler`.
+
+You may override the default handler with config like:
+
+.. code-block:: ini
+
+   [rattail]
+   people.handler = poser.people:PoserPeopleHandler
+
+The default handler is :class:`rattail:rattail.people.PeopleHandler` -
+see its documentation for a list of methods you can override.

docs/base/handlers/other/products.rst

@@ -0,0 +1,5 @@
+
+Products Handler
+================
+
+TODO

docs/base/handlers/other/report.rst

@@ -0,0 +1,7 @@
+
+Report Handler
+==============
+
+TODO
+
+* :doc:`/data/reports/handler`

docs/base/index.rst

@@ -18,4 +18,4 @@ Base Layer
    supervisor
    filemon
    upgrades
-   handlers
+   handlers/index

docs/data/batch/index.rst

@@ -9,5 +9,5 @@ Data Batch Processing
    overview
    schema
    handlers
-   native
+   native/index
    custom

docs/data/batch/native.rst

@@ -1,19 +0,0 @@
-
-==================
-Native Batch Types
-==================
-
-The following batch types are provided by Rattail itself.  Listed below for
-each is the "batch type key" followed by the descriptive name.
-
-* ``custorder`` - Customer Order Batch
-* ``handheld`` - Handheld Batch
-* ``importer`` - Importer Batch
-* ``inventory`` - Inventory Batch
-* ``labels`` - Label Batch
-* ``newproduct`` - New Product Batch
-* ``pricing`` - Pricing Batch
-* ``product`` - Product Batch
-* ``purchase`` - Purchasing Batch
-* ``vendor_catalog`` - Vendor Catalog
-* ``vendor_invoice`` - Vendor Invoice

docs/data/batch/native/custorder.rst

@@ -0,0 +1,13 @@
+
+Customer Order Batch
+====================
+
+**Batch Type Key:** ``custorder``
+
+**Purpose:** Create and/or process a customer order.
+
+**Default Handler:** :class:`~rattail:rattail.batch.custorder.CustomerOrderBatchHandler`
+
+As of this writing, the only actual use for this batch is to create a
+*new* customer order, specifically in the context of a so-called
+"case" or "special" order.

docs/data/batch/native/delproduct.rst

@@ -0,0 +1,22 @@
+
+Delete Product Batch
+====================
+
+**Batch Type Key:** ``delproduct``
+
+**Purpose:** Delete products from the system.
+
+**Default Handler:** :class:`~rattail:rattail.batch.delproduct.DeleteProductBatchHandler`
+
+Data for this batch may come from spreadsheet file or grid query, etc.
+
+It should try to catch potential issues which might arise should the
+products actually be deleted, for instance if a given item has pending
+customer orders.
+
+It also should try to highlight items which have seen recent movement,
+to help avoid removing items which are more active than you thought
+etc.
+
+Ultimately executing this batch will just update Rattail by default;
+you may want a custom handler to update your POS system instead.

docs/data/batch/native/handheld.rst

@@ -0,0 +1,17 @@
+
+Handheld Batch
+==============
+
+**Batch Type Key:** ``handheld``
+
+**Purpose:** Process a basic / generic product batch from a handheld device.
+
+**Default Handler:** :class:`~rattail:rattail.batch.handheld.HandheldBatchHandler`
+
+This batch can read from a variety of file formats, which correspond
+to particular types of handheld devices.  The file is expected to have
+a UPC or barcode field, and can optionally have case and/or unit
+quantities for each.
+
+Executing this batch usually just "converts" it into either an
+:doc:`inventory` or a :doc:`labels`.

docs/data/batch/native/importer.rst

@@ -0,0 +1,19 @@
+
+Importer Batch
+==============
+
+**Batch Type Key:** ``importer``
+
+**Purpose:** Allows user to preview an importer run before committing it.
+
+**Default Handler:** :class:`~rattail:rattail.batch.importer.ImporterBatchHandler`
+
+Normally when an importer runs, e.g. via command line, it reads data
+from the host system and writes it to the local / target side.  If in
+dry run mode, then the local data is not actually written.  But it's
+normally "all or nothing" in the sense that you either want to commit
+all the writes, or else you don't (dry run).
+
+It's also possible to write the import data to a batch, which can then
+be previewed and perhaps even adjusted.  Then executing the batch will
+"finalize" the import using data from the batch.

docs/data/batch/native/index.rst

@@ -0,0 +1,26 @@
+
+Native Batch Types
+==================
+
+This section describes all "native" batch types which are provided (in
+whole or in part) by Rattail itself.
+
+Of course you can always make your own batch types for other purposes;
+see :doc:`/data/batch/custom`.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   custorder
+   delproduct
+   handheld
+   importer
+   inventory
+   labels
+   newproduct
+   pricing
+   product
+   purchase
+   vendor_catalog
+   vendor_invoice

docs/data/batch/native/inventory.rst

@@ -0,0 +1,18 @@
+
+Inventory Batch
+===============
+
+**Batch Type Key:** ``inventory``
+
+**Purpose:** Process counts and adjustments for product inventory.
+
+**Default Handler:** :class:`~rattail:rattail.batch.inventory.InventoryBatchHandler`
+
+Data for this batch can come directly from file, or from a Handheld
+Batch etc.  It can contain counts for various products.
+
+Executing this batch with the default handler in place, will cause
+Rattail's own inventory counts to be updated according to the batch
+data.  Depending on your POS system it may be possible to push the
+updates to it instead, and if so you'd probably want to, since your
+POS is likely the authority for current inventory levels.

docs/data/batch/native/labels.rst

@@ -0,0 +1,17 @@
+
+Label Batch
+===========
+
+**Batch Type Key:** ``labels``
+
+**Purpose:** Print item labels / shelf tags for a set of products.
+
+**Default Handler:** :class:`~rattail:rattail.batch.labels.LabelBatchHandler`
+
+Data for this batch can come directly from file, or from a
+:doc:`handheld` etc.  It can contain a list of items and various label
+printing attributes for each.
+
+Executing this batch may send a job(s) directly to your dedicated
+label printer if you have one.  Or it can generate an Excel file for
+use with BarTender or other software, etc.

docs/data/batch/native/newproduct.rst

@@ -0,0 +1,16 @@
+
+New Product Batch
+=================
+
+**Batch Type Key:** ``newproduct``
+
+**Purpose:** Import new products into the system.
+
+**Default Handler:** :class:`~rattail:rattail.batch.newproduct.NewProductBatchHandler`
+
+Data for this batch usually comes from a spreadsheet file.  It should
+contain new product records, with all necessary data for each.
+
+Executing this batch may just create the item in Rattail by default.
+You may want to use a custom handler for inserting the item directly
+to your POS system instead, for instance.

docs/data/batch/native/pricing.rst

@@ -0,0 +1,22 @@
+
+Pricing Batch
+=============
+
+**Batch Type Key:** ``pricing``
+
+**Purpose:** Change pricing for a set of products, optionally calculating new prices.
+
+**Default Handler:** :class:`~rattail:rattail.batch.pricing.PricingBatchHandler`
+
+There are sort of 2 modes for this batch type:
+
+In "static" mode you would have a data file containing the new prices,
+which you upload as a new batch.  Executing this batch would then
+apply the prices from the file.
+
+In "dynamic" mode you need only identify the set of products, and then
+let the software calculate new prices for each.  Executing this batch
+would then apply the new calculated prices.
+
+In either case the default handler will update Rattail itself, so you
+may need a custom handler to update your POS instead.

docs/data/batch/native/product.rst

@@ -0,0 +1,15 @@
+
+Product Batch
+=============
+
+**Batch Type Key:** ``product``
+
+**Purpose:** Generic batch to identify and act on a set of items.
+
+**Default Handler:** :class:`~rattail:rattail.batch.product.ProductBatchHandler`
+
+Data for this batch type usually comes from a simple file, or perhaps
+a grid query.  Executing it will usually create another type of batch
+using the current one only to define which items are involved.  For
+example by default it will create either a :doc:`labels` or a
+:doc:`pricing`.

docs/data/batch/native/purchase.rst

@@ -0,0 +1,27 @@
+
+Purchase Batch
+==============
+
+**Batch Type Key:** ``purchase``
+
+**Purpose:** Provides workflows for ordering, receiving, and invoice costing.
+
+**Default Handler:** :class:`~rattail:rattail.batch.purchase.PurchaseBatchHandler`
+
+There are 3 "modes" for this type of batch, meant to correspond to the
+life-cycle of a purchase order:
+
+- Ordering
+- Receiving
+- Costing
+
+Depending on the mode, data for the batch may come from any of:
+
+- PO file or invoice file from the vendor
+- purchase order data from the POS system
+- directly entered via the Rattail app
+
+Execution of this type of batch will also depend on the mode.  The
+default handler may just update Rattail data (e.g. ``purchase`` table)
+according to the batch.  If applicable, you may want a custom handler
+so it updates your POS instead.

docs/data/batch/native/vendor_catalog.rst

@@ -0,0 +1,18 @@
+
+Vendor Catalog Batch
+====================
+
+**Batch Type Key:** ``vendor_catalog``
+
+**Purpose:** Allows updating product costs from new catalog data
+
+**Default Handler:** :class:`~rattail:rattail.batch.vendorcatalog.VendorCatalogHandler`
+
+Data for this type of batch usually comes from a spreadsheet or
+similar file, as obtained directly from the vendor.  You can also
+define a "common" format to use, in which case you would convert each
+vendor file to that format.  (That is to cut down on the number of
+file parsers needed.)
+
+In any case executing this batch will just update Rattail by default;
+you may want a custom handler to update your POS system instead.

docs/data/batch/native/vendor_invoice.rst

@@ -0,0 +1,20 @@
+
+Vendor Invoice Batch
+====================
+
+**Batch Type Key:** ``vendor_invoice``
+
+**Purpose:** (DEPRECATED) Process a vendor invoice
+
+**Default Handler:** :class:`~rattail:rattail.batch.vendorinvoice.VendorInvoiceHandler`
+
+.. warning::
+   This batch type should be considered deprecated.  It still exists
+   and may be used, but that may not always be the case.  If possible
+   please use :doc:`purchase` instead.
+
+Data for this type of batch usually comes from a spreadsheet or
+similar file, as obtained directly from the vendor.
+
+Executing this batch does nothing at all by default; you would need a
+custom handler to make it useful.