[ID]
SCRIPT_NAME: synomap_apply_from_plan_v1.2.6.sh
PROJECT: SEED_MOVER

[ROLE]
- Interpréteur de plan synomap "classique" : lit un plan généré par daily_qbittorrent_update et applique (ou simule) les opérations nécessaires pour synchroniser les torrents vers l’arborescence Synology.
- En mode WRITE, crée les hardlinks manquants, ajuste le save_path des torrents via l’API qBittorrent, applique le tag SYNO et déclenche un recheck lorsque de nouveaux liens sont posés.
- Sert d’étape intermédiaire entre la génération du plan et les phases de cleanup OMV.

[CONTEXT]
- Conçu pour tourner sur le serveur OMV hébergeant à la fois :
  - les volumes de données /data/...,
  - les points de montage Synology /syno/...,
  - et le conteneur qBittorrent.
- Dépendances système : /bin/sh, ln, mkdir, stat, sed, grep, cut, curl (API qBittorrent). Aucun awk n’est requis (contrainte POSIX stricte).
- Peut charger un fichier d’environnement SYNO_ENV (synomap.env) pour initialiser QB_URL, QB_USER, QB_PASS, DEST_ROOT, UMASK et autres paramètres globaux.
- Structure du plan consommé :
  - entête contenant un hash (40 hex) et des métadonnées (dest_dir=..., flags, etc.),
  - lignes d’action du type :
      plan: ln 'SRC' -> 'DST'
  - les blocs marqués SKIP ou [NOSTAT] sont ignorés.
- Toutes les interactions réseau sont limitées à l’API HTTP de qBittorrent (setLocation, addTags, recheck).

[INPUTS]
- Paramètres CLI :
  - PLAN       : chemin du fichier plan (obligatoire).
  - --write    : active les modifications réelles (sinon, PREVIEW pur).
- Variables d’environnement :
  - SYNO_ENV   : chemin d’un .env chargé pour initialiser QB_URL, QB_USER, QB_PASS, DEST_ROOT, UMASK.
  - QB_URL     : URL de l’API qBittorrent.
  - QB_USER    : utilisateur API.
  - QB_PASS    : mot de passe API.
  - DEST_ROOT  : fallback si le plan ne fournit pas dest_dir.
  - UMASK      : umask utilisée lors des mkdir/ln en mode WRITE.
- Priorité :
  1. Valeurs issues du plan (dest_dir, etc.),
  2. Variables d’environnement (via SYNO_ENV ou export),
  3. Valeurs par défaut internes au script.
- Format du plan :
  - chaque bloc hash regroupe un torrent,
  - chaque ligne plan: ln 'SRC' -> 'DST' décrit un lien à créer,
  - les lignes non conformes ou commentées sont ignorées.

[OUTPUTS]
- Mode PREVIEW (par défaut) :
  - affiche les actions simulées :
      mkdir -p DEST_DIR
      ln 'SRC' 'DST'
      qB:setLocation HASH DEST_DIR
      qB:addTags HASH SYNO
      qB:recheck HASH
  - un récapitulatif du nombre d’items traités est présenté à la fin.
- Mode WRITE (--write) :
  - crée réellement les répertoires DEST_DIR (mkdir -p),
  - crée les hardlinks (ln SRC DST),
  - appelle l’API qBittorrent :
      /torrents/setLocation (vers DEST_DIR),
      /torrents/addTags (tag SYNO),
      /torrents/recheck (uniquement si un nouveau lien a été posé),
  - la trace d’exécution reste sur stdout ; aucun log dédié n’est créé.
- Le script ne modifie pas le fichier mapping_entries.txt : il travaille uniquement à partir du plan fourni.

[FAILURE_MODES]
- PLAN non fourni ou illisible → message ERR: plan not found et exit ≠ 0.
- Parsing SRC/DST impossible sur une ligne → ligne ignorée (skip local) sans interrompre le reste du plan.
- mkdir/ln échouent (droits, cross-device, chemin invalide) :
  - journalisation “ERR ln” ou “SKIP link”,
  - recheck qB n’est pas déclenché pour ces entrées,
  - le traitement continue sur les lignes suivantes (best effort).
- Authentification qBittorrent :
  - si login échoue, COOKIE reste vide,
  - les appels API sont alors no-op (ou simplement skip) sans arrêter le script.
- curl vers setLocation/addTags/recheck :
  - exécutés en best effort (souvent protégés par “|| true”),
  - les erreurs réseau n’arrêtent pas l’exécution globale.
- Exit code global :
  - ≠ 0 uniquement en cas d’erreur d’entrée (plan manquant/illisible ou usage incorrect),
  - 0 même si certaines opérations individuelles échouent (modèle best effort).

[OBSERVATIONS & LIMITES]
- L’exécution se fait en boucle simple sur les lignes du plan, sans mécanisme de séquencement strict entre les appels qBittorrent :
  - pas de pause forcée,
  - pas de contrôle explicite des états intermédiaires (checking, moved, etc.),
  - ce qui peut exposer le pipeline à des conditions de course sur certains environnements chargés.
- Pas de gestion avancée des "sidecars" (.nfo, .srt, etc.) : seule la logique SRC→DST basique est appliquée.
- Aucune limitation de débit ni de parallelisme côté qBittorrent (tout passe en séquence, mais sans attente fine des transitions internes).
- L’absence de log fichier rend l’analyse post-mortem plus délicate en cas d’incident.

[HISTORIQUE]
- v1.2.6 :
  - version POSIX sh only, explicitement documentée comme sans awk,
  - restructuration du parsing du plan par rapport aux versions ≤1.2.5,
  - affinage de la logique de recheck (uniquement si un nouveau lien a été créé).
- Utilisée comme moteur d’application principal dans le pipeline synomap 2024–2025 avant l’introduction de la version “sequential”.
- Des comportements de type "race" entre commandes qBittorrent ont été observés en production, ce qui a motivé la conception de la lignée 1.6.x_sequential.
- Dates et commits précis à confirmer via l’historique Git.