From 84477e5e36c696bc6765eb68e4789e31be9b48d3 Mon Sep 17 00:00:00 2001 From: Lance Edgar Date: Wed, 18 Aug 2021 12:49:40 -0500 Subject: [PATCH] Add some more "handler" docs app handler, batch handlers, native batch types, people handler --- docs/base/handlers.rst | 8 ------- docs/base/handlers/app.rst | 23 +++++++++++++++++++ docs/base/handlers/batch.rst | 15 +++++++++++++ docs/base/handlers/import.rst | 7 ++++++ docs/base/handlers/index.rst | 24 ++++++++++++++++++++ docs/base/handlers/other/board.rst | 5 +++++ docs/base/handlers/other/clientele.rst | 5 +++++ docs/base/handlers/other/email.rst | 5 +++++ docs/base/handlers/other/employment.rst | 5 +++++ docs/base/handlers/other/feature.rst | 5 +++++ docs/base/handlers/other/index.rst | 20 +++++++++++++++++ docs/base/handlers/other/people.rst | 19 ++++++++++++++++ docs/base/handlers/other/products.rst | 5 +++++ docs/base/handlers/other/report.rst | 7 ++++++ docs/base/index.rst | 2 +- docs/data/batch/index.rst | 2 +- docs/data/batch/native.rst | 19 ---------------- docs/data/batch/native/custorder.rst | 13 +++++++++++ docs/data/batch/native/delproduct.rst | 22 ++++++++++++++++++ docs/data/batch/native/handheld.rst | 17 ++++++++++++++ docs/data/batch/native/importer.rst | 19 ++++++++++++++++ docs/data/batch/native/index.rst | 26 ++++++++++++++++++++++ docs/data/batch/native/inventory.rst | 18 +++++++++++++++ docs/data/batch/native/labels.rst | 17 ++++++++++++++ docs/data/batch/native/newproduct.rst | 16 ++++++++++++++ docs/data/batch/native/pricing.rst | 22 ++++++++++++++++++ docs/data/batch/native/product.rst | 15 +++++++++++++ docs/data/batch/native/purchase.rst | 27 +++++++++++++++++++++++ docs/data/batch/native/vendor_catalog.rst | 18 +++++++++++++++ docs/data/batch/native/vendor_invoice.rst | 20 +++++++++++++++++ 30 files changed, 397 insertions(+), 29 deletions(-) delete mode 100644 docs/base/handlers.rst create mode 100644 docs/base/handlers/app.rst create mode 100644 docs/base/handlers/batch.rst create mode 100644 docs/base/handlers/import.rst create mode 100644 docs/base/handlers/index.rst create mode 100644 docs/base/handlers/other/board.rst create mode 100644 docs/base/handlers/other/clientele.rst create mode 100644 docs/base/handlers/other/email.rst create mode 100644 docs/base/handlers/other/employment.rst create mode 100644 docs/base/handlers/other/feature.rst create mode 100644 docs/base/handlers/other/index.rst create mode 100644 docs/base/handlers/other/people.rst create mode 100644 docs/base/handlers/other/products.rst create mode 100644 docs/base/handlers/other/report.rst delete mode 100644 docs/data/batch/native.rst create mode 100644 docs/data/batch/native/custorder.rst create mode 100644 docs/data/batch/native/delproduct.rst create mode 100644 docs/data/batch/native/handheld.rst create mode 100644 docs/data/batch/native/importer.rst create mode 100644 docs/data/batch/native/index.rst create mode 100644 docs/data/batch/native/inventory.rst create mode 100644 docs/data/batch/native/labels.rst create mode 100644 docs/data/batch/native/newproduct.rst create mode 100644 docs/data/batch/native/pricing.rst create mode 100644 docs/data/batch/native/product.rst create mode 100644 docs/data/batch/native/purchase.rst create mode 100644 docs/data/batch/native/vendor_catalog.rst create mode 100644 docs/data/batch/native/vendor_invoice.rst diff --git a/docs/base/handlers.rst b/docs/base/handlers.rst deleted file mode 100644 index f889376..0000000 --- a/docs/base/handlers.rst +++ /dev/null @@ -1,8 +0,0 @@ - -App Handlers -============ - -TODO - -* :doc:`/data/reports/handler` -* :doc:`/data/batch/handlers` diff --git a/docs/base/handlers/app.rst b/docs/base/handlers/app.rst new file mode 100644 index 0000000..83375ea --- /dev/null +++ b/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. diff --git a/docs/base/handlers/batch.rst b/docs/base/handlers/batch.rst new file mode 100644 index 0000000..5f1022c --- /dev/null +++ b/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. diff --git a/docs/base/handlers/import.rst b/docs/base/handlers/import.rst new file mode 100644 index 0000000..2a6d7ca --- /dev/null +++ b/docs/base/handlers/import.rst @@ -0,0 +1,7 @@ + +Import Handlers +=============== + +TODO + +* :doc:`/data/importing/index` diff --git a/docs/base/handlers/index.rst b/docs/base/handlers/index.rst new file mode 100644 index 0000000..8aefc33 --- /dev/null +++ b/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 diff --git a/docs/base/handlers/other/board.rst b/docs/base/handlers/other/board.rst new file mode 100644 index 0000000..8b835ce --- /dev/null +++ b/docs/base/handlers/other/board.rst @@ -0,0 +1,5 @@ + +Board Handler +============= + +TODO diff --git a/docs/base/handlers/other/clientele.rst b/docs/base/handlers/other/clientele.rst new file mode 100644 index 0000000..9a23448 --- /dev/null +++ b/docs/base/handlers/other/clientele.rst @@ -0,0 +1,5 @@ + +Clientele Handler +================= + +TODO diff --git a/docs/base/handlers/other/email.rst b/docs/base/handlers/other/email.rst new file mode 100644 index 0000000..96c240e --- /dev/null +++ b/docs/base/handlers/other/email.rst @@ -0,0 +1,5 @@ + +Email Handler +============= + +TODO diff --git a/docs/base/handlers/other/employment.rst b/docs/base/handlers/other/employment.rst new file mode 100644 index 0000000..b5d4fec --- /dev/null +++ b/docs/base/handlers/other/employment.rst @@ -0,0 +1,5 @@ + +Employment Handler +================== + +TODO diff --git a/docs/base/handlers/other/feature.rst b/docs/base/handlers/other/feature.rst new file mode 100644 index 0000000..46c85c5 --- /dev/null +++ b/docs/base/handlers/other/feature.rst @@ -0,0 +1,5 @@ + +Feature Handler +=============== + +TODO diff --git a/docs/base/handlers/other/index.rst b/docs/base/handlers/other/index.rst new file mode 100644 index 0000000..c179129 --- /dev/null +++ b/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 diff --git a/docs/base/handlers/other/people.rst b/docs/base/handlers/other/people.rst new file mode 100644 index 0000000..ef3f392 --- /dev/null +++ b/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. diff --git a/docs/base/handlers/other/products.rst b/docs/base/handlers/other/products.rst new file mode 100644 index 0000000..675b1b4 --- /dev/null +++ b/docs/base/handlers/other/products.rst @@ -0,0 +1,5 @@ + +Products Handler +================ + +TODO diff --git a/docs/base/handlers/other/report.rst b/docs/base/handlers/other/report.rst new file mode 100644 index 0000000..68995c3 --- /dev/null +++ b/docs/base/handlers/other/report.rst @@ -0,0 +1,7 @@ + +Report Handler +============== + +TODO + +* :doc:`/data/reports/handler` diff --git a/docs/base/index.rst b/docs/base/index.rst index 92a4ff5..6381f70 100644 --- a/docs/base/index.rst +++ b/docs/base/index.rst @@ -18,4 +18,4 @@ Base Layer supervisor filemon upgrades - handlers + handlers/index diff --git a/docs/data/batch/index.rst b/docs/data/batch/index.rst index 8e2e90e..e61095d 100644 --- a/docs/data/batch/index.rst +++ b/docs/data/batch/index.rst @@ -9,5 +9,5 @@ Data Batch Processing overview schema handlers - native + native/index custom diff --git a/docs/data/batch/native.rst b/docs/data/batch/native.rst deleted file mode 100644 index 8823d23..0000000 --- a/docs/data/batch/native.rst +++ /dev/null @@ -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 diff --git a/docs/data/batch/native/custorder.rst b/docs/data/batch/native/custorder.rst new file mode 100644 index 0000000..ca859b3 --- /dev/null +++ b/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. diff --git a/docs/data/batch/native/delproduct.rst b/docs/data/batch/native/delproduct.rst new file mode 100644 index 0000000..8f92663 --- /dev/null +++ b/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. diff --git a/docs/data/batch/native/handheld.rst b/docs/data/batch/native/handheld.rst new file mode 100644 index 0000000..17bc45a --- /dev/null +++ b/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`. diff --git a/docs/data/batch/native/importer.rst b/docs/data/batch/native/importer.rst new file mode 100644 index 0000000..34eadd5 --- /dev/null +++ b/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. diff --git a/docs/data/batch/native/index.rst b/docs/data/batch/native/index.rst new file mode 100644 index 0000000..4eb2e8a --- /dev/null +++ b/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 diff --git a/docs/data/batch/native/inventory.rst b/docs/data/batch/native/inventory.rst new file mode 100644 index 0000000..d8824d9 --- /dev/null +++ b/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. diff --git a/docs/data/batch/native/labels.rst b/docs/data/batch/native/labels.rst new file mode 100644 index 0000000..a513c2d --- /dev/null +++ b/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. diff --git a/docs/data/batch/native/newproduct.rst b/docs/data/batch/native/newproduct.rst new file mode 100644 index 0000000..9cd2bf8 --- /dev/null +++ b/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. diff --git a/docs/data/batch/native/pricing.rst b/docs/data/batch/native/pricing.rst new file mode 100644 index 0000000..d8fb97b --- /dev/null +++ b/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. diff --git a/docs/data/batch/native/product.rst b/docs/data/batch/native/product.rst new file mode 100644 index 0000000..9ad95bb --- /dev/null +++ b/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`. diff --git a/docs/data/batch/native/purchase.rst b/docs/data/batch/native/purchase.rst new file mode 100644 index 0000000..d172e86 --- /dev/null +++ b/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. diff --git a/docs/data/batch/native/vendor_catalog.rst b/docs/data/batch/native/vendor_catalog.rst new file mode 100644 index 0000000..77c1425 --- /dev/null +++ b/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. diff --git a/docs/data/batch/native/vendor_invoice.rst b/docs/data/batch/native/vendor_invoice.rst new file mode 100644 index 0000000..2cce5d9 --- /dev/null +++ b/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.