Initial Commit

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

@@ -0,0 +1,71 @@
+# 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.
+