docs: update README for V1 release candidate

2026-06-21 18:26:14 +02:00
parent 19ffc45fbc
commit d91ad72a5b
1 changed files with 231 additions and 90 deletions
@@ -1,65 +1,130 @@
 # Enuxia E-Invoice

-Application open source de facturation électronique française pour **Frappe Framework et ERPNext v16**.
+Application open source de facturation électronique française pour **Frappe Framework** et **ERPNext v16**.

 Enuxia E-Invoice connecte les factures de vente et d’achat standards d’ERPNext aux services de facturation électronique de **SuperPDP**.

-> **État du projet :** développement actif et tests en environnement de laboratoire.
-> Un audit de sécurité, de conformité réglementaire et de configuration comptable reste nécessaire avant toute utilisation en production.
+> **État du projet : Release Candidate V1.**
+> Le périmètre fonctionnel principal, les contrôles d’accès et les tests automatisés sont en place.
+> L’application est prête pour une préproduction et un pilote encadré. Une validation sur un environnement SuperPDP de production, ainsi qu’un audit de déploiement, de sécurité et de configuration comptable, restent nécessaires avant une mise en production générale.
+
+---

 ## Fonctionnalités

 ### Factures de vente

-* Utilisation des factures de vente standards ERPNext
-* Génération des données sémantiques EN 16931
-* Conversion au format UBL
-* Validation des factures générées
-* Envoi des factures par l’intermédiaire de SuperPDP
-* Enregistrement de l’identifiant distant SuperPDP
-* Protection contre les doubles envois
-* Synchronisation des statuts
-* Historique des événements de transmission
-* Gestion des identifiants et informations de routage françaises
-* Recherche dans l’annuaire français de facturation électronique
+- utilisation des factures de vente standards d’ERPNext ;
+- contrôle des données nécessaires à la facturation électronique ;
+- génération des données sémantiques conformes à EN 16931 ;
+- conversion au format UBL ;
+- validation du document généré ;
+- envoi des factures par l’intermédiaire de SuperPDP ;
+- enregistrement de l’identifiant distant SuperPDP ;
+- protection contre les doubles envois ;
+- synchronisation des statuts de transmission ;
+- historique des événements de transmission ;
+- gestion des identifiants et informations de routage françaises ;
+- recherche dans l’annuaire français de facturation électronique ;
+- suivi de l’état de paiement ;
+- déclaration des encaissements auprès de SuperPDP ;
+- gestion des erreurs et nouvelle tentative de déclaration d’encaissement.

 ### Factures fournisseurs

-* Synchronisation incrémentale des factures reçues
-* Synchronisation manuelle depuis l’interface ERPNext
-* Synchronisation automatique horaire
-* Protection contre les synchronisations concurrentes avec Redis
-* Archivage des données sémantiques EN 16931
-* Archivage du document original
-* Rapprochement fournisseur par identifiant fiscal
-* Correspondance des articles, taxes, entrepôts et comptes comptables
-* Prévisualisation de la facture d’achat
-* Création d’une facture d’achat ERPNext en brouillon
-* Protection contre les doublons
-* Restauration de l’échange entrant lorsqu’une facture d’achat brouillon est supprimée
+- synchronisation incrémentale des factures reçues ;
+- synchronisation manuelle depuis l’interface ERPNext ;
+- synchronisation automatique horaire ;
+- protection contre les synchronisations concurrentes avec Redis ;
+- archivage des données sémantiques EN 16931 ;
+- archivage du document original ;
+- création d’un échange électronique entrant traçable ;
+- rapprochement fournisseur par identifiant fiscal ;
+- association manuelle d’un fournisseur existant ;
+- création d’un fournisseur depuis les données reçues ;
+- correspondance des articles, taxes, entrepôts et comptes comptables ;
+- préparation et validation des lignes d’achat ;
+- prévisualisation de la facture d’achat ;
+- calcul ERPNext en mémoire avant import ;
+- création d’une facture d’achat ERPNext en brouillon ;
+- protection contre les doublons ;
+- restauration de l’échange entrant lorsqu’une facture d’achat brouillon est supprimée ;
+- accès au document original et aux données EN 16931 depuis la facture d’achat.

 ### Intégration ERPNext

