diff --git a/docs/actions.rst b/docs/actions.rst index 59fa7b33..45b19b7e 100644 --- a/docs/actions.rst +++ b/docs/actions.rst @@ -1,15 +1,14 @@ -Actions and states -################## - Actions -******* - +####### Actions are events performed to devices, changing their **state**. Actions can have attributes defining **where** it happened, **who** performed them, **when**, etc. Actions are stored in a log for each device. An exemplifying action can be ``Repair``, which dictates that a device has been repaired, -after this action, the device is in the ``repaired`` state. +after this action, the device is in the ``repaired`` state. Another +example is performing a ``Sell`` to agent 1 (now this agent *owns* +the device), and then performing another ``Sell`` to agent 2 (now +agent 2 is the owner). Devicehub actions inherit from `schema actions `_, are written in Pascal case and using @@ -19,14 +18,14 @@ is going to be / must be repaired, whereas ``Repair`` states that the reparation happened. The former actions have the preposition *To* prefixing the verb. -Actions and states affect devices in different ways or **dimensions**. +:ref:`actions:Actions` and :ref:`states:States` affect devices in +different ways or **dimensions**. For example, ``Repair`` affects the **physical** dimension of a device, and ``Sell`` the **political** dimension of a device. A device can be in several states at the same time, one per dimension; ie. a device can be ``repaired`` (physical) and ``reserved`` (political), but not ``repaired`` and ``disposed`` at the same time: - - Physical actions: The following actions describe and react on the Physical condition of the devices. @@ -37,7 +36,7 @@ but not ``repaired`` and ``disposed`` at the same time: - DisposeWaste, Recover - Association actions: Actions that change the associations users have with devices; - ie. the **owners**, **usufructuarees**, **reservees**, + ie. the **owners**, **usufructuarees** (*from usufruct*), **reservees** (*from reserve*), and **physical possessors**. - Trade @@ -60,15 +59,8 @@ but not ``repaired`` and ``disposed`` at the same time: The following index has all the actions (please note we are moving from calling them ``Event`` to call them ``Action``): +Schema +****** + .. dhlist:: :module: ereuse_devicehub.resources.event.schemas - - -States -****** -.. autoclass:: ereuse_devicehub.resources.device.states.State - -.. uml:: states.puml - -.. autoclass:: ereuse_devicehub.resources.device.states.Trading -.. autoclass:: ereuse_devicehub.resources.device.states.Physical diff --git a/docs/devices.rst b/docs/devices.rst index 697802a7..1974eebd 100644 --- a/docs/devices.rst +++ b/docs/devices.rst @@ -1,6 +1,19 @@ Devices -######### +####### +Devices are objects that can be identified, and they are the +main entity in a Devicehub. Refer to :ref:`devices:Device` for more +info. +Schema +****** +The following schema represents all the device types and their +properties. + +.. dhlist:: + :module: ereuse_devicehub.resources.device.schemas + +API +*** You can retrieve devices using ``GET /devices/``, or a specific device by ``GET /devices/24``. @@ -46,5 +59,4 @@ The result is a JSON object with the following fields: - **next**: The number of the next page, if any. - **last**: The number of the last page, if any. -.. dhlist:: - :module: ereuse_devicehub.resources.device.schemas + diff --git a/docs/index.rst b/docs/index.rst index 0269992a..a8547ff9 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -14,19 +14,36 @@ reusing devices, created under the project Our main objectives are: -- To offer a common IT Asset Management for donors, receivers and IT - professionals so they can manage devices and exchange them. - This is, reusing –and ultimately recycling. +- To offer a common IT Asset Management for distributors, refurbishers, + receivers and other IT professionals so they can manage devices and exchange them. + This is, reusing —and ultimately recycling. - To automatically recollect, analyse, process and share (controlling privacy) metadata about devices with other tools of the eReuse ecosystem to guarantee traceability, and to provide inputs for the indicators which measure circularity. -- To highly integrate with existing IT Asset Management Systems. -- To be decentralized. -Devicehub is built with `Teal `_ and -`Flask `_. +The main entity of a Devicehub are :ref:`devices:Devices`, which is any object that +can be identified. Devices are divided in *types* (like ``Computer``), +and each one defines *properties*, like serial number, weight, +quality rating, pricing, or a list of owners. +We perform :ref:`actions:Actions` on devices, which are events that +change their *state* and *properties*. Examples are sales, reparations, +quality diagnostics, data wiping, and location. +Actions are stored in the traceability log of the device. + +Devicehub is decentralized, and each instance is an inventory. We can +share and exchange devices between inventories —like in real live between +organizations. + +:ref:`tags:Tags` identify devices through those organizations and their +internal systems. With Devicehub we can manage and print smart tags with +QR and NFC capabilities, operating devices by literally scanning them. + +Devicehub is a REST API built with `Teal `_ and +`Flask `_ using `PostgreSQL `_. +`DevicehubClient `_ is the +front–end that consumes this API. .. toctree:: :maxdepth: 2 @@ -34,6 +51,7 @@ Devicehub is built with `Teal `_ and api devices actions + states tags lots diff --git a/docs/states.rst b/docs/states.rst new file mode 100644 index 00000000..7c253e9a --- /dev/null +++ b/docs/states.rst @@ -0,0 +1,48 @@ +States +###### +.. note:: In construction. + +A mutable property of a device result of applying an +:ref:`actions:Action` to it. + +States are represented as properties in :ref:`devices:Device` and +sub–types. They can be steps in a workflow +(like ``sold`` and ``payed``, part of a trading), or properties +describing computed values from applying events (like a list of owners, +or a quality rating). + +There are three types of states: + +* **Trading**: a workflow of states resulting from applying the action + :ref:`actions:Trade`. +* **Physical**: a workflow of states resulting from applying + physical actions (ref. :ref:`actions:Actions`). +* **Attributes**: miscellaneous device properties that are not part of + a workflow. + +.. uml:: states.puml + +Trading +******* + Trading states. + +:cvar Reserved: The device has been reserved. +:cvar Cancelled: The device has been cancelled. +:cvar Sold: The device has been sold. +:cvar Donated: The device is donated. +:cvar Renting: The device is in renting +:cvar ToBeDisposed: The device is disposed. + This is the end of life of a device. +:cvar ProductDisposed: The device has been removed + from the facility. It does not mean end-of-life. + +Physical +******** + Physical states. + +:cvar ToBeRepaired: The device has been selected for reparation. +:cvar Repaired: The device has been repaired. +:cvar Preparing: The device is going to be or being prepared. +:cvar Prepared: The device has been prepared. +:cvar ReadyToBeUsed: The device is in working conditions. +:cvar InUse: The device is being reported to be in active use. diff --git a/ereuse_devicehub/resources/device/states.py b/ereuse_devicehub/resources/device/states.py index 1cadfb39..93c5a2af 100644 --- a/ereuse_devicehub/resources/device/states.py +++ b/ereuse_devicehub/resources/device/states.py @@ -6,6 +6,10 @@ from ereuse_devicehub.resources.event import models as e class State(Enum): + """A mutable property of a device result of applying an + :ref:`actions:Action` to it. + """ + @classmethod def events(cls): """Events participating in this state."""