fix/api-demanda
needs attentionviewing older commit3d60435 · incrementalPR #348reviewed 2026-07-24 20:38 UTC0H · 2M · 3L- Purpose
- Fix a public-API gap: GET /v1/bills returned neither hiredDemand nor connectedCharge even though the Batu app's recibos table displays both — root cause was that API_DEFAULT_CONCEPTS didn't include them, and the contract-level fallback columns are null for ~1,400 wizard-created contracts.
- Goal
- Surface hiredDemand (Demanda Contratada) and connectedCharge (Carga Conectada) in the public API concepts map by sourcing them per-bill from the recibo's line items (36 → 38 concepts), matching what the app already shows.
- Sub-goals
- SG-1: Add hiredDemand and connectedCharge to API_DEFAULT_CONCEPTS in seed-column-configurations.ts
- SG-2: Update seed comment to document rationale (line-item source vs. unreliable contract columns) and reflect new count (38)
- What
- Added two strings ('hiredDemand', 'connectedCharge') to API_DEFAULT_CONCEPTS readonly array; added a dated comment block explaining the design choice; refreshed the running concept-count note from 36 to 38.
- Why
- Wizard-created contracts (the majority path) leave hired_demand_kw / connected_charge_kw null in utility_contracts — so the contract sub-object fields were silent. Per-bill line items carry the actual values from the CFE recibo and are already the source the app uses; exposing them in the concepts map makes the API consistent with the UI.
- Areas
- packages/database/src/seed-column-configurations.ts+11−1
- Blast
- 1 file, +11/-1; additive seed-data change only — no existing concept renamed or removed, no route/param/contract changes.
Findings · 5
conventions2
MCP tool description not updated for new concept keys
packages/mcp-server/src/index.ts
batu_list_bills describes concepts as "consumption kWh, demand kW, amounts MXN" — omitting hiredDemand (Demanda Contratada) and connectedCharge (Carga Conectada). The mcp-server.md rule requires updating the tool in the SAME change when the public API surface changes. The route params are unchanged, but the tool description is the contract for AI agents; agents will miss these fields. Update the description to mention capacity keys.
Preview/staging re-seed not tracked
packages/database/src/seed-column-configurations.ts
PR description says staging/preview still need db:seed:column-configs. This command is absent from seed-preview.ts (runCatalogSeeds), so previews won't auto-pick-up the new api-config row. Add to the deployment checklist or a Linear follow-up.
tests1
No regression guard on API_DEFAULT_CONCEPTS membership
packages/database/src/seed-column-configurations.ts
No test asserts the array contains hiredDemand/connectedCharge (or has exactly 38 items). Low risk — readonly const + 19 passing mapper tests — but a containment assertion would catch accidental removal in future edits.
improvement2
Dual data sources coexist without explanation
apps/platform/src/api/utils/public-v1-bill-read.ts
The PR fix is correct: concepts.hiredDemand/connectedCharge now source from per-bill line items (reliable). But contract.hired_demand / contract.connected_charge on the response's contract sub-object still source from utility_contracts.hired_demand_kw / connected_charge_kw — the same unreliable wizard-contract columns the fix was designed to avoid. A consumer can see values in concepts but null in contract.hired_demand for the same RPU, with no documentation of why. A follow-up should either document the duality or deprecate/populate the contract sub-object fields from the enrichment fix.
OpenAPI example omits new concept keys
apps/platform/src/app/api/v1/openapi.json/route.ts
EXAMPLE_CONCEPTS doesn't include hiredDemand or connectedCharge. The spec is not wrong, but the example undersells the field to API consumers. Minor — add the two keys to EXAMPLE_CONCEPTS for discoverability.