← all branches

feat/energy-api

needs attentionviewing older commit
5ecd80c · incrementalPR #207reviewed 2026-07-05 04:59 UTC1H · 2M · 1L
The branch
Purpose
Port the legacy electricity-data API (billing + savings + metrics + webhooks + PDFs, batu-monorepo, Pulumi/DDB/Athena) into this platform, establishing the SiteMetrics seam as the metrics↔billing boundary.
Goal
Deliver Phases 0–8+ of the port: Tinybird SiteMetrics adapter, CFE bills integration, savings calculation, PDF generation, and all associated API contracts.
Sub-goals
  • SG-0: Port spec + decisions (decisions-port.md)
  • SG-1: Tinybird → SiteMetrics metrics adapter (resolveMetricStreamWindow)
  • SG-2: CFE bills domain port (energy bill generation)
  • SG-3: Savings calculation core
  • SG-4–8: PDF generation, API contracts, webhooks, portfolio, asset-fleet endpoints
  • SG-Helioscope: operation_start_date migration from site_locations → sites
The changes (whole branch)
What
Fix Helioscope handlers to read operationStartDate from the sites table instead of siteLocations, matching the schema migration (migrations 0054-0056) that moved operation_start_date to sites. One comment update (daily-job) and one DB query field remap (materialize-persist).
Why
The operation_start_date column was moved from site_locations to sites as part of this branch's schema work. Without this fix, loadSourceContext would return operationStartDate: null for every source (siteLocations.operationStartDate no longer exists), causing the guard to skip all Helioscope top-ups.
Areas
apps/platform+16526−4387domains/cross-domain+8435−13domains/utility+6640−28docs/development+5512−0packages/database+2560−8domains/metrics+1180−14packages/api+1142−33packages/ui+3529−0services/utility+1286−0infra/cdk+675−0packages/bill-pdf+366−0services/metrics+79−26+2 more
Blast
490 files, +112k/−4.7k across 14 areas; this incremental commit touches 2 files (+4/−1) in services/metrics only.
schema-migration-followup no-integration-test-coverage
➖ci· CI status not accessible via this token

Findings · 4

conventions2

medium

Branch reference in comment will rot

services/metrics/integrations/helioscope/src/handlers/materialize-persist.lambda.ts:536

The comment includes "(feat/energy-api)" — a branch name reference. Per project conventions, task/fix/branch references belong in the PR description, not in code comments, as they rot after merge. Remove the branch name; the structural why (operation_start_date belongs on sites) is worth keeping.

low

Second comment clause restates visible code structure

services/metrics/integrations/helioscope/src/handlers/materialize-persist.lambda.ts:537

"sites is inner-joined below, so read it from there" describes what is already visible two lines down. Only the non-obvious WHY deserves a comment — why siteLocations is still in the query at all (for timezone). Trim to just that: "// site_locations stays for timezone; operation_start_date moved to sites."

tests2

high

No integration test for loadSourceContext — operationStartDate regression undetectable

services/metrics/integrations/helioscope/src/handlers/materialize-persist.lambda.ts:538

All existing tests mock loadContext via the ctxLoader seam, so the real loadSourceContext DB query (now reading sites.operationStartDate instead of siteLocations.operationStartDate) is never exercised. A silently-wrong column reference would return operationStartDate: null on every real invocation and trigger the guard — but no test catches it. Add an integration test that seeds a metricSource + metricStream + site with operationStartDate set and asserts the field comes back correctly.

medium

Stale operator error message still references site_locations

services/metrics/integrations/helioscope/src/handlers/materialize-persist.lambda.ts:324

The invalidInput message says "set it on site_locations." but operation_start_date now lives on the sites table. An operator following this message will look in the wrong place. The existing test asserts on _tag only (HelioscopeMpInvalidInput) and does not pin the message text, so this stays undetected. Fix: change "site_locations" to "sites" in the error string and extend the test to assert on the message.

History · 8 commits

  1. d6b4a35needs attentionincremental4H · 4M · 5L2026-07-05 20:29
  2. 678cb93safeincremental0H · 0M · 1L2026-07-05 17:40
  3. d219403needs attentionincremental1H · 3M · 4L2026-07-05 05:37
  4. 5ecd80cneeds attentionincremental1H · 2M · 1L2026-07-05 04:59current
  5. 3fd1d03needs attentionincremental0H · 3M · 5L2026-07-05 04:36
  6. 1446f7eneeds attentionincremental2H · 4M · 7L2026-07-05 04:08
  7. ca73a1bneeds attentionfull4H · 10M · 14L2026-07-05 02:46
  8. c24738eneeds attentionincremental3H · 10M · 9L2026-07-04 05:12