motovaultpro/docs/changes/vehicle-names-v1/CODEX.md

Vehicle Names v1 – Model/Make Normalization

Change set to normalize human-facing vehicle make and model names across the application service. Addresses cases like:

• GMC sierra_1500 → GMC Sierra 1500
• GMC sierra_2500_hd → GMC Sierra 2500 HD

Scope

• Application service database (vehicles, vin_cache tables).
• Backend write paths for vehicle creation and update.
• Non-breaking; affects presentation format only.

Rationale

Source values may contain underscores, inconsistent casing, or unnormalized acronyms. We enforce consistent, human-friendly formatting at write time and backfill existing rows.

Changes

• Add normalization utility

  • File: backend/src/features/vehicles/domain/name-normalizer.ts
  • normalizeModelName(input): replaces underscores, collapses whitespace, title-cases words, uppercases common acronyms (HD, GT, Z06, etc.).
  • normalizeMakeName(input): trims/title-cases, with special cases for BMW, GMC, MINI, McLaren.

• Apply normalization in service layer

  • File: backend/src/features/vehicles/domain/vehicles.service.ts
  • Create flow: normalizes VIN-decoded and client-supplied make/model prior to persistence.
  • Update flow: normalizes any provided make/model fields before update.

• Backfill migration for existing rows

  • File: backend/src/features/vehicles/migrations/004_normalize_model_names.sql
  • Adds normalize_model_name_app(text) in the DB and updates vehicles.model and vin_cache.model in-place.

Migration

Run inside containers:

make migrate

What it does:

• Creates normalize_model_name_app(text) (immutable function) for consistent DB-side normalization.
• Updates existing rows in vehicles and vin_cache where model is not normalized.

Acronym Handling (Models)

Uppercased when matched as tokens:

• HD, GT, GL, SE, LE, XLE, RS, SVT, XR, ST, FX4, TRD, ZR1, Z06, GTI, GLI, SI, SS, LT, LTZ, RT, SRT, SR, SR5, XSE, SEL
• Mixed alphanumeric short tokens (e.g., z06) are uppercased.

Make Special Cases

• BMW, GMC, MINI fully uppercased; McLaren with proper casing.
• Otherwise, standard title case across words.

Verification

1. After migration, sample queries (inside make shell-backend):

psql -U postgres -d motovaultpro -c "SELECT make, model FROM vehicles ORDER BY updated_at DESC LIMIT 10;"

Confirm: no underscores; title case with acronyms uppercased.

2. Create/update tests (app flow):

• Create a vehicle with model = 'sierra_2500_hd' → persisted as Sierra 2500 HD.
• VIN-decode flow returns sierra_1500 → stored as Sierra 1500.

Rollback

• Code: revert the three files noted above.
• Data: no automatic downgrade (idempotent forward normalization). If critical, restore from backup or reapply custom transformations.

Compatibility & Notes

• Read paths unchanged; only write-time and migration normalization applied.
• Case-insensitive indexes are already present; behavior remains consistent.
• Extend acronym lists or special cases easily by editing name-normalizer.ts and the migration function if needed for backfills.

Next Steps (Optional)

• Add unit tests for name-normalizer.ts in backend/src/features/vehicles/tests/unit/.
• Expose a one-off admin endpoint or script to re-run normalization for targeted rows if future sources change.