feat: unblock geo-enrichment (coords) + exact/estimate EPC with manual address override

[timothygithinji]

Why

A read of prod data showed the enrichment pipeline — gaff's differentiator — was mostly empty: only ~18% of clusters had crime/flood/amenities/council-tax, and EPC was 0/102. Root causes (both confirmed against prod, not guessed):

1. Coordinates were stranded. Zoopla/OpenRent listings carry true per-property lat/lng in rawJson, but they were never promoted to the listings.lat/lng columns the enrichments read — so the geo tasks no-op'd for ~80% of clusters. (Geocoding from postcode doesn't help: scraped postcodes are outcodes only, e.g. "N11".)
2. EPC had no way to pick the right cert. An outcode search returns the whole district's certificates with no coordinates to disambiguate, so the old code stamped one arbitrary cert on every cluster.

What

• fix(enrich) — backfill stranded rawJson coords → listings → property_clusters, then re-fire the geo enrichments. (Already run against prod: geo-enrichment 18% → ~95%.)
• feat(enrich-epc) — reverse-geocode the now-populated coords to a full unit postcode, exact-match a certificate by house number + street when the address has one, else a labelled postcode-level estimate (modal rating + range), else blank. Guards bedroom counts ("2 Bedroom Flat") from being mistaken for house numbers.
• feat(epc) — manual address override: property_clusters.user_address (migration 0014) + setClusterAddress server fn. The user pins the exact door (read off the photos vs Google Maps) → re-resolves EPC precisely. UI: a "Fix address for exact EPC" link → "Pin the exact address" dialog; cards show ~C est, listing detail shows EPC · area estimate · ~C · range C–E · N homes.

Verified

Driven in-app against prod data (logged in): geo-enrichment card populated, EPC renders ~D · area estimate · range C–E · 18 homes for a sample N14 listing, Fix-address dialog opens. Resolver across all clusters: 88 estimate / 1 exact / 1 none of 90. bun run build clean, 154 tests pass.

⚠️ Deploy notes

Done to prod DB already this session: migration 0014 applied, coords backfilled, EPC populated, geo-enrichment populated. Still needed: deploy this branch so the Worker serves the new code — until then the live site won't show the EPC display / dialog, and new scrapes won't self-promote coords or run the new enrich-epc. (The coords forward-path itself was already in main via 5c7fd543; it just needs deploying.)

🤖 Generated with Claude Code

Summary by CodeRabbit

Release Notes

• New Features

  • Added ability to manually pin exact property address for improved EPC data accuracy.
  • EPC estimates now clearly marked with ~ indicator and show min/max rating ranges.

• Improvements

  • Address editing available on both mobile and desktop listing views.
  • Better distinction between exact EPC certificates and postcode-level estimates.

[coderabbitai]

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Free

Run ID: 5ea7d818-c961-45e7-83e5-facd3484f5d4

📥 Commits

Reviewing files that changed from the base of the PR and between e938563 and e7f29da.

📒 Files selected for processing (15)

• db/schema.ts
• drizzle/0014_cuddly_lily_hollister.sql
• drizzle/meta/0014_snapshot.json
• drizzle/meta/_journal.json
• scripts/backfill-listing-coords.ts
• src/components/listing-detail/desktop-listing-detail.tsx
• src/components/review/info-row.tsx
• src/components/review/review-card.tsx
• src/lib/geocode.ts
• src/routes/index.tsx
• src/routes/listings/$clusterId.tsx
• src/server/functions/listing-detail.ts
• src/server/functions/review.ts
• src/trigger/enrich-epc.test.ts
• src/trigger/enrich-epc.ts

---

Walkthrough

This PR adds a postcode-and-address-driven EPC enrichment workflow, user address pinning capability, and estimate markers for postcode-level EPC data. Schema adds userAddress column; geocoding support via postcodes.io enables coordinate-to-postcode resolution; EPC enrichment refactors to prioritise exact address matching before falling back to postcode-level estimates; UI surfaces address editing and visually distinguishes estimates with ~ markers.

