Badges, Warnings, and Validation Reference

Job card badges

Badges appear on job cards in the work queue, board, timeline, map details, and Quick View drawer. They are rendered by schedulingBadges.jsx.

Deployment badges

Deployment badges show the current deployment state and, for deployed jobs, whether the engineer has acknowledged receipt.

Badge	CSS class	Condition	Source fields
Draft	`badge-default`	`deploymentState === "draft"` and not deploy-ready	`job.deploymentState`
Ready	`badge-success`	`deployReady === true`	`job.deployReady`
Deployed ✓	`badge-accent`	Deployed and engineer has acknowledged	`job.deploymentState`, `job.engineerAcknowledgedAt`
Deployed ○	`badge-accent-muted`	Deployed but awaiting engineer acknowledgement	`job.deploymentState`, `job.engineerAcknowledgedAt`

The shared deploymentBadge() function in schedulingBadges.jsx renders these badges consistently across all surfaces.

Statutory due-date badges

Inspection cards use nextInspectionDate to show compliance proximity in both colour and text. The Dispatch Board also exposes the same tiers in its legend.

Badge	Card tone	Condition
Overdue	Critical	Statutory due date is before the scheduler reference day
Due soon	Warning	Due within the notice window
Due this month	Info	Due in the intermediate month-range window
Comfortable	Success	Due date is outside the warning windows

The colour accent is never the only signal: queue, board, and timeline cards also render the icon+text badge.

Operational badges

Badge	Appearance	Condition	Source field
👥 N	Default badge with emoji + count	`crewSizeRequired > 1`	`job.crewSizeRequired`
OOH	Accent badge	`outOfHours === true`	`job.outOfHours`
MEWP	Default badge	`"mewp"` in `accessEquipment`	`job.accessEquipment`
Scaffold	Default badge	`"scaffold"` in `accessEquipment`	`job.accessEquipment`
Tower scaffold	Default badge	`"tower_scaffold"` in `accessEquipment`	`job.accessEquipment`
Ladder	Default badge	`"ladder"` in `accessEquipment`	`job.accessEquipment`
Cherry picker	Default badge	`"cherry_picker"` in `accessEquipment`	`job.accessEquipment`
Rope access	Default badge	`"rope_access"` in `accessEquipment`	`job.accessEquipment`
Harness	Default badge	`"harness"` in `accessEquipment`	`job.accessEquipment`
Access	Info badge with icon	`siteAccessNotes` is non-empty	`job.siteAccessNotes`

Equipment label mapping

The canonical lowercase equipment values map to display labels:

Stored value	Display label
`mewp`	MEWP
`scaffold`	Scaffold
`tower_scaffold`	Tower scaffold
`ladder`	Ladder
`cherry_picker`	Cherry picker
`rope_access`	Rope access
`harness`	Harness

Badge rendering locations

Location	Component	Notes
Work queue cards	`workspacePrimitives.jsx`	Full card with queue actions
Board cards	`workspacePrimitives.jsx`	Compact size
Timeline cards	`workspacePrimitives.jsx`	Compact size
Quick View	`SchedulingJobQuickViewDialog.jsx`	Full size in hero section

Accessibility

The crew badge uses aria-label="N crew members required" with aria-hidden="true" on the emoji
Equipment and OOH badges use their text content as the accessible name

Validation warnings

The scheduler validates every job against a set of rules. Warnings appear on job cards, in the work queue, and in the Quick View drawer.

Severity, workflow tier, and blocking state

Each warning has three related properties:

severity is the presentation urgency: info, warning, or critical.
tier is the workflow rule: hard, override, or advisory.
blocking is the deployment or movement guard. It is true for hard and override warnings, and false for advisory warnings. An override workflow must record accepted evidence before an override-tier change can proceed.

Severity controls how urgently a warning is shown; it is not itself the blocking test.

Tier	Meaning	Deployment effect
Hard	Invalid assignment, overlap, or site-access conflict	Resolve before applying or deploying.
Override	A deliberate exception such as moving locked work, crossing a schedule window, or crossing field-resource availability	Provide and review the workflow's override evidence before applying.
Advisory	Capacity, competency, equipment, month-planned, unscheduled, or customer-promise information	Review it; the warning alone does not block the change.

Warning types

