Add processes and empty tests

docs/actions.rst

@@ -161,11 +161,17 @@ Add, Remove
 .. autoclass:: ereuse_devicehub.resources.event.models.Add
 .. autoclass:: ereuse_devicehub.resources.event.models.Remove
 
-EraseBasic, EraseSectors
+Erase
-========================
+=====
 .. autoclass:: ereuse_devicehub.resources.event.models.EraseBasic
 .. autoclass:: ereuse_devicehub.resources.event.models.EraseSectors
+.. autoclass:: ereuse_devicehub.resources.enums.ErasureStandards
+    :members:
 .. autoclass:: ereuse_devicehub.resources.event.models.ErasePhysical
+.. autoclass:: ereuse_devicehub.resources.enums.PhysicalErasureMethod
+    :members:
+    :undoc-members:
+
 
 Install
 =======
@@ -216,6 +222,17 @@ Rate
 ====
 .. autoclass:: ereuse_devicehub.resources.event.models.Rate
 
+The following are the values the appearance, performance, and
+functionality grade can have:
+
+.. autoclass:: ereuse_devicehub.resources.enums.AppearanceRange
+    :members:
+    :undoc-members:
+.. autoclass:: ereuse_devicehub.resources.enums.FunctionalityRange
+    :members:
+    :undoc-members:
+.. autoclass:: ereuse_devicehub.resources.enums.RatingRange
+
 Price
 =====
 .. autoclass:: ereuse_devicehub.resources.event.models.Price
@@ -226,6 +243,12 @@ Not done.
 
 .. autoclass:: ereuse_devicehub.resources.event.models.Migrate
 
+Locate
+======
+todo
+.. todo !!
+
+
 States
 ******
 .. autoclass:: ereuse_devicehub.resources.device.states.State

docs/index.rst

@@ -5,13 +5,33 @@
    :alt: DeviceHub logo
 
 
-This is the documentation and API of the `eReuse.org Devicehub
+This is the documentation of the `eReuse.org Devicehub
 <https://github.com/ereuse/devicehub-teal>`_.
 
+Devicehub is a distributed IT Asset Management System focused in
+reusing devices, created under the project
+`eReuse.org <https://www.ereuse.org>`_.
+
+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 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 <https://github.com/bustawin/teal>`_ and
+`Flask <http://flask.pocoo.org>`_.
+
 
 ..  toctree::
     :maxdepth: 2
 
+    processes
     actions
     agents
     devices

docs/processes.rst

