[HARD][FLEET] Build vehicle compliance, maintenance, insurance, and downtime workflow

[Obiajulu-gif]

Overview

Expand the vehicle domain into an operational lifecycle system for compliance documents, inspections, maintenance, insurance, incidents, downtime, and return-to-service approval.

Problem

The current vehicle model stores basic specifications and a broad status. A mobility-finance platform must know whether an asset is legally and operationally fit, why it is unavailable, how downtime affects a driver contract, and which documents or maintenance actions are overdue.

Scope

• Add normalized records for vehicle documents, inspections, insurance policies, maintenance work orders, incidents, odometer readings, expenses, and downtime periods.
• Define expiry/reminder rules for insurance, roadworthiness, permits, and inspections.
• Implement maintenance lifecycle states: reported, triaged, approved, scheduled, in progress, completed, verified, cancelled.
• Restrict vehicle status transitions based on unresolved critical issues or expired compliance.
• Record vendor, cost estimate, final cost, evidence, approver, and service history.
• Track downtime start/end and reason; expose its effect on repayment/contract policy without silently changing financial terms.
• Add return-to-service checklist and authorized approval.
• Add APIs and focused admin/driver UI needed to create, review, and close records.
• Provide migration defaults for existing vehicles.

Integrity requirements

• VIN/identifier uniqueness must remain enforced.
• A vehicle with critical unresolved inspection failure cannot become available/active.
• Expired documents produce clear compliance state, not destructive status changes.
• Maintenance cost adjustments require audit history.
• Driver-visible data must exclude private vendor/admin notes.

Test requirements

• document expiry calculations
• overlapping insurance policies and downtime periods
• invalid return-to-service attempt
• maintenance state transitions and authorization
• incident linked to active driver/contract snapshot
• migration of legacy vehicles
• timezone/date boundary cases

Acceptance criteria

• Vehicle operational and compliance records are normalized and queryable.
• Expiry and overdue status are calculated consistently.
• Critical issues block unsafe activation.
• Maintenance and return-to-service follow guarded workflows.
• Downtime is measured and linked to the relevant asset/contract period.
• Driver and admin responses expose only appropriate fields.
• Tests, migration, documentation, lint, typecheck, and build pass.

Difficulty

Hard

[Owolabenjade]

Hey maintainer, I want to work on this

[grantfox-oss]

🦊 GrantFox — @Owolabenjade has been assigned to this issue as part of the Official Campaign | FWC26 campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #105)
2. Your PR will be reviewed by the Chainmove maintainers

Good luck! Track your progress on GrantFox.