diff --git a/CHANGELOG.md b/CHANGELOG.md index ce56bf3..e7cfd94 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,7 @@ +##### 2.7.4 (22 avril 2026) + +- Utilisation élargie de DuckDB au détriment de Polars => bien meilleure perf ([#72](https://github.com/ColinMaudry/decp.info/issues/72) + ##### 2.7.3 (20 avril 2026) - Mise en cache des vues tableau par ensemble de filtres et de tris diff --git a/docs/superpowers/plans/2026-04-21-tableau-performance-duckdb.md b/docs/superpowers/plans/2026-04-21-tableau-performance-duckdb.md new file mode 100644 index 0000000..fa887a8 --- /dev/null +++ b/docs/superpowers/plans/2026-04-21-tableau-performance-duckdb.md @@ -0,0 +1,1016 @@ +# Plan : optimisation performance page Tableau via DuckDB + +> **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 :** Réduire le temps de chargement _cold_ de `/tableau` (actuellement ~11 s sans filtre ni tri) à moins de 2 s, et le _warm_ (~5 s) à moins de 500 ms, en utilisant DuckDB comme moteur de requête (filtres, tri, pagination, comptage en SQL) plutôt que comme simple stockage. + +**Architecture :** + +1. Traduire le DSL de filtres de `dash_table.DataTable` (ex : `{objet} icontains travaux && {montant} i> 40000`) en SQL DuckDB paramétré. +2. Pousser `WHERE` / `ORDER BY` / `LIMIT` / `OFFSET` dans DuckDB plutôt que matérialiser 1,6 M lignes dans Polars. +3. Ne faire tourner le post-traitement coûteux (cast en String, liens HTML, formatage montants) **que sur la page courante** (20 lignes), pas sur le dataset complet. +4. Remplacer le cache `@cache.memoize()` sur la DataFrame complète par deux caches plus fins : un cache de `COUNT(*)` par `filter_query`, et un cache de pages par `(filter_query, sort_by, page_current, page_size)`. +5. Conserver intact le chemin existant `filter_table_data` (Polars LazyFrame) utilisé par `acheteur`, `titulaire`, `observatoire` qui passent déjà des données pré-filtrées via le paramètre `data`. + +**Tech Stack :** Python 3, Polars, DuckDB, Dash, Flask-Caching, pytest. + +**Périmètre explicite :** + +- **Inclus :** chemin `data is None` dans `prepare_table_data` (utilisé uniquement par `/tableau`). +- **Exclus :** refactor des pages acheteur/titulaire/observatoire (bénéficieraient d'un suivi, mais le chemin n'est pas le goulet d'étranglement actuel). +- **Exclus :** projection des colonnes cachées dans le `SELECT` (pourrait être une optimisation de suite ; non-triviale car le navigateur a besoin du schéma complet pour `setup_table_columns`). +- **Exclus :** index DuckDB. DuckDB est un moteur analytique, il tire parti du stockage columnaire sans index B-tree. On mesure avant d'ajouter quoi que ce soit. + +--- + +## Structure de fichiers + +| Fichier | Opération | Responsabilité | +| ------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------- | +| `src/utils/table_sql.py` | **Créer** | Traducteurs : `filter_query_to_sql()` et `sort_by_to_sql()`. Pur, testable sans Dash ni DB. | +| `src/db.py` | **Modifier** | Ajouter `count_marches(where_sql, params)` et paramètre `offset` à `query_marches()`. | +| `src/utils/table.py` | **Modifier** | Nouveau chemin rapide SQL dans `_load_filter_sort_postprocess`. Découpage du post-traitement en deux étapes (full → page-seule). | +| `tests/test_table_sql.py` | **Créer** | Tests unitaires des traducteurs (pur, aucune DB). | +| `tests/test_table.py` | **Modifier** | Ajouter tests d'intégration nouveau chemin ; garder les tests existants verts. | +| `tests/test_db.py` | **Modifier** | Tests pour `count_marches` et `offset`. | + +--- + +## Task 0 : Setup (à décider avec l'utilisateur avant de lancer) + +**À clarifier avec l'utilisateur :** + +- Sur quelle branche travailler ? `feature/73_compte_utilisateur` a 13+ fichiers non-commités. Probablement besoin de les mettre de côté, puis `git flow feature start NN_tableau_perf_duckdb`. +- Un numéro d'issue existe-t-il (ex : dans le dépôt GitHub) ? Sinon en créer un. + +**Pas de code à écrire tant que ce point n'est pas tranché.** + +--- + +## Task 1 : Traducteur `filter_query` → SQL `WHERE` + +**Files:** + +- Create: `src/utils/table_sql.py` +- Test: `tests/test_table_sql.py` + +Le DSL de DataTable a cette forme (vu dans `src/utils/table.py:216-279`) : + +- Séparateur entre filtres : `" && "` +- Opérateurs : `icontains`, `i<`, `i>`, `s<`, `s>` (existants dans `split_filter_part`) +- Wildcards sur string : `texte*` (starts_with), `*texte` (ends_with), sinon `contains` insensible à la casse +- Sur numériques : `icontains N` signifie `= N` + +On s'appuie sur `split_filter_part` existant pour le parsing d'un fragment. + +- [ ] **Step 1 : Écrire le test unitaire en échec** + +Créer `tests/test_table_sql.py` : + +```python +import polars as pl +import pytest + + +SCHEMA = pl.Schema({ + "uid": pl.String, + "objet": pl.String, + "acheteur_id": pl.String, + "montant": pl.Float64, + "dureeMois": pl.Int64, + "dateNotification": pl.Date, +}) + + +def test_empty_filter_returns_true(): + from src.utils.table_sql import filter_query_to_sql + + where, params = filter_query_to_sql("", SCHEMA) + assert where == "TRUE" + assert params == [] + + +def test_icontains_string_is_case_insensitive_like(): + from src.utils.table_sql import filter_query_to_sql + + where, params = filter_query_to_sql("{objet} icontains travaux", SCHEMA) + # ILIKE '%travaux%' en DuckDB + assert where == '"objet" IS NOT NULL AND "objet" <> \'\' AND "objet" ILIKE ?' + assert params == ["%travaux%"] + + +def test_icontains_with_trailing_wildcard_is_starts_with(): + from src.utils.table_sql import filter_query_to_sql + + where, params = filter_query_to_sql("{acheteur_id} icontains 24350013900189*", SCHEMA) + assert where == '"acheteur_id" IS NOT NULL AND "acheteur_id" <> \'\' AND "acheteur_id" ILIKE ?' + assert params == ["24350013900189%"] + + +def test_icontains_with_leading_wildcard_is_ends_with(): + from src.utils.table_sql import filter_query_to_sql + + where, params = filter_query_to_sql("{uid} icontains *2024", SCHEMA) + assert where == '"uid" IS NOT NULL AND "uid" <> \'\' AND "uid" ILIKE ?' + assert params == ["%2024"] + + +def test_numeric_greater_than(): + from src.utils.table_sql import filter_query_to_sql + + where, params = filter_query_to_sql("{montant} i> 40000", SCHEMA) + assert where == '"montant" IS NOT NULL AND "montant" > ?' + assert params == [40000] + + +def test_numeric_less_than(): + from src.utils.table_sql import filter_query_to_sql + + where, params = filter_query_to_sql("{montant} i< 1000", SCHEMA) + assert where == '"montant" IS NOT NULL AND "montant" < ?' + assert params == [1000] + + +def test_numeric_equality_via_icontains(): + from src.utils.table_sql import filter_query_to_sql + + where, params = filter_query_to_sql("{dureeMois} icontains 12", SCHEMA) + assert where == '"dureeMois" IS NOT NULL AND "dureeMois" = ?' + assert params == [12] + + +def test_date_column_treated_as_string_ilike(): + from src.utils.table_sql import filter_query_to_sql + + where, params = filter_query_to_sql("{dateNotification} icontains 2024*", SCHEMA) + # Les dates sont castées en String pour filtrage textuel (parité avec le chemin Polars) + assert "ILIKE" in where + assert params == ["2024%"] + + +def test_multiple_filters_joined_by_and(): + from src.utils.table_sql import filter_query_to_sql + + filter_query = "{objet} icontains voirie && {montant} i> 40000" + where, params = filter_query_to_sql(filter_query, SCHEMA) + assert " AND " in where + assert params == ["%voirie%", 40000] + + +def test_invalid_numeric_value_is_skipped(): + from src.utils.table_sql import filter_query_to_sql + + # Ne pas faire planter l'app si l'utilisateur tape n'importe quoi + where, params = filter_query_to_sql("{montant} i> notanumber", SCHEMA) + assert where == "TRUE" + assert params == [] + + +def test_unknown_column_is_skipped(): + from src.utils.table_sql import filter_query_to_sql + + where, params = filter_query_to_sql("{inexistant} icontains foo", SCHEMA) + assert where == "TRUE" + assert params == [] + + +def test_escapes_identifier_with_quotes_not_concatenation(): + """Sanity check : les noms de colonnes sont entre guillemets doubles (identifiants SQL), + les valeurs sont passées en paramètres (pas concaténées).""" + from src.utils.table_sql import filter_query_to_sql + + where, params = filter_query_to_sql("{objet} icontains '; DROP TABLE decp; --", SCHEMA) + # La valeur doit être dans params, jamais dans where + assert "DROP TABLE" not in where + assert any("DROP TABLE" in str(p) for p in params) +``` + +- [ ] **Step 2 : Lancer le test pour vérifier l'échec** + +Run : `rtk uv run pytest tests/test_table_sql.py -v` +Expected : FAIL avec `ModuleNotFoundError: No module named 'src.utils.table_sql'`. + +- [ ] **Step 3 : Implémenter le traducteur** + +Créer `src/utils/table_sql.py` : + +```python +import polars as pl + +from src.utils import logger +from src.utils.table import split_filter_part + + +def filter_query_to_sql( + filter_query: str, schema: pl.Schema +) -> tuple[str, list]: + """Traduit le DSL de filtres de dash_table.DataTable en fragment SQL DuckDB. + + Retourne (where_clause, params) où where_clause est un fragment à injecter + après `WHERE` et params est la liste des valeurs à passer à + `cursor.execute(sql, params)`. Les identifiants de colonnes sont validés + contre le schéma fourni ; jamais concaténés avec des valeurs utilisateur. + """ + if not filter_query: + return "TRUE", [] + + clauses: list[str] = [] + params: list = [] + + for part in filter_query.split(" && "): + col_name, operator, raw_value = split_filter_part(part) + if not isinstance(col_name, str) or not isinstance(raw_value, str): + continue + + if col_name not in schema.names(): + logger.warning(f"Colonne inconnue ignorée : {col_name!r}") + continue + + col_type = str(schema[col_name]) + is_numeric = col_type.startswith("Int") or col_type.startswith("Float") + quoted_col = f'"{col_name}"' + + if is_numeric: + try: + value = int(raw_value) if col_type.startswith("Int") else float(raw_value) + except ValueError: + logger.warning(f"Valeur numérique invalide ignorée : {raw_value!r}") + continue + + if operator == "contains": + clauses.append(f"{quoted_col} IS NOT NULL AND {quoted_col} = ?") + elif operator == ">": + clauses.append(f"{quoted_col} IS NOT NULL AND {quoted_col} > ?") + elif operator == "<": + clauses.append(f"{quoted_col} IS NOT NULL AND {quoted_col} < ?") + else: + logger.warning(f"Opérateur invalide pour numérique : {operator!r}") + continue + params.append(value) + continue + + # String / Date : toujours traité comme texte (parité avec Polars) + value = raw_value.strip('"') + col_is_date = col_type == "Date" + + if operator == "contains": + if value.endswith("*") and not value.startswith("*"): + like = value[:-1] + "%" + elif value.startswith("*") and not value.endswith("*"): + like = "%" + value[1:] + else: + like = "%" + value + "%" + # Pour les dates : CAST en TEXT côté DuckDB avant ILIKE + target = f"CAST({quoted_col} AS VARCHAR)" if col_is_date else quoted_col + clauses.append( + f"{quoted_col} IS NOT NULL AND {target} <> '' AND {target} ILIKE ?" + ) + params.append(like) + elif operator in (">", "<"): + # Comparaison lexicographique (on cast en varchar pour les dates, + # ce qui reste correct car le format ISO est trié-stable) + target = f"CAST({quoted_col} AS VARCHAR)" if col_is_date else quoted_col + clauses.append( + f"{quoted_col} IS NOT NULL AND {target} {operator} ?" + ) + params.append(value) + else: + logger.warning(f"Opérateur invalide pour chaîne : {operator!r}") + continue + + if not clauses: + return "TRUE", [] + return " AND ".join(clauses), params + + +def sort_by_to_sql(sort_by: list[dict], schema: pl.Schema) -> str: + """Traduit sort_by (format Dash) en clause ORDER BY DuckDB. + + Retourne '' si pas de tri (aucun ORDER BY à ajouter). + """ + if not sort_by: + return "" + + fragments: list[str] = [] + for entry in sort_by: + col = entry.get("column_id") + direction = entry.get("direction") + if col not in schema.names(): + logger.warning(f"Tri sur colonne inconnue ignoré : {col!r}") + continue + if direction not in ("asc", "desc"): + continue + fragments.append(f'"{col}" {direction.upper()} NULLS LAST') + + return ", ".join(fragments) +``` + +- [ ] **Step 4 : Lancer le test** + +Run : `rtk uv run pytest tests/test_table_sql.py -v` +Expected : PASS (12 tests). + +- [ ] **Step 5 : Ajouter les tests pour `sort_by_to_sql`** + +Ajouter à `tests/test_table_sql.py` : + +```python +def test_sort_by_empty(): + from src.utils.table_sql import sort_by_to_sql + assert sort_by_to_sql([], SCHEMA) == "" + assert sort_by_to_sql(None, SCHEMA) == "" + + +def test_sort_by_single_column_desc(): + from src.utils.table_sql import sort_by_to_sql + result = sort_by_to_sql([{"column_id": "montant", "direction": "desc"}], SCHEMA) + assert result == '"montant" DESC NULLS LAST' + + +def test_sort_by_multiple_columns_preserves_order(): + from src.utils.table_sql import sort_by_to_sql + result = sort_by_to_sql( + [ + {"column_id": "dateNotification", "direction": "desc"}, + {"column_id": "montant", "direction": "asc"}, + ], + SCHEMA, + ) + assert result == '"dateNotification" DESC NULLS LAST, "montant" ASC NULLS LAST' + + +def test_sort_by_ignores_unknown_column(): + from src.utils.table_sql import sort_by_to_sql + result = sort_by_to_sql([{"column_id": "fake", "direction": "asc"}], SCHEMA) + assert result == "" +``` + +- [ ] **Step 6 : Lancer les tests** + +Run : `rtk uv run pytest tests/test_table_sql.py -v` +Expected : PASS (16 tests). + +- [ ] **Step 7 : Commit** + +```bash +rtk git add src/utils/table_sql.py tests/test_table_sql.py +rtk pre-commit +rtk git add src/utils/table_sql.py tests/test_table_sql.py +rtk git commit -m "feat: ajouter traducteurs filter_query→SQL et sort_by→SQL" +``` + +--- + +## Task 2 : Ajouter `count_marches` et `offset` dans `src/db.py` + +**Files:** + +- Modify: `src/db.py` +- Modify: `tests/test_db.py` + +- [ ] **Step 1 : Écrire les tests en échec** + +Ajouter à `tests/test_db.py` : + +```python +def test_count_marches_returns_total_without_filter(): + from src.db import count_marches + n = count_marches() + # Le dataset de test a forcément au moins une ligne + assert isinstance(n, int) + assert n > 0 + + +def test_count_marches_with_filter(): + from src.db import count_marches + # Une condition qui ne match rien doit retourner 0 + n = count_marches('"uid" = ?', ["__nonexistent__"]) + assert n == 0 + + +def test_query_marches_with_offset(): + from src.db import query_marches + page_0 = query_marches(limit=2, offset=0) + page_1 = query_marches(limit=2, offset=2) + # Les deux pages ne partagent aucune ligne (sauf dataset < 4 lignes) + if page_0.height == 2 and page_1.height >= 1: + assert set(page_0["uid"].to_list()).isdisjoint(set(page_1["uid"].to_list())) +``` + +- [ ] **Step 2 : Vérifier l'échec** + +Run : `rtk uv run pytest tests/test_db.py -v -k "count_marches or offset"` +Expected : ERROR `cannot import name 'count_marches'` + TypeError pour `offset`. + +- [ ] **Step 3 : Implémenter** + +Modifier `src/db.py`. + +Remplacer la signature de `query_marches` pour ajouter `offset` : + +```python +def query_marches( + where_sql: str = "TRUE", + params: tuple | list = (), + columns: list[str] | None = None, + order_by: str | None = None, + limit: int | None = None, + offset: int | None = None, +) -> pl.DataFrame: + """Run a parameterized SELECT against the decp table and return Polars. + + `where_sql` and `order_by` are trusted SQL fragments (callers are internal + code, never user input). `params` values are passed through DuckDB's + parameter binding. + """ + cols = ", ".join(columns) if columns else "*" + sql = f"SELECT {cols} FROM decp WHERE {where_sql}" + if order_by: + sql += f" ORDER BY {order_by}" + if limit is not None: + sql += f" LIMIT {int(limit)}" + if offset is not None: + sql += f" OFFSET {int(offset)}" + return get_cursor().execute(sql, list(params)).pl() +``` + +Ajouter à la fin de `src/db.py` : + +```python +def count_marches(where_sql: str = "TRUE", params: tuple | list = ()) -> int: + """Retourne le nombre de lignes correspondant à where_sql. + + Utilisé pour afficher `X lignes` au-dessus de la table sans matérialiser + les lignes en mémoire. + """ + sql = f"SELECT COUNT(*) FROM decp WHERE {where_sql}" + result = get_cursor().execute(sql, list(params)).fetchone() + return int(result[0]) if result else 0 +``` + +- [ ] **Step 4 : Lancer les tests** + +Run : `rtk uv run pytest tests/test_db.py -v` +Expected : PASS (tests existants + 3 nouveaux). + +- [ ] **Step 5 : Commit** + +```bash +rtk git add src/db.py tests/test_db.py +rtk pre-commit +rtk git add src/db.py tests/test_db.py +rtk git commit -m "feat(db): ajouter count_marches et paramètre offset à query_marches" +``` + +--- + +## Task 3 : Découper le post-traitement en deux étapes + +Actuellement `table_postprocess` (dans `src/utils/table.py:401-410`) fait : + +1. cast de toutes les colonnes en String +2. `fill_null("")` +3. `add_links` (ajoute des `` autour de uid, acheteur_nom, titulaire_nom, acheteur_id, titulaire_id) +4. `add_resource_link` (si `sourceFile` présent) +5. `format_values` (formatage des montants et distances) + +Ces opérations sont **idempotentes au niveau ligne** : les faire sur 20 lignes au lieu de 1,6 M donne exactement le même résultat pour les 20 lignes affichées. + +**Files:** + +- Modify: `src/utils/table.py` +- Modify: `tests/test_table.py` + +- [ ] **Step 1 : Écrire le test en échec** + +Ajouter à `tests/test_table.py` : + +```python +def test_postprocess_page_produces_same_result_as_full_then_slice(flask_app, sample_lff): + """Post-traiter 20 lignes doit donner le même résultat que post-traiter + l'ensemble puis slicer.""" + from src.utils import table + + full = sample_lff.collect() + with flask_app.app_context(): + via_full = table.table_postprocess(full.lazy()).slice(0, 1) + via_page = table.postprocess_page(full.slice(0, 1)) + # Mêmes colonnes, mêmes valeurs + assert via_full.columns == via_page.columns + for col in via_full.columns: + assert via_full[col].to_list() == via_page[col].to_list() +``` + +- [ ] **Step 2 : Vérifier l'échec** + +Run : `rtk uv run pytest tests/test_table.py::test_postprocess_page_produces_same_result_as_full_then_slice -v` +Expected : FAIL `module 'src.utils.table' has no attribute 'postprocess_page'`. + +- [ ] **Step 3 : Implémenter `postprocess_page`** + +Dans `src/utils/table.py`, juste sous `table_postprocess` (ligne ~401), ajouter : + +```python +def postprocess_page(dff: pl.DataFrame) -> pl.DataFrame: + """Post-traitement à appliquer sur une page déjà paginée. + + Équivalent à `table_postprocess` mais prend une DataFrame (pas un LazyFrame) + et ne matérialise rien de plus. À appeler après que la pagination ait été + poussée en SQL. + """ + dff = dff.with_columns(pl.all().cast(pl.String).fill_null("")) + dff = add_links(dff) + if "sourceFile" in dff.columns: + dff = add_resource_link(dff) + if dff.height > 0: + dff = format_values(dff) + return dff +``` + +- [ ] **Step 4 : Lancer les tests** + +Run : `rtk uv run pytest tests/test_table.py -v` +Expected : tous les tests PASS (existants + nouveau). + +- [ ] **Step 5 : Commit** + +```bash +rtk git add src/utils/table.py tests/test_table.py +rtk pre-commit +rtk git add src/utils/table.py tests/test_table.py +rtk git commit -m "feat(table): ajouter postprocess_page pour post-traiter une page seule" +``` + +--- + +## Task 4 : Nouveau chemin rapide SQL dans `_load_filter_sort_postprocess` + +C'est le cœur du plan. On remplace le chemin `data is None` de `prepare_table_data` pour faire filtre/tri/pagination en SQL DuckDB et post-traiter uniquement la page. + +**Files:** + +- Modify: `src/utils/table.py` +- Modify: `tests/test_table.py` + +**Contrat du nouveau helper** : au lieu de retourner la DataFrame complète post-traitée, retourner un tuple `(page_dff, total_count)`. Le cache s'applique sur la page et sur le count séparément. + +- [ ] **Step 1 : Écrire le test en échec** + +Ajouter à `tests/test_table.py` (en utilisant une vraie DB de test via la fixture existante de conftest si elle existe ; sinon voir `tests/test_db.py` pour le pattern) : + +```python +def test_fetch_page_sql_respects_pagination(flask_app): + """Nouveau chemin : retourne (page_dff, total_count) via DuckDB.""" + from src.utils import table + + with flask_app.app_context(): + page, total = table._fetch_page_sql( + filter_query=None, sort_by_key=(), page_current=0, page_size=5 + ) + assert page.height <= 5 + assert total >= page.height + + +def test_fetch_page_sql_pagination_returns_distinct_pages(flask_app): + from src.utils import table + + with flask_app.app_context(): + p0, total = table._fetch_page_sql( + filter_query=None, sort_by_key=(), page_current=0, page_size=2 + ) + if total >= 4: + p1, _ = table._fetch_page_sql( + filter_query=None, sort_by_key=(), page_current=1, page_size=2 + ) + assert set(p0["uid"].to_list()).isdisjoint(set(p1["uid"].to_list())) + + +def test_fetch_page_sql_applies_filter(flask_app): + from src.utils import table + + with flask_app.app_context(): + page, total = table._fetch_page_sql( + filter_query="{uid} icontains __ne_matche_rien__", + sort_by_key=(), + page_current=0, + page_size=20, + ) + assert total == 0 + assert page.height == 0 + + +def test_fetch_page_sql_applies_sort(flask_app): + from src.utils import table + + with flask_app.app_context(): + page, _ = table._fetch_page_sql( + filter_query=None, + sort_by_key=(("uid", "asc"),), + page_current=0, + page_size=10, + ) + uids = page["uid"].to_list() + assert uids == sorted(uids) + + +def test_fetch_page_sql_post_processes_links(flask_app): + from src.utils import table + + with flask_app.app_context(): + page, _ = table._fetch_page_sql( + filter_query=None, sort_by_key=(), page_current=0, page_size=1 + ) + if page.height > 0: + assert " tuple[pl.DataFrame, int]: + """Chemin rapide : filtre/tri/pagine dans DuckDB, post-traite la page seule. + + Retourne (page_dataframe_post_traitée, total_count_avant_pagination). + """ + logger.debug( + f"Cache miss SQL — filter={filter_query!r} sort={sort_by_key!r} " + f"page={page_current} size={page_size}" + ) + + where_sql, params = filter_query_to_sql(filter_query or "", schema) + + sort_by_dash = [ + {"column_id": col, "direction": direction} for col, direction in sort_by_key + ] + order_by = sort_by_to_sql(sort_by_dash, schema) or None + + total = count_marches(where_sql, params) + + page = query_marches( + where_sql=where_sql, + params=params, + order_by=order_by, + limit=page_size, + offset=page_current * page_size, + ) + + page = postprocess_page(page) + return page, total +``` + +- [ ] **Step 4 : Brancher `prepare_table_data` sur le nouveau chemin** + +Dans `src/utils/table.py`, dans `prepare_table_data`, remplacer le bloc `if data is None` (lignes ~435-439) : + +```python + if data is None: + sort_by_key = normalize_sort_by(sort_by) + dff, total = _fetch_page_sql( + filter_query=filter_query, + sort_by_key=sort_by_key, + page_current=page_current, + page_size=page_size, + ) + height = total + # La pagination a déjà eu lieu en SQL : NE PAS re-slicer plus bas. + already_paginated = True + else: + already_paginated = False + if isinstance(data, list): + lff: pl.LazyFrame = pl.LazyFrame( + data, strict=False, infer_schema_length=5000 + ) + elif isinstance(data, pl.LazyFrame): + lff = data + else: + lff = query_marches().lazy() + + if filter_query: + lff = filter_table_data(lff, filter_query) + + if sort_by and len(sort_by) > 0: + lff = sort_table_data(lff, sort_by) + + dff: pl.DataFrame = table_postprocess(lff) + height = dff.height +``` + +Puis, plus bas dans la même fonction, remplacer le bloc qui slice : + +```python + if height > 0: + nb_rows = ( + f"{format_number(height)} lignes " + f"({format_number(dff.select('uid').unique().height if not already_paginated else total_unique(filter_query))} marchés)" + ) + else: + nb_rows = "0 lignes (0 marchés)" + + if not already_paginated: + start_row = page_current * page_size + dff = dff.slice(start_row, page_size) +``` + +**Note :** le compte `uid.unique()` pose un problème : sur la page paginée il n'a pas de sens. On doit aussi le récupérer via DuckDB. Voir Step 5. + +- [ ] **Step 5 : Ajouter `count_unique_marches` dans db.py** + +Ajouter à `src/db.py` : + +```python +def count_unique_marches(where_sql: str = "TRUE", params: tuple | list = ()) -> int: + """Retourne le nombre de uid distincts correspondant à where_sql. + + Utilisé pour afficher `(X marchés)` — un uid peut apparaître plusieurs fois + si un marché a plusieurs titulaires. + """ + sql = f"SELECT COUNT(DISTINCT uid) FROM decp WHERE {where_sql}" + result = get_cursor().execute(sql, list(params)).fetchone() + return int(result[0]) if result else 0 +``` + +Et modifier `_fetch_page_sql` pour renvoyer aussi le count unique : + +```python + total = count_marches(where_sql, params) + total_unique = count_unique_marches(where_sql, params) + ... + return page, total, total_unique +``` + +Et adapter `prepare_table_data` en conséquence : + +```python + dff, total, total_unique = _fetch_page_sql(...) + height = total + already_paginated = True +``` + +Puis le message `nb_rows` : + +```python + if already_paginated: + if height > 0: + nb_rows = ( + f"{format_number(height)} lignes " + f"({format_number(total_unique)} marchés)" + ) + else: + nb_rows = "0 lignes (0 marchés)" + else: + if height > 0: + nb_rows = ( + f"{format_number(height)} lignes " + f"({format_number(dff.select('uid').unique().height)} marchés)" + ) + else: + nb_rows = "0 lignes (0 marchés)" +``` + +- [ ] **Step 6 : Lancer TOUS les tests** + +Run : `rtk uv run pytest tests/test_table.py tests/test_table_sql.py tests/test_db.py -v` +Expected : tous les tests PASS, y compris le test existant `test_prepare_table_data_paginates_without_recomputing` (la cache-key ne contient plus `page_current`, donc la deuxième page fera un cache-miss — attention, ce test doit être mis à jour, voir Step 7). + +- [ ] **Step 7 : Mettre à jour `test_prepare_table_data_paginates_without_recomputing`** + +Le test existant suppose l'ancien design (cache stocke la DF entière, pagination gratuite après). Le nouveau design cache par page. Adapter : + +Remplacer dans `tests/test_table.py` la fonction existante (ligne ~207) par : + +```python +def test_prepare_table_data_same_page_uses_cache( + monkeypatch, flask_app +): + """Deux appels avec exactement les mêmes (filter, sort, page, size) + doivent frapper le cache au deuxième coup.""" + from src.utils import table + + call_count = {"n": 0} + + real_fetch = table._fetch_page_sql.uncached if hasattr(table._fetch_page_sql, "uncached") else None + + def counting_fetch(*args, **kwargs): + call_count["n"] += 1 + # renvoyer un tuple minimal valide + import polars as pl + return pl.DataFrame({"uid": [], "acheteur_id": [], "titulaire_id": [], + "titulaire_typeIdentifiant": []}), 0, 0 + + # Patch la fonction sous-jacente avant memoize : remplacer par un mock + monkeypatch.setattr(table, "_fetch_page_sql", counting_fetch) + + with flask_app.app_context(): + table.prepare_table_data( + data=None, data_timestamp=0, filter_query=None, + page_current=0, page_size=10, sort_by=[], source_table="tableau", + ) + table.prepare_table_data( + data=None, data_timestamp=0, filter_query=None, + page_current=0, page_size=10, sort_by=[], source_table="tableau", + ) + # Le deuxième appel peut passer par le cache OU re-fire le mock + # (flask-caching mémoïze la fonction décorée, pas le mock). On valide + # juste que la plomberie appelle la bonne fonction. + assert call_count["n"] >= 1 +``` + +**Note importante :** flask-caching ne cachera pas le mock (il cache la fonction décorée d'origine). Ce test vérifie surtout que la plomberie est correcte. Pour tester vraiment le cache, ajouter un test en intégration avec une vraie DB, voir Task 6. + +- [ ] **Step 8 : Supprimer l'ancien `_load_filter_sort_postprocess`** + +Maintenant que le chemin rapide marche, supprimer la fonction `_load_filter_sort_postprocess` (inutilisée). Vérifier avec `rtk grep -rn "_load_filter_sort_postprocess" src/ tests/` qu'il n'y a plus aucune référence (sauf éventuellement les tests à nettoyer). + +**Si** des tests existants y font référence (ex : `test_load_filter_sort_postprocess_*`), les supprimer — ils testent un chemin qui n'existe plus. + +- [ ] **Step 9 : Lancer tous les tests à nouveau** + +Run : `rtk uv run pytest -v` +Expected : PASS. + +- [ ] **Step 10 : Commit** + +```bash +rtk git add src/db.py src/utils/table.py tests/test_table.py +rtk pre-commit +rtk git add src/db.py src/utils/table.py tests/test_table.py +rtk git commit -m "perf(tableau): pousser filtre/tri/pagination/comptage dans DuckDB" +``` + +--- + +## Task 5 : Test d'intégration end-to-end + mesure de performance + +**Files:** + +- Modify: `tests/test_main.py` (vérifier que la page /tableau se charge toujours) + +- [ ] **Step 1 : Lancer l'appli en local** + +```bash +rtk uv run run.py +``` + +Ouvrir http://localhost:8050/tableau dans un navigateur. + +- [ ] **Step 2 : Vérifier à la main** + + - La page se charge (affiche 20 lignes) + - Les liens `` sont présents dans les colonnes uid, acheteur_nom, titulaire_nom + - Les montants sont formatés (`12 500 €`) + - Appliquer un filtre texte (ex : `{objet} icontains voirie`), vérifier que la page se met à jour + - Appliquer un filtre numérique (ex : `{montant} i> 40000`), idem + - Cliquer sur le tri d'une colonne, vérifier que ça fonctionne + - Changer de page (20 → 40 → 60), vérifier que ça marche + - Partager une URL avec filtres+tris+colonnes, ouvrir dans un autre onglet, vérifier que l'état est restauré + - Téléchargement Excel fonctionne encore (doit passer par le chemin `query_marches().lazy()` qui n'a pas été touché) + +- [ ] **Step 3 : Mesurer à froid** + +Redémarrer l'appli (kill + `rtk uv run run.py`). Ouvrir `/tableau` sans filtre. Noter le temps (onglet Network → finished). Recharger plusieurs fois, noter warm. + +- [ ] **Step 4 : Mesurer avec filtre** + +Appliquer un filtre fréquent (ex : `{acheteur_departement_code} icontains 35`). Noter cold (premier filtre) et warm (mêmes filtre appliqué après un `Reset`). + +- [ ] **Step 5 : Si les perfs ne sont pas au rendez-vous** + +Debugger : + +- `rtk uv run python -c "import duckdb, time; c = duckdb.connect('./decp.duckdb', read_only=True); t=time.time(); r=c.execute('SELECT * FROM decp ORDER BY dateNotification DESC LIMIT 20').pl(); print(time.time()-t, r.height)"` +- Si DuckDB lui-même est lent sur cette requête (> 1 s), envisager `CREATE INDEX` sur `dateNotification` (bien que les index B-tree aient un bénéfice limité sur DuckDB columnaire — vérifier avec EXPLAIN ANALYZE). +- Vérifier que `postprocess_page` s'exécute bien sur 20 lignes, pas plus. Ajouter un `logger.debug(f"postprocess {dff.height} rows")`. + +- [ ] **Step 6 : Documenter les résultats** + +Ajouter à la fin de ce fichier plan (ou dans un nouveau fichier `docs/superpowers/plans/2026-04-21-tableau-performance-duckdb-results.md`) : + +``` +## Résultats mesurés + +| Scénario | Avant | Après | +|---|---|---| +| Cold, sans filtre | 11 s | X s | +| Warm, sans filtre | 5 s | X s | +| Cold, avec filtre texte | ? | X s | +| Warm, avec filtre texte | ? | X s | +| Changement de page | ? | X s | +| Tri sur colonne | ? | X s | +``` + +- [ ] **Step 7 : Commit du plan avec résultats** + +```bash +rtk git add docs/superpowers/plans/ +rtk pre-commit +rtk git add docs/superpowers/plans/ +rtk git commit -m "docs: résultats perf tableau après optimisation DuckDB" +``` + +--- + +## Task 6 : Non-régression sur les autres pages qui utilisent `prepare_table_data` + +**Files:** + +- Smoke test manuel sur `/acheteurs/`, `/titulaires/`, `/observatoire` + +- [ ] **Step 1 : Lancer l'appli et naviguer sur chaque page** + +Lancer : `rtk uv run run.py` + +Puis : + +1. `/recherche` → rechercher un acheteur → cliquer sur un résultat → la page `/acheteurs/` doit afficher le tableau des marchés de l'acheteur avec les mêmes liens `` et formats (les tests passent déjà, c'est juste un smoke test UI). +2. Idem sur `/titulaires/`. +3. Aller sur `/observatoire`, vérifier que la datatable en bas de page affiche les marchés et que les liens/formats fonctionnent. + +- [ ] **Step 2 : Lancer la suite Selenium** + +Run : `rtk uv run pytest tests/test_main.py -v` +Expected : PASS (ou si échec, comprendre s'il est lié à la modif ou à un flake Selenium). + +- [ ] **Step 3 : Si tout est vert, commit de validation** + +(Aucun code à commiter normalement ; c'est juste un check final.) + +--- + +## Self-Review + +Cette section est ma relecture du plan avant remise à l'utilisateur. + +**Couverture du spec :** + +- ✅ Pousser WHERE/ORDER BY/LIMIT/OFFSET dans DuckDB → Tasks 1-4 +- ✅ Ne post-traiter que la page courante → Task 3 +- ✅ `COUNT(*)` en SQL au lieu de `.height` sur DF matérialisée → Task 2 +- ✅ Préserver les autres pages → Task 6 +- ⚠️ Index DuckDB : explicitement hors scope, à décider après mesure (Task 5 Step 5). +- ⚠️ Projection des colonnes cachées : hors scope (mentionné dans le périmètre). +- ⚠️ Cache client-side : rejeté dans la discussion initiale, pas dans le plan. + +**Chasse aux placeholders :** pas de "TBD", pas de "implement later". Tous les steps ont du code concret. + +**Cohérence des types :** + +- `filter_query_to_sql(filter_query, schema) → (str, list)` — utilisé Task 4 Step 3 de la même façon. ✓ +- `sort_by_to_sql(sort_by, schema) → str` — idem. ✓ +- `_fetch_page_sql(filter_query, sort_by_key, page_current, page_size) → (pl.DataFrame, int, int)` après Step 5. Attention : j'ai d'abord écrit `(DataFrame, int)` à deux endroits (Task 4 Step 3 & 4) puis élargi à `(DataFrame, int, int)` au Step 5. **Fix inline :** Step 3 et Step 4 doivent dès le départ renvoyer le triplet pour éviter une double-édition. J'ajoute la note ci-dessous. + +**Fix inline (ne pas éditer à l'implémentation, juste suivre la note) :** dans Task 4 Step 3, `_fetch_page_sql` doit retourner `(page, total, total_unique)` et appeler `count_marches` + `count_unique_marches`. Le tuple-à-deux-éléments dans le test Step 1 doit aussi être un triplet : + +```python +page, total, total_unique = table._fetch_page_sql(...) +``` + +De même, `count_unique_marches` doit être ajouté dans Task 2 (pas dans Task 4 Step 5), avec son propre test. **Mise à jour du plan :** ajouter à Task 2 Step 3 : + +```python +def count_unique_marches(where_sql: str = "TRUE", params: tuple | list = ()) -> int: + sql = f"SELECT COUNT(DISTINCT uid) FROM decp WHERE {where_sql}" + result = get_cursor().execute(sql, list(params)).fetchone() + return int(result[0]) if result else 0 +``` + +et son test dans Task 2 Step 1 : + +```python +def test_count_unique_marches_respects_distinct(): + from src.db import count_unique_marches + n = count_unique_marches() + assert isinstance(n, int) + assert n > 0 +``` + +Avec ça, Task 4 Step 5 devient trivial (le helper existe déjà). + +**Décisions en suspens à confirmer avec l'utilisateur avant exécution :** + +1. **Branche** : rester sur `feature/73_compte_utilisateur` (couplée à `#73 compte utilisateur`, aucun rapport) semble incorrect. Créer `feature/NN_tableau_performance` après stash/commit des fichiers en cours. +2. **Numéro d'issue** : à créer côté GitHub si pertinent pour la release note. +3. **Suppression ou conservation de `_load_filter_sort_postprocess`** : le plan le supprime à Task 4 Step 8. Alternative : le garder en tant que legacy pendant une version pour comparaison de perf en prod. Par défaut : supprimer (YAGNI).