016-backoffice-order-management.rst (9999B)
1 DD 16: Backoffice Order Management 2 ################################## 3 4 :Design status: Accepted 5 :Implementation status: Implemented 6 :DD shepherd: TBD 7 :Historical contributors: Sebastian 8 :First published: 2021-03-19 9 :Last substantive change: 2021-04-15 10 :Implementation evidence: merchant (2021-08-05) 11 :Normative references: :doc:`../taler-merchant-manual`, :doc:`../core/api-merchant` 12 13 .. note:: 14 15 The screens below record the original UI design. The current merchant API 16 is authoritative for order fields and operations. 17 18 Summary 19 ======= 20 21 This document describe the complete list features for orders management and how 22 will be shown. 23 24 Motivation 25 ========== 26 27 User will use the backoffice to manage their orders and verify the status of the 28 current and past orders. 29 30 Requirements 31 ============ 32 33 Access all information provided from the Merchant Backend API in a 34 understandable and accessible way 35 36 User should use the backoffice to manage orders by: 37 38 * searching for orders 39 * showing details about the order and the activity history 40 * refund order that are refundable 41 * create orders ( if admin ) 42 43 Proposed Solution 44 ================= 45 46 Listing orders 47 -------------- 48 49 .. image:: ../images/backoffice-order-list.svg 50 :width: 800 51 52 4 tabs will be show for an easy access to common filter, click on any of this and 53 search will reset all filter except date 54 55 * paid (default) 56 * refunded 57 * not wired 58 * all (empty filter box) 59 60 Columns for the order listings will be: 61 62 * date in 'dd/MM/yyyy HH:mm:ss' format 63 * amount: value and currency 64 * summary 65 66 Actions per row: 67 68 * refund: pop up with amount and reason (select box and text) 69 * copy payment url (if not status==unpaid) 70 * view details 71 72 An export button will allow the user to download the result page in CSV format. 73 74 An infinity scroll is propose instead of a pagination, reasons: 75 76 * users usually does not jump from one page to another using random access 77 * if the user want to search, is going to limit the result using filters 78 * no need to go back after loading more result 79 * it could be triggered by scrolling, with buttons (or both) 80 81 Create orders 82 ------------- 83 84 this form is divided into 4 sections 85 86 * ``product``: where the merchant can add inventory product and non-inventory 87 product. 88 89 * ``price``: where the merchant can override the total price (if product was 90 added) or set the order price and summary. 91 92 * ``payment``: where some default of the payment processing can be changed 93 94 * ``extra``: where the merchant can add extra information in JSON format 95 96 97 Create order: Product section 98 ............................. 99 100 This section has two parts: 101 102 The first part will add/remove product from the current stock. 103 104 * ``name``: search box to select product by description field. if not found it 105 will be a 'create new' option leading to the create product without losing 106 context 107 108 * ``quantity``: mandatory 109 110 The second part will add non inventory product. To add a product a :ref:`create 111 product <backoffice-create-product>` form will be shown. The product in the list 112 can be edited or deleted from the list. 113 114 In both cases, the total unit and price of the products will be calculated and 115 shown in the bottom of the section. If the merchant collapse one of the product 116 list a line with a resume of the total price and units will be shown. 117 118 .. image:: ../images/backoffice-order-create.product-section.svg 119 :width: 800 120 121 Create order: Price section 122 ........................... 123 124 This section has 2 scenarios. 125 126 The fist one is without products being added: the ``order price`` and 127 ``summary`` inputs will be shown. 128 129 If there is at least one product added, the ``total products price`` as the sum 130 of all products prices will be shown. The ``order price`` will default to 131 ``total products price``. The ``products taxes`` and ``profit`` will be shown 132 since ``order price`` cannot be less that ``product taxes``. 133 134 .. image:: ../images/backoffice-order-create.price-section.svg 135 :width: 800 136 137 Create order: Payment section 138 ............................. 139 140 This section show optional values that can be overwritten by the merchant 141 142 * ``refund deadline``: calendar type of input. default from instance 143 144 * ``pay deadline``: calendar type of input. default from instance 145 146 * ``auto refund deadline``: calendar type of input. default empty, optional. 147 148 * ``delivery date``: calendar type of input. default empty, optional. 149 150 * ``delivery location``: location section similar to instance jurisdiction or 151 instance address. optional 152 153 * ``max fee``: default value from the instance 154 155 .. image:: ../images/backoffice-order-create.payment-section.svg 156 :width: 800 157 158 Create order: all section expanded 159 .................................. 160 161 An example of how all section in a page will be shown. 162 163 .. image:: ../images/backoffice-order-create.all-expanded.svg 164 :width: 800 165 166 167 Creation order success 168 ...................... 169 170 A success message showing the amount, summary and the order id. Additionally the 171 taler_pay_uri can be shown to be copied to send to the customer. 172 173 action buttons that allow the following: 174 175 * create another payment: go to the create payment page again 176 * view details: show details of the payment (see page) 177 178 Order details 179 ------------- 180 181 Status text should be set with a background color for easier recognition when 182 indicated: 183 184 * paid: green 185 * claimed: light-green 186 * unpaid: grey 187 * refunded: red 188 189 Header 190 ...... 191 192 This is a resume of most important information 193 194 * big status with color 195 * date 196 * total 197 198 - deposit_total (if not refunded) 199 - refund_amount (if status is refunded) 200 - deposit_total - refund amount (if refunded partially) 201 202 * order_status_url 203 * taler_pay_uri (if unpaid) 204 * actions: refund (if not refunded), add note, copy order_status_url 205 206 Timeline of events 207 .................. 208 209 Event of status changed over time describe vertically. 210 Sorted from newest to oldest. 211 On line per status updated, with datetime and a short description. 212 213 Info taken from: 214 215 * refund_details: a row showing date an amount 216 217 * wire_details: a row date and id 218 219 220 About wire details 221 222 Normally one wire transfer will involve more than one payment from the same 223 exchange. And an order can have multiple wire transfers if the payment 224 involved more than one exchange. 225 226 227 228 Error status 229 ............ 230 231 This section is not going to be shown if there is no error 232 233 * Wire Error: info taking from wire_reports in contractTerm. for every element 234 in the list show hint and error code 235 236 * Exchange Error: connection with exchange failed, info taking from exchange_ec 237 and exchange_hc 238 239 Payment details 240 ............... 241 242 If the order was claimed 243 244 * summary 245 * amount (contract.amount) 246 * fee (contract.amount - deposit_total) 247 * refund_amount (if status is refunded) 248 * net (deposit_total - refund_amount) 249 * current status 250 251 252 Contract Terms 253 .............. 254 255 collapsed as default. show disabled if unpaid 256 257 * summary 258 * amount 259 * fulfillment_url, if present 260 * max fee 261 * list of exchange names and URLs 262 * products table: list of products, one row per product 263 264 * description 265 * quantity 266 * total price 267 * total tax 268 * sum at the bottom 269 270 * horizontal timeline of important dates in the contract 271 272 * start at contract creation time 273 * show current date 274 * pay_deadline 275 * wire_transfer_deadline 276 * refund_deadline 277 * delivery_date (immediately if null) 278 * auto_refund 279 280 281 refund popup 282 ............ 283 284 If there is any refund: 285 286 * show total refund from ``refund_amount`` 287 * a (down arrow) to show more information 288 * if expanded show table with date, amount and reason 289 290 Warn if there is a pending refund when ``refund_pending`` is true 291 292 Ask for: 293 294 * amount: default 0, show max amount refundable (order amount - already 295 refunded) 296 297 * reason: concatenation of the next values 298 299 * drop down options: duplicated, requested by customer, other 300 * after selecting, free text for additional information 301 302 .. image:: ../images/backoffice-order-refund.svg 303 :width: 800 304 305 .. image:: ../images/backoffice-order-refund.already.svg 306 :width: 800 307 308 Example of details by status 309 ---------------------------- 310 311 312 313 .. image:: ../images/backoffice-order-details.paid.svg 314 :width: 800 315 316 .. image:: ../images/backoffice-order-details.unpaid.svg 317 :width: 800 318 319 .. image:: ../images/backoffice-order-details.claimed.svg 320 :width: 800 321 322 .. image:: ../images/backoffice-order-details.refunded.svg 323 :width: 800 324 325 326 Alternatives 327 ============ 328 329 330 pagination 331 ---------- 332 order list was originally thought with pagination footer 333 334 .. image:: ../images/backoffice-order-list.pagination.svg 335 :width: 800 336 337 ascending boolean flag cloud be eliminated using the load before and load after 338 and a design without random access to pages was proposed 339 340 search box 341 ---------- 342 343 A SearchBox was considered for managing filter. 344 Filter will allow paid, refunded, wired status and date. 345 346 * paid: yes/no 347 * refunded: yes/no 348 * wired: yes/no 349 * date: 'dd/MM/yyyy' 350 351 The UI of the search box is an input field with tags showing ``field=value`` for 352 any filter set. Additionally a custom criteria can be supported like 353 ``date>last_week`` or ``amount>USD:10`` 354 355 356 357 Discussion / Q&A 358 ================ 359 360 * Shall we show merchant information from the ContractTerm in the order detail? 361 362 * Do we have the date and time of when the order goes from these states? 363 364 * null => unpaid (using contractTerm.timestamp from now but may not be correct) 365 366 * unpaid => claimed (maybe contractTerm.timestamp) 367 368 * claimed => paid (maybe last wire_details.execution_time with confirmed = true ) 369 370 * Refund button is being show if "refund_amount < contract_terms.amount" and "time < refund deadline". 371 Is there any other case? Is this taking into account auto_refund? 372 373 * Field left out in the order creation: 374 375 * contractTerm.summary_i18n: it makes the UI complex 376 * contractTerm.order_id: should be created by the backend 377 * contractTerm.timestamp: defined by backend 378 * contractTerm.merchant_pub: filled by the backend 379 * contractTerm.merchant_base_url: filled by the backend 380 * contractTerm.h_wire: defined by the backend 381 * contractTerm.nonce: not used