72 lines
3.3 KiB
Markdown
72 lines
3.3 KiB
Markdown
# 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.
|
||
|