01 — Quick Reference

Which units get an item

A plan with a group gives each unit one item if the unit's primary maintenance group (Asset Register) is the plan's group or a descendant of it. A plan with an SMCS code gives an item only to units that have that SMCS fitted. A plan with no group applies to no units (a plan must be given a group to take effect). New, regrouped and retired units are handled as the Register tells us; the items of a plan that no longer applies are closed, and last done is kept where the plan is the same.

How the next due is worked out (the earliest governs)

A quiet meter (older than stale_reading_days), or an unknown rate, gives low confidence; the dates are still shown and no usage is invented. A new item counts from the last known reading.

Statuses

not_due until the due date minus lead_days → due_soon inside that window → due at the due point → overdue after the plan's tolerance_days. in_work once an order has been asked for (and it stays so until the order closes or is cancelled); deferred while the deferral date is ahead; incorporated into a larger service; closed for a finished one-off or an item whose plan no longer applies.

Work

When an item enters its lead window (or is already due or overdue) and has no order, the app sends Work the command work.create_work_order with a title and the template — no work type; the template decides it — and the item as the source. The command's message id names the item and its due point, so a retry raises one order; Work's work_order_created event, caused by that command, tells the item its order. If the order is cancelled, the next recalculation clears it and the next request is new. Items without a template are left for a person.

Completion

work.work_closed, matched by the stored order: last done = the actual finish; each trigger's last-done value is Lifecycle's reading at that date (or the scheduled point, when the plan is fixed_cycle); the lesser services the plan includes are reset; the next cycle is computed. A one-off item is closed.

Tiers

A lesser item whose due point falls inside the larger item's lead window is incorporated: no order of its own, completed with the larger one. The 1000 h template includes the 250 h and 500 h tasks, so the app never combines templates. A task of the larger service that was completed on the same unit within the last 14 days (for example the oil change of a 250 h service done last week) is not repeated: Work copies it onto the new order as Not applicable - already done on WO-xxxx.

One-off items

Condition findings are not scheduled (an elevated reading is a warning in Condition Monitoring; a possible or confirmed wear pattern asks Work for a draft order) (idempotent on the alert), due in condition_due_days; resolving the alert closes it. Lifecycle's life_due gives a life item (unless a life plan already schedules that SMCS); it follows life_forecast_changed and closes when the forecast ends.

Deferral

schedule.defer_item sets the date and the note. A deferral beyond the tolerance past the due point publishes schedule.item_deferred (Assurance decides whether it is material); a shorter one is recorded without the event.

When it recalculates, and the settings

schema/schedule_settings.yaml: tolerance_days, stale_reading_days (7), condition_due_days (14), one_off_lead_days, the default templates for one-offs.

A meter update is the trigger. When Lifecycle records a new value for a meter that a plan's trigger uses (lifecycle.usage_recorded), or a correction (lifecycle.exposure_revised), that unit's items are recalculated at once and Work is asked for an order when one enters its lead window. Between updates an item keeps the due date it was last given.

The batch is for the rest. Calendar, fixed-date and life triggers, a plan newly added to a group, and anything stale are caught by python apps/maintenance_schedule/scripts/recalculate.py or the command schedule.recalculate. Run it every few days, or by hand when the planner wants. Use the Schedule → Recalculate screen (all units, or one) or run it from a terminal. It takes the units that already have items and the units of every active plan's group (asset.group_units: all of them, no limit); nothing schedules it inside the app.

Numbers

Everyday tasks

Running it

python server/run.py maintenance_schedule                  # alone, http://localhost:5101
python networks/work_supply/network.py start            # with the whole Work & Supply network