smart_ide/docs/API/local-office.md

API — local-office

Service FastAPI : gestion de fichiers Office (upload, liste, métadonnées, téléchargement, commandes sur docx, suppression). Auth par clé API, pas Bearer.

• Code : services/local-office/
• Doc fonctionnelle : features/local-office.md
• OpenAPI : GET http://<host>:<port>/docs (ex. port 8000 en run local)

Authentification

Toutes les routes documentées ici exigent :

X-API-Key: <une des clés listées dans API_KEYS>

Les clés sont définies côté serveur (variable API_KEYS, liste séparée par virgules). Chaque document est associé à la clé qui l’a créé ; accès aux ressources d’un autre propriétaire renvoie 404.

Rate limiting : requêtes limitées par clé (slowapi, voir RATE_LIMIT_PER_MINUTE).

Préfixe des routes

Le routeur est monté sous /documents (pas de préfixe /api).

Endpoints

POST /documents

Upload multipart d’un fichier Office.

• En-têtes : X-API-Key ; pour la partie fichier, Content-Type doit être l’un des types autorisés :
  • application/vnd.openxmlformats-officedocument.wordprocessingml.document (docx)
  • application/vnd.openxmlformats-officedocument.spreadsheetml.sheet (xlsx)
  • application/vnd.openxmlformats-officedocument.presentationml.presentation (pptx)

Réponse 201

{
  "document_id": "string",
  "name": "string",
  "mime_type": "string",
  "size": number
}

Erreurs : 400 type non supporté ; 413 fichier trop volumineux (MAX_UPLOAD_BYTES).

GET /documents

Liste les documents de la clé.

Réponse 200 : tableau d’objets métadonnées (structure définie par le stockage SQLite — champs typiques : id, nom, mime, taille, dates).

GET /documents/{document_id}

Métadonnées d’un document (propriétaire = clé courante).

Erreurs : 404 si absent ou non propriétaire.

GET /documents/{document_id}/file

Téléchargement du fichier binaire ; Content-Type et nom de fichier alignés sur les métadonnées.

POST /documents/{document_id}/commands

Applique une liste de commandes au contenu. Implémenté pour docx uniquement ; xlsx/pptx renvoient 400 (« not implemented yet »).

Corps JSON

{
  "commands": [
    {
      "type": "replaceText",
      "search": "texte à chercher",
      "replace": "remplacement"
    },
    {
      "type": "insertParagraph",
      "text": "nouveau paragraphe",
      "position": "end"
    }
  ]
}

type	Champs	Description
replaceText	search (non vide), replace	Première occurrence remplacée dans paragraphes / tableaux
insertParagraph	text, position optionnel end (défaut) ou start	Insère un paragraphe

Réponse 200 : { "document_id", "size" } (taille après écriture).

Erreurs : 400 commande ou MIME invalide ; 404 document absent ou autre clé.

DELETE /documents/{document_id}

Supprime métadonnées et fichier.

Réponse 204 sans corps.

Erreurs : 404 si absent ou non propriétaire.

Variables d’environnement (rappel)

Variable	Rôle
API_KEYS	Liste de clés autorisées (obligatoire en production)
STORAGE_PATH	Fichiers sur disque
DATABASE_PATH	SQLite métadonnées
MAX_UPLOAD_BYTES	Taille max upload
RATE_LIMIT_PER_MINUTE	Plafond requêtes / minute / clé

Voir services/local-office/.env.example.