diff --git a/backend/src/features/vehicles/README.md b/backend/src/features/vehicles/README.md index 24e4a80..f8ce50d 100644 --- a/backend/src/features/vehicles/README.md +++ b/backend/src/features/vehicles/README.md @@ -12,6 +12,9 @@ Primary entity for vehicle management consuming MVP Platform Vehicles Service. H - `PUT /api/vehicles/:id` - Update vehicle details - `DELETE /api/vehicles/:id` - Soft delete vehicle +### VIN Decoding (Pro/Enterprise Only) +- `POST /api/vehicles/decode-vin` - Decode VIN using NHTSA vPIC API + ### Hierarchical Vehicle Dropdowns **Status**: Vehicles service now proxies the platform vehicle catalog to provide fully dynamic dropdowns. Each selection step filters the next list, ensuring only valid combinations are shown. @@ -100,6 +103,12 @@ vehicles/ │ └── name-normalizer.ts ├── data/ # Database layer │ └── vehicles.repository.ts +├── external/ # External service integrations +│ ├── CLAUDE.md # Integration pattern docs +│ └── nhtsa/ # NHTSA vPIC API client +│ ├── nhtsa.client.ts +│ ├── nhtsa.types.ts +│ └── index.ts ├── migrations/ # Feature schema │ └── 001_create_vehicles_tables.sql ├── tests/ # All tests @@ -112,11 +121,45 @@ vehicles/ ## Key Features -### 🔍 Automatic VIN Decoding -- **Platform Service**: MVP Platform Vehicles Service VIN decode endpoint -- **Caching**: Platform service handles caching strategy -- **Fallback**: Circuit breaker pattern with graceful degradation -- **Validation**: 17-character VIN format validation +### 🔍 VIN Decoding (NHTSA vPIC API) +- **Tier Gating**: Pro and Enterprise users only (`vehicle.vinDecode` feature key) +- **NHTSA API**: Calls official NHTSA vPIC API for authoritative vehicle data +- **Caching**: Results cached in `vin_cache` table (1-year TTL, VIN data is static) +- **Validation**: 17-character VIN format, excludes I/O/Q characters +- **Matching**: Case-insensitive exact match against dropdown options +- **Confidence Levels**: High (exact match), Medium (normalized match), None (hint only) +- **Timeout**: 5-second timeout for NHTSA API calls + +#### Decode VIN Request +```json +POST /api/vehicles/decode-vin +Authorization: Bearer +{ + "vin": "1HGBH41JXMN109186" +} + +Response (200): +{ + "year": { "value": 2021, "nhtsaValue": "2021", "confidence": "high" }, + "make": { "value": "Honda", "nhtsaValue": "HONDA", "confidence": "high" }, + "model": { "value": "Civic", "nhtsaValue": "Civic", "confidence": "high" }, + "trimLevel": { "value": "EX", "nhtsaValue": "EX", "confidence": "high" }, + "engine": { "value": null, "nhtsaValue": "2.0L L4 DOHC 16V", "confidence": "none" }, + "transmission": { "value": null, "nhtsaValue": "CVT", "confidence": "none" }, + "bodyType": { "value": null, "nhtsaValue": "Sedan", "confidence": "none" }, + "driveType": { "value": null, "nhtsaValue": "FWD", "confidence": "none" }, + "fuelType": { "value": null, "nhtsaValue": "Gasoline", "confidence": "none" } +} + +Error (400 - Invalid VIN): +{ "error": "INVALID_VIN", "message": "Invalid VIN format. VIN must be..." } + +Error (403 - Tier Required): +{ "error": "TIER_REQUIRED", "requiredTier": "pro", "currentTier": "free", ... } + +Error (502 - NHTSA Failure): +{ "error": "VIN_DECODE_FAILED", "message": "Unable to decode VIN from external service" } +``` ### 📋 Hierarchical Vehicle Dropdowns - **Platform Service**: Consumes year-based hierarchical vehicle API