[ID]
SCRIPT_NAME: sonarr_postprocess_v1.32_fix_append.sh
PROJECT: SEED_MOVER

[ROLE]
- Hook post-traitement Sonarr exécuté lors de l’import ou de l’upgrade d’un épisode.
- Enregistre l’association entre le fichier source issu du client BitTorrent et le fichier final que Sonarr place dans sa bibliothèque.
- Alimente le pipeline seed_mover en ajoutant une entrée SONARR|SRC|DST dans le mapping partagé et en créant un fichier .state permettant à synomap d’effectuer les opérations de relink/cleanup.

[CONTEXT]
- Déclenché automatiquement via “Custom Script” Sonarr v3/v4, avec injection des variables d’environnement SONARR_* dans un conteneur où /scripts et /data sont montés par Docker.
- Environnement requis : /bin/sh + outils POSIX (mkdir, chmod, chown, date, basename, tr). Aucun accès réseau.
- Dossiers utilisés (créés si nécessaires) :
  - mapping_entries.txt dans /scripts/synomap/,
  - fichiers .state dans /scripts/state/,
  - logs dans /scripts/synomap/log/.
- Lecture exclusive des variables Sonarr :
  - SONARR_EPISODEFILE_PATH (DST final),
  - SONARR_EPISODEFILE_SOURCEPATH (SRC original, si fourni),
  - SONARR_DOWNLOAD_CLIENT_CATEGORY,
  - SONARR_EVENTTYPE.
- Règle SRC :
  - priorité au chemin fourni par Sonarr (SONARR_EPISODEFILE_SOURCEPATH),
  - sinon reconstruction via /data/torrents/completed/<cat>/<basename> selon la convention interne seed_mover (règle métier, non optionnelle).
- Mécanisme de verrouillage : utilisation de ${MAP}.lockdir pour sérialiser les écritures dans mapping_entries.txt et éviter la corruption en accès concurrent.
- Aucun appel vers des services externes (qBittorrent, Radarr, Synology). Ce script produit uniquement les données pour les étapes synomap ultérieures.

[INPUTS]
- Aucun argument CLI.
- Variables d’environnement :
  - LOG : chemin du log (défaut : /scripts/synomap/log/sonarr_postprocess.log).
  - MAP : fichier de mapping (défaut : /scripts/synomap/mapping_entries.txt).
  - STATE_DIR : répertoire des .state (défaut : /scripts/state).
  - LOCKDIR : répertoire de lock (défaut : ${MAP}.lockdir).
  - MAP_OWNER / MAP_GROUP : réglage optionnel des permissions du mapping.
  - Variables Sonarr (ou minuscules) : SONARR_EVENTTYPE, SONARR_EPISODEFILE_PATH, SONARR_EPISODEFILE_SOURCEPATH, SONARR_DOWNLOAD_CLIENT_CATEGORY.
- Priorité :
  1. Variables Sonarr (toujours prioritaires car injectées par Sonarr),
  2. Variables d’environnement définies par wrapper/systemd,
  3. Valeurs internes par défaut du script.
- Contraintes :
  - Les chemins doivent correspondre aux volumes montés dans Sonarr (attention aux remappages /data et /scripts selon le docker-compose).
  - mapping_entries.txt est append-only : aucune déduplication, d'où l’importance de LOCKDIR.

[OUTPUTS]
- Ajout d’une ligne SONARR|<SRC>|<DST> dans MAP, sous verrou LOCKDIR.
- Création d’un fichier STATE_DIR/<basename>.state contenant CAT=SONARR, SRC, DST, WHEN (timestamp ISO8601).
- Journalisation append dans LOG. Pas de log fichier supplémentaire ; stdout peut être capturé par Sonarr si configuré, mais n'est pas utilisé comme canal principal.

[FAILURE_MODES]
- Variable critique manquante ou vide (ex. SONARR_EPISODEFILE_PATH) → set -eu → exit ≠ 0 et aucune écriture.
- Lockdir indisponible après 25 tentatives (5 secondes cumulées) → WARN dans LOG, exit 0 (skip sécurisé).
- Échec chmod/chown ou écriture log → ignorés via “|| true” : best effort.
- Échec mkdir -p sur LOG, MAP ou STATE_DIR → exit ≠ 0 (set -e).
- Reconstruction SRC impossible (ni SONARR_EPISODEFILE_SOURCEPATH ni chemin reconstruit valide) → skip avec trace dans LOG.
- Exit codes :
  - ≠ 0 : erreurs structurelles (env critique manquante, dossiers inaccessibles),
  - = 0 : skips contrôlés (lock indisponible, reconstruction SRC impossible mais non fatale).

[HISTORIQUE]
- v1.32 “fix append” : stabilisation du mécanisme LOCKDIR, introduction systématisée des fichiers .state et prise en charge de Sonarr v4 (variantes minuscules des variables).
- Hérite des versions 1.31 et antérieures sans gestion robuste du mapping en accès concurrent.
- À COMPLÉTER via historique Git pour les dates exactes et les modifications incrémentales.