Rapport pour initialiser une knowledge base Confluence

Contexte

Ce document sert de base pour ouvrir une knowledge base Confluence sur le projet Heriade Addin.

Périmètre relu dans ce rapport :

• dépôt heriade-addin
• documentation VitePress déjà présente
• code frontend addin/
• code backend back/

Date de lecture : 2026-04-08

Résumé rapide

Le projet est déjà à un stade utilisable en pilote.

Le coeur produit existe :

• add-in Excel en Vue 3 + Office.js
• authentification Supabase
• backend NestJS avec séparation auth / addin
• import CSV
• connexion à des bases externes
• configuration de vues pivot
• collage dans Excel
• mode dynamique avec paramètres modifiables dans la feuille
• presets et préférences utilisateur

Le sujet principal n'est plus "est-ce qu'on a un produit ?", mais plutôt :

• formaliser la vision
• clarifier le périmètre supporté
• durcir le backend pour un usage plus large
• structurer la roadmap produit
• documenter le run et les cas d'usage

1. Vision projet

Vision courte

Heriade Addin permet de construire dans Excel des vues de type pivot à partir de sources métier externes, sans sortir de l'usage Excel des équipes.

Problème adressé

Aujourd'hui, pour exploiter des données métiers dans Excel, les utilisateurs passent souvent par :

• des exports manuels
• des copier-coller instables
• des tableaux peu traçables
• des fichiers difficiles à maintenir quand la donnée change

Le projet répond à ce besoin avec une approche simple :

• l'utilisateur se connecte à Heriade
• choisit une source de données
• configure sa vue dans le panneau
• colle le résultat dans Excel
• peut réutiliser la vue via presets et modes de rafraîchissement

Promesse produit

• rester dans Excel
• brancher des données externes sans montage technique lourd côté utilisateur
• produire des vues réutilisables
• garder un lien entre la donnée source, les filtres et le rendu dans la feuille

2. Ce qui est déjà fait

Parcours utilisateur confirmé

Les éléments ci-dessous sont présents dans le code et la doc projet.

Authentification et contexte utilisateur

• login via Supabase côté add-in
• injection du JWT dans les appels API
• vérification du token côté backend
• rattachement à un profil, une enterprise, un environnement et une application
• affichage du profil utilisateur dans le task pane

Gestion des données source

• import de fichiers CSV
• stockage de métadonnées d'environnement et de table dans le classeur Excel
• stockage de données importées dans des feuilles cachées
• connexion à des bases externes via le backend
• lecture de tables distantes pour alimenter une vue

Construction de la vue pivot

• sélection d'un environnement et d'une table
• aperçu des données source
• glisser-déposer des champs dans les zones En-tête / Lignes / Colonnes
• filtres par valeurs et filtres numériques min/max
• aperçu temps réel du résultat
• unpivot automatique si plusieurs mesures sont sélectionnées

Insertion dans Excel

• collage du résultat dans la feuille active
• création d'un vrai tableau structuré Excel
• mode dynamique avec cellules paramètres modifiables dans la feuille
• mode figé pour produire une vue statique
• pour les sources BDD : refresh auto ou manuel
• bloc "Filtres actifs" écrit dans la feuille
• note de source "Données générées par Heriade Addin"
• renommage automatique ou manuel de feuille
• export CSV du résultat

Réutilisation

• presets sauvegardés côté serveur avec fallback local
• préférences utilisateur
• restauration de session
• réattache automatique de session dynamique si le classeur est rouvert

Backend déjà en place

Le backend expose déjà trois briques métier principales :

Module	Rôle
addin-preset	profil courant, presets, préférences
external-db	CRUD des connexions externes
data-pivot	lecture des bases et récupération des lignes

Le calcul du pivot reste côté add-in. Le backend sert surtout à :

• sécuriser l'accès
• gérer les connexions externes
• servir les données brutes
• persister presets et préférences

Qualité déjà présente

• documentation développeur et utilisateur déjà en place dans docs/
• séparation claire frontend / backend / SQL
• moteur pivot testé côté add-in
• services critiques couverts par des tests unitaires

Vérification rapide faite pendant cette lecture

• 16 suites de tests add-in passent
• 181 tests passent
• aucune suite backend visible dans ce dépôt extrait

3. Architecture technique actuelle

