car-tracker/executions/phase004.md

Phase 004 Execution

Scope

• Added fuel and maintenance event creation from the vehicle detail page.
• Added nested event routes and focused create controllers.
• Added odometer update behavior for fuel and maintenance entries.
• Added placeholder event attribution until Phase 005 authentication exists.
• Added request and model specs for the new behavior.

Changes

• Added nested fuel_entries#create and maintenance_entries#create routes under vehicles.
• Added FuelEntriesController for creating fuel entries from a vehicle page.
• Added MaintenanceEntriesController for creating maintenance entries from a vehicle page.
• Added a private unknown_user controller helper that looks up unknown@example.invalid.
• Added an idempotent Unknown User seed in db/seeds.rb for temporary Phase 004 attribution.
• Updated vehicles#show setup to build form objects and eager-load event users.
• Added fuel and maintenance forms to vehicles#show.
• Added inline validation error display for both event forms.
• Added maintenance type selection from the vehicle's existing maintenance schedules.
• Disabled maintenance entry creation in the UI when a vehicle has no maintenance schedules.
• Added Updated by columns to fuel and maintenance history tables.
• Added fuel-entry validation rejecting odometer readings lower than the vehicle current odometer.
• Added vehicle odometer updates when saved fuel or maintenance entries have newer odometer readings.
• Added a Stimulus controller that warns when a maintenance odometer is more than 500 miles behind the current vehicle odometer.
• Added server-side flash warning and application log warning for maintenance entries more than 500 miles behind the current vehicle odometer.
• Hardened temporary Unknown User attribution so event creation creates the placeholder if the seed has not been run.
• Added a user-visible warning path for attribution setup failures instead of raising a server error.

Decisions

• Phase 004 uses Unknown User for event attribution because Phase 005 will add actual authentication and session identity.
• Unknown User is seeded instead of silently created by controllers so missing setup is visible.
• Controllers also create Unknown User as a runtime fallback because a missing seed should not produce a 404/server error for users.
• Fuel entries below the current vehicle odometer are rejected.
• Maintenance entries below the current vehicle odometer are allowed because paperwork may be entered later.
• Maintenance entries update the vehicle odometer only when their odometer is newer.
• Maintenance entry names must match an existing maintenance schedule for the vehicle.
• Client-side maintenance odometer warnings are advisory only; server-side logging is the durable audit trail.

Phase 005 Follow-Up

• Replace Unknown User attribution with the authenticated/current session user.
• Remove or stop using the temporary Unknown User seed once all event creation requires an identified user.

Verification

• Passed: bundle exec rspec spec/models/fuel_entry_spec.rb spec/requests/vehicles_spec.rb
• Passed: bundle exec rspec
• Passed: bin/rubocop app/controllers/application_controller.rb app/controllers/vehicles_controller.rb app/controllers/fuel_entries_controller.rb app/controllers/maintenance_entries_controller.rb app/models/fuel_entry.rb spec/models/fuel_entry_spec.rb spec/requests/vehicles_spec.rb db/seeds.rb
• Passed after attribution hardening: bundle exec rspec spec/requests/vehicles_spec.rb
• Passed after attribution hardening: bundle exec rspec
• Passed after attribution hardening: bin/rubocop app/controllers/application_controller.rb app/controllers/fuel_entries_controller.rb app/controllers/maintenance_entries_controller.rb spec/requests/vehicles_spec.rb