@bytebrand/fe-ui-core-autobahn 1.0.0

package/data/fieldMapping.ts

@@ -0,0 +1,342 @@
+// Autobahn (auto.de redesign) — AutobahnCar field-mapping table (AB-P0-6).
+//
+// PM deliverable. Documents, for EVERY field of the AutobahnCar view-model
+// (components/autobahn/cards/types.ts), exactly where its value comes from on
+// the real fe-main "store car" (the transformDataForVehicles output that
+// SearchResultsStore.getCarsForPage returns to the SRP) — or marks it
+// 'needs-data' when there is no real source yet.
+//
+// This is the machine-readable companion to the "Data mapping" table in
+// docs/redesign/autobahn-fe-main-plan.md. Each row's `source` is the literal
+// path on the store car (or an injected dep); `confirmedAt` cites the repo
+// file:line where that path / behaviour was verified, so reviewers don't have to
+// take it on trust. It is data-only (no imports) and is consumed by ./toAutobahnCar.ts.
+
+/** Where a field's value originates. */
+export type MappingStatus =
+  | 'wired' // real value taken from the search payload (or a pure derivation of it)
+  | 'wired-dep' // real value, but supplied through an injected dependency (images / translator)
+  | 'wired-optional' // real value emitted ONLY when present on the payload; else left undefined
+  | 'needs-data'; // NO real source on the search payload — left undefined; card shows 'Daten folgt'
+
+export interface FieldMapping {
+  /** AutobahnCar field name. */
+  field: keyof import('../cards/types').AutobahnCar;
+  /** REQUIRED on the type (always-real) vs OPTIONAL (`?`, may be needs-data). */
+  required: boolean;
+  status: MappingStatus;
+  /** literal source path on the store car, or the injected dep, or '—'. */
+  source: string;
+  /** transform applied by toAutobahnCar (formatting / mapping), if any. */
+  transform?: string;
+  /** repo file:line that confirms the source path / behaviour. */
+  confirmedAt?: string;
+  /** extra rationale, esp. for rating / monthly / images / needs-data. */
+  notes?: string;
+}
+
+/**
+ * The store car (transformDataForVehicles output) — key paths the mapper reads.
+ * Confirmed in services/fe-main/source/framework/DataTransformers.ts:285-374.
+ */
+export const FIELD_MAPPINGS: readonly FieldMapping[] = [
+  // ---------------------------------------------------------------- identity
+  {
+    field: 'make',
+    required: true,
+    status: 'wired',
+    source: 'title.make',
+    confirmedAt: 'DataTransformers.ts:295',
+    notes: 'mainData.make, capitalized upstream by normalizeRateObject.',
+  },
+  {
+    field: 'model',
+    required: true,
+    status: 'wired',
+    source: 'title.model',
+    confirmedAt: 'DataTransformers.ts:296',
+  },
+  {
+    field: 'trim',
+    required: true,
+    status: 'wired',
+    source: 'title.subModel',
+    confirmedAt: 'DataTransformers.ts:297',
+    notes: "Mapped to the design's `trim` (sub-model / variant line).",
+  },
+
+  // --------------------------------------------------------------- key specs
+  {
+    field: 'km',
+    required: true,
+    status: 'wired',
+    source: 'info.mileage',
+    transform: 'number passthrough (cards format de-DE via fmtKm)',
+    confirmedAt: 'DataTransformers.ts:304',
+  },
+  {
+    field: 'reg',
+    required: true,
+    status: 'wired',
+    source: 'info.regDate',
+    transform: "formatTimestamp({ timestamp, format: 'MM/YYYY' }) → 'EZ' shown by card",
+    confirmedAt:
+      'DataTransformers.ts:303 (regDate=mainData.firstRegistration, unix s) · decoratedLightProps.tsx:66 (same MM/YYYY format on legacy card)',
+    notes: 'firstRegistration is a Unix timestamp in seconds.',
+  },
+  {
+    field: 'power',
+    required: true,
+    status: 'wired',
+    source: 'engineData.powerKW + engineData.powerPS',
+    transform: "getPowerLabel(kW, PS) → '150 kW (204 PS)'",
+    confirmedAt:
+      'DataTransformers.ts:326-328 · fe-ui-core getPowerLabel decoratedProps.tsx:44 · de template vehicleProps.json value.power "{{powerKW}} kW ({{powerPS}} PS)"',
+  },
+  {
+    field: 'fuel',
+    required: true,
+    status: 'wired-dep',
+    source: 'consumption.fuel',
+    transform: "cbd:* selector code → label via injected t (e.g. 'Benzin'); de fallback if no t",
+    confirmedAt:
+      'DataTransformers.ts:318 · cbd.ts:170-177 (selector_fuel_* → German labels)',
+    notes:
+      'Stored as a selector code (e.g. selector_fuel_petrol). Card shortens long labels itself (cardParts FUEL_SHORT).',
+  },
+  {
+    field: 'gear',
+    required: true,
+    status: 'wired-dep',
+    source: 'info.gearbox',
+    transform: "cbd:* selector code → label via injected t (e.g. 'Automatik'); de fallback if no t",
+    confirmedAt: 'DataTransformers.ts:305 · cbd.ts:227-229 (selector_gearbox_* → German labels)',
+  },
+  {
+    field: 'owners',
+    required: true,
+    status: 'wired',
+    source: 'info.numberOfPreviousOwners',
+    transform: "number passthrough (card renders 'N. Hand'); 0 when 'N/A'",
+    confirmedAt: 'DataTransformers.ts:306',
+    notes: "Default 'N/A' upstream → coerced to 0 (non-finite) by the mapper.",
+  },
+
+  // ------------------------------------------------------------------- price
+  {
+    field: 'monthly',
+    required: true,
+    status: 'wired',
+    source: 'price.financing.monthlyInstallment',
+    transform: 'number passthrough (LEAD price); 0 if absent',
+    confirmedAt:
+      'getFinancing.ts:82 (monthlyInstallment = monthlyCarPrice + monthlyExtraCost) · getComputedFinancing.ts:11 (financing block) · DataTransformers.ts:345 (spread into price.financing)',
+    notes:
+      'This is the FinancingStore-computed financing rate, NOT a hand-rolled annuity. transformDataForVehicles runs getComputedFinancing over the merged search/user config, so the value is present on the store car the SRP already consumes.',
+  },
+  {
+    field: 'price',
+    required: true,
+    status: 'wired',
+    source: 'price.currentSalesPrice',
+    transform: 'number passthrough (cards format de-DE)',
+    confirmedAt: 'DataTransformers.ts:352',
+  },
+
+  // ------------------------------------------------------------------- media
+  {
+    field: 'gallery',
+    required: true,
+    status: 'wired-dep',
+    source: 'deps.loadedImages (imagesStore.images.get(id)) ?? deps.getImageUrl(id, mainImageId, size) ?? placeholder',
+    transform: 'pick imageUrlMedium/Large per size; single main-image URL; else one placeholder',
+    confirmedAt:
+      'ImagesStore.ts:149-152 (getSupportedImageFormat → /{id}/{imageId}/{size}-cached.webp|jpeg) · IImage.imageUrlMedium/Large ImagesStore.ts:30-32 · SearchResults.tsx:98 (SRP builds src via getSupportedImageFormat(id, mainImageId, "small"))',
+    notes:
+      'Pure: images arrive via deps. Container injects imagesStore.getSupportedImageFormat as getImageUrl and imagesStore.images.get(id) as loadedImages. Falls back to a single placeholder before images load — never a fabricated photo.',
+  },
+  {
+    field: 'photos',
+    required: true,
+    status: 'wired',
+    source: 'imagesCount',
+    transform: 'number passthrough; 0 if absent',
+    confirmedAt: 'DataTransformers.ts:292 (metaData.imagesCount, default 0)',
+  },
+
+  // ------------------------------------------------- EnVKV (legally required)
+  {
+    field: 'cons',
+    required: true,
+    status: 'wired',
+    source: 'consumption.wltpCombined ?? consumption.consumptionCombined',
+    transform: "→ '<n> l/100 km' (n formatted per language)",
+    confirmedAt:
+      'DataTransformers.ts:319-320 · de template vehicleProps.json value.consumption "{{consumption}}l/100km"',
+    notes: 'WLTP preferred when present, mirroring the legacy decorated consumption line.',
+  },
+  {
+    field: 'co2',
+    required: true,
+    status: 'wired',
+    source: 'environmentEmissions.wltpCo2 ?? environmentEmissions.co2',
+    transform: "→ '<n> g/km'",
+    confirmedAt:
+      'DataTransformers.ts:332-333 · de template vehicleProps.json value.co2Combined "{{co2}}g CO2/km (komb)*"',
+  },
+  {
+    field: 'co2class',
+    required: true,
+    status: 'wired',
+    source: 'environmentEmissions.wltpEnergyEfficiencyClass',
+    transform:
+      "selector_energyEfficiencyClass_* → single letter A..G (A+/A++/A+++ collapse to 'A' so the card color band resolves)",
+    confirmedAt: 'DataTransformers.ts:334 · cbd.ts:156-165 (class codes → A+++..G)',
+    notes:
+      "cardParts.InlineCls does CO2_CLASSES.indexOf(c) over ['A'..'G'], so co2class MUST be a bare letter. '' when the car has no class.",
+  },
+  {
+    field: 'phev',
+    required: false,
+    status: 'wired-optional',
+    source:
+      'consumption.{wltpWeightedPowerCombined,wltpWeightedCombined,wltpCombined,consumptionPowerCombined} + environmentEmissions.{wltpCo2,wltpEnergyEfficiencyClass,wltpDischargedEnergyEfficiencyClass}',
+    transform: 'AutobahnPhev dual-figure block; only when fuel is hybridElectricalDiesel/Petrol AND weighted figures exist',
+    confirmedAt:
+      'DataTransformers.ts:321-324,331-335 · VehicleInfo.tsx:86-87 / decoratedLightProps.tsx:155-156 (PHEV = fuel type, ADV-88) · wltpDischargedEnergyEfficiencyClass referenced decoratedLightProps.tsx:168',
+    notes:
+      'wltpDischargedEnergyEfficiencyClass is read by legacy code but is NOT in the transformDataForVehicles environmentEmissions whitelist (DataTransformers.ts:331-335) — so co2classD usually falls back to the weighted class. FLAGGED: confirm whether the search payload should expose the discharged class.',
+  },
+
+  // --------------------------------------------------------- trust / features
+  {
+    field: 'features',
+    required: true,
+    status: 'needs-data',
+    source: '— (not on the SEARCH payload)',
+    transform: 'always [] from the search mapper',
+    confirmedAt:
+      'DataTransformers.ts:285-374 (no equipment field) · plan data-mapping table: "equipment (grouped) | CarsAPI | wire" is a VDP/CarsAPI source',
+    notes:
+      'Equipment highlights come from CarsAPI on the VDP, not from search results. The CarRow shows no chips on the SRP. NOT fabricated. (Type marks it required, but the real search source is empty — emitted as [].)',
+  },
+  {
+    field: 'rating',
+    required: true,
+    status: 'wired',
+    source: 'price.currentSalesPrice + price.mlCurrentSalesPricePredicted',
+    transform:
+      "getPriceRating(sale, predicted) [0..5] → autobahn tone: 5→'top' 4→'good' 3→'fair' 2→'raised' 1→'high'; 0(noRating)→neutral 'fair'",
+    confirmedAt:
+      'VehicleInfo.tsx:160 (SRP card renders getPriceRating(currentSalesPrice, mlCurrentSalesPricePredicted)) · CommonUtils.ts:353-373 (getPriceRating) · price.ts:1 (priceRatings order) · DataTransformers.ts:354 (mlCurrentSalesPricePredicted)',
+    notes:
+      "REAL Preisbewertung. Card only special-cases tone==='fair' → warn pill; every other tone → good/green pill (CarCard.tsx:96-97). For noRating we pick the NEUTRAL middle tier, never a flattering one. predicted falls back to sale*1.07814 (PREDICTABLE_PRICE_INDEX) inside getPriceRating, exactly like the live card.",
+  },
+  {
+    field: 'ratingLabel',
+    required: true,
+    status: 'wired',
+    source: 'derived from the rating tier',
+    transform: "TIER_LABELS[tier] → 'Top Preis'|'Guter Preis'|'Fairer Preis'|'Erhöht'|'Hoher Preis'",
+    confirmedAt:
+      'autobahn/constants.ts:17 (TIER_LABELS) · fe-ui-core locales/priceRating.ts:2-9 (legacy German labels: TOP/GUTER/FAIRER/ERHÖHTER/HOHER PREIS)',
+    notes:
+      "Autobahn labels condense increasedPrice→'Erhöht' and highPrice→'Hoher Preis' vs the legacy 'ERHÖHTER PREIS'/'HOHER PREIS'.",
+  },
+
+  // ------------------------------------- NEEDS-DATA (never synthesized)
+  {
+    field: 'listPrice',
+    required: false,
+    status: 'wired-optional',
+    source: 'price.financing.highestPrice (only if isStrikeShown && highest > sale)',
+    transform: 'emitted only when a real strike price exists; else undefined',
+    confirmedAt:
+      'getFinancing.ts:75 (highestPrice), :70 (isStrikeShown) → spread into price.financing DataTransformers.ts:345',
+    notes:
+      'FLAGGED: there is no dedicated purchase list/UVP strike on the search payload. highestPrice is the financing "strike" base, gated on isStrikeShown. If product wants a true UVP strike, that is needs-data/backend. Left undefined when no real strike.',
+  },
+  {
+    field: 'savings',
+    required: false,
+    status: 'wired-optional',
+    source: 'listPrice − price.currentSalesPrice (only when listPrice resolved)',
+    transform: 'emitted only alongside a real listPrice; card gates UI at >600 €',
+    confirmedAt: 'CarCard.tsx:36 / cardParts.tsx:94 (showStrike requires savings>600 && listPrice)',
+    notes: 'Same caveat as listPrice — no synthetic savings.',
+  },
+  {
+    field: 'drop',
+    required: false,
+    status: 'needs-data',
+    source: '—',
+    confirmedAt: 'plan data-mapping: "price history sparkline | — | needs data"',
+    notes:
+      'Real per-car price reduction. price.historyPriceDifference exists (DataTransformers.ts:355) but is the financing-config delta, not a confirmed advertised "Preis gesenkt" amount — NOT wired to drop to avoid a misleading reduction chip. Backend phase.',
+  },
+  {
+    field: 'marketLow',
+    required: false,
+    status: 'needs-data',
+    source: '—',
+    confirmedAt: 'plan data-mapping: "market-value band (low/avg/high) | — | needs data"',
+    notes: 'Market band lower bound. No source. PricePaths renders the Marktvergleich "Daten folgt" marker.',
+  },
+  {
+    field: 'marketAvg',
+    required: false,
+    status: 'needs-data',
+    source: '—',
+    confirmedAt: 'plan data-mapping: market-value band → needs data',
+    notes:
+      'NOT mapped from mlCurrentSalesPricePredicted: that ML figure feeds the Preisbewertung, it is not a comparable-market average — using it as the market band would be a fabricated comparison.',
+  },
+  {
+    field: 'marketHigh',
+    required: false,
+    status: 'needs-data',
+    source: '—',
+    confirmedAt: 'plan data-mapping: market-value band → needs data',
+    notes: 'Market band upper bound. No source.',
+  },
+  {
+    field: 'lease',
+    required: false,
+    status: 'wired-optional',
+    source: 'price.leasing.monthlyInstallment',
+    transform: 'emitted only when present',
+    confirmedAt:
+      'getLeasing → leasing.monthlyInstallment (getComputedFinancing.ts:13) · price.leasing spread DataTransformers.ts:348-350 · SearchResultsStore.ts:202 (leasing presence checked on the store car)',
+    notes:
+      'Leasing is not offered/active for every car (SearchResultsStore.getLeasingActive). Left undefined when absent — PricePaths simply omits the leasing row.',
+  },
+  {
+    field: 'watchers',
+    required: false,
+    status: 'needs-data',
+    source: '— (search payload). Possible later: UserActionsAPI stats',
+    confirmedAt:
+      'plan data-mapping: "views / interest | UserActionsAPI stats (verify) | wire if present, else stub" · searchStore.statsData (SearchResultsStore.ts:211-232) is fetched separately, NOT part of the store car',
+    notes:
+      'Buyer-activity count. Not on transformDataForVehicles output. statsData is keyed by carId and loaded async; wiring it is a later SRP task — left undefined so PpActivity shows "Daten folgt".',
+  },
+  {
+    field: 'views',
+    required: false,
+    status: 'needs-data',
+    source: '— (search payload). Possible later: UserActionsAPI stats',
+    confirmedAt: 'as watchers (searchStore.statsData, separate from the store car)',
+    notes: 'Recent-views cue. Same as watchers — not synthesized.',
+  },
+] as const;
+
+/** Quick lookups for tooling / tests. */
+export const NEEDS_DATA_FIELDS: readonly string[] = FIELD_MAPPINGS.filter(
+  (m) => m.status === 'needs-data'
+).map((m) => m.field);
+
+export const WIRED_FIELDS: readonly string[] = FIELD_MAPPINGS.filter(
+  (m) => m.status === 'wired' || m.status === 'wired-dep'
+).map((m) => m.field);
+
+export default FIELD_MAPPINGS;