Merge pull request #44 from T-DAT-902-Homepedia/feat/iris-quartier-layer

feat(webapp): IRIS neighborhood choropleth layer on price and score maps

Author: glopez-dev

docs/data-cdn.md

@@ -21,13 +21,16 @@ BASE = https://storage.googleapis.com/homepedia-web/v1
   "nb_communes": 34933,
   "nb_communes_scorees": 17774,
   "nb_communes_avis": 78,
+  "nb_iris": 16400,
+  "nb_iris_scores": 14500,
   "generated_at": "2026-07-07T20:08:24+00:00"
 }
 ```
 
 `nb_communes_avis` (0 ou absent = run sans analyse d'avis) sert de feature-gate à
-la section « avis » ; `schema_version` reste à 1 tant que les évolutions sont
-additives (le schéma zod tolère un futur bump).
+la section « avis » ; `nb_iris` (0 ou absent = run sans maille quartier) sert de
+feature-gate à la couche IRIS des cartes ; `schema_version` reste à 1 tant que
+les évolutions sont additives (le schéma zod tolère un futur bump).
 
 - Tout le reste est sous `{BASE}/{meta.base}/…`, **immuable** (cache-control 1 an,
   `immutable`) :
@@ -37,6 +40,10 @@ additives (le schéma zod tolère un futur bump).
   - `choropleth/departements-low.geojson` (~120 Ko gz), `choropleth/departements-mid.geojson` (~800 Ko gz)
   - `choropleth/communes-mid.geojson` (~3,4 Mo gz, 34 928 features, national)
   - `choropleth/communes-high/{dept}.geojson` ×101 (`{dept}` ∈ 01…95, 2A, 2B, 971…976)
+  - `choropleth/iris-high/{dept}.geojson` ×~104 (~80 Ko gz, max ~400 Ko) — maille
+    quartier (IRIS INSEE, ADR-0015 pipeline), **communes multi-IRIS uniquement**
+    (1 944 villes) : la couche se superpose à la maille commune, **404 = normal**
+    (département sans ville multi-IRIS)
   - `communes/{dept}.json` ×101 (fiches commune, groupées par département —
     incluent le bloc `avis` résumé quand la commune est couverte)
   - `avis/{dept}.json` (départements couverts uniquement, **404 = normal**) :
@@ -70,6 +77,18 @@ dimensions normalisées `n_*` (toutes nullables). Le `v1/score.geojson` racine e
 **déprécié** : `src/lib/score.ts` adapte désormais la choroplèthe communale
 versionnée à son ancien format.
 
+**Properties GeoJSON quartiers (IRIS)** : identité `code_iris`, `nom` (nom du
+quartier), `code_commune`, `nom_commune`, `type_iris`, `code_departement` ;
+données `prix_m2_median` (entier), `nb_transactions`, `fiable`,
+`annee_min`/`annee_max` ; score `score_commune`, `n_prix_iris`, `gap_iris`,
+`gap_pondere_iris` (3 décimales). Les noms diffèrent de la maille commune :
+`score_valeur` → `score_commune` (hérité de la ville), `gap` → `gap_iris`,
+`gap_pondere` → `gap_pondere_iris` (mapping dans `src/lib/iris.ts`). Le prix
+est une **médiane poolée** sur `annee_min`–`annee_max` : ne pas le comparer
+chiffre à chiffre au prix communal (millésime courant). `gap_iris > 0` =
+quartier sous-coté par rapport à la qualité de vie de sa ville ;
+`fiable = false` → valeurs à null (« pas de donnée », comme les communes).
+
 ## Sémantique métier
 
 - `score_valeur` ∈ [0,1] : qualité de vie composite. Poids : **emploi 30 %, proximité
@@ -85,7 +104,9 @@ versionnée à son ancien format.
 
 1. **Paris (75056), Lyon (69123), Marseille (13055) n'ont pas d'agrégat prix/évolution
    au niveau commune** : les transactions DVF sont codées par arrondissement (751xx,
-   6938x, 132xx), qui sont eux des features/fiches normales.
+   6938x, 132xx), qui sont eux des features/fiches normales. Les quartiers IRIS
+   portent aussi les codes arrondissements : la couche quartier affiche des
+   données sur Paris là où la choroplèthe communale montre « pas de donnée ».
 2. **5 fiches sans géométrie** (communes fusionnées entre millésimes) : atteignables par
    recherche/fiche mais pas par la carte.
 3. **Dérivation du département depuis un code commune** : 3 premiers caractères si

src/components/iris-tooltip.tsx

@@ -0,0 +1,54 @@
+import type { ReactNode } from "react"
+
+import type { IrisProperties } from "@/lib/iris"
+import { formatEuroM2, formatInt, formatScore, formatSigned } from "@/lib/format"
+
+/**
+ * Corps du tooltip quartier (IRIS), partagé par les deux cartes. Le prix est
+ * une médiane poolée sur plusieurs millésimes : on affiche sa période plutôt
+ * que de l'opposer chiffre à chiffre au prix communal (millésime courant).
+ * Le score est hérité de la commune — mention explicite. `children` s'insère
+ * après le titre (ex. : la métrique courante de la carte score).
+ */
+export function IrisTooltipContent({
+  p,
+  clickHint,
+  children,
+}: {
+  p: IrisProperties
+  clickHint?: string
+  children?: ReactNode
+}) {
+  const periode =
+    p.annee_min != null && p.annee_max != null
+      ? ` ${p.annee_min}–${p.annee_max}`
+      : ""
+  return (
+    <>
+      <div className="font-display font-semibold">{p.nom}</div>
+      <div className="text-xs text-muted-foreground">
+        Quartier de {p.nom_commune}
+      </div>
+      {children}
+      <div className="mt-1">
+        Prix médian{periode} :{" "}
+        <span className="font-semibold text-accent">
+          {formatEuroM2(p.prix_m2_median)}
+        </span>
+      </div>
+      <div className="text-muted-foreground">
+        {formatInt(p.nb_transactions)} transactions
+        {p.fiable ? "" : " (faible volume)"}
+      </div>
+      <div className="text-muted-foreground">
+        Écart qualité/prix : {formatSigned(p.gap_pondere_iris)}
+      </div>
+      <div className="text-muted-foreground">
+        Score : {formatScore(p.score_commune)} — score de la commune
+      </div>
+      {clickHint && (
+        <div className="mt-1 text-xs text-muted-foreground">{clickHint}</div>
+      )}
+    </>
+  )
+}

src/components/score-sidebar.tsx

@@ -62,6 +62,8 @@ type ScoreSidebarProps = {
   isError: boolean
   wordCloudEnabled: boolean
   onWordCloudEnabled: (v: boolean) => void
+  /** Couche quartier (IRIS) actuellement visible sur la carte. */
+  irisActive?: boolean
 }
 
 /** Bulle d'aide « i » réutilisée sur chaque métrique et titre de section. */
@@ -138,6 +140,7 @@ function SidebarContent({
   isError,
   wordCloudEnabled,
   onWordCloudEnabled,
+  irisActive,
 }: ScoreSidebarProps) {
   return (
     <>
@@ -248,6 +251,13 @@ function SidebarContent({
             )}
           </div>
 
+          {irisActive && (
+            <p className="mt-2 text-[10px] text-muted-foreground">
+              Maille quartier (IRIS) sur les grandes villes — score hérité de
+              la commune, prix et écart propres au quartier.
+            </p>
+          )}
+
           {isLoading && (
             <div className="mt-2 text-xs text-muted-foreground">Chargement…</div>
           )}

src/hooks/useCommunesHigh.ts

@@ -14,10 +14,11 @@ export const MAX_HIGH_DEPTS = 15
 /**
  * Codes des départements dont l'emprise intersecte le viewport, triés
  * (identité stable pour les queryKeys). Source : la choroplèthe
- * départementale low, déjà en cache après la vue initiale.
+ * départementale low, déjà en cache après la vue initiale. `enabled` évite
+ * son fetch tant qu'aucun consommateur n'en a besoin (carte score).
  */
-export function useVisibleDepartements(viewBounds: Bbox | null): string[] {
-  const { data: depts } = useChoropleth("departements", "low")
+export function useVisibleDepartements(viewBounds: Bbox | null, enabled = true): string[] {
+  const { data: depts } = useChoropleth("departements", "low", enabled)
   const bboxes = useMemo(
     () => (depts ? deptBboxes(depts.features) : new Map<string, Bbox>()),
     [depts],

src/hooks/useIrisHigh.ts

@@ -0,0 +1,50 @@
+import { useQueries } from "@tanstack/react-query"
+
+import { fetchIrisDept, type IrisFeature } from "@/lib/iris"
+import { MAX_HIGH_DEPTS } from "@/hooks/useCommunesHigh"
+import { useMeta } from "@/hooks/useMeta"
+
+/** Seuil de zoom « quartier » : au-dessus du high commune (10), là où les
+ *  IRIS deviennent lisibles. */
+export const IRIS_ZOOM_THRESHOLD = 11
+
+/** Feature-gate : run publiant la maille quartier (clés meta additives). */
+export function useHasIris(): boolean {
+  const { data: meta } = useMeta()
+  return (meta?.nb_iris ?? 0) > 0
+}
+
+/**
+ * IRIS des départements demandés, fusionnés. Même mécanique que
+ * useCommunesHigh : un fetch par département, caché indéfiniment. Le
+ * feature-gate nb_iris est interne : sur un ancien run, zéro requête.
+ */
+export function useIrisHigh(depts: string[], enabled: boolean) {
+  const { data: meta } = useMeta()
+  const hasIris = useHasIris()
+  const capped =
+    enabled && hasIris && depts.length <= MAX_HIGH_DEPTS ? depts : []
+  return useQueries({
+    queries: capped.map((dept) => ({
+      queryKey: ["choropleth", meta?.base, "iris-high", dept],
+      queryFn: () => fetchIrisDept(meta!.base, dept),
+      enabled: !!meta,
+      staleTime: Infinity,
+    })),
+    combine: (results) => {
+      const features: IrisFeature[] = []
+      const loadedDepts = new Set<string>()
+      results.forEach((r, i) => {
+        if (r.data) {
+          features.push(...r.data.features)
+          loadedDepts.add(capped[i])
+        }
+      })
+      return {
+        features,
+        loadedDepts,
+        isFetching: results.some((r) => r.isFetching),
+      }
+    },
+  })
+}

src/lib/colorScale.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from "vitest"
+
+import { makeColorScale } from "@/lib/colorScale"
+import { NO_DATA } from "@/lib/palettes"
+import type { ChoroplethFeature, ChoroplethProperties } from "@/lib/choropleth"
+
+// Fixture minimale : makeColorScale ne lit que properties via les accessors.
+const feature = (prix: number | null, fiable = true) =>
+  ({
+    type: "Feature",
+    geometry: null,
+    properties: { prix_m2_median: prix, fiable },
+  }) as unknown as ChoroplethFeature
+
+const getValue = (p: ChoroplethProperties) => p.prix_m2_median
+const getFiable = (p: ChoroplethProperties) => p.fiable
+
+describe("makeColorScale().color (value-based, couche IRIS)", () => {
+  const features = [1000, 2000, 3000, 4000, 5000, 6000, null].map((v) =>
+    feature(v),
+  )
+  const scale = makeColorScale(features, getValue, getFiable)
+
+  it("rend NO_DATA pour null", () => {
+    expect(scale.color(null)).toEqual(NO_DATA)
+    expect(scale.color(undefined)).toEqual(NO_DATA)
+  })
+
+  it("atténue l'alpha à 110 quand fiable=false", () => {
+    const plein = scale.color(3000)
+    const attenue = scale.color(3000, false)
+    expect(attenue.slice(0, 3)).toEqual(plein.slice(0, 3))
+    expect(attenue[3]).toBe(110)
+  })
+
+  it("reste cohérente avec getColor (mêmes seuils commune/quartier)", () => {
+    for (const f of [feature(1500), feature(5500), feature(null), feature(2500, false)]) {
+      expect(scale.color(getValue(f.properties), getFiable(f.properties))).toEqual(
+        scale.getColor(f),
+      )
+    }
+  })
+})

src/lib/colorScale.ts

@@ -44,6 +44,9 @@ export function quantileScale(
 
 export interface FeatureColorScale {
   getColor(f: ChoroplethFeature): RGBA
+  /** Couleur d'une valeur brute — mêmes seuils que getColor (couche IRIS :
+   *  un quartier se lit sur l'échelle calculée sur les communes). */
+  color(v: number | null | undefined, fiable?: boolean): RGBA
   /** Bornes de classes (pour la légende), croissantes. */
   thresholds: number[]
   palette: RGBA[]
@@ -62,14 +65,16 @@ export function makeColorScale(
   const values = features.map((f) => getValue(f.properties))
   const thresholds = quantileThresholds(values, PRICE_SEQ.length)
   const base = quantileScale(values, PRICE_SEQ)
+  const color = (v: number | null | undefined, fiable = true): RGBA => {
+    if (v == null) return NO_DATA
+    const rgba = base(v)
+    return fiable ? rgba : [rgba[0], rgba[1], rgba[2], 110]
+  }
   return {
     thresholds,
     palette: PRICE_SEQ,
-    getColor(feature: ChoroplethFeature): RGBA {
-      const v = getValue(feature.properties)
-      if (v == null) return NO_DATA
-      const rgba = base(v)
-      return getFiable(feature.properties) ? rgba : [rgba[0], rgba[1], rgba[2], 110]
-    },
+    color,
+    getColor: (feature: ChoroplethFeature): RGBA =>
+      color(getValue(feature.properties), getFiable(feature.properties)),
   }
 }

src/lib/data.ts

@@ -20,6 +20,10 @@ export const metaSchema = z.object({
   // Communes couvertes par l'analyse d'avis (0 ou absent = pas d'avis dans ce
   // run : les sections Avis se masquent d'elles-mêmes).
   nb_communes_avis: z.number().optional(),
+  // Maille quartier IRIS (0 ou absent = run sans quartiers : la couche carte
+  // reste masquée).
+  nb_iris: z.number().optional(),
+  nb_iris_scores: z.number().optional(),
   generated_at: z.string(),
 })
 export type Meta = z.infer<typeof metaSchema>