From 0073e7d30689ad53f499ea5c9ccc2adc588cecbd Mon Sep 17 00:00:00 2001 From: Sebastian Date: Thu, 18 Mar 2021 18:58:32 -0300 Subject: backoffice routing design --- .../015-merchant-backoffice-routing.rst | 153 +++++++++++++++++++++ 1 file changed, 153 insertions(+) create mode 100644 design-documents/015-merchant-backoffice-routing.rst diff --git a/design-documents/015-merchant-backoffice-routing.rst b/design-documents/015-merchant-backoffice-routing.rst new file mode 100644 index 00000000..3cf7e80f --- /dev/null +++ b/design-documents/015-merchant-backoffice-routing.rst @@ -0,0 +1,153 @@ +Design Doc 015: Merchant backoffice Routing +########################################### + + +Motivation +========== + +A well defined routing will allow users to share backoffice links pointing directly into instance pages (settings, orders, products, etc...) +The backoffice should load from the instance URL and then allow a internal +rounting of the views with the posibility to accessing them directly when +sharing a link. + + +Application rounting +==================== + +There are 2 type of rounting: external and internal + + external: define how the pathname of the URL will be interpreted to infer + which instance is being accessed. Also the full URL is used as default when + no BACKEND_URL exist yet in localStorage. After login, the BACKEND_URL is saved + in localStorage and the pathname is parsed to infer the instance id. + + internal: define wich view will be rendered. It is implemented using a hash + routing since 1) the SPA is not server side rendered and 2) the http servers + doest not need to care about matching all applications URL + +Some border cases: +https://bugs.gnunet.org/view.php?id=6811 + + +Application Ready definition +============================ + +The application is considered ready after + + * the user tried to login. + * the applicaton checked that the backend url points to a merchant backend + * the merchant backend response successfully + +The backoffice test for $BACKEND_URL/config to define if the $BACKEND_URL is ok. +The application can potentially test if the protocol or version matched. + +While the application is not ready, just the top navigation bar will be shown +with a message in the left and the lang selection option. + + +Application entry points +======================== + +When the application is ready to start, it queries the backend to test if the +user can access to the list of instance and decide if the admin panel should be +accesible. + +All of this entry points that do not require a paramenter (like $ID) should be +accesbile from the Sidebar. + +If the admin panel is accesible, this entry points are available: + + - /instances: Show the list of instances currently created + - /instance/new: Show a instance creation form + - /instance/$ID/update: Show a instance modify form and allow updating it + +Where admin or not, there is also this entry points: + + - / : redirects to the instance settings page + - /update: instance setting page, renders a form and allow modifing it + - /products: list of instance products + - /product/$ID/update: product modification page + - /product/new : product creation page + - /orders : list of instance orders + - /transfers : list of transfers + +Special cases +============= + +First time +---------- + +If the application is loaded for the first time a welcoming message is shown +with the login form (even if the backend doest not need authentication) + +Log out +------- + +On logout, the application go to the initial state + +Unauthorized +------------ + +For any case that the backend respond 401 the application will render the +login view showing a notification error that the user must check the login +credentials or the backend url + +Not found +--------- + +For any case that the backend respond 404 the application will render a +custom not found page + +Missing default instance +------------------------ + +If the **user is admin** AND is loading the setting page (/update), product list +(/products), order list (/orders) or transfer list (/transfers) AND **gets a +404** it will tell the user that it need to create a default instance before +proceeding. + + +Checking for admin rights +========================= + +The token and backend url provided may give access to the default instance and +in that case an admin functionality should be accesbile. + +This check is done after the query to $BACKEND_URL/config returns 200 validating +that it points to a correct merchant backend. Sidebar with access to the logout +button should be shown after this point. + +The user is considered admin if has access to the default instance. This will be +defined after quering $BACKEND_URL/private/instances. + + * HTTP response 200: means that $BACKEND_URL points to default instance and + user has admin rights + * HTTP response 401: means that $BACKEND_URL points to default instance but + wrong credentials (either no there or invalid). It will render login screen. + * HTTP response 404: means that $BACKEND_URL its not the default instance and + will asume that $BACKEND_URL points to a non default instance (since + $BACKEND_URL/config should have responded 200) + * HTTP respone with error code: render the error message and the login screen. + +When testing for admin rights and if the response is 404, the application will +parse the $BACKEND_URL pathname and expect to match exactly '/instances/$ID' +(optionally ending with a slash) and use $ID as the instance $ID for any +operation that needs it. If fails to infer the instance $ID render an error +message with a login screen. + + +Credentials +============ + +All tokens are saved in localStorage with key ``backend-token-$ID``, the default +backend token have the key ``backend-token``. + +Default instance user is expected to jump from one instance to another in the +same session so all queries to the backend will be to +``${BACKEND_URL}/instances/${CURRENT_INSTANCE_ID}`` with the ``BACKEND_URL`` provided in +the login form and using the token expected to ``$CURRENT_INSTANCE_ID``. + +Queries from a normal user will be done directly to ``$BACKEND_URL`` and using token +from the login form. + + -- cgit v1.2.3