@sinoia/hubdoc-tools 1.0.4 → 1.2.1

package/DEMO-DOCUMENTATION.md

@@ -1,411 +0,0 @@
-# 🏗️ HubDoc Tool - Cas d'Usage : Import Massif BTP
-
-## 📋 Scénario : Groupe Immobilier BAUTECH
-
-**Client :** BAUTECH Construction & Promotion Immobilière  
-**Secteur :** BTP, Promotion immobilière, Gestion de patrimoine  
-**Volume :** 15,000 documents à importer  
-**Projets :** 8 programmes immobiliers en cours + archives historiques  
-
-### 🎯 Objectif
-Centraliser tous les documents de construction dans HubDoc pour faciliter :
-- Suivi des chantiers en temps réel
-- Conformité réglementaire (RT2020, normes sécurité)
-- Gestion des sous-traitants et fournisseurs
-- Archivage légal (10 ans minimum)
-
----
-
-## 📊 Répartition des Documents
-
-```
-📁 BAUTECH - Documents (15,000 total)
-├── 🏢 Projets Actifs (8,500 docs)
-│   ├── Les Jardins de Meudon (1,800 docs)
-│   ├── Résidence Harmony Levallois (2,100 docs)
-│   ├── Éco-Quartier Boulogne (1,900 docs)
-│   ├── Villa Prestige Neuilly (1,200 docs)
-│   ├── Loft Industrial Montreuil (700 docs)
-│   ├── Green Towers La Défense (600 docs)
-│   └── Campus Student Créteil (200 docs)
-│
-├── 📋 Administration (3,200 docs)
-│   ├── Contrats & Marchés (1,100 docs)
-│   ├── Certifications & Agréments (800 docs)
-│   ├── Assurances & Garanties (700 docs)
-│   └── RH & Formation (600 docs)
-│
-├── 🛠️ Techniques (2,100 docs)
-│   ├── Plans & Études (900 docs)
-│   ├── DOE - Dossiers Ouvrages Exécutés (800 docs)
-│   └── Maintenance & SAV (400 docs)
-│
-└── 📜 Archives (1,200 docs)
-    ├── Projets 2020-2022 (800 docs)
-    └── Documents Historiques (400 docs)
-```
-
----
-
-## 🏢 Organisation HubDoc : Domaines & Projets
-
-### 🌐 **Domaines** (Notions Métier Transverses)
-Les domaines regroupent les documents par expertise métier, indépendamment des projets :
-
-- **🏗️ BTP & Construction** : Plans, permis, études techniques, PV chantier
-- **💼 Administration** : Contrats, assurances, RH, comptabilité  
-- **🔧 Technique & Maintenance** : DOE, manuels, rapports, certifications
-- **📜 Légal & Conformité** : Autorisations, audits, certifications ISO
-
-### 🏢 **Projets** (avec Plans de Classement Spécifiques)
-Chaque projet dispose de son plan de classement adapté au type d'opération :
-
-**Projet: 🏡 Les Jardins de Meudon**
-```
-📁 Plan de Classement BTP
-├── 📜 Administrative/
-│   ├── Permis & Autorisations
-│   ├── Contrats & Marchés
-│   └── Assurances
-├── 🏗️ Technique/
-│   ├── Plans Architecture
-│   ├── Plans Structure  
-│   ├── Plans Fluides
-│   └── Études & Calculs
-├── 💰 Financier/
-│   ├── Devis
-│   ├── Factures
-│   └── Situations Travaux
-└── 🔍 Suivi/
-    ├── PV Chantier
-    ├── PV Réception
-    └── Photos & Constats
-```
-
-**Projet: 🏢 Résidence Harmony Levallois** (même structure)  
-**Projet: 🌃 Éco-Quartier Boulogne** (même structure)  
-**Projet: 📁 BAUTECH Corporate** (documents transverses groupe)
-
----
-
-## 📝 Exemple de Mapping CSV
-
-### 🆕 **Définition des Projets**
-
-Le CSV peut contenir des lignes spéciales pour **créer des projets** avec leur plan de classement :
-
-**Format :**
-- **File Path** : Chemin vers le dossier projet (terminé par `/`)
-- **Target Folder** : `CREATE_PROJECT` (mot-clé spécial)
-- **Workspace** : Nom du projet à créer (champ technique)
-- **Domain** : Domaine métier associé
-- **Plan Classement** : Template de plan de classement à appliquer
-
-**Plans de Classement Disponibles :**
-- `BTP_PROMOTION_IMMOBILIERE` : Plan standard pour projets immobiliers
-- `BTP_INFRASTRUCTURE` : Plan pour travaux publics/infrastructures  
-- `ADMINISTRATION_GENERALE` : Plan pour documents corporate
-- `MAINTENANCE_TECHNIQUE` : Plan pour gestion maintenance
-- `JURIDIQUE_CONTENTIEUX` : Plan pour dossiers juridiques
-
-```csv
-File Path,Target Folder,Workspace,Domain,Plan Classement,Metadata (JSON),Read Permissions,Write Permissions
-# === DÉFINITION DES PROJETS ===
-./docs/projets/meudon/,CREATE_PROJECT,Les Jardins de Meudon,BTP & Construction,BTP_PROMOTION_IMMOBILIERE,"{\"type\":\"projet\",\"client\":\"Ville de Meudon\",\"surface\":\"15000m2\",\"budget\":8500000}",groups:direction,architectes,conducteurs_travaux,groups:direction,architectes
-./docs/projets/levallois/,CREATE_PROJECT,Résidence Harmony Levallois,BTP & Construction,BTP_PROMOTION_IMMOBILIERE,"{\"type\":\"projet\",\"client\":\"SCI Harmony\",\"surface\":\"8500m2\",\"budget\":12000000}",groups:direction,architectes,conducteurs_travaux,groups:direction,architectes
-./docs/admin/,CREATE_PROJECT,BAUTECH Corporate,Administration,ADMINISTRATION_GENERALE,"{\"type\":\"projet\",\"description\":\"Documents transverses groupe\"}",groups:direction,rh,comptabilite,groups:direction
-
-# === DOCUMENTS ===
-./docs/projets/meudon/plans/plan_masse_v3.pdf,Technique/Plans Architecture,Les Jardins de Meudon,BTP & Construction,,"{\"type\":\"plan\",\"version\":\"3.0\",\"date\":\"2024-03-15\",\"architecte\":\"Cabinet Dubois\"}",users:j.martin,m.dupont|groups:architectes,conducteurs_travaux,groups:architectes
-./docs/projets/meudon/permis/pc_2024_001.pdf,Administrative/Permis & Autorisations,Les Jardins de Meudon,Légal & Conformité,,"{\"type\":\"permis_construire\",\"numero\":\"PC-2024-001\",\"commune\":\"Meudon\",\"statut\":\"accordé\"}",groups:direction,juridique,conducteurs_travaux,groups:direction
-./docs/projets/levallois/devis/gros_oeuvre_entreprise_martin.pdf,Financier/Devis,Résidence Harmony Levallois,BTP & Construction,,"{\"type\":\"devis\",\"corps_etat\":\"gros_oeuvre\",\"entreprise\":\"Martin TP\",\"montant\":285000}",users:c.bernard,a.rousseau|groups:conducteurs_travaux,groups:conducteurs_travaux,direction
-./docs/projets/boulogne/pv/pv_reception_lot_3.pdf,Suivi/PV Réception,Éco-Quartier Boulogne,BTP & Construction,,"{\"type\":\"pv_reception\",\"lot\":\"3_electricite\",\"date_reception\":\"2024-02-20\",\"entreprise\":\"Elec Pro\"}",groups:conducteurs_travaux,maitrise_oeuvre,quality,groups:conducteurs_travaux
-./docs/admin/contrats/marche_public_ville_paris.pdf,Contrats & Marchés,BAUTECH Corporate,Administration,,"{\"type\":\"marche_public\",\"client\":\"Ville de Paris\",\"montant\":1200000,\"duree_mois\":18}",groups:direction,commercial,groups:direction
-./docs/technique/doe/doe_chauffage_meudon.pdf,Documentation Technique,Les Jardins de Meudon,Technique & Maintenance,,"{\"type\":\"doe\",\"lot\":\"chauffage\",\"projet\":\"meudon\",\"entreprise\":\"Thermique Plus\"}",users:tech.leader|groups:maintenance,technique,groups:technique
-```
-
----
-
-## ⚙️ Workflow d'Import
-
-### 📋 Phase 1 : Préparation (J-7)
-
-```bash
-# 1. Scan du serveur de fichiers BAUTECH
-hubdoc-tool generate-mapping /srv/bautech/documents/
-```
-
-**Résultat :**
-```
-🔍 Scanning directory: /srv/bautech/documents/
-📁 Found 14,847 files to import
-✅ Mapping file generated: mapping.csv
-📝 Edit the file to specify target folders, projets, and permissions
-```
-
-### 📋 Phase 2 : Configuration & Mapping (J-5 à J-1)
-
-**Équipe mobilisée :**
-- **Chef de Projet :** Mapping des dossiers et projets
-- **Responsable Qualité :** Définition des métadonnées  
-- **DSI :** Configuration des permissions utilisateurs
-
-**Exemple d'enrichissement CSV :**
-```csv
-# Avant (généré automatiquement)
-./srv/bautech/plans/meudon/archi/facade_sud.pdf,,,
-
-# Après (enrichi par l'équipe)  
-./srv/bautech/plans/meudon/archi/facade_sud.pdf,Les Jardins de Meudon/Plans,BAUTECH Production,"{\"type\":\"plan\",\"vue\":\"facade_sud\",\"phase\":\"exe\"}",groups:architectes,maitrise_oeuvre,groups:architectes
-```
-
-### 📋 Phase 3 : Import en Production (J-Day)
-
-```bash
-# Configuration API HubDoc
-hubdoc-tool config
-```
-
-```
-🔧 HubDoc Importer Configuration
-HubDoc API URL: https://bautech.hubdoc.sinoia.cloud/api/v1
-API Token: [HIDDEN]
-✅ Configuration saved to .hubdoc-config.json
-```
-
-```bash
-# Lancement de l'import
-hubdoc-tool import --mapping mapping_bautech_15k.csv
-```
-
----
-
-## 📈 Métriques d'Import en Temps Réel
-
-### 📊 Dashboard d'Import
-
-```
-🚀 HubDoc Import - BAUTECH Construction
-📅 Date: 15/03/2024 09:30:00
-⏱️  Durée: 2h 34m 18s
-
-📊 Progression Globale
-██████████████████████████████████████ 100%
-15,000 / 15,000 documents traités
-
-✅ Succès:        14,847 (98.98%)
-❌ Échecs:           153 (1.02%)
-⚠️  Avertissements:   89
-
-💾 Volume traité: 47.3 GB
-📈 Vitesse moy.: 97 docs/min
-🏆 Pic performance: 145 docs/min
-```
-
-### 📋 Détail par Projet
-
-```
-📁 BAUTECH Production
-   ├── Les Jardins de Meudon      ✅ 1,798/1,800 (99.9%)
-   ├── Résidence Harmony          ✅ 2,095/2,100 (99.8%)  
-   ├── Éco-Quartier Boulogne     ✅ 1,887/1,900 (99.3%)
-   ├── Villa Prestige Neuilly     ✅ 1,200/1,200 (100%)
-   ├── Administration             ✅ 3,156/3,200 (98.6%)
-   └── Technique                  ✅ 2,089/2,100 (99.5%)
-
-📁 BAUTECH Archives              ✅ 1,177/1,200 (98.1%)
-```
-
-### 🚨 Erreurs & Avertissements
-
-```
-❌ Échecs d'import (153 docs):
-  • 89x Fichiers corrompus (PDF endommagés)
-  • 34x Permissions insuffisantes (serveur source)
-  • 30x Fichiers trop volumineux (>50MB)
-
-⚠️  Avertissements (89 docs):
-  • 45x Métadonnées JSON invalides (corrigées auto)
-  • 28x Utilisateurs inexistants (permissions ignorées)  
-  • 16x Doublons détectés (suffixe ajouté)
-```
-
----
-
-## 🔧 Configuration Technique
-
-### 🌐 Architecture Déployée
-
-```
-🏢 BAUTECH Infrastructure
-│
-├── 🖥️  Serveur HubDoc Cloud
-│   ├── URL: https://bautech.hubdoc.sinoia.cloud
-│   ├── Stockage: 500GB SSD
-│   └── Backup: 3x/jour (Paris + Londres)
-│
-├── 🔐 Active Directory Integration  
-│   ├── SSO via SAML 2.0
-│   ├── Groupes: 12 corps d'état
-│   └── Sync auto utilisateurs
-│
-└── 📱 Applications
-    ├── Web App (Chrome, Edge, Safari)
-    ├── Mobile iOS/Android  
-    └── Plugin AutoCAD/Revit
-```
-
-### 👥 Gestion des Permissions
-
-```yaml
-# Configuration des groupes BAUTECH
-groups:
-  direction:
-    permissions: [read, write, admin]
-    users: [p.dubois, m.lambert, c.martin]
-    
-  conducteurs_travaux:
-    permissions: [read, write]  
-    users: [j.martin, a.rousseau, c.bernard, m.durand]
-    
-  architectes:
-    permissions: [read, write]
-    users: [s.architect, l.designer, m.urbaniste]
-    
-  bureaux_etudes:
-    permissions: [read, write]
-    users: [tech.leader, calc.struct, ing.fluides]
-    
-  sous_traitants:
-    permissions: [read]
-    users: [ext.martin, ext.elecpro, ext.thermique]
-```
-
----
-
-## 📚 Guide d'Utilisation Post-Import
-
-### 🔍 Recherche Avancée HubDoc
-
-**Fonctionnalités natives HubDoc (post-import) :**
-
-**🤖 Recherche Intelligente par IA**
-```
-# Recherche sémantique sur le contenu OCR
-"façade sud Meudon" → trouve tous les plans même sans ces mots exacts
-"devis électricité > 50000€" → utilise l'IA pour détecter montants
-"permis accordé 2024" → recherche dans le contenu OCR des documents
-```
-
-**📊 Filtres Métadonnées (enrichies par notre import)**
-```
-# Utilise les métadonnées injectées lors de l'import
-metadata.type:"plan" AND metadata.projet:"Meudon"
-metadata.entreprise:"Martin TP" AND metadata.montant:>100000
-folder:"Les Jardins de Meudon" AND status:"validé"
-```
-
-**🔍 Recherche OCR dans Documents Scannés**
-```
-# HubDoc extrait automatiquement le texte des PDF scannés
-"article 15 du CCTP" → trouve dans documents scannés
-"réception définitive" → recherche OCR multi-formats
-```
-
-### 📋 Workflows HubDoc (Post-Import)
-
-**Ce que fait notre outil d'import :**
-- ✅ Place les documents dans les bons dossiers
-- ✅ Applique les permissions read/write
-- ✅ Injecte les métadonnées initiales (projet, type, entreprise...)
-
-**Ce que fait HubDoc automatiquement après :**
-
-**🏗️ Validation de Plans**
-1. **Import** → Documents placés dans "Plans/À Classer"
-2. **IA HubDoc** → Classification automatique par type de plan
-3. **OCR** → Extraction des cotes, références, dates
-4. **Workflow** → Circuit de validation selon les règles métier
-5. **Notification** → Alerts automatiques aux équipes concernées
-6. **Indexation** → Recherche sémantique sur le contenu technique
-
-**💰 Circuit Devis** 
-1. **Import** → Documents avec métadonnées de base (entreprise, projet)
-2. **IA HubDoc** → Détection automatique des montants dans le PDF
-3. **Classification** → Tri par corps d'état et seuils de validation
-4. **Workflow** → Routage selon montant (Direction si >100k€)
-5. **OCR Avancé** → Extraction des détails techniques et prix
-6. **Signature** → Circuit d'approbation électronique intégré
-
-**🔄 Gestion Automatique des Versions**
-1. **Import initial** → Version 1.0 avec métadonnées
-2. **IA HubDoc** → Détection automatique des révisions
-3. **Liens intelligents** → Relations entre plans et devis
-4. **Historique** → Traçabilité complète des modifications
-
----
-
-## 🔄 Répartition des Rôles : Import Tool vs HubDoc
-
-### 🛠️ **HubDoc Importer** (Notre Outil)
-
-**✅ Ce qu'il fait :**
-- **Import massif** de documents existants (15k+ en quelques heures)
-- **Mapping CSV** pour organisation précise des dossiers
-- **Permissions granulaires** read/write par utilisateur/groupe
-- **Métadonnées initiales** (projet, type, entreprise, montant...)
-- **Création automatique** des dossiers et projets
-- **Gestion des erreurs** et reprise d'import
-- **Intégration API** HubDoc native
-
-**🎯 Idéal pour :**
-- Migration depuis serveurs de fichiers
-- Centralisation de documents éparpillés  
-- Setup initial avec permissions complexes
-- Import one-shot de gros volumes
-
-### 🤖 **HubDoc** (Solution Native)
-
-**✅ Ce qu'il fait automatiquement après l'import :**
-
-**🔍 Intelligence Artificielle**
-- **OCR avancé** : Extraction texte dans tous formats (PDF scannés, images, CAD)
-- **Classification IA** : Détection automatique du type de document
-- **Extraction métadonnées** : Montants, dates, références techniques
-- **Recherche sémantique** : Compréhension du contexte technique
-
-**📋 Gestion Documentaire Avancée**
-- **Plans de classement** intelligents par métier BTP
-- **Workflows automatisés** : Validation selon règles métier
-- **Gestion des versions** : Détection automatique des révisions
-- **Relations documents** : Liens intelligents plan ↔ devis ↔ PV
-
-**👥 Collaboration & Workflows**
-- **Notifications contextuelles** : Alerts selon le rôle utilisateur
-- **Signature électronique** intégrée
-- **Tableau de bord temps réel** : KPIs par projet/chantier
-- **Mobile app** : Capture et consultation terrain
-
-**🔒 Sécurité & Conformité**
-- **Traçabilité complète** : Qui, quand, quoi sur chaque document
-- **Sauvegarde cloud** haute disponibilité (99.9%)
-- **Conformité légale** : Archivage réglementaire 10 ans BTP
-- **Intégrations** : Sage, AutoCAD, logiciels métier
-
-## 🎯 Roadmap Évolutions
-
-### 🚀 **Import Tool** - Prochaines versions
-- [ ] **Import incrémental** : Synchronisation serveurs de fichiers
-- [ ] **Templates métier** : Configurations pré-définies (BTP, juridique, santé)
-- [ ] **API avancée** : Intégration directe logiciels métier
-- [ ] **Monitoring** : Dashboard temps réel des imports
-
-### 🤖 **HubDoc Native** - Évolutions continues
-- [ ] **IA générative** : Résumés automatiques de documents techniques
-- [ ] **Réalité augmentée** : Consultation plans sur chantier
-- [ ] **Prédictif** : Alertes avant expiration permis/garanties
-- [ ] **Intégration BIM** : Liaison directe maquettes numériques
-
----
-
-*Documentation générée le 15/03/2024 - HubDoc Importer v1.0.0*