Intégration OnlyOffice

Ce document décrit l'architecture et le flux de communication pour l'intégration d'OnlyOffice dans l'application, permettant l'édition de documents directement depuis l'interface.

Principe de fonctionnement

L'intégration repose sur une communication entre quatre acteurs principaux :

Client (Navigateur) : L'utilisateur qui interagit avec l'interface.
MDF Frontend : Le conteneur qui sert les fichiers statiques et la configuration (pas l'application front qui tourne dans le navigateur).
MDF API : Le backend qui orchestre la logique, gère les fichiers et la sécurité.
OnlyOffice Document Server : Le service externe qui fournit les fonctionnalités d'édition de documents.

L'objectif est de permettre au backend (MDF API) de récupérer un document modifié depuis le serveur OnlyOffice, même lorsque ces deux services ne sont pas exposés sur le même réseau public.

Variables de configuration

Pour gérer les différents contextes réseau (public vs. interne Docker), deux variables d'environnement sont utilisées.

`ONLYOFFICE_URL`

Rôle : URL publique du serveur OnlyOffice.
Configuration : Backend ET Frontend (la même valeur est attendue).
Utilisation Backend : Rôle de sécurité. L'API vérifie que les requêtes provenant d'OnlyOffice (initiées via le front-end) contiennent bien cette URL de référence. Cela garantit que la source est légitime et correctement configurée.
Utilisation Frontend : C'est l'adresse publique du serveur OnlyOffice. Le front-end l'utilise pour charger l'éditeur et la transmet dans les requêtes vers l'API.

`ONLYOFFICE_SHADOW_URL`

Rôle : URL interne (ou shadow) du serveur OnlyOffice.
Configuration : Backend uniquement
Utilisation : C'est l'URL utilisée par le backend (MDF API) pour communiquer directement avec le serveur OnlyOffice. Dans un environnement conteneurisé, cela permet à l'API de joindre le service OnlyOffice via le réseau interne, sans passer par l'extérieur. C'est plus sécurisé, plus performant et résout les problèmes de résolution réseau (Connection Refused).

`SHADOW_API_URL`

Rôle : URL interne (ou shadow) de l'API MDF.
Configuration : Frontend uniquement
Utilisation : C'est l'URL que le front-end fournit à OnlyOffice pour que ce dernier puisse rappeler l'API MDF via le réseau interne.

Utilisation conditionnelle

Les URLs shadow (SHADOW_API_URL et ONLYOFFICE_SHADOW_URL) ne sont utilisées que si elles sont explicitement configurées.

Exemple pour `compose.yml`

services:
  mdf-api:
    environment:
      ONLYOFFICE_SHADOW_URL: http://onlyoffice # (1)
      ONLYOFFICE_URL: https://mdf.onlyoffice.local # (2)

  mdf-front:
    environment:
      ONLYOFFICE_URL: https://mdf.onlyoffice.local # (3)
      SHADOW_API_URL: http://mdf-api:8080 # (4)

URL Interne (Back-end) : Utilisée par l'API pour joindre OnlyOffice via le réseau interne.
URL Publique (Back-end) : Utilisée par l'API pour valider l'URL fournie par le front-end.
URL Publique (Front-end) : Fournie au navigateur pour charger l'éditeur OnlyOffice.
URL Interne API (Front-end) : Fournie à OnlyOffice pour les callbacks vers l'API via le réseau interne.

Flux d'interaction

Le flux commence lorsque le client reçoit l'URL publique (ONLYOFFICE_URL) du serveur OnlyOffice. C'est cette adresse, accessible depuis le réseau des utilisateurs, qui est utilisée par le navigateur pour charger l'éditeur.

Le diagramme de séquence ci-dessous illustre les étapes d'édition et de sauvegarde d'un document.

sequenceDiagram
    participant Client (Firefox)
    participant MDF FRONTEND
    participant MDF API
    participant ONLYOFFICE

    rect rgb(60, 60, 60)
    note over Client (Firefox), MDF FRONTEND: Étape 1 - Initialisation
    end
    MDF FRONTEND->>Client (Firefox): Envoi de l'URL de OnlyOffice
    Client (Firefox)->>Client (Firefox): Import d'un document Word

    rect rgb(60, 60, 60)
    note over Client (Firefox), MDF API: Étape 2 - Upload vers MDF
    end
    Client (Firefox)->>MDF API: Requête API Upload du fichier Word
    MDF API-->>Client (Firefox): Renvoi Lien fichier stocké + Token accès

    rect rgb(60, 60, 60)
    note over Client (Firefox), ONLYOFFICE: Étape 3 - Ouverture dans OnlyOffice
    end
    Client (Firefox)->>ONLYOFFICE: Envoi Lien + Token accès
    ONLYOFFICE->>MDF API: Téléchargement du fichier Word (*)
    ONLYOFFICE-->>Client (Firefox): Affiche le fichier dans la modale embarquée
    Client (Firefox)->>MDF API: Suppression du fichier temporaire

    rect rgb(60, 60, 60)
    note over Client (Firefox), ONLYOFFICE: Étape 4 - Édition et sauvegarde
    end
    Client (Firefox)->>Client (Firefox): Cliquer sur "Enregistrer"
    Client (Firefox)->>ONLYOFFICE: Demande du lien du fichier final
    ONLYOFFICE-->>Client (Firefox): Renvoi lien du fichier final

    rect rgb(60, 60, 60)
    note over Client (Firefox), MDF API: Étape 5 - Récupération du fichier final
    end
    Client (Firefox)->>MDF API: Transmet lien OnlyOffice (action initiée par le client)
    MDF API->>ONLYOFFICE: Télécharge fichier final (PDF) (**)
    MDF API-->>Client (Firefox): Renvoi du fichier final

    rect rgb(60, 60, 60)
    note over Client (Firefox), MDF API: Étape 6 - Enregistrement définitif
    end
    Client (Firefox)->>MDF API: Envoi du fichier + métadonnées (action initiée par le client)

Légende des communications

Communication Publique (*) : OnlyOffice appelle l'API MDF en utilisant l'URL de callback fournie par le front-end. Par défaut, c'est l'URL publique de l'API, mais si SHADOW_API_URL est configuré côté front, c'est cette URL interne qui est utilisée pour le callback.
Communication Interne ()** : L'API MDF appelle le serveur OnlyOffice. Par défaut, elle utilise l'URL publique (ONLYOFFICE_URL), mais si ONLYOFFICE_SHADOW_URL est configuré, c'est cette URL interne qui est prioritaire pour la communication.

Utilisation conditionnelle des URLs

Les URLs shadow (SHADOW_API_URL et ONLYOFFICE_SHADOW_URL) ne sont utilisées que si elles sont explicitement configurées. En leur absence, toutes les communications transitent par les URLs publiques.

Détail des étapes

Étape 1 : Initialisation

Le MDF FRONTEND envoie la configuration, y compris l'URL d'OnlyOffice, au client. L'utilisateur importe ensuite un document depuis son poste.

Étape 2 : Upload vers MDF

Le client envoie directement le document à MDF API, qui le stocke temporairement et retourne au client un lien sécurisé et un token d'accès.

Étape 3 : Ouverture dans OnlyOffice

Le client transmet à OnlyOffice le lien et le token nécessaires pour récupérer le document. C'est ici que SHADOW_API_URL entre en jeu : - Le serveur ONLYOFFICE utilise l'URL de callback fournie par le front-end pour télécharger le document depuis MDF API. - Si SHADOW_API_URL est configuré, cette communication se fait via le réseau interne, de manière sécurisée et performante. - Une fois le document récupéré, OnlyOffice l'affiche dans l'éditeur côté client.

Étape 4 : Édition et sauvegarde

Après modification par l'utilisateur, le client demande à ONLYOFFICE le lien du fichier finalisé. OnlyOffice renvoie ce lien au MDF FRONTEND.

Étape 5 : Récupération du fichier final

Le client transmet le lien du fichier final à MDF API.
C'est ici que le ONLYOFFICE_SHADOW_URL est crucial : l'API reçoit une URL publique (ex: https://onlyoffice.mdf.local/...) mais la remplace par l'URL interne (ex: http://onlyoffice/...) pour télécharger le fichier via le réseau interne. L'API renvoie ensuite le document final au client.

Étape 6 : Enregistrement définitif

Le client envoie une dernière fois le fichier final récupéré à MDF API, avec les métadonnées métier, pour un enregistrement permanent.

Historique des versions

Voir l'historique

Version	Changement
`3.3`	Ajout de la variable`SHADOW_API_URL` et clarification des configurations.
`3.3`	Introduction de la variable`ONLYOFFICE_SHADOW_URL`.