Changes

Core EPC Address Override & Enrichment

Layer / File(s)	Summary
Schema migration: userAddress column db/schema.ts, drizzle/0014_cuddly_lily_hollister.sql, drizzle/meta/_journal.json	Adds nullable userAddress text column to propertyClusters table for user-supplied address overrides, tracked in Drizzle migration.
Reverse postcode geocoding src/lib/geocode.ts	Introduces reverseGeocodePostcode(lat, lng, options) helper that calls postcodes.io to snap cluster coordinates to full UK postcodes, enabling postcode resolution when exact address is unavailable.
Listing coordinate backfill script scripts/backfill-listing-coords.ts	Executable script that promotes numeric coords from listings.rawJson, propagates to NULL cluster coords deterministically, and re-triggers four geo enrichment tasks in batches.
EPC enrichment: postcode-and-address-driven approach src/trigger/enrich-epc.ts	Replaces coordinate-based certificate selection with: full postcode resolution (manual override → scraped postcode → reverse geocode), exact matching when house number + street word overlap is present, postcode-level estimate rollup when exact match unavailable, and provenance tracking (source: "exact" | "estimate" | "none"). Introduces pickExactCert, exactBlob, and estimateBlob helpers and rewrites enrichEpcTask run flow.
EPC enrichment test suite src/trigger/enrich-epc.test.ts	Comprehensive tests for pickExactCert (address matching logic), exactBlob (10-year expiry, camelCase mapping), and estimateBlob (postcode modal aggregation, tie-breaking) replacing the prior normalisation tests.
Listing detail server function: address override & EPC metadata src/server/functions/listing-detail.ts	Extended ListingDetailCluster to include userAddress: string | null and ListingDetailEpc to include source?: "exact" | "estimate", range?: { min; max }, and sampleSize?: number. Added setClusterAddress(clusterId, address) POST function that persists override, enforces household ownership, and triggers enrich-epc re-enrichment.
Review card: epcIsEstimate flag src/server/functions/review.ts	Extended ReviewCard type with optional epcIsEstimate field computed from enrichment blob source metadata via new isEpcEstimate helper, enabling client-side distinction between exact certificates and postcode estimates.

UI: EPC Estimate Marker & Address Override

Layer / File(s)	Summary
InfoRow: estimate EPC marker src/components/review/info-row.tsx	Updated InfoRow Props to accept optional epcIsEstimate flag; EPC cell now conditionally renders ~ prefix and "est" unit when estimate, or plain rating otherwise.
ReviewCard: pass epcIsEstimate to InfoRow src/components/review/review-card.tsx	Thread epcIsEstimate from review card data through to InfoRow component.
Hero page: EPC estimate display src/routes/index.tsx	Updated buildHeroData to format hero EPC spec with ~{epcRating} when marked as estimate.
DesktopListingDetail: address edit button src/components/listing-detail/desktop-listing-detail.tsx	Added optional onEditAddress callback prop; wired through InfoColumn → PriceCard to render conditional "Edit pinned address" or "Fix address for exact EPC" button based on cluster.userAddress presence.
DesktopListingDetail: estimate EPC display src/components/listing-detail/desktop-listing-detail.tsx	Extended epcRecordRow to display estimate records with ~ prefix and postcode-level metadata (range, sampleSize).
Listing page: address override dialog & mutation src/routes/listings/$clusterId.tsx	Added address-entry dialog with input, save/clear controls, and setAddress mutation backing; integrated with desktop onEditAddress callback and mobile action button to allow users to pin exact addresses and trigger EPC re-enrichment.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

---

Note

🎁 Summarized by CodeRabbit Free

Your organization is on the Free plan. CodeRabbit will generate a high-level summary and a walkthrough for each pull request. For a comprehensive line-by-line review, please upgrade your subscription to CodeRabbit Pro by visiting https://app.coderabbit.ai/login.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}