summaryrefslogtreecommitdiff
path: root/design-documents/016-backoffice-order-management.rst
blob: b6564485f049937bc8a66c9b443237c9ebf1d653 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
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
-------------

this form is divided into 4 sections

* ``product``: where the merchant can add inventory product and non-inventory
  product.

* ``price``: where the merchant can override the total price (if product was
  added) or set the order price and summary.

* ``payment``: where some default of the payment processing can be changed

* ``extra``: where the merchant can add extra information in JSON format
  

Create order: Product section
.............................

This section has two parts:

The first part will add/remove product from the current stock.

* ``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

The second part will add non inventory product. To add a product a :ref:`create
product <backoffice-create-product>` form will be shown. The product in the list
can be edited or deleted from the list. 

In both cases, the total unit and price of the products will be calculated and
shown in the bottom of the section. If the merchant collapse one of the product
list a line with a resume of the total price and units will be shown.

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

Create order: Price section
...........................

This section has 2 scenarios. 

The fist one is without products being added: the ``order price`` and
``summary`` inputs will be shown.

If there is at least one product added, the ``total products price`` as the sum
of all products prices will be shown. The ``order price`` will default to
``total products price``. The ``products taxes`` and ``profit`` will be shown
since ``order price`` cannot be less that ``product taxes``. 

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

Create order: Payment section
.............................

This section show optional values that can be overwritten by the merchant

* ``refund deadline``: calendar type of input. default from instance
  
* ``pay deadline``: calendar type of input. default from instance

* ``auto refund deadline``: calendar type of input. default empty, optional.

* ``delivery date``: calendar type of input. default empty, optional.

* ``delivery location``: location section similar to instance jurisdiction or
  instance address. optional

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

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

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

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

Create order: all section expanded
..................................

An example of how all section in a page will be shown.

.. image:: ../backoffice-order-create.all-expanded.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 (down arrow) to show more information
* if expanded show table with date, amount and reason

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

Ask for:

* amount: default 0, show max amount refundable (order amount - already
  refunded) 

* 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?

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

  * null => unpaid (using contractTerm.timestamp from now but may not be correct)

  * unpaid => claimed (maybe contractTerm.timestamp)

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

* Refund button is being show if "refund_amount < contract_terms.amount" and "time < refund deadline".
  Is there any other case? Is this taking into account auto_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.nonce: not used