Problem¶
One table (factors) reaches form selects through seven delivery
mechanisms (full exploration 2026-08-26, follow-up 5 of #2360):
GET factors/{det}/class-subclass-map?year=— names only; factors store (in-flight dedup since #2383).GET factors/{det}/list?year=— every row with all coefficients; one consumer bypasses the store entirely (PlannerResearchFacilityRows.vue); route missing from the committedopenapi.d.ts.GET taxonomies/…— the batch routemodule/{module}/data-entries(cached +Cache-Controlsince #2280) plus 3 single-shot routes with zero frontend callers (module_type/{x},data_entry_type/{x},module/{x}); nodes still shipped coefficients, and thetranslation_keymachinery was dead (never populated, echoed the code back).- Hardcoded
options:arrays — ~4k lines underfrontend/src/constant/module-config/duplicating backend enums/CSVs. The hand-mirroredenumSubmodule(constant/modules.ts) has already drifted: missingbuilding_embodied_energy = 32. - Static i18n label tables — including 2.2 MB / 89k-line
i18n/purchase_factors.tslabeling the same UNSPSC codes path 1 delivers. The DB's own description column (purchase_institutional_descriptionin the CSV) is never ingested. building_roomsside table — its options override path 1's Buildings subkind; one Buildings form mixes three mechanisms.- Misc singles (locations typeahead, exchange rates, headcount members).
Since #2385 the explore page defers all of this to first module expansion, so the target metric is per-expansion latency and total payload, no longer a mount stampede.
Lifecycle invariant (settled 2026-08-26)¶
Operators prepare a year in the backoffice: upload factor CSVs, possibly
several times, before the year is opened to users. Once a year is
started, its factors never change. So per-(data_entry_type, year) data is
mutable during preparation and immutable after — which is what lets decision
2's cache TTL and ETag be aggressive.
Decisions¶
- The batch taxonomy endpoint becomes THE lookup endpoint.
GET taxonomies/module/{module}/data-entries?entries=…&year=(#2280) already has the right shape, the server-side(det, year)cache, write-time invalidation inFactorRepository, cross-pod broadcast, andCache-Control. Evolve it: strip coefficients, carry labels, and retireclass-subclass-map+/listas frontend-facing routes once every consumer reads from it. - Cache per the lifecycle invariant. The 60 s TTL was sized as the
cross-process staleness bound before the broadcast existed; with exact
cross-pod invalidation in place, raise the server TTL substantially and
add an
ETag(derived from the cache entry / last ingestion) so browsers revalidate cheaply. A started year is immutable — its responses can carry a longmax-age. - Strip coefficients from bulk payloads. The only verified client
consumer of coefficient values is the equipment form/table prefill
(
active_power_w/standby_power_w) via the narrowGET factors/{det}/classes/{kind}/values?year=(api/factors.ts:48,ModuleForm.vue:713,ModuleTable.vue:639) — kept as-is. All math stays server-side; raw emission factors stop being shipped to every authenticated user. - Purchase moves to server-side search: typeahead endpoint (shape of
locations/search), 10–100 entries per response. Ingestpurchase_institutional_descriptionfrom the CSV as the label so the DB is authoritative; delete the 2.2 MBi18n/purchase_factors.ts. - Delete dead code: the 3 uncalled taxonomy routes, the
translation_keymachinery, the exported-but-uncalledgetModuleTaxonomy(stores/modules.ts), and the stale/listgap in the openapi snapshot. - Generate the hand-mirrored constants from backend enums following the
emission-taxonomy.gen.tsprecedent (make gen-emission-taxonomy):enumSubmodule, room types, cabin classes, currencies, SIUS categories. - One frontend discipline: a single lookup store with in-flight promise
dedup (pattern of #2378/#2383) fed only by the taxonomy endpoint; no
component calls
api.getfor lookups directly.use_unit, the one row fieldPlannerResearchFacilityRowsneeded offfactors/{det}/list, now travels on the taxonomy node as declared display metadata (decision 1).
Open points for the plan¶
- ~~Where
building_roomsfits~~ — settled 2026-08-26: stays a side table (genuinely different, year-less data); documented as the one legitimate exception to the unified lookup path. - ~~ETag derivation~~ — settled with decision 2: content hash of the built tree (no ingestion-timestamp column exists to use instead).
- ~~Purchase label i18n schema~~ — settled 2026-08-31: proposition 2
(translation table),
classification_translations(field_name, value, lang) -> label. Delivered generically (any handler'sclassification_fields) against equipment first, perdocs/src/implementation-plans/2401-purchase-label-i18n.md. Purchase's own side (kind_label_field = purchase_institutional_description, the_fringestion column, row-level labels) shipped on the same branch — decision 4 built directly on it. - Exact per-module migration order (equipment last — it carries the values-prefill edge case).
Delivery checklist¶
- Decision 3 — strip coefficients from
TaxonomyNode(classification/valuesdropped from the schema and the tree builder). All four frontend consumers (ModuleForm.vue,ModuleInlineSelect.vue,ModuleTable.vue,PrintModuleTable.vue) only ever readname/label/translation_key/childrenoff a taxonomy node — verified with a repo-wide grep, no whitelist needed.PlannerResearchFacilityRows.vue'suse_unitread is offfactors/{det}/list, not the taxonomy tree, so it's untouched here (see decision 7). Delivered by PR #2396. - Decision 5, partial — deleted the 3 uncalled taxonomy routes
(
module_type/{x},data_entry_type/{x},module/{x}) and the uncalledgetModuleTaxonomystore action. Two items deferred: thetranslation_keymachinery is not removed — its only non-trivial source (values.get("translation_key")) is dead, so the field is now structurally identical toname, but four Vue components still branch on it and untangling that wants its own change + CT test rather than riding along here; the "stale/listgap in the openapi snapshot" item was already fixed by other work merged todevearlier the same day (2026-08-26) — verified present in both the pre- and post-regen snapshot, not something this PR did. Delivered by PR #2396. - Decision 7 (remainder) —
PlannerResearchFacilityRows.vuereads the taxonomy tree through the factors store; no component callsapi.getfor lookup data any more. Delivered with decision 1. - Decision 1 — the taxonomy endpoint is the single lookup endpoint;
factors/{det}/class-subclass-mapandfactors/{det}/listare deleted (GET factors/{det}/classes/{kind}/values, the equipment prefill, stays). Detailed below. - Decision 2 — server TTL raised 60s → 3600s (the cross-pod broadcast
is now the correctness mechanism; the TTL is only a backstop for what
it doesn't reach). ETag is a content hash of the built tree
(
factorscarries no updated-at column to use as an ingestion marker), computed once at build time and cached alongside the tree so every pod emits the identical ETag with zero extra queries; the batch route combines per-entry ETags deterministically (sorted, so query order doesn't matter) and both routes answerIf-None-Matchwith an empty 304 before serializing.Cache-Controlnow splits on the year lifecycle:max-age=86400once a year is started (its factors never change again),max-age=60while still in preparation — a short, cachedis_year_startedlookup decides which, defaulting to not-started (short max-age) when no year-configuration row exists. Delivered by PR #. - Decision 4 — purchase server-side typeahead. Delivered by PR
#2583 (riding the #2401 branch, which had already shipped the two
prerequisites:
purchase_institutional_descriptioningestion +kind_label_field, and thei18n/purchase_factors.tsdeletion). NewGET taxonomies/module/{module}/{data_entry}/options— the shape oflocations/search:querymin 2 chars,limit≤ 100, relevance ordering exact → starts-with → contains; matches the stored value, the English label text, and its translated label (#2401 table), labels resolving translated → English → bare code. Generic over both handler shapes, not purchase-only. Frontend: anoptionsSearchmodule-config flag (set onpurchase_institutional_codeonly) routes the form select toServerSearchSelectField(per-keystroke search, min-2 guard, edit-mode option seeded from the row's backendlabels), the form's taxonomy fetch is skipped (skipClassOptions), andModuleTablestops fetching the tree foroptionsSearchsubmodules — purchase pages no longer download the ~17k-node tree anywhere.purchases_centralized(tiny factor set) and every other module stay on the taxonomy path. - Decision 6 — generate
enumSubmodule, room types, cabin classes, currencies, SIUS categories from backend enums (make gen-module-constants, newfrontend/src/types/module-lookups.gen.ts). ConfirmedenumSubmoduledrift (building_embodied_energy = 32) was behavior-safe to add — every consumer does a keyed lookup, none iterates the object.external-cloud-and-ai.ts's 3-currency subset (eur/chf/usd, vs. the full 9-currency backend set) is left hand-written: it isn't a mirror of a backend constant, and widening it would be an unreviewed behavior change. Delivered by PR #2400.
Decision 1 — the two handler-declared mechanisms¶
Labels were already there: kind_label_field / subkind_label_field on
BaseModuleHandler, set to researchfacility_name on both research-facility
handlers since #2007. The issue text called for a new label_field; it would
have been a second name for a solved problem, so nothing was added.
Display metadata is new: taxonomy_meta_fields: tuple[str, ...] (default
empty) copies whitelisted classification/values fields onto a new optional
TaxonomyNode.meta. Research facilities declare ("use_unit",). Both
node-construction sites in ModuleHandlerService.get_taxonomy populate it, so
a subkind node carries its own row's metadata — an animal facility meters
rodents in housings and fish in tanks. Display only: ef_* and power
coefficients stay server-side (#2396), and meta defaults to None so
response_model_exclude_none leaves every other module's payload byte-for-byte
as it was.
Frontend: the factors store caches the taxonomy tree per (submodule, year) —
same TTL and in-flight dedup as before — and derives class options, subclass
options and the planner's facility rows from it. One consequence worth naming:
a form's options and the taxonomy relabel can no longer disagree, which is
exactly what the #2007 bug was.
Decision 4 set kind_label_field = purchase_institutional_description for
purchase (shipped with the #2401 ingestion on the same branch). The one
decision-5 leftover — untangling the translation_key branches in the four
Vue components — remains parked as its own change (#2396 reasoning), now
easier since equipment_factors.ts/purchase_factors.ts are deleted.