Fleet maintenance and work orders

This page describes two sub-modules of fleet. The maintenance sub-module in src/cluster_erp/modules/fleet/maintenance/ holds maintenance plans and the reminders the engine computes from them. The workorders sub-module in src/cluster_erp/modules/fleet/workorders/ holds work orders, their items, and their spare-part lines. The module overview and the end-to-end maintenance diagram are on fleet module.

Scope and source¶

• Defined in: src/cluster_erp/modules/fleet/models.py (FleetMaintenancePlan, FleetMaintenanceReminder, FleetWorkOrder, FleetWorkOrderItem, FleetWorkOrderPart), maintenance/services.py (FleetPlanService, FleetReminderService), workorders/services.py (FleetWorkOrderService), and the routes.py and metadata.py files of both folders.
• Count: 5 tables, 23 routes (9 in maintenance/routes.py, 14 in workorders/routes.py), 9 ActionMeta entries (4 in maintenance/metadata.py, 5 in workorders/metadata.py).

Plan fields¶

Reminder engine¶

A reminder (FleetMaintenanceReminder) is engine output, one live row per plan and asset. Its status is computed and never edited (src/cluster_erp/modules/fleet/maintenance/services.py:17-19).

• A plan needs at least one rule: a day interval, a meter interval, or a meter threshold. A threshold needs a direction, and a season needs both boundaries in MM-DD (src/cluster_erp/modules/fleet/maintenance/services.py:99-143).
• The calendar rule steps from the start date in schedule mode, or adds the interval to the last completion (src/cluster_erp/modules/fleet/maintenance/services.py:508-518).
• The meter rule turns the remaining usage into days through the meter's daily rate over the last five valid readings (src/cluster_erp/modules/fleet/maintenance/services.py:48, src/cluster_erp/modules/fleet/maintenance/services.py:520-546).
• When both a calendar date and a meter date exist, the earlier one wins. A date outside the season moves to the next season start (src/cluster_erp/modules/fleet/maintenance/services.py:273-288, src/cluster_erp/modules/fleet/maintenance/services.py:578-586).
• A threshold hit makes the reminder due today and latches until a completion after the hit (src/cluster_erp/modules/fleet/maintenance/services.py:548-577).
• The status is snoozed while a snooze date lies ahead, overdue after due date plus tolerance, due_soon from due date minus lead days, and ok otherwise (src/cluster_erp/modules/fleet/maintenance/services.py:588-597).
• A plan with suppressed_by_plan_id gets is_suppressed while the covering reminder is due (src/cluster_erp/modules/fleet/maintenance/services.py:438-461).
• Editing a plan recomputes its reminders and retires the ones that no longer match. Deleting a plan retires all its reminders (src/cluster_erp/modules/fleet/maintenance/services.py:175-254).

The engine runs when a reading is posted, an asset is created, a plan changes, a reminder action runs, or a work order completes (src/cluster_erp/modules/fleet/meters/services.py:311, src/cluster_erp/modules/fleet/assets/services.py:244-248, src/cluster_erp/modules/fleet/maintenance/services.py:403). POST /maintenance/reminders/recompute runs it for one asset or for all assets that are not disposed (src/cluster_erp/modules/fleet/maintenance/routes.py:141-153, src/cluster_erp/modules/fleet/maintenance/services.py:409-416). A scheduled call of recompute_all was not found in src/, deploy/, webapp/, or gated_apps/.

Snoozing needs a future date. Completion refuses a future date, records the current life-to-date of the plan's meter, and clears the snooze (src/cluster_erp/modules/fleet/maintenance/services.py:340-389).

Work order fields¶

An item (FleetWorkOrderItem) has a typed source: scheduled_maintenance, fault, inspection_defect, form, issue, or manual (src/cluster_erp/modules/fleet/models.py:71-78, src/cluster_erp/modules/fleet/models.py:418-433). A part line (FleetWorkOrderPart) carries the mandatory product, model, and version, a warehouse, a quantity, a unit cost, and a status planned or issued (src/cluster_erp/modules/fleet/models.py:436-452).

Work order statuses and actions¶

stateDiagram-v2
 [*] --> draft
 draft --> open: release
 open --> in_progress: start
 open --> completed: complete
 in_progress --> completed: complete
 draft --> cancelled: cancel
 open --> cancelled: cancel

In prose: an order starts as draft, is released to open, can be started, and is completed from open or in_progress. It can be cancelled from draft or open (src/cluster_erp/modules/fleet/workorders/services.py:47-53).

Work order rules¶

• A new order checks the asset and, when given, the purchase request through GetPurchaseRequestById. An order opened from a reminder gets a first item with source scheduled_maintenance (src/cluster_erp/modules/fleet/workorders/services.py:103-121, src/cluster_erp/modules/fleet/workorders/services.py:367-396).
• Items and parts can change only while the order is draft, open, or in_progress (src/cluster_erp/modules/fleet/workorders/services.py:55, src/cluster_erp/modules/fleet/workorders/services.py:544-550).
• A part line checks the product breakdown through ensure_product_breakdown and needs a positive quantity. Its total is quantity times unit cost, rounded with ROUND_HALF_EVEN to two decimals (src/cluster_erp/modules/fleet/workorders/services.py:412-446).
• Issuing a part locks the line, needs a released order, and posts PostGoodsIssue to inventory with the order as reference. A refusal from inventory fails the action (src/cluster_erp/modules/fleet/workorders/services.py:464-514).
• An issued part line cannot be removed, and an order with issued parts cannot be cancelled (src/cluster_erp/modules/fleet/workorders/services.py:448-462, src/cluster_erp/modules/fleet/workorders/services.py:158-166).
• parts_cost is the sum of part totals; total_cost adds labour, external, and parts costs when any of them is set (src/cluster_erp/modules/fleet/workorders/services.py:528-542).
• Completion needs every planned part issued or removed and a date not in the future. It can record an odometer reading with source work_order, completes every linked reminder, and returns the asset to service when no other order is open (src/cluster_erp/modules/fleet/workorders/services.py:191-295).
• Only a draft or cancelled order can be deleted; the delete sets deleted_at (src/cluster_erp/modules/fleet/workorders/services.py:177-189).

Routes¶

The delete routes of items and parts set deleted_at on the line (src/cluster_erp/modules/fleet/workorders/services.py:349-355, src/cluster_erp/modules/fleet/workorders/services.py:448-462).

Terms introduced¶

Related pages¶

• Fleet module
• Meters and fuel
• Operations
• Inventory module
• Product breakdown and stock conversion

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