changeset 0032a1985534 in modules/stock:default details: https://hg.tryton.org/modules/stock?cmd=changeset;node=0032a1985534 description: Improve documentation
issue9681 review302311002 diffstat: doc/conf.py | 61 ++++++++ doc/design/configuration.rst | 17 ++ doc/design/index.rst | 16 ++ doc/design/inventory.rst | 48 ++++++ doc/design/location.rst | 59 +++++++ doc/design/move.rst | 58 +++++++ doc/design/period.rst | 32 ++++ doc/design/product.rst | 97 +++++++++++++ doc/design/shipment.rst | 231 +++++++++++++++++++++++++++++++ doc/index.rst | 319 +----------------------------------------- doc/reference.rst | 13 + doc/setup.rst | 69 +++++++++ doc/usage/index.rst | 14 + doc/usage/period.rst | 16 ++ doc/usage/quantity.rst | 98 +++++++++++++ doc/usage/shipment.rst | 125 ++++++++++++++++ doc/usage/value.rst | 66 ++++++++ setup.py | 7 +- 18 files changed, 1038 insertions(+), 308 deletions(-) diffs (1438 lines): diff -r 86bbfaea7a8c -r 0032a1985534 doc/conf.py --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/conf.py Sat Feb 06 10:51:53 2021 +0000 @@ -0,0 +1,61 @@ +# This file is part of Tryton. The COPYRIGHT file at the top level of +# this repository contains the full copyright notices and license terms. + +modules_url = 'https://docs.tryton.org/projects/modules-{module}/en/{series}/' +trytond_url = 'https://docs.tryton.org/projects/server/en/{series}/' + + +def get_info(): + import configparser + import os + import subprocess + import sys + + module_dir = os.path.dirname(os.path.dirname(__file__)) + + config = configparser.ConfigParser() + config.read_file(open(os.path.join(module_dir, 'tryton.cfg'))) + info = dict(config.items('tryton')) + + result = subprocess.run( + [sys.executable, 'setup.py', '--name'], + stdout=subprocess.PIPE, check=True, cwd=module_dir) + info['name'] = result.stdout.decode('utf-8').strip() + + result = subprocess.run( + [sys.executable, 'setup.py', '--version'], + stdout=subprocess.PIPE, check=True, cwd=module_dir) + version = result.stdout.decode('utf-8').strip() + if 'dev' in version: + info['series'] = 'latest' + else: + info['series'] = '.'.join(version.split('.', 2)[:2]) + + for key in {'depends', 'extras_depend'}: + info[key] = info.get(key, '').strip().splitlines() + info['modules'] = set(info['depends'] + info['extras_depend']) + info['modules'] -= {'ir', 'res'} + + return info + + +info = get_info() + +master_doc = 'index' +project = info['name'] +release = version = info['series'] +default_role = 'ref' +highlight_language = 'none' +extensions = [ + 'sphinx.ext.intersphinx', + ] +intersphinx_mapping = { + 'trytond': (trytond_url.format(series=version), None), + } +intersphinx_mapping.update({ + m: (modules_url.format( + module=m.replace('_', '-'), series=version), None) + for m in info['modules'] + }) + +del get_info, info, modules_url, trytond_url diff -r 86bbfaea7a8c -r 0032a1985534 doc/design/configuration.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/design/configuration.rst Sat Feb 06 10:51:53 2021 +0000 @@ -0,0 +1,17 @@ +.. _model-stock.configuration: + +Configuration +============= + +The *Stock Configuration* contains settings that are used to configure the +behaviour and default values for stock related activities, including the +sequences used to generate `Shipment <concept-stock.shipment>` numbers. + +.. seealso:: + + The stock configuration can be found using the main menu item: + + |Inventory & Stock --> Configuration --> Stock Configuration|__ + + .. |Inventory & Stock --> Configuration --> Stock Configuration| replace:: :menuselection:`Inventory & Stock --> Configuration --> Stock Configuration` + __ https://demo.tryton.org/model/stock.configuration/1 diff -r 86bbfaea7a8c -r 0032a1985534 doc/design/index.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/design/index.rst Sat Feb 06 10:51:53 2021 +0000 @@ -0,0 +1,16 @@ +****** +Design +****** + +The stock module introduces or extends the following concepts. + +.. toctree:: + :maxdepth: 1 + + location + move + shipment + inventory + period + configuration + product diff -r 86bbfaea7a8c -r 0032a1985534 doc/design/inventory.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/design/inventory.rst Sat Feb 06 10:51:53 2021 +0000 @@ -0,0 +1,48 @@ +.. _model-stock.inventory: + +Inventory +========= + +The *Inventory* concept is used to help check and correct the amount of +stock stored in a `Location <model-stock.location>`. + +Each inventory has a set of lines, one for each `Product <concept-product>` +that is in, or is should be in, the location. +Each line has an expected quantity and an actual quantity. +The former is used to show how much stock is expected to be in the location +and the latter is used to record how much stock was actually found there. + +A option on the inventory specifies what to do with lines whose actual +quantity is left empty. + +When the *Inventory* is confirmed the stock in the location is updated by +creating a set of `Stock Moves <model-stock.move>`. +These moves correct the stock in the location. +They do this by transferring stock to and from the lost and found location +associated with location being checked. + +.. warning:: + + Do not use inventories when `Setting initial stock levels`. + +.. seealso:: + + The inventory checks can be found using the main menu item: + + |Inventory & Stock --> Inventories|__ + + .. |Inventory & Stock --> Inventories| replace:: :menuselection:`Inventory & Stock --> Inventories` + __ https://demo.tryton.org/model/stock.inventory + +Wizards +------- + +.. _wizard-stock.inventory.count: + +Inventory Count +^^^^^^^^^^^^^^^ + +The *Inventory Count* wizard helps users fill in inventories on a +`Product <concept-product>` by product basis. +It takes a product and a quantity and adds this to the appropriate inventory +line. diff -r 86bbfaea7a8c -r 0032a1985534 doc/design/location.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/design/location.rst Sat Feb 06 10:51:53 2021 +0000 @@ -0,0 +1,59 @@ +.. _model-stock.location: + +Location +======== + +A location represents the place where stock is stored. +This may be a physical location, such as a shelf, or a virtual location such +as the location used for products that have gone missing. + +Locations are organised in to a structure with each location having a parent +location and zero or more sub-locations. +It is possible to restrict a location to only one level of children. +This enables the use of an optimisation that improves the performance of the +the stock quantity calculation. + +A location also has a set of properties that allow the :ref:`current and +forecasted amounts of stock <concept-product.quantity>` in the location to be +obtained along with the stock's value. + +.. _concept-stock.location.warehouse: + +Warehouse +--------- + +Warehouses are special locations that represent a physical warehouse and as +such can have an `Address <party:model-party.address>`. +They are also normally split up into a set of locations each with a particular +purpose, such as for the input, output or storage of stock. + +.. seealso:: + + Stock locations can be added, removed and changed from the main menu item: + + |Inventory & Stock --> Configuration --> Locations|__ + + .. |Inventory & Stock --> Configuration --> Locations| replace:: :menuselection:`Inventory & Stock --> Configuration --> Locations` + __ https://demo.tryton.org/model/stock.location + + The stock locations structure, and access to the stock levels in + a location can be found from the main menu item: + + :menuselection:`Inventory & Stock --> Locations` + +.. _model-stock.location.lead_time: + +Location Lead Time +================== + +A *Location Lead Time* is the amount of time that it normally takes to +transfer stock between two `Warehouses <concept-stock.location.warehouse>`. + +.. seealso:: + + Location lead times can be updated from the main menu item: + + |Inventory & Stock --> Configuration --> Locations --> Location Lead Times|__ + + .. |Inventory & Stock --> Configuration --> Locations --> Location Lead Times| replace:: :menuselection:`Inventory & Stock --> Configuration --> Locations --> Location Lead Times` + __ https://demo.tryton.org/model/stock.location.lead_time diff -r 86bbfaea7a8c -r 0032a1985534 doc/design/move.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/design/move.rst Sat Feb 06 10:51:53 2021 +0000 @@ -0,0 +1,58 @@ +.. _model-stock.move: + +Move +==== + +In Tryton a stock *Move* represents the transfer of a given amount of a +`Product <concept-product>` between two different +`Stock Locations <model-stock.location>`. +Often stock moves will be grouped together into a +`Shipment <concept-stock.shipment>`. + +.. note:: + + Service products have no physical presence, so are not available for + use in stock moves. + +A stock move has some properties that record the planned date for the stock +move and also its effective date, which is when the move actually happened. + +Some stock moves are also associated with unit and cost prices. +These allow the value of stock to be calculated at any time, and for products' +cost prices to be updated based on the stock moves. + +Each `Company <company:model-company.company>` has its own stock moves which +are kept separate from other company's stock moves. + +.. seealso:: + + The stock moves can be listed by opening the main menu item: + + |Inventory & Stock --> Moves|__ + + .. |Inventory & Stock --> Moves| replace:: :menuselection:`Inventory & Stock --> Moves` + __ https://demo.tryton.org/model/stock.move + +.. _concept-stock.move.assign: + +Assign Concept +-------------- + +A stock move is assigned when the stock for the stock move has been found +and reserved and cannot be assigned by any other stock move. + +When attempting to assign a stock move Tryton looks at the stock move's source +locations and their sub-locations, and searches for the stock that is needed +to complete the stock moves. +If stock is found then the source location of the stock move is changed, +or the stock move is split up into several stock moves, each of which may +take stock from a different sub-location. + +If there is not enough stock available to fully assign the stock move then the +remainder is left in a stock move that is not assigned. + +.. note:: + + Consumable products always get assigned even when there is not enough + stock available for the stock move. + This is the key difference between goods and consumable products. diff -r 86bbfaea7a8c -r 0032a1985534 doc/design/period.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/design/period.rst Sat Feb 06 10:51:53 2021 +0000 @@ -0,0 +1,32 @@ +.. _model-stock.period: + +Period +====== + +In Tryton a stock *Period* is used to group together the all stock moves that +happened up to a specific date and that were also done after the date of any +previous stock *Period*. + +This allows the stock levels for the `Products <concept-product>` in all stock +`Locations <model-stock.location>` to be calculated for the date of the period, +and stored in the `Stock Period Cache <model-stock.period.cache>`. + +These cached values can then be used, where applicable, instead of having to +recalculate them each time they are needed. + +.. seealso:: + + The periods can be viewed and managed from the main menu item: + + |Inventory & Stock --> Configuration --> Periods|__ + + .. |Inventory & Stock --> Configuration --> Periods| replace:: :menuselection:`Inventory & Stock --> Configuration --> Periods` + __ https://demo.tryton.org/model/stock.period + +.. _model-stock.period.cache: + +Period Cache +============ + +The *Period Cache* is used to store the quantities of a product in a +particular location on the date defined by its `Period <model-stock.period>`. diff -r 86bbfaea7a8c -r 0032a1985534 doc/design/product.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/design/product.rst Sat Feb 06 10:51:53 2021 +0000 @@ -0,0 +1,97 @@ +.. _concept-product: + +Product +======= + +When the *Stock Module* is activated, products gain some extra properties. +These include a product's stock and forecast quantities, which show its +current and predicted future stock situation, and the cost value of its +stock. + +.. seealso:: + + The `Product <product:concept-product>` concept is introduced by the + :doc:`Product Module <product:index>`. + +.. _concept-product.quantity: + +Product Quantity +---------------- + +The amount, and the value, of a product in a +`Stock Location <model-stock.location>` is calculated by adding up all the +`Stock Moves <model-stock.move>` in to that location and subtracting those +out of the same location. + +Some values from the +:attr:`Transaction context <trytond:trytond.transaction.Transaction.context>` +are used to help determine which stock moves get included in this calculation +and which get left out. +These values include things like which locations to include in the +calculation, and what dates should be included. + +Normally, when calculating stock quantities for a date in the past, only moves +that are done are included in the calculation, and only if their effective +date is early enough. +This reflects the real situation based on completed stock moves. +For dates in the future, draft and `Assigned <concept-stock.move.assign>` +moves are also included, but only if their planned date is between today's +date and the future date, inclusive. + +.. note:: + + The stock quantity of consumable products is calculated in exactly + the same way as any other product, even though consumable products + can always be assigned regardless of how much stock there is. + +Wizards +------- + +.. _wizard-product.recompute_cost_price: + +Recompute Cost Price +^^^^^^^^^^^^^^^^^^^^ + +The *Recompute Cost Price* wizard updates products' cost prices using their +cost price method. + +.. _wizard-product.modify_cost_price: + +Modify Cost Price +^^^^^^^^^^^^^^^^^ + +The *Modify Cost Price* wizard is only way in which a product's cost price +can be changed once it has stock moves. +The wizard takes a date and a fixed price or formula for the new cost price. +These changes are stored in the +`Cost Price Revision <model-product.cost_price.revision>` concept and are +applied at the beginning of the date that was selected when the cost price +of the product gets re-calculated. + +.. _model-stock.product_quantities_warehouse: + +Product Quantities by Warehouse +=============================== + +The idea of the *Product Quantities by Warehouse* concept is to provide +information about how the stock levels of one or more products have varied +over time in a particular `Warehouse <concept-stock.location.warehouse>`. + +.. _model-stock.product_quantities_warehouse.move: + +Product Quantities by Warehouse Move +==================================== + +The *Product Quantities by Warehouse Move* concept provides information about +how `Stock Moves <model-stock.move>` have affected the stock levels in a +`Warehouse <concept-stock.location.warehouse>` over time. + +.. _model-product.cost_price.revision: + +Cost Price Revision +=================== + +The *Cost Price Revision* records changes to a product's cost price. +These revisions are automatically created when the product's cost price is +changed using the `Modify Cost Price <wizard-product.modify_cost_price>` +wizard. diff -r 86bbfaea7a8c -r 0032a1985534 doc/design/shipment.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/design/shipment.rst Sat Feb 06 10:51:53 2021 +0000 @@ -0,0 +1,231 @@ +.. _concept-stock.shipment: + +Shipment +======== + +In Tryton the concept of a *Shipment* is used to help organise and manage +groups of related `Stock Moves <model-stock.move>`. +There are different types of shipment which are used for different purposes. +Some of these types of shipment may also be split up into stages. +In each stage stock is moved to or from an intermediate +`Location <model-stock.location>`. +Each stage's moves form a subset of the shipment's total moves. + +.. _model-stock.shipment.in: + +Supplier Shipment +----------------- + +A *Supplier Shipment* has a set of properties that hold details about the +shipment such as who the supplier is, what +`Warehouse <concept-stock.location.warehouse>` it is going to and the date +when the shipment is expected to be delivered. + +It is made up from two sets of `Stock Moves <model-stock.move>`: + +* Incoming moves, these are used to move stock between a supplier + `Location <model-stock.location>` and the warehouse's input location, and +* Inventory moves, these then put the stock away in the warehouse's storage + location, or one of its child locations. + +.. note:: + + If the warehouse's input location and storage location are the same then + the inventory moves are not created. + +.. seealso:: + + The supplier shipments can be found by opening the main menu item: + + |Inventory & Stock --> Supplier Shipments|__ + + .. |Inventory & Stock --> Supplier Shipments| replace:: :menuselection:`Inventory & Stock --> Supplier Shipments` + __ https://demo.tryton.org/model/stock.shipment.in + +Reports +^^^^^^^ + +.. _report-stock.shipment.in.restocking_list: + +Restocking List +""""""""""""""" + +The *Restocking List* report lists the items on an incoming shipment and the +destination locations for the stock based on the inventory moves. + +.. _model-stock.shipment.in.return: + +Supplier Return Shipment +------------------------ + +A *Supplier Return Shipment* has a set of properties that contain information +about the shipment such as who the supplier was, what +`Address <party:model-party.address>` the shipment is going to, and the date +the shipment is sent. + +It is made up from a single set of `Stock Moves <model-stock.move>` that return +the stock directly back to a supplier `Location <model-stock.location>`. + +.. seealso:: + + The supplier shipments can be found by opening the main menu item: + + |Inventory & Stock --> Supplier Shipments --> Supplier Return Shipments|__ + + .. |Inventory & Stock --> Supplier Shipments --> Supplier Return Shipments| replace:: :menuselection:`Inventory & Stock --> Supplier Shipments --> Supplier Return Shipments` + __ https://demo.tryton.org/model/stock.shipment.in.return + +.. _model-stock.shipment.out: + +Customer Shipment +----------------- + +A *Customer Shipment* has a set of properties that contain information about +the shipment such as which `Warehouse <concept-stock.location.warehouse>` it +is being sent from, what `Address <party:model-party.address>` it is being +delivered to, and the date it is being sent. + +A customer shipment is made up from two sets of +`Stock Moves <model-stock.move>`: + +* Inventory moves, these moves are used to pick the stock from the warehouse's + storage `Location <model-stock.location>` and put it in the output location, + and +* Outgoing moves, these then take the picked stock and send it to a + customer location. + The outgoing moves are created first and define what stock needs to be sent + to the customer. + +.. note:: + + If the warehouse's picking location (or storage location if no picking + location is defined) is the same as its output location then only + outgoing moves are created and these moves do not get + `Assigned <concept-stock.move.assign>`. + +.. seealso:: + + The customer shipments can be found by opening the main menu item: + + |Inventory & Stock --> Customer Shipments|__ + + .. |Inventory & Stock --> Customer Shipments| replace:: :menuselection:`Inventory & Stock --> Customer Shipments` + __ https://demo.tryton.org/model/stock.shipment.out + +Reports +^^^^^^^ + +.. _report-stock.shipment.out.picking_list: + +Picking List +"""""""""""" + +The *Picking List* report lists the stock that is needed for a shipment. +For each item on the shipment it details the location the stock should be +taken from, and how much should be taken. + +.. _report-stock.shipment.out.delivery_note: + +Delivery Note +""""""""""""" + +The *Delivery Note* report contains information about where the shipment is +being sent, and when the delivery is happening. +It also lists all the items on the shipment. + +.. _model-stock.shipment.out.return: + +Customer Return Shipment +------------------------ + +A *Customer Return Shipment* has properties that contain information about +which customer the stock is being returned from, which +`Warehouse <concept-stock.location.warehouse>` it is sent to and the date the +return is happening. + +It is made up from two sets of `Stock Moves <model-stock.move>`: + +* Incoming moves, these are used to move stock between a customer + `Location <model-stock.location>` and the warehouse's input location, and +* Inventory moves, these then put the stock away in the warehouse's storage + location, or one of its child locations. + +.. note:: + + If the warehouse's input location and storage location are the same then + the inventory moves are not created. + +.. seealso:: + + The customer shipments can be found by opening the main menu item: + + |Inventory & Stock --> Customer Shipments --> Customer Return Shipments|__ + + .. |Inventory & Stock --> Customer Shipments --> Customer Return Shipments| replace:: :menuselection:`Inventory & Stock --> Customer Shipments --> Customer Return Shipments` + __ https://demo.tryton.org/model/stock.shipment.out.return + +Reports +^^^^^^^ + +.. _report-stock.shipment.out.return.restocking_list: + +Customer Return Restocking List +""""""""""""""""""""""""""""""" + +The *Customer Return Restocking List* report lists the items that were +returned by a customer. +For each item a destination location for the stock is also included based on +the inventory moves. + +.. _model-stock.shipment.internal: + +Internal Shipment +----------------- + +An internal shipment allows a group of `Stock Moves <model-stock.move>`, +between locations within the same `Company <company:model-company.company>`, +to be managed as a single entity. + +For internal shipments that are planned to start and end on different dates it +is made up from two sets of moves. +The first set are outgoing moves that put the stock in a transit +`Location <model-stock.location>` and the second set are incoming moves that +take the stock from the transit location and place it in the destination +location. + +.. seealso:: + + Internal shipments are available from the main menu item: + + |Inventory & Stock --> Internal Shipments|__ + + .. |Inventory & Stock --> Internal Shipments| replace:: :menuselection:`Inventory & Stock --> Internal Shipments` + __ https://demo.tryton.org/model/stock.shipment.internal + +Reports +^^^^^^^ + +.. _report-stock.shipment.internal.report: + +Internal Shipment Report +"""""""""""""""""""""""" + +The *Internal Shipment Report* provides a list of the items on the internal +shipment along with their quantities. +For shipments between `Warehouses <concept-stock.location.warehouse>` it also +contains the `Address <party:model-party.address>` of the warehouse the stock +is being sent to. + +Wizards +------- + +.. _wizard-stock.shipment.assign: + +Assign Shipment +^^^^^^^^^^^^^^^ + +The *Assign Shipment* wizard is used to assign a shipment. +Assigning a shipment tries to `Assign <concept-stock.move.assign>` the +`Stock Moves <model-stock.move>` that take the stock for the shipment. +If not all the stock moves can be assigned then it provides the user with a +set of options of what to do next. diff -r 86bbfaea7a8c -r 0032a1985534 doc/index.rst --- a/doc/index.rst Wed Feb 03 21:21:03 2021 +0100 +++ b/doc/index.rst Sat Feb 06 10:51:53 2021 +0000 @@ -1,311 +1,18 @@ +############ Stock Module ############ -The stock module defines fundamentals for all stock management -situations: Locations where products are stored, moves between these -locations, shipments for product arrivals and departures and inventory -to control and update stock levels. - -Location -******** - -Locations are generic places where products are physically or -virtually stored. The following location types are defined: - -* Storage - - Storage locations define real places where products are stored. - -* Warehouse - - Warehouses are meta-locations which define input, storage, picking, output - ,lost and found and waste locations. These locations are all of type - Storage. Input and Output are locations where incoming an outgoing product - are temporally stored awaiting transportation. The storage location is often - the biggest location where products are stored for middle or long periods of - time. The picking location is optionally where the products are picked by - the customer shipment otherwise the storage location is used. The lost and - found location is the location used by inventories when correcting stock - levels. Waste locations are used to throw away wrong products entering the - warehouse. - -* Customer - - Customer locations are virtual locations accumulating products that - have been sent to customers. - -* Supplier - - Supplier locations are virtual locations accumulating products that have - been received from suppliers. - -* Lost And Found - - Lost And Found locations collects inventory gaps. See - :ref:inventory for details. - -* Drop - - Drop locations are virtual locations used as intermediary locations in the - process of drop shipping. - -* Production - - Production locations are used during the production of products. - -* View - - View locations are virtual locations that can be used to logically group - other location types. - -Locations are organised in tree structures, allowing to define -fine grained structures. -It is possible to restrict a location to have only one level of children, this -allows to improve the performance of the stock quantity computation. - -Location Lead Time ------------------- - -It allows to define the time needed for an *Internal Shipment* between two -warehouses. - - -Move -**** - -A move is a movement of a product in a given quantity between two -locations. It may eventually defines a unit price and a currency for -the products that are moved from or to another company, allowing to -compute stock value at any time (and to update the cost prices if the -chosen cost price method is *Average*). A move also defines a planned -date (when one plan to do the move) and an effective date (when the -move is actually made). Products that are used in stock move must of -of type *Goods* or *Assets*. Stock levels are ignored for -consumable, this means that they can be always assigned. *Service* -products are ignored by the stock module. - -A move can be in one of this states: - -* Draft - - The initial state, used when the move is created and to define - future stock movement that are planned, but still subject to - modifications. - -* Assigned - - An assigned move allow to reserve some products. Thus preventing - other user to assign them. - -* Done - - The move is in state Done when the real movement is made. - -* Cancelled - - A cancelled move will be ignored by the system. Only Draft or - Assigned move can be cancelled. To revert a move in state Done, an - opposite move must be created. - -* Staging - - A phantom state used to create in advance move that should not be taken for - stock computation. - -A cron task runs every day and recomputes the cost price of moves if a past -unit price has changed. - -Product Quantities ------------------- - -Product quantities on each location are the sum of all moves coming -from or going to this location. For quantities that are computed for -a date in the past, only confirmed moves (i.e. in state Done) with an -effective date inferior to the considered date are taken into account, -reflecting the real situation. For future quantities, Draft and -Assigned move with a planned date greater than today and smaller than -the given date are also summed. - - -Shipment -******** - -A Shipment define a group of moves happening at the same date and -around the same location. - - -Supplier Shipment ------------------ - -A supplier shipment is used when products are received from a -supplier. It is mainly composed of a party (the supplier), a location -(the warehouse in which the products are coming) and two list of moves: - -* Incoming moves - - The moves between the supplier location and the input location - (as defined on the warehouse). - -* Inventory moves - - The inventory moves are between the input location and the storage - location (or one of his child locations). - -If the storage location is configured as the same as the input location only -incoming moves are created. - +The *Stock Module* provides the fundamental concepts required for managing +stock. +This includes keeping track of where the stock is, how much is available, +and checking and correcting stock levels. +It also allows stock to be moved from one place to another, and delivered to +and from customers and suppliers. -The supplier shipment can be in one of this states: - -* Draft - - Incoming moves and inventory moves (if they exist) are in draft. - -* Received - - Incoming move are set in state Done, inventory moves are created if - necessary. - -* Done - - Inventory and incoming moves are in state Done. - -* Cancelled - - All moves are cancelled. - - -Customer Shipment ------------------ - -A customer shipment is used for sending products to customer. It is -mainly composed of a party (the customer), a location (the warehouse -out of which the product are going) and two list of moves: - -* Inventory moves - - The moves between the picking or storage location and the output location of - the warehouse - -* Outgoing moves - - The moves between the output location of the warehouse and a - customer location. - -If the picking or storage location is configured as the same as the output -location, then only outgoing moves are created and no assignation is done. - - -The customer shipment can be in one of this states: - -* Draft - - Outgoing moves and inventory moves (if they exist) are in draft. - -* Waiting - - When a customer shipment is set to waiting, the inventory moves are - created (or completed) to balance the outgoing moves. The waiting - state also means that the shipment should be processed. - -* Assigned - - The assigned state is when products have been assigned (or reserved) - from the storage locations. - -* Packed - - The packed state is when the inventory moves have been made, i.e - when the products have been physically moved to the outgoing - locations. - -* Done - - The shipment is Done when the outgoing moves have been made, - e.g. when a truck left the warehouse. - -* Cancelled - - A shipment which is not yet completed (not in state Done) can be - cancelled at any time. This also cancels all the moves. - +.. toctree:: + :maxdepth: 2 -Rescheduling Customer Shipments -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -It is possible to setup a cron task to reschedule customer shipments that are -planned for the past. By default they are rescheduled to today. - - -Internal Shipment ------------------ - -An internal shipment is used for sending products across locations -inside the company. It is mainly composed of two locations and a list -of moves. It can be in one of these states: - - -* Draft - - The moves (if they exist) are in draft. - -* Waiting - - The waiting state means that the shipment should be processed. - -* Assigned - - The assigned state is when products have been assigned. - -* Done - - The shipment is Done when the moves have been made. - -* Cancelled - - A shipment which is not yet completed (not in state Done) can be - cancelled at any time. This also cancels all the moves. - - -Rescheduling Internal Shipments -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -It is possible to setup a cron task to reschedule internal shipments that are -planned for the past. By default they are rescheduled to today. - - -Inventory -********* - -Inventories allow to control and update stock levels. They are mainly composed -of the inventoried storage location and a list of inventory lines. -Inventory lines consist of a product and it's default unit of measure, an -expected quantity and the real quantity (the real products on the shelves). - -A button allows to auto-complete inventory lines with respect to the expected -quantities for each product in the location. -Another button allows to launch a wizard to count products by adding the -quantity to the existing matching line. - -When the inventory is confirmed, moves are created to balance expected -quantities and real ones. - -.. warning:: - Inventories must not be used to import initial stock levels. - Individual moves from supplier to each locations must be used with the cost - price as unit price. - -Product -******* - -The cost price of a product can only be modified using the "Modify Cost Price" -wizard once it is associated with stock moves. The wizard stores, for each -template or product the cost price revision. This revision contains a formula -that compute the new cost price based on the current one. E.g. `cost_price * -0.9` to reduce the cost price by 10%. -The cost price revisions are applied at the beginning of the stored date when -the cost price of a product is re-computed. - -.. warning:: - If the user modifies a revision manually, they must also run the "Recompute - Cost Price" wizard. + setup + usage/index + design/index + reference diff -r 86bbfaea7a8c -r 0032a1985534 doc/reference.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/reference.rst Sat Feb 06 10:51:53 2021 +0000 @@ -0,0 +1,13 @@ +************* +API Reference +************* + +Stock Quantities +================ + +.. class:: trytond.modules.stock.StockMixin + + This mixin_ provides some common methods that are useful when creating + classes that provide quantity fields. + + .. _mixin: http://en.wikipedia.org/wiki/Mixin diff -r 86bbfaea7a8c -r 0032a1985534 doc/setup.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/setup.rst Sat Feb 06 10:51:53 2021 +0000 @@ -0,0 +1,69 @@ +***** +Setup +***** + +.. _Setting up stock locations: + +Setting up stock locations +========================== + +The *Stock Module* provides a set of default +`Stock Locations <model-stock.location>`, however it is likely that you will +want to customise them to suit your company. + +.. tip:: + + If you only have a small `Warehouse <concept-stock.location.warehouse>` + you can use the same location for its storage, input and output locations. + This reduces the stock moves required to send and receive shipments. + +.. tip:: + + If you have a large number of locations in your warehouse you can + use the option to limit locations to only a single level of children. + This will improve the performance of Tryton when it is calculating + stock quantities. + +.. tip:: + + If you are altering your stock locations, and you have already used a + stock location then it cannot be deleted. + However, you can deactivate it which will hide it during normal use. + +.. _Setting initial stock levels: + +Setting initial stock levels +============================ + +When you start using Tryton you may already have some stock that you want to +bring into the system. + +In order to ensure the value of your stock is correctly calculated, and to +show that this stock has (at some point in the past) come from a supplier, +you must enter this initial stock in the correct way. + +The right way of doing this is to create a set of individual +`Stock Moves <model-stock.move>`. +These moves can be created in the view that is opened from the +|Inventory & Stock --> Moves|__ main menu item. +Each of the stock moves should move some stock of a `Product <concept-product>` +from a supplier `Location <model-stock.location>` to the appropriate storage +location. +These stock moves must have their unit prices set to their product's cost +price. + +.. |Inventory & Stock --> Moves| replace:: :menuselection:`Inventory & Stock --> Moves` +__ https://demo.tryton.org/model/stock.move + +.. note:: + + As these moves are for your initial stock they have no origin, and + when you try and do these moves Tryton will warn you about this. + Because this is for your initial stock this is not a problem, and you + can safely go ahead and finish doing the moves. + +.. tip:: + + If you create all the stock moves to start with, you can then select them + all in the list view, and use the :guilabel:`Do` item from the + :guilabel:`Launch Action` menu to do them all in one go. diff -r 86bbfaea7a8c -r 0032a1985534 doc/usage/index.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/usage/index.rst Sat Feb 06 10:51:53 2021 +0000 @@ -0,0 +1,14 @@ +***** +Usage +***** + +The [:menuselection:`Inventory & Stock`] main menu item allows access to the +items that allow you to view, manage and change things related to stock. + +.. toctree:: + :maxdepth: 1 + + shipment + quantity + value + period diff -r 86bbfaea7a8c -r 0032a1985534 doc/usage/period.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/usage/period.rst Sat Feb 06 10:51:53 2021 +0000 @@ -0,0 +1,16 @@ +.. _Using stock periods: + +Using stock periods +=================== + +You can use `Stock Periods <model-stock.period>` to stop +`Stock Moves <model-stock.move>` being created or updated before a specific +date, and to improve the performance of Tryton when looking at and using +`Product Quantities <concept-product.quantity>`. + +.. tip:: + + Depending on the number of stock moves that your + `Company <company:model-company.company>` generates you may find it useful + to create new stock periods as part of your accounting period end, or + fiscal year end, processes. diff -r 86bbfaea7a8c -r 0032a1985534 doc/usage/quantity.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/usage/quantity.rst Sat Feb 06 10:51:53 2021 +0000 @@ -0,0 +1,98 @@ +.. _Viewing stock levels: + +Viewing stock levels +==================== + +In Tryton there are a few different ways of seeing +`Product Stock Quantities <concept-product.quantity>`. +You can also easily see what the stock situation was at any time in the past, +and get an idea of what the stock situation will be after any +`Stock Moves <model-stock.move>` that are still being processed have been +completed. + +.. note:: + + Tryton is designed to allow you to create stock moves even if they + create negative stock. + For normal storage locations negative stock levels indicate that more + stock has been used than was available. + This suggests that there may be incoming moves to the location that + have not yet been done, or a mistake has been made that can be resolved + by `Checking and correcting stock levels`. + + However, although it is possible to create negative stock, you will + normally use `Shipments <concept-stock.shipment>` to help manage stock + moves, and a process to `assign them <Assigning shipments>`. + These respect stock availability and wont allow you to create negative + stock unless you force them to. + +Depending on what you are trying to find out you can get information about +stock levels for either `Products <concept-product>` or +`Locations <model-stock.location>`. + +If you are interested in finding out where some particular products are +stored, then once you have selected the products you are interested in, you +can use the menu items in the product's :guilabel:`Open related records` menu. + +To view how much stock is in one or more stock locations you first need to +select the locations you are interested in. +Once you have done this you can use the :guilabel:`Products` item from the +:guilabel:`Open related records` menu. +This then shows the total stock that is in all the selected locations. + +.. tip:: + + From the [:menuselection:`Inventory & Stock --> Locations`] main menu item + you can quickly get a list of stock in a single location by opening the + location you are interested in. + +.. tip:: + + If you have only selected a single location then the stock levels will + include all the stock in the location's children as well. + However, if you selected multiple locations then only the stock in the + selected locations is included, any stock in their child locations is + *not* included. + +.. _Checking and correcting stock levels: + +Checking and correcting stock levels +==================================== + +There are a range of things, such as mispicks, damages and theft, that can +cause the stock levels on Tryton to not match the actual amount of stock +available. + +Tryton allows you to check for and correct these discrepancies by performing +an `Inventory <model-stock.inventory>` of a +`Stock Location <model-stock.location>`. +This process is sometimes also called a stocktake, stock count or inventory +check. +How often you need to do this, and to what extent, is very dependent on your +business. +You may do this once a year at the end of your fiscal year, or continuously +by means of a `cycle count`_. + +When you create a new inventory you can use the :guilabel:`Complete` button to +complete the creation of the inventory. +This adds a line to the inventory for each product that is expected to be in +the location. + +How you go about actually counting the stock will depend on how your stock +location is organised. +If each `Product <concept-product>` is all together and is easy to count, +then you can enter the totals directly into the :guilabel:`Quantity` column. +If there are many different lines in the location, or not all of each product +is together, then you can start the `Count <wizard-stock.inventory.count>` +wizard using the :guilabel:`Count` button to enter the quantities as you go. +In this case, multiple quantities for the same product will be automatically +added together. + +For each inventory you can choose how to deal with any lines where the quantity +has been left empty. +You can either keep the stock in the location, or empty it out. + +Once the inventory has been finished you use the :guilabel:`Confirm` button +to correct the stock levels on Tryton. + +.. _`cycle count`: https://en.wikipedia.org/wiki/Cycle_count diff -r 86bbfaea7a8c -r 0032a1985534 doc/usage/shipment.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/usage/shipment.rst Sat Feb 06 10:51:53 2021 +0000 @@ -0,0 +1,125 @@ +.. _Sending and receiving deliveries: + +Sending and receiving deliveries +================================ + +In Tryton you use `Shipments <concept-stock.shipment>` to send stock to your +customers and receive stock from your suppliers. +There are different kinds of shipments available depending on whether you're +dealing with customers or suppliers and whether you are sending or receiving +stock. + +Although each type of shipment helps you manage the delivery of some stock, +and encompasses the same set of ideas, each is tailored for a particular +type of delivery. + +From Suppliers +-------------- + +You use a `Supplier Shipment <model-stock.shipment.in>` when receiving stock +from a supplier. + +* The supplier shipment is first received in to the + `Warehouse's <concept-stock.location.warehouse>` + input `Location <model-stock.location>`. +* You can then use the + `Restocking List <report-stock.shipment.in.restocking_list>` + to help you put the stock away in the right locations in the warehouse. + +To Suppliers +------------ + +If you need to send stock back to a supplier you use a +`Supplier Return Shipment <model-stock.shipment.in.return>`. + +To Customers +------------ + +You use a `Customer Shipment <model-stock.shipment.out>` when sending stock +out to a customer. + +* When the customer shipment is waiting to be worked on, normally the first + thing you need to do is `Assign it <Assigning shipments>`. +* You then pick the stock from the + `Warehouse <concept-stock.location.warehouse>`. + A `Picking List <report-stock.shipment.out.picking_list>` helps with this as + it details how much stock you need, and where it can be found. +* Once you've picked and packed the delivery you can dispatch it to the + customer from the warehouse's output `Location <model-stock.location>`. + It is common practice to send a + `Delivery Note <report-stock.shipment.out.delivery_note>` along with your + customer's shipment. + +From Customers +-------------- + +Stock that is returned by customers is handled by using a +`Customer Return Shipment <model-stock.shipment.out.return>`. +It works in a similar way to supplier shipments. + +* You receive the stock in the warehouse's input location. +* Then you use the `Customer Return Restocking List + <report-stock.shipment.out.return.restocking_list>` to help you put it away + in the warehouse. + +.. _Moving stock within your company: + +Moving stock within your company +================================ + +If you want to move stock between `Locations <model-stock.location>` within a +`Warehouse <concept-stock.location.warehouse>`, or between warehouses that +belong to the same `Company <company:model-company.company>` you use an +`Internal Shipment <model-stock.shipment.internal>`. + +The internal shipment helps you manage the processes of moving stock from one +place to another. + +* Once the internal shipment is waiting to be worked on, you need to go ahead + and `Assign it <Assigning shipments>`. +* You can use the + `Internal Shipment Report <report-stock.shipment.internal.report>` + to help you find and pick, or move, the stock. +* If the stock is intended for another warehouse you then send the shipment + to it. +* Finally once you've put the stock away in the correct locations the internal + shipment is done. + +.. tip:: + + You can use the `Stock Location Lead Time <model-stock.location.lead_time>` + to setup how long it normally takes for shipments between two warehouses. + +.. note:: + + If an internal shipment is expected to take more than one day to complete + then when the stock is sent it gets put in a transit location until the + shipment is done. + +.. _Assigning shipments: + +Assigning shipments +=================== + +Any `Shipments <concept-stock.shipment>` types that normally take stock from +either a storage or view `Location <model-stock.location>` must be assigned +before they can be done. +The aim of this process is to find and reserve the stock specifically for the +shipment. + +The `Assign Shipment <wizard-stock.shipment.assign>` wizard is used when +assigning shipments. +It tries to `Assign <concept-stock.move.assign>` each of the shipment's +incoming `Stock Moves <model-stock.move>`. +In doing so it updates the stock moves based on what stock it managed to find. + +If there is not enough stock available to fully assign the shipment you can +force the remainder to be assigned, although this will result in some stock +locations having negative stock. + +.. note:: + + When stock moves from a view location are assigned the stock must always be + taken from one of its sub-locations, as view locations cannot be the + source or destination of a done move. + This also means moves from a view location cannot be forced. diff -r 86bbfaea7a8c -r 0032a1985534 doc/usage/value.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/usage/value.rst Sat Feb 06 10:51:53 2021 +0000 @@ -0,0 +1,66 @@ +.. _Finding the value of your stock: + +Finding the value of your stock +=============================== + +In Tryton you can easily find the value of stock that's in one, or more, +`Locations <model-stock.location>` as the stock's cost value is included when +`Viewing stock levels` for the locations you are interested in. + +.. _Updating the value of your stock: + +Updating the value of your stock +================================ + +The value of the stock that your `Company <company:model-company.company>` +owns is based on the `Quantity <concept-product.quantity>` of stock and its +cost price. + +You can correct the quantity of stock by +`Checking and correcting stock levels`. + +You can also change how much the stock is worth by +`Updating a product's cost price`. + +.. _Updating a product's cost price: + +Updating a product's cost price +=============================== + +A `Product's <concept-product>` cost price is affected by various factors +including its cost price method and in some cases the value of stock received +or dispatched. + +The `Recompute Cost Price <wizard-product.recompute_cost_price>` wizard is +used to update a product's cost price using the product's cost price method. + +.. tip:: + + Most of the time you will not need to run the wizard that recalculates your + products' cost prices, because, by default, there is a scheduled task that + runs once a day and does this for you. + + You can, however, also run the wizard at any time to ensure you are seeing + the most up to date information. + +Once there are some `Stock Moves <model-stock.move>` for a +`Product <concept-product>` you can make a manual adjustment to a product's +cost price using the `Modify Cost Price <wizard-product.modify_cost_price>` +wizard. +This allows you to do things like reduce the cost price, and consequently +stock value, of a product by ``10%`` from a certain date by using +``cost_price * 0.9``. + +.. note:: + + If you modify a cost price you may also need to run the *Recompute Cost + Price* wizard to see the changes reflected in the product's cost price. + +.. _Viewing cost price changes: + +Viewing cost price changes +========================== + +You can get a list of any manual cost price changes that have been applied +to a product by using the :guilabel:`Cost Price Revision` relate action from +the product's :guilabel:`Open Related Records` menu. diff -r 86bbfaea7a8c -r 0032a1985534 setup.py --- a/setup.py Wed Feb 03 21:21:03 2021 +0100 +++ b/setup.py Sat Feb 06 10:51:53 2021 +0000 @@ -10,9 +10,12 @@ def read(fname): - return io.open( + content = io.open( os.path.join(os.path.dirname(__file__), fname), 'r', encoding='utf-8').read() + content = re.sub( + r'(?m)^\.\. toctree::\r?\n((^$|^\s.*$)\r?\n)*', '', content) + return content def get_require_version(name): @@ -80,7 +83,7 @@ download_url=download_url, project_urls={ "Bug Tracker": 'https://bugs.tryton.org/', - "Documentation": 'https://docs.tryton.org/', + "Documentation": 'https://docs.tryton.org/projects/modules-stock/', "Forum": 'https://www.tryton.org/forum', "Source Code": 'https://hg.tryton.org/modules/stock', },