Better definition of Application versus Application domain

Keyclic · Mar 8, 2017 · 07bca4e · 07bca4e
1 parent 3a6caa3
commit 07bca4e
Show file tree

Hide file tree

Showing 8 changed files with 74 additions and 21 deletions.
diff --git a/authentication.md b/authentication.md
@@ -46,7 +46,7 @@ Si les credentials sont reconnus par le serveur, celui-ci retourne un accessToke
 
 La quasi totalité des requêtes à l'API nécessitent que l'utilisateur soit authentifié, c'est à dire qu'il fournisse son accessToken. Le token est envoyé dans l'entête Authorization de la requête, préfixé par Bearer.
 
-Par exemple, pour récupérer la liste des feedbacks du domaine applicatif com.keyclic.app, un utilisateur utilise le endpoint :
+Par exemple, pour récupérer la liste des feedbacks de l'application com.keyclic.app, un utilisateur utilise le endpoint :
 
 ```
 GET /feedbacks
@@ -90,7 +90,7 @@ Cette requête envoie un email à l'utilisateur contenant un lien se terminant p
 https://domain.com/#/password-reset/jrtVqBLxxoSA0c2hpsOBN-JQGQHGN3YXsKPMG1PWWWA
 ```
 
-Dans le lien ci-dessus, le domaine dépend du domaine applicatif (paramètre X-Keyclic-App passé en header de la requête) et jrtVqBLxxoSA0c2hpsOBN-JQGQHGN3YXsKPMG1PWWWA est le jeton de changement de mot de passe.
+Dans le lien ci-dessus, le nom de domaine dépend de la configuration de l'application et jrtVqBLxxoSA0c2hpsOBN-JQGQHGN3YXsKPMG1PWWWA est le jeton de changement de mot de passe.
 
 L'utilisateur peut ensuite changer son mot de passe avec :
 

diff --git a/feedbacks.md b/feedbacks.md
@@ -50,11 +50,11 @@ Exemple :
 
 ## Modération et cycle de vie d'une observation
 
-Après qu'un utilisateur a créé une nouvelle observation, celle-ci possède le statut PENDING_REVIEW : en attente de modération. Elle devra être validée par un administrateur du domaine applicatif.
+Après qu'un utilisateur a créé une nouvelle observation, celle-ci possède le statut PENDING_REVIEW : en attente de modération. Elle devra être validée par un administrateur de l'application.
 
 LIEN : statuts et changements de statuts
 
-Un administrateur du domaine applicatif valide une observation avec le endpoint :
+Un administrateur d'application valide une observation avec le endpoint :
 
 ```
 POST /feedbacks/{feedback}/state
@@ -129,7 +129,7 @@ Plusieurs critères permettent de filter les observations.
 
 **Par statut : paramètre state**
 
-Par exemple, pour filtrer les observations en attente de validation, un administrateur du domaine applicatif effectuera la requête :
+Par exemple, pour filtrer les observations en attente de validation, un administrateur d'application effectuera la requête :
 
 ```
 GET /feedbacks?state=PENDING_REVIEW

diff --git a/index.md b/index.md
@@ -2,7 +2,7 @@
 
 Swagger file : https://api.keyclic.com/swagger.json
 
-## Apperçu général 
+## Apperçu 
 - Intro
 - Vocabulaire (français et anglais)
 - Fonctionnement général
@@ -28,7 +28,7 @@ Swagger file : https://api.keyclic.com/swagger.json
 - Intro
 - Utilisateur de base
 - Administrateur d'organisation
-- Administrateur de domaine applicatif
+- Administrateur d'application
 - Membres d'organisation
 - Ressource utilisateur
 - Récupération des membres

diff --git a/organizations.md b/organizations.md
@@ -25,7 +25,7 @@ Exemple :
 
 L'utilisateur devient automatiquement membre et administrateur de cette nouvelle organisation.
 
-Pour récupérer toutes les organisations du domaine applicatif :
+Pour récupérer toutes les organisations de l'application :
 
 ```
 GET /organizations
@@ -120,7 +120,7 @@ body :
 }
 ```
 
-Pour récupérer toutes les zones géographiques du domaine applicatif :
+Pour récupérer toutes les zones géographiques de l'application :
 
 ```
 GET /places
@@ -152,7 +152,7 @@ Exemple :
 
 Les 3 propriétés name, color et icon peuvent être éditées par une requête PATCH (LIEN).
 
-Pour récupérer l'ensemble des catégories du domaine applicatif :
+Pour récupérer l'ensemble des catégories de l'application :
 
 ```
 GET /categories

