GET /v1/zones/{zone_id}/score-breakdown #87

📋 Description

⚠️ Suggestion à valider par le PO avant planification — non confirmée, ticket créé pour garder l'idée.

Permet à l'utilisateur de comprendre pourquoi une zone a tel score, en affichant les valeurs brutes qui ont contribué à chaque sous-indice sur la fiche zone. Répond à l'exigence d'explicabilité du scoring (score "traçable, testable, explicable").

GET /v1/zones/881f1d4a3fffffff/score-breakdown?bucket_id=2026-08

{
  "zone_id": "881f1d4a3fffffff",
  "bucket_id": "2026-08",
  "breakdown": {
    "human_pressure": { "building_area_ratio": 0.34, "road_density_major": 1.2, "urban_landuse_ratio": 0.41 },
    "vegetation": { "ndvi": 0.61, "ndwi": 0.12, "ndbi": 0.08 },
    "biodiversity": { "species_total_count": 47, "vulnerability_weighted_score": 0.29 },
    "protection": { "protected_area_type": null, "coverage_ratio": 0.0 }
  }
}

✅ Acceptance Criteria

• score_human_pressure détaillé via osm_features_by_zone (building_area_ratio, road_density_major, road_density_all, urban_landuse_ratio)
• score_vegetation détaillé via satellite_features_by_zone (ndvi, ndwi, ndbi)
• score_biodiversity détaillé via species_features_by_zone (species_total_count, comptes par catégorie IUCN, vulnerability_weighted_score)
• score_protection détaillé via protected_areas_by_zone (protected_area_type, coverage_ratio)
• Toujours en lecture seule, même bucket_id/période que le score consulté

🔗 Prerequisite Issues

• Scaffold apps/api (FastAPI) #79 (Scaffold apps/api)
• GET /v1/zones/{zone_id} #81 (GET /v1/zones/{zone_id})
• Lit directement les tables sources (pas stress_score_by_zone) : Job extract_sentinel_2 #36 (extract_sentinel_2), Jobs sur les zones protégées #37 (zones protégées), Compute OSM features + Cleanup #38 (OSM features), compute_species_features_by_zone #39 (species features by zone) doivent être terminées
• Confirmation PO que la feature entre dans le scope v3

Source : Notion « GET /v1/zones/{zone_id}/score-breakdown » (API).