Skip to main content

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}