diff --git a/overview.md b/overview.md
@@ -0,0 +1,47 @@
+# Aperçu
+
+Keyclic est une application de remontée et de traitement d'observations. Elle permet à ses utilisateurs de signaler des dysfonctionnements, des problèmes techniques ou tout autre type d'information, et de remonter ces signalements aux personnes concernées qui pourront alors en effectuer le traitement.
+
+## Fonctionnement général
+
+L'application Keyclic est librement ouverte aux inscriptions. Une fois inscrit, tout utilisateur peut créer des observations. Une observation est toujours liée à une position géographique et comporte éventuellement une ou plusieurs photos.
+
+Certains utilisateurs peuvent également être regroupés au seins d'organisations. Une organisation est donc un groupe d'utilisateurs membres de la même entreprise, association, corporation, école, etc. Tout utilisateur est libre de créer sa propre organisation et d'inviter d'autres utilisateurs à en devenir membres.
+
+Les administrateurs d'organisation définissent des zones géographiques sur lesquelles leur organisation peut intervenir, et des catégories d'intervention (exemples : voirie, animal perdu, propreté, etc...) Ainsi, quand un utilisateur crée une observation, la position géographique de cette observation permet de lui proposer les catégories et organisations qui sont en mesure de traiter son signalement et de le laisser choisir celle qui lui semble la plus apte à traiter son problème.
+
+Quand un utilisateur crée une observation, celle-ci doit tout d'abord être validée par un administrateur de l'application, [sauf dans certains cas où la validation est automatique](LIEN_PAGE_FEEDBACKS)). Une fois validée, cette observation est visble par la communauté : ainsi les autres utilisateurs peuvent la commenter et/ou la soutenir. De plus, au moment où l'observation est validée, un rapport est généré et transmis à l'organisation concernée. 
+
+Un administrateur d'organisation a donc accès à l'ensemble des rapports concernant son organisation, chaque rapport correspondant à une observation. Pour chaque rapport, il peut créer une ou plusieurs opérations, et affecter ces opérations aux utilisateurs membres de son organisation. Une fois que toutes les opérations ont été accomplies, il pourra considérer que le traitement est terminé et clôturer le rapport. Une autre possibilité est de déléguer ce rapport à une organisation partenaire.
+
+## Vocabulaire
+
+**Observation** : Remarque effectuée sur le terrain par un utilisateur, pouvant porter sur un dysfonctionnement, un problème technique, une nuisance, etc. Toute observation est forcément faite en une position géographique donnée. Elle peut éventuellement comporter des photos, et être commentée et/ou soutenue par les autres utilisateurs.
+
+**Rapport** : Toute observation, une fois validée par un administrateur du domaine applicatif, entraîne la génération d'un rapport. Un rapport reprend donc toutes les informations de l'observation dont il est issu, et n'est visible et manipulable que par l'organisation concernée par l'observation initiale. Le rapport est donc le pendant professionnel de l'observation. C'est sur ce rapport que l'organisation travaille : création d'opérations, suivi, délégation, etc.
+
+**Organisation** : Groupe d'utilisateurs pouvant être une entreprise, une école, une association, etc... 
+
+**Application** : Un client de l'API travaille toujours sur une application particulière de Keyclic, correspondant à un domaine applicatif. Chaque application possède ses propres administrateurs, dont la principale mission est de modérer les observations avant que celles-ci ne soient transmises sous forme de rapport aux organisations concernées.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/reports.md b/reports.md
@@ -1,6 +1,6 @@
 # Rapports
 
-Chaque fois qu'une observation est acceptée, soit après validation par un administrateur du domaine applicatif, soit automatiquement parce que l'utilisateur qui l'a créée était membre de l'organisation concernée par cette observation, un rapport est créé.
+Chaque fois qu'une observation est acceptée, soit après validation par un administrateur de l'application, soit automatiquement parce que l'utilisateur qui l'a créée était membre de l'organisation concernée par cette observation, un rapport est créé.
 
 Un administrateur d'organisation récupère les rapports concernant son organisation avec :
 

