WIP

README.md

+# Introduction
+
+We all remember problems we had in school, stated likes:
+
+> Alice recieve 10 candies from her grandmother and later gives 2 candies to Bob.
+> How many candies has Alice left ?
+
+Using ERP5 Universal Business Model this simple problem will be modeled using:
+ - resource: The resource are candies
+ - node: Alice, Bob and the Grandmother are nodes
+ - movements: When Alice gives 2 candies to Bob, there is a movement where Alice is _source_ and Bob is _destination_. The resource of this movement is candy.
+
+![ERP5's 5 classes](https://www.erp5.com/developer-ERP5.UBM.Picture?quality=75.0&display=small&format=png "ERP5 5 classes")
+
+In this problem, there are two movements:
+
+| Movement | Source        | Destination   | Resource | Quantity  |
+|---------:| ------------- |------------- -| ---------| ---------:|
+|       M1 | Grandmother   | Alice         | Candy    |        10 |
+|       M2 | Alice         | Bob           | Candy    |         2 |
+
+
+A simple solution to "how many candies Alice has left" is achived by summing the quantities of incoming movements, ie. movements for which Alice is the destination, and then substracting the quantities of outgoing movements, ie. movements for which Alice is the source.
+
+Which in pseudo SQL format, means:
+
+```#SQL
+SELECT SUM(quantity) FROM movements WHERE Source = 'Alice'
+- SUM(quantity) FROM movements Where Destination = 'Alice'
+```
+
+Which leads to complex and unefficient queries.
+
+
+
+The underlying idea of Inventory is to see all movements from the source's point of view and from the destination's point of view. We can say that an incoming movement increase the inventory of the destination *node* while decreasing the inventory of the node at the other side of the movement, that we call *mirror node* in Inventory API terminology.
+
+We store the movements using the following data structure:
+
+| Movement | Node          | Mirror Node   | Resource | Quantity  |
+|---------:| ------------- |------------- -| ---------| ---------:|
+|       M1 | Grandmother   | Alice         | Candy    |       -10 |
+|       M1 | Alice         | Grandmother   | Candy    |        10 |
+|       M2 | Alice         | Bob           | Candy    |        -2 |
+|       M2 | Bob           | Alice         | Candy    |         2 |
+
+
+Using this data structure querying inventory of Alice is much efficient:
+
+```SQL
+SELECT SUM(quantity) FROM stock WHERE Node = 'Alice'
+```
+
+Using ERP5 API, this call would be :
+
+```#python
+return portal_simulation.getInventory(
+   node_uid=alice.getUid()
+)
+```
+
+
+---
+
+## Dates
+
+We are usually interested in knowing the stock level at a certain point of time. This is rather easy, because we usually record the point in time when the movement occured.
+
+It may happen that the movement itself takes some time and that there is a difference between the time when resource beeing leaves the source and the time when it arrives at destination. 
+
+To support this, movements have two properties:
+
+ - *Start Date*: When the movement begins and the quantity is removed from source
+ - *Stop Date*: When the movements finishes and the quantity is added at destination
+
+
+Let's imagine that on Wednesday Alice send 3 candies to her cousin Carol that lives far away. Carol will only recieve the candies after two days, because it is the time the post office will take to deliver. This movement is depicted as M3 in the table below:
+
+
+| Movement | Node          | Mirror Node   | Resource | Quantity  | Date      |
+|---------:| ------------- |------------- -| ---------| ---------:|-----------|
+|       M1 | Grandmother   | Alice         | Candy    |       -10 | Monday    |
+|       M1 | Alice         | Grandmother   | Candy    |        10 | Monday    |
+|       M2 | Alice         | Bob           | Candy    |        -2 | Tuesday   |
+|       M2 | Bob           | Alice         | Candy    |         2 | Tuesday   |
+|       M3 | Alice         | Carol         | Candy    |        -3 | Wednesday |
+|       M3 | Carol         | Alice         | Candy    |         3 | Thursday  |
+
+In this table it, as easy to see that before Tuesday evening, Alice had 8 candies:
+
+```#python
+>>> getInventory(node=Alice, at_date=Tuesday)
+8 # M1 & M2
+```
+
+Because under the hood, this will use a query like:
+```SQL
+SELECT SUM(quantity) from stock where Node='Alice' and Date <= Monday
+```
+
+On Wednesday evening, has only 5 Candies because the movement already decreased her stock
+
+```#python
+>>> getInventory(node=Alice, at_date=Tuesday)
+5 # M1 & M2 & M3
+```
+```#SQL
+SELECT SUM(quantity) from stock where Node='Alice' and Date <= Tuesday
+```
+
+But Carol's inventory of candies is still 0 on Wednesday:
+```#python
+>>> getInventory(node=Carol, at_date=Wednesday)
+0
+```
+```#SQL
+SELECT SUM(quantity) from stock where Node='Carol' and Date <= Tuesday
+```
+
+And this inventory is only increased on Thursday:
+```#python
+>>> getInventory(node=Carol, at_date=Thursday)
+3
+```
+```#SQL
+SELECT SUM(quantity) from stock where Node='Carol' and Date <= Thursday
+```
+
+---
+
+# Complete structure of a movement
+
+quantity 
+quantity unit
+resource
+price
+price currency
+use
+start_date
+stop_date
+simulation_state
+
+# Different kind of inventories
+## Current Inventory
+## Future Inventory
+## Available Inventory
+
+
+# More axis
+ ( section, project, payment, funding )
+
+
+# Category 
+Explain node_category instead of node_uid
+
+
+# Complete API
+## getInventory
+## getInventoryAssetPrice
+## getInventoryList
+## getMovementHistoryList
+## Complete List of supported parameters
+
+at_date
+from_date
+to_date
+
+omit_input, omit_output
+omit_asset_increase, omit_asset_decrease
+
+
+# Flow API
+linear movements
+
+
+
+# Tracking API
+
+
+