From 21b25b8b3595eb7b9e15650f714e1b7c644e6005 Mon Sep 17 00:00:00 2001 From: Khalim Conn-Kowlessar Date: Fri, 26 Jun 2026 16:53:42 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20record=20PV-array=20+=20floor-flag=20ro?= =?UTF-8?q?und-trip=20closures=20=F0=9F=9F=AA?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Document Slice 2 in the persistence-fidelity migration log, plus the 7 calculator-read nested gaps the recursive guard newly surfaced (tracked follow-up). Co-Authored-By: Claude Opus 4.8 (1M context) --- .../epc-property-round-trip-fidelity.md | 49 +++++++++++++++++-- 1 file changed, 46 insertions(+), 3 deletions(-) diff --git a/docs/migrations/epc-property-round-trip-fidelity.md b/docs/migrations/epc-property-round-trip-fidelity.md index a23d0f62..f91b8a4f 100644 --- a/docs/migrations/epc-property-round-trip-fidelity.md +++ b/docs/migrations/epc-property-round-trip-fidelity.md @@ -58,14 +58,57 @@ now fails if any `EpcPropertyData` field is neither reconstructed by `_compose` allow-list — so the gaps below are no longer "latent until a fixture exercises them", they are explicit and tracked. -**Still open (follow-up issues):** the remaining §2 structural tables (room-in-roof detail, PV -arrays, **roof windows** — `sap_roof_windows`) + §3 nested-wall fields -(`SapAlternativeWall.u_value`/`wall_thickness_mm`) + `SapFloorDimension` exposed-floor flags + the +**Still open (follow-up issues):** the remaining §2 structural tables (room-in-roof detail, +**roof windows** — `sap_roof_windows`) + §3 nested-wall fields +(`SapAlternativeWall.u_value`/`wall_thickness_mm`) + the solar-HW collector columns (`solar_hw_collector_orientation` / `_pitch_deg` / `_overshading`, §3.1). Each is on the structural-guard allow-list with a reason until its columns land. --- +## Slice 2 — PV arrays + floor heat-loss flags (#TBD) + +Closed two **scoring-relevant** round-trip gaps that were corrupting the modelling baseline by up +to ~12 SAP points on a real Hyde property (725634, an ASHP + solar dwelling whose DB-read picture +scored ~12 points below the in-memory cert it was modelled from): + +- **§2 `epc_photovoltaic_array` child table** — `sap_energy_source.photovoltaic_arrays` (a list of + `peak_power` kWp + `pitch`/`overshading`/`orientation` SAP codes) had no table, so every array was + dropped on save and the dwelling lost its PV generation credit. Now persisted (one row per array, + ordered by `array_index`) and reconstructed in `_to_energy_source`. **Round-trip test asserts + deep-equality** (`test_photovoltaic_arrays_round_trip`). +- **§3 `epc_floor_dimension` flags** — `is_exposed_floor` + `is_above_partially_heated_space` had no + columns, so a `True` flag round-tripped back to the `False` default and silently flipped the + floor's heat-loss path. Now persisted and reconstructed in `_to_floor_dimension`. **Round-trip + test** `test_floor_dimension_heat_loss_flags_round_trip`. + +DB migration: FE branch `feature/epc-pv-and-floor-heatloss-schema` (additive — new table + two +`NOT NULL DEFAULT false` columns; no backfill). Run `drizzle-kit generate`/migrate **before** +deploying this backend code. + +### Recursive-guard gaps (newly surfaced) + +Generalising the ADR-0036 structural guard to recurse into **nested** dataclasses (it previously +saw only `EpcPropertyData`'s top-level fields — which is exactly how the PV-array and floor-flag +drops stayed latent) surfaced **7 pre-existing, calculator-read** nested fields with no FE column. +These are silent-drop gaps of the **same class as the PV bug** and want their own follow-up +(verify scoring impact per field, then add FE columns): + +| Field | Lives on | +|---|---| +| `community_heating_boiler_fuel_type`, `community_heating_chp_fraction` | `MainHeatingDetail` | +| `is_sheltered` | `SapAlternativeWall` | +| `wall_insulation_thermal_conductivity` | `SapBuildingPart` | +| `pv_diverter_present` | `SapEnergySource` | +| `cylinder_volume_measured_l` | `SapHeating` | +| `air_permeability_ap50_m3_h_m2` | `SapVentilation` | + +(Plus dormant, not-calculator-read nested fields: `SapBuildingPart.{floor_u_value, roof_u_value, +wall_u_value, wall_is_basement, rafter_insulation_thickness}`, `SapAlternativeWall.is_basement`, +`SapHeating.cylinder_heat_loss` — allow-listed as dormant.) + +--- + ## 1. Type fidelity — convert `Union[int, str]` code columns to JSONB These columns hold SAP/RdSAP categorical codes that are **`int` from the gov API** and **`str`