====== Mise à jour de TaxRef ======

Présentation des étapes pour migrer TaxRef malgré l'utilisation en production d'une version ancienne de TaxHub (v1.9.4). Réaliser d'abord toutes ces étapes en local avant de les reproduire en production.

<color #ed1c24>**Pré-requis**</color> : la base de données ne doit pas avoir évolué... Sinon, il faut vérifier que les modifications sont compatibles avec la branche ''feat/sinp''. Le code SQL de migration peut être ajouté au script SQL ''pre_detection.sql'' (voir ci-dessous). Rechercher les éventuelles évolutions dans [[https://github.com/PnX-SI/TaxHub/releases | la liste des releases]].

**Migration de TaxRef en version** :
  * v17 depuis v16 : évolution de la base impactant la migration entre la v1.9.4 et la v1.14.0 => nécessite de créer la table ''taxonomie.t_meta_taxref'' dans script SQL de pré-détection.
  * v16 depuis v15 : pas d'évolution de la base impactant la migration entre la v1.9.4 et la v1.11.3.

===== Installation de la dernière version de TaxHub =====

  * Se connecter sur l'hôte ''web-srv''
  * Se placer dans le dossier ''~/www/'' : <code bash>cd ~/www/</code>
  * Cloner le dépôt Taxhub : <code bash>git clone https://github.com/PnX-SI/TaxHub.git taxhub.taxref_v17</code>
    * Mettre à jour les sous-module si utilisation en local en mode "dev" : <code bash>cd ~/www/taxhub.taxref_v17 ; git submodule init; git submodule update</code>
  * Se placer dans le dossier cloné : <code bash>cd ~/www/taxhub.taxref_v17</code>
  * Copier les fichiers de configuration : <code bash>
cp settings.ini.sample settings.ini
cp apptax/config.py.sample apptax/config.py
</code>
    * Éditer le fichier ''settings.ini'' : <code bash>vi settings.ini</code>
      * Modifier les 3 paramètres suivant :<code properties>
db_host=10.0.1.20

# Database name
db_name=geonature2db
 
# Database owner username
user_pg=geonatadmin
 
# Database owner password
user_pg_pass=<geonatadmin-password>
</code>
    * Éditer le fichier ''config.py'' : <code bash>vi apptax/config.py</code>
      * Modifier les 2 paramètres suivant :<code properties>
