docs(spec): design de la migration Dash 3.4 → 4.4 (#101)
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Colin Maudry
@@ -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 |
|
||||||
Reference in New Issue
Block a user