# Local Office — API documents Office (programmatique)

## Emplacement dans le monorepo

Le code et la doc d’exploitation détaillée sont sous **[`services/local-office/`](../../services/local-office/README.md)** (service HTTP local, au même niveau que les autres dossiers de `services/`). L’ancien dépôt forge `git.4nkweb.com/4nk/local_office` a été **fusionné par copie de fichiers** ; le dépôt distant peut être supprimé.

## Rôle produit

| Besoin | Réponse |
|--------|---------|
| Édition **riche** navigateur / bureautique métier | **ONLYOFFICE** (couche doc-services existante) |
| **Automatisation** : upload, remplacements de texte, insertion de paragraphes dans un **docx** via HTTP + JSON | **Local Office** |
| RAG / conversations documentaires | **AnythingLLM** |

Local Office **ne remplace pas** ONLYOFFICE : il couvre les flux **programmatiques** et **intégrations tierces légères** (clé API, pas d’UI WYSIWYG intégrée ici).

## Stack technique

- **FastAPI** + **Uvicorn**
- **SQLite** pour les métadonnées des documents
- Fichiers sur disque (`STORAGE_PATH`)
- **python-docx** pour les commandes sur les docx
- Auth : en-tête **`X-API-Key`** (liste de clés dans `API_KEYS`)
- **slowapi** : rate limit par clé (`RATE_LIMIT_PER_MINUTE`)

## Variables d’environnement

| Variable | Obligatoire | Description |
|----------|-------------|-------------|
| `API_KEYS` | oui | Clés séparées par des virgules ; chaque document est rattaché à la clé qui l’a créé |
| `STORAGE_PATH` | non | Répertoire des fichiers (défaut `./data/files`) |
| `DATABASE_PATH` | non | Chemin SQLite (défaut `./data/local_office.db`) |
| `MAX_UPLOAD_BYTES` | non | Taille max upload (défaut 20 Mo) |
| `RATE_LIMIT_PER_MINUTE` | non | Plafond de requêtes par minute et par clé (défaut 60) |

Copier [`services/local-office/.env.example`](../../services/local-office/.env.example) vers `.env` **hors commit** ; ne pas commiter de secrets. Alignement possible avec la convention projet `.secrets/<env>/` pour l’injection sur l’hôte.

## Exécution

```bash
cd services/local-office
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
export API_KEYS='votre-cle'
uvicorn app.main:app --host 127.0.0.1 --port 8000
```

- OpenAPI / Swagger : `http://127.0.0.1:8000/docs` (selon hôte/port).
- Le README amont propose parfois `--host 0.0.0.0` pour tests ; en **smart_ide**, préférer **`127.0.0.1`** sur le serveur et un **reverse proxy TLS** vers l’extérieur.

## API (résumé)

Toutes les routes exigent **`X-API-Key`**.

| Méthode | Chemin | Action |
|---------|--------|--------|
| POST | `/documents` | Upload multipart (`Content-Type` correct pour docx / xlsx / pptx) |
| GET | `/documents` | Liste des documents de la clé |
| GET | `/documents/{id}` | Métadonnées |
| GET | `/documents/{id}/file` | Téléchargement |
| POST | `/documents/{id}/commands` | Commandes JSON (docx : `replaceText`, `insertParagraph`) |
| DELETE | `/documents/{id}` | Suppression |

Les répertoires `data/` sont listés dans [`services/local-office/.gitignore`](../../services/local-office/.gitignore) : données et base **locales à l’instance**.

## Intégration smart_ide

- **Orchestrateur / gateway** : router les intentions « modifier un modèle docx par script » ou « pipeline documentaire sans UI » vers cette API plutôt que vers ONLYOFFICE quand c’est suffisant.
- **Policy / OpenShell** : nommer un droit du type **accès API Local Office** (clé dédiée, réseau autorisé) dans les profils agents.
- **Déploiement** : cohérent avec [deployment-target.md](../deployment-target.md) — instance en pratique sur le **serveur** où vivent les autres services.

## Documentation détaillée (sources dans `services/local-office/docs/`)

| Fichier | Contenu |
|---------|---------|
| [services/local-office/README.md](../../services/local-office/README.md) | Installation, routes, résumé API |
| [services/local-office/docs/features/local-office-api.md](../../services/local-office/docs/features/local-office-api.md) | Fiche fonctionnelle (impacts, sécurité, déploiement) |
| [services/local-office/docs/architecture-proposal.md](../../services/local-office/docs/architecture-proposal.md) | Pistes ONLYOFFICE / hybride / WOPI |

## Voir aussi

- [system-architecture.md](../system-architecture.md) — couche **doc-services**, routage, cartographie `services/local-office/`
- [services.md](../services.md) — vue d’ensemble des services sur l’hôte