motovaultpro/backend/src/features/maintenance

Maintenance Feature Capsule

Quick Summary

Tracks vehicle maintenance including routine service, repairs, and performance upgrades. Supports multiple subtypes per record, recurring schedules, and upcoming/overdue calculations. User-scoped data with vehicle ownership enforcement.

API Endpoints

Maintenance Records

• POST /api/maintenance/records - Create a new maintenance record
• GET /api/maintenance/records - List all records (optional filters: vehicleId, category)
• GET /api/maintenance/records/:id - Get single record by ID
• GET /api/maintenance/records/vehicle/:vehicleId - Get all records for a vehicle
• PUT /api/maintenance/records/:id - Update existing record
• DELETE /api/maintenance/records/:id - Delete record

Maintenance Schedules

• POST /api/maintenance/schedules - Create recurring schedule
• GET /api/maintenance/schedules/vehicle/:vehicleId - Get schedules for a vehicle
• PUT /api/maintenance/schedules/:id - Update schedule
• DELETE /api/maintenance/schedules/:id - Delete schedule

Utilities

• GET /api/maintenance/upcoming/:vehicleId - Get upcoming/overdue maintenance (optional query: currentMileage)
• GET /api/maintenance/subtypes/:category - Get valid subtypes for a category

Structure

• api/ - HTTP endpoints, routes, validators
• domain/ - Business logic, types, rules
• data/ - Repository, database queries
• migrations/ - Feature-specific schema
• tests/ - All feature tests

Categories and Subtypes

Routine Maintenance (27 subtypes)

Accelerator Pedal, Air Filter Element, Brakes and Traction Control, Cabin Air Filter / Purifier, Coolant, Doors, Drive Belt, Engine Oil, Evaporative Emissions System, Exhaust System, Fluid - A/T, Fluid - Differential, Fluid - M/T, Fluid Filter - A/T, Fluids, Fuel Delivery and Air Induction, Hood Shock / Support, Neutral Safety Switch, Parking Brake System, Restraints and Safety Systems, Shift Interlock A/T, Spark Plug, Steering and Suspension, Tires, Trunk / Liftgate Shock / Support, Washer Fluid, Wiper Blade

Repair (5 subtypes)

Engine, Transmission, Drivetrain, Exterior, Interior

Performance Upgrade (5 subtypes)

Engine, Drivetrain, Suspension, Wheels/Tires, Exterior

Dependencies

Internal

• core/auth - Authentication plugin
• core/logging - Structured logging
• core/config - Database pool

Database

• Tables: maintenance_records, maintenance_schedules
• FK: vehicles(id) - CASCADE DELETE

Business Rules

Validation

1. Category must be: routine_maintenance, repair, or performance_upgrade
2. Subtypes array must be non-empty
3. All subtypes must be valid for the selected category
4. Date required for records
5. Vehicle must belong to user (ownership check)
6. At least one interval (months OR miles OR both) required for schedules

Next Due Calculation

If interval_months AND interval_miles both set, due when EITHER condition is met (whichever comes first). If only one interval set, calculate based on that single criterion.

Due Soon / Overdue Logic

Due Soon: next_due_date within 30 days OR next_due_mileage within 500 miles Overdue: next_due_date in the past OR next_due_mileage < current odometer

Security Requirements

1. All queries user-scoped (filter by user_id)
2. Vehicle ownership validated before operations
3. Prepared statements (never concatenate SQL)
4. All routes require JWT authentication
5. Users can only access their own data

Testing

# Run feature tests
npm test -- features/maintenance