# 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.