Skip to main content

Routing Assignment States

This is the locked V1 routing assignment contract for IED.

Use this as the source of truth for:

  • what a lead assignment is
  • the V1 assignment status set
  • how assignment differs from lead lifecycle
  • how path choice affects assignment creation
  • what closes or replaces an assignment

What A Lead Assignment Is​

A LeadAssignment is a per-installer operational record.

It represents one routing relationship between:

  • one lead
  • one installer

It is not a duplicate of the lead lifecycle.

Lead lifecycle remains the top-level customer journey.

Assignment status captures distribution-specific progress, not installer sales progression.

V1 Assignment Status Model​

V1 live operations use the following assignment status set:

  • pending Assignment exists internally but has not been sent to the installer yet
  • sent Assignment has been handed to the installer
  • contacted Follow-up work recorded real customer outreach after delivery
  • rerouted Assignment was superseded because the lead was reassigned elsewhere

V1 does not add scoring, SLA states, installer sales outcomes, or automated escalation states to the assignment model.

Relationship To Lead Lifecycle​

Assignment status must stay separate from lead status.

The relationship is:

  • lead assigned means the lead has been captured into installer distribution
  • assignment sent means installer delivery succeeded
  • delivery events determine billing truth

This means:

  • assignment records do not replace the lead lifecycle
  • assignment delivery and billing stay separate from the lead status
  • installer company status is separate from assignment status

Path-Specific Routing Behavior​

V1 routing is path-specific.

This path usually creates one primary assignment.

It should still support rerouting if the first assignment stops being viable.

compare_quotes​

This path can create multiple parallel assignments.

It should support parallel distribution and separate follow-up work on the same lead.

Path choice affects assignment count and workflow shape.

It does not change the assignment status model itself.

Completion And Rerouting Rules​

V1 operational completion rules:

  • rerouted is the visible replacement outcome before delivery succeeds

rerouted should be used when operations actively replace the assignment by sending the lead elsewhere.

Do not overload routing status to represent installer sales progress or customer follow-up outcomes.

Rerouting should stay visible for:

  • reporting
  • internal timelines
  • operator clarity

Suggested LeadAssignment fields:

  • leadId
  • installerId
  • regionId
  • selectedPath
  • status
  • assignedAt
  • sentAt
  • contactedAt
  • closedAt
  • outcomeReason
  • notes

Contract Boundaries​

These do not belong inside the routing assignment state contract:

  • lead lifecycle design belongs in docs/product/lead-lifecycle.md
  • installer company availability status belongs in docs/product/installer-tier-status-rules.md
  • region ownership rules belong in docs/product/region-postcode-ownership-rules.md
  • follow-up workflow belongs in the follow-up contract
  • scoring, SLA windows, and auto-escalation can be defined later without changing the core assignment state model

Validation Scenarios​

The model should support these scenarios:

  • a recommended-installer lead creates one primary assignment that moves pending -> sent -> contacted
  • a compare-quotes lead creates multiple assignments in parallel
  • rerouting creates a visible rerouted outcome instead of hiding replacement behind some other operational label
  • assignment progress does not force lead terminal state
  • installer paused or inactive status remains separate from assignment progress