# Architecture proposée — Instance d’édition de fichiers Office pour applications tierces **Contexte** : Une instance permettant à des applications tierces de modifier des fichiers Office (Word, Excel, PowerPoint) en ligne. **Objectif** : Exposer un service consommable par des logiciels externes (API et/ou éditeur embarqué), avec stockage et édition des documents. --- ## 1. Scénarios d’usage | Scénario | Acteur | Besoin | |----------|--------|--------| | Modification programmatique | App tierce (backend) | Envoyer un fichier + opérations (remplacer texte, insérer paragraphe, fusionner cellules…), récupérer le fichier modifié | | Édition dans le navigateur | App tierce (frontend) | Ouvrir un document dans un éditeur WYSIWYG (iframe), sauvegarder les modifications | | Conversion | App tierce | Convertir Office → PDF / HTML ou inversement | | Ouverture via Office Online | Utilisateur final | Éditer un fichier hébergé par l’instance via Microsoft Office Online (WOPI) | --- ## 2. Options d’architecture ### Option A — Serveur document (ONLYOFFICE / Collabora) - **Principe** : Déployer un serveur document (Docker) ; les tiers intègrent l’éditeur (iframe) ou utilisent l’API du serveur. - **Pour** : Fidélité Office, édition collaborative, conversion intégrée. - **Contre** : Ressources importantes, licence à clarifier (ONLYOFFICE AGPL, Collabora), moindre contrôle sur le modèle API métier. ### Option B — API métier + librairies d’édition - **Principe** : Backend unique qui reçoit des fichiers Office et des commandes (JSON), applique les modifications via des librairies (python-docx, openpyxl, etc.), renvoie le fichier modifié. Pas d’éditeur WYSIWYG. - **Pour** : Léger, maîtrise totale de l’API, pas de dépendance à un serveur document. - **Contre** : Pas d’édition visuelle dans le navigateur. ### Option C — Hybride (recommandé) - **API métier** pour les modifications programmatiques (scénario 1 et 3). - **Serveur document** (ONLYOFFICE ou Collabora) pour l’édition en ligne (scénario 2), appelé par l’instance. - **Optionnel** : implémentation WOPI pour le scénario 4. --- ## 3. Architecture proposée (option C) ``` ┌─────────────────────────────────────────────────────────┐ │ Applications tierces │ │ (backend API, frontend iframe, scripts) │ └───────────────────────────┬─────────────────────────────┘ │ HTTPS ▼ ┌───────────────────────────────────────────────────────────────────────────────┐ │ GATEWAY / REVERSE PROXY │ │ Auth (API key / JWT), rate limit, routage, TLS │ └───────────────────────────┬───────────────────────────────────────────────────┘ │ ┌───────────────────┼───────────────────┐ ▼ ▼ ▼ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │ API REST │ │ Page hôte │ │ (Optionnel) │ │ documents │ │ éditeur │ │ Endpoints │ │ │ │ (iframe) │ │ WOPI │ └───────┬───────┘ └───────┬───────┘ └───────┬───────┘ │ │ │ ▼ ▼ ▼ ┌───────────────────────────────────────────────────────────────┐ │ COUCHE MÉTIER DOCUMENTS │ │ • Gestion sessions / documents (CRUD, versioning optionnel) │ │ • Commandes d’édition (texte, paragraphes, cellules, etc.) │ │ • Conversion (Office ↔ PDF/HTML si nécessaire) │ └───────┬─────────────────────────────┬─────────────────────────┘ │ │ ▼ ▼ ┌───────────────────┐ ┌───────────────────┐ │ Moteur d’édition │ │ Serveur document │ │ programmatique │ │ (ONLYOFFICE ou │ │ (librairies │ │ Collabora) │ │ Office) │ │ pour WYSIWYG │ └───────┬───────────┘ └───────┬───────────┘ │ │ └─────────────┬───────────────┘ ▼ ┌─────────────────────────────┐ │ STOCKAGE FICHIERS │ │ (fichier système / S3) │ │ + métadonnées (DB optionnelle) │ └─────────────────────────────┘ ``` --- ## 4. Briques à implémenter ### 4.1 Gateway et exposition | Brique | Rôle | Détail | |--------|------|--------| | Reverse proxy | Terminaison TLS, routage par chemin ou sous-domaine | Nginx (ou Caddy) devant l’API et la page hôte | | Authentification API | Identifier les applications tierces | Clés API (header) ou JWT ; pas de session utilisateur obligatoire pour l’API pure | | Rate limiting | Limiter les abus par clé / IP | Règles dans le proxy ou dans l’API | | CORS | Autoriser les appels depuis les frontends tiers | En-têtes CORS configurés sur l’API et la page hôte | ### 4.2 API REST documents | Brique | Rôle | Détail | |--------|------|--------| | Upload document | Déposer un fichier Office | `POST /documents` multipart ; retourne un `document_id` | | Téléchargement | Récupérer le fichier courant ou une version | `GET /documents/:id/file` | | Commandes d’édition | Modifications programmatiques | `POST /documents/:id/commands` avec payload JSON (liste d’opérations) | | Conversion | Office → PDF / HTML ou inverse | `POST /documents/:id/convert` ou endpoint dédié | | Métadonnées | Liste, statut, versions | `GET /documents/:id`, `GET /documents` (liste), optionnel `GET /documents/:id/versions` | | Suppression | Nettoyage | `DELETE /documents/:id` | **Modèle de commandes (exemple)** : ordre d’opérations appliquées séquentiellement (ex. `replaceText`, `insertParagraph`, `mergeCells`, `setCellValue`), avec paramètres par type. ### 4.3 Moteur d’édition programmatique | Brique | Rôle | Détail | |--------|------|--------| | Parsing / écriture Office | Lire et modifier docx, xlsx, pptx sans interface graphique | Librairies selon stack : **Python** (python-docx, openpyxl, python-pptx) ou **Node** (docx, xlsx, pptxgenjs ou équivalents) | | Interpréteur de commandes | Transformer le JSON de commandes en appels librairie | Un module par type de document (document, spreadsheet, presentation) ; validation des paramètres et erreurs explicites | | Gestion des erreurs | Cohérence et traçabilité | Pas de fallback silencieux ; erreurs typées, logs structurés, codes HTTP adaptés | ### 4.4 Édition en ligne (WYSIWYG) | Brique | Rôle | Détail | |--------|------|--------| | Serveur document | Éditeur riche dans le navigateur | ONLYOFFICE Document Server ou Collabora Online (Docker) | | Connecteur instance ↔ serveur document | Créer une session d’édition, fournir l’URL du fichier, recevoir les sauvegardes | Appel à l’API du serveur document (JWT si ONLYOFFICE) ; callback de sauvegarde vers l’instance | | Page hôte éditeur | Page fournie aux tiers pour intégration en iframe | URL avec `document_id` (+ token) ; page charge la config d’éditeur et l’iframe vers le serveur document | | Callback de sauvegarde | Récupérer le fichier modifié après édition | Endpoint appelé par le serveur document ; enregistrer dans le stockage et invalider/renouveler l’URL d’édition si besoin | ### 4.5 Stockage | Brique | Rôle | Détail | |--------|------|--------| | Stockage fichiers | Fichiers Office et dérivés (PDF, etc.) | Répertoire local ou stockage S3-compatible ; chemin dérivé de `document_id` | | Métadonnées (optionnel) | Nom, type MIME, taille, date, lien propriétaire (app tierce) | Base relationnelle ou clé-valeur ; index pour lister par clé API / utilisateur | | Versioning (optionnel) | Historique des versions pour rollback ou audit | Nouveau fichier par version, métadonnées avec `version_id` | ### 4.6 Optionnel — WOPI | Brique | Rôle | Détail | |--------|------|--------| | Endpoints WOPI | CheckFileInfo, GetFile, PutFile, etc. | Implémenter le protocole WOPI pour que Office Online ou un client compatible édite les fichiers hébergés par l’instance | | Page hôte WOPI | Page qui héberge l’iframe Office Online avec token | Génération de l’URL d’action et du token d’accès fichier | | Découverte WOPI | XML de discovery | Endpoint exposant les actions et capacités pour les clients WOPI | À envisager seulement si l’objectif est l’intégration avec Microsoft 365 / Office Online. --- ## 5. Stack technique suggérée - **API** : Node.js (TypeScript) ou Python (FastAPI) selon compétences et écosystème des librairies Office. - **Proxy** : Nginx (déjà en place sur l’infra 4NK). - **Stockage** : Fichier local ou MinIO/S3 selon la cible de déploiement. - **Base métadonnées** : PostgreSQL ou SQLite selon volume et besoins de requêtes. - **Serveur document** : ONLYOFFICE Document Server (Docker) ou Collabora (Docker), communiqué via réseau interne au proxy. - **Auth** : Clés API en base ou config ; JWT si besoin de délégation fine (éditeur embarqué avec session courte). --- ## 6. Sécurité et contraintes - **Isolation** : Un document est lié à une clé API (ou utilisateur) ; pas d’accès cross-tenant sans autorisation explicite. - **Validation des entrées** : Taille max des fichiers, types MIME autorisés, validation stricte des commandes (schéma JSON). - **Secrets** : Pas de secret dans le dépôt ; configuration via variables d’environnement ou `.secrets//`. - **HTTPS uniquement** : Pas d’alternative HTTP en production (règles projet). --- ## 7. Ordre d’implémentation suggéré 1. **Gateway** : reverse proxy, auth par clé API, rate limit, CORS. 2. **Stockage** : écriture/lecture fichiers + métadonnées minimales (document_id, clé API, nom, type). 3. **API REST** : upload, GET file, DELETE ; pas encore d’édition. 4. **Moteur d’édition programmatique** : interpréteur de commandes + librairies Office pour au moins un format (ex. docx). 5. **Endpoint commandes** : `POST /documents/:id/commands` branché sur le moteur. 6. **Conversion** : si besoin (ex. docx → PDF via librairie ou service dédié). 7. **Serveur document + page hôte** : édition WYSIWYG pour les tiers. 8. **Optionnel** : WOPI si besoin d’intégration Office Online. --- ## 8. Synthèse des briques | # | Brique | Couche | Priorité | |---|--------|--------|----------| | 1 | Reverse proxy (Nginx) + TLS | Gateway | P0 | | 2 | Authentification API (clés / JWT) | Gateway | P0 | | 3 | Rate limiting + CORS | Gateway | P0 | | 4 | Stockage fichiers + métadonnées | Stockage | P0 | | 5 | API REST (upload, GET, DELETE) | API | P0 | | 6 | Moteur d’édition programmatique (commandes) | Métier | P0 | | 7 | Endpoint commandes + conversion | API | P1 | | 8 | Serveur document (ONLYOFFICE/Collabora) | Édition en ligne | P1 | | 9 | Connecteur + page hôte + callback sauvegarde | Édition en ligne | P1 | | 10 | Versioning (optionnel) | Stockage | P2 | | 11 | WOPI (optionnel) | Édition en ligne | P2 | **P0** : indispensable pour une première version « applications tierces modifient des fichiers Office via API ». **P1** : nécessaire pour l’édition en ligne dans le navigateur. **P2** : optionnel selon les besoins métier.