Nicolas Cantu
088eab84b7
- Add ia_dev submodule (projects/smart_ide on forge 4nk) - Document APIs, orchestrator, gateway, local-office, rollout - Add systemd/scripts layout; relocate setup scripts - Remove obsolete nginx/enso-only docs from this repo scope
204 lines
13 KiB
Markdown
204 lines
13 KiB
Markdown
# 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é
|
||
|
||
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.
|