[ID]
SCRIPT_NAME: daily_qbittorrent_update_v1.32c_synomap.sh
PROJECT: SEED_MOVER

[ROLE]
But métier (en 2–3 phrases max) :
- Automatise la finalisation quotidienne des torrents achevés dans qBittorrent en les filtrant par catégories approuvées et par ancienneté.
- Pour chaque torrent admissible, crée ou rafraîchit un hardlink vers l’arborescence Synology montée localement, repositionne la sauvegarde qBittorrent, puis applique le tag SYNO dans qBittorrent pour marquer qu’il est traité.

[CONTEXT]
- Environnement cible : serveur OMV hébergeant qBittorrent, avec l'arborescence Synology montée sous /syno/... via NFS/SMB.
- Localisation habituelle du script : /srv/dev-disk-by-uuid-.../data/scripts (selon déploiement).
- Dépendances système : shell POSIX (/bin/sh), curl, jq, utilitaires classiques Linux (stat, ln, mkdir).
- Hypothèse d’utilisation : exécuté via tâche cron quotidienne ou via un orchestrateur externe (wrapper .sh ou systemd timer).
- Lit le fichier d’environnement SYNO_ENV (par défaut synomap.env) pour charger QB_URL, QB_USER, QB_PASS et autres paramètres.
- Consomme le fichier de mapping MAP_FILE (par défaut /data/scripts/mapping_entries.txt) contenant des lignes séparées par “|” (ID | SRC | DST).
- N’écrit pas dans le fichier de mapping : le script crée des répertoires sous DEST_ROOT et génère des hardlinks, puis pilote qBittorrent via API HTTP.

[INPUTS]
- Paramètres CLI :
  - --allow "cat1 cat2" : liste d’espaces des catégories autorisées (défaut : "sonarr radarr").
  - --min-age SEC : âge minimal (en secondes) depuis completion_on ou added_on (défaut : 259200 = 3 jours).
  - --dest-root PATH : racine cible des hardlinks (défaut : /syno/torrents/completed).
  - --limit N : traite au maximum N torrents admissibles (0 = illimité).
  - --map-file PATH : fichier de mapping SRC→DST.
  - --write : en son absence, le script opère strictement en mode dry-run (aucune création de répertoires, aucun hardlink).
  - --yes : indicateur reconnu mais non utilisé dans cette version.
- Variables d’environnement :
  - SYNO_ENV : chemin vers un .env contenant QB_URL, QB_USER, QB_PASS, etc.
  - QB_URL, QB_USER, QB_PASS : endpoint et credentials qBittorrent (obligatoires).
  - ALLOW, MIN_AGE, DEST_ROOT, LIMIT, MAP_FILE : surcharges possibles des valeurs par défaut.
- Priorité de résolution :
  1. Options CLI (priorité la plus forte)
  2. Variables d’environnement
  3. Valeurs par défaut internes du script
- Contraintes :
  - mapping_entries.txt doit contenir des chemins absolus cohérents avec ceux renvoyés par qBittorrent.
  - Les chemins source et DEST_ROOT doivent résider sur le même device pour autoriser les hardlinks (ln).

[OUTPUTS]
- Fichiers et répertoires :
  - Création éventuelle de DEST_ROOT/<cat> (si --write).
  - Hardlinks sous DEST_ROOT/<cat>/<top_file> pointant vers la destination calculée.
- Actions qBittorrent (si --write) :
  - Déplacement du save_path (API torrents/setLocation).
  - Ajout du tag SYNO.
  - Recheck automatique si un nouveau lien est posé.
- Journaux :
  - Le script n’écrit aucun fichier log. Toute la journalisation passe par stdout.
  - Les préfixes SKIP:*, MAPMISS, CROSS-DEV, etc. facilitent l’analyse via syslog/cron.

[FAILURE_MODES]
- QB_URL / QB_USER / QB_PASS absents → erreur immédiate, message explicite et exit code ≠ 0.
- MAP_FILE introuvable → arrêt (“MAP_FILE not found”) avec exit code ≠ 0.
- Échec d’authentification qBittorrent → erreur “qB login failed”, exit code ≠ 0.
- Absence de timestamps (completion_on / added_on) → torrent ignoré (SKIP:no_time).
- Torrents trop récents → SKIP:age.
- Catégorie non autorisée → SKIP:category.
- Chemin TOP introuvable ou mapping absent → MAPMISS.
- Volumes source/destination différents → CROSS-DEV (hardlink impossible) → torrent ignoré.
- Échec stat sur les chemins → NOSTAT.
- Erreurs API qBittorrent (setLocation/addTags/recheck) :
  - Non gérées explicitement ; elles apparaissent via curl si verbeux.
  - Le script continue en mode “best effort”.
- Exit codes :
  - Exit ≠ 0 pour les erreurs bloquantes (env manquante, mapping absent, login KO).
  - Exit = 0 même si certains torrents sont ignorés (skip contrôlé).

[HISTORIQUE]
- 2025-??-?? : Création/ajustement de la version v1.32c (issue du script historique daily_qbittorrent_update).
- v1.31 (2025-11-10) → v1.32c : refactor mineur ; détails à compléter via historique Git.
- À COMPLÉTER : compléter les dates et changements précis lorsque le repo disposera d’un historique Git plus complet.