Vue d'ensemble

Couche	Techno	Rôle
Runtime Excel	Office.js	interaction avec le classeur, écoute des changements
Frontend add-in	Vue 3 + TypeScript + Webpack	UI, logique de config, moteur pivot, écriture Excel
Auth frontend	Supabase JS	login, refresh token, gestion session
Backend API	NestJS 11	auth backend, accès données, persistance
ORM	Prisma 6	accès db_auth et db_addin
Bases	PostgreSQL	auth partagée + base dédiée add-in

Frontend

Le frontend est organisé en 4 couches lisibles :

• shared/ : auth, client API, cache, utilitaires transverses
• services/ : pivot engine, écriture Excel, session dynamique, parsing CSV, accès BDD
• composables/ : état Vue et orchestration écran
• components/ : UI du task pane

Le point fort ici est que le calcul pivot et la logique Excel sont bien séparés.

Backend

Le backend repose sur :

• NestJS
• un AuthGuard commun
• un PrismaService avec deux clients
• des modules métiers simples par domaine

Deux bases sont distinguées :

Base	Usage
db_auth	utilisateurs, profils, entreprises, environnements, applications
db_addin	connexions externes, presets, préférences

Persistance côté Excel

Le classeur stocke déjà plusieurs choses :

• contexte du dernier environnement / table utilisé
• environnement et tables connues
• données source dans des feuilles cachées
• session de pivot dynamique dans workbook.settings

Choix d'architecture important

Le choix actuel est cohérent :

• le backend sert la donnée et la sécurité
• le frontend garde le moteur pivot et l'expérience Excel

Ce choix accélère l'itération produit, mais impose d'être attentif à :

• la volumétrie des données remontées dans l'add-in
• les performances Excel quand les vues grossissent
• la sécurité des endpoints backend

4. Points à consolider

Cette partie correspond au "à faire" technique le plus crédible à court terme.

4.1 Documentation et cadrage

Il manque encore une base claire pour un usage équipe / direction :

• une page "vision produit"
• une page "périmètre actuel"
• une page "roadmap"
• une page "architecture"
• une page "run / support / debug"

Le dépôt contient déjà beaucoup de matière, mais elle est encore répartie entre README, docs/dev, docs/user et quelques tickets.

4.2 Tests backend

Le gap le plus visible côté qualité est l'absence de suite de tests backend dans ce dépôt.

À faire :

• tests unitaires des services NestJS
• tests d'intégration des controllers clés
• tests auth sur les cas multi-tenant

4.3 Durcissement sécurité / prod

En l'état, il y a quelques sujets à traiter avant un déploiement large :

• CORS ouvert dans back/src/main.ts
• Swagger exposé sans condition d'environnement
• plusieurs endpoints external-db sans @UseGuards(AuthGuard)
• pas de stratégie visible de rate limiting

Le dépôt contient aussi un audit sécurité daté du 2026-03-11. Il faut le relire avec recul, car une partie de ses findings semble viser un scope plus large que ce dépôt extrait.

4.4 Clarification du périmètre supporté

Quelques points méritent d'être posés noir sur blanc :

• volumétrie max supportée par vue
• dialectes officiellement supportés en prod
• limites du mode dynamique
• comportement attendu quand l'add-in n'est pas installé
• règles de nommage et de partage des presets

5. Projection proposée

Je n'ai pas trouvé de roadmap produit officielle dans le dépôt. La projection ci-dessous est donc une proposition de travail à valider avec l'équipe.

6. Epics proposés

Epic 1. Cadrage produit et base de connaissance

But :

• poser une vision commune
• rendre le projet lisible pour produit, tech et métier

Contenu :

• page vision
• page périmètre actuel
• page architecture
• page cas d'usage
• page backlog / roadmap
• page support et debug

Epic 2. Stabilisation pilote

But :

• rendre l'existant fiable pour un pilote interne ou client cadré

Contenu :

• campagne de validation fonctionnelle sur les 5 tickets déjà documentés
• correction des écarts restants
• revue de performance sur gros jeux de données
• politique de gestion des erreurs côté Excel

Epic 3. Durcissement backend

But :

• rendre le backend propre pour une exposition plus large

Contenu :

• protection de tous les endpoints sensibles
• configuration CORS par origine
• Swagger hors production
• rate limiting
• revue des connexions manuelles aux BDD externes