diff --git a/technical.md b/technical.md
@@ -8,16 +8,22 @@ Le nom de domaine de l'API Keyclic est :
 api.keyclic.com
 ```
 
-La documentation technique de l'API selon la spécification Swagger peut être téléchargée ici : https://api.keyclic.com/swagger.json
+La documentation technique Swagger de l'API peut être téléchargée ici : https://api.keyclic.com/swagger.json
 
-## Domaines applicatifs
+## Applications et clés d'applications
 
-Toutes les opérations sont effectuées sur un domaine applicatif particulier. Deux domaines applicatifs sont actuellement reconnus par l'API :
+Tout client de l'API doit transmettre dans les headers de chaque requête une clé définissant l'application sur laquelle il travaille.
+
+Si vous développez un client pour travailler sur une application existante de Keyclic, vous devez connaître la clé de cette application. Si au contraire vous développez un client pour une nouvelle application, merci de vous adresser à la société Keyclic pour que celle-ci crée l'application et sa configuration et vous fournisse la clé correspondante.
+
+Deux clés d'application sont actuellement disponibles :
 
 - com.keyclic.app
 - com.keyclic.highway.vinci
 
-Tout client de l'API doit donc travailler sur l'un de ces domaines, en le précisant dans les headers de chaque requête (voir ci-desous : [Requêtes](#requêtes)). Si vous souhaitez qu'un nouveau domaine applicatif soit créé, merci d'en faire la demande à la société Keyclic.
+Chaque requête doit donc préciser, dans ses headers, la valeur du paramètre X-Keyclic-App. Voir ci-dessous le paragraphe [Requêtes](#requêtes) pour la mise en œuvre.
+
+Notez cependant que la base utilisateurs est commune à toutes les applications Keyclic. De fait, les endpoints d'inscription et de connexion (LIEN : authentification) font exception à la règle ci-dessus : ces deux endpoints n'exigent pas qu'une clé d'application leur soit fournie.
 
 ## Requêtes
 
@@ -51,7 +57,7 @@ GET /feedbacks?before=2018-04-22T01:00:00+05:00
 
 ### Headers
 
-En plus des [headers conventionnels de HTTP/1.1](https://tools.ietf.org/html/rfc7231#section-5), l'API Keyclic accepte, et même exige dans la plupart des cas, le header X-Keyclic-App, correspondant au domaine applicatif (voir ci-dessus : [Domaines applicatifs](#domaines-applicatifs)). Par exemple, pour récupérer toutes les observations sur le domaine applicatif com.keyclic.app, la requête comportera le header :
+En plus des [headers conventionnels de HTTP/1.1](https://tools.ietf.org/html/rfc7231#section-5), l'API Keyclic accepte, et même exige dans la plupart des cas, le header X-Keyclic-App, correspondant à l'application utilisée (voir ci-dessus : [Domaines applicatifs](#domaines-applicatifs)). Par exemple, pour récupérer toutes les observations sur l'application com.keyclic.app, la requête comportera le header :
 
 ```
 X-Keyclic-App : com.keyclic.app

diff --git a/users.md b/users.md
@@ -4,7 +4,7 @@ Les utilisateurs de l'application Keyclic possèdent un ou plusieurs rôles, dé
 
 - ROLE_USER : utilisateur de base
 - ORGANIZATION:ADMIN : administrateur d'une organisation
-- APPLICATION:ADMIN : administrateur d'un domaine applicatif
+- APPLICATION:ADMIN : administrateur d'application
 
 ## Utilisateur de base (rôle ROLE_USER)
 
@@ -34,9 +34,9 @@ L'administrateur d'une organisation peut :
 
 LIEN : rubrique organisation
 
-## Administrateur de domaine applicatif (rôle APPLICATION:ADMIN)
+## Administrateur d'application (rôle APPLICATION:ADMIN)
 
-L'administrateur d'un domaine applicatif a la possibilité de modérer les observations.
+L'administrateur d'une application a la possibilité de modérer les observations avant que celles-ci soient transmises, sous forme de rapport, aux organisations concernées.
 
 LIEN : Feedbacks / modération
 
@@ -50,7 +50,7 @@ Note : dans l'appli cliente Keyclic, ce fonctionnement est obtenu par l'activati
 
 ## Exemple de ressource utilisateur
 
-La lecture d'une ressource Utilisateur permet de découvrir les rôles de cet utilisateur, et éventuellement l'organisation dont il est administrateur et/ou le domaine applicatif dont il est administrateur.
+La lecture d'une ressource Utilisateur permet de découvrir les rôles de cet utilisateur, et éventuellement l'organisation dont il est administrateur et/ou l'application dont il est administrateur.
 
 ```
 GET /people/5020c6ea-ca07-42d1-994f-d90b86703b1a
@@ -95,7 +95,7 @@ Ce retour indique que :
 1. Cet utilisateur possède le rôle ROLE_USER, comme tous les utilisateurs.
 2. Il est membre de l'organisation 84d36093-b8bc-47ad-bc8a-a043b3e301a9
 3. Il possède le rôle ORGANIZATION:ADMIN, il est donc administrateur de l'organisation 84d36093-b8bc-47ad-bc8a-a043b3e301a9
-4. Il possède le rôle APPLICATION:ADMIN, il est donc administrateur du domaine applicatif auquel est rattachée l'organisation 84d36093-b8bc-47ad-bc8a-a043b3e301a9
+4. Il possède le rôle APPLICATION:ADMIN, il est donc administrateur de l'application à laquelle est rattachée l'organisation 84d36093-b8bc-47ad-bc8a-a043b3e301a9
 
 ## Récupération des membres