← all branches

feat/energy-api

safeviewing older commit
678cb93 · incrementalPR #207reviewed 2026-07-05 17:40 UTC0H · 0M · 1L · 4I
The branch
Purpose
Port the legacy electricity-data-api (billing + savings + metrics + webhooks + PDFs, Pulumi/DDB/Athena in batu-monorepo) into the platform following the 10-phase roadmap.
Goal
Deliver the functional core of the full port end-to-end: metrics adapter → tariff/TOU reference data → CFE bill calculators → calculated-bill persistence → PDF (Phases 0–8), plus Inc-1 pure cores for run orchestration, webhooks, savings, and public-v1 API.
Sub-goals
  • SG-0: Port spec + decisions D1–D5 (decisions-port.md)
  • SG-1: Tinybird → SiteMetrics adapter (derived-at-read, integral transform, DQ) — KK matched 1e-6
  • SG-2a: tariff_rate_values storage (mig 0046, 5801 legacy rates seeded)
  • SG-2b: CFE TOU classifier + tariff_tou_schedules (mig 0045, 97 schedules, conservation 1e-9)
  • SG-3: CFE bill calculators + THOR FAC + computeCfeBillShell + persist/dedup
  • SG-4: Run orchestration Inc-1 — pure planner + runScheduledBillingShell
  • SG-5: Webhooks Inc-1 — utility.bill.finalized + WebhookDeliveryFCIS
  • SG-6: Savings Inc-1 — SavingsFCIS.calculateSavingsReport
  • SG-7: Public /v1 API Inc-1 — GET /v1/sites/:id/energy-summary
  • SG-8: PDFs — @batu/bill-pdf (react-pdf) + S3/bill_files persist + tz-local charts
The changes (whole branch)
What
Corrects two audit-trail comments in tariff-jobs.handler.ts: (1) renames withPublicApiAuth → withAuth (Supabase session) to accurately reflect the actual middleware used; (2) expands the dispatchTariffJobPipeline justification to clarify it performs service-role writes (SFN ARN recording + failure marking), not a read.
Why
The old comment incorrectly named withPublicApiAuth (the /v1/* machine-JWT middleware) as the auth gate for a handler that uses withAuth (Supabase session). This was a documentation error that could mislead future developers copying the pattern. Also removes reference to BAT-247 ticket in inline comment (per convention: ticket refs belong in PR descriptions, not source code).
Areas
apps/platform/src+16542−4387domains/cross-domain/src+8434−13domains/utility/src+6633−28domains/metrics/src+1172−9packages/database/src+2338−8packages/api/src+1073−33packages/bill-pdf/src+326−0infra/cdk/src+675−0
Blast
481 files, +49711/-4729 across 8 major areas (cumulative branch). This incremental commit touches 1 file, 0 functional lines changed — comment corrections only.
Phase 9 (legacy A/B peso-to-peso validation) open — known gap, tracked in PR Inc-2 infra (cron→SFN→worker, webhook delivery, savings entities) deferred to follow-up
➖ci· CI check API not accessible from runner token➖coderabbit· No .coderabbit.yaml in repo

Findings · 5

correctness3

low

Old comment named wrong auth middleware — copy risk now resolved

apps/platform/src/api/handlers/tariff-jobs.handler.ts:58

Previous comment said 'gated by withPublicApiAuth — matches the cfe-jobs posture (BAT-247)'. withPublicApiAuth is the Bearer-only public-API middleware (/v1/* surface, accepts machine JWTs); this handler uses withAuth (Supabase session). A developer copy-pasting the handler stub could have wired the wrong middleware. Fix removes that risk.

info

Corrected auth middleware name is accurate

apps/platform/src/api/handlers/tariff-jobs.handler.ts:58

The file imports withAuth (line 16) and calls it (line 43). Updated comment now correctly names withAuth (Supabase session).

info

Expanded dispatchTariffJobPipeline comment matches implementation

apps/platform/src/api/handlers/tariff-jobs.handler.ts:82

New comment — 'records the SFN execution ARN best-effort, marks the job failed on dispatch error' — accurately reflects the dispatch utility: recordExecutionArnShell is best-effort (ignored on error), failTariffJobShell is called on dispatch failure.

security1

info

Comment correction eliminates auth-path confusion

apps/platform/src/api/handlers/tariff-jobs.handler.ts:58

Old comment could have led an auditor reading comments-only to conclude the machine-JWT path was the entry point. Now correct. No security concern introduced.

conventions1

info

WHY-focused admin-required audit comments comply with project pattern

apps/platform/src/api/handlers/tariff-jobs.handler.ts:58

Both revised comments follow the established admin-required: audit trail pattern — explain WHY admin is needed (global scope, service-role write, no org). The added detail on dispatch clarifies it is a write, not a read — non-obvious from the function name alone.

History · 8 commits

  1. d6b4a35needs attentionincremental4H · 4M · 5L2026-07-05 20:29
  2. 678cb93safeincremental0H · 0M · 1L2026-07-05 17:40current
  3. d219403needs attentionincremental1H · 3M · 4L2026-07-05 05:37
  4. 5ecd80cneeds attentionincremental1H · 2M · 1L2026-07-05 04:59
  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