Fleet operations

This page describes the operations sub-module in src/cluster_erp/modules/fleet/operations/. It records who holds an asset and when, which tractor pulls which trailer, driver inspections and the defects they find, reservations of pool assets, and incidents such as accidents. The module overview is on fleet module.

Scope and source¶

• Defined in: src/cluster_erp/modules/fleet/models.py (FleetAssignment, FleetCoupling, FleetInspection, FleetDefect, FleetReservation, FleetIncident), operations/services.py, operations/routes.py, operations/schemas.py, and operations/metadata.py.
• Count: 6 tables, 27 routes in operations/routes.py, 14 ActionMeta entries in operations/metadata.py.
• Every service refuses a new document on a disposed asset (src/cluster_erp/modules/fleet/operations/services.py:80-98).

Entities¶

Assignments and couplings¶

• An assignment names a party, checked through GetPartyById on the EventBus (src/cluster_erp/modules/fleet/operations/services.py:64-79, src/cluster_erp/modules/fleet/operations/services.py:138).
• An assignment starts now or in the past, at most five minutes ahead (src/cluster_erp/modules/fleet/operations/services.py:139-145).
• A new assignment closes the open one of the same asset and kind at its own start. It must start after the open one and must not overlap closed history (src/cluster_erp/modules/fleet/operations/services.py:146-187).
• A partial unique index allows one open assignment per asset and kind (src/cluster_erp/modules/fleet/models.py:463-472).
• GET /assignments/as-of answers who held the asset at a moment, per kind. A time without an offset is read as UTC (src/cluster_erp/modules/fleet/operations/routes.py:83-100, src/cluster_erp/modules/fleet/operations/services.py:225-249).
• A coupling joins a powered tractor and an unpowered trailer, read from the asset class. An asset whose class is gone is refused (src/cluster_erp/modules/fleet/operations/services.py:284-294, src/cluster_erp/modules/fleet/operations/services.py:352-375).
• A new coupling closes the open couplings of both sides; partial unique indexes allow one open coupling per tractor and per trailer (src/cluster_erp/modules/fleet/operations/services.py:295-320, src/cluster_erp/modules/fleet/models.py:486-501).

Inspections and defects¶

The code describes a three-signature chain: the author signs the inspection, resolving a defect is the second signature, and the next signed clean inspection verifies resolved defects (src/cluster_erp/modules/fleet/operations/services.py:12-16).

stateDiagram-v2
 [*] --> open: defect recorded
 open --> resolved: resolve
 resolved --> open: reopen or observe
 resolved --> verified: later signed clean inspection
 open --> open: observe

In prose: a defect starts open. Resolve moves it to resolved; Reopen or a new observation moves it back to open. When a later inspection of the same asset is signed clean, every defect resolved before that inspection becomes verified (src/cluster_erp/modules/fleet/operations/services.py:423-459, src/cluster_erp/modules/fleet/operations/services.py:569-656).

• An unsigned inspection can be edited; a signed one is sealed (src/cluster_erp/modules/fleet/operations/services.py:410-422, src/cluster_erp/modules/fleet/operations/services.py:461-467).
• Signing sets is_clean when the inspection has no defects of its own, and records the odometer as a reading with source form. A refused reading does not block the signature (src/cluster_erp/modules/fleet/operations/services.py:434-440, src/cluster_erp/modules/fleet/operations/services.py:478-503).
• A defect on an inspection must belong to the same asset, and a signed inspection takes no new defects (src/cluster_erp/modules/fleet/operations/services.py:538-567).
• Create Work Order on a defect opens one order with an item of source inspection_defect or fault; a defect gets at most one order (src/cluster_erp/modules/fleet/operations/services.py:612-645).

Reservations and incidents¶

• A reservation names a party, must end after it starts, and must not overlap a reserved or retrieved reservation of the same asset (src/cluster_erp/modules/fleet/operations/services.py:693-725).
• Check Out and Return can record odometer readings with source form. The return value cannot be below the checkout value. A damage note at return creates an open defect (src/cluster_erp/modules/fleet/operations/services.py:727-786).
• An incident can be edited until it is closed. Open Insurance Claim needs reported; Create Repair Order opens one work order; Close seals it (src/cluster_erp/modules/fleet/operations/services.py:855-934).

Actions¶

Routes¶

Each of the six routers has list, create, read, and action routes; inspections and incidents also have an update route (src/cluster_erp/modules/fleet/operations/routes.py:45-458). The router prefixes are /assignments, /couplings, /inspections, /defects, /reservations, and /incidents (src/cluster_erp/modules/fleet/operations/routes.py:45-50). There is no delete route in operations/routes.py.

Terms introduced¶

Related pages¶

• Fleet module
• Maintenance and work orders
• Meters and fuel
• Parties module

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