# Ownership Costs Feature

Tracks vehicle ownership costs including insurance, registration, tax, inspection, parking, and other costs.

## Database Schema

```sql
ownership_costs (
  id UUID PRIMARY KEY,
  user_id VARCHAR(255) NOT NULL,
  vehicle_id UUID NOT NULL REFERENCES vehicles(id) ON DELETE CASCADE,
  document_id UUID NULL REFERENCES documents(id) ON DELETE CASCADE,
  cost_type VARCHAR(32) NOT NULL CHECK (cost_type IN ('insurance', 'registration', 'tax', 'inspection', 'parking', 'other')),
  amount DECIMAL(10, 2) NOT NULL CHECK (amount > 0),
  description VARCHAR(200),
  period_start DATE,
  period_end DATE,
  notes TEXT,
  created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
)
```

## API Endpoints

### POST /ownership-costs
Create a new ownership cost record.

**Auth**: Required (JWT)

**Request Body**:
```json
{
  "vehicleId": "uuid",
  "documentId": "uuid (optional)",
  "costType": "insurance | registration | tax | inspection | parking | other",
  "amount": 150.00,
  "description": "Auto insurance premium (optional)",
  "periodStart": "2024-01-01 (optional)",
  "periodEnd": "2024-12-31 (optional)",
  "notes": "Additional notes (optional)"
}
```

**Response**: 201 Created
```json
{
  "id": "uuid",
  "userId": "string",
  "vehicleId": "uuid",
  "documentId": "uuid",
  "costType": "insurance",
  "amount": 150.00,
  "description": "Auto insurance premium",
  "periodStart": "2024-01-01",
  "periodEnd": "2024-12-31",
  "notes": "Additional notes",
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T00:00:00.000Z"
}
```

### GET /ownership-costs
List all ownership costs for the authenticated user.

**Auth**: Required (JWT)

**Query Parameters**:
- `vehicleId` (optional): Filter by vehicle UUID
- `costType` (optional): Filter by cost type
- `documentId` (optional): Filter by document UUID

**Response**: 200 OK
```json
[
  {
    "id": "uuid",
    "userId": "string",
    "vehicleId": "uuid",
    "costType": "insurance",
    "amount": 150.00,
    "description": "Auto insurance premium",
    "periodStart": "2024-01-01",
    "periodEnd": "2024-12-31",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z"
  }
]
```

### GET /ownership-costs/:id
Get a specific ownership cost record.

**Auth**: Required (JWT)

**Response**: 200 OK (same as POST response)

**Errors**:
- 404 Not Found: Cost not found or not owned by user

### PUT /ownership-costs/:id
Update an ownership cost record.

**Auth**: Required (JWT)

**Request Body**: (all fields optional)
```json
{
  "documentId": "uuid",
  "costType": "insurance",
  "amount": 160.00,
  "description": "Updated description",
  "periodStart": "2024-01-01",
  "periodEnd": "2024-12-31",
  "notes": "Updated notes"
}
```

**Response**: 200 OK (same as POST response)

**Errors**:
- 404 Not Found: Cost not found or not owned by user

### DELETE /ownership-costs/:id
Delete an ownership cost record.

**Auth**: Required (JWT)

**Response**: 204 No Content

**Errors**:
- 404 Not Found: Cost not found or not owned by user

## Cost Types

| Type | Description |
|------|-------------|
| insurance | Auto insurance premiums |
| registration | Vehicle registration fees |
| tax | Property or excise taxes |
| inspection | State inspection fees |
| parking | Parking permits, monthly fees |
| other | Other ownership costs |

## Authorization

All endpoints enforce user scoping - users can only access their own ownership cost records. Vehicle ownership is verified before creating records.

## Integration with Other Features

- **Documents**: Optional document_id links costs to supporting documents
- **Vehicles**: vehicle_id foreign key with CASCADE delete
- **TCO Calculation**: Service provides `getVehicleOwnershipCosts()` for total cost of ownership aggregation
