Merge pull request #4 from Keyclic/enhancement

Enhancement

applications.rst

@@ -3,18 +3,34 @@
 Applications
 ============
 
-Une application au coeur du service Keyclic permet de cloisonner les remontées d’observation suivant des domaines applicatifs. Cela se traduit par l’utilisation d’applications ou de sites internet spécifiques à certains métiers. Pour l'application éponyme du service, les applications sont « Keyclic » pour les smartphones et le site internet https://app.keyclic.com pour les navigateurs.
+Une *application* au coeur du service Keyclic permet de cloisonner les remontées d’observation suivant des domaines applicatifs.
+Cela se traduit par l’utilisation d’applications clientes ou de sites internet spécifiques à certains métiers.
 
-Exemple :
-Il existe d’autres applications utilisant le service Keyclic, notamment l’application « Jaidemaville ».
-Depuis l’application « Jaidemaville », il est impossible de remonter une observation à l’application « Keyclic » (et inversement) et il est impossible de lister les observations dédiées à l’application « Keyclic » (et inversement).
+Pour le client éponyme du service, l'*application* déclarée est "com.keyclic.app", toutes les applications clientes ou sites internet utilisant cette clé auront le même cloisement. (Ici : l'application iPhone Keyclic, l'application Android Keyclic et le site internet https://app.keyclic.com pour les navigateurs.)
+
+Il existe d’autres *applications* déclarées dans le service Keyclic avec d'autres clés, notamment "Vinci Mon Autoroute" disponible sur iPhone et Android.
+
+Par exemple depuis "Vinci Mon Autoroute":
+
+ - il est impossible de remonter une observation à l’*application* déclarée avec la clé "com.keyclic.app" et inversement,
+
+ - il est impossible de lister les observations dédiées à l’*application* déclarée avec la clé "com.keyclic.app" et inversement.
 
 .. _applications-admin:
 
 Administrateur d'application
 ----------------------------
 
-L’ « Administrateur d’application » est un statut particulier donné à un utilisateur du service Keyclic qui a la possibilité de modérer les observations d’une application avant que celles-ci soient transmises, sous forme de rapports, aux organisations concernées.
-Cette modération permet de filtrer toutes observations avec du contenu enfreignant les règles d’utilisation d’une application ou enfreignant la législation d’un pays (contenu pédopornographique, incitation à la haine, etc).
+L’*administrateur d’application* est un statut particulier donné à un utilisateur du service Keyclic qui a la possibilité de **modérer** les observations d’une *application* avant que celles-ci soient transmises, sous forme de rapports, aux organisations concernées.
+
+Cette modération permet de filtrer toutes observations avec du contenu enfreignant les règles d’utilisation d’une application cliente ou d'un site internet. Par exemple, obstruction à la législation d’un pays (contenu pédopornographique, incitation à la haine, etc).
+
+Plusieurs *administrateurs d'application* peuvent modérer les observations d'une *application*. Cependant un *administrateur d'application* ne peut pas modérer les observations provenant de plusieurs *applications*.
+
+Note : L'*administrateur d'application* n'est pas obligatoirement membre d'une organisation ou n'est pas obligatoirement employé par la société Keyclic.
+
+Cas particulier
+---------------
 
-Note : Un « Administrateur d’application » n’est pas obligatoirement membre d’une organisation et ne peut modérer les observations que d’une seule et unique application, une application peut avoir plusieurs « Administrateur d’application ».
+Toutes les observations ne sont pas soumises à la modération.
+C'est le cas d'une observation effectuée par un acteur de confiance. (Voir :ref:`feedbacks-organization-member`.)

feedbacks.rst

@@ -16,38 +16,37 @@ Création d'une observation
 
     POST /feedbacks/issues
 
-Exemple minimaliste : dans l'exemple suivant, une observation est créée sans catégorie et sans description.
+Exemple du minimum requis pour effectuer une observation, une observation est créée sans catégorie et sans description. L'utilisateur émettant cette observation est détecté automatiquement grâce à l'authentification.
 
 .. code-block:: json
 
     {
+        "businessActivity": "4bff7cb9-0fd2-4b44-9b0e-f6d17bb4ef36",
         "geo": {
-            "elevation":1,
+            "elevation": 1,
             "point": {
-                "latitude":44.851343361295214,
-                "longitude":-0.5763262510299683
+                "latitude": 44.851343361295214,
+                "longitude": -0.5763262510299683
             }
-        },
-        "reporter":"6dbbd601-267f-46ea-be90-8c9742f7180b"
+        }
     }
 
