Manuel Professionnel Complet

Ce manuel explique le pourquoi et le comment internes. Pour le guide d'utilisation pas à pas, voir le Manuel d'Utilisateur.

1. Architecture générale

Ledyvas est une application de bureau construite sur Electron. Elle tourne à 100 % sur la machine du client — il n'y a pas de serveur d'application ni de base de données dans le cloud. La seule chose que Ledyvas interroge par Internet est un serveur de licences (un Cloudflare Worker), et seulement de temps en temps.

• Processus principal : démarre l'application, valide la licence, ouvre la base de données et relie chaque module avant d'afficher l'interface.
• Interface : HTML/CSS/JavaScript sans framework. Chaque écran est une vue chargée à la demande lors de la navigation.
• Pont unique : l'interface ne touche jamais la base de données directement. Tout passe par une couche de services avec validation, transactions et calculs.
• Mode portable : la base de données vit dans un dossier Data à côté de l'exécutable. Vous pouvez copier le dossier entier vers un autre ordinateur ou un disque externe.

2. Licence et chiffrement

Ledyvas s'active avec un code de licence contre le serveur de licences. La validation utilise la signature cryptographique asymétrique (Ed25519) : la clé privée vit uniquement sur le serveur, donc l'application ne pourrait pas falsifier une licence même si quelqu'un la décompilait.

• Marge hors ligne : après l'activation, Ledyvas fonctionne plusieurs jours sans connexion. Il se revalide en arrière-plan dès qu'il y a Internet. Ce n'est que si la marge expire et qu'il n'y a pas de connexion que l'application demande de se reconnecter.
• Transfert : la licence peut être déplacée vers une autre machine. Le serveur impose une seule machine active à la fois (empreinte matérielle) ; activer sur un nouveau PC désactive le précédent.
• Base de données chiffrée : le fichier opshield.db est chiffré. La clé est dérivée du code de licence avec PBKDF2 à 210 000 itérations (standard OWASP). Si le portable est volé, personne n'ouvre la base sans la licence. Comme la clé voyage avec la licence et non avec le matériel, la même licence réactivée sur un autre PC rouvre le même fichier — c'est pourquoi vous pouvez déplacer le dossier entre ordinateurs.

3. Base de données et migrations

Ledyvas utilise un seul fichier SQLite. Le schéma évolue via des migrations numérotées et ordonnées : chaque mise à jour de l'application apporte de nouvelles migrations qui s'appliquent elles-mêmes, une fois, au premier démarrage, dans leur propre transaction. Une migration déjà appliquée n'est jamais modifiée ; on en ajoute une nouvelle.

Au démarrage, Ledyvas fait aussi un point de contrôle du journal d'écriture anticipée (WAL) et le répète en arrière-plan de temps en temps — cela empêche le fichier de travail de croître sans limite lors des longues sessions.

4. Catalogue et relations

Le catalogue est la base de tout. Il est chargé une fois et référencé dans chaque opération ultérieure par son identifiant interne stable, jamais par son nom — c'est pourquoi vous pouvez renommer un produit, une destination ou une catégorie à tout moment sans casser l'historique.

Entité	Rôle	En relation avec
Produit	Un article acheté, vendu ou produit. A une catégorie, sous-catégorie, unité, coût, code-barres.	Achats, Ventes, Recettes, Formule, Inventaire
Catégorie / Sous-catégorie	Classent le produit. Définissent le regroupement dans Achat/Inventaire et à quelle « famille » il appartient (Alimentaire, Boissons, Usage Unique, Carburant…).	Produit, Formule, Consolidés
Fournisseur	À qui vous achetez. Peut avoir une liste de produits fournis avec le coût (référence).	Achat
Client	À qui vous vendez. Si « revendeur », a son propre stock.	Vente au Consommateur, Destination
Destination	Un point de distribution. Peut avoir un client-revendeur lié et un prix de vente par PAX.	Formule, Centre Logistique, Marge par Destination
Équipement	Véhicule ou bateau. Type (bateau/terrestre) et groupe (entreprise/loué).	Carburant, Consolidé des Flottes

5. Le moteur Formule-par-PAX

Uniquement avec le Mode Excursion activé. La Formule traduit « combien de personnes vous allez servir » en « combien acheter et expédier ».