Warning	Tier	Condition	Resolution
Inspection has no field resource	Hard	An inspection has no eligible assignment	Assign at least one eligible field resource.
Invalid assignee or overlap	Hard	A selected field resource is ineligible or has overlapping work	Reschedule or change the crew.
Site access rule conflict	Hard	A visit breaches access dates, blackout dates, notice, or allowed weekdays	Adjust the visit to match the site rules.
Locked visit or schedule-window conflict	Override	A movement crosses `Do not move` or the permitted window	Keep the promise, or record the explicit override required by the preview.
Field-resource day, shift, or leave conflict	Override	Work falls outside availability	Reassign, reschedule, or record the explicit override.
Competency, equipment, or capacity mismatch	Advisory	The plan may need different skills, equipment, or workload	Review before applying; choose a better crew or slot where practical.
Month planned or unscheduled	Advisory	The work has no exact visit time	Keep it as planning demand or book an exact slot before deployment.
Customer promise changed	Advisory	A move affects an offered arrival promise	Review the customer handoff before applying.

Warning display

Job cards: Warning icon with count; red icon for blocking, amber for warning
Work queue: Warning badges remain visible while jobs wait for a slot
Quick View: Full warning list with descriptions and resolution guidance
Pipeline filters: Use Draft, Ready, and Deployed to separate deployment state; warnings remain visible on cards

Deployment validation

A job is deploy-ready when all of these conditions are met:

Condition	Check
Engineer assigned	`engineerIds.length > 0`
Exact scheduled date set	`scheduledDate !== null`
Booking is committed	`bookingStatus` is `confirmed` or `do_not_move`
Status is active	Status is not `completed`, `cancelled`, or `on_hold`
No blocking warnings	`validationWarnings.filter(w => w.blocking).length === 0`

Deployment state transitions

Draft  ──(deploy)──▶  Deployed (awaiting ○)  ──(engineer opens day run)──▶  Deployed (acknowledged ✓)
  ▲                       │                                                       │
  └──(scheduling change)──┴───────────────────────────────────────────────────────┘

Changes to the visit schedule, assigned field resources, or estimated duration reset deploymentState to draft.

Redeploying a job (e.g. after a schedule change) clears engineerAcknowledgedAt back to null, so the job returns to the awaiting state until the engineer opens their day run again.

When an engineer opens their day run (GET /api/scheduler/my-day-run), all deployed stops in the response are silently marked as acknowledged. This is a fire-and-forget side effect — it does not delay the response to the engineer.

How acknowledgement works:

Step	What happens
Engineer opens My Day Run	The API returns the day-run plan, then asynchronously writes `engineerAcknowledgedAt` for all deployed stops that haven't been acknowledged yet
Implicit acknowledgement	If an inspection or work order has `startedAt` set, or a task has `completedAt` set, the system treats this as implicit acknowledgement even without an explicit timestamp
Preference order	Explicit `engineerAcknowledgedAt` is always preferred over implicit `startedAt` / `completedAt`
Redeployment	Clears `engineerAcknowledgedAt` back to `null` so the engineer must re-acknowledge
Idempotency	The DB-level `IS NULL` guard prevents double-writes; reloading the day run does not create unnecessary transactions

Deployment side effects

Side effect	Detail
`deployedAt` timestamp	ISO datetime of deployment
`engineerAcknowledgedAt` cleared	Reset to `null` on every (re)deployment
`deploymentBatchId`	Groups jobs deployed together
Email notifications	Sent to assigned engineers (fire-and-forget)
History entry	Logged with before/after snapshot for audit and undo

Scheduling constraints

Rule	Constraint
Date vs month	`scheduledDate` and `targetMonth` are mutually exclusive
Target month format	Must match `YYYY-MM`
Window ordering	`scheduleWindowEnd` must be after `scheduleWindowStart`
Duration range	15-1440 minutes (15 minutes to 24 hours)
Flex range	0-120 days
Crew size range	1-50

Equipment validation

Rule	Detail
Canonical set	`mewp`, `scaffold`, `tower_scaffold`, `ladder`, `cherry_picker`, `rope_access`, `harness`
Normalisation	Values lowercased and trimmed on input
Deduplication	Duplicate values removed automatically
Unknown values	Rejected by the server (Zod enum validation)

Assignment validation

Rule	Detail
Organisation membership	Assigned engineer must belong to the user's organisation
Field eligibility	Engineer must have `canBeScheduled: true`
Inspection assignment	Cannot clear engineer assignment on inspections

Bulk update validation

Rule	Detail
Job count	1-100 jobs per bulk update
Required fields	Each job must include `entityType` and `id`
Per-job overrides	Take precedence over base-level values
Inspection status	Cannot be changed via bulk update
Work order status	Cannot be changed via bulk update
Warning check	Rejected if update would introduce new blocking warnings