From cc1caa9671ac154f00d3c8df20496ab46d360a7f Mon Sep 17 00:00:00 2001 From: Colin Maudry Date: Thu, 9 Jul 2026 16:12:11 +0200 Subject: [PATCH] =?UTF-8?q?docs(spec):=20design=20de=20la=20migration=20Da?= =?UTF-8?q?sh=203.4=20=E2=86=92=204.4=20(#101)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.8 --- .../2026-07-09-migration-dash-4-design.md | 67 +++++++++++++++++++ 1 file changed, 67 insertions(+) create mode 100644 docs/superpowers/specs/2026-07-09-migration-dash-4-design.md diff --git a/docs/superpowers/specs/2026-07-09-migration-dash-4-design.md b/docs/superpowers/specs/2026-07-09-migration-dash-4-design.md new file mode 100644 index 0000000..fbfe694 --- /dev/null +++ b/docs/superpowers/specs/2026-07-09-migration-dash-4-design.md @@ -0,0 +1,67 @@ +# Migration Dash 3.4 → 4.4 — Design (#101) + +> Statut : design validé le 2026-07-09. Prêt pour le plan d'implémentation. +> Issues liées : #101 (cette migration), #41 (AG Grid, suite), #111 (serveur MCP, nécessite Dash ≥ 4.3). + +## 1. Objectif & périmètre + +Monter la dépendance `dash` de **3.4.0 à 4.4.x**, sans changement fonctionnel de l'application. + +**Dans le périmètre :** + +- Consolidation et bump de la déclaration `dash` dans `pyproject.toml`. +- Validation et, si nécessaire, bump des libs de l'écosystème Dash (`dash-leaflet`, `dash-extensions`, `dash[testing]`). +- Acceptation du nouveau style des composants DCC de Dash 4 ; retrait du CSS custom qui entre en conflit. +- Corrections des cassures fonctionnelles éventuelles. + +**Hors périmètre (issues dédiées) :** + +- Migration DataTable → AG Grid → **#41**. Les `dash_table.DataTable` restent en place. Elles sont dépréciées mais fonctionnelles en Dash 4.x (retrait prévu seulement en Dash 5.0). +- Serveur MCP des données sous auth → **#111** (nécessite Dash ≥ 4.3, donc cette migration en est le prérequis). +- Toute nouvelle fonctionnalité tirant parti de Dash 4. + +## 2. Contexte technique constaté + +- `pyproject.toml` déclare `dash` de façon dédoublée : `"dash==3.4.0"` **et** `"dash[compress]"` (non épinglé). À consolider. +- Version installée : `dash` 3.4.0, `dash-bootstrap-components` 2.0.4, `dash-leaflet` 1.1.3, `dash-extensions` 2.0.5. +- **Aucun** usage de `run_server`, `long_callback`, `LogoutButton`, `_set_react_version` dans `src/` ni `run.py` → les ruptures Dash 3.0 sont déjà absorbées. React 18.3.1 est déjà le défaut depuis Dash 3. +- Composants DCC utilisés que Dash 4 restyle : `dcc.Dropdown` (×11, filtres et sélecteurs de colonnes), `dcc.Input` (×23), `dcc.Loading` (×5), `dcc.Checklist` (×2), `dcc.RadioItems` (×1). Pas de `Slider`, `DatePicker`, `Tabs`, `TextArea` → surface visuelle limitée. +- `DataTable` est utilisé dans `recherche`, `tableau`, `acheteur`, `titulaire`, `observatoire`, `admin/liste`, et sous-classé dans `src/figures.py` (`class DataTable(dash_table.DataTable)`). `src/utils/table_sql.py` traduit le DSL de filtre DataTable en SQL DuckDB. Tout cela reste inchangé (relève de #41). + +## 3. Décisions de design + +- **Régressions visuelles : accepter le look Dash 4.** On ne corrige que les cassures fonctionnelles (débordement, illisibilité, comportement rompu). Le CSS custom qui entre en conflit avec le restyling DCC est **retiré** plutôt que patché. +- **Épinglage :** pin exact sur la dernière 4.4.x, cohérent avec le style actuel (`dash==3.4.0`). Ligne consolidée en `"dash[compress]==4.4.x"`. +- **Bump des libs tierces : seulement si nécessaire.** On ne monte `dash-leaflet` / `dash-extensions` que si la compat Dash 4 l'exige. +- **Approche de séquencement : bump groupé (A), dans un worktree isolé basé sur `dev`.** Une seule PR. Justifié par le périmètre contenu et l'absence de ruptures majeures. + +## 4. Étapes d'implémentation (haut niveau) + +Le détail sera produit par le skill `writing-plans`. Séquence prévue : + +1. **Validation de compat (premier, car seul vrai risque).** Dans le worktree : consolider/bumper `dash` dans `pyproject.toml`, `uv sync`, `uv run run.py`. Observer la résolution des dépendances et le démarrage. Point le plus à risque : les cartes **Leaflet** (`dash-leaflet` + clustering via `dash-extensions`). Bumper ces libs si cassées. + - Si un blocage dur apparaît (lib tierce sans release compatible Dash 4), **arrêt et réévaluation** avant d'aller plus loin. +2. **Corrections fonctionnelles.** Vérifier les 11 `dcc.Dropdown` face aux nouveaux défauts Dash 4 (`optionHeight='auto'`, `closeOnSelect` distinct en multi-select) ; corriger uniquement si comportement cassé. +3. **Nettoyage CSS.** Retirer de `src/assets/css/` les overrides devenus inutiles ou cassants suite au restyling DCC. +4. **Alignement `dash[testing]`** sur la même version dans le groupe `dev`. + +## 5. Vérification (definition of done) + +- `pre-commit` exécuté (ruff) avant tout `git add` / commit (cf. CLAUDE.md). +- `uv run pytest` vert (suite pytest/Selenium, nécessite Chrome/Chromium). +- `uv run run.py` démarre l'app sans erreur. +- Smoke test manuel local des 6 pages principales : `/`, `/acheteur`, `/titulaire`, `/tableau`, `/marche`, `/observatoire`, **plus** cartes Leaflet et exports (xlsx/csv). + +## 6. Livraison + +- Worktree isolé basé sur `dev` → une PR vers `dev`. +- Le merge dans `dev` déclenche l'auto-deploy vers **test.colibre.fr** (validation en conditions réelles = bonus, hors DoD strict). + +## 7. Risques & mitigations + +| Risque | Mitigation | +| ------------------------------------------------------- | ---------------------------------------------------------------------------------- | +| `dash-leaflet` / `dash-extensions` incompatibles Dash 4 | Étape 1 le révèle tôt ; bump ciblé ; blocage dur → réévaluation avant de continuer | +| Régressions des cartes non couvertes par les tests | Smoke manuel explicite dans la DoD (cartes Leaflet) | +| CSS custom cassant un composant DCC restylé | Retrait de l'override plutôt que patch | +| Conflits de peer-dependencies (React/Dash) à `uv sync` | Détectés à l'étape 1 ; résolus par alignement des versions écosystème |