Lifecycle states across the platform

CargoSurge uses explicit lifecycle states instead of free-text "status" strings. Every transition is audited and some require approval. Knowing the states saves you from UI confusion later.

Quotation states

draft → sent → accepted | rejected | expired

• draft — you're still editing. Not visible to the customer.
• sent — PDF generated and sent (or public link issued). Waiting on customer action.
• accepted — customer has accepted. Auto-converts to a Booking.
• rejected — customer rejected. Terminal.
• expired — past the validity date. Terminal; clone it to create a new version.

Booking states

draft → requested → confirmed → locked → planned → in_transit → delivered
                                                               → cancelled

• draft / requested — pre-confirmation. The route, charges, and cargo may still change.
• confirmed — customer and carrier have agreed. Now chargeable.
• locked — documents (BL, AWB) issued. Further changes require a revision, not an in-place edit.
• planned — pickup scheduled; physical execution about to start.
• in_transit — cargo is moving. Milestones tick as events arrive.
• delivered — POD received. Can still generate late-delivery invoices.
• cancelled — booking killed before completion. Any charges already posted need explicit reversal.

On confirmed, CargoSurge auto-creates the linked Shipment (or RoadTrip for road mode).

Shipment / Trip states

For road: planned → dispatched → loaded → in_transit → delivered. For sea and air: milestones drive the state via carrier events or manual updates.

Invoice states

draft → issued → sent → partially_paid | paid
                     → overdue
                     → cancelled

• draft — you're still adding lines.
• issued — PDF generated, number assigned, locked from further editing.
• sent — emailed to the customer.
• partially_paid — payment received but less than grand_total.
• paid — fully settled.
• overdue — past due_date without full payment. Not a separate manual state — CargoSurge computes it on the fly.
• cancelled — voided. Requires a Credit Note to keep accounting straight; don't just delete.

Customs declaration states

draft → submitted | docs_to_broker
docs_to_broker → broker_processing
broker_processing → held | cleared
submitted → under_review → held | cleared
held → cleared | rejected
cleared → released
released → reopened   (admin-only, rare)
reopened → cleared    (re-enter the normal chain)

Plus a separate post-release track after released: docs_pending → docs_submitted → docs_accepted | docs_rejected → closed. That tracks the doc-submission followup to the customs authority, which usually happens after the cargo has already been physically released.

Why explicit states matter

1. Audit log integrity — every transition is recorded with user + timestamp.
2. Automation — you can wire workflows that fire "when a booking moves to confirmed".
3. Reporting — status-based KPIs (e.g. "% of quotes accepted", "average days in transit") need a clean state machine.
4. Permissions — some transitions are role-gated (e.g. only admin can reopen a released customs declaration).

Common pitfalls