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