@@ -0,0 +1,352 @@
+Processes
+#########
+
+This is a unclosed list of processes that you can do in Devicehub.
+Use them as a reference.
+
+..  toctree::
+    :maxdepth: 4
+
+    processes
+
+
+Registration and refurbish
+**************************
+
+Tag provisioning
+================
+Please refer to :ref:`tags:Use case`.
+
+Processing a device with Workbench
+==================================
+
+Track a device
+==============
+
+Recover a lost device
+=====================
+
+Rating a device
+===============
+Rating a device is the act of grading the appearance, performance,
+and functionality of a device. This results in a :ref:`actions:Rate`
+action, which includes a guessed **price** for the device.
+
+There are two ways of rating a device:
+
+1. When processing a computer with Workbench and the Android App.
+2. Anytime with the Android App or website.
+
+When processing a computer with the Workbench, once the user scans the
+tag, it is showed with a screen where it can rate the appearance and
+functionality. Once done, this data is added to the report of the
+Workbench, which includes the automatic performance grade, and it is
+uploaded to Devicehub, computing the :ref:`actions:Rate` with the
+final total rate and guessed price.
+
+.. todo this is not done yet
+
+The second way is opening the App, scan the tag of the device, and
+then select *rate* to write the appearance and functionality. The
+same process can be done through the website by searching the device.
+Note that with this process there is no way of introducing the
+performance, as it is computed by Workbench, meaning that Devicehub
+takes the last known performance value to compute a new Rate.
+
+Refer to :ref:`actions:Rate` for technical details.
+
+Storing devices
+===============
+Devices are stored in places like warehouses.
+
+:ref:`lots:`, :ref:`actions:Locate`, :ref:`actions:Receive`,
+and :ref:`actions:Live`, actions help locating devices,
+from a global scale to inside places.
+
+The :ref:`actions:Locate`, :ref:`actions:Receive`,
+and :ref:`actions:Live`; embed approximated city or province level
+information, and the user can write a location, name, or address
+in Locate and Receive. This location can be as detailed as required,
+like shelves in a building. Users can create actions by scanning
+a tag with the App or searching a device through the website,
+and then selecting *create an action*.
+
+Lots are more versatile than actions, and they do not pollute the
+traceability log, which is not needed when placing devices in temporal
+places like warehouses. Lots act like folders in an Operative System,
+so the user is free to choose what each lot represents, like representing
+physical locations. For example:
+
+- Lot company ACME
+
+  - Lot Warehouse 1 of ACME
+
+    - Lot Zone A
+
+      - Computer 1
+      - Monitor 2
+
+Users create lots through the website or App, selecting *create lot*,
+and then can place devices as they were files and folders. With the
+App users can select multiple devices and move all of them to a lot.
+
+To look for devices users reduce the area to look for them by
+checking to which lot the device is. And then, they visually check
+the identifier printed in the tags of devices in that place
+to find the ones they are looking for.
+
+Erasing data and obtaining a certificate
+========================================
+
+.. todo add a reference that explains how Workbench works in general
+
+Workbench erases data storage units, once the user configured Workbench
+to do so. In the configuration users parameterize the erasure to
+follow their desired erasure standard (which involves selecting
+erasure steps, data written or verification, for example).
+
+Once the Workbench uploads the report to a Devicehub, users can get
+the erasure certificate of the (data storage units of the) computer.
+
+An external user, like a client, if scans the tag with a smartphone,
+can see an on-line version of the certificate with its smartphone
+web browser.
+
+A logged-in user with access to the device, can scan the tag with
+the App or search the device through the web app and select
+*certificates*, then *erasure certificate*, to view an on-line
+version of the certificate and download a PDF.
+
+Please refer to :ref:`actions:Erase` for detailed information about
+how erasures work and which information they take.
+
+Delivery
+========
+:ref:`actions:Receive` is the act of physically taking delivery of a
+device. When an user performs a Receive, it means that another user took
+the device physically, confirming reception.
+
+To perform this action scan the tag of the devices with the App,
+or search it through the website, and select *actions* > *Receive*,
+filling information about the receiver and delivery.
+
+An exemplifying case is delivering a device from the warehouse to
+a customer through a transporter:
+
+1. Warehouse employees look in the website devices that are
+   :ref:`actions:Trade` (sold, donated, rented) that are still in
+   the warehouse and ready to be used.
+2. They look for them in the warehouse. Refer to :ref:`Storing devices`
+   for more details.
+3. Once the devices are located the employees give them to the
+   transporter. To acknowledge this to the system, they scan the
+   tags of those devices with the App and perform the action
+   :ref:`actions:Receive`, stating that the transporter received the
+   devices.
+4. The transporter takes the devices to the customer, performing the
+   same :ref:`actions:Receive` again, this time stating that the
+   customer received the devices.
+
+Value (price) devices
+=====================
+Devicehub guesses automatically a price after each new rate, explained
+in :ref:`Rating a device`, and manually by performing the action
+:ref:`actions:Price`. By doing manually it, the user can set any
+price.
+
+To perform a manual price the user scans the tags of the devices
+with the App, or searches them through the website, and selects
+*actions* > *price*.
+
+The user has still a chance to set the final trading price when
+performing :ref:`actions:Trade`. If the user does not set any price,
+and the trade is not a :ref:`actions:Donation` or similar, Devicehub
+assumes that the last known price is the one which the device is
+sold.
+
+Refer to :ref:`actions:Price` to know the technical details in how
+Devicehub guesses the price.
+
+Share device information
+========================
+
+.. todo explain too lot sharing to users?
+
+Users can generate public links to share with external users, like
+retailers or donors, so they can see a subset of the metadata. Thanks
+to this, external users can audit the devices (donors, consumers), take
+confident and faster decisions when requesting devices (retailers,
+consumers).
+
+This information includes hardware information, device rates,
+device price (both guessed and manually set), and a public part of
+the traceability log.
+
+To share devices:
+
+1. Users scan their tags with the Android App or searches them through
+   the website.
+2. They select *generate sharing links*, which gives them a list of
+   public links of the devices.
+3. Users send those links to their contacts using their preferred
+   method, like e-mail.
+4. External users visit those links in order to see a web page
+   containing the public information of the device.
+
+Public information of a device is always accessible when an user
+scans the QR of the tag through its smartphone, as the QR contains
+a public link of the device. This ways people in contact with the
+device, like consumers, can always check information about the device.
+
+Manage sale with buyer (reserve, outgoing lots, sell, receive)
+==============================================================
+We exemplify the use of lots and actions to manage sales with
+a buyer.
+
+
+1. The first step on sales is for a seller to showcase the devices
+   to potential customers by :ref:`sharing them <share device information>`.
+2. A customer inquires about the devices, for example through e-mail.
+3. This can imply a reservation process.
+   In such case, the seller can perform the action :ref:`actions:Reserve`,
+   which reserves the selected devices for the customer.
+   To perform that action, users scan the tags of the devices
+   with the App or search them through the website, select them,
+   and click *actions* > *Reserve*.
+2. Reservations can be cancelled but not modified, as they are saved
+   in the private traceability log of the devices. To cancel a
+   reservation users use the App or the web to select the devices,
+   and look for their reservation to cancel it. Note that reservations
+   are never deleted, but marked as cancelled.
+3. A reservation is fulfilled once the customer buys, gets through, or rents
+   a device; for example by an e-commerce or through a confirmation e-mail.
+   To perform any of those actions, sellers select the devices and click
+   *actions* > *Sell*, *Donate*, or *Rent*. They can perform those actions
+   over devices that are not reserved, or mix reserved devices with
+   non-reserved devices. Refer to :ref:`actions:Trade`
+   to know more about selling, donating, and renting.
+4. Lots help sellers in keeping an order in sales. A good ordering is
+   creating a lot called ``Sales``, and then, inside that lot,
+   a lot for each sales, or a lot for each customer.
+5. Devices have to be transported to the customer. Please refer to
+   the :ref:`delivery` process for more info.
+
+
+Verify refurbishment of a device through the tag
+================================================
+
+.. todo called Verify refurbishment of end-user's device
+
+Devicehub and eReuse.org allows usage of the :ref:`tags: Photochromic tags`
+to visually assist users, at-a-glance, in verifying correctly non-fraudulent
+refurbishing of a device.
+
+As the tags do not provide any technology that links them to a
+specific device, they are just stuck on devices.
+
+On the end-user side:
+
+1. End-users buy second-hand devices from retailers.
+2. End-users can apply a more throughout validation or learn about
+   the life-cycle of the device by scanning the ID tag, the tag
+   with a QR and/or an NFC, taking the user with the public information
+   of the device (see :ref:`Share device information`.
+3. The public web page contains, along information about the device,
+   instructions on how to check the validity of the Photochromic tag,
+   consisting on illuminating the tag with the smartphone's lantern
+   during a minimum of 6 seconds.
+
+Delivery or pickup from buyer after use
+=======================================
+After customer usage devices can be picked-up so they are prepared
+for re-use or recycle.
+
+.. todo what happens if the device is from another inventory?
+
+Once the customer agrees for the devices to be taken, a transporter
+or the same customer takes the device to the warehouse, and an
+employee performs a :ref:`Receive` to state that a device has been
+physically received, and a :ref:`Trade` to state the change of
+property. These actions can be performed by scanning the tag with
+the App or by manually searching the device through the website.
+
+Retail and distribution
+***********************
+
+Make devices available for sale to final users
+==============================================
+Once the devices are registered in the Devicehub, users can share
+the devices to potential customers. Please refer to
+:ref:`share devices information`.
+
+Manage purchase of devices with refurbisher / ITAD
+==================================================
+
+.. todo this is not available as for now
+
+Retailers and distributors can reserve devices that are shared to them
+by the refurbishers.
+
+Una entidad puede reservar dispositivos compartidos a través de la plataforma seguiendo los siguientes pasos:
+
+Para ello, navegue al lote eReuseCAT de la entidad que ha compartido los dispositivos.
+Dentro de este lote, navegue al lote de la donación
+Escoge los dispositivos que quiera reservar
+Haga el evento RESERVE para reservar los dispositivos
+La entidad que ha compartido los dispositivo recibirá un email. Para terminar la venta, ambos entidades gestionan la reserva.
+
+
+Distribution of devices
+=======================
+.. es exactamente lo que ya he explicado, las únicas diferencias son
+   ad-hoc de ereuse cat.
+
+
+Enviar un email con los dispositivos disponibles incluyendo los IDs y los precios a las posibles entidades receptoras (compradores) o bien subir los dispositivos a una tienda online (e-commerce)
+La entidad receptora escoge unos dispositivos y hace un pedido especificando los IDs de los dispositivos escogidos
+Finalizar facturas y convenios con la entidad receptora
+La receptora hace el pago de 100% de la factura
+Hacer el evento SELL sobre los dispositivos para formalizar la venta
+Preparar los dispositivos para entrega
+Confirmar fecha y lugar de la entrega
+Entregar dispositivos y hacer el evento RECEIVE para formalizar la entrega
+Venta en colaboración con entidades comercializadoras:
+
+​Compartir los dispositivos con las entidades especificas o con todo el circuito​
+Una entidad comercializadora reserva los dispositivos​
+La entidad comercializadora y receptora gestionan la reserva​
+
+https://reutilitza-cat.gitbook.io/preguntes-frequents/como-vender-un-dispositivo
+https://nextcloud.pangea.org/index.php/s/V04IMZMt4Jlxmiv/preview
+
+Transport between service providers and buyers
+==============================================
+??
+
+Estimate selling price
+======================
+??
+
+Manage donations and interactions with donors
+=============================================
+- Como solicitar una recogida a donante
+- Como hacer el convenio y reportes para el donante
+- Como transferir los dispositivos del donante a uno o varios restauradores
+- Como redactar la memoria
+
+Post-sale channel support
+*************************
+
+Customer service for hardware issues
+====================================
+Or better said: How to handle after sales issues
+
+Provide hardware warranty
+=========================
+
+
+Recyclers
+*********
+
+Get the certification for recycling
+===================================

docs/tags.rst

@@ -107,6 +107,14 @@ Tags and migrations
 Tags travel with the devices they are linked when migrating them. Future
 implementations can parameterize this.
 
+Photochromic tags
+*****************
+The photochromic Reversible Tag helps the end-user to identify a
+legitimate device that has correctly refurbished by an eReuse.org
+authorized refurbisher, without the hassle to read the QR code.
+
+Only eReuse.org authorized organizations can use the Photochromic tags.
+
 Use-case with eTags
 *******************
 We explain the use-case of tagging a device with an :ref:`tags:eTags`,

ereuse_devicehub/resources/enums.py

@@ -43,7 +43,13 @@ class RatingRange(IntEnum):
     """
     The human translation to score range.
 
-    You can compare them: ScoreRange.VERY_LOW < ScoreRange.LOW
+    You can compare them: ScoreRange.VERY_LOW < ScoreRange.LOW.
+    There are four levels:
+
+    1. Very low.
+    2. Low.
+    3. Medium.
+    4. High.
     """
     VERY_LOW = 2
     LOW = 3
@@ -324,6 +330,8 @@ class PhysicalErasureMethod(Enum):
 
 
 class ErasureStandards(Enum):
+    """Software erasure standards."""
+
     HMG_IS5 = 'British HMG Infosec Standard 5 (HMG IS5)'
     """`British HMG Infosec Standard 5 (HMG IS5) 
     <https://en.wikipedia.org/wiki/Infosec_Standard_5>`_.

ereuse_devicehub/resources/event/models.py

@@ -497,20 +497,8 @@ class SnapshotRequest(db.Model):
 
 
 class Rate(JoinedWithOneDeviceMixin, EventWithOneDevice):
-    """Devicehub generates an rating for a device taking into consideration the
+    """The act of grading the appearance, performance, and functionality
-    visual, functional, and performance.
+    of a device.
-
-    A Workflow is as follows:
-
-    1. An agent generates feedback from the device in the form of benchmark,
-       visual, and functional information; which is filled in a ``Rate``
-       event. This is done through a **software**, defining the type
-       of ``Rate`` event. At the moment we have ``WorkbenchRate``.
-    2. Devicehub gathers this information and computes a score, which
-       it is embedded into the Rate event.
-    3. Devicehub takes the rate from 2. and embeds it into an
-       `AggregateRate` which is like a total rate. This is the
-       official rate that agents can lookup.
 
     There are two base **types** of ``Rate``: ``WorkbenchRate``,
     ``ManualRate``. ``WorkbenchRate`` can have different
@@ -522,10 +510,18 @@ class Rate(JoinedWithOneDeviceMixin, EventWithOneDevice):
     if an agent fulfills a ``WorkbenchRate`` and there are 2 software
     algorithms and each has two versions, Devicehub will generate 4 rates.
     Devicehub understands that only one software and version are the
-    **oficial** (set in the settings of each inventory),
+    **official** (set in the settings of each inventory),
     and it will generate an ``AggregateRating`` for only the official
     versions. At the same time, ``Price`` only computes the price of
-    the **oficial** version.
+    the **official** version.
+
+    There are two ways of rating a device:
+
+    1. When processing the device with Workbench and the Android App.
+    2. Anytime after with the Android App or website.
+
+    Refer to *processes* in the documentation to get more info with
+    the process.
 
     The technical Workflow in Devicehub is as follows:
 
@@ -737,9 +733,10 @@ class AggregateRate(Rate):
 
 
 class Price(JoinedWithOneDeviceMixin, EventWithOneDevice):
-    """Price states a selling price for the device, but not
+    """The act of setting a trading price for the device.
-    necessarily the final price this is sold (which is set in the Sell
+
-    event).
+    This does not imply that the device is ultimately traded for that
+    price. Use the :class:`.Sell` for that.
 
     Devicehub automatically computes a price from ``AggregateRating``
     events. As in a **Rate**, price can have **software** and **version**,
@@ -803,7 +800,13 @@ class Price(JoinedWithOneDeviceMixin, EventWithOneDevice):
 
 
 class EreusePrice(Price):
-    """A Price class that auto-computes its amount by"""
+    """The act of setting a price by guessing it using the eReuse.org
+    algorithm.
+
+    This algorithm states that the price is the use value of the device
+    (represented by its last :class:`.Rate`) multiplied by a constants
+    value agreed by a circuit or platform.
+    """
     MULTIPLIER = {
         Desktop: 20,
         Laptop: 30
@@ -1110,7 +1113,7 @@ class Organize(JoinedTableMixin, EventWithMultipleDevices):
 
 
 class Reserve(Organize):
-    """The act of reserving devices and cancelling them.
+    """The act of reserving devices.
 
     After this event is performed, the user is the **reservee** of the
     devices. There can only be one non-cancelled reservation for
@@ -1223,6 +1226,11 @@ class Receive(JoinedTableMixin, EventWithMultipleDevices):
     they are the
     :attr:`ereuse_devicehub.resources.device.models.Device.physical_possessor`.
 
+    This differs from :class:`.Trade` in that trading changes the
+    political possession. As an example, a transporter can *receive*
+    a device but it is not it's owner. After the delivery, the
+    transporter performs another *receive* to the final owner.
+
     The receiver can optionally take a
     :class:`ereuse_devicehub.resources.enums.ReceiverRole`.
     """

tests/test_event.py

@@ -254,8 +254,10 @@ def test_live_geoip():
 
 
 @pytest.mark.xfail(reson='Develop reserve')
-def test_reserve(user: UserClient):
+def test_reserve_and_cancel(user: UserClient):
-    """Performs a reservation and then cancels it."""
+    """Performs a reservation and then cancels it,
+    checking the attribute `reservees`.
+    """
 
 
 @pytest.mark.parametrize('event_model_state', [
@@ -330,3 +332,24 @@ def test_erase_standards():
 @pytest.mark.xfail(reson='Develop test')
 def test_erase_physical():
     pass
+
+
+@pytest.mark.xfail(reson='validate use-case')
+def test_view_public_erasure_certificate():
+    """User can see html erasure certificate even if not logged-in,
+    from the public link.
+    """
+
+
+@pytest.mark.xfail(reson='Validate use-case')
+def test_not_download_erasure_certificate_if_public():
+    """User cannot download an erasure certificate as PDF if
+    not logged-in.
+    """
+
+
+@pytest.mark.xfail(reson='talk to Jordi about variables in certificate erasure.')
+def test_download_erasure_certificate():
+    """User can download erasure certificates. We test erasure
+    certificates with: ... todo
+    """