1. Une matrice de Valeur est configurée : pour chaque combinaison produit × destination, combien une personne consomme (ex. 0,25 kg de riz par PAX à la destination X).
2. Chaque jour, le PAX par destination est saisi.
3. Le calcul produit, par ligne (destination × produit) : Requis = Valeur × PAX.
4. Du Requis, on soustrait trois ajustements saisis par destination : Stock Existant (ce que la destination a déjà), Retour (ce qu'elle a retourné) et Inventaire sur la Plage (comptage physique sur le point). Le résultat est l'Expédition de cette ligne (jamais négative).
5. Pour savoir combien acheter au total, on somme l'Expédition de toutes les destinations de chaque produit (en arrondissant chaque ligne à l'entier supérieur, car on ne livre pas une fraction à un restaurant) et on soustrait une seule fois l'Inventaire d'Entrepôt (stock partagé déjà présent dans le Centre Logistique).

L'Achat Assisté A (Alimentaire) et B (Boissons) exécutent seulement ce calcul — ce sont une proposition. Ils ne génèrent aucun achat réel et ne touchent aucun inventaire. L'écran Achat est le seul qui confirme.

6. Achat : comment le stock entre

L'écran Achat est le seul point du système qui génère un achat réel. À la confirmation, dans une seule transaction atomique :

1. Le document d'achat est inséré (fournisseur, date, lignes).
2. La quantité est ajoutée au current_stock de chaque produit, de manière synchrone.
3. Un mouvement est enregistré dans l'historique (stock_movements) avec produit, quantité, coût, date et utilisateur — traçabilité complète.
4. Le module Contrôle Journalier est synchronisé pour ce jour/catégorie.
5. Si le produit est Boissons, Usage Unique ou Carburant, il se transfère tout seul au suivi interne de ces catégories dans le Centre Logistique.

Annuler ou modifier un achat inverse tout ce qui précède à la date d'origine du document, pas à la date d'aujourd'hui. Ledyvas ne bloque pas l'annulation même si le stock passe en négatif (voir section 16).

7. Centre Logistique et les Ventes

Le Centre Logistique est le seul entrepôt du système. De là, vous vendez/expédiez aux destinations. Chaque section de vente (Vente aux Restaurants = Alimentaire + Usage Unique ; Vente aux Bateaux = Boissons) a son propre PAX, indépendant du PAX de l'Achat — le PAX de l'Achat et celui de la Vente ne s'écrasent pas mutuellement (acheter et vendre sont des processus distincts).

À la confirmation d'une vente, pour chaque destination avec quelque chose de calculé un transfert réel est généré : il déduit le current_stock, crédite le stock du client-revendeur de cette destination, et enregistre le mouvement — le tout dans une seule transaction (si une destination échoue, tout est inversé). L'expédition par destination utilise la même Formule, ajustée par Stock Existant / Retour / Inventaire sur la Plage, que l'Achat.

La vente valide le stock et avertit de ce qui manque, mais n'empêche pas la confirmation — l'opération n'est pas interrompue.

8. Vente au Consommateur et stock du revendeur

Chaque client marqué comme « revendeur » a son propre solde de stock (reseller_stock). Il est crédité quand le Centre Logistique lui expédie, et déduit quand ce revendeur vend au client final sur l'écran Vente au Consommateur.

• Confirmer une vente depuis le Centre Logistique crée automatiquement un brouillon de Vente au Consommateur par destination. Le brouillon existe et peut être modifié, mais ne déduit pas de stock tant qu'il n'est pas confirmé explicitement.
• Les lignes de Boissons des bateaux n'ont pas de prix de vente propre (l'encaissement du forfait par PAX est enregistré une seule fois côté Alimentaire, pour ne pas compter le revenu deux fois). Elles s'affichent comme un enregistrement de coût, pas comme une perte.
• Revente n'est qu'un rapport de ce qui a déjà été expédié — elle ne génère aucun mouvement.

9. Boissons, Usage Unique et Carburant

Ces trois familles n'ont pas d'entrepôt ni d'écran séparé. Elles vivent dans le Centre Logistique avec leur propre suivi de stock :

• Elles se transfèrent toutes seules à ce suivi à la confirmation d'un Achat (au lieu de s'ajouter au stock général des produits).
• Depuis le Centre Logistique, vous enregistrez leurs ventes, ajustements, sorties/consommations et retours, chacun avec son propre type de mouvement et son historique.
• Les Boissons se subdivisent en Alcoolisées / Non Alcoolisées.
• La vue « Retours du Jour » consolide tous les retours (Boissons par sous-groupe, Consommables, Carburant) en un seul endroit, et ce stock retourné réduit automatiquement la suggestion d'achat du jour suivant.

Dans les Consolidés, ces familles ne sont pas réparties par destination : elles sont portées comme coût général (sauf l'Usage Unique, qui est expédié par destination — voir section 5).

10. Bidons de carburant

Pour les activités qui, en plus du stock en gallons, gèrent le carburant/l'huile en bidons physiques (5, 7, 9, 10 et 18 GL). C'est un inventaire parallèle qui se synchronise tout seul avec le stock en gallons — rien ne doit jamais être saisi deux fois.

Opération	Effet
Achat	Ajoute des bidons (par capacité et quantité exacte, ou avec une suggestion de répartition optimale selon les gallons dont vous avez besoin) et ajoute les gallons équivalents à l'inventaire général.
Vente / expédition	Retire des bidons en les affectant à un équipement, et retire les gallons de l'inventaire.
Retour	Plein (ajoute tout), partiel (ajoute les gallons réels contenus) ou vide (n'ajoute pas de carburant, retourne seulement le contenant).
Ajustement	Corrige le comptage après un inventaire physique. Demande la valeur correcte par capacité/état et un motif, et c'est audité.

Il a sa propre Clôture de Journée (Initial + Achats − Vendu + Retourné = Final) et un historique complet. L'affichage peut basculer entre Gallons et Litres ; ce qui est stocké dans la base ne change jamais d'unité.

11. Contrôle Journalier

C'est une couche de rapprochement, distincte du stock réel. Elle enregistre, par jour/catégorie/produit : initial, achats, expéditions (par équipement/destination), retours et le comptage physique.

Final calculé = Initial + Achats − (Expédié − Retourné). Si un comptage physique est saisi, c'est le nombre vérifié et il est utilisé comme initial du jour suivant — ainsi une différence entre le théorique et le réel se corrige et n'est pas reportée.

Les achats et expéditions réels synchronisent le Contrôle Journalier automatiquement ; il peut aussi être modifié à la main.

12. Comment se calcule chaque Consolidé

Résumé Journalier / Consolidé Opérationnel

Le coût opérationnel total de l'activité pour la période : l'Achat réel confirmé (par catégorie, avec les postes Essence/Huile séparés) plus les coûts manuels configurables par catégorie (loyer, salaires, commissions, etc. — gérés dans Paramètres, pas une liste fixe). Il affiche aussi : le PAX de la période, la dépense totale, le coût par PAX, et un tableau statistique PAX Moyen par Destination (moyenne des PAX vendus par jour à chaque destination, en comptant uniquement les jours avec une vente réelle). Ce tableau est purement informatif — il n'entre dans aucun calcul de coût.

Marge par Destination

Mode Excursion uniquement. Coût, ventes et marge par destination, uniquement pour ce qui est passé par le Centre Logistique (transferts réels). Le coût est figé dans chaque transfert ; les ventes utilisent le prix stocké dans le transfert. Boissons et Carburant n'apparaissent pas par destination (ils s'affichent à part comme « autres coûts de la période »).

Consolidé des Flottes

Consommation de carburant par équipement. En mode hebdomadaire, il utilise une moyenne pondérée par quantité (un jour de forte consommation pèse plus qu'un jour léger). Montants en devise locale ou en dollars US, selon le taux configuré.

13. Recettes et Production

Une recette définit, pour un produit fini, combien il faut de chaque ingrédient. L'ingrédient peut être dans une unité différente de celle du produit dans le catalogue (grammes dans la recette, kilos dans Produits) — Ledyvas convertit automatiquement par famille d'unité (poids, volume) avant de calculer le coût et la consommation.

À la production, dans une transaction :

1. Chaque ingrédient est déduit du stock selon la quantité convertie × lots.
2. Le produit fini est ajouté (portions × lots).
3. Le coût du produit fini est recalculé comme une moyenne pondérée entre le stock déjà présent (à son coût précédent) et ce qui vient d'être produit (au coût par portion de la recette). Si la recette n'a pas d'ingrédients valorisés, le coût réel précédent n'est pas écrasé.

Ainsi le produit fini a toujours un coût réel : il vaut le bon montant dans l'Inventaire et peut être vendu sans que la validation le bloque pour coût nul.

14. Équipements et Consolidé des Flottes

Équipements est le registre des véhicules/bateaux. Chacun avec un code automatique, un type (bateau/terrestre) et un groupe (entreprise / loués). Ils servent à attribuer les expéditions de carburant et les ventes par unité, qui alimentent ensuite le Consolidé des Flottes (voir section 12).

15. Multi-utilisateur, rôles et accès

Ledyvas a un système d'utilisateurs avec 5 rôles : Direction, Achats, Ventes, Entrepôt, Comptabilité. Les mots de passe sont stockés uniquement sous forme de hachage (scrypt), jamais en clair.

16. Stock négatif : un choix de conception

Ledyvas ne bloque jamais la confirmation d'une vente, d'une expédition, d'une production ou de l'annulation d'un achat par manque de stock. C'est un choix explicite : ne pas interrompre l'opération de l'activité. Un stock négatif n'est pas une erreur du programme — il se corrige avec le bouton Ajuster le Stock de cette ligne (dans Produits ou Inventaire), qui demande la valeur correcte et un motif et l'audite.

La seule exception : le Retour de marchandise d'un revendeur valide qu'il ne retourne pas plus qu'il n'a reçu (cela n'a physiquement pas de sens).

17. Sauvegarde et Suppression Maître

Sauvegarde (sur Accueil) : enregistre une copie complète du fichier de base de données en un clic.

Suppression Maître (sur Accueil, « Mode Test ») : supprime les Achats, Ventes et Transferts à partir d'une date choisie — jamais avant cette date, et jamais le catalogue (Produits, Clients, Fournisseurs, Destinations). Elle demande de taper « TOUT SUPPRIMER ». Chaque document est supprimé avec le même mécanisme qu'une annulation individuelle, donc les inversions de stock restent cohérentes. Elle sert à nettoyer les données de test avant d'opérer pour de vrai.

18. Langues et devise

Ledyvas est traduit en espagnol, italien, anglais, français et portugais. La langue change à la volée avec les drapeaux, sans redémarrage. La devise de l'activité se définit dans Paramètres et gouverne chaque montant ; le taux de change vers les dollars US (configurable) est utilisé dans les rapports de flotte.

19. Assistant IA

L'assistant dans l'application répond aux questions d'utilisation. Architecture :

• L'application envoie la question (et l'historique récent) avec sa licence et son empreinte matérielle au serveur de licences.
• Le serveur valide la licence, applique une limite de 40 questions par jour et par licence (un filet de sécurité sur les coûts), et ce n'est qu'ensuite qu'il appelle le modèle de langage.
• La clé du fournisseur d'IA n'est jamais dans l'application ni dans l'installateur — elle vit uniquement comme secret du serveur.
• L'assistant répond toujours dans la langue dans laquelle on lui écrit, parmi les 5 langues prises en charge.

20. Règles métier clés

• Acheter ≠ vendre. L'Achat ajoute seulement du stock. La distribution aux destinations est indépendante.
• Un seul entrepôt. Le Centre Logistique. Il n'y a pas de dépôt séparé ni d'« entrepôt satellite ».
• L'Achat Assisté ne fait que calculer. Il ne génère jamais un achat réel.
• Identifiants stables. Tout est référencé par id interne ; les noms peuvent être changés sans rien casser.
• Chaque mouvement de stock est audité dans l'historique, avec la date réelle du document (pas celle d'aujourd'hui).
• Le stock n'arrête jamais l'opération (sauf le Retour d'un revendeur).
• Le comptage physique fait foi. Dans le Contrôle Journalier, le comptage réel corrige le théorique et est reporté comme initial du jour suivant.

21. Questions techniques fréquentes

Puis-je déplacer l'installation vers un autre ordinateur ?

Oui. Copiez le dossier entier (programme + dossier Data) et activez la licence sur la nouvelle machine. La licence se transfère toute seule (la précédente est désactivée). Comme la clé de chiffrement dérive de la licence, la base s'ouvre sur le nouveau PC.

Les données sont-elles dans le cloud ?

Non. Tout est sur votre machine, dans un fichier chiffré. Faites des sauvegardes souvent.

Pourquoi un produit produit valait zéro et maintenant non ?

Produire calcule maintenant le coût réel du produit fini (moyenne pondérée). Avant, il fallait le saisir à la main.

Pourquoi la Vente aux Restaurants propose-t-elle maintenant l'Usage Unique ?

L'Usage Unique est expédié par destination exactement comme l'Alimentaire. Il faut que sa Valeur soit chargée dans la Formule (Achat Assisté A) et son coût dans Produits.

Que se passe-t-il si je supprime un produit qui est dans une recette ?

Ledyvas vous avertit avant de confirmer dans combien de recettes et de lignes de Formule il est utilisé. Si vous le supprimez, il est retiré de là et ces recettes recalculent leur coût. Si le produit a des achats/ventes réels, il n'est pas supprimé : il est désactivé.

Si quelque chose n'est pas couvert ici

Écrivez à info@ledyvas.com.