Copies/Architecture.org

Architecture et conventions de développement

• API commune pour les scripts
• Convention des scripts standardisés
• Organisation du code
• État et exécution du GUI
• Invariants à préserver
• Règle de classement de la documentation

Ce document décrit les invariants techniques du projet. Il s'adresse aux développeurs et aux agents logiciels qui modifient le dépôt.

• Guide de démarrage
• Référence des étapes et des scripts

API commune pour les scripts

Le paquet copienator centralise les chemins d'une évaluation et les écritures JSON sûres. Un script ne devrait donc plus reconstruire les chemins partagés à la main :

from copienator import EvaluationWorkspace, atomic_write_json

workspace = EvaluationWorkspace("Interro")
atomic_write_json(workspace.correction_file, corrections)

EvaluationWorkspace.discover(path) retrouve également la racine d'une évaluation à partir d'un fichier ou d'un sous-dossier. Sa construction ne crée aucun fichier. La création explicite de .copienator/logs/ et .copienator/runs/ se fait avec workspace.ensure_control_directories(). Le chemin .copienator/state.sqlite3 est réservé à une future couche d'état transactionnelle.

atomic_write_json écrit d'abord dans un fichier temporaire situé dans le même dossier, synchronise son contenu, puis remplace la destination. Une interruption ne laisse donc pas un JSON partiellement écrit. Pour une modification concurrente de type lire-modifier-écrire, utiliser atomic_update_json : cet utilitaire protège l'opération complète avec un verrou inter-processus Linux, Windows et macOS.

Convention des scripts standardisés

Les scripts standardisés exposent build_parser(), run(...) et main(argv=None). Leur import ne lance aucun traitement. Ils acceptent le dossier d'évaluation comme premier argument positionnel, utilisent EvaluationWorkspace pour les chemins partagés et peuvent afficher la trace complète d'une erreur avec --verbose.

Les codes de sortie communs sont :

Code	Signification
0	réussite
1	erreur de traitement
2	arguments invalides
3	évaluation ou prérequis invalides
4	traitement partiel, avec avertissements
130	interruption par l'utilisateur

Le GUI distingue notamment un traitement partiel d'un échec. Toutes les commandes du paquet suivent désormais cette convention. Elles sont regroupées dans copienator.commands et exposées par le répartiteur python -m copienator.

Organisation du code

• Le paquet copienator contient les abstractions partagées par les scripts, notamment EvaluationWorkspace et les écritures atomiques.
• Le paquet copienator_gui contient la définition du workflow, l'état persistant, le lanceur de processus et l'application Tk.
• Le sous-paquet copienator.commands contient les points d'entrée. Leur import ne doit pas déclencher de traitement.
• copienator.dispatcher expose le CLI unifié et copienator_gui contient l'application Tk.

État et exécution du GUI

L'état d'une évaluation est conservé dans .copienator-gui.json. Les valeurs des arguments, le dernier mode exécuté, les statuts et un historique borné y sont enregistrés atomiquement. Les sorties des processus sont conservées dans .copienator/logs/. Le GUI lance les scripts dans des processus séparés afin de pouvoir afficher leur sortie, leur transmettre une saisie et les interrompre.

Les retours en arrière ne suppriment pas les artefacts. Ils marquent les étapes suivantes comme étant à revalider. Les automatismes de première visite sont également persistés et ne doivent pas être rejoués lors d'un retour en arrière.

Invariants à préserver

• Utiliser EvaluationWorkspace pour les chemins partagés d'une évaluation au lieu de reconstruire ces chemins dans chaque script.
• Publier les JSON et les ensembles de fichiers importants de façon atomique. Une interruption ou un résultat partiel doit conserver la dernière sortie complète lorsqu'elle existe.
• Conserver la convention build_parser(), run(...) et main(argv=None) pour les scripts standardisés.
• Ne lancer aucun traitement lors de l'import d'un module.
• Retourner les codes de sortie communs afin que le GUI distingue une réussite, un résultat partiel, un échec et une interruption.
• Préserver les modifications manuelles et les fichiers déjà présents, sauf lorsqu'une option explicite comme --overwrite ou --reset autorise leur remplacement.
• Les labels deviennent des noms de fichiers. Ils doivent donc respecter les contraintes de la plateforme, notamment l'interdiction de : sous Windows.

Règle de classement de la documentation

• Une information nécessaire pour installer ou démarrer l'application appartient à Readme.org.
• Une commande, un argument ou une étape du workflow appartient à Script.org.
• Une convention interne, un invariant ou une décision d'architecture appartient au présent document.