Add some more "handler" docs

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

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.