SQLALCHEMY_DATABASE_URI = "postgresql://geonatadmin:<geonatadmin-password>@10.0.1.20:5432/geonature2db"
SECRET_KEY = '<generate-super-secret-key-with-uuid>'
</code>
  * Lancer l'installation du ''venv'' : <code bash>./install_app.sh</code>
  * Activer le ''venv'' : <code bash>source venv/bin/activate</code>
  * Lancer l'import de TaxRef : <code bash>flask taxref migrate-to-v17 import-taxref-v17</code>
    * Pas certain que cela soit utile si on utilise le scripts SQL ''pre_detection.sql'' mais on peut lancer la commande suivante pour tester d'éventuel changement réalisé dans la base : <code bash>flask taxref migrate-to-v17 test-changes-detection</code>
  * Lors de la réalisation des tests en local, préparer une nouveau dossier de version de TaxRef sur le dépôt ''sinp-<region>-data'' : 
    * Voir : [[https://github.com/cbn-alpin/sinp-paca-data/tree/main/taxref|PACA]] ou [[https://github.com/cbn-alpin/sinp-aura-data/tree/main/taxref|AURA]]
    * Copier les fichiers csv générés par le script précédent dans le dossier ''taxref/v17/csv/'' du dépôt.
    * Créer les scripts SQL qui permettront la migration dans le dossier ''taxref/v17/sql/''. Se baser sur la version précédente de TaxRef pour avoir des exemples de script SQL qu'il faudra adapté aux informations fournies dans les fichiers CSV.
  * Lors de la mise en production, récupérer les fichiers SQL permettant la migration :<code bash>
wget https://raw.githubusercontent.com/cbn-alpin/sinp-<region>-data/main/taxref/v<version>/sql/pre_detection.sql
wget https://raw.githubusercontent.com/cbn-alpin/sinp-<region>-data/main/taxref/v<version>/sql/post_detection.sql
</code>
  * Lancer la migration de TaxRef : <code bash>flask taxref migrate-to-v17 apply-changes --script_predetection ./pre_detection.sql --script_postdetection ./post_detection.sql</code>
    * **NOTE** : pour une raison inconnue, dans le cas du SINP AURA, il m'a fallu lancer à 2 reprises cette  commande. Après l'import, 14 conflits sont indiqués. Après le premier lancement, il reste 8 conflits. Après le second, cela tombe 0 et la migration s'effectue correctement...
  * Vérifier que la nouvelle version de TaxRef a bien été migré correctement ! Vérifier qu'un cd_nom disparu dans la v17 n'est plus présent dans votre table ''taxonomie.taxref'' et qu'un nouveau cd_nom ajouté à partir de la v17 s'y trouve bien.
  * <color /#fff200>Si nécessaire (avant la v17)</color>, lier à nouveau les statuts de protection aux zones géographiques : <code bash>flask taxref link-bdc-statut-to-areas</code>
    * Désactiver à nouveau les textes de la BDC Statut qui ne vous sont pas nécessaire à votre installation :
      * SINP PACA : <code bash>psql -h localhost -U geonatadmin -d geonature2db -f ~/data/db-geonature/data/sql/04_disable_status_text.sql</code>
      * SINP AURA : <code bash>psql -h localhost -U geonatadmin -d geonature2db -f ~/data/db-geonature/data/sql/003_disable_status_text.sql</code>
    * Ajouter les éventuels nouveaux textes de cette nouvelle version de Taxref à ne pas prendre en compte à votre script ''04_disable_status_text.sql''.
  * <color /#fff200>Vérifier que la nouvelle version de la BDC Statuts a bien été migrée correctement !</color> Il faut s'assure que les textes avec le champ ''enable'' à ''true'' dans la table ''taxonomie.bdc_statut_text'' correspondent bien à la France métropolitaine, à la région ou aux département qui concernent le SINP. Il peut s'avérer nécessaire de relancer le script SQL de sélection des textes du SINP (dépôt ''sinp-<region>-data/db-geonature/data/sql/..._disable_status_text.sql'') pour activer les nouveaux textes.
    * Si pour une raison ou une autre, il est nécessaire de recharger la BDC statut, il est possible de suivre la démarche définie dans [[https://github.com/PnX-SI/TaxHub/issues/501|le ticket #501 de TaxHub]]. Il faudra juste modifier l'URL de téléchargement des fichiers zip et la version de TaxRef si nécessaire.
===== Détail utilisation du script "flask taxref migrate-to-vXX" =====
  * Ressource : https://github.com/PnX-SI/TaxHub/tree/master/apptax/taxonomie/commands/migrate_taxref
  * Voir aussi le ticket corrigeant des problèmes dans la migration et la détection des conflits : https://github.com/PnX-SI/TaxHub/issues/527
  * Lancer le script : ''flask taxref migrate-to-v17 import-taxref-v17''
    * La récupération de toutes les informations permettant la migration définitive vers la dernière version de TaxRef nécessite de lancer plusieurs fois ce script. Des fichiers de sortie différents seront ainsi générés.
  * Le fichier [[https://github.com/cbn-alpin/sinp-aura-data/tree/main/taxref/v17/csv| liste_changements.csv]] est généré. Le charger [[https://docs.google.com/spreadsheets/d/1jnlyju6K06OBRG5rKUpEaRwoA09ScZBTrme8UcabvQ8/edit?usp=sharing| dans le Drive]]. Figer la ligne 1 et y ajouter des filtres.
    * Dans ce fichier tous les changements ne sont pas à corriger. À l'aide des filtres de la ligne 1, afficher seulement les lignes dont la colonne ''action'' afficher seulement lignes commençant par "Conflicts with attributes". Sélectionner ces lignes et les colorer en rouge.
    * Avec la colonne ''f_cd_ref'' trier les résultat de A à Z : cela va regrouper les lignes par f_cd_ref et il sera plus simple de repérer les cd_ref à remplacer.
    * La colonne ''f_cd_ref'' indique le cd_ref retenu et la colonne ''i_cd_ref'' indique le cd_ref remplacé. Pour chaque ''f_cd_ref'' on va trouver une ligne avec la même valeur dans ''i_cd_ref'' et dans ''f_cd_ref'', elle est à ignorer. Il faut repérer les lignes où ils sont différents. 
      * Pour chaque ligne :
        * récupérer le ''i_cd_ref'' et s'en servir pour [[https://github.com/cbn-alpin/sinp-aura-data/blob/main/taxref/v17/sql/pre_detection.sql#L124-L128| supprimer les attributs correspondant]] de la table ''cor_taxon_attributs'' dans le script SQL de prédétection.
        * si la colonne ''media_nb'' indique une valeur non NULL, il faut aussi [[https://github.com/cbn-alpin/sinp-aura-data/blob/main/taxref/v17/sql/pre_detection.sql#L133-L163| remplacer l'attribution du cd_ref pour les médias correspondant]] dans le script SQL de prédétection en récupérant les valeurs des colonnes ''i_cd_ref'' et ''f_cd_ref''. Si plusieurs ''i_cd_ref'' sont fusionnés dans le même ''f_cd_ref'', [[https://github.com/cbn-alpin/sinp-aura-data/blob/main/taxref/v17/sql/pre_detection.sql#L146-L147| utiliser une clause IN]].
  * Relancer le script en essayant d'appliquer les changements ''flask taxref migrate-to-v17 apply-changes'' et en indiquant cette fois l'utilisation des fichiers SQL de pré-détection et post-détection : ''%%flask taxref migrate-to-v17 apply-changes --script_predetection ./pre_detection.sql --script_postdetection ./post_detection.sql%%''
  * Le fichier [[https://github.com/cbn-alpin/sinp-aura-data/blob/main/taxref/v17/csv/missing_cd_nom_into_database.csv| missing_cd_nom_into_database.csv]] est généré. Le charger [[https://docs.google.com/spreadsheets/d/1jnlyju6K06OBRG5rKUpEaRwoA09ScZBTrme8UcabvQ8/edit?usp=sharing| dans le Drive dans un second onglet]]. Figer la ligne 1 et y ajouter des filtres.
    * La colonne ''table_name'' permet de filtrer sur la  table :
      * ''gn_synthese.synthese'' les changements à y effectuer :
        * les lignes ayant la valeur "2" ou "3" dans la colonne ''cd_raison_suppression'' nécessitent de mettre à NULL le champ ''cd_nom'' dans la table ''gn_synthese.synthese'' à l'aide de [[https://github.com/cbn-alpin/sinp-aura-data/blob/main/taxref/v17/sql/pre_detection.sql#L59-L66| requêtes SQL qui seront à ajouter dans le fichier ''pre_detection.sql'']].
        * les lignes ayant la valeur "1" dans la colonne ''cd_raison_suppression'' nécessitent de remplacer la valeur du champ ''cd_nom'' dans la table ''gn_synthese.synthese'' à l'aide de [[https://github.com/cbn-alpin/sinp-aura-data/blob/main/taxref/v17/sql/pre_detection.sql#L68-L72| requêtes SQL qui seront à ajouter dans le fichier ''pre_detection.sql'']].
      * ''taxonomie.bib_noms'' les changements à y effectuer :
        * quelques soit les valeurs de la colonne ''cd_raison_suppression'', il faudra supprimer les lignes correspondantes de la table ''cor_nom_liste'' et ''bib_noms'' à l'aide de [[https://github.com/cbn-alpin/sinp-aura-data/blob/main/taxref/v17/sql/pre_detection.sql#L89-L117| requêtes SQL qui seront à ajouter dans le fichier ''pre_detection.sql'']].
        *  les lignes ayant la valeur "1" dans la colonne ''cd_raison_suppression'' nécessitent de remplacer la valeur du champ ''cd_nom'' dans la table ''taxonomie.bib_noms'' à l'aide de [[https://github.com/cbn-alpin/sinp-aura-data/blob/main/taxref/v17/sql/pre_detection.sql#L82-L84| requêtes SQL qui seront à ajouter dans le fichier ''pre_detection.sql'']]. Si [[https://github.com/cbn-alpin/sinp-aura-data/blob/main/taxref/v17/sql/pre_detection.sql#L85-L86| les requêtes de mise à jour]] pose problème [[https://github.com/PnX-SI/TaxHub/issues/495| vis à vis du maintient temporaire de l'ancienne version de TaxRef]], il est possible d'ajouter les cd_nom correspondant à [[https://github.com/cbn-alpin/sinp-aura-data/blob/main/taxref/v17/sql/pre_detection.sql#L101| la liste des lignes à supprimer]] dans la table ''cor_nom_liste'' et [[https://github.com/cbn-alpin/sinp-aura-data/blob/main/taxref/v17/sql/pre_detection.sql#L115| des lignes à supprimer]] dans la table ''taxonomie.bib_noms''.
  * Lancer à nouveau le script en essayant d'appliquer les changements ''flask taxref migrate-to-v17 apply-changes'', normalement le script SQL ''pre_detection.sql'' devrait s'exécuter correctement mais le script ''post_detection.sql'' devrait générer des erreurs. En effet, ce script "post-détection" est exécuté avant d'avoir réaliser le changement de référentiel TaxRef, ainsi [[https://github.com/cbn-alpin/sinp-aura-data/blob/main/taxref/v17/sql/post_detection.sql#L4|la  réactivation]] des contraintes [[https://github.com/cbn-alpin/sinp-aura-data/blob/main/taxref/v17/sql/pre_detection.sql#L41| désactiver]] dans le script ''pre_detection.sql'' peuvent générer de nouvelles erreurs. Voir [[https://github.com/PnX-SI/TaxHub/issues/495| ticket #495]]. Il est donc nécessaire de [[https://github.com/cbn-alpin/sinp-aura-data/blob/main/taxref/v17/sql/pre_detection.sql#L44-L51| modifier temporairement TaxRef pour qu'ils ressemblent à la future version]] sur laquelle nous cherchons à migrer.
  * Si la base de données de TaxHub a évolué, il se peut que l'utilisation des scripts déclenche des erreurs. Il est alors nécessaire de rechercher dans les migrations Alembic de TaxHub le code SQL correspondant. Il est possible [[https://github.com/cbn-alpin/sinp-aura-data/blob/main/taxref/v17/sql/post_detection.sql#L3-L7| d'appliquer ce code à l'ajoutant au script "pre_detection.sql"]]. 
  * Enfin, lorsque nous avons réussi à appliquer sans erreur tous les changements ''flask taxref migrate-to-v17 apply-changes'', il devient possible de copier toutes les données dans une base de données GeoNature de la branche "develop" à l'aide du [[https://github.com/cbn-alpin/various-scripts/blob/main/geonature/copy/bin/copy_all.sh| script Bash copy_all.sh]].
    * Lors de l'exécution de ce script, de nouvelles erreurs peuvent être générée lors de la copie des données dans les tables ''gn_synthese.synthese'' et ''taxonomie.bib_noms''. Ces erreurs sont dues à l'absence de certaines lignes du TaxRef de la version générée avec la branche "develop". Pourquoi ces lignes n'ont elles pas été supprimées dans la version migrée ? Il est nécessaire de supprimer les lignes correspondant à ces cd_noms de la table [[https://github.com/cbn-alpin/sinp-aura-data/blob/main/taxref/v17/sql/pre_detection.sql#L65| gn_synthese.synthese]] et des tables [[https://github.com/cbn-alpin/sinp-aura-data/blob/main/taxref/v17/sql/pre_detection.sql#L102|cor_nom_liste]] et [[https://github.com/cbn-alpin/sinp-aura-data/blob/main/taxref/v17/sql/pre_detection.sql#L116| bib_noms]] du schéma taxonomie.
  * Dans le cas présent, migration des données SINP, il est également nécessaire de [[https://github.com/cbn-alpin/sinp-aura-data/blob/main/taxref/v17/sql/pre_detection.sql#L34-L38| désactiver les triggers]] gérant la mise à jour des dates et de la sensibilité de la table synthese dans le script "pre_detection.sql" puis de [[https://github.com/cbn-alpin/sinp-aura-data/blob/main/taxref/v17/sql/post_detection.sql#L3-L7| les réactiver]] dans le script "post_detection.sql".