Fleet module (fleet)

The fleet module in src/cluster_erp/modules/fleet/ manages the vehicles and machines a company operates. One asset master covers cars, vans, trucks, tractor units, trailers, buses, forklifts, and construction machines. Around it the module keeps meters and readings, maintenance plans and reminders, work orders with spare parts, driver assignments, inspections and defects, reservations, incidents, fuel, compliance obligations, penalties, tires, and campaigns. This page is the overview; the sub-topics have their own pages.

At a glance¶

What the module does¶

• Keeps one asset master with first-class identities (plate, VIN, chassis number, engine number) and a lifecycle that starts as a draft (src/cluster_erp/modules/fleet/models.py:159-237).
• Lets the organisation add its own asset fields at runtime through tenant fields; the module seeds a heavy-vehicle starter set (src/cluster_erp/modules/fleet/module.py:197-265). See tenant fields.
• Records counters as an immutable reading ledger with life-to-date values (src/cluster_erp/modules/fleet/meters/services.py:1-18).
• Computes maintenance due dates from calendar, meter, and threshold rules (src/cluster_erp/modules/fleet/maintenance/services.py:1-20).
• Collects every maintenance need on one work order and issues spare parts from inventory through the EventBus (src/cluster_erp/modules/fleet/workorders/services.py:1-18).
• Tracks who holds an asset, tractor and trailer couplings, inspections, defects, reservations, and incidents (src/cluster_erp/modules/fleet/operations/services.py:1-20).
• Keeps a fuel ledger with consumption alerts, compliance obligations with renewal, and penalties (src/cluster_erp/modules/fleet/fuel/services.py:1-20).
• Reports total cost of ownership, a renewal ranking, tires, campaigns, and emission factors (src/cluster_erp/modules/fleet/tco/services.py:1-12).
• Accepts counter batches from telematics adapters (src/cluster_erp/modules/fleet/telematics.py:1-16).

Sub-modules¶

All routers are included in one module router with the prefix /api/v1/fleet (src/cluster_erp/modules/fleet/module.py:267-336). Each routes.py declares its own paths, for example src/cluster_erp/modules/fleet/fuel/routes.py:35-41.

Data model¶

All 23 tables are declared in src/cluster_erp/modules/fleet/models.py. Each sub-module page lists its fields. Common traits:

• Every model inherits the audit and soft-delete columns of BaseModel (src/cluster_erp/modules/fleet/models.py:42). See base model and IDs.
• Uniqueness holds on live rows only, through partial unique indexes such as uq_fleet_assets_plate_live (src/cluster_erp/modules/fleet/models.py:168-186).
• Money columns are Numeric(18, 2) with a separate three-letter currency column, for example FleetWorkOrder.labor_cost and FleetFuelEntry.total_cost (src/cluster_erp/modules/fleet/models.py:409-413, src/cluster_erp/modules/fleet/models.py:621-622).
• Counter values are Numeric with one decimal place (src/cluster_erp/modules/fleet/models.py:298-301).
• Status vocabularies are tuples at the top of the file, for example FLEET_ASSET_STATUSES and FLEET_WO_STATUSES (src/cluster_erp/modules/fleet/models.py:46-127).

Screens and metadata¶

get_metadata declares a sidebar group Fleet (Turkish Filo) with 16 sections (src/cluster_erp/modules/fleet/module.py:403-547). Six sections show on the bar: Assets, Maintenance, Work Orders, Reservations, Fuel, and Compliance. Nine list sections carry hidden_from_bar=True: Penalties, Tires, Campaigns, Renewal Analysis, Assignments, Couplings, Inspections, Defects, and Incidents. The code comment states that these lists stay searchable and that the asset card is their contextual door (src/cluster_erp/modules/fleet/module.py:490-492). Settings is a settings view with four tabs: asset classes, maintenance plans, inspection periods, and emission factors (src/cluster_erp/modules/fleet/module.py:536-547).

The asset card has 14 detail tabs, from Overview to Tires (src/cluster_erp/modules/fleet/assets/metadata.py:358-450). The web app and the desktop render all of this generically; see generic list and generic detail.

Status and actions¶

Each sub-module page lists its actions. Every status change runs through an action route POST .../{id}/actions/{action}; the asset update path does not change the status (src/cluster_erp/modules/fleet/assets/services.py:1-11). The diagram shows the maintenance flow across the sub-modules.

