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/<env>/.
- HTTPS uniquement : Pas d’alternative HTTP en production (règles projet).
7. Ordre d’implémentation suggéré
- Gateway : reverse proxy, auth par clé API, rate limit, CORS.
- Stockage : écriture/lecture fichiers + métadonnées minimales (document_id, clé API, nom, type).
- API REST : upload, GET file, DELETE ; pas encore d’édition.
- Moteur d’édition programmatique : interpréteur de commandes + librairies Office pour au moins un format (ex. docx).
- Endpoint commandes :
POST /documents/:id/commands branché sur le moteur.
- Conversion : si besoin (ex. docx → PDF via librairie ou service dédié).
- Serveur document + page hôte : édition WYSIWYG pour les tiers.
- 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.
Nicolas Cantu
088eab84b7