-Ce endpoint se présente sous la forme **/feedbacks/issue** et non pas simplement **/feedbacks**, car à terme, il sera possible de créer différents types d'observation. Actuellement, seul le type "issue" est disponible.
-
-Exemple plus complet, l'utilisateur précise une catégorie et une description :
+Exemple plus complet, une catégorie et une description sont précisées :
 
 .. code-block:: json
 
     {
+        "businessActivity": "4bff7cb9-0fd2-4b44-9b0e-f6d17bb4ef36",
+        "category": "b0d007d5-e6ad-4113-b2b5-d8a1858a2fb1",
+        "description": "Mon feedback 5",
         "geo": {
             "elevation":1,
             "point": {
                 "latitude":44.851343361295214,
                 "longitude":-0.5763262510299683
             }
         },
-        "category":"b0d007d5-e6ad-4113-b2b5-d8a1858a2fb1",
-        "description":"Mon feedback 5",
-        "reporter":"6dbbd601-267f-46ea-be90-8c9742f7180b"
+        "visibility": "VISIBILITY_PUBLIC"
     }
 
 L'utilisateur peut ensuite ajouter une ou plusieurs images à son observation :
@@ -69,26 +68,24 @@ Pour plus d'informations sur l'envoi d'images, voir :ref:`technical-files`.
 Rattachement d'une observation à une organisation
 -------------------------------------------------
 
-L'application Keyclic ne se contente pas de recueillir des observations : elle les fait ensuite remonter, sous la forme de :ref:`reports`, aux organisations concernées, qui en assureront le traitement. Toute observation doit donc être, dans la mesure du possible, remontée à une organisation sous la forme d'un rapport. Pour cela, quatre cas de figure peuvent se présenter :
+Le service Keyclic ne se contente pas de recueillir des observations : elle les fait ensuite remonter, sous la forme de :ref:`reports`, aux organisations concernées, qui en assureront le traitement. Toute observation doit donc être, dans la mesure du possible, remontée à une organisation sous la forme d'un rapport. Pour cela, quatre cas de figure peuvent se présenter :
 
 - Si la position géographique de l'observation ne correspond à aucune zone de responsabilité, alors l'API retournera une erreur 409 et aucune organisation ne recevra de rapport sur cette observation.
 
 - Si la position géographique de l'observation se trouve dans une zone de responsabilité définie par une organisation, alors le rapport de l'observation est automatiquement remonté à l'organisation en question.
 
-- Si la position géographique de l'observation se trouve sur deux (ou plus) zones de responsabilité appartenant à deux (ou plus) organisations différentes, et que l'utilisateur a précisé une catégorie, alors le rapport de l'observation est remonté à l'organisation propriétaire de la catégorie en question.
-
 - Si la position géographique de l'observation se trouve sur deux (ou plus) zones de responsabilité appartenant à deux (ou plus) organisations différentes, mais que l'utilisateur n'a pas précisé de catégorie, alors plusieurs rapports sont générés et remontés à toutes les organisations concernées. La première organisation qui acceptera le rapport pourra en effectuer le traitement.
 
 .. _feedbacks-lifecyle:
 
 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 de l'application (sauf cas particulier d'une :ref:`feedbacks-organization-member`).
+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 d'application* (sauf cas particulier d'une :ref:`feedbacks-organization-member`).
 
 Voir : :ref:`technical-states`
 
-Un administrateur d'application valide une observation avec le endpoint :
+Un *administrateur d'application* valide une observation avec le endpoint :
 
 .. code-block:: bash
 
@@ -266,5 +263,3 @@ Pour récupérer tous les soutiens effectués sur une observation :
 .. code-block:: bash
 
     GET /feedbacks/{feedback}/contributions
-
-

sdk.rst

@@ -3,8 +3,8 @@
 SDK
 ===
 
-La société Keyclic gratuitement et librement sous licence MIT propose un SDK javascript.
-Ce SDK permet de développer plus rapidement des applications se connectant à l'API du service Keyclic.
+La société Keyclic propose gratuitement et librement sous licence MIT un SDK javascript.
+Ce SDK permet de développer plus rapidement des applications clientes se connectant à l'API du service Keyclic.
 
 Liens utiles
 ------------
@@ -14,4 +14,4 @@ Liens utiles
 Utilisation
 -----------
 
-Ce SDK est utilisé par l'application Keyclic et toutes les autres applications développées par la société Keyclic.
+Ce SDK est utilisé par l'application Keyclic elle-même et toutes les autres applications développées par la société Keyclic.