# 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/`](../../services/local-office/)
- **Doc fonctionnelle** : [features/local-office.md](../features/local-office.md)
- **OpenAPI** : `GET http://<host>:<port>/docs` (ex. port `8000` en run local)

## Authentification

Toutes les routes documentées ici exigent :

```http
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`**

```json
{
  "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**

```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`](../../services/local-office/.env.example).