Merge branch 'doc-chill-database' into 'master'

doc: documentation for database printciples

See merge request Chill-Projet/chill-bundles!562

.changes/unreleased/DX-20230608-112417.yaml

@@ -0,0 +1,5 @@
+kind: DX
+body: Documentation for database principles
+time: 2023-06-08T11:24:17.701892874+02:00
+custom:
+  Issue: ""

docs/source/development/database-principles.rst

@@ -0,0 +1,84 @@
+
+.. database-principles:
+
+Principes de la base de données
+###############################
+
+Cette page donne une compréhension globale de la base de donnée de Chill, et explique quelques détails d'implémentations qui permettent d'accélérer les traitements à partir de la base de donnée, ou de l'exploiter plus aisément.
+
+Cette page est rédigée en français.
+
+.. note::
+
+    La stabilité du schéma de la base de donnée n'est pas garantie.
+
+    Toutefois, ce dernier évolue relativement peu. Il est rare que des tables ou des colonnes soient supprimées ou renommées. Mais il n'est pas garanti que cela puisse arriver.
+
+Généralités
+===========
+
+Une liste commentée de toutes les tables :download:`est disponible au format CSV <./database/table_list.csv`.
+
+Schéma et conventions de nommage
+--------------------------------
+
+Au début de l'histoire de Chill, les schémas postgresql n'étaient pas exploités. Les données étaient stockées dans le schéma :code:`public`.
+
+Par la suite, des nouveaux bundles sont apparus, et les tables ont été classées dans des schémas dédiés.
+
+A l'heure actuelle:
+
+- pour les anciens bundle, ceux qui ont déjà des tables dans le schéma public, les nouvelles tables sont ajoutées à ce schéma. Elles sont préfixées par :code:`chill_<nom du bundle>_`;
+- pour les bundles plus récents, les tables sont créées dans le schéma dédié
+
+Données avec de l'historicité
+-----------------------------
+
+Certaines données sont historisées:
+
+- les référents d'un parcours;
+- les statuts d'un parcours;
+- la liaison entre les centres et les usagers;
+- etc.
+
+Dans ces cas-là, Chill crée généralement deux colonnes, qui sont habituellement nommées :code:`startDate` et :code:`endDate`. Lorsque la colonne :code:`endDate` est à :code:`NULL`, cela signifie que la période n'est pas "fermée". La colonne :code:`startDate` n'est pas nullable.
+
+Dans certains cas, la donnée actuelle (référent d'un parcours, par exemple) est également répétée au niveau de la table en elle-même. Par exemple, la table des parcours :code:`chill_person_accompanying_period` comporte une colonne :code:`step` (le statut du parcours) et :code:`user_id` (id du référent) en plus de l'historique. Bien que redondant, cela simplifie les traitements.
+
+Relations particulières
+=======================
+
+Usagers, ménages, adresses
+--------------------------
+
+Les usagers ont une adresse au travers des ménages: dans l'interface, l'adresse est inscrite dans le dossier du ménage, et elle est "donnée" aux usagers membres du ménage, **et** qui partagent l'adresse de ce ménage. En effet, il est possible que des usagers "appartiennent" à un ménage sans y être domicilié: c'est le cas, par exemple, des enfants en garde alternée.
+
+L'historique de l'appartenance des usagers au ménage est conservée, de même que l'historique des adresses pour un même ménage.
+
+Les tables en jeu sont les suivantes:
+
+- la table :code:`chill_person_person` liste les usagers;
+- la table :code:`chill_person_household_members` liste les appartenances au ménage: il s'agit de la jointure entre les usagers et les ménages:
+  - les colonnes :code:`startDate` et :code:`endDate` indiquent la date de début et la date de fin de l'appartenance;
+  - la colonne :code:`shareHousehold` indique si l'utilisateur partage l'adresse du ménage (si oui, sa valeur est :code:`TRUE`)
+- la table :code:`chill_person_household` liste les ménages
+- la table :code:`chill_person_household_to_addresses` associe les ménages aux adresses;
+- la table :code:`chill_main_address` contient les adresses, en indiquant la date de début de validité (:code:`validFrom`) et la fin de validité (:code:`validTo`).
+
+Pour simplifier la résolution des adresses et des usagers, deux vues ont été mises en œuvre:
+
+- la vue :code:`view_chill_person_household_address` reprend, pour chaque usager, l'historique des appartenances au ménage découpée par l'historique des adresses d'un ménage.
+  Autrement dit, une ligne est créée à chaque fois qu'un usager change de ménage, ou qu'un ménage change d'adresse. Il est donc possible de retrouver l'historique complet des adresses pour un usager donné via cette table.
+- la vue :code:`view_chill_person_current_address` reprend l'adresse actuelle des usagers.
+
+Adresses et unités géographiques
+--------------------------------
+
+Chill propose des statistiques sur la localisation des adresses par rapport à des zones géographiques (:code:`chill_main_geographical_unit`).
+
+Comme la résolution géographique des adresses est coûteuse en CPU et en temps de traitement, une vue matérialisée a été créée: :code:`view_chill_main_address_geographical_unit`. Elle est rafraichie quotidiennement dans la base de donnée de production.
+
+Liste des tables et commentaires
+================================
+
+Une liste commentée de toutes les tables :download:`est disponible au format CSV <./database/table_list.csv`.

docs/source/development/database/table_list.csv

@@ -0,0 +1,155 @@
+order,table_schema,table_name,commentaire
+1,chill_3party,party_category,Catégorie de tiers
+2,chill_3party,party_center,Association entre les tiers et les centres (déprécié)
+3,chill_3party,party_profession,Profession du tiers (déprécié)
+4,chill_3party,third_party,Tiers
+5,chill_3party,thirdparty_category,association tiers - catégories
+6,chill_asideactivity,asideactivity,Activités annexes
+7,chill_asideactivity,asideactivitycategory,Catégories d'activités annexes
+8,chill_budget,charge,Charges du budget
+9,chill_budget,charge_type,Types de charges
+10,chill_budget,resource,Ressources du budget
+11,chill_budget,resource_type,Types de ressources
+12,chill_calendar,calendar,Rendez-vous
+13,chill_calendar,calendar_doc,Document du rendez-vous
+14,chill_calendar,calendar_range,Plage de disponibilité
+15,chill_calendar,calendar_to_persons,association rendez-vous - usagers
+16,chill_calendar,calendar_to_thirdparties,association rendez-vous - tiers
+17,chill_calendar,cancel_reason,Motifs d'annulations
+18,chill_calendar,invite,Invitation aux rendez-vous
+19,chill_doc,accompanyingcourse_document,Documents associés aux parcours
+20,chill_doc,document_category,Catégories de documents
+21,chill_doc,person_document,Documents associés à l'usagers
+22,chill_doc,stored_object,Documents
+23,chill_task,recurring_task,Tâches récurrentes (non utilisé)
+24,chill_task,single_task,Tâches
+25,chill_task,single_task_place_event,Historique des transitions des tâches
+26,chill_vendee,adressederelais,
+27,chill_vendee,center_polygon
+28,chill_vendee,entourage,
+29,chill_vendee,geographical_unit
+30,chill_vendee,geographical_unit_association
+31,chill_vendee,mobilite
+32,chill_vendee,niveauetude
+33,chill_vendee,security_profile
+34,chill_vendee,security_profile_action
+35,chill_vendee,security_profile_jobs
+36,chill_vendee,situationprofessionelle
+37,chill_vendee,statutlogement
+38,chill_vendee,tempsdetravail
+39,chill_vendee,titredesejour
+40,chill_vendee,vendee_person
+41,chill_vendee,vendee_person_mineur
+42,chill_vendee,vendeeperson_entourage
+43,chill_vendee,vendeepersonmineur_adressederelais
+44,public,accompanying_periods_scopes,Services associés aux parcours
+45,public,activity,Échanges
+46,public,activity_activityreason,s
+47,public,activity_person,
+48,public,activity_storedobject,
+49,public,activity_thirdparty,
+50,public,activity_user,
+51,public,activityreason,Sujets d'échange
+52,public,activityreasoncategory,Catégories de sujets
+53,public,activitytpresence,Présence aux échanges
+54,public,activitytype,Types d'échanges
+55,public,activitytypecategory,Catégories de types d'échanges
+56,public,centers,"Centres (territoires, agences, etc.)"
+57,public,chill_activity_activity_chill_person_socialaction,
+58,public,chill_activity_activity_chill_person_socialissue
+59,public,chill_docgen_template,Gabarits de documents
+60,public,chill_main_address,Adresses
+61,public,chill_main_address_legacy,Anciennes adresses (dépréciés)
+62,public,chill_main_address_reference,Adresses de référence
+63,public,chill_main_civility,Civilités
+64,public,chill_main_cronjob_execution,Dernière exécution des tâche cron
+65,public,chill_main_geographical_unit,Unités géographiques
+66,public,chill_main_geographical_unit_layer,Couches d'unités géographiques
+67,public,chill_main_location,Localisations
+68,public,chill_main_location_type,Types de localisations
+69,public,chill_main_notification,Notifications
+70,public,chill_main_notification_addresses_unread
+71,public,chill_main_notification_addresses_user
+72,public,chill_main_notification_comment,
+73,public,chill_main_postal_code,Code postaux
+74,public,chill_main_saved_export,Exports enregistrés
+75,public,chill_main_user_job,Métiers
+76,public,chill_main_workflow_entity,Workflows
+77,public,chill_main_workflow_entity_comment
+78,public,chill_main_workflow_entity_step,Etapes du workflow
+79,public,chill_main_workflow_entity_step_cc_user,
+80,public,chill_main_workflow_entity_step_user
+81,public,chill_main_workflow_entity_step_user_by_accesskey,
+82,public,chill_main_workflow_entity_subscriber_to_final,
+83,public,chill_main_workflow_entity_subscriber_to_step
+84,public,chill_person_accompanying_period,Parcours d'accompagnement
+85,public,chill_person_accompanying_period_closingmotive,Motifs de cloture des parcours
+86,public,chill_person_accompanying_period_comment,Commentaires des parcours
+87,public,chill_person_accompanying_period_location_history,Historique de la localisatio ndes parcours
+88,public,chill_person_accompanying_period_origin,Origine des parcours
+89,public,chill_person_accompanying_period_participation,Appartenance des usagers au parcours
+90,public,chill_person_accompanying_period_resource,Personnes ressources d'un parcours
+91,public,chill_person_accompanying_period_social_issues,
+92,public,chill_person_accompanying_period_step_history
+93,public,chill_person_accompanying_period_user_history
+94,public,chill_person_accompanying_period_work,Actions d'accompagnements
+95,public,chill_person_accompanying_period_work_evaluation,Évaluations (dans les actions d'accompagnements)
+96,public,chill_person_accompanying_period_work_evaluation_document,Documents des évaluations
+97,public,chill_person_accompanying_period_work_goal,Objectifs d'une actions
+98,public,chill_person_accompanying_period_work_goal_result,Objectifs et résultats d'une action
+99,public,chill_person_accompanying_period_work_person,Usagers associés à une actions
+100,public,chill_person_accompanying_period_work_referrer,Référents d'une actions
+101,public,chill_person_accompanying_period_work_result,Résultats d'une action
+102,public,chill_person_accompanying_period_work_third_party,Tiers traitants d'une action
+103,public,chill_person_alt_name,"Noms supplémentaires d'un usager (nom marital, etc.)"
+104,public,chill_person_household,Ménages
+105,public,chill_person_household_composition,
+106,public,chill_person_household_composition_type,Types de composition de ménage
+107,public,chill_person_household_members,Membres du ménages
+108,public,chill_person_household_position,Positions dans le ménage
+109,public,chill_person_household_to_addresses,Association adresses - ménages
+110,public,chill_person_marital_status,Etats civils
+111,public,chill_person_not_duplicate,
+112,public,chill_person_person,Usagers
+113,public,chill_person_person_center_history,Historique des centres d'un usagers
+114,public,chill_person_persons_to_addresses,Déprécié
+115,public,chill_person_phone,Numéros d etéléphone supplémentaires d'un usager
+116,public,chill_person_relations,Types de relations de filiation
+117,public,chill_person_relationships,Relations de filiations
+118,public,chill_person_residential_address,Adresses de résidences
+119,public,chill_person_resource,Personnes ressources (pour les personnes)
+120,public,chill_person_resource_kind,Type de personnes ressources
+121,public,chill_person_social_action,Liste des actions d'accompagnement
+122,public,chill_person_social_action_goal,Objectifs associés à une action
+123,public,chill_person_social_action_result,Résultats associés à une action
+124,public,chill_person_social_issue,Problématiques sociales
+125,public,chill_person_social_work_evaluation,Evaluations disponibles
+126,public,chill_person_social_work_evaluation_action,Associations entre les évaluations et les actions
+127,public,chill_person_social_work_goal,Objectifs disponibles pour une actions
+128,public,chill_person_social_work_goal_result,Objectifs et résultats disponible pour une action
+129,public,chill_person_social_work_result,Résultats disponibles pour une action
+130,public,country,Pays
+131,public,custom_field_long_choice_options,
+132,public,customfield
+133,public,customfieldsdefaultgroup
+134,public,customfieldsgroup
+135,public,geography_columns,Table liée à postgis
+136,public,geometry_columns,Table liée à postgis
+137,public,group_centers,
+138,public,language,Langues
+139,public,messenger_messages,Table système
+140,public,migration_versions,Table système
+141,public,permission_groups
+142,public,permissionsgroup_rolescope
+143,public,persons_spoken_languages
+144,public,regroupment,Regroupement de centres
+145,public,regroupment_center,
+146,public,role_scopes,
+147,public,scopes,Services
+148,public,spatial_ref_sys,Table système (postgis)
+149,public,user_groupcenter,
+150,public,users,Utilisateurs
+151,public,view_chill_person_accompanying_period_info,
+152,public,view_chill_person_current_address
+153,public,view_chill_person_household_address
+154,public,view_chill_person_person_center_history_current

docs/source/development/index.rst

@@ -36,6 +36,7 @@ As Chill rely on the `symfony <http://symfony.com>`_ framework, reading the fram
     Assets <assets.rst>
     Cron Jobs <cronjob.rst>
     Info about entities <entity-info.rst>
+    Info about database (in French) <database-principles.rst>
 
 Layout and UI
 **************