carbonfr_sdk/dto.rs
1//! DTO de réponse (et un DTO de requête, [`CreateWebhookRequest`]) du contrat
2//! `/v1`, dupliqués depuis les schémas `components.schemas` de
3//! `crates/adapter-http/tests/openapi.snapshot.json` (ADR-0031 décision 5) —
4//! aucune dépendance à `carbonfr-core`/`carbonfr-adapter-http`.
5//!
6//! **Champs publics, aucun `#[non_exhaustive]`** (ADR-0030 §3 : « Les structs
7//! à champs publics n'en reçoivent jamais [`#[non_exhaustive]`] […], y
8//! compris pour le futur SDK Rust » — cette clause visait explicitement ces
9//! types) : ce sont des types de données, pas des invariants à protéger par
10//! construction, et doivent rester constructibles par littéral côté
11//! appelant (tests, code applicatif). Conséquence assumée : ajouter un champ
12//! public à l'une d'elles sera un bump *minor*, jamais un
13//! `#[non_exhaustive]` posé après coup (casserait justement la construction
14//! par littéral que cette doctrine protège).
15//!
16//! **Horodatages** : `time::OffsetDateTime` (RFC 3339, `time::serde::rfc3339`
17//! / `rfc3339::option`) pour tout champ réellement RFC 3339 (`timestamp`,
18//! `from`/`to`, `start`/`end`, `valid_at`/`run_at`, `at`, `disabled_at`).
19//! **Restent `String`, délibérément** (pas des instants RFC 3339) :
20//! `vintage` (`HistoryPoint`/`IntensityResponse` : étiquette de révision, ex.
21//! `définitif` — distinct de `CostReferenceEntry::vintage`, un millésime
22//! entier), `PriceResponse::vintage` (millésime réglementaire, ex. `2026-H2`,
23//! pas une date), `RulesetInfo::hourly_switchover` (date **sans** heure, ex.
24//! `2030-01-01`, confirmé par `tests/fixtures/eligibility_rulesets.json` —
25//! `time::serde::rfc3339` échouerait dessus) et `VisitStatsResponse::since`
26//! (`ISO YYYY-MM-DD`, même raison).
27//!
28//! **Champs `String` plutôt qu'un enum dupliqué** pour tout catalogue
29//! **non** listé par `enums_to_duplicate` dans `sdk-spec.json` (`filiere`,
30//! `technology`/`source`/`perimeter`/`basis` du LCOE, `pillar`/`basis` d'un
31//! signal d'éligibilité…) : ADR-0030 §3 classe ces catalogues internes à
32//! `core` comme `#[non_exhaustive]` (voués à grandir), mais la mission I6 ne
33//! les a pas mis dans le périmètre des enums à dupliquer — les garder en
34//! `String` évite d'inventer côté SDK une liste fermée que le serveur ne
35//! promet pas.
36//!
37//! **Entiers** : `format: int32` → `u32`, `format: int64` → `u64` (compteurs
38//! sur un historique long : `StatsBucket`/`StatsResponse::count`,
39//! `VisitStatsResponse::total`/`unique`), pas de `format` déclaré → `u32`
40//! (bornés en pratique : nombre d'entrées d'un catalogue, de créneaux…).
41//! `MethodologyInfo::id` reste délibérément `String` (pas [`Methodology`]) :
42//! c'est un catalogue de **découverte**, qui peut lister une méthode
43//! `planned` non encore sélectionnable — le typer figerait la désérialisation
44//! le jour où une 3ᵉ méthode y apparaît avant que `Methodology` ne la
45//! connaisse.
46
47use serde::{Deserialize, Serialize};
48use time::OffsetDateTime;
49
50use crate::enums::{
51 EligibilityFramework, EligibilitySignalProvenance, EligibilitySignalVerdict, Estimator,
52 FlowDirection, IntensityIndex, Interval, Methodology, ThresholdDirection, WebhookStatus,
53};
54use crate::region::Region;
55
56// --- Intensité (`/v1/intensity/*`) -----------------------------------------
57
58/// Valeur d'intensité carbone (`IntensityResponse::intensity`).
59#[derive(Debug, Clone, PartialEq, Deserialize)]
60pub struct IntensityValue {
61 pub value: f64,
62 pub unit: String,
63}
64
65/// Réponse de `GET /v1/intensity/now`.
66#[derive(Debug, Clone, Deserialize, PartialEq)]
67pub struct IntensityResponse {
68 pub region: Region,
69 #[serde(with = "time::serde::rfc3339")]
70 pub timestamp: OffsetDateTime,
71 pub intensity: IntensityValue,
72 /// Index qualitatif de `intensity` (ADR-0033), `None` face à un serveur
73 /// ≤ 0.10.
74 #[serde(default)]
75 pub index: Option<IntensityIndex>,
76 pub methodology: Methodology,
77 pub methodology_version: u32,
78 /// Étiquette de révision de la mesure (ADR-0006) — pas un horodatage,
79 /// voir le commentaire de module.
80 pub vintage: String,
81}
82
83/// Réponse de `GET /v1/intensity/now/all` — dernière mesure de **chaque**
84/// région disposant d'une donnée, national puis les 12 régions dans l'ordre de
85/// `GET /v1/regions` (une région sans donnée est omise ; liste vide possible).
86#[derive(Debug, Clone, Deserialize, PartialEq)]
87pub struct IntensityAllResponse {
88 /// Méthodologie servie — identique au champ `methodology` de chaque entrée
89 /// (`rte-direct` n'existe qu'au national : une seule entrée).
90 pub methodology: Methodology,
91 pub methodology_version: u32,
92 /// Nombre d'entrées de `regions` (1 à 13).
93 pub count: u32,
94 pub regions: Vec<IntensityResponse>,
95}
96
97/// Un point de `GET /v1/intensity/date` (`HistoryResponse::data`).
98#[derive(Debug, Clone, Deserialize, PartialEq)]
99pub struct HistoryPoint {
100 #[serde(with = "time::serde::rfc3339")]
101 pub timestamp: OffsetDateTime,
102 pub intensity: f64,
103 /// Index qualitatif de `intensity` (ADR-0033), `None` face à un serveur
104 /// ≤ 0.10.
105 #[serde(default)]
106 pub index: Option<IntensityIndex>,
107 pub vintage: String,
108}
109
110/// Réponse de `GET /v1/intensity/date`.
111#[derive(Debug, Clone, Deserialize, PartialEq)]
112pub struct HistoryResponse {
113 pub region: Region,
114 #[serde(with = "time::serde::rfc3339")]
115 pub from: OffsetDateTime,
116 #[serde(with = "time::serde::rfc3339")]
117 pub to: OffsetDateTime,
118 pub unit: String,
119 pub methodology: Methodology,
120 pub count: u32,
121 pub data: Vec<HistoryPoint>,
122}
123
124/// Un seau agrégé de `GET /v1/intensity/stats?interval=` (`StatsResponse::intervals`).
125#[derive(Debug, Clone, Deserialize, PartialEq)]
126pub struct StatsBucket {
127 #[serde(with = "time::serde::rfc3339")]
128 pub start: OffsetDateTime,
129 pub average: f64,
130 pub min: f64,
131 pub max: f64,
132 pub count: u64,
133}
134
135/// Réponse de `GET /v1/intensity/stats`.
136#[derive(Debug, Clone, Deserialize, PartialEq)]
137pub struct StatsResponse {
138 pub region: Region,
139 #[serde(with = "time::serde::rfc3339")]
140 pub from: OffsetDateTime,
141 #[serde(with = "time::serde::rfc3339")]
142 pub to: OffsetDateTime,
143 pub unit: String,
144 pub methodology: Methodology,
145 pub average: f64,
146 pub min: f64,
147 pub max: f64,
148 pub count: u64,
149 /// Pas d'agrégation demandé (`?interval=`), `None` si absent de la requête.
150 pub interval: Option<Interval>,
151 /// Série agrégée par seau, `None` si `interval` n'a pas été demandé.
152 pub intervals: Option<Vec<StatsBucket>>,
153}
154
155/// Un créneau (`GET /v1/schedule/slots`, `GET /v1/intensity/below`).
156#[derive(Debug, Clone, Deserialize, PartialEq)]
157pub struct SlotBody {
158 #[serde(with = "time::serde::rfc3339")]
159 pub timestamp: OffsetDateTime,
160 pub intensity: f64,
161}
162
163/// Réponse d'une liste de créneaux (`GET /v1/schedule/slots`,
164/// `GET /v1/intensity/below`).
165#[derive(Debug, Clone, Deserialize, PartialEq)]
166pub struct SlotsResponse {
167 pub region: Region,
168 pub methodology: Methodology,
169 /// Identité versionnée du modèle de prévision (ex. `climatology@1`).
170 pub model: String,
171 pub estimator: Estimator,
172 pub unit: String,
173 pub count: u32,
174 pub slots: Vec<SlotBody>,
175}
176
177// --- Prévision (`/v1/intensity/forecast`, `/v1/intensity/greenest-window`) -
178
179/// Un point de `GET /v1/intensity/forecast` (`ForecastResponse::data`).
180#[derive(Debug, Clone, Deserialize, PartialEq)]
181pub struct ForecastPointBody {
182 #[serde(with = "time::serde::rfc3339")]
183 pub timestamp: OffsetDateTime,
184 pub expected: f64,
185 pub lower: f64,
186 pub upper: f64,
187 /// Index qualitatif de `expected` (ADR-0033), `None` face à un serveur
188 /// ≤ 0.10.
189 #[serde(default)]
190 pub index: Option<IntensityIndex>,
191}
192
193/// Réponse de `GET /v1/intensity/forecast`.
194#[derive(Debug, Clone, Deserialize, PartialEq)]
195pub struct ForecastResponse {
196 pub region: Region,
197 pub methodology: Methodology,
198 /// Identité versionnée du modèle de prévision (ex. `climatology@1`).
199 pub model: String,
200 #[serde(with = "time::serde::rfc3339")]
201 pub from: OffsetDateTime,
202 pub horizon_hours: u32,
203 pub unit: String,
204 pub count: u32,
205 pub data: Vec<ForecastPointBody>,
206}
207
208/// Un signal d'un créneau (`EligibilitySlotBody::signals`, ADR-0025/0026).
209#[derive(Debug, Clone, Deserialize, PartialEq)]
210pub struct EligibilitySignalBody {
211 /// Pilier évalué (`renewable-share`, `surplus-price`,
212 /// `low-carbon-intensity`) — `String`, pas dans le périmètre des enums
213 /// dupliqués (voir le commentaire de module).
214 pub pillar: String,
215 pub verdict: EligibilitySignalVerdict,
216 /// `regulatory`, `indicative-non-regulatory` ou `user-override` — `String`,
217 /// même raison que `pillar`.
218 pub basis: String,
219 pub provenance: Option<EligibilitySignalProvenance>,
220 /// Pourquoi le pilier est `indeterminate` (`missing-data`,
221 /// `beyond-calibrated-horizon`…), absent sinon.
222 pub reason: Option<String>,
223 pub threshold: Option<f64>,
224 pub value: Option<f64>,
225 pub value_lower: Option<f64>,
226 pub value_upper: Option<f64>,
227}
228
229/// Verdict d'éligibilité d'un créneau (`EligibilityBody::slots`).
230#[derive(Debug, Clone, Deserialize, PartialEq)]
231pub struct EligibilitySlotBody {
232 #[serde(with = "time::serde::rfc3339")]
233 pub timestamp: OffsetDateTime,
234 pub eligible: bool,
235 pub intensity: f64,
236 pub intensity_lower: f64,
237 pub intensity_upper: f64,
238 /// Score de classement **interne au cadre** — jamais comparable entre
239 /// `framework`s (utiliser `intensity` pour ça).
240 pub score: f64,
241 pub signals: Vec<EligibilitySignalBody>,
242}
243
244/// Meilleur créneau éligible (`EligibilityBody::best_eligible`).
245#[derive(Debug, Clone, Deserialize, PartialEq)]
246pub struct EligibleSlotBody {
247 #[serde(with = "time::serde::rfc3339")]
248 pub timestamp: OffsetDateTime,
249 pub intensity: f64,
250 pub intensity_lower: f64,
251 pub intensity_upper: f64,
252 pub score: f64,
253}
254
255/// Overlay d'éligibilité électrolyseur (`GreenestWindowResponse::eligibility`,
256/// présent seulement si `?eligibility=` a été fourni).
257#[derive(Debug, Clone, Deserialize, PartialEq)]
258pub struct EligibilityBody {
259 pub framework: EligibilityFramework,
260 pub ruleset_version: String,
261 pub ruleset_status: String,
262 /// `true` si des overrides utilisateur (`surplus_price_eur_mwh`…) ont été
263 /// appliqués au ruleset servi.
264 pub overridden: bool,
265 /// Zone de dépôt : toujours `FR` (jamais une sous-région).
266 pub bidding_zone: String,
267 pub disclaimer: String,
268 pub window_eligible: bool,
269 pub count_eligible: u32,
270 pub count_indeterminate: u32,
271 pub slots: Vec<EligibilitySlotBody>,
272 pub best_eligible: Option<EligibleSlotBody>,
273 /// Identité versionnée du modèle de part renouvelable prévue
274 /// (`share-clim@1`), présente seulement si au moins un créneau est en
275 /// provenance `forecast`.
276 pub share_model: Option<String>,
277}
278
279/// Réponse de `GET /v1/intensity/greenest-window`.
280#[derive(Debug, Clone, Deserialize, PartialEq)]
281pub struct GreenestWindowResponse {
282 pub region: Region,
283 pub methodology: Methodology,
284 /// Identité versionnée du modèle de prévision (ex. `climatology@1`).
285 pub model: String,
286 #[serde(with = "time::serde::rfc3339")]
287 pub start: OffsetDateTime,
288 #[serde(with = "time::serde::rfc3339")]
289 pub end: OffsetDateTime,
290 pub unit: String,
291 pub average_intensity: f64,
292 /// Overlay d'éligibilité électrolyseur (présent uniquement si
293 /// `?eligibility=` a été fourni) — annotation additive, la fenêtre verte
294 /// elle-même est inchangée.
295 pub eligibility: Option<EligibilityBody>,
296}
297
298// --- Scheduling (`/v1/schedule`, `/v1/schedule/slots`) ---------------------
299
300/// Économie carbone d'un créneau planifié vs « maintenant » (ADR-0014).
301#[derive(Debug, Clone, Deserialize, PartialEq)]
302pub struct SavingsBody {
303 pub now: f64,
304 pub scheduled: f64,
305 pub intensity_delta: f64,
306 pub reduction_percent: f64,
307 /// Économie absolue (gCO₂eq), seulement si `energy_kwh` a été fourni à la
308 /// requête.
309 pub absolute_saved_g: Option<f64>,
310}
311
312/// Réponse de `GET /v1/schedule`.
313#[derive(Debug, Clone, Deserialize, PartialEq)]
314pub struct ScheduleResponse {
315 pub region: Region,
316 pub methodology: Methodology,
317 pub model: String,
318 pub estimator: Estimator,
319 pub unit: String,
320 #[serde(with = "time::serde::rfc3339")]
321 pub start: OffsetDateTime,
322 #[serde(with = "time::serde::rfc3339")]
323 pub end: OffsetDateTime,
324 pub average_intensity: f64,
325 pub savings: SavingsBody,
326}
327
328// --- Mix de production (`/v1/mix`) -----------------------------------------
329
330/// Mix de production par filière (`MixResponse::mix`), en MW.
331#[derive(Debug, Clone, Copy, PartialEq, Deserialize)]
332pub struct MixBody {
333 pub nucleaire: f64,
334 pub gaz: f64,
335 pub charbon: f64,
336 pub fioul: f64,
337 pub hydraulique: f64,
338 pub eolien: f64,
339 pub solaire: f64,
340 pub bioenergies: f64,
341 pub pompage: f64,
342 pub echanges: f64,
343 /// Thermique fossile agrégé — **mix régional uniquement**, `None` au
344 /// national.
345 pub thermique: Option<f64>,
346}
347
348/// Part d'une filière dans la production (`MixResponse::shares`). Même forme
349/// que [`PriceMixShareBody`] (contexte de `/v1/price`, un seul composant
350/// OpenAPI côté serveur) — type distinct pour ne pas changer celui d'un champ
351/// public déjà publié.
352#[derive(Debug, Clone, Deserialize, PartialEq)]
353pub struct MixShareBody {
354 /// Slug de filière (`nucleaire`, `thermique`…) — `String`, catalogue
355 /// `#[non_exhaustive]` côté serveur (voir le commentaire de module).
356 pub filiere: String,
357 pub label: String,
358 /// Part dans la production, dans `[0, 1]` (somme = 1).
359 pub share: f64,
360 pub output_mw: f64,
361}
362
363/// Réponse de `GET /v1/mix`.
364#[derive(Debug, Clone, Deserialize, PartialEq)]
365pub struct MixResponse {
366 pub region: Region,
367 #[serde(with = "time::serde::rfc3339")]
368 pub timestamp: OffsetDateTime,
369 pub unit: String,
370 pub mix: MixBody,
371 /// Parts de production par filière (filières à production nulle omises,
372 /// pompage/échanges exclus, `thermique` agrégé au régional). **Vide** face à
373 /// un serveur plus ancien qui ne sert pas encore ce champ.
374 #[serde(default)]
375 pub shares: Vec<MixShareBody>,
376}
377
378// --- Échanges transfrontaliers (`/v1/exchanges*`) ---------------------------
379
380/// Une frontière (`ExchangesResponse::exchanges`) : flux net signé FR↔voisin
381/// + intensité carbone du voisin.
382#[derive(Debug, Clone, Deserialize, PartialEq)]
383pub struct ExchangeEntry {
384 /// Code du voisin (`be`, `de-lu`, `es`, `it-north`, `ch`, `gb`).
385 pub country: String,
386 pub country_name: String,
387 /// Flux net (MW) : `> 0` = la France **importe**, `< 0` = exporte.
388 pub flow_mw: f64,
389 pub direction: FlowDirection,
390 pub intensity: IntensityValue,
391}
392
393/// Réponse de `GET /v1/exchanges`.
394#[derive(Debug, Clone, Deserialize, PartialEq)]
395pub struct ExchangesResponse {
396 #[serde(with = "time::serde::rfc3339")]
397 pub timestamp: OffsetDateTime,
398 pub net_flow_mw: f64,
399 pub direction: FlowDirection,
400 pub imports_mw: f64,
401 pub exports_mw: f64,
402 pub exchanges: Vec<ExchangeEntry>,
403}
404
405/// Réponse de `GET /v1/exchanges/date`.
406#[derive(Debug, Clone, Deserialize, PartialEq)]
407pub struct ExchangesHistoryResponse {
408 #[serde(with = "time::serde::rfc3339")]
409 pub from: OffsetDateTime,
410 #[serde(with = "time::serde::rfc3339")]
411 pub to: OffsetDateTime,
412 pub count: u32,
413 pub snapshots: Vec<ExchangesResponse>,
414}
415
416// --- Météo (`/v1/weather*`) --------------------------------------------------
417
418/// Un créneau météo (`WeatherHistoryResponse::points`), vent à 100 m +
419/// irradiance, moyenne nationale.
420#[derive(Debug, Clone, Deserialize, PartialEq)]
421pub struct WeatherPoint {
422 #[serde(with = "time::serde::rfc3339")]
423 pub valid_at: OffsetDateTime,
424 #[serde(with = "time::serde::rfc3339")]
425 pub run_at: OffsetDateTime,
426 pub wind_kmh: f64,
427 pub irradiance_wm2: f64,
428}
429
430/// Réponse de `GET /v1/weather`.
431#[derive(Debug, Clone, Deserialize, PartialEq)]
432pub struct WeatherResponse {
433 /// Attribution de la source (Open-Meteo, licence CC-BY 4.0).
434 pub source: String,
435 #[serde(with = "time::serde::rfc3339")]
436 pub valid_at: OffsetDateTime,
437 #[serde(with = "time::serde::rfc3339")]
438 pub run_at: OffsetDateTime,
439 pub wind_kmh: f64,
440 pub irradiance_wm2: f64,
441}
442
443/// Réponse de `GET /v1/weather/date`.
444#[derive(Debug, Clone, Deserialize, PartialEq)]
445pub struct WeatherHistoryResponse {
446 pub source: String,
447 #[serde(with = "time::serde::rfc3339")]
448 pub from: OffsetDateTime,
449 #[serde(with = "time::serde::rfc3339")]
450 pub to: OffsetDateTime,
451 pub count: u32,
452 pub points: Vec<WeatherPoint>,
453}
454
455// --- Renouvelable estimé (`/v1/renewable`) ----------------------------------
456
457/// Capacités effectives calibrées (`RenewableResponse::model`, transparence
458/// du modèle).
459#[derive(Debug, Clone, Copy, PartialEq, Deserialize)]
460pub struct RenewableModelInfo {
461 pub wind_capacity_mw: f64,
462 pub solar_capacity_mw: f64,
463}
464
465/// Réponse de `GET /v1/renewable`.
466#[derive(Debug, Clone, Deserialize, PartialEq)]
467pub struct RenewableResponse {
468 /// Attribution (météo Open-Meteo CC-BY 4.0 ; valeurs modélisées).
469 pub source: String,
470 #[serde(with = "time::serde::rfc3339")]
471 pub at: OffsetDateTime,
472 pub wind_mw: f64,
473 pub solar_mw: f64,
474 pub wind_capacity_factor: f64,
475 pub solar_capacity_factor: f64,
476 pub model: RenewableModelInfo,
477}
478
479// --- Méthodologies et facteurs (`/v1/methodologies`, `/v1/factors`) --------
480
481/// Une méthodologie du catalogue (`MethodologiesResponse::methodologies`).
482#[derive(Debug, Clone, Deserialize, PartialEq)]
483pub struct MethodologyInfo {
484 /// Identifiant stable (`rte-direct`, `acv-ademe`…) — `String` et pas
485 /// [`Methodology`] : catalogue de découverte, peut lister une méthode
486 /// `planned` non encore sélectionnable (voir le commentaire de module).
487 pub id: String,
488 pub version: u32,
489 pub basis: String,
490 pub scope: String,
491 /// `true` si servie par défaut quand `?methodology=` est absent.
492 pub default: bool,
493 /// `served` (interrogeable) ou `planned` (spécifiée, pas encore servie).
494 pub status: String,
495 pub adr: String,
496 pub description: String,
497}
498
499/// Réponse de `GET /v1/methodologies`.
500#[derive(Debug, Clone, Deserialize, PartialEq)]
501pub struct MethodologiesResponse {
502 pub methodologies: Vec<MethodologyInfo>,
503}
504
505/// Une région servie (`RegionsResponse::regions`).
506#[derive(Debug, Clone, Deserialize, PartialEq)]
507pub struct RegionInfo {
508 /// Slug stable — la valeur du paramètre `region` ([`Region`] tolère un
509 /// futur slug inconnu via `Region::Other`).
510 pub slug: Region,
511 pub label: String,
512 /// Code INSEE de la région métropolitaine ; `None` pour `national`.
513 pub insee_code: Option<String>,
514 /// `true` pour la maille nationale.
515 pub national: bool,
516}
517
518/// Réponse de `GET /v1/regions` — catalogue statique : national puis les 12
519/// régions métropolitaines (même ordre que `GET /v1/intensity/now/all`).
520#[derive(Debug, Clone, Deserialize, PartialEq)]
521pub struct RegionsResponse {
522 pub regions: Vec<RegionInfo>,
523}
524
525/// Un facteur d'émission par filière (`FactorsResponse::factors`).
526#[derive(Debug, Clone, Deserialize, PartialEq)]
527pub struct FactorEntry {
528 /// Filière (`nucleaire`, `gaz`…) — `String`, pas dans le périmètre des
529 /// enums dupliqués.
530 pub filiere: String,
531 /// Facteur cycle de vie (gCO₂eq/kWh).
532 pub factor: f64,
533}
534
535/// Réponse de `GET /v1/factors`.
536#[derive(Debug, Clone, Deserialize, PartialEq)]
537pub struct FactorsResponse {
538 pub methodology: Methodology,
539 pub methodology_version: u32,
540 pub unit: String,
541 pub source: String,
542 /// Facteur de pertes T&D appliqué, `None` hors méthode consommation.
543 pub td_loss_factor: Option<f64>,
544 pub factors: Vec<FactorEntry>,
545}
546
547// --- Index qualitatif (`/v1/intensity/index`) ------------------------------
548
549/// Une bande du barème de l'index qualitatif (`IntensityIndexResponse::bands`),
550/// intervalle `[min, max[` en gCO₂eq/kWh.
551#[derive(Debug, Clone, Deserialize, PartialEq)]
552pub struct IndexBand {
553 /// La valeur servie dans le champ `index` des réponses.
554 pub label: IntensityIndex,
555 /// Borne basse **incluse** (gCO₂eq/kWh), `None` pour la première bande.
556 pub min: Option<f64>,
557 /// Borne haute **exclue** (gCO₂eq/kWh), `None` pour la dernière bande.
558 pub max: Option<f64>,
559 /// Ce que la bande signifie, en une phrase.
560 pub description: String,
561}
562
563/// Une borne du barème et ce qui la fonde (`IntensityIndexResponse::thresholds`).
564#[derive(Debug, Clone, Deserialize, PartialEq)]
565pub struct IndexThreshold {
566 /// Valeur de la borne (gCO₂eq/kWh) : haute **exclue** de `below`, basse
567 /// **incluse** de `above`.
568 pub value: f64,
569 /// Bande sous la borne.
570 pub below: IntensityIndex,
571 /// Bande à partir de la borne.
572 pub above: IntensityIndex,
573 /// Source de la borne : texte réglementaire ou facteur publié.
574 pub source: String,
575 /// Où la vérifier : URL absolue d'un texte officiel, ou chemin relatif à
576 /// cette API (`/v1/factors?…`) — d'où un `String`, pas un type `Url`.
577 pub url: String,
578}
579
580/// Réponse de `GET /v1/intensity/index` — barème de l'index qualitatif
581/// (ADR-0033) : même rôle que `/v1/factors` pour l'ACV, la légende du champ
582/// `index` est **auditable** (bornes et sources) au lieu d'être codée en dur
583/// côté client. Serveur ≥ 0.11 (404 avant).
584#[derive(Debug, Clone, Deserialize, PartialEq)]
585pub struct IntensityIndexResponse {
586 /// Version du barème (`index@1`) : immuable, toute révision est une
587 /// nouvelle version.
588 pub version: u32,
589 pub unit: String,
590 /// Les cinq bandes, de la plus basse à la plus haute (`[min, max[`).
591 pub bands: Vec<IndexBand>,
592 /// Les quatre bornes, croissantes, chacune avec sa source.
593 pub thresholds: Vec<IndexThreshold>,
594 /// Ce que l'index dit — et ne dit pas.
595 pub note: String,
596 pub source: String,
597}
598
599// --- Prix (`/v1/price*`, `/v1/cost-reference`) ------------------------------
600
601/// Une composante du prix (`PriceResponse::components`).
602#[derive(Debug, Clone, Deserialize, PartialEq)]
603pub struct PriceComponentBody {
604 /// Identifiant stable (`energie`, `acheminement`, `accise`,
605 /// `commercialisation`, `tva`) — `String`, pas dans le périmètre des
606 /// enums dupliqués.
607 pub kind: String,
608 pub label: String,
609 pub amount_eur_mwh: f64,
610 /// Source / fondement réglementaire de la composante.
611 pub source: String,
612}
613
614/// Part d'une filière dans le mix (`PriceContextBody::mix`).
615#[derive(Debug, Clone, Deserialize, PartialEq)]
616pub struct PriceMixShareBody {
617 pub filiere: String,
618 pub label: String,
619 /// Part dans la production domestique, dans `[0, 1]`.
620 pub share: f64,
621 pub output_mw: f64,
622}
623
624/// Technologie marginale **estimée** (`PriceContextBody::marginal_technology`,
625/// ordre de mérite domestique — jamais mesurée, `estimated` vaut toujours
626/// `true`).
627#[derive(Debug, Clone, Deserialize, PartialEq)]
628pub struct MarginalTechnologyBody {
629 pub filiere: String,
630 pub label: String,
631 pub estimated: bool,
632 /// Méthode d'estimation (transparence).
633 pub method: String,
634}
635
636/// Contexte explicatif du prix (`PriceResponse::context`, ADR-0023 §4).
637#[derive(Debug, Clone, Deserialize, PartialEq)]
638pub struct PriceContextBody {
639 pub mix: Vec<PriceMixShareBody>,
640 pub marginal_technology: Option<MarginalTechnologyBody>,
641}
642
643/// Réponse de `GET /v1/price`.
644#[derive(Debug, Clone, Deserialize, PartialEq)]
645pub struct PriceResponse {
646 pub region: Region,
647 #[serde(with = "time::serde::rfc3339")]
648 pub timestamp: OffsetDateTime,
649 /// Millésime de la construction réglementaire en vigueur à cet
650 /// horodatage (ex. `2026-H2`) — `String`, pas un instant RFC 3339 (voir
651 /// le commentaire de module).
652 pub vintage: String,
653 pub unit: String,
654 pub currency: String,
655 pub total_eur_mwh: f64,
656 pub total_eur_kwh: f64,
657 pub components: Vec<PriceComponentBody>,
658 pub context: PriceContextBody,
659 pub disclaimer: String,
660}
661
662/// Un point compact de `GET /v1/price/date` (`PriceHistoryResponse::points`).
663#[derive(Debug, Clone, Deserialize, PartialEq)]
664pub struct PricePointBody {
665 #[serde(with = "time::serde::rfc3339")]
666 pub timestamp: OffsetDateTime,
667 pub energie_eur_mwh: f64,
668 pub total_eur_mwh: f64,
669}
670
671/// Réponse de `GET /v1/price/date`.
672#[derive(Debug, Clone, Deserialize, PartialEq)]
673pub struct PriceHistoryResponse {
674 #[serde(with = "time::serde::rfc3339")]
675 pub from: OffsetDateTime,
676 #[serde(with = "time::serde::rfc3339")]
677 pub to: OffsetDateTime,
678 pub count: u32,
679 pub unit: String,
680 pub currency: String,
681 pub points: Vec<PricePointBody>,
682}
683
684/// Hypothèses d'une estimation LCOE (`CostReferenceEntry::hypotheses`),
685/// `None` = « non publié par la source », jamais une dimension retirée.
686#[derive(Debug, Clone, Copy, PartialEq, Deserialize)]
687pub struct CostAssumptionsBody {
688 pub discount_rate: Option<f64>,
689 pub lifetime_years: Option<u32>,
690 pub load_factor: Option<f64>,
691}
692
693/// Fourchette d'une estimation LCOE (`CostReferenceEntry::range`).
694#[derive(Debug, Clone, PartialEq, Deserialize)]
695pub struct LcoeRangeBody {
696 pub min: f64,
697 pub median: f64,
698 pub max: f64,
699 pub unit: String,
700}
701
702/// Une estimation LCOE (source × technologie × périmètre × millésime,
703/// `CostReferenceResponse::entries`, ADR-0024). Champs catalogue
704/// (`technology`/`source`/`perimeter`/`basis`) en `String` : hors du
705/// périmètre des enums dupliqués par cette mission.
706#[derive(Debug, Clone, Deserialize, PartialEq)]
707pub struct CostReferenceEntry {
708 pub technology: String,
709 pub technology_label: String,
710 pub source: String,
711 pub source_label: String,
712 pub source_attribution: String,
713 /// `france` ou `monde` — les valeurs IRENA sont **mondiales**.
714 pub geography: String,
715 pub perimeter: String,
716 pub perimeter_label: String,
717 /// `accounting-amortized` (coût comptable) vs `prospective-lcoe`
718 /// (moyen neuf).
719 pub basis: String,
720 pub basis_label: String,
721 /// Nombre de sources distinctes pour cette filière (≥ 2 = dispersion
722 /// inter-sources).
723 pub technology_source_count: u32,
724 /// Millésime (année du rapport source) — entier, distinct de
725 /// `HistoryPoint::vintage`/`IntensityResponse::vintage` (étiquette de
726 /// révision, pas un millésime).
727 pub vintage: u32,
728 /// Statut : toujours `estimation` (ADR-0024 §4).
729 pub kind: String,
730 pub range: LcoeRangeBody,
731 pub hypotheses: CostAssumptionsBody,
732}
733
734/// Réponse de `GET /v1/cost-reference` — couche comparative LCOE (ADR-0024).
735/// **Estimation**, en fourchette, jamais mise en différence avec le prix de
736/// marché (`disclaimer` obligatoire, ADR-0024 §3).
737#[derive(Debug, Clone, Deserialize, PartialEq)]
738pub struct CostReferenceResponse {
739 pub unit: String,
740 pub currency: String,
741 /// Statut systématique de la couche : `estimation`.
742 pub kind: String,
743 pub disclaimer: String,
744 pub count: u32,
745 pub entries: Vec<CostReferenceEntry>,
746}
747
748// --- Éligibilité (`/v1/eligibility/rulesets`) -------------------------------
749
750/// Une entrée du catalogue (`RulesetsResponse::rulesets`).
751#[derive(Debug, Clone, Deserialize, PartialEq)]
752pub struct RulesetInfo {
753 pub framework: EligibilityFramework,
754 pub version: String,
755 /// `served` (appliqué) ou `planned` (réservé, texte non adopté).
756 pub status: String,
757 pub adr: String,
758 /// Granularité de corrélation temporelle (pilier `rfnbo`) ;
759 /// `n/a (pilier rfnbo)` pour `low-carbon`.
760 pub granularity: String,
761 /// Seuil renouvelable de l'exception Article 4 (`rfnbo` uniquement).
762 pub article4_renewable_threshold: Option<f64>,
763 pub surplus_price_eur_mwh: Option<f64>,
764 /// Date de bascule horaire (`rfnbo`), ex. `2030-01-01` — **date seule**,
765 /// pas un instant RFC 3339 (voir le commentaire de module), `None` pour
766 /// `low-carbon`.
767 pub hourly_switchover: Option<String>,
768 pub low_carbon_intensity_threshold_g_per_kwh: Option<f64>,
769 pub low_carbon_intensity_is_indicative: bool,
770 /// Consommation électrolyseur qui dérive le seuil (`low-carbon`
771 /// uniquement).
772 pub electrolyzer_kwh_per_kg: Option<f64>,
773 pub legal_basis: String,
774 pub description: String,
775}
776
777/// Réponse de `GET /v1/eligibility/rulesets`.
778#[derive(Debug, Clone, Deserialize, PartialEq)]
779pub struct RulesetsResponse {
780 pub rulesets: Vec<RulesetInfo>,
781 pub disclaimer: String,
782}
783
784// --- Statistiques de visite (`/v1/stats`, `POST /v1/stats/visit`) ----------
785
786/// Réponse de `GET /v1/stats` et `POST /v1/stats/visit`.
787#[derive(Debug, Clone, PartialEq, Deserialize)]
788pub struct VisitStatsResponse {
789 pub unique: u64,
790 pub total: u64,
791 /// Premier jour comptabilisé, `ISO YYYY-MM-DD` — **date seule**, pas un
792 /// instant RFC 3339 (voir le commentaire de module), `None` si aucun.
793 pub since: Option<String>,
794}
795
796// --- Webhooks (`/v1/webhooks*`) --------------------------------------------
797
798/// Corps de `POST /v1/webhooks` (ADR-0016).
799#[derive(Debug, Clone, Serialize, PartialEq)]
800pub struct CreateWebhookRequest {
801 /// Seuil d'intensité (gCO₂eq/kWh).
802 pub threshold: f64,
803 pub direction: ThresholdDirection,
804 /// URL HTTPS de rappel (validée anti-SSRF côté serveur).
805 pub callback_url: String,
806 /// Région à surveiller. National par défaut si `None`.
807 pub region: Option<Region>,
808}
809
810/// Réponse de création : inclut le **secret** (affiché une seule fois,
811/// jamais ré-exposé par `GET /v1/webhooks`).
812#[derive(Debug, Clone, Deserialize, PartialEq)]
813pub struct CreatedWebhookResponse {
814 pub id: String,
815 /// Secret de signature HMAC — à conserver, non ré-affiché.
816 pub secret: String,
817 pub region: Region,
818 pub threshold: f64,
819 pub direction: ThresholdDirection,
820 pub callback_url: String,
821}
822
823/// Résumé d'un abonnement, sans le secret (`WebhookListResponse::webhooks`).
824#[derive(Debug, Clone, Deserialize, PartialEq)]
825pub struct WebhookSummary {
826 pub id: String,
827 pub region: Region,
828 pub threshold: f64,
829 pub direction: ThresholdDirection,
830 pub callback_url: String,
831 pub status: WebhookStatus,
832 /// Instant de la désactivation automatique, `None` si actif.
833 #[serde(with = "time::serde::rfc3339::option")]
834 pub disabled_at: Option<OffsetDateTime>,
835}
836
837/// Réponse de `GET /v1/webhooks`.
838#[derive(Debug, Clone, Deserialize, PartialEq)]
839pub struct WebhookListResponse {
840 pub count: u32,
841 pub webhooks: Vec<WebhookSummary>,
842}