Skip to main content

Trucking Status Canonicalization (Job + Leg)

This doc summarizes the trucking status canonicalization work completed to fix inconsistent status spellings (e.g. "New" vs new, "En Route" vs en_route, "In Progress" vs in_progress) and prevent invalid job transitions like New → in_progress.

Canonical statuses (stored in MongoDB)​

Job (trucking)​

new → scheduled → dispatched → in_progress → completed → invoiced → paid

Leg (trucking)​

pending → assigned → en_route → at_pickup → loaded → in_transit → at_delivery → delivered

Backward compatibility model​

  • Inputs: API endpoints accept legacy spellings (Title Case, camelCase, hyphenated) and normalize them.
  • Storage: trucking statuses are persisted as canonical snake_case.
  • UIs: web/mobile should map canonical values to display labels; stage selection uses normalization so legacy records still render.
  • Migration: no bulk migration required; “normalize-on-write” gradually cleans up stored values.

Derivation rules (trucking job rollup)​

Trucking job status is derived from legs + assignment using:

  • Service: attunelogic-api/src/services/job-status-rollup.service.js
  • Helpers:
    • attunelogic-api/src/utils/status/jobStatus.js
    • attunelogic-api/src/utils/status/legStatus.js

Rules implemented:

  • new → scheduled: at least one leg has an appointment date
  • scheduled → dispatched: at least one driver is assigned (via job.drivers or leg.driver or leg status assigned)
  • dispatched → in_progress: at least one leg is in-progress-like (en_route, at_pickup, loaded, in_transit, at_delivery)
  • → completed: all legs are delivered
  • invoiced / paid: handled by invoice/payment flows (not auto-derived here)

Main API write paths updated​

  • Leg status transitions

    • GET /api/v1/legs/:id/status?status=...
    • Controller: attunelogic-api/src/controllers/legs/updateStatus.js
    • Behavior:
      • normalize incoming status for trucking
      • persist canonical leg status
      • run job rollup
      • advance the next leg from pending → assigned (canonical)

  • Leg create / leg edit

    • Create: attunelogic-api/src/controllers/legs/create.js triggers job rollup after creating a leg
    • Update: attunelogic-api/src/controllers/legs/index.js normalizes trucking req.body.status and triggers job rollup on update

  • Job assignment (dispatch)

    • Controller: attunelogic-api/src/controllers/jobs/index.js
    • For trucking, assigning drivers sets job status to canonical dispatched (and unassigned falls back to new)

  • Job creation (leg defaults during create)

    • Controller: attunelogic-api/src/controllers/jobs/create.js
    • Leg defaults during creation now use canonical pending (not "Pending")

Downstream readers updated for canonical statuses​

  • Scheduler route selection
    • attunelogic-api/src/controllers/schedule/index.js
    • “current leg” selection now uses normalization (prefers en_route / in-progress-like leg statuses)

Web UI compatibility notes​

  • Web stage selection now normalizes raw job.status before looking up stages:
    • attunelogic-service/src/pages/Jobs/job-stages.tsx
  • Job Show confirmation/fallback copy uses normalized stage ids rather than checking raw strings:
    • attunelogic-service/src/pages/Jobs/Show/index.jsx

Known follow-ups​

  • Ensure any remaining reporting/aggregation logic that matches exact strings is updated to count both legacy + canonical statuses until old records age out.
  • Add/repair automated tests (some workspaces currently have test runner environment issues).