015-merchant-backoffice-routing.rst (5827B)
1 DD 15: Merchant backoffice Routing 2 ################################## 3 4 :Design status: Accepted 5 :Implementation status: Implemented 6 :DD shepherd: TBD 7 :Historical contributors: Sebastian 8 :First published: 2021-03-18 9 :Last substantive change: 2021-08-06 10 :Implementation evidence: merchant (2021-08-05) 11 :Normative references: :doc:`../taler-merchant-manual`, :doc:`../core/api-merchant` 12 13 .. note:: 14 15 This document records the original SPA routing and authentication design. 16 In particular, its ``default``-as-administrator convention is historical; 17 the current API uses the ``admin`` instance and scoped bearer tokens. 18 19 Motivation 20 ========== 21 22 A well defined routing will allow users to share backoffice links pointing 23 directly into instance pages (settings, orders, products, etc...) 24 25 The backoffice should load from the instance URL and then allow an internal 26 routing of the views with the possibility to accessing them directly when 27 sharing a link. 28 29 This 3 definitions are going to be use in this document: 30 31 * BACKOFFICE_URL as the url where the app is loaded. 32 33 * BACKEND_URL as the url where the merchant backend is. 34 35 * INSTANCE the name of the instance being manage 36 37 38 Application Ready definition 39 ============================ 40 41 The application is considered ready after 42 43 * the user tried to login. 44 45 * the application checked that the backend url points to a merchant backend 46 47 * the merchant backend response successfully 48 49 The backoffice test for ``$BACKEND_URL/config`` to define if the $BACKEND_URL is ok. 50 The application can potentially test if the protocol or version matched. 51 52 While the application is not ready, just the top navigation bar will be shown 53 with a message in the left and the lang selection option. 54 55 .. _routing: 56 57 Application routing 58 ==================== 59 60 There are 2 type of routing: instance and internal 61 62 **instance**: define how the URL will be interpreted to infer which instance is 63 being accessed. Also the full URL is used as default when no BACKEND_URL exist 64 yet in localStorage. After login, the BACKEND_URL is saved in localStorage and 65 the pathname is parsed to infer the instance id. 66 67 **internal**: define which view will be rendered. It is implemented using a hash 68 routing since 1) the SPA is not server side rendered and 2) the http servers 69 doest not need to care about matching all applications URL 70 71 Knowing that the $BACKEND_URL points to a correct merchant backend the SPA will 72 check for ``$BACKEND_URL/management/instances``: 73 74 * if Unauthorized ask for credentials 75 76 * if error check with the user 77 78 * if not found, then url should end with ``/instances/$INSTANCE``. otherwise is 79 an error. app will continue as admin = false 80 81 * if ok then $INSTANCE == 'admin', app will continue as admin = true 82 83 When a user access the SPA there are 3 scenarios possible: 84 85 * **standard**: admin is false so BACKEND_URL points to a non-admin instance. 86 standard features and links are shown 87 88 * **admin**: admin is true so BACKEND_URL points to the admin instance. As 89 before and user can create and list instances with some additional links in 90 the sidebar. 91 92 * **mimic**: admin is true and the request parameter "instance" is set $INSTANCE 93 instance. BACKEND_URL points to the admin instance but the user is managing 94 $INSTANCE 95 96 Normally all communication with the backend will be done to $BACKOFFICE_URL and 97 ``backend-token`` will be used used for authentication. 98 99 For **mimic** scenario then ``backend-token-$INSTANCE`` is used and the queries 100 to the merchant are being sent to ``$BACKEND_URL/instances/$INSTANCE`` 101 102 Application entry points 103 ======================== 104 105 When the application is ready to start, it queries the backend to test if the 106 user can access to the list of instance and decide if the admin panel should be 107 accessible. See :ref:`routing` 108 109 All of this entry points are corresponds to the internal routing and is 110 implemented using the hash path. For any entry point that do not require a 111 parameter (like order id or product id) it should be accessible from the Sidebar. 112 113 If the user has admin access, this entry points are available: 114 115 - /instances: Show the list of instances currently created 116 - /instance/new: Show an instance creation form 117 118 Where admin or not, there is also this entry points: 119 120 - / : redirects to the instance settings page 121 - /update: instance setting page, renders a form and allow modifying it 122 - /products: list of instance products 123 - /product/$ID/update: product modification page 124 - /product/new : product creation page 125 - /orders : list of instance orders 126 - /transfers : list of transfers 127 128 As an example: 129 130 * ``$BACKOFFICE_URL/?instance=foo#/orders`` will show the orders of the foo 131 instance, assuming that BACKEND_URL points to the admin instance. 132 133 * ``$BACKOFFICE_URL/#/product/foo/update`` will show the update page for the 134 ``foo`` product of the instance pointed by $BACKEND_URL 135 136 137 Special cases 138 ============= 139 140 First time 141 ---------- 142 143 If the application is loaded for the first time a welcoming message is shown 144 with the login form (even if the backend doest not need authentication) 145 146 Log out 147 ------- 148 149 On logout, the application go to the initial state. Removing all backend-token-* 150 from the localStorage 151 152 Unauthorized 153 ------------ 154 155 For any case that the backend respond 401 the application will render the 156 login view showing a notification error that the user must check the login 157 credentials or the backend url 158 159 Not found 160 --------- 161 162 For any case that the backend respond 404 the application will render a 163 custom not found page 164 165 Admin instance is missing 166 ------------------------- 167 168 If the **user is admin** AND is loading the setting page (/update), product list 169 (/products), order list (/orders) or transfer list (/transfers) AND **gets a 170 404** it will tell the user that it needs to create an admin instance before 171 proceeding.