SYNOMAP — DOCUMENTATION MÉTIER V1 Bloc ABC (flux normal) — Document de cadrage complet (Long Form) Version : 1.0 Date : 2025-11-16 Portée : Fonctionnement métier complet du module Synomap dans son périmètre “flux normal” Audience : Chef de projet, architecte fonctionnel, développeur backend, futur intégrateur API/WebUI ------------------------------------------------------------------------------- 0. INTRODUCTION ------------------------------------------------------------------------------- 0.1. Contexte général Synomap est un composant logiciel destiné à orchestrer la migration progressive et déterministe des torrents gérés dans un environnement OMV (OpenMediaVault) vers une infrastructure NAS Synology. Il agit en tant que couche fonctionnelle supérieure au-dessus de qBittorrent et du système de fichiers, et garantit qu’un torrent atteint un état stable, cohérent et définitif une fois les règles métier remplies. Le système existe pour répondre à un besoin simple et récurrent : libérer l'espace sur OMV, stabiliser les seeds, éviter les manipulations manuelles, et assurer une continuité de service malgré les différences de comportements entre OMV et Synology. Synomap n’est pas un moteur de téléchargement. C’est un orchestrateur métier qui pilote les actions de post-process, de vérification et de migration finale. Ce document couvre le périmètre fonctionnel du flux dit « normal » (états A, B, C). Les comportements en cas d’erreurs, de divergences ou d’anomalies feront l’objet de documents ultérieurs (v2, v3…). 0.2. Vision long terme À terme, Synomap sera intégré dans une interface web centralisée, offrant : - supervision du parc de torrents, - pilotage graphique de l’état, - API REST pour interactions externes, - contrôle du comportement métier (seuils de seed, règles d’évolution), - diagnostics et auto-cicatrisation. Pour cela, la présente documentation métier vise à poser des fondations claires, stables, compréhensibles et indépendantes des choix techniques courants (shell, docker, etc.). ------------------------------------------------------------------------------- 1. OBJECTIFS MÉTIER DE SYNOMAP ------------------------------------------------------------------------------- 1.1. Objectif principal L’objectif métier n°1 de Synomap est : « Devenir la source de vérité définitive des torrents en transférant progressivement la responsabilité de stockage et de seeding vers le NAS Synology, de manière fiable, contrôlée, automatique et sans risque pour les données. » 1.2. Objectifs secondaires - Réduire la charge de stockage sur OMV en migrant les contenus mûrs. - Préserver l’intégrité des torrents en créant des miroirs via hardlinks. - Éviter toute intervention manuelle sur les torrents une fois la boucle en place. - Centraliser la logique métier des migrations. - Assurer la cohérence entre les différents éléments : OMV, qBittorrent, Synology. - Marquer fonctionnellement chaque torrent selon son état métier. - Garantir qu’un torrent « finalisé » ne subisse aucune manipulation ultérieure. 1.3. Stratégie de migration Le pivot métier majeur est la stratégie dite : S2_SYNO_CENTRIC C’est-à-dire : - La destination finale d’un torrent est toujours Synology. - OMV est un nœud de passage temporaire. - Un torrent ne peut être considéré « stable » qu’une fois migré sur Synology. ------------------------------------------------------------------------------- 2. DÉFINITIONS MÉTIER ------------------------------------------------------------------------------- 2.1. Torrent géré Un torrent est « géré par Synomap » lorsqu’il possède une entrée valide dans le fichier mapping_entries.txt contenant : - un chemin source (SRC_ABS) sur OMV, - un chemin destination (DST_ABS) sur Synology. 2.2. Miroir Synology Copie des fichiers d’un torrent créée via hardlink sur le NAS, permettant : - le seeding depuis Synology (cible finale), - la préservation du ratio via qBittorrent, - la disponibilité des fichiers pour Plex, Jellyfin, etc. 2.3. Seeding time Durée pendant laquelle un torrent a seedé. En v1 : - seul le temps est pris en compte, - le ratio est ignoré, - la condition métier de maturité dépend uniquement de ce temps. 2.4. États métier ABC constitue le cycle de vie complet d’un torrent en flux normal : A — Torrent découvert, miroir absent B — Miroir créé, torrent pas encore migré vers Synology C — Torrent migré, confirmé, stable, point fixe ------------------------------------------------------------------------------- 3. DESCRIPTION MÉTIER DES ÉTATS ------------------------------------------------------------------------------- 3.1. État A — « Nouveau, mappé, non préparé » Description : Le torrent a été détecté par Synomap via le mapping. Il est encore physiquement situé dans OMV, et aucun miroir Synology n’existe. Critères étatiques : - mapping présent - SRC présent - DST absent - save_path sur OMV (/data) - aucun tag SYNO_OK Objectif métier : - préparer le torrent en créant son miroir Synology. 3.2. État B — « Miroir créé, en attente de maturité » Description : Le miroir Synology existe, mais le torrent n’est pas encore suffisamment mature pour être migré vers Synology en tant que source de vérité. Critères : - mapping présent - SRC présent - DST présent - save_path sur /data - seed pas encore suffisant OU migration non encore effectuée - tag SYNO possible Objectif métier : - attendre la condition métier (maturité de seed) - préparer la migration finale 3.3. État C — « Migré, confirmé, stable » Description : Le torrent a atteint la maturité métier attendue : - miroir existant, - migration qB réussie, - tag SYNO_OK présent. Critères : - mapping présent - SRC présent - DST présent - save_path = Synology - seed OK - tag = SYNO_OK Objectif métier : - considérer ce torrent comme définitivement stabilisé. - ne plus rien modifier. ------------------------------------------------------------------------------- 4. RÈGLES MÉTIER GÉNÉRALES ------------------------------------------------------------------------------- 4.1. Priorité à la vérité terrain Synomap observe toujours la réalité du système : - disparition de fichiers, - changements manuels, - incohérences éventuelles. Il ne se base jamais sur des hypothèses, mais sur des mesures temps réel du FS et de qBittorrent. 4.2. Idempotence métier Un torrent en état C ne doit générer : - aucun appel qBittorrent, - aucune création de fichier, - aucune tentative de migration, - aucun changement de tag. Il est considéré comme scellé. 4.3. Opportunisme métier Si un torrent est déjà suffisamment seedé lors de sa découverte (état A), Synomap peut effectuer le cycle complet A→B→C en un seul run. 4.4. Rôle métier des tags SYNO : - indique que le miroir existe et que Synomap a pris en charge le torrent. SYNO_OK : - indique que la migration vers Synology est confirmée, - marqueur final de conformité métier. ------------------------------------------------------------------------------- 5. CYCLE DE VIE MÉTIER D’UN TORRENT ------------------------------------------------------------------------------- 5.1. Découverte (A) Le torrent est identifié dans mapping_entries.txt. OMV est la source unique. Aucune action n’a encore été menée. 5.2. Préparation (A→B) Synomap crée les miroirs Synology (hardlinks). Si la création échoue, le torrent reste en A (ou bascule en erreur dans les futurs docs). Une fois les miroirs créés : - SYNO peut être posé, - le torrent est prêt pour la migration. 5.3. Maturation (B) Le torrent est en attente : - du seeding time suffisant, - ou d’une migration réussie. Tant que le torrent n’est pas mûr, Synomap n’intervient plus, préservant les ressources et évitant les actions inutiles. 5.4. Migration (B→C) Une fois que la condition métier de seed est remplie : - Synomap ordonne la migration à qBittorrent (setLocation), - vérifie que qB est cohérent via relecture, - applique SYNO_OK si tout est conforme. 5.5. Stabilisation (C) Le torrent ne sera plus jamais modifié. Il devient la source de vérité définitive pour les usages Plex/Jellyfin/etc. ------------------------------------------------------------------------------- 6. COMPORTEMENTS ATTENDUS ------------------------------------------------------------------------------- 6.1. Déterminisme Synomap doit produire les mêmes décisions pour un même état de terrain. 6.2. Tolérance aux runs multiples Relancer la boucle plusieurs fois ne doit jamais produire d’effets négatifs ou “en double”. 6.3. Préservation des données Aucun déplacement destructif. La logique se base sur les hardlinks. 6.4. Respect de qBittorrent Un seul appel setLocation par torrent/run, lecture de confirmation obligatoire. 6.5. Non-ingérence sur les torrents non gérés Synomap n’interfère jamais avec les torrents qui ne figurent pas dans son mapping. ------------------------------------------------------------------------------- 7. LIMITES MÉTIER V1 ------------------------------------------------------------------------------- Cette version du document ne couvre pas : - les ambiguïtés de mapping, - les catégories inconnues (“unknown_category”), - les pertes de miroirs, - les mismatches qB persistants, - les ratios de seed, - les torrents orphelins (fichiers sans entrée qB ou inversement), - la supervision d’erreurs répétées. Ces points seront spécifiés dans les documents : - v2 — erreurs de mapping, - v3 — incohérences FS (miroirs cassés), - v4 — mismatches qB, - v5 — intégration du ratio. ------------------------------------------------------------------------------- 8. VISION LONG TERME ------------------------------------------------------------------------------- 8.1. Interface Web Synomap sera pilotable via une interface web proposant : - vue globale des torrents, - état ABC et futurs états, - actions managées, - logs et notifications. 8.2. API REST Les états ABC feront l’objet d’expositions API simples : - GET /torrent/:id/state - GET /torrent/:id/details - POST /torrent/:id/refresh - future: /torrent/:id/recover 8.3. Résilience et auto-cicatrisation Synomap aura la capacité de : - détecter les incohérences, - proposer un plan de correction, - stabiliser automatiquement les états, - produire un rapport métier clair. ------------------------------------------------------------------------------- FIN DU DOCUMENT -------------------------------------------------------------------------------