Epic 4. Gouvernance des sources et des vues

But :

• mieux gérer l'usage équipe

Contenu :

• conventions de nommage
• partage ou duplication de presets
• règles par environnement
• clarification des rôles et droits

Epic 5. Industrialisation Excel

But :

• faire du tableau collé une vraie base de travail dans Excel

Contenu :

• stabilité des tables nommées
• bonnes pratiques pour rapports Excel liés
• documentation TCD natif / graphiques / formules
• stratégie de rafraîchissement par usage

7. Proposition MVP0

Positionnement

MVP0 = version prête pour un pilote propre, avec périmètre assumé et doc claire.

Ce que MVP0 doit contenir

• login et contrôle d'accès OK
• import CSV OK
• lecture BDD externe OK
• config pivot OK
• collage dans Excel OK
• mode dynamique et mode figé OK
• presets OK
• documentation de base OK
• sécurisation backend minimale OK

Livrables MVP0

• knowledge base Confluence initialisée
• validation des 5 tickets déjà décrits dans docs/tickets
• correction des sujets sécurité les plus simples
• README / setup / architecture remis au propre
• premier guide support

Définition de done MVP0

• un nouvel arrivant peut comprendre le projet en moins de 30 minutes
• un utilisateur pilote peut construire une vue sans aide dev
• le backend n'expose plus d'endpoint sensible non protégé
• le périmètre supporté est écrit noir sur blanc

8. Proposition MVP1

Positionnement

MVP1 = version prête pour élargir l'usage, avec un niveau plus propre côté exploitation, sécurité et adoption.

Ce que MVP1 ajoute

• tests backend
• observabilité minimale
• stratégie claire de support et incidents
• gouvernance des presets et des environnements
• documentation d'exploitation
• cadrage performance sur volumétrie réelle

Livrables MVP1

• suite de tests backend
• checklist de mise en prod
• règles d'usage par type de source
• documentation admin pour installation et support
• politique de refresh selon les cas métier

9. Proposition de structure Confluence

Voici une structure simple pour démarrer sans surdocumenter.

1. Vision

Contenu :

• problème adressé
• cible utilisateur
• promesse produit
• périmètre actuel
• hors périmètre

2. Produit

Contenu :

• parcours utilisateur
• fonctions déjà livrées
• limites connues
• exemples de cas d'usage

3. Architecture

Contenu :

• vue d'ensemble
• frontend add-in
• backend
• auth
• stockage Excel
• schémas Prisma

4. Setup et exploitation

Contenu :

• setup local
• variables d'environnement
• sideload manifest
• debug courant
• procédure de test

5. Roadmap

Contenu :

• epics
• MVP0
• MVP1
• risques et dépendances

10. Risques à garder en tête

• le moteur pivot tourne côté add-in, donc la volumétrie doit être surveillée
• le backend est fonctionnel mais doit être durci avant montée en charge
• la doc existe déjà, mais elle n'est pas encore organisée comme une base de connaissance transverse
• la roadmap n'est pas formalisée dans le dépôt, donc elle doit être validée avec produit et tech

11. Recommandation courte

Le bon angle pour Confluence n'est pas de repartir de zéro.

Il faut :

1. reprendre l'existant déjà solide
2. le réorganiser en pages produit / tech / run
3. afficher un MVP0 centré sur stabilisation et cadrage
4. garder MVP1 pour industrialisation et déploiement large

Sources principales relues

• README.md
• docs/dev/architecture.md
• docs/dev/backend/modules.md
• docs/dev/backend/auth.md
• docs/dev/backend/database.md
• docs/dev/testing.md
• docs/user/*.md
• docs/tickets/*.md
• addin/src/taskpane/App.vue
• addin/src/taskpane/components/NewViewDialog/NewViewDialog.vue
• addin/src/taskpane/composables/usePivotConfig.ts
• addin/src/taskpane/composables/useExcelActions.ts
• addin/src/taskpane/services/excelWriter.ts
• addin/src/taskpane/services/dynamicPivotManager.ts
• addin/src/taskpane/services/storageManager.ts
• back/src/app.module.ts
• back/src/main.ts
• back/src/common/guards/authGuard.ts
• back/src/data-pivot/*
• back/src/external-db/*
• back/src/addin-preset/*