Colin Maudry
1229 lines
56 KiB
Markdown
1229 lines
56 KiB
Markdown
# Migration AG Grid — `acheteur.py` + `titulaire.py` (Lot 2a) — Implementation Plan
|
|
|
|
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
|
|
|
**Goal:** Remplacer les `dash_table.DataTable` des pages `/acheteurs/<id>` et `/titulaires/<id>` par des grilles `dash-ag-grid`, en factorisant la logique commune dans un module partagé et en réutilisant au maximum l'infrastructure AG Grid du Lot 1 (`tableau.py`).
|
|
|
|
**Architecture:** Un nouveau module `src/utils/entity_grid.py` porte toute la logique de grille scopée à une entité (fonctions pures testables + une fabrique de callbacks appelée une fois par page). Chaque grille a un `id` **pattern-matching** (`{"type": "<org>-grid", "entity_id": ..., "year": ...}`) pour scoper la persistance du `filterModel` par fiche ; la disposition des colonnes (`columnState`) est persistée globalement dans un `dcc.Store` partagé. Le datasource, le reset, l'export filtré et le compteur passent par le moteur AST → SQL DuckDB du Lot 1 (`fetch_grid_page`, `export_dataframe`, `grid_column_defs`, `apply_persisted_layout`).
|
|
|
|
**Tech Stack:** Dash 4.4, dash-ag-grid 35.2.0, DuckDB, Polars, pytest + DashComposite/Selenium.
|
|
|
|
**Spec de référence:** `docs/superpowers/specs/2026-07-13-migration-ag-grid-acheteur-titulaire-design.md`
|
|
|
|
## Global Constraints
|
|
|
|
- Périmètre = **`acheteur.py` + `titulaire.py` uniquement**. Ne pas toucher `observatoire.py` (Lot 2b), `recherche.py`, `admin/liste.py`, `figures.make_table` (Lot 3), ni `tableau.py` (déjà migré — ses appels doivent rester fonctionnellement inchangés).
|
|
- **Dash 4.4** : `Input`/`State` en `MATCH` avec `Output` à id fixe est autorisé (relaxation Dash 4.2+). Un `Output` en `MATCH` exige toujours un `Input`/`State` en `MATCH` sur la même clé ; pour piloter la grille depuis un bouton à id fixe, utiliser `ALL` en `Output`/`State` (une seule grille présente à la fois).
|
|
- Imports internes toujours préfixés `src.` (ex. `src.utils.entity_grid`).
|
|
- **Thème "brique" du Lot 1 réutilisé** via `ag_grid()` (pas d'apparence de base non-thémée, pas de nouveau CSS).
|
|
- **Extensions rétro-compatibles du Lot 1** : `ag_grid()` et `export_dataframe()` gagnent des paramètres optionnels ; les appels existants de `tableau.py` doivent continuer à marcher **sans modification** (valeurs par défaut = comportement actuel).
|
|
- Sécurité : identifiants de colonnes validés contre `schema.names()` (déjà fait par `ast_to_sql`/`grid_column_defs`), valeurs **toujours** liées via `?` (jamais concaténées). Le scope entité (`entity_id`, année) passe **toujours** en paramètre lié, jamais concaténé dans le SQL.
|
|
- Lancer `pre-commit run --files <fichiers>` avant chaque `git add`/commit (hook prettier/ruff peut reformater — re-`git add` puis committer).
|
|
- Tests par fichier pendant le lot ; `uv run pytest` complet **uniquement** à la dernière tâche (cf. mémoire projet « full suite only at end »).
|
|
- Ne pas supprimer `filter_table_data`/`sort_table_data`/`prepare_table_data`/`clean_filters`/`filter_query_to_sql` : encore utilisés par `observatoire.py` et les Lots suivants. On les **débranche** seulement d'acheteur/titulaire.
|
|
- **Hors périmètre, à ne PAS migrer** : le sélecteur de colonnes (`make_column_picker`, composant `{page}_column_list`) reste un `dash_table.DataTable` — il est partagé avec `tableau.py` (lui aussi non migré sur ce point) ; le migrer toucherait `tableau.py` et sort du lot.
|
|
|
|
**Fonctions/objets réutilisables (ne pas réécrire) :**
|
|
|
|
- `src/db.py` : `schema` (pl.Schema), `query_marches(where_sql, params, columns, order_by, limit, offset)`, `count_marches(where_sql, params)`, `count_unique_marches(where_sql, params)`, `aggregate_marches(select_sql, where_sql, params, ...)`.
|
|
- `src/utils/grid.py` : `fetch_grid_page(filter_model, sort_model, start_row, end_row, base_where_sql="TRUE", base_params=()) -> (rows, total, total_unique)`, `grid_column_defs(hidden_columns=None)`, `apply_persisted_layout(defs, column_state)`, `export_dataframe(...)` (étendu en Task 1).
|
|
- `src/utils/table.py` : `postprocess_page(dff)`, `setup_table_columns(dff, hideable=True, exclude=None) -> (columns, tooltip)`, `add_links(dff)`, `get_default_hidden_columns(page)`, `write_styled_excel(df, buffer, worksheet="DECP")`, `COLUMNS` (= `schema.names()`).
|
|
- `src/figures.py` : `ag_grid(grid_id, column_defs, ...)` (paramétré en Task 2), `AG_GRID_LOCALE_FR`, `make_column_picker(page)`, `make_card(title, subtitle=None, fig=None, paragraphs=None, lg=6, xl=4)`, `DATA_SCHEMA`.
|
|
- `src/utils/frontend.py` : `get_button_properties(count) -> (disabled, children, title)` (état du bouton de téléchargement selon le seuil de 65 000 lignes), `DROPDOWN_LABELS_FR`.
|
|
- `src/utils/tracking.py` : `track_search(query, source)`.
|
|
|
|
---
|
|
|
|
## File Structure
|
|
|
|
- **Modify** `src/utils/grid.py` — étendre `export_dataframe()` avec `base_where_sql`/`base_params`.
|
|
- **Modify** `src/figures.py` — paramétrer `ag_grid()` (id dict + `persisted_props`) ; ajouter `get_top_org_ag_grid()`.
|
|
- **Create** `src/utils/entity_grid.py` — fonctions pures de grille scopée + `register_entity_grid_callbacks(org_type)`.
|
|
- **Create** `tests/test_entity_grid.py` — tests unitaires des fonctions pures.
|
|
- **Modify** `src/pages/acheteur.py` — `layout` → fonction, grille AG Grid via `entity_grid`, top 10 en AG Grid, suppression des callbacks DataTable.
|
|
- **Modify** `src/pages/titulaire.py` — idem acheteur.
|
|
- **Modify** `tests/test_main.py` — sélecteurs AG Grid (`test_002_filter_persistence`) ; vérifier `test_003_tableau_download`.
|
|
|
|
---
|
|
|
|
## Task 1: Étendre `export_dataframe()` avec le scope de base
|
|
|
|
**Files:**
|
|
|
|
- Modify: `src/utils/grid.py:71-85`
|
|
- Test: `tests/test_grid.py`
|
|
|
|
**Interfaces:**
|
|
|
|
- Produces: `export_dataframe(filter_model, sort_model, hidden_columns, base_where_sql="TRUE", base_params=()) -> pl.DataFrame`
|
|
|
|
- [ ] **Step 1: Écrire le test qui échoue**
|
|
|
|
Ajouter dans `tests/test_grid.py` :
|
|
|
|
```python
|
|
def test_export_dataframe_applies_base_scope():
|
|
"""base_where_sql restreint l'export à un sous-ensemble (ex. un acheteur),
|
|
en plus du filterModel — utilisé par acheteur.py/titulaire.py (#41)."""
|
|
# Récupère un acheteur_id présent dans le jeu de test.
|
|
unscoped = export_dataframe(None, None, hidden_columns=[])
|
|
assert unscoped.height > 0
|
|
an_acheteur = unscoped["acheteur_id"][0]
|
|
|
|
scoped = export_dataframe(
|
|
None,
|
|
None,
|
|
hidden_columns=[],
|
|
base_where_sql="acheteur_id = ?",
|
|
base_params=(an_acheteur,),
|
|
)
|
|
assert scoped.height > 0
|
|
assert scoped.height <= unscoped.height
|
|
assert set(scoped["acheteur_id"].to_list()) == {an_acheteur}
|
|
```
|
|
|
|
- [ ] **Step 2: Lancer le test, vérifier l'échec**
|
|
|
|
Run: `uv run pytest tests/test_grid.py::test_export_dataframe_applies_base_scope -v`
|
|
Expected: FAIL — `TypeError: export_dataframe() got an unexpected keyword argument 'base_where_sql'`.
|
|
|
|
- [ ] **Step 3: Implémenter l'extension**
|
|
|
|
Remplacer `export_dataframe` dans `src/utils/grid.py` par :
|
|
|
|
```python
|
|
def export_dataframe(
|
|
filter_model,
|
|
sort_model,
|
|
hidden_columns,
|
|
base_where_sql: str = "TRUE",
|
|
base_params: tuple = (),
|
|
) -> pl.DataFrame:
|
|
"""Renvoie les lignes filtrées/triées pour l'export Excel.
|
|
|
|
Colonnes masquées exclues, valeurs brutes (non post-traitées HTML).
|
|
`base_where_sql`/`base_params` scopent l'export à un sous-ensemble (ex. un
|
|
acheteur/titulaire) — combinés en `(base) AND (filtre)`, comme
|
|
`fetch_grid_page`. Par défaut `TRUE` → comportement inchangé pour tableau.py.
|
|
"""
|
|
ast = filtermodel_to_ast(filter_model, schema)
|
|
filter_sql, filter_params = ast_to_sql(ast, schema)
|
|
where_sql = f"({base_where_sql}) AND ({filter_sql})"
|
|
params = [*base_params, *filter_params]
|
|
order_by = sort_model_to_sql(sort_model, schema) or None
|
|
visible = [c for c in schema.names() if c not in set(hidden_columns or [])]
|
|
return query_marches(
|
|
where_sql=where_sql,
|
|
params=params,
|
|
columns=visible,
|
|
order_by=order_by,
|
|
)
|
|
```
|
|
|
|
- [ ] **Step 4: Lancer les tests du fichier, vérifier le succès + non-régression**
|
|
|
|
Run: `uv run pytest tests/test_grid.py -v`
|
|
Expected: PASS pour tous (dont `test_export_dataframe_excludes_hidden_columns` et `test_export_dataframe_applies_filter`, qui appellent sans les nouveaux args → défaut `TRUE`).
|
|
|
|
- [ ] **Step 5: Commit**
|
|
|
|
```bash
|
|
pre-commit run --files src/utils/grid.py tests/test_grid.py
|
|
git add src/utils/grid.py tests/test_grid.py
|
|
git commit -m "feat(grid): export_dataframe scopable par base_where_sql/base_params (#41)"
|
|
```
|
|
|
|
---
|
|
|
|
## Task 2: Paramétrer `ag_grid()` (id dict + persisted_props)
|
|
|
|
**Files:**
|
|
|
|
- Modify: `src/figures.py:1101-1162`
|
|
- Test: `tests/test_figures.py`
|
|
|
|
**Interfaces:**
|
|
|
|
- Produces: `ag_grid(grid_id: str | dict, column_defs: list[dict], persisted_props=("filterModel", "columnState"), persistence=True) -> dag.AgGrid`
|
|
|
|
- [ ] **Step 1: Écrire les tests qui échouent**
|
|
|
|
Ajouter dans `tests/test_figures.py` :
|
|
|
|
```python
|
|
def test_ag_grid_accepts_dict_id_and_custom_persisted_props():
|
|
"""Grille entité : id pattern-matching + persistance limitée au filterModel
|
|
(columnState géré via un store partagé, pas la persistance native)."""
|
|
from src.figures import ag_grid
|
|
|
|
gid = {"type": "acheteur-grid", "entity_id": "123", "year": "Toutes les années"}
|
|
grid = ag_grid(gid, [], persisted_props=["filterModel"])
|
|
|
|
assert grid.id == gid
|
|
assert list(grid.persisted_props) == ["filterModel"]
|
|
assert grid.persistence is True
|
|
|
|
|
|
def test_ag_grid_defaults_unchanged_for_tableau():
|
|
"""Sans args de persistance, comportement identique au Lot 1 (tableau.py)."""
|
|
from src.figures import ag_grid
|
|
|
|
grid = ag_grid("tableau_grid", [])
|
|
|
|
assert grid.id == "tableau_grid"
|
|
assert list(grid.persisted_props) == ["filterModel", "columnState"]
|
|
assert grid.persistence is True
|
|
```
|
|
|
|
- [ ] **Step 2: Lancer les tests, vérifier l'échec**
|
|
|
|
Run: `uv run pytest tests/test_figures.py::test_ag_grid_accepts_dict_id_and_custom_persisted_props -v`
|
|
Expected: FAIL — `TypeError: ag_grid() got an unexpected keyword argument 'persisted_props'`.
|
|
|
|
- [ ] **Step 3: Implémenter la paramétrisation**
|
|
|
|
Dans `src/figures.py`, modifier la signature et les deux lignes de persistance de `ag_grid()` :
|
|
|
|
```python
|
|
def ag_grid(
|
|
grid_id: "str | dict",
|
|
column_defs: list[dict],
|
|
persisted_props=("filterModel", "columnState"),
|
|
persistence: bool = True,
|
|
) -> "dag.AgGrid":
|
|
```
|
|
|
|
Et, dans le `return dag.AgGrid(...)`, remplacer les lignes finales :
|
|
|
|
```python
|
|
persistence=persistence,
|
|
persistence_type="local",
|
|
persisted_props=list(persisted_props),
|
|
)
|
|
```
|
|
|
|
(Le reste du corps — `dashGridOptions`, thème, `style`, etc. — est inchangé. `id=grid_id` accepte déjà str ou dict.)
|
|
|
|
- [ ] **Step 4: Lancer les tests, vérifier le succès + non-régression**
|
|
|
|
Run: `uv run pytest tests/test_figures.py -v`
|
|
Expected: PASS pour tous (dont les tests existants `test_ag_grid_locale_text_*`, `test_ag_grid_keeps_base_appearance`, `test_ag_grid_always_shows_horizontal_scroll`).
|
|
|
|
- [ ] **Step 5: Commit**
|
|
|
|
```bash
|
|
pre-commit run --files src/figures.py tests/test_figures.py
|
|
git add src/figures.py tests/test_figures.py
|
|
git commit -m "feat(figures): ag_grid() paramétrable (id dict + persisted_props) (#41)"
|
|
```
|
|
|
|
---
|
|
|
|
## Task 3: `get_top_org_ag_grid()` — tableau « top 10 » en AG Grid
|
|
|
|
**Files:**
|
|
|
|
- Modify: `src/figures.py` (ajouter la fonction près de `get_top_org_table`, ~ligne 1062)
|
|
- Test: `tests/test_figures.py`
|
|
|
|
**Interfaces:**
|
|
|
|
- Consumes: `setup_table_columns`, `add_links` (src.utils.table) ; `ag_grid` (Task 2).
|
|
- Produces: `get_top_org_ag_grid(data, org_type, extra_columns, filters=True) -> dag.AgGrid | html.Div` — même rôle que `get_top_org_table`, mais rend une AG Grid client-side (row model par défaut, `rowData` fournie). Renvoie `html.Div()` si vide/erreur.
|
|
|
|
- [ ] **Step 1: Écrire les tests qui échouent**
|
|
|
|
Ajouter dans `tests/test_figures.py` :
|
|
|
|
```python
|
|
def test_get_top_org_ag_grid_returns_grid_with_rowdata():
|
|
"""Le top 10 devient une AG Grid client-side (rowData directe, pas de
|
|
getRowsRequest server-side)."""
|
|
import dash_ag_grid as dag
|
|
|
|
from src.db import query_marches
|
|
from src.figures import get_top_org_ag_grid
|
|
|
|
lff = query_marches("TRUE", (), columns=None).lazy()
|
|
grid = get_top_org_ag_grid(lff, "titulaire", ["titulaire_distance"])
|
|
|
|
assert isinstance(grid, dag.AgGrid)
|
|
assert grid.rowData is not None and len(grid.rowData) > 0
|
|
# Colonne d'agrégat présente ; colonnes définies.
|
|
assert any(c.get("field") == "Attributions" for c in grid.columnDefs)
|
|
# Pas de persistance (petit tableau statique, régénéré à chaque fiche).
|
|
assert grid.persistence in (False, None)
|
|
|
|
|
|
def test_get_top_org_ag_grid_empty_returns_div():
|
|
"""Données vides → html.Div() (parité get_top_org_table)."""
|
|
import polars as pl
|
|
from dash import html
|
|
|
|
from src.figures import get_top_org_ag_grid
|
|
|
|
empty = pl.DataFrame(
|
|
{"uid": [], "titulaire_id": [], "titulaire_nom": [], "titulaire_distance": []}
|
|
).lazy()
|
|
out = get_top_org_ag_grid(empty, "titulaire", ["titulaire_distance"])
|
|
assert isinstance(out, html.Div)
|
|
|
|
|
|
def test_get_top_org_table_still_returns_datatable_after_refactor():
|
|
"""Non-régression : get_top_org_table (utilisé par observatoire.py) garde
|
|
son comportement après extraction du helper d'agrégation partagé."""
|
|
import dash_ag_grid # noqa: F401
|
|
from dash import html
|
|
|
|
from src.db import query_marches
|
|
from src.figures import DataTable, get_top_org_table
|
|
|
|
lff = query_marches("TRUE", (), columns=None).lazy()
|
|
out = get_top_org_table(lff, "titulaire", ["titulaire_distance"])
|
|
assert isinstance(out, (DataTable, html.Div))
|
|
|
|
|
|
def test_top_org_aggregate_does_not_mutate_extra_columns():
|
|
"""Le helper ne mute pas la liste extra_columns passée (bug latent de
|
|
l'ancien get_top_org_table, qui faisait extra_columns.append(...))."""
|
|
from src.db import query_marches
|
|
from src.figures import _top_org_aggregate
|
|
|
|
extra = ["titulaire_distance"]
|
|
_top_org_aggregate(query_marches("TRUE", (), columns=None).lazy(), "titulaire", extra)
|
|
assert extra == ["titulaire_distance"]
|
|
```
|
|
|
|
- [ ] **Step 2: Lancer les tests, vérifier l'échec**
|
|
|
|
Run: `uv run pytest tests/test_figures.py::test_get_top_org_ag_grid_returns_grid_with_rowdata -v`
|
|
Expected: FAIL — `ImportError: cannot import name 'get_top_org_ag_grid'`.
|
|
|
|
- [ ] **Step 3a: Extraire le helper d'agrégation partagé**
|
|
|
|
Dans `src/figures.py`, ajouter le helper `_top_org_aggregate` (juste avant `get_top_org_table`). Il porte l'agrégation commune ; il **copie** `extra_columns` (l'ancien `get_top_org_table` mutait la liste du caller — bug latent corrigé) et renvoie le `pl.DataFrame` agrégé **avant** `add_links`, ou `None` si vide/erreur :
|
|
|
|
```python
|
|
def _top_org_aggregate(data, org_type: str, extra_columns: list):
|
|
"""Agrégation « top N » commune à get_top_org_table et get_top_org_ag_grid.
|
|
|
|
Renvoie le DataFrame agrégé (colonnes castées en str, tri par Attributions
|
|
décroissant), AVANT add_links, ou None si vide/colonne manquante.
|
|
"""
|
|
if isinstance(data, pl.LazyFrame):
|
|
lff = data
|
|
else:
|
|
lff = pl.LazyFrame(data, strict=False, infer_schema_length=5000)
|
|
|
|
extra = list(extra_columns) # copie : ne pas muter la liste du caller
|
|
if org_type == "titulaire":
|
|
extra.append("titulaire_typeIdentifiant")
|
|
columns = ["uid", f"{org_type}_id", f"{org_type}_nom"] + extra
|
|
|
|
lff = lff.select(columns)
|
|
lff = lff.group_by([f"{org_type}_id", f"{org_type}_nom"] + extra).agg(
|
|
pl.len().alias("Attributions")
|
|
)
|
|
lff = lff.sort(by="Attributions", descending=True, nulls_last=True)
|
|
lff = lff.cast(pl.String)
|
|
lff = lff.fill_null("")
|
|
|
|
try:
|
|
dff: pl.DataFrame = lff.collect(engine="streaming")
|
|
except ColumnNotFoundError:
|
|
logger.warning(f"_top_org_aggregate: column not found. {lff.collect_schema()}")
|
|
return None
|
|
return dff if dff.height > 0 else None
|
|
```
|
|
|
|
Puis **refactorer `get_top_org_table`** pour l'utiliser (comportement identique : `setup_table_columns` toujours appelé sur le dff _avant_ `add_links`). Remplacer le début de son corps (jusqu'au `dff = add_links(dff)` inclus) par :
|
|
|
|
```python
|
|
def get_top_org_table(data, org_type: str, extra_columns: list, filters: bool = True):
|
|
dff = _top_org_aggregate(data, org_type, extra_columns)
|
|
if dff is None:
|
|
return html.Div()
|
|
|
|
columns, tooltip = setup_table_columns(
|
|
dff, hideable=False, exclude=[f"{org_type}_id"]
|
|
)
|
|
dff = add_links(dff)
|
|
data = dff.to_dicts()
|
|
|
|
return DataTable(
|
|
dtid=f"top10_{org_type}",
|
|
data=data,
|
|
page_action="native",
|
|
page_size=10,
|
|
columns=columns,
|
|
tooltip_header=tooltip,
|
|
filter_action="native" if filters else "none",
|
|
)
|
|
```
|
|
|
|
- [ ] **Step 3b: Implémenter `get_top_org_ag_grid` via le helper**
|
|
|
|
Ajouter (juste après `get_top_org_table`) :
|
|
|
|
```python
|
|
def get_top_org_ag_grid(data, org_type: str, extra_columns: list, filters: bool = True):
|
|
"""Top N acheteurs/titulaires en AG Grid client-side (rowData directe).
|
|
|
|
Remplace get_top_org_table (dash_table) : même agrégation (helper partagé),
|
|
rendu AG Grid (thème brique, liens markdown). html.Div() si vide/erreur.
|
|
"""
|
|
dff = _top_org_aggregate(data, org_type, extra_columns)
|
|
if dff is None:
|
|
return html.Div()
|
|
|
|
dff = add_links(dff)
|
|
|
|
# columnDefs : on masque l'id (lien porté par le nom), on rend le nom en
|
|
# markdown (HTML <a>), on cache les colonnes techniques *_tooltip.
|
|
id_col = f"{org_type}_id"
|
|
nom_col = f"{org_type}_nom"
|
|
link_cols = {nom_col}
|
|
column_defs = []
|
|
for col in dff.columns:
|
|
if col == id_col or col.endswith("_tooltip"):
|
|
continue
|
|
col_def = {
|
|
"field": col,
|
|
"headerName": DATA_SCHEMA.get(col, {}).get("title", col),
|
|
"sortable": True,
|
|
"filter": "agTextColumnFilter" if filters else False,
|
|
}
|
|
if col in link_cols:
|
|
col_def["cellRenderer"] = "markdown"
|
|
col_def["flex"] = 1
|
|
column_defs.append(col_def)
|
|
|
|
# ag_grid() du Lot 1 est server-side (rowModelType="infinite", pas de
|
|
# rowData) : inadapté au top 10, qui est client-side. On construit donc une
|
|
# AG Grid client-side directe, en réutilisant le thème + localeText.
|
|
return dag.AgGrid(
|
|
id=f"top10_{org_type}",
|
|
columnDefs=column_defs,
|
|
rowData=dff.to_dicts(),
|
|
dangerously_allow_code=True, # rend le HTML <a> des cellules liens
|
|
columnSize="responsiveSizeToFit",
|
|
dashGridOptions={
|
|
"domLayout": "autoHeight", # OK ici : row model client-side
|
|
"pagination": True,
|
|
"paginationPageSize": 10,
|
|
"suppressCellFocus": True,
|
|
"localeText": AG_GRID_LOCALE_FR,
|
|
"theme": {
|
|
"function": (
|
|
"themeQuartz.withParams({"
|
|
"accentColor: 'rgb(179, 56, 33)',"
|
|
"headerTextColor: 'white',"
|
|
"headerBackgroundColor: 'rgb(179, 56, 33)',"
|
|
"oddRowBackgroundColor: 'rgba(255, 240, 240, 0.4)',"
|
|
"borderColor: '#ccc',"
|
|
"fontFamily: 'Inter, sans-serif',"
|
|
"fontSize: 16"
|
|
"})"
|
|
)
|
|
},
|
|
},
|
|
style={"width": "100%"},
|
|
persistence=False,
|
|
)
|
|
```
|
|
|
|
(Vérifier que `import dash_ag_grid as dag` est déjà présent en tête de `src/figures.py` — c'est le cas. `add_links`, `setup_table_columns`, `ColumnNotFoundError`, `DATA_SCHEMA`, `logger`, `AG_GRID_LOCALE_FR` sont déjà importés/définis dans `src/figures.py` puisque `get_top_org_table` les utilise.)
|
|
|
|
> `get_top_org_table` reste en place ce lot (encore utilisé par `observatoire.py`), mais partage désormais l'agrégation via `_top_org_aggregate` (plus de duplication). Le test de non-régression garantit qu'il rend toujours une `DataTable`.
|
|
|
|
- [ ] **Step 4: Lancer les tests, vérifier le succès**
|
|
|
|
Run: `uv run pytest tests/test_figures.py -k "top_org" -v`
|
|
Expected: PASS pour `test_get_top_org_ag_grid_returns_grid_with_rowdata`, `test_get_top_org_ag_grid_empty_returns_div`, `test_get_top_org_table_still_returns_datatable_after_refactor`, `test_top_org_aggregate_does_not_mutate_extra_columns`.
|
|
|
|
- [ ] **Step 5: Commit**
|
|
|
|
```bash
|
|
pre-commit run --files src/figures.py tests/test_figures.py
|
|
git add src/figures.py tests/test_figures.py
|
|
git commit -m "feat(figures): get_top_org_ag_grid (top 10 en AG Grid client-side) (#41)"
|
|
```
|
|
|
|
---
|
|
|
|
## Task 4: `entity_grid.py` — fonctions pures de grille scopée
|
|
|
|
**Files:**
|
|
|
|
- Create: `src/utils/entity_grid.py`
|
|
- Test: `tests/test_entity_grid.py`
|
|
|
|
**Interfaces:**
|
|
|
|
- Consumes: `fetch_grid_page`, `export_dataframe` (Task 1), `grid_column_defs`, `apply_persisted_layout` (grid.py) ; `ag_grid` (Task 2) ; `schema` (src.db).
|
|
- Produces (consommées en Task 5/6/7) :
|
|
|
|
- `entity_scope(org_type: str, entity_id: str, year) -> tuple[str, list]`
|
|
- `entity_grid_column_defs(hidden_columns, column_state) -> list[dict]`
|
|
- `fetch_entity_page(org_type, entity_id, year, request: dict) -> tuple[dict, int, int]` — renvoie `({"rowData": ..., "rowCount": total}, total, total_unique)`
|
|
- `export_entity_dataframe(org_type, entity_id, year, filter_model, column_state) -> pl.DataFrame`
|
|
- `clear_sort(column_state) -> list[dict]`
|
|
- `build_entity_grid(org_type, entity_id, year, hidden_columns, column_state) -> dag.AgGrid`
|
|
- `GRID_TYPE = "{org_type}-grid"` construit via `grid_type(org_type)`
|
|
|
|
- [ ] **Step 1: Écrire les tests qui échouent**
|
|
|
|
Créer `tests/test_entity_grid.py` :
|
|
|
|
```python
|
|
import dash_ag_grid as dag
|
|
import pytest
|
|
|
|
import src.app # noqa: F401 # instancie l'app → schema chargé
|
|
from src.db import query_marches
|
|
from src.utils.entity_grid import (
|
|
build_entity_grid,
|
|
clear_sort,
|
|
entity_grid_column_defs,
|
|
entity_scope,
|
|
export_entity_dataframe,
|
|
fetch_entity_page,
|
|
grid_type,
|
|
)
|
|
|
|
|
|
def _an_acheteur_id():
|
|
return query_marches("TRUE", (), columns=["acheteur_id"])["acheteur_id"][0]
|
|
|
|
|
|
def test_entity_scope_acheteur():
|
|
where, params = entity_scope("acheteur", "S123", None)
|
|
assert where == "acheteur_id = ?"
|
|
assert params == ["S123"]
|
|
|
|
|
|
def test_entity_scope_titulaire_requires_siret():
|
|
where, params = entity_scope("titulaire", "S123", None)
|
|
assert "titulaire_id = ?" in where
|
|
assert "titulaire_typeIdentifiant = 'SIRET'" in where
|
|
assert params == ["S123"]
|
|
|
|
|
|
def test_entity_scope_with_year_adds_bound_param():
|
|
where, params = entity_scope("acheteur", "S123", "2025")
|
|
assert 'YEAR("dateNotification") = ?' in where
|
|
assert params == ["S123", 2025]
|
|
|
|
|
|
def test_entity_scope_toutes_les_annees_no_year_filter():
|
|
where, params = entity_scope("acheteur", "S123", "Toutes les années")
|
|
assert "YEAR" not in where
|
|
assert params == ["S123"]
|
|
|
|
|
|
def test_fetch_entity_page_is_scoped():
|
|
ach = _an_acheteur_id()
|
|
request = {"startRow": 0, "endRow": 50, "filterModel": None, "sortModel": None}
|
|
response, total, total_unique = fetch_entity_page("acheteur", ach, None, request)
|
|
assert total > 0
|
|
assert total_unique > 0
|
|
assert response["rowCount"] == total
|
|
assert len(response["rowData"]) <= 50
|
|
# Toutes les lignes appartiennent à l'acheteur scopé.
|
|
assert all(str(r["acheteur_id"]).find(str(ach)) != -1 for r in response["rowData"])
|
|
|
|
|
|
def test_fetch_entity_page_none_request():
|
|
from dash import no_update
|
|
|
|
out = fetch_entity_page("acheteur", "S123", None, None)
|
|
assert out == (no_update, no_update, no_update)
|
|
|
|
|
|
def test_export_entity_dataframe_scoped():
|
|
ach = _an_acheteur_id()
|
|
df = export_entity_dataframe("acheteur", ach, None, None, None)
|
|
assert df.height > 0
|
|
assert set(df["acheteur_id"].to_list()) == {ach}
|
|
|
|
|
|
def test_clear_sort_preserves_width_and_order():
|
|
column_state = [
|
|
{"colId": "objet", "width": 400, "sort": "asc", "sortIndex": 0},
|
|
{"colId": "montant", "width": 150, "sort": "desc", "sortIndex": 1},
|
|
]
|
|
cleared = clear_sort(column_state)
|
|
assert all(c["sort"] is None and c["sortIndex"] is None for c in cleared)
|
|
assert cleared[0]["width"] == 400 and cleared[0]["colId"] == "objet"
|
|
assert cleared[1]["width"] == 150
|
|
|
|
|
|
def test_clear_sort_empty():
|
|
assert clear_sort(None) == []
|
|
|
|
|
|
def test_entity_grid_column_defs_applies_persisted_layout():
|
|
defs = entity_grid_column_defs(hidden_columns=[], column_state=[{"colId": "montant", "width": 999}])
|
|
by_field = {d["field"]: d for d in defs}
|
|
assert by_field["montant"]["width"] == 999
|
|
|
|
|
|
def test_build_entity_grid_has_pattern_matching_id_and_filter_only_persistence():
|
|
grid = build_entity_grid("acheteur", "S123", "Toutes les années", [], None)
|
|
assert isinstance(grid, dag.AgGrid)
|
|
assert grid.id == {"type": "acheteur-grid", "entity_id": "S123", "year": "Toutes les années"}
|
|
assert list(grid.persisted_props) == ["filterModel"]
|
|
|
|
|
|
def test_grid_type():
|
|
assert grid_type("acheteur") == "acheteur-grid"
|
|
assert grid_type("titulaire") == "titulaire-grid"
|
|
```
|
|
|
|
- [ ] **Step 2: Lancer les tests, vérifier l'échec**
|
|
|
|
Run: `uv run pytest tests/test_entity_grid.py -v`
|
|
Expected: FAIL — `ModuleNotFoundError: No module named 'src.utils.entity_grid'`.
|
|
|
|
- [ ] **Step 3: Implémenter le module**
|
|
|
|
Créer `src/utils/entity_grid.py` :
|
|
|
|
```python
|
|
"""Logique de grille AG Grid scopée à une entité (acheteur/titulaire).
|
|
|
|
Factorise ce qui est commun aux pages acheteur.py et titulaire.py :
|
|
- scope SQL (WHERE acheteur_id/titulaire_id + année),
|
|
- datasource server-side (réutilise fetch_grid_page du Lot 1),
|
|
- export Excel filtré (réutilise export_dataframe),
|
|
- columnDefs + réapplication de la disposition persistée,
|
|
- fabrique de grille à id pattern-matching (persistance filterModel par fiche).
|
|
|
|
Les callbacks Dash sont enregistrés par register_entity_grid_callbacks()
|
|
(cf. module séparé de wiring) ; ici, seules des fonctions pures testables.
|
|
"""
|
|
|
|
import dash_ag_grid as dag
|
|
from dash import no_update
|
|
|
|
from src.figures import (
|
|
AG_GRID_LOCALE_FR, # noqa: F401 (réexport pratique)
|
|
ag_grid,
|
|
)
|
|
from src.utils.grid import (
|
|
apply_persisted_layout,
|
|
export_dataframe,
|
|
fetch_grid_page,
|
|
grid_column_defs,
|
|
)
|
|
|
|
_TOUTES = "Toutes les années"
|
|
|
|
|
|
def grid_type(org_type: str) -> str:
|
|
"""Valeur de la clé `type` de l'id pattern-matching de la grille."""
|
|
return f"{org_type}-grid"
|
|
|
|
|
|
def entity_scope(org_type: str, entity_id: str, year) -> tuple[str, list]:
|
|
"""WHERE SQL + params liés scopant les requêtes à cette entité (+ année).
|
|
|
|
Reproduit _acheteur_scope/_titulaire_scope des pages, unifié par org_type.
|
|
"""
|
|
if org_type == "titulaire":
|
|
where_sql = "titulaire_id = ? AND titulaire_typeIdentifiant = 'SIRET'"
|
|
else:
|
|
where_sql = "acheteur_id = ?"
|
|
params: list = [entity_id]
|
|
if year and year != _TOUTES:
|
|
where_sql += ' AND YEAR("dateNotification") = ?'
|
|
params.append(int(year))
|
|
return where_sql, params
|
|
|
|
|
|
def _sort_model_from_column_state(column_state) -> list:
|
|
"""Extrait le sortModel AG Grid d'un columnState (comme tableau.download_data)."""
|
|
return [
|
|
{"colId": c["colId"], "sort": c["sort"]}
|
|
for c in (column_state or [])
|
|
if c.get("sort")
|
|
]
|
|
|
|
|
|
def entity_grid_column_defs(hidden_columns, column_state) -> list[dict]:
|
|
"""columnDefs du schéma DECP + disposition (largeur/ordre) persistée."""
|
|
defs = grid_column_defs(hidden_columns)
|
|
return apply_persisted_layout(defs, column_state)
|
|
|
|
|
|
def fetch_entity_page(org_type, entity_id, year, request) -> tuple:
|
|
"""Datasource server-side scopé pour la grille entité.
|
|
|
|
Renvoie ({"rowData": ..., "rowCount": total}, total, total_unique).
|
|
"""
|
|
if request is None:
|
|
return no_update, no_update, no_update
|
|
base_where_sql, base_params = entity_scope(org_type, entity_id, year)
|
|
rows, total, total_unique = fetch_grid_page(
|
|
request.get("filterModel") or None,
|
|
request.get("sortModel") or None,
|
|
request.get("startRow", 0),
|
|
request.get("endRow", 100),
|
|
base_where_sql=base_where_sql,
|
|
base_params=tuple(base_params),
|
|
)
|
|
return {"rowData": rows, "rowCount": total}, total, total_unique
|
|
|
|
|
|
def export_entity_dataframe(org_type, entity_id, year, filter_model, column_state):
|
|
"""DataFrame filtré/trié (état courant de la grille) pour l'export Excel."""
|
|
base_where_sql, base_params = entity_scope(org_type, entity_id, year)
|
|
sort_model = _sort_model_from_column_state(column_state)
|
|
hidden_columns = [c["colId"] for c in (column_state or []) if c.get("hide")]
|
|
return export_dataframe(
|
|
filter_model,
|
|
sort_model,
|
|
hidden_columns,
|
|
base_where_sql=base_where_sql,
|
|
base_params=tuple(base_params),
|
|
)
|
|
|
|
|
|
def clear_sort(column_state) -> list[dict]:
|
|
"""columnState avec le tri effacé (sort/sortIndex à None), largeur/ordre/
|
|
épinglage préservés. Approche #47-safe de tableau.reset_view."""
|
|
return [{**col, "sort": None, "sortIndex": None} for col in (column_state or [])]
|
|
|
|
|
|
def build_entity_grid(org_type, entity_id, year, hidden_columns, column_state):
|
|
"""Grille AG Grid à id pattern-matching, scopée à (entité, année).
|
|
|
|
L'id inclut entity_id + year → une entrée localStorage de filterModel par
|
|
fiche/année (persistance native scopée). columnState n'est PAS persisté
|
|
nativement (géré par un store global partagé) : persisted_props=["filterModel"].
|
|
"""
|
|
grid_id = {"type": grid_type(org_type), "entity_id": entity_id, "year": year or _TOUTES}
|
|
defs = entity_grid_column_defs(hidden_columns, column_state)
|
|
return ag_grid(grid_id, defs, persisted_props=["filterModel"])
|
|
```
|
|
|
|
- [ ] **Step 4: Lancer les tests, vérifier le succès**
|
|
|
|
Run: `uv run pytest tests/test_entity_grid.py -v`
|
|
Expected: PASS pour les 12 tests.
|
|
|
|
- [ ] **Step 5: Commit**
|
|
|
|
```bash
|
|
pre-commit run --files src/utils/entity_grid.py tests/test_entity_grid.py
|
|
git add src/utils/entity_grid.py tests/test_entity_grid.py
|
|
git commit -m "feat(entity_grid): fonctions pures de grille scopée acheteur/titulaire (#41)"
|
|
```
|
|
|
|
---
|
|
|
|
## Task 5: `register_entity_grid_callbacks()` — wiring des callbacks partagés
|
|
|
|
**Files:**
|
|
|
|
- Modify: `src/utils/entity_grid.py` (ajouter la fonction de registration)
|
|
- Test: `tests/test_entity_grid.py` (test de fumée : la registration ne lève pas)
|
|
|
|
**Interfaces:**
|
|
|
|
- Consumes: fonctions pures de Task 4.
|
|
- Produces: `register_entity_grid_callbacks(org_type: str) -> None` — enregistre, pour la page `org_type`, les callbacks : datasource (grille MATCH → stores totaux fixes), rebuild de grille (nav/année/colonnes masquées), persistance columnState (grille → store partagé), reset (bouton → grille ALL), export filtré (bouton → Download), meta (totaux → nb_rows + état bouton export filtré).
|
|
- **Ids conventionnels attendus par page** (créés en Task 6/7) : `f"{org_type}_url"` (dcc.Location), `f"{org_type}_year"` (dropdown), `f"{org_type}-grid-container"` (html.Div hôte), `f"{org_type}-total"`, `f"{org_type}-total-unique"` (dcc.Store), `f"{org_type}-hidden-columns"` (dcc.Store), `"entity-grid-columns-state"` (dcc.Store partagé), `f"{org_type}_nb_rows"` (Span), `f"btn-{org_type}-reset"`, `f"btn-download-filtered-data-{org_type}"`, `f"{org_type}-download-filtered-data"` (dcc.Download).
|
|
|
|
- [ ] **Step 1: Écrire le test de fumée qui échoue**
|
|
|
|
Ajouter dans `tests/test_entity_grid.py` :
|
|
|
|
```python
|
|
def test_register_entity_grid_callbacks_smoke():
|
|
"""La registration ne lève pas (les ids/patterns sont valides pour Dash)."""
|
|
import src.app # noqa: F401
|
|
from src.utils.entity_grid import register_entity_grid_callbacks
|
|
|
|
# Ne doit pas lever ; idempotence non requise (appelée une fois par page).
|
|
register_entity_grid_callbacks("acheteur")
|
|
```
|
|
|
|
- [ ] **Step 2: Lancer le test, vérifier l'échec**
|
|
|
|
Run: `uv run pytest tests/test_entity_grid.py::test_register_entity_grid_callbacks_smoke -v`
|
|
Expected: FAIL — `ImportError: cannot import name 'register_entity_grid_callbacks'`.
|
|
|
|
- [ ] **Step 3: Implémenter la registration**
|
|
|
|
Ajouter en tête de `src/utils/entity_grid.py` les imports Dash nécessaires :
|
|
|
|
```python
|
|
from dash import ALL, MATCH, Input, Output, State, callback, ctx, dcc
|
|
```
|
|
|
|
Puis ajouter à la fin du module :
|
|
|
|
```python
|
|
def register_entity_grid_callbacks(org_type: str) -> None:
|
|
"""Enregistre les callbacks de grille pour la page org_type (acheteur/titulaire).
|
|
|
|
Appelée une fois par page. Utilise des closures sur org_type ; toute la
|
|
logique délègue aux fonctions pures ci-dessus (testées en Task 4).
|
|
"""
|
|
gtype = grid_type(org_type)
|
|
|
|
# 1) Datasource server-side. Input MATCH (grille) → Output MATCH
|
|
# (getRowsResponse) + Outputs fixes (stores totaux). Autorisé en Dash 4.4.
|
|
@callback(
|
|
Output({"type": gtype, "entity_id": MATCH, "year": MATCH}, "getRowsResponse"),
|
|
Output(f"{org_type}-total", "data"),
|
|
Output(f"{org_type}-total-unique", "data"),
|
|
Input({"type": gtype, "entity_id": MATCH, "year": MATCH}, "getRowsRequest"),
|
|
prevent_initial_call=True,
|
|
)
|
|
def _get_rows(request):
|
|
gid = ctx.triggered_id # {"type", "entity_id", "year"}
|
|
if request is None or gid is None:
|
|
return no_update, no_update, no_update
|
|
if request.get("filterModel") and request.get("startRow", 0) == 0:
|
|
import json
|
|
|
|
from src.utils.tracking import track_search
|
|
|
|
track_search(json.dumps(request["filterModel"]), org_type)
|
|
return fetch_entity_page(org_type, gid["entity_id"], gid["year"], request)
|
|
|
|
# 2) (Re)construit la grille au changement de fiche (URL), d'année, ou de
|
|
# colonnes masquées. Le remontage réinitialise le filterModel (accepté
|
|
# au changement de fiche/année) ; pour les colonnes masquées voir §3bis.
|
|
@callback(
|
|
Output(f"{org_type}-grid-container", "children"),
|
|
Input(f"{org_type}_url", "pathname"),
|
|
Input(f"{org_type}_year", "value"),
|
|
State(f"{org_type}-hidden-columns", "data"),
|
|
State("entity-grid-columns-state", "data"),
|
|
)
|
|
def _build_grid(pathname, year, hidden_columns, column_state):
|
|
from src.utils.table import get_default_hidden_columns
|
|
|
|
entity_id = (pathname or "").split("/")[-1]
|
|
if hidden_columns is None:
|
|
hidden_columns = get_default_hidden_columns(org_type)
|
|
return build_entity_grid(org_type, entity_id, year, hidden_columns, column_state)
|
|
|
|
# 3) Persiste columnState (largeur/ordre/tri/visibilité) dans le store global
|
|
# partagé. Input MATCH (grille) → Output fixe (store). Autorisé Dash 4.4.
|
|
# allow_duplicate=True OBLIGATOIRE : ce store est partagé et
|
|
# register_entity_grid_callbacks est appelé pour acheteur ET titulaire,
|
|
# donc deux callbacks visent ce même Output fixe (sans allow_duplicate →
|
|
# collision, 500 au runtime dès que les deux pages sont câblées).
|
|
@callback(
|
|
Output("entity-grid-columns-state", "data", allow_duplicate=True),
|
|
Input({"type": gtype, "entity_id": MATCH, "year": MATCH}, "columnState"),
|
|
prevent_initial_call=True,
|
|
)
|
|
def _persist_column_state(column_state):
|
|
return column_state or no_update
|
|
|
|
# 3bis) Colonnes masquées → columnDefs in-place (préserve le filtre courant,
|
|
# contrairement au remontage). Input fixe → Output ALL (grille unique).
|
|
@callback(
|
|
Output({"type": gtype, "entity_id": ALL, "year": ALL}, "columnDefs"),
|
|
Input(f"{org_type}-hidden-columns", "data"),
|
|
State({"type": gtype, "entity_id": ALL, "year": ALL}, "columnState"),
|
|
prevent_initial_call=True,
|
|
)
|
|
def _apply_hidden_columns(hidden_columns, column_states):
|
|
from src.utils.table import get_default_hidden_columns
|
|
|
|
if hidden_columns is None:
|
|
hidden_columns = get_default_hidden_columns(org_type)
|
|
# ALL → listes (une entrée par grille présente, ici 0 ou 1).
|
|
return [
|
|
entity_grid_column_defs(hidden_columns, cs) for cs in (column_states or [])
|
|
]
|
|
|
|
# 4) Reset : efface filtres ET tris (columnState avec sort=None). Bouton fixe
|
|
# → grille ALL.
|
|
@callback(
|
|
Output({"type": gtype, "entity_id": ALL, "year": ALL}, "filterModel"),
|
|
Output({"type": gtype, "entity_id": ALL, "year": ALL}, "columnState"),
|
|
Input(f"btn-{org_type}-reset", "n_clicks"),
|
|
State({"type": gtype, "entity_id": ALL, "year": ALL}, "columnState"),
|
|
prevent_initial_call=True,
|
|
)
|
|
def _reset(_n, column_states):
|
|
cleared = [clear_sort(cs) for cs in (column_states or [])]
|
|
return [{} for _ in cleared], cleared
|
|
|
|
# 5) Export filtré (état courant de la grille). Bouton fixe → Download fixe,
|
|
# lit filterModel/columnState de la grille via ALL (state).
|
|
@callback(
|
|
Output(f"{org_type}-download-filtered-data", "data"),
|
|
Input(f"btn-download-filtered-data-{org_type}", "n_clicks"),
|
|
State(f"{org_type}_url", "pathname"),
|
|
State(f"{org_type}_year", "value"),
|
|
State(f"{org_type}_nom", "children"),
|
|
State({"type": gtype, "entity_id": ALL, "year": ALL}, "filterModel"),
|
|
State({"type": gtype, "entity_id": ALL, "year": ALL}, "columnState"),
|
|
prevent_initial_call=True,
|
|
)
|
|
def _download_filtered(_n, pathname, year, nom, filter_models, column_states):
|
|
import datetime as _dt
|
|
|
|
from src.utils.table import write_styled_excel
|
|
|
|
entity_id = (pathname or "").split("/")[-1]
|
|
filter_model = (filter_models or [None])[0]
|
|
column_state = (column_states or [None])[0]
|
|
if filter_model:
|
|
import json
|
|
|
|
from src.utils.tracking import track_search
|
|
|
|
track_search(json.dumps(filter_model), f"{org_type} download")
|
|
df = export_entity_dataframe(org_type, entity_id, year, filter_model, column_state)
|
|
|
|
def to_bytes(buffer):
|
|
write_styled_excel(df, buffer)
|
|
|
|
date = _dt.datetime.now().strftime("%Y-%m-%d_%H:%M:%S")
|
|
label = nom if isinstance(nom, str) else org_type
|
|
return dcc.send_bytes(to_bytes, filename=f"decp_filtrées_{label}_{date}.xlsx")
|
|
|
|
# 6) Meta : "X marchés (Y lignes)" + état du bouton d'export filtré (seuil 65k).
|
|
@callback(
|
|
Output(f"{org_type}_nb_rows", "children"),
|
|
Output(f"btn-download-filtered-data-{org_type}", "disabled"),
|
|
Output(f"btn-download-filtered-data-{org_type}", "children"),
|
|
Output(f"btn-download-filtered-data-{org_type}", "title"),
|
|
Input(f"{org_type}-total", "data"),
|
|
Input(f"{org_type}-total-unique", "data"),
|
|
)
|
|
def _meta(total, total_unique):
|
|
from src.utils.frontend import get_button_properties
|
|
from src.utils.table import format_number
|
|
|
|
total = total or 0
|
|
total_unique = total_unique or 0
|
|
nb_rows = (
|
|
f"{format_number(total_unique) or 0} marchés "
|
|
f"({format_number(total) or 0} lignes)"
|
|
)
|
|
disabled, children, title = get_button_properties(total)
|
|
return nb_rows, disabled, children, title
|
|
```
|
|
|
|
> **Note :** `format_number` est dans `src/utils/table.py` (importé en local pour éviter les cycles). Vérifier lors de l'implémentation que `get_button_properties(count)` renvoie bien `(disabled, children, title)` (cf. `acheteur.update_download_button_acheteur`). Si sa signature/retour diffère, adapter l'appel dans `_meta` en conséquence.
|
|
|
|
- [ ] **Step 4: Lancer le test de fumée, vérifier le succès**
|
|
|
|
Run: `uv run pytest tests/test_entity_grid.py::test_register_entity_grid_callbacks_smoke -v`
|
|
Expected: PASS (aucune exception de validation Dash sur les patterns d'ids).
|
|
|
|
- [ ] **Step 5: Commit**
|
|
|
|
```bash
|
|
pre-commit run --files src/utils/entity_grid.py tests/test_entity_grid.py
|
|
git add src/utils/entity_grid.py tests/test_entity_grid.py
|
|
git commit -m "feat(entity_grid): register_entity_grid_callbacks (datasource/reset/export/meta) (#41)"
|
|
```
|
|
|
|
---
|
|
|
|
## Task 6: Migrer `acheteur.py` vers AG Grid
|
|
|
|
**Files:**
|
|
|
|
- Modify: `src/pages/acheteur.py`
|
|
- Test: manuel (Selenium couvert en Task 8) ; vérifier l'import de la page.
|
|
|
|
**Interfaces:**
|
|
|
|
- Consumes: `entity_grid.register_entity_grid_callbacks`, `entity_grid.build_entity_grid` (indirect via le container), `figures.get_top_org_ag_grid`, helpers existants.
|
|
|
|
- [ ] **Step 1: Remplacer le composant table et les stores dans le layout**
|
|
|
|
Dans `src/pages/acheteur.py` :
|
|
|
|
1. **Imports** : retirer `DataTable` de l'import `src.figures` ; ajouter `get_top_org_ag_grid`. Retirer les imports devenus inutiles (`filter_table_data`, `sort_table_data`, `prepare_table_data`, `COLUMNS`, `get_default_hidden_columns` si plus utilisés localement — garder ceux encore référencés). Ajouter :
|
|
|
|
```python
|
|
from src.utils.entity_grid import register_entity_grid_callbacks
|
|
```
|
|
|
|
2. **Supprimer** le bloc `DATATABLE = html.Div(className="marches_table", children=DataTable(dtid="acheteur_datatable", ...))` (lignes ~71-85).
|
|
|
|
3. **Convertir `layout` en fonction** `def layout(acheteur_id=None, **kwargs):` qui retourne l'actuelle liste, avec ces changements dans le corps :
|
|
- Conserver `dcc.Location(id="acheteur_url", ...)`, tous les composants d'infos/carte/stats/histogramme **inchangés**.
|
|
- Ajouter, à côté de `dcc.Store(id="acheteur-hidden-columns", storage_type="local")` :
|
|
|
|
```python
|
|
dcc.Store(id="acheteur-total"),
|
|
dcc.Store(id="acheteur-total-unique"),
|
|
dcc.Store(id="entity-grid-columns-state", storage_type="local"),
|
|
```
|
|
|
|
- Remplacer le `DATATABLE` (dernier enfant, ligne ~256) par le container hôte de la grille :
|
|
|
|
```python
|
|
html.Div(id="acheteur-grid-container", className="marches_table"),
|
|
```
|
|
|
|
> `entity-grid-columns-state` est **partagé** avec titulaire.py. Il est déclaré dans les deux `layout()` : Dash tolère un même id de Store présent sur des pages différentes (une seule page montée à la fois). Ne PAS le déclarer dans un layout global.
|
|
|
|
- [ ] **Step 2: Supprimer les callbacks DataTable, enregistrer les callbacks de grille**
|
|
|
|
Dans `src/pages/acheteur.py`, **supprimer** les callbacks devenus obsolètes :
|
|
|
|
- `get_last_marches_data` (Output `acheteur_datatable.*`).
|
|
- `download_filtered_acheteur_data` (remplacé par le callback export de `register_entity_grid_callbacks`).
|
|
- le `clientside_callback` `clean_filters` + le `dcc.Store(id="filter-cleanup-trigger-acheteur")`.
|
|
- `store_hidden_columns` (Output `acheteur_datatable.hidden_columns`).
|
|
- `reset_view` (Output `acheteur_datatable.filter_query/sort_by`) — remplacé par le reset de la grille.
|
|
|
|
**Conserver inchangés** : `update_acheteur_infos`, `update_acheteur_map`, `update_acheteur_stats`, `update_download_button_acheteur`, `download_acheteur_data` (bouton « toutes les données »), `update_hidden_columns_from_checkboxes`, `toggle_acheteur_columns`, `update_acheteur_distance_histogram`.
|
|
|
|
**Corriger** `update_checkboxes_from_hidden_columns` : son `Input` pointe aujourd'hui vers `acheteur_datatable.hidden_columns` (prop qui disparaît avec la DataTable). Le rebrancher sur le **store** :
|
|
|
|
```python
|
|
@callback(
|
|
Output("acheteur_column_list", "selected_rows"),
|
|
Input("acheteur-hidden-columns", "data"),
|
|
State("acheteur_column_list", "selected_rows"), # pour éviter la boucle infinie
|
|
)
|
|
def update_checkboxes_from_hidden_columns(hidden_cols, current_checkboxes):
|
|
hidden_cols = hidden_cols or get_default_hidden_columns("acheteur")
|
|
visible_cols = [COLUMNS.index(col) for col in COLUMNS if col not in hidden_cols]
|
|
return visible_cols
|
|
```
|
|
|
|
(Garder donc les imports `COLUMNS` et `get_default_hidden_columns` dans `acheteur.py`.)
|
|
|
|
**Migrer le top 10** : dans `get_top_titulaires`, remplacer `get_top_org_table(...)` par `get_top_org_ag_grid(...)` :
|
|
|
|
```python
|
|
@callback(
|
|
Output(component_id="top10_titulaires", component_property="children"),
|
|
Input(component_id="acheteur_url", component_property="pathname"),
|
|
Input(component_id="acheteur_year", component_property="value"),
|
|
)
|
|
def get_top_titulaires(pathname, ach_year):
|
|
where_sql, params = _acheteur_scope(pathname, ach_year)
|
|
table = get_top_org_ag_grid(
|
|
query_marches(where_sql, params).lazy(), "titulaire", ["titulaire_distance"]
|
|
)
|
|
return make_card(fig=table, title="Top titulaires", lg=12, xl=12)
|
|
```
|
|
|
|
**Enregistrer les callbacks de grille** (une fois, au niveau module, après les définitions de callbacks) :
|
|
|
|
```python
|
|
register_entity_grid_callbacks("acheteur")
|
|
```
|
|
|
|
**Unifier le scope** : `_acheteur_scope` reste utilisé par les callbacks conservés (carte, stats, download « toutes les données », top 10) — le **garder** mais le faire **déléguer** à `entity_scope` (source unique, plus de duplication du WHERE) :
|
|
|
|
```python
|
|
from src.utils.entity_grid import entity_scope, register_entity_grid_callbacks
|
|
|
|
|
|
def _acheteur_scope(pathname: str, ach_year: str | None) -> tuple[str, list]:
|
|
"""WHERE SQL scopant les requêtes à cet acheteur (et éventuellement une année)."""
|
|
return entity_scope("acheteur", pathname.split("/")[-1], ach_year)
|
|
```
|
|
|
|
- [ ] **Step 3: Corriger le smoke test entity_grid (double enregistrement)**
|
|
|
|
À partir de maintenant, `acheteur.py` appelle `register_entity_grid_callbacks("acheteur")` **au niveau module** (à l'import). Or `tests/test_entity_grid.py::test_register_entity_grid_callbacks_smoke` fait `import src.app` (qui importe la page → 1er enregistrement) **puis** rappelle `register_entity_grid_callbacks("acheteur")` (2e enregistrement) → collision des Outputs org-spécifiques (`acheteur-total`, etc. — sans `allow_duplicate`), erreur `DuplicateCallback`.
|
|
|
|
Rendre ce test « forward-safe » : ne plus ré-enregistrer, mais **vérifier que l'enregistrement fait à l'import a bien eu lieu**. Remplacer son corps par :
|
|
|
|
```python
|
|
def test_register_entity_grid_callbacks_registered_via_page_import():
|
|
"""Les callbacks de grille entité sont enregistrés (une fois) à l'import
|
|
des pages acheteur/titulaire — pas de double enregistrement."""
|
|
import src.app # noqa: F401 # importe les pages → register_entity_grid_callbacks
|
|
|
|
from dash import get_app
|
|
|
|
callback_map = get_app().callback_map
|
|
# Le store columnState partagé est piloté par un callback enregistré.
|
|
assert any("entity-grid-columns-state.data" in k for k in callback_map)
|
|
```
|
|
|
|
(Renommer le test depuis `test_register_entity_grid_callbacks_smoke`.)
|
|
|
|
- [ ] **Step 4: Vérifier que la page s'importe sans erreur**
|
|
|
|
Run: `uv run python -c "import src.app; import src.pages.acheteur; print('acheteur OK')"`
|
|
Expected: `acheteur OK` (aucune exception de validation Dash : ids en double, patterns invalides, Output dupliqués sans `allow_duplicate`).
|
|
|
|
> Si Dash signale un Output dupliqué autre que ceux déjà gérés, ajouter `allow_duplicate=True` + `prevent_initial_call=True` sur l'Output concerné (le store `entity-grid-columns-state.data` a déjà `allow_duplicate=True` depuis la Task 5).
|
|
|
|
- [ ] **Step 5: Vérifier le rendu réel de la page (skill run)**
|
|
|
|
Lancer l'app et charger `/acheteurs/<un_id_présent_dans_test.parquet>`. Vérifier : la grille s'affiche, filtre multi-conditions (ET/OU + Contient) fonctionne, tri fonctionne, le compteur affiche « X marchés (Y lignes) », le bouton Réinitialiser vide filtres+tris, l'export filtré télécharge un fichier cohérent, le sélecteur de colonnes masque/affiche, le top 10 s'affiche en AG Grid.
|
|
|
|
> Utiliser le skill `run` (ou `uv run run.py`) ; ne pas cocher cette étape tant que la grille n'est pas vérifiée visuellement fonctionnelle.
|
|
|
|
- [ ] **Step 5: Commit**
|
|
|
|
```bash
|
|
pre-commit run --files src/pages/acheteur.py
|
|
git add src/pages/acheteur.py
|
|
git commit -m "feat(acheteur): migration du tableau des marchés vers AG Grid (#41)"
|
|
```
|
|
|
|
---
|
|
|
|
## Task 7: Migrer `titulaire.py` vers AG Grid
|
|
|
|
**Files:**
|
|
|
|
- Modify: `src/pages/titulaire.py`
|
|
|
|
**Interfaces:** identiques à Task 6, substitutions `acheteur`→`titulaire`. Différences spécifiques titulaire détaillées ci-dessous.
|
|
|
|
- [ ] **Step 1: Layout — stores + container**
|
|
|
|
Dans `src/pages/titulaire.py` :
|
|
|
|
- Imports : retirer `DataTable`, ajouter `get_top_org_ag_grid` et `from src.utils.entity_grid import register_entity_grid_callbacks`.
|
|
- Supprimer le bloc `DATATABLE = html.Div(..., DataTable(dtid="titulaire_datatable", ...))` (lignes ~70-84).
|
|
- `layout` → `def layout(titulaire_id=None, **kwargs):`.
|
|
- Ajouter près de `dcc.Store(id="titulaire-hidden-columns", ...)` :
|
|
|
|
```python
|
|
dcc.Store(id="titulaire-total"),
|
|
dcc.Store(id="titulaire-total-unique"),
|
|
dcc.Store(id="entity-grid-columns-state", storage_type="local"),
|
|
```
|
|
|
|
- Remplacer le `DATATABLE` final (ligne ~271) par :
|
|
|
|
```python
|
|
html.Div(id="titulaire-grid-container", className="marches_table"),
|
|
```
|
|
|
|
- [ ] **Step 2: Callbacks — suppression + registration + top 10**
|
|
|
|
- Supprimer : `get_last_marches_data` (Output `titulaire_datatable.*`), `download_filtered_titulaire_data`, le `clientside_callback` `clean_filters` + `dcc.Store(id="filter-cleanup-trigger-titulaire")`, `store_hidden_columns` (Output `titulaire_datatable.hidden_columns`), `reset_view` (Output `titulaire_datatable.*`).
|
|
- Conserver inchangés : `update_titulaire_infos`, `update_titulaire_map`, `update_titulaire_stats`, `update_download_button_titulaire`, `download_titulaire_data`, `update_hidden_columns_from_checkboxes`, `toggle_titulaire_columns`, `update_titulaire_distance_histogram`.
|
|
- **Corriger** `update_checkboxes_from_hidden_columns` (comme pour acheteur) : rebrancher son `Input("titulaire_datatable", "hidden_columns")` sur `Input("titulaire-hidden-columns", "data")` (le store), corps inchangé sinon (utilise `COLUMNS`/`get_default_hidden_columns("titulaire")`). Garder ces imports.
|
|
- **Top 10 (spécifique titulaire)** : `get_top_acheteurs` n'utilise PAS `make_card` — il retourne la table directement dans `html.Div(id="top10_acheteurs")` (qui a déjà son `<H3>Top acheteurs` dans le layout, lignes ~189-194). Migrer ainsi :
|
|
|
|
```python
|
|
@callback(
|
|
Output(component_id="top10_acheteurs", component_property="children"),
|
|
Input(component_id="titulaire_url", component_property="pathname"),
|
|
Input(component_id="titulaire_year", component_property="value"),
|
|
)
|
|
def get_top_acheteurs(pathname, titulaire_year):
|
|
where_sql, params = _titulaire_scope(pathname, titulaire_year)
|
|
return get_top_org_ag_grid(
|
|
query_marches(where_sql, params).lazy(), "acheteur", ["titulaire_distance"]
|
|
)
|
|
```
|
|
|
|
- Enregistrer les callbacks de grille (niveau module) :
|
|
|
|
```python
|
|
register_entity_grid_callbacks("titulaire")
|
|
```
|
|
|
|
- **Unifier le scope** : garder `_titulaire_scope` (utilisé par carte/stats/download/top 10) mais le faire déléguer à `entity_scope` — qui ajoute déjà `titulaire_typeIdentifiant = 'SIRET'` pour `org_type="titulaire"` :
|
|
|
|
```python
|
|
from src.utils.entity_grid import entity_scope, register_entity_grid_callbacks
|
|
|
|
|
|
def _titulaire_scope(pathname: str, titulaire_year: str | None) -> tuple[str, list]:
|
|
"""WHERE SQL scopant les requêtes à ce titulaire (et éventuellement une année)."""
|
|
return entity_scope("titulaire", pathname.split("/")[-1], titulaire_year)
|
|
```
|
|
|
|
- [ ] **Step 3: Vérifier l'import de la page**
|
|
|
|
Run: `uv run python -c "import src.app; import src.pages.titulaire; print('titulaire OK')"`
|
|
Expected: `titulaire OK`.
|
|
|
|
- [ ] **Step 4: Vérifier le rendu réel (skill run)**
|
|
|
|
Charger `/titulaires/<un_id_SIRET_présent_dans_test.parquet>`. Mêmes vérifications qu'en Task 6 Step 4, plus : le scope SIRET s'applique (pas de lignes non-SIRET). Vérifier aussi qu'après avoir redimensionné/réordonné une colonne sur `/acheteurs/...` puis navigué vers `/titulaires/...`, la disposition des colonnes est **conservée** (store partagé), mais que le **filtre** n'est PAS repris d'une fiche à l'autre.
|
|
|
|
- [ ] **Step 5: Commit**
|
|
|
|
```bash
|
|
pre-commit run --files src/pages/titulaire.py
|
|
git add src/pages/titulaire.py
|
|
git commit -m "feat(titulaire): migration du tableau des marchés vers AG Grid (#41)"
|
|
```
|
|
|
|
---
|
|
|
|
## Task 8: Mettre à jour les tests d'intégration + suite complète
|
|
|
|
**Files:**
|
|
|
|
- Modify: `tests/test_main.py:63-95` (`test_002_filter_persistence`), `tests/test_main.py:98-121` (`test_003_tableau_download`)
|
|
|
|
> Note : la correction « Dash 3.4 → Dash 4.4 » dans `CLAUDE.md` a déjà été faite par l'utilisateur — ne pas la refaire.
|
|
|
|
- [ ] **Step 1: Adapter `test_002_filter_persistence` aux sélecteurs AG Grid**
|
|
|
|
Ce test pilote `/acheteurs/123` et `/titulaires/345` et cherche l'input de filtre de colonne DataTable (`.marches_table th[data-dash-column="dateNotification"] input[type="text"]`). Avec AG Grid, le filtre flottant d'une colonne est un `input` dans `.ag-floating-filter-input` de la colonne correspondante. Lire d'abord le test actuel :
|
|
|
|
Run: `uv run pytest tests/test_main.py::test_002_filter_persistence -v`
|
|
Expected (avant correction) : FAIL/erreur (sélecteur DataTable absent sur la grille AG Grid).
|
|
|
|
Adapter le corps pour cibler le filtre flottant AG Grid. Remplacer la recherche du champ de filtre par (adapter aux noms de variables du test existant) :
|
|
|
|
```python
|
|
# AG Grid : le filtre flottant de la colonne dateNotification est un input
|
|
# dans la cellule d'en-tête flottante correspondante. On l'atteint via le
|
|
# col-id AG Grid (= nom du champ).
|
|
filter_input = dash_duo.wait_for_element(
|
|
'div[col-id="dateNotification"] .ag-floating-filter-input input',
|
|
timeout=10,
|
|
)
|
|
filter_input.send_keys("2024")
|
|
```
|
|
|
|
> Le `col-id` AG Grid vaut le `field` de la columnDef (= nom de colonne DECP). Vérifier le sélecteur exact au moment de l'implémentation en inspectant le DOM rendu (le skill `run` peut servir à confirmer la structure `.ag-floating-filter-input`). Conserver l'intention du test (persistance du filtre après rechargement) : après saisie, recharger la page et vérifier que la valeur du filtre persiste — mais **attention** : la persistance filterModel est désormais scopée par `(entity_id, year)` ; le test doit recharger la **même** fiche pour observer la persistance.
|
|
|
|
- [ ] **Step 2: Vérifier `test_003_tableau_download`**
|
|
|
|
Ce test appelle directement `download_data(1, None, None)` (tableau), `download_acheteur_data(1, "/acheteurs/123", "2025", "ACHETEUR 1")`, `download_titulaire_data(1, "/titulaires/345", "2025", "TITULAIRE 1")`. Ces trois callbacks (« toutes les données ») ne changent PAS de signature dans ce lot. Vérifier qu'ils s'importent et s'appellent toujours :
|
|
|
|
Run: `uv run pytest tests/test_main.py::test_003_tableau_download -v`
|
|
Expected: PASS sans modification. Si un `ImportError` survient (ex. un helper supprimé était importé en tête du test), corriger l'import ; ne pas changer la logique du test.
|
|
|
|
- [ ] **Step 3: Lancer les tests ciblés**
|
|
|
|
Run: `uv run pytest tests/test_main.py::test_002_filter_persistence tests/test_main.py::test_003_tableau_download tests/test_entity_grid.py tests/test_grid.py tests/test_figures.py -v`
|
|
Expected: PASS.
|
|
|
|
- [ ] **Step 4: Lancer la suite complète (fin de lot)**
|
|
|
|
Run: `uv run pytest`
|
|
Expected: PASS (hors flakes Selenium préexistants éventuels — les identifier en relançant le test isolé et en confirmant qu'il échoue aussi sur `dev` sans ce lot ; cf. mémoire projet). Aucun échec **nouveau** attribuable à ce lot.
|
|
|
|
- [ ] **Step 5: Commit**
|
|
|
|
```bash
|
|
pre-commit run --files tests/test_main.py
|
|
git add tests/test_main.py
|
|
git commit -m "test(acheteur/titulaire): sélecteurs AG Grid pour la grille des marchés (#41)"
|
|
```
|
|
|
|
---
|
|
|
|
## Notes de fin de lot
|
|
|
|
- **`entity-grid-columns-state`** est un store `storage_type="local"` partagé acheteur+titulaire ; sa déclaration apparaît dans les deux `layout()`. Si Dash se plaint d'un id dupliqué au chargement simultané (ne devrait pas : une page montée à la fois), déplacer sa déclaration dans un layout applicatif global unique (`src/app.py`) et retirer des pages.
|
|
- **Persistance filterModel scopée** : repose sur le fait que dash-ag-grid sérialise l'id dict comme clé localStorage. Le vérifier en Task 6 Step 4 (deux acheteurs distincts → filtres indépendants). Si la persistance ne discrimine pas par id, repli documenté dans la spec (« reset systématique au changement de fiche » — le remontage de grille le fait déjà, seul le rappel du filtre par fiche serait perdu).
|
|
- **Scope unifié** : `entity_scope` (entity_grid.py) est la source unique du WHERE ; `_acheteur_scope`/`_titulaire_scope` sont de fins wrappers qui y délèguent. `_top_org_aggregate` (figures.py) est la source unique de l'agrégation top N, partagée par `get_top_org_table` et `get_top_org_ag_grid`.
|
|
- **Hors périmètre confirmé** : sélecteur de colonnes (`make_column_picker` reste DataTable, partagé avec tableau.py), `observatoire.py` (Lot 2b).
|