flowchart TD
 RD["FleetMeterReading created"] --> RC["FleetReminderService.recompute_for_asset_id"]
 PL["FleetMaintenancePlan"] --> RC
 RC --> RM["FleetMaintenanceReminder: ok, due_soon, overdue"]
 RM -->|create_work_order| WO["FleetWorkOrder draft"]
 AS["FleetAsset send_to_maintenance"] --> WO2["FleetWorkOrder released"]
 DF["FleetDefect create_work_order"] --> WO
 WO -->|release, start| WOP["open, in_progress"]
 WOP -->|issue part| GI["PostGoodsIssue to inventory"]
 WOP -->|complete| DONE["completed"]
 DONE --> RCOMP["linked reminders completed"]
 DONE --> ODO["odometer reading, source work_order"]
 DONE --> BACK["asset back to active"]

In prose:

1. A new reading recomputes the reminders of its asset (src/cluster_erp/modules/fleet/meters/services.py:308-311, src/cluster_erp/modules/fleet/meters/services.py:363-371).
2. The reminder engine sets each reminder to ok, due_soon, overdue, or snoozed (src/cluster_erp/modules/fleet/maintenance/services.py:588-597).
3. A reminder, a defect, an incident, or a campaign item can open a work order. Sending an asset to maintenance opens a released one (src/cluster_erp/modules/fleet/maintenance/services.py:351-366, src/cluster_erp/modules/fleet/assets/services.py:307-338).
4. Issuing a part line posts PostGoodsIssue to inventory (src/cluster_erp/modules/fleet/workorders/services.py:464-514).
5. Completing the order completes the linked reminders, can record a closing odometer, and returns the asset to active when no other order is open (src/cluster_erp/modules/fleet/workorders/services.py:191-265).

Business rules¶

The rules of each sub-module are on its page. Rules that apply across the module:

• Every datetime the API accepts must carry a UTC offset; a naive value is refused with a validation error (src/cluster_erp/modules/fleet/validation.py:1-21).
• A blank string in a form payload counts as no value (src/cluster_erp/modules/fleet/validation.py:24-37).
• A disposed asset takes no new operational documents (src/cluster_erp/modules/fleet/operations/services.py:80-98).
• Asset codes come from the sequence fleet_asset and work order codes from fleet_work_order (src/cluster_erp/modules/fleet/assets/services.py:229, src/cluster_erp/modules/fleet/workorders/services.py:108).
• Sub-modules call each other's services inside the package. The code comments mark these as sibling imports, not cross-module calls (src/cluster_erp/modules/fleet/assets/services.py:240-241).

Events and queries¶

The module consumes 1 contract and produces 6. Consumed means passed as the first argument of subscribe( or register_query_handler( in the package; produced means a contract class name followed by ( in the package. The full list is on the contracts reference.

The product breakdown of a part line is checked with ensure_product_breakdown before the line is stored (src/cluster_erp/modules/fleet/workorders/services.py:412-424).

Permissions¶

Every route checks a permission with require_permission. The keys follow the pattern <entity>.read, .create, .update, and .delete.

The mechanism is described on roles and permissions.

Privacy, retention, and history¶

The module has no privacy_handlers.py and no retention_handlers.py (folder listing). Deleting a record sets deleted_at. For an asset this also retires its live reminders, while readings, orders, and segments stay (src/cluster_erp/modules/fleet/assets/services.py:340-363). Readings are never edited or deleted; a wrong reading is marked incorrect (src/cluster_erp/modules/fleet/meters/services.py:9-12). Changes are captured by change history; deactivation is described on soft delete and deactivation.

Analytics facts¶

analytics_facts.py contributes four fact sets: fleet_fuel, fleet_work_order, fleet_penalty, and fleet_compliance, all read with fleet_asset.read (src/cluster_erp/modules/fleet/analytics_facts.py:35-310). Details are on TCO, telematics, and analytics; the collection path is on analytics facts.

Settings and reference data¶

• Asset classes are reference data. On start the module seeds nine classes when they are missing: car, van, truck, tractor_unit, trailer, bus, forklift, construction, and other, each with its default meters (src/cluster_erp/modules/fleet/module.py:27-47, src/cluster_erp/modules/fleet/module.py:159-195).
• The module seeds nine asset field definitions as tenant fields in the bucket fleet_asset, for example fuel_tank_l and gvwr_kg. A key that already exists is left alone (src/cluster_erp/modules/fleet/module.py:49-133, src/cluster_erp/modules/fleet/module.py:197-265).
• Inspection periods and emission factors start empty; the organisation fills them (src/cluster_erp/modules/fleet/models.py:673-789).

Tests¶

Found by a grep for /fleet/ in web-client/_e2e_*.mjs and for fleet in tests/*.py.

Discrepancies¶

Terms introduced¶

Related pages¶

• Modules index
• Assets
• Meters and fuel
• Maintenance and work orders
• Operations
• TCO, telematics, and analytics
• Inventory module
• API reference for this module

Verified against commit 92f8051 on 2026-11-13.