====================================================================
STATE_SCHEMA.txt
Projet : Seedbox Manager
Objet  : Spécification du format des fichiers .state (ARR post-process)
Version : 1.0 (2025-10-12)
====================================================================

1) FINALITÉ
------------
Définir un schéma formel et stable pour les fichiers .state produits par
les post-process Sonarr/Radarr afin d’orchestrer la bascule NVMe→Synology
et toute action “daily”.

2) EMPLACEMENT & ENCODAGE
-------------------------
- Répertoire : /scripts/state/
- Extension  : .state
- Encodage   : UTF-8 (LF)
- Droits     : 0640 (lect/écr. service), pas de secrets

3) FORMAT GÉNÉRAL
-----------------
- Format : texte “clé=valeur”, une paire par ligne, sans guillemets.
- Lignes vides et commentaires (# ...) autorisés.
- Les caractères de fin de ligne CRLF sont interdits (LF uniquement).

4) CLÉS REQUISES (MINIMUM)
--------------------------
- kind        : string  ; {added|upgrade|test}
- added       : int     ; timestamp (epoch seconds) de l’ajout par ARR
- upgrade     : int     ; {0|1} – 1 si remplacement d’une version
- old         : string  ; chemin ancien (si upgrade=1), sinon vide
- new         : string  ; chemin cible normalisé après post-process

5) CLÉS COMPLÉMENTAIRES (RECOMMANDÉES)
--------------------------------------
- release     : string  ; nom de release tel que fourni par ARR
- category    : string  ; (ex. tv, movies, anim…)
- indexer     : string  ; nom logique interne (ex. autobrr)
- infohash    : string  ; hex 40 (si disponible)
- size_bytes  : int     ; taille totale (si connue)
- client      : string  ; ex. qbittorrent
- eventtype   : string  ; ex. Test (ARR), ImportCompleted…
- note        : string  ; message libre court (<= 200 chars)

6) CONTRAINTES & VALIDATIONS
----------------------------
- kind ∈ {added, upgrade, test}
- added > 1_600_000_000 (borne basse sanity)
- upgrade ∈ {0,1}
- new != "" (chemin absolu)
- encodage UTF-8 sans BOM
- Pas de guillemets, \r interdit, trim des espaces fin de ligne.

7) EXEMPLE
----------
kind=added
added=1728691200
upgrade=0
old=
new=/data/media/TV/Show.Name.S01E01.1080p
release=Show.Name.S01E01.1080p.WEB-DL
category=tv
indexer=autobrr
client=qbittorrent

8) ERREURS & JOURNAUX
---------------------
- Les parseurs doivent :
  * ignorer les lignes inconnues,
  * loguer toute clé manquante critique (kind, added, new),
  * refuser un fichier .state non conforme (code retour ≠ 0).
- Journal dédié : /scripts/log/state_parser.log

9) VERSIONNEMENT DU SCHÉMA
--------------------------
- SCHEMA_VERSION=1 (dans l’en-tête du .state facultatif)
- Toute évolution majeure → incrémenter et documenter ici.

====================================================================
FIN – STATE_SCHEMA.txt
====================================================================