-* Workspace dédié à la facturation électronique
-* Configuration des comptes de facturation électronique
-* Intégration aux factures de vente
-* Intégration aux factures d’achat
-* Gestion des identifiants électroniques des clients
-* Accès aux documents reçus depuis les factures d’achat
-* Application visible dans le Desk Frappe v16
-* Sidebar et icône Desk dédiées
+- workspace dédié à la facturation électronique ;
+- configuration des comptes de facturation électronique ;
+- intégration aux factures de vente standards ;
+- intégration aux factures d’achat standards ;
+- gestion des identifiants électroniques des sociétés et des clients ;
+- accès aux échanges et documents liés ;
+- vues rapides pour les factures et les échanges ;
+- statuts de transmission et d’encaissement traduits ;
+- application visible dans le Desk Frappe v16 ;
+- sidebar et icône Desk dédiées ;
+- interface française intégrée au système de traduction Frappe.
+
+---
+
+## Rôles et permissions
+
+L’application crée trois rôles métier :
+
+### Facturation électronique - Lecture
+
+Permet notamment de :
+
+- consulter les échanges électroniques autorisés ;
+- consulter les statuts de transmission et de paiement ;
+- utiliser les vues de suivi ;
+- ouvrir les documents liés lorsque les permissions ERPNext le permettent.
+
+### Facturation électronique - Opérateur
+
+Inclut les capacités de lecture et permet notamment de :
+
+- vérifier une facture ;
+- préparer, générer, valider et envoyer une facture électronique ;
+- synchroniser les statuts ;
+- déclarer un encaissement ;
+- synchroniser les factures entrantes ;
+- rapprocher les fournisseurs ;
+- préparer et importer une facture d’achat ;
+- utiliser l’annuaire de facturation électronique.
+
+### Facturation électronique - Responsable
+
+Inclut les capacités de l’Opérateur et permet notamment de :
+
+- créer et modifier les comptes de facturation électronique ;
+- renseigner les identifiants SuperPDP ;
+- tester la connexion à SuperPDP ;
+- administrer la configuration sensible de l’intégration.
+
+`System Manager` et `Administrator` conservent un accès privilégié pour l’administration Frappe.
+
+Les permissions ERPNext natives restent appliquées aux factures, sociétés, clients, fournisseurs et documents comptables.
+
+Les `User Permission` Frappe permettent de limiter l’accès aux sociétés autorisées.
+
+Les contrôles côté interface améliorent l’expérience utilisateur, mais les contrôles côté serveur restent l’autorité de sécurité.
+
+---

 ## Prérequis

-* Frappe Framework v16
-* ERPNext v16
-* Une installation Bench compatible
-* Redis
-* Un compte SuperPDP
-* Des identifiants d’API SuperPDP
+- Frappe Framework v16 ;
+- ERPNext v16 ;
+- une installation Bench compatible ;
+- Redis ;
+- un compte SuperPDP ;
+- des identifiants d’API SuperPDP.

 ERPNext est déclaré comme dépendance obligatoire et doit être installé avant Enuxia E-Invoice.

+---
+
 ## Installation

 Depuis une installation Bench Frappe/ERPNext v16 existante :
@@ -93,22 +158,28 @@ Redémarrer les services lorsque le mode de déploiement l’exige :
 bench restart
 ```

+---
+
 ## Configuration initiale

 Après l’installation :

-1. Ouvrir l’application **Facturation électronique** depuis le Desk.
-2. Ouvrir **Comptes de facturation électronique**.
-3. Créer un compte `Electronic Invoicing Account`.
-4. Sélectionner la société ERPNext concernée.
-5. Choisir l’environnement SuperPDP.
-6. Renseigner les identifiants d’API SuperPDP.
-7. Tester la connexion.
-8. Configurer les identifiants électroniques de la société et des clients.
-9. Configurer les correspondances comptables des factures fournisseurs.
+1. ouvrir l’application **Facturation électronique** depuis le Desk ;
+2. attribuer les rôles de facturation électronique aux utilisateurs concernés ;
+3. configurer les `User Permission` de société ;
+4. ouvrir **Comptes de facturation électronique** ;
+5. créer un compte `Electronic Invoicing Account` ;
+6. sélectionner la société ERPNext concernée ;
+7. choisir l’environnement SuperPDP ;
+8. renseigner les identifiants d’API SuperPDP ;
+9. tester la connexion ;
+10. configurer les identifiants électroniques de la société et des clients ;
+11. configurer les correspondances comptables des factures fournisseurs.

 Les identifiants et jetons SuperPDP sont propres à chaque site. Ils ne sont pas inclus dans ce dépôt.

+---
+
 ## Envoi d’une facture client

 L’envoi s’effectue depuis une facture de vente ERPNext validée.
@@ -124,6 +195,10 @@ L’application :

 Les factures déjà envoyées sont protégées contre les doubles transmissions.

+Lorsqu’une facture transmise est encaissée, un utilisateur autorisé peut déclarer l’encaissement à SuperPDP depuis la facture de vente.
+
+---
+
 ## Synchronisation des factures reçues

 Les factures reçues sont synchronisées automatiquement par le scheduler horaire.
@@ -143,6 +218,8 @@ Elle ne valide pas automatiquement les écritures comptables.

 Les factures d’achat ERPNext sont toujours créées en statut **Brouillon** et doivent être contrôlées par un utilisateur autorisé avant validation.

+---
+
 ## Développement

 Appliquer les migrations :
@@ -157,80 +234,144 @@ Construire les assets :
 bench build --app enuxia_einvoice
 ```

-Lancer les tests :
+### Tests unitaires
+
+```bash
+./env/bin/python -m unittest discover \
+  -s apps/enuxia_einvoice/enuxia_einvoice/tests
+```
+
+État actuel :
+
+```text
+101 tests unitaires
+```
+
+### Tests d’intégration Frappe

 ```bash
 bench --site votre-site.example run-tests \
-  --app enuxia_einvoice
+  --app enuxia_einvoice \
+  --module enuxia_einvoice.tests.permissions_integration \
+  --test-category integration
 ```

-Le projet contient notamment des tests pour :
+État actuel :

-* les appels à l’API SuperPDP ;
-* la génération EN 16931 ;
-* la conversion UBL ;
-* la validation des factures ;
-* le workflow d’envoi ;
-* la synchronisation entrante ;
-* les calculs de facture d’achat ;
-* les correspondances fournisseurs et articles ;
-* la protection contre les doublons ;
-* l’historique des événements ;
-* la sécurité des URLs de documents ;
-* les identifiants d’entreprise français.
+```text
+5 tests d’intégration
+```
+
+Les tests couvrent notamment :
+
+- les appels à l’API SuperPDP ;
+- la génération EN 16931 ;
+- la conversion UBL ;
+- la validation des factures ;
+- le workflow d’envoi ;
+- la synchronisation entrante ;
+- la déclaration des encaissements ;
+- les calculs de facture d’achat ;
+- les correspondances fournisseurs et articles ;
+- la protection contre les doublons ;
+- l’historique des événements ;
+- la sécurité des URL de documents ;
+- les identifiants d’entreprise français ;
+- la hiérarchie des rôles ;
+- les permissions des DocTypes ;
+- les restrictions de société par `User Permission`.
+
+---

 ## Sécurité

 Ne publiez jamais dans les issues, logs ou pull requests :

-* les secrets client SuperPDP ;
-* les jetons d’accès ;
-* les jetons de rafraîchissement ;
-* des factures de production ;
-* des données personnelles ;
-* des informations confidentielles de clients ou fournisseurs ;
-* des fichiers de configuration privés ;
-* des clés privées.
+- les secrets client SuperPDP ;
+- les jetons d’accès ;
+- les jetons de rafraîchissement ;
+- des factures de production ;
+- des données personnelles ;
+- des informations confidentielles de clients ou fournisseurs ;
+- des fichiers de configuration privés ;
+- des clés privées.

 Les identifiants doivent être configurés dans l’interface ERPNext et stockés dans les champs protégés de Frappe.

 Les vulnérabilités sensibles ne doivent pas être publiées dans une issue publique. Elles doivent être signalées directement aux mainteneurs Enuxia.

+Avant un déploiement réel :
+
+- attribuez les rôles selon le principe du moindre privilège ;
+- configurez les `User Permission` par société ;
+- vérifiez les droits ERPNext natifs ;
+- activez HTTPS ;
+- protégez les sauvegardes ;
+- testez la restauration ;
+- contrôlez les journaux et la supervision ;
+- vérifiez qu’aucun secret n’est exposé dans les logs.
+
+---
+
 ## Données et conformité

 Cette application facilite le transport et le traitement de données de facturation électronique.

 Elle ne garantit pas, à elle seule, la conformité :

-* comptable ;
-* fiscale ;
-* juridique ;
-* réglementaire ;
-* RGPD ;
-* organisationnelle.
+- comptable ;
+- fiscale ;
+- juridique ;
+- réglementaire ;
+- RGPD ;
+- organisationnelle.

 Chaque déploiement doit être contrôlé selon :

-* l’organisation concernée ;
-* sa configuration comptable ;
-* sa plateforme de dématérialisation partenaire ;
-* les exigences françaises et européennes applicables ;
-* ses obligations de sécurité et de protection des données.
+- l’organisation concernée ;
+- sa configuration comptable ;
+- sa plateforme de dématérialisation partenaire ;
+- les exigences françaises et européennes applicables ;
+- ses obligations de sécurité et de protection des données.
+
+---

 ## État du projet

-Le projet est actuellement destiné :
+Le projet est actuellement adapté :

-* au développement ;
-* aux démonstrations ;
-* aux tests en laboratoire ;
-* à la préparation de pilotes encadrés.
+- au développement ;
+- aux démonstrations ;
+- aux tests en laboratoire ;
+- à une préproduction ;
+- à la préparation de pilotes encadrés.

-Il n’est pas encore déclaré prêt pour un déploiement en production sans audit complémentaire.
+Le périmètre fonctionnel principal de la V1 est terminé et couvert par des tests automatisés.
+
+L’application n’est pas encore déclarée prête pour un déploiement en production générale sans validation complémentaire.
+
+Avant une version stable `v1.0.0`, les points suivants doivent notamment être validés :
+
+- installation sur un site ERPNext v16 vierge ;
+- migrations répétables ;
+- échanges avec l’environnement SuperPDP de production ;
+- tests réels d’envoi, de réception, d’avoir et d’encaissement ;
+- validation des principaux cas comptables ;
+- sauvegarde et restauration ;
+- supervision des synchronisations ;
+- documentation d’exploitation ;
+- pilote sans anomalie bloquante.
+
+Version recommandée pour la prochaine étape :
+
+```text
+v1.0.0-rc.1
+```
+
+---

 ## Licence

 Ce projet est distribué sous licence MIT.

 Copyright © 2026 Enuxia contributors.
-