📝 update documentation for permissions on v4.4

11 files changed, 114 insertions, 14 deletions

diff --git a/docs/fr/source/_static/admin-fiche-compte.png b/docs/fr/source/_static/admin-fiche-compte.png
new file mode 100644
index 000000000..4ad859260
--- /dev/null
+++ b/docs/fr/source/_static/admin-fiche-compte.png
diff --git a/docs/fr/source/_static/permissions-admin.png b/docs/fr/source/_static/permissions-admin.png
new file mode 100644
index 000000000..39c15c8b3
--- /dev/null
+++ b/docs/fr/source/_static/permissions-admin.png
diff --git a/docs/fr/source/_static/permissions-amont.png b/docs/fr/source/_static/permissions-amont.png
new file mode 100644
index 000000000..c067cf39a
--- /dev/null
+++ b/docs/fr/source/_static/permissions-amont.png
diff --git a/docs/fr/source/_static/permissions-rattachement.png b/docs/fr/source/_static/permissions-rattachement.png
new file mode 100644
index 000000000..ad8a04f3f
--- /dev/null
+++ b/docs/fr/source/_static/permissions-rattachement.png
diff --git a/docs/fr/source/administrateur-applicatif.rst b/docs/fr/source/administrateur-applicatif.rst
index c77ddd4c5..b51d3fdda 100644
--- a/docs/fr/source/administrateur-applicatif.rst
+++ b/docs/fr/source/administrateur-applicatif.rst
@@ -5,7 +5,7 @@ Administration applicative
 ==========================
 
 :Auteurs: Étienne Loks, ValĂ©rie-Emma Leroux, Perrine Pautrat
-:Date: 2024-06-06
+:Date: 2025-02-28
 :Copyright: CC-BY 3.0
 
 ----------------------------------
@@ -143,7 +143,13 @@ Cette interface de création de compte permet aussi de modifier le mot de passe
 Permissions dans Ishtar
 ***********************
 
-Les permissions dans Ishtar sont essentiellement gérées par « Type de profil ». Chaque compte a un ou plusieurs « types de profil » associés à son compte. Chaque type de profil donne accÚs à des actions et des accÚs sur des types d'objets.
+Les permissions dans Ishtar sont uniquement gérées par le « Type de profil » associé à chaque compte utilisateur. Chaque compte a un ou plusieurs « types de profil » associés à son compte. Chaque type de profil donne accÚs à des actions et des accÚs sur des types d'objets.
+
+.. warning:: Un profil particulier existe, le profil « administrateur » qui correpond à l'utilisateur disposant des permissions de l'administrateur applicatif. Le détail des permissions supplémentaires octroyé par ce profil est détaillé dans ':ref:`annexe 2 - détail des permissions <annexe-permission-action>`.
+
+.. warning:: Lorsque l'on change les types de profils d'un utilisateur, il est nécessaire de regénérer les permissions depuis sa fiche « compte ». Cf. (1) sur l'image ci-dessous.
+
+.. image:: _static/admin-fiche-compte.png
 
 La crĂ©ation/configuration d'un type de profil se fait via : *Ishtar - Commun â€ș Types de profil* :
 
@@ -151,32 +157,41 @@ La crĂ©ation/configuration d'un type de profil se fait via : *Ishtar - Commun â€
 - **identifiant textuel** : rempli selon les rĂšgles habituelles des identifiants textuels.
 - **groupes** : listes des groupes auxquels le profil est rattaché.
 
+
 Chaque groupe correspond à un type de permission pour un élément précis de la base de données :
 
-- droit de lecture ;
-- droit d'ajout ;
-- droit de modification/suppression.
+- permission de lecture ;
+- permission d'ajout ;
+- permission de modification
+- permission de suppression.
+
 
-Chacun de ces droits est décliné en deux modalités :
+Hormi pour la permission d'ajout (pour laquelle le distinguo n'est pas pertinent), chacune de ces permissions est déclinée en deux modalités :
 
-- droits sur tous les éléments ;
-- droit sur les éléments rattachés.
+- permission sur tous les éléments ;
+- permission sur les éléments rattachés.
 
-Un élément est dit « rattaché » à une personne en fonction de rÚgles précises spécifiées dans l':ref:`annexe 2 - détail des permissions <annexe-permission-action>`. La notion de rattachement permet de spécifier finement les permissions pour des personnes qui sont directement associées à l'élément. Par exemple cela permet de donner les droits de modification du mobilier d'une opération au responsable scientifique de cette opération.
+
+Les Ă©lĂ©ments rattachĂ©s Ă  un utilisateur (via son profil d'utilisateur) sont dĂ©finis via une « requĂȘte pour permission ». Cette « requĂȘte pour permission » dĂ©fini le type de rattachement pour chaque permission (lecture, ajout, modification, suppression) concernant chaque type d'Ă©lĂ©ment rattachĂ©. Ces requĂȘtes pour permissions sont dĂ©finis dans l':ref:`annexe 2 - dĂ©tail des permissions <annexe-permission-action>`.
+
+.. warning:: Les requĂȘtes pour permissions peuvent ĂȘtre des requĂȘtes dynamiques (exemple : toutes les opĂ©rations prĂ©ventives), ces permissions sont regĂ©nĂ©rĂ©es automatiquement une fois par jour pour prendre en compte ces Ă©ventuels changements. Une regĂ©nĂ©ration peut ĂȘtre dĂ©clenchĂ©e ponctuellement via la fiche de compte d'un utilisateur.
 
 En pratique, globalement, les groupes de droits permettent d'accéder à certaines actions :
 
-- le droit de lecture permet une ouverture de la fiche correspondant à l'élément ;
+- le droit de lecture permet une ouverture de la fiche correspondant à l'élément, l'affichage du détail sur la fiche, l'affichage certaines colonnes sur les tableaux ;
 - le droit d'ajout permet d'accéder aux actions d'ajout d'un nouvel élément ;
-- le droit de modification/suppression permet d'accéder aux actions concernant la modification/suppression des éléments.
+- le droit de modification permet d'accéder aux actions concernant la modification des éléments ;
+- le droit de suppression permet d'accéder aux actions concernant la suppression des éléments.
 
-Dans le détail, il y a certaines données, actions qui sont accessibles en fonction d'appartenance à des groupes en particulier. Tout cela est détaillé dans l':ref:`annexe 2 - détail des permissions <annexe-permission-action>`.
 
 .. note:: La page *Ishtar - Commun â€ș RĂ©sumĂ©s des types de profil* permet d'accĂ©der Ă  un tableau qui reprend et rend explicites toutes les permissions associĂ©es aux types de profil.
 
+
 Permissions dans les pages d'administration
 *******************************************
 
+TODO : Ă  revoir v4.4
+
 Les permissions des pages d'administration sont gérées différemment. Elles utilisent le systÚme de permission du framework Django, framework (cadre de développement logiciel) utilisé par Ishtar.
 Une fois le compte crĂ©Ă©, les droits se spĂ©cifient dans les pages d'administration : *Authentification et autorisation â€ș Utilisateurs*.
 
diff --git a/docs/fr/source/annexe-2-permission-action.rst b/docs/fr/source/annexe-2-permission-action.rst
index 7576121eb..8140e5cd7 100644
--- a/docs/fr/source/annexe-2-permission-action.rst
+++ b/docs/fr/source/annexe-2-permission-action.rst
@@ -7,11 +7,93 @@ Annexe 2 - DĂ©tails des permissions
 ==================================
 
 :Auteur: Étienne Loks
-:Date: 2023-10-26
+:Date: 2025-02-28
 :Copyright: CC-BY 3.0
 
 ----------------------------------
 
+Profil administrateur
+=====================
+
+Un profil spécial « administrateur » (identifiant textuel `administrator`) a par défaut toutes les permissions sur l'interface Ishtar (et pas nécessairement sur les pages d'administration).
+
+Un certain nombre d'action ne sont disponibles que pour les utilisateurs disposant de ce profil administrateur :
+
+- visualisation de la fiche compte utilisateur ;
+- gestion des comptes utilisateurs ;
+- fusion des personnes ;
+- fusion des organisations ;
+- fusion des contenants ;
+- rattachement des éléments aux utilisateurs (permissions).
+
+
+RequĂȘtes pour permissions
+=========================
+
+Les requĂȘtes pour permission doivent ĂȘtre paramĂ©trĂ©es pour dĂ©finir finement les droits des diffĂ©rents comptes utilisateurs.
+
+Une requĂȘte pour permission est dĂ©finie via un nom (pour pouvoir les distinguer), d'un identifiant textuel, d'un modĂšle auquel associer cette requĂȘte, d'une requĂȘte (champ optionnel) et des champs boolĂ©ens (oui/non), « actif » (pour activer, dĂ©sactiver la requĂȘte), « Inclure les Ă©lĂ©ments rattachĂ©s Ă  l'utilisateur », « Inclure les Ă©lĂ©ments liĂ©s aux droits amonts » et « Limiter la requĂȘte aux zones rattachĂ©es ». Cette requĂȘte pour permissions est dĂ©finie dans l'interface d'administration d'Ishtar (« https://mon-instance-ishtar/admin/ishtar_common/permissionrequest/ »).
+
+.. image:: _static/permissions-admin.png
+
+Le détail de ces champs est fait dans les sections ci-dessous.
+
+Cette requĂȘte pour permission est ensuite rattachĂ©e aux « types de profils » pour qu'ils soient effectifs. Les types de profils sont aussi dĂ©finis depuis l'interface d'administration d'Ishtar (« https://mon-instance-ishtar/admin/ishtar_common/profiletype/ »). Ces requĂȘtes pour permission ne sont nĂ©cessaires que pour les permissions limitĂ©es (« Ă©lĂ©mĂ©nt rattachĂ© »). Une alerte est affichĂ©e en haut de la page d'Ă©dition des types de profils lorsqu'une permission rattachĂ©e d'un type de profil ne dispose pas d'une requĂȘte pour permissions correspondante.
+
+RequĂȘte
+-------
+
+Une requĂȘte dynamique peut ĂȘtre faite pour obtenir les Ă©lĂ©ments Ă  rattacher. Cette requĂȘte reprend la syntaxe du champ de recherche Ishtar.
+
+**Exemple** : requĂȘte pour les opĂ©rations : « `type="Projet Collectif de Recherche"` ».
+
+Un champ spĂ©cial peut ĂȘtre utilisĂ© afin de reprendre la personne correspondant Ă  l'utilisateur dans la requĂȘte : `{USER}`.
+
+**Exemple** : requĂȘte pour les opĂ©rations dont l'utilisateur est responsable d'opĂ©ration : « `scientifique="{USER}"` ».
+
+
+Inclure les éléments rattachés à l'utilisateur
+----------------------------------------------
+
+Si cette option est cochée, des permissions sont octroyées pour les éléments qui sont directement rattachés à l'utilisateur.
+Les éléments sont rattachés via une action disponible depuis l'interface de recherche (action disponible pour le profil administrateur).
+
+.. image:: _static/permissions-rattachement.png
+
+.. note:: Le contenu des paniers de mobilier partagés sont automatiquement ajoutés aux éléments rattachés.
+
+
+Inclure les éléments liés aux droits amonts
+-------------------------------------------
+
+« Inclure les Ă©lĂ©ments liĂ©s aux permissions amonts » permet de dĂ©finir des permissions de maniĂšre discrĂȘte assez simplement.
+
+*Par exemple : pour une permission octroyĂ©e sur une unitĂ© d'enregistrement particuliĂšre, si l'utilisateur dispose, par exemple, d'une permission voir le mobilier rattachĂ© avec la requĂȘte « Mobilier – Inclure les Ă©lĂ©ments liĂ©s aux permissions amonts ». Alors cet utilisateur pourra visualiser tout le mobilier correspondant Ă  cette unitĂ© d'enregistrement.*
+
+Ces permissions sont octroyées en cascade. Ainsi si une permission est donnée sur une opération particuliÚre et qu'un utilisateur a des permissions amonts octroyées sur les unités d'enregistrement et le mobilier, cet utilisateur aura une permission sur le mobilier de l'opération en question.
+
+Si une permission amont est paramétrée avec un élément amont directement rattaché à cet utilisateur, les permissions sont octroyées sur cet élément amont sans que des permissions amont soient forcément définies.
+
+**Exemple** : une permission « voir unité d'enregistrement rattachée » sans permission « voir opération » mais avec une opération directement rattachée.
+
+Pour dĂ©finir ces rĂšgles, il faut avoir en tĂȘte la logique de ces Ă©lĂ©ments amonts. Elle est dĂ©crite par le graphe ci-dessous (les Ă©lĂ©ments amonts sont, logiquement, en haut du graphe). Le graphe peut paraĂźtre difficile Ă  apprĂ©hender, mais il suffit de remonter les flĂšches depuis l'Ă©lĂ©ment rattachĂ© qui nous intĂ©resse.
+
+**Exemple** : le mobilier a comme élément rattaché Lieu de conservation et Unité d'enregistrement.
+
+.. image:: _static/permissions-amont.png
+
+
+.. note:: Pour des raisons de lisibilité, les documents, actes administratifs et éléments géographiques n'ont pas été représentés. Ceux-ci ont comme élément amonts les éléments auxquels ils sont liés.
+
+
+Limiter la requĂȘte aux zones rattachĂ©es
+---------------------------------------
+
+Si cette option est cochée, les éléments sont filtrés par rapport à la zone rattachée au profil de l'utilisateur.
+
+**Exemple** : si des permissions sont octroyées sur les opérations avec une limite sur les zones rattachées, un utilisateur rattaché à un département spécifique n'aura accÚs qu'aux opérations de ce département.
+
+
 Imports
 =======
 
diff --git a/docs/fr/source/media-src/admin-fiche-compte.xcf b/docs/fr/source/media-src/admin-fiche-compte.xcf
new file mode 100644
index 000000000..69509bb0e
--- /dev/null
+++ b/docs/fr/source/media-src/admin-fiche-compte.xcf
diff --git a/docs/fr/source/media-src/nouvelles-permissions-amonts.drawio b/docs/fr/source/media-src/nouvelles-permissions-amonts.drawio
new file mode 100644
index 000000000..cf64e4b7a
--- /dev/null
+++ b/docs/fr/source/media-src/nouvelles-permissions-amonts.drawio
@@ -0,0 +1 @@
+<mxfile host="Electron" modified="2024-11-25T15:52:24.644Z" agent="5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/20.3.0 Chrome/104.0.5112.114 Electron/20.1.3 Safari/537.36" etag="zY0R4PlSJUkZw7cJZwD3" version="20.3.0" type="device"><diagram id="ryNfY-MA6ts6GcB-Ni9M" name="Page-1">1VrbdqIwFP0a1zzVRbgEeGzt7aFz7XR1+hjlFNNBwoSoOF8/AYJcrNZRC8UHlzk5uZ2dvTkJDozRLLnhJJp+Zh4EA13zkoFxOdB1F9nyOzWscgOyDSu3+Jx6ylYa7ulfUEZNWefUg7jmKBgLBI3qxgkLQ5iImo1wzpZ1t2cW1EeNiA8bhvsJCTatj9QT09zq6HZpvwXqT4uREXbzmhkpnNVK4inx2LJiMq4GxogzJvJfs2QEQRq8Ii55u+stteuJcQjFPg0ufnnP1wncjRbfH16W47H/cgtnahkLEszVgtVkxaqIAHgyIKrIuJgyn4UkuCqtF5zNQw/SYTRZKn3uGIukEUnjCwixUuiSuWDSNBWzQNVuLkWtLmZzPoEd88dqSxDug9jhp/pL11IZQAXqBtgMBF9JBw4BEXRRB5+oPeSv/cowyx8q0v8RdfRK1HEg538xlj98kYUkNzwzGZIqHvjPnBUVZ3EW0XPpgHCUlJVFL1+jwcgYnLtcLoqFRZ9yznm39aGkuTJ8YxeUGKeALadUwH1EMmyWkvl74rkALiDZiYCqNQxFGyUclqLVsiQhwsplWiFgYTs5ZkYXxICEil9p86GlSk+VmstE9ZwVVkUhlMutNEqLT9W6sllWKtodTsJCl98iof6hSKi3RcKHkIqchumD8BOEHHwaCw4zyEjYW04ijDsmpXUUKdGBpCwJprfEMH1Phpkfi2HHJRPHw4Mdt4bPUCsB24JRVvoGnMoQAD9eGu1eIme2pY2f2ZgGVAa6RzJoNmRQd5yOZRC3Bdcli+OeodV8aJ2ZRsdorcWjVVl8//TOObWEZU3POSerikPEaCjiSs/fUkMFb9xIUky7gVjeY4nfemqHQ+q0RcB7SZc+sQ+ZDTT0rlNG3ekkKVkf5OzqSW59eHvrJGefJtFscHOfixPrFCTeYKmF6vvCMN16F7kqqVYNyE9AWLOT1FQe+thvGLGA8WxMQ8s+x6nz3ldg1odKMYvpvL9m/uREylzvDttu4wIMmV0r53FXYKfOWw7QMtxFQmLaDamz3SoUmwmMs9O/nsC8PZrptCqsqL2zCMyI3Frr3nlRkdo0sUH60qFXMqA18HS7vghHr70zeheE7yjMZeVrGE9YGANf1F5r9BPgZiaEsN21zrvdZsjYcSopMhpqcsftTJNloYMbO9T2eXfrE8NuaISpNbZGvpb30/zWjr8j6QQh6VcmZzUfyW1K+OgHfRpHJHh80fAXdLtMkB+edXIBdfBrky1n591vQbfkiIcogvlfgnDyozI2tKHm1HaQzBGlKrrlZ78c7wBpwVgOjkzNMS3N1sziCLAWmsap/WChkcXynzC5e/l/IuPqHw==</diagram></mxfile>
\ No newline at end of file
diff --git a/docs/fr/source/media-src/nouvelles-permissions.drawio b/docs/fr/source/media-src/nouvelles-permissions.drawio
new file mode 100644
index 000000000..2610ee3bc
--- /dev/null
+++ b/docs/fr/source/media-src/nouvelles-permissions.drawio
@@ -0,0 +1 @@
+<mxfile host="Electron" modified="2024-11-17T14:27:49.455Z" agent="5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/15.4.0 Chrome/91.0.4472.164 Electron/13.5.0 Safari/537.36" etag="2I9ToygRJi77t5LPU44b" version="15.4.0" type="device"><diagram id="C5RBs43oDa-KdzZeNtuy" name="Page-1">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</diagram></mxfile>
\ No newline at end of file
diff --git a/example_project/settings.py b/example_project/settings.py
index a4a2b72f5..0ccbb03a5 100644
--- a/example_project/settings.py
+++ b/example_project/settings.py
@@ -282,7 +282,7 @@ ISHTAR_SLUGS = {
 }
 
 ISHTAR_MIGRATE_V4 = False
-ISHTAR_DOCUMENT_VERSION = "develop"
+ISHTAR_DOCUMENT_VERSION = "develop-4.4"
 
 REGISTRATION_OPEN = False
 SRID = 4326  # WGS84 - World
diff --git a/requirements_rtd.txt b/requirements_rtd.txt
index 31c781b47..b5b1f127f 100644
--- a/requirements_rtd.txt
+++ b/requirements_rtd.txt
@@ -1 +1,2 @@
+sphinx_rtd_theme
 sphinx-book-theme