# Complément Excel « Muse »

Un panneau latéral dans Excel (Windows, Mac et Excel web) qui discute
avec Muse : questions sur votre classeur, formules, résumés, et actions
proposées **puis confirmées par vous**.

## Ce que fait le complément

- **Discuter** : vous posez une question en français, Muse répond en
  français simple, avec le tutoiement.
- **Voir votre classeur** : à chaque question, le panneau envoie au
  serveur le contexte du classeur — noms des feuilles, tableaux, plages
  utilisées, valeurs et formules (limitées aux petites plages). C'est ce
  qui permet de répondre sur *vos* données, pas en général.
- **Proposer, puis appliquer** : quand une modification est utile
  (créer une feuille, écrire des valeurs, poser des formules), elle
  s'affiche **d'abord en aperçu**, avec le détail. Rien n'est modifié
  tant que vous n'appuyez pas sur **Appliquer**. **Annuler** ne change
  rien.
- **Vérifier les formules** : le bouton **Vérifier les formules**
  relit les cellules modifiées par le complément et affiche, pour
  chacune, sa formule et sa valeur. Vous comparez, vous validez.
- **Partie VBA (Windows seulement)** : le script `Inject-VBA.ps1`
  importe un fichier `.bas` dans le projet VBA d'un classeur ouvert.
  C'est la partie « tout automatique » pour le VBA, que le panneau
  web ne peut pas faire tout seul.

## Nouveautés

- **Mise en page** : le complément peut mettre en forme une plage —
  gras, italique, couleur de police, couleur de fond, taille de
  police, format de nombre, largeur de colonne, hauteur de ligne.
  Comme toujours, la mise en page s'affiche d'abord en aperçu, et
  elle n'est appliquée que si vous cliquez sur **Appliquer**.
- **Graphiques et tableaux de bord** : le complément peut ajouter
  un graphique à partir d'une plage de données — colonnes groupées,
  courbe ou secteurs — avec un titre. Idéal pour transformer un
  tableau en tableau de bord en une question.
- **Classeur personnel de macros** : pour que vos macros soient
  disponibles dans **tous** vos fichiers sans réinstaller, installez
  les une fois dans le classeur personnel d'Excel. Voir le guide
  `PERSONAL-WORKBOOK.md` (création en une fois, puis import avec
  `Inject-VBA.ps1`).

## Fichiers

| Fichier | Rôle |
|---|---|
| `manifest.xml` | Manifeste de sideloading (bouton « Ouvrir Muse » dans l'onglet Accueil) |
| `taskpane.html` / `taskpane.js` / `taskpane.css` | Le panneau latéral : discussion, aperçu, vérification |
| `commands.html` / `commands.js` | Fichier de commandes du ruban (requis par le manifeste) |
| `worker.js` | Le proxy serveur (Cloudflare Worker) entre Excel et le service d'IA |
| `Inject-VBA.ps1` | Script Windows d'import VBA automatique |
| `PERSONAL-WORKBOOK.md` | Guide : macros disponibles dans tous les fichiers via le classeur personnel |
| `assets/icon-16.png`, `icon-32.png`, `icon-80.png` | Icônes du complément |

## Installer le complément (sideloading)

Le complément est déjà déployé en production :

- Panneau : `https://muse-excel-addin.pages.dev/taskpane.html`
- Serveur IA : Worker Cloudflare (adresse configurée dans `taskpane.js`)
- Manifeste : `https://muse-excel-addin.pages.dev/manifest.xml`

### Charger le complément

**Excel web :** ouvrez un classeur dans Excel web, puis
Insertion > Compléments > Mes compléments > Charger un complément
non publié, et choisissez `manifest.xml`.

**Excel Windows :** dans Excel, Insertion > Mes compléments >
Gérer mes compléments > Charger un complément non publié, et
choisissez `manifest.xml`.

Le bouton **Ouvrir Muse** apparaît dans l'onglet Accueil.

### Test en local (optionnel)

Pour tester sans la production, servez ce dossier sur le port 3000
(`npx --yes http-server -p 3000`) et remplacez temporairement les
adresses de production par `https://localhost:3000` dans
`manifest.xml` (Office accepte `localhost` en HTTP pour le test).

## Où vit la clé du service d'IA ?

**Uniquement côté serveur, jamais dans le complément.**

- Le panneau (`taskpane.js`) n'en contient aucune : il envoie juste
  votre question et le contexte du classeur au Worker.
- Le Worker (`worker.js`) lit le secret **uniquement** dans la variable
  d'environnement `XKIRO_API_KEY`, configurée comme secret du Worker
  au moment du déploiement.
- Le secret n'est jamais écrit en dur dans le code, jamais journalisé
  et jamais renvoyé au navigateur, ni dans les réponses, ni dans les
  erreurs.
- Le déploiement du Worker et la configuration de son secret sont
  faits séparément (pas dans ce dossier).

## Protection contre les abus (le Worker est public)

- CORS restreint à l'origine du complément
  (`https://muse-excel-addin.pages.dev`). Un navigateur tiers ne peut
  pas lire les réponses. Un appel direct reste possible : d'où les
  mesures suivantes.
- Jeton partagé : le panneau envoie l'en-tête `X-Muse-Token`, comparé
  au secret `MUSE_ADDIN_TOKEN` du Worker. Ce jeton est visible dans
  le code public du panneau : il bloque les appels directs à
  l'aveugle, mais ce n'est PAS une authentification utilisateur.
- Limitation de débit : 60 requêtes / heure / adresse IP (via KV).
  Au-delà, erreur 429, sans appel au modèle.
- Plafonds : requête 100 Ko max, 20 derniers messages max, contexte
  30 000 caractères max, 1 500 tokens max par réponse, modèles
  autorisés limités aux deux codés en dur dans le Worker.
- Pour une vraie authentification par utilisateur, il faudra des
  comptes utilisateurs — ce n'est pas en place pour l'instant.

## Comment ça marche, en bref

1. Vous écrivez une question, le panneau lit le classeur.
2. Question + contexte partent vers le Worker.
3. Le Worker interroge le service d'IA (modèle principal, puis modèle
   de secours si le premier répond 503) et renvoie la réponse.
4. Si la réponse propose des modifications, elles s'affichent en
   aperçu. Vous cliquez **Appliquer** (ou **Annuler**).
5. Plus tard, **Vérifier les formules** relit les cellules modifiées
   pour comparer formules et valeurs.

Erreurs possibles, en clair : « Service non configuré côté serveur »
(secret absent), « Service indisponible (erreur de configuration côté
serveur) » (secret invalide), « Modèles saturés pour le moment »
(les deux modèles ont répondu 503 — réessayez plus tard).

## Partie VBA sous Windows

```
.\Inject-VBA.ps1 -BasFile "C:\chemin\Module1.bas" -Workbook "C:\chemin\Classeur.xlsm"
```

Sans `-Workbook`, le script utilise le classeur actif d'Excel déjà
ouvert. Si Excel refuse l'import, le script explique comment activer
l'option « Accès approuvé au modèle d'objet du projet VBA »
(Fichier > Options > Centre de gestion de la confidentialité >
Paramètres des macros). N'activez cette option que si vous faites
confiance aux fichiers que vous ouvrez.

## Tester chaque partie

- **Panneau (affichage)** : ouvrez `taskpane.html` dans un navigateur
  pour vérifier la mise en page. Hors Excel, il affichera simplement
  « Ouvrez ce panneau dans Excel » — c'est normal.
- **Panneau (vrai test)** : sideloading dans Excel web ou Windows
  (voir ci-dessus), avec un petit classeur de test.
- **Code JavaScript** : `node --check taskpane.js` et
  `node --check worker.js` (le Worker est un module : le vérifier en
  le copiant avec l'extension `.mjs` si besoin).
- **Manifeste** : vérifiez que le XML est bien formé et que toutes
  les URL pointent vers la production.
- **Script VBA** : à tester sur un ordinateur Windows avec Excel
  (impossible à tester sous Linux — voir l'en-tête du script).

## Ce qui reste à faire

1. **Confirmer l'OS de l'ordinateur** (Windows, Mac ou Excel web
   seulement) : la partie injection VBA ne fonctionne que sous
   Windows avec Excel ; sous Mac ou Excel web, seul le panneau
   Office.js fonctionne.
2. **Tester le script VBA** sur l'ordinateur Windows, avec l'option
   d'accès VBA activée.
4. Remplacer les icônes `assets/` par de vraies icônes si besoin
   (celles-ci sont de simples repères).