summaryrefslogtreecommitdiff
path: root/design-documents/015-merchant-backoffice-routing.rst
diff options
context:
space:
mode:
authorSebastian <sebasjm@gmail.com>2021-03-26 15:20:58 -0300
committerSebastian <sebasjm@gmail.com>2021-03-26 15:21:46 -0300
commit0ba52664158c2de81b0f805c417046ff5ebf86c0 (patch)
treeb1cbaa6c9e68ac4588c2460ae53d65dafedcee99 /design-documents/015-merchant-backoffice-routing.rst
parentb3df4cf18decb81ed16dac1f46c861dd29d689fe (diff)
downloaddocs-0ba52664158c2de81b0f805c417046ff5ebf86c0.tar.gz
docs-0ba52664158c2de81b0f805c417046ff5ebf86c0.tar.bz2
docs-0ba52664158c2de81b0f805c417046ff5ebf86c0.zip
routing refactored
Diffstat (limited to 'design-documents/015-merchant-backoffice-routing.rst')
-rw-r--r--design-documents/015-merchant-backoffice-routing.rst146
1 files changed, 75 insertions, 71 deletions
diff --git a/design-documents/015-merchant-backoffice-routing.rst b/design-documents/015-merchant-backoffice-routing.rst
index 49a5dede..771b0d30 100644
--- a/design-documents/015-merchant-backoffice-routing.rst
+++ b/design-documents/015-merchant-backoffice-routing.rst
@@ -9,70 +9,117 @@ 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
+routing of the views with the possibility to accessing them directly when
sharing a link.
+This 3 definitions are going to be use in this document:
-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.
+* BACKOFFICE_URL as the url where the app is loaded.
+
+* BACKEND_URL as the url where the merchant backend is.
- 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
+* INSTANCE the name of the instance being manage
-Some border cases:
-https://bugs.gnunet.org/view.php?id=6811
+.. _routing:
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 user tried to login.
+
+* the application 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 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 routing
+====================
+
+There are 2 type of routing: instance and internal
+
+ **instance**: define how 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 which 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
+
+Knowing that the $BACKEND_URL points to a correct merchant backend the SPA will
+check for ``$BACKEND_URL/private/instances``:
+
+* if Unauthorized ask for credentials
+
+* if error check with the user
+
+* if not found, then url should end with ``/instances/$INSTANCE``. otherwise is
+ an error. app will continue as admin = false
+
+* if ok then then $INSTANCE == 'default', app will continue as admin = true
+
+When a user access the SPA there are 3 scenarios possible:
+
+* **standard**: admin is false so BACKEND_URL points to a non-default instance.
+ standard features and links are shown
+
+* **admin**: admin is true so BACKEND_URL point to default instance. same as
+ before and user can create and list instances with some additional links in
+ the sidebar.
+
+* **mimic**: admin is true and the request parameter "instance" is set $INSTANCE
+ instance. BACKEND_URL point to default instance but the user is managing
+ $INSTANCE
+
+Normally all communication with the backend will be done to $BACKOFFICE_URL and
+``backend-token`` will be used used for authentication.
+
+For **mimic** scenario then ``backend-token-$INSTANCE`` is used and the queries
+to the merchant are being sent to ``$BACKEND_URL/instances/$INSTANCE``
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.
+accessible. See :ref:`routing`
-All of this entry points that do not require a paramenter (like $ID) should be
-accesbile from the Sidebar.
+All of this entry points are corresponds to the internal routing and is
+implemented using the hash path. For any entry point that do not require a
+parameter (like order id or product id) it should be accessible from the Sidebar.
-If the admin panel is accesible, this entry points are available:
+If the user has admin access, 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
+ - /update: instance setting page, renders a form and allow modifying 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
+As an example:
+
+* ``$BACKOFFICE_URL/?instance=foo#/orders`` will show the orders of the foo
+ instance, assuming that BACKEND_URL points to the default instance.
+
+* ``$BACKOFFICE_URL/#/product/foo/update`` will show the update page for the
+ `foo` product of the instance pointed by $BACKEND_URL
+
+
Special cases
=============
@@ -85,7 +132,8 @@ with the login form (even if the backend doest not need authentication)
Log out
-------
-On logout, the application go to the initial state
+On logout, the application go to the initial state. Removing all backend-token-*
+from the localStorage
Unauthorized
------------
@@ -100,7 +148,7 @@ Not found
For any case that the backend respond 404 the application will render a
custom not found page
-Missing default instance
+Default instance is missing
------------------------
If the **user is admin** AND is loading the setting page (/update), product list
@@ -108,49 +156,5 @@ If the **user is admin** AND is loading the setting page (/update), product list
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.