Nicolas Cantu
ac96434351
**Motivations:** - Single canonical documentation tree under docs/; reduce drift between README copies. **Evolutions:** - Add docs/repo/ with operational guides (cron, systemd, projects, logs, docv, ia_dev, services, scripts, extension). - Replace scattered README.md files with pointers to docs/repo/*.md. - Refresh docs/README.md index and cross-links across docs/, .cursor rules/agents. - Bump ia_dev submodule to matching doc pointer commits.
85 lines
4.4 KiB
Markdown
85 lines
4.4 KiB
Markdown
# 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/`** ; la doc centralisée : [repo/service-local-office.md](../repo/service-local-office.md). 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 |
|
||
|---------|---------|
|
||
| [repo/service-local-office.md](../repo/service-local-office.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
|