backend requirements onthe xustomer app

constants/constants.go

@@ -168,3 +168,74 @@ const (
 	ExceptionResolved           = "Resolved"
 	ExceptionClosed             = "Closed"
 )
+
+// Customer-app stages. Nine operational stages, spelt exactly as the customer
+// client parses them: lowercase snake_case, on the wire verbatim. The client
+// rolls these up into seven milestones itself and falls back to "booked" on an
+// unknown key, silently — so adding a value here without an app release makes a
+// parcel look un-started. Never rename one; add and coordinate.
+//
+// Stages 0-5 belong to the booking. Stages 6-8 belong to each order and may
+// differ between destinations of the same booking.
+const (
+	CxStageBooked         = "booked"           // 0 — pickup requested
+	CxStageAssigned       = "assigned"         // 1 — a miler accepted it
+	CxStageOnTheWay       = "on_the_way"       // 2 — rider en route, distance/ETA live
+	CxStageArrived        = "arrived"          // 3 — rider at the door; LAST cancellable stage
+	CxStagePickedUp       = "picked_up"        // 4 — weighed, photographed, price settled
+	CxStageOrderCreated   = "order_created"    // 5 — one tracking number minted per destination
+	CxStageInTransit      = "in_transit"       // 6 — per order from here on
+	CxStageOutForDelivery = "out_for_delivery" // 7 — delivery agent carrying it
+	CxStageDelivered      = "delivered"        // 8 — handed over
+)
+
+// Customer-facing booking status. Derived from the stage but sent explicitly,
+// because a client that has to infer it will eventually infer it differently.
+const (
+	CxStatusActive    = "active"
+	CxStatusCompleted = "completed"
+	CxStatusCancelled = "cancelled"
+)
+
+// Who caused a stage transition. Recorded on every bookingstageevents row: the
+// customer timeline is derived from that table, so it has to be real, and a
+// cancellation the customer did not make is unexplainable without this.
+const (
+	CxActorMiler    = "miler"
+	CxActorOps      = "ops"
+	CxActorCustomer = "customer"
+	CxActorSystem   = "system"
+)
+
+// CxStageOrder is the rank of each stage, used to decide whether a transition
+// moves forward and whether cancellation is still open. Cancellation closes
+// after arrived, so anything at or past picked_up is refused.
+var CxStageOrder = map[string]int{
+	CxStageBooked:         0,
+	CxStageAssigned:       1,
+	CxStageOnTheWay:       2,
+	CxStageArrived:        3,
+	CxStagePickedUp:       4,
+	CxStageOrderCreated:   5,
+	CxStageInTransit:      6,
+	CxStageOutForDelivery: 7,
+	CxStageDelivered:      8,
+}
+
+// CxStageRank returns the rank of a stage, or -1 when the stage is unknown or
+// empty. A booking written before this surface existed has no stage at all,
+// and -1 keeps it strictly behind every real stage rather than tying with
+// "booked".
+func CxStageRank(stage string) int {
+	if r, ok := CxStageOrder[stage]; ok {
+		return r
+	}
+	return -1
+}
+
+// CxCancellable reports whether a booking at this stage may still be cancelled.
+// The UI mirrors this to hide the button, but the server re-checks on the
+// cancel call — the button state is a hint, never the authority.
+func CxCancellable(stage string) bool {
+	return CxStageRank(stage) <= CxStageOrder[CxStageArrived]
+}