# 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

```bash
# Run feature tests
npm test -- features/maintenance
```
