Spécification fonctionnelle

Spécification fonctionnelle

Règles générales

• L’API backend est la source de vérité distante.
• Le fichier .obf local est une copie de travail, un cache ou un export.
• L’application doit fonctionner même lorsque l’API est indisponible.
• Les actions utilisateur doivent générer une notification temporaire.
• Les erreurs doivent être visibles via l’état applicatif ou le panneau debug lorsque pertinent.
• Les changements de données ne doivent pas provoquer de déplacement incohérent des fenêtres, modales ou badges.
• Le lancement doit afficher un écran de préchargement jusqu’à disponibilité du premier état applicatif.
• L’application doit surveiller les ressources locales sans bloquer les actions utilisateur.

Workspace

Création

• L’utilisateur doit saisir un nom de workspace.
• L’utilisateur peut saisir une description.
• L’utilisateur doit choisir un dossier local.
• Le dossier choisi ne doit pas déjà contenir de fichier .obf.
• Si le nom ou le dossier est manquant, le workspace ne doit pas être créé.
• Si le dossier contient déjà un .obf, le workspace ne doit pas être créé.
• L’utilisateur doit être notifié lorsque la validation bloque la création.
• Le fichier .obf doit être créé dans le dossier choisi.
• Le nom du fichier doit être dérivé du nom saisi.
• Les espaces dans le nom de fichier doivent être remplacés par _.
• Les caractères invalides doivent être remplacés par _.
• Le workspace créé doit être ajouté aux récents.
• Les chemins par défaut du workspace doivent être initialisés.
• Les dossiers nécessaires doivent être créés s’ils n’existent pas.
• La version initiale du workspace doit être 1.
• Si l’API est disponible, le workspace doit être créé dans l’API.
• Si l’API est indisponible, une opération created doit être mise en attente.

Ouverture

• L’utilisateur peut ouvrir un fichier .obf depuis le système.
• Le fichier doit être validé avant ouverture.
• Le workspace ouvert doit devenir le workspace courant.
• Le workspace ouvert doit être ajouté ou remonté dans les récents.
• En cas d’erreur de validation, l’utilisateur doit voir une erreur.

Mes workspaces

La vue My workspaces doit être séparée en deux sections:

• My local workspaces: workspaces connus localement;
• My remote workspaces: workspaces persistés dans l’API pour l’utilisateur courant.

My local workspaces

• La liste est limitée à 12 entrées.
• Une entrée récente est unique par filePath.
• L’utilisateur peut afficher les détails d’un workspace récent.
• L’utilisateur peut ouvrir un workspace récent.
• L’utilisateur peut retirer un workspace de la liste.
• Retirer un workspace récent ne supprime pas le fichier local.

My remote workspaces

• La liste distante est chargée via GET /workspaces.
• Le contrat OpenAPI de référence est {{baseUrl}}/api/openapi.json.
• La section distante affiche les workspaces associés à l’utilisateur authentifié.
• Si l’API est indisponible ou si la session ne permet pas l’accès, la section affiche un message d’indisponibilité.
• Les workspaces distants affichent au minimum l’id, le nom, la description et les chemins exposés par l’API.

Fermeture

• Si le workspace est marqué dirty, l’utilisateur doit confirmer la fermeture.
• Si l’utilisateur annule, le workspace reste ouvert.
• Si l’utilisateur confirme, le workspace courant est vidé.

Modification du nom et de la description

• L’action Edit doit ouvrir une modale.
• Le formulaire doit contenir le nom et la description.
• Le nom est obligatoire.
• La description peut être vide.
• Si le nom et la description sont inchangés, aucune sauvegarde utile ne doit être déclenchée.
• À la sauvegarde, workspace.name, workspace.description, workspace.updatedAt, exportedAt et workspace.version doivent être mis à jour.
• Le fichier .obf doit être sauvegardé.
• L’entrée récente doit être mise à jour.
• Une synchronisation API doit être tentée si elle est activée.
• Si l’API est indisponible, une opération updated doit être mise en attente.

Settings globaux

• Les settings globaux sont sauvegardés dans l’état local de l’application.
• L’écran Settings est organisé en onglets: General, Local Workspace, Projects, Archives, Sync, Remote Storage, Health Integrity & Restore, Logs & Observability, Advanced.
• Chaque onglet conserve un brouillon local et n’écrit les changements qu’au clic sur Save changes.
• Reset changes annule les modifications non sauvegardées de l’onglet courant.
• Un indicateur Unsaved signale les onglets modifiés.
• La langue doit être normalisée à fr ou en.
• Le thème doit accepter system, light, dark.
• L’URL API est configurable depuis l’onglet Sync.
• L’intervalle de polling du health API est configurable en secondes.
• L’intervalle de polling du health API ne peut pas être inférieur à 5 secondes.
• Le debug API global est configurable.
• La modification des settings globaux ne doit pas rediriger l’utilisateur vers une autre page.

Settings workspace

• Les settings workspace ne sont modifiables que si un workspace est ouvert.
• Toute modification de settings workspace doit sauvegarder le .obf.
• Toute modification de settings workspace doit incrémenter la version.
• Toute modification de settings workspace doit tenter une synchronisation API.
• Les chemins doivent pouvoir être saisis manuellement.
• Les chemins doivent pouvoir être sélectionnés via le navigateur système.
• Les champs de dossier doivent aligner champ texte, bouton Browse..., état de validation et action Reveal in Finder lorsque pertinente.
• Les chemins sauvegardés doivent être pris en compte par le workspace.
• Les dossiers manquants doivent être créés lors de la sauvegarde.
• Les actions avancées destructives doivent demander confirmation.

Remote Storage

• Chaque workspace peut configurer un primary backup et un secondary backup.
• Une destination de backup désactivée ne doit pas afficher ses champs avancés et ne doit pas afficher de badge dans le header.
• Une destination activée doit afficher uniquement les champs cohérents avec son provider: S3, GCS, OCI, Azure, NAS ou SFTP.
• Le statut des credentials doit être présenté sous forme de badges par destination activée.
• Les statuts credentials doivent distinguer Configured, Missing, Incomplete et Not required.
• Le bouton Test connection doit mettre à jour le statut de la destination concernée dans les settings et dans le header.
• Le header doit afficher une icône distincte pour le primary backup et le secondary backup.
• Le dernier résultat de test doit primer sur le simple état de configuration: un test échoué doit rendre l’icône concernée rouge.
• Les tests de connexion automatiques doivent s’exécuter au chargement du workspace puis à l’intervalle configuré dans Remote backup policy.
• Les tests cloud doivent valider l’accès par écriture puis suppression d’un objet temporaire lorsque les credentials nécessaires sont fournis.

Structure workspace

Les listes suivantes sont éditables:

• dossiers principaux;
• sous-dossiers projet;
• sous-dossiers archive;
• dossiers importables.

Une liste peut être saisie avec des lignes ou des valeurs séparées par des virgules. Les valeurs vides sont ignorées.

Archive

Le moteur d’archive doit être l’une des valeurs:

• zip;
• tar.gz;
• pigz;
• zstd.

La stratégie doit être l’une des valeurs:

• create-new;
• overwrite;
• incremental.

Les limites d’historique doivent être des entiers positifs.

Import

Le mode d’import doit être l’une des valeurs:

• copy;
• move;
• reference.

L’utilisateur peut activer ou désactiver:

• la préservation de la structure originale;
• la détection des doublons.

Synchronisation

• La synchronisation peut être activée ou désactivée par workspace.
• Si elle est désactivée, aucune synchronisation API workspace ne doit être lancée.
• Si elle est activée, l’application contrôle le health API avant la sync.
• Si le health API échoue, le statut devient offline.
• Si le health API réussit, les opérations en attente peuvent être drainées.
• Avant un push local, l’application récupère les changements distants.
• Les événements distants issus de desktop sont ignorés pour éviter de réappliquer ses propres changements.
• Les événements distants avec une version inférieure ou égale à la version locale sont ignorés.
• Les événements distants plus récents peuvent fusionner le payload workspace.
• Si la version distante API est supérieure au serverVersion local connu, l’utilisateur peut déclencher un refresh du workspace depuis le header.
• Un refresh API applique les champs distants du workspace tout en conservant les chemins locaux du fichier .obf.
• Après lecture des changements, le cursor peut être accusé réception via l’API.
• Les conflits renvoyés par l’API doivent passer le statut à conflict.
• Les échecs renvoyés par l’API doivent passer le statut à failed.

Authentification et licence

• L’utilisateur peut s’authentifier avec email et mot de passe.
• Après login, le token et l’utilisateur sont conservés dans authSession.
• L’application tente de récupérer la licence courante.
• Si une licence est récupérée et qu’un workspace est ouvert, elle est appliquée aux settings du workspace.
• Le logout supprime la session locale.

Notifications

• Les notifications sont temporaires.
• Les notifications sont affichées en bas à droite.
• Les couleurs dépendent du ton:
  • info;
  • success;
  • warning;
  • error.
• Les actions utilisateur importantes doivent notifier leur résultat.
• Les hausses anormales d’utilisation CPU, mémoire ou disque doivent notifier l’utilisateur.

Projets

• Les boutons Nouveau projet et Importer un projet doivent être groupés ensemble dans l’interface.
• Le projet sélectionné doit être persisté par workspace dans le stockage local.
• À l’ouverture d’un workspace, le dernier projet sélectionné doit être restauré automatiquement.
• Si le projet restauré n’existe plus, la vue revient à la liste des projets.

Reconstruction de l’index projet

• Lancer une reconstruction de l’index affiche un panneau de progression.
• Le panneau affiche le statut courant, un bouton d’annulation et un bouton de relance.
• Un bouton de fermeture (×) permet de masquer le panneau sans annuler la tâche.
• La fermeture du panneau ne redevient pas visible si le statut du job change dans le même cycle de vie de l’application.

Modales et accessibilité clavier

• Les modales de création de workspace, création de projet et modification de projet doivent piéger le focus clavier.
• La navigation Tab et Shift+Tab doit rester dans la modale.
• Le focus doit être restauré sur l’élément déclencheur à la fermeture de la modale.
• Si la modale de modification d’un projet est ouverte lors d’un rechargement de vue, le brouillon en cours doit être restauré depuis le stockage local.

Ressources locales

• Le footer de la sidebar doit afficher les ressources locales consommées par l’application.
• Les métriques affichées sont l’utilisation CPU, l’utilisation mémoire et l’espace disque disponible.
• Les métriques doivent être rafraîchies périodiquement sans déplacer la sidebar.
• Si la collecte est indisponible, le footer doit afficher un état indisponible.
• Les seuils d’alerte sont centralisés dans resource-monitor.
• Une alerte ressource doit être limitée dans le temps pour éviter de spammer l’utilisateur.

Logging

• Chaque événement applicatif significatif doit être écrit localement.
• Les logs locaux sont durables et au format JSONL.
• Les logs doivent inclure le contexte applicatif disponible.
• Les champs sensibles doivent être masqués.
• Si le remote logging est activé, les logs doivent être exportés en batch.
• Un échec d’export remote ne doit pas empêcher l’écriture locale.
• Les alertes de ressources locales doivent être écrites dans les logs JSONL.

Packaging et CI

• La qualité code doit vérifier lint, format, typecheck, tests, audit et build.
• Les tests doivent couvrir les niveaux unitaires, fonctionnels, techniques, end-to-end et performance.
• Le packaging unsigned doit produire un DMG sans signature.
• Le packaging unsigned ne doit pas publier automatiquement depuis la CI.
• Les commits doivent respecter conventional commit.
• Les releases doivent suivre SemVer.
• Les assets de release doivent être publiés sur la release du repo source puis copiés vers le repo public ctay/obscura-flow-releases.