path: root/design-documents/016-backoffice-order-management.rst

Design Doc 016: Backoffice Order Management
###########################################

Summary
=======

This document describe the complete list features for orders management and how
will be shown.

Motivation
==========

User will use the backoffice to manage their orders and verify the status of the
current and past orders.

Requirements
============

Access all information provided from the Merchant Backend API in a
understandable and accessible way

User should use the backoffice to manage orders by:

* searching for orders
* showing details about the order and the activity history
* refund order that are refundable
* create orders ( if admin )

Proposed Solution
=================

Listing orders
--------------

.. image:: ../backoffice-order-list.svg
  :width: 800

4 tabs will be show for a easy access to common filter, click on any of this and
search will reset all filter except date

* paid (default) 
* refunded
* not wired
* all (empty filter box)

Columns for the order listings will be:

* date in 'dd/MM/yyyy HH:mm:ss' format
* amount: value and currency
* summary

Actions per row:

* refund: pop up with amount and reason (select box and text)
* copy payment url (if not status==unpaid)
* view details

An export button will allow the user to download the result page in CSV format.

An infinity scroll is propose instead of a pagination, reasons:

* users usually does not jump from one page to another using random access
* if the user want to search, is going to limit the result using filters
* no need to go back after loading more result
* it could be triggered by scrolling, with buttons (or both)

Create orders
-------------



* ``product``: optional, collapsed by default

  * ``name``: search box to select product by description field. if not found it
    will be a 'create new' option leading to the create product without loosing
    context
  * ``quantity``: mandatory
  * ``price``: taken from the product, but it can be overridden.
  * ``add button``: will add the product to the list and calculate the total price


* ``amount``: default to the total price of product, but can be overridden. If
  overridden, show a message with the discount in %

* ``summary``: order description

* ``fulfillment url``: url where the user will land after buying the product

* ``payment``: all values should have default from instance configuration

  * ``exchanges``: default value from the instance, new exchanges will be added
    using the url and public key will be taken from querying the url

  * ``auditors``: default value from the instance, new auditors will be added using
    the url and name/pub_key will be taken from querying the url

  * ``wire method``: it should select one of supported from exchanges
  * ``refund deadline``: calendar type of input
  * ``pay deadline``: calendar type of input
  * ``auto refund deadline``: calendar type of input
  * ``max fee``: default value from the instance

  * ``max wire fee``: default value from the instance

  * ``wire_fee_amortization``: default value from the instance

There were field not considered for this form, check Alternatives for more
information.

.. image:: ../backoffice-order-create.svg
  :width: 800


Creation order success
**********************

A success message showing the amount, summary and the order id. Additionally the
taler_pay_uri can be shown to be copied to send to the customer. 

action buttons that allow the following: 

* create another payment: go to the create payment page again
* view details: show details of the payment (see page)

Order details
-------------

Status text should be set with a background color for easier recognition when
indicated:

* paid: green
* claimed: light-green
* unpaid: grey
* refunded: red

Header
******

This is a resume of most important information

* big status with color 
* date
* total

  - deposit_total (if not refunded)
  - refund_amount (if status is refunded)
  - deposit_total - refund amount (if refunded partially)

* order_status_url
* taler_pay_uri (if unpaid)
* actions: refund (if not refunded), add note, copy order_status_url

Timeline of events
******************

Event of status changed over time describe vertically. 
Sorted from newest to oldest.
On line per status updated, with datetime and a short description.

Info taken from:

* refund_details: a row showing date an amount

* wire_details: a row date and id


    About wire details

    Normally one wire transfer will involve more than one payment from the same
    exchange. And an order can have multiple wire transfers if the payment
    involved more than one exchange.



Error status
************

This section is not going to be shown if there is no error

* Wire Error: info taking from wire_reports in contractTerm. for every element
  in the list show hint and error code

* Exchange Error: connection with exchange failed, info taking from exchange_ec
  and exchange_hc

Payment details
***************

If the order was claimed

* summary
* amount (contract.amount)
* fee (contract.amount - deposit_total)
* refund_amount (if status is refunded)
* net (deposit_total - refund_amount)
* current status

  
Contract Terms
**************

collapsed as default. show disabled if unpaid

* summary
* amount
* fulfillment_url, if present
* max fee
* max fire fee
* wire_fee_amortization
* list of (exchange | auditor) name and url
* products table: list of products, one row per product

  * description
  * quantity
  * total price
  * total tax
  * sum at the bottom

* horizontal timeline of important dates in the contract

  * start at contract creation time
  * show current date
  * pay_deadline
  * wire_transfer_deadline
  * refund_deadline
  * delivery_date (immediately if null)
  * auto_refund


refund popup
--------------

If there is any refund:

* show total refund from ``refund_amount``
* a + sign to show more information
* if expanded show a timeline vertically showing amount a reason 
  ``refund_details``

Warn if there is a pending refund when ``refund_pending`` is true

Ask for:

* amount
* reason: concatenation of the next values

  * drop down options: duplicated, requested by customer, other
  * after selecting, free text for additional information

.. image:: ../backoffice-order-refund.svg
  :width: 800

.. image:: ../backoffice-order-refund.already.svg
  :width: 800

Example of details by status
----------------------------


.. image:: ../backoffice-order-details.paid.svg
  :width: 800

.. image:: ../backoffice-order-details.unpaid.svg
  :width: 800

.. image:: ../backoffice-order-details.claimed.svg
  :width: 800

.. image:: ../backoffice-order-details.refunded.svg
  :width: 800


Alternatives
============


pagination
-----------
order list was originally thought with pagination footer

.. image:: ../backoffice-order-list.pagination.svg
  :width: 800

ascending boolean flag cloud be eliminated using the load before and load after
and a design without random access to pages was proposed

search box
----------

A SearchBox was considered for managing filter.
Filter will allow paid, refunded, wired status and date.

* paid: yes/no
* refunded: yes/no
* wired: yes/no
* date: 'dd/MM/yyyy'

The UI of the search box is an input field with tags showing ``field=value`` for
any filter set. Additionally a custom criteria can be supported like
``date>last_week`` or ``amount>USD:10``



Discussion / Q&A
================

* Shall we show merchant information from the ContractTerm in the order detail?

* Order creation was first thought as out of scope but should be useful for
  testing purpose or when frontend is not yet integrated with taler merchant
  backend. Shall we skip it?

* Do we have the date and time of when the order goes from these states?

  * claimed => paid (maybe last wire_details.execution_time with confirmed = true )
  * unpaid => claimed (maybe contractTerm.timestamp)

* Refund button is being show if "not refunded" and "time < refund deadline".
  should we consider partial refund?

* Field left out in the order creation:
 
  * contractTerm.summary_i18n: it makes the UI complex
  * contractTerm.order_id: should be created by the backend
  * contractTerm.timestamp: defined by backend
  * contractTerm.merchant_pub: filled by the backend
  * contractTerm.merchant_base_url: filled by the backend
  * contractTerm.h_wire: defined by the backend
  * contractTerm.delivery_location: not used
  * contractTerm.delivery_date: not used
  * contractTerm.nonce: not used
  * contractTerm.products[].description: defined by product_id
  * contractTerm.products[].description_i18n: defined by product_id
  * contractTerm.products[].unit: defined by product_id
  * contractTerm.products[].image: defined by product_id
  * contractTerm.products[].delivery_date: not used
  * contractTerm.products[].taxes: defined by product_id