Driver logistics request contract
Driver logistics requests are assignment contracts, not ordinary order-status updates. List visibility, detail presentation, decision eligibility, assignment settlement, grouped member effects, and ETA follow-ons must remain separate.
A card, toast, Back navigation, moved list item, or changed member order is not an acceptance or rejection receipt. Confirm the decision using the returned server result.
Availability
The logistics entry is conditionally presented from configuration and tab composition. The client treats a nonempty raw module value as truthy, so visible entry does not prove intended enablement.
The list/detail also requires authenticated Driver context, connectivity, current request data, and nonexpired display state. The API separately owns role, self-scope, request ownership, pending/time-window, lock, busy, capacity, and concurrency decisions.
Prerequisites
- Keep the Driver identity bound to the authenticated session; never accept a client-supplied Driver identity as authorization.
- Treat request/group/member IDs, business/customer/order data, timing, location, messages, and socket metadata as private.
- Distinguish individual assignment, grouped assignment, and ordinary order status contracts.
- Use non-production requests and test provider credentials when testing assignment details or decisions.
Responsibility boundaries
| Owner | Responsibility |
|---|---|
| Driver App list | Present loading/cards/empty/error/expired filtering and local refresh |
| Driver App detail | Present request/order/group context and decision controls |
| Assignment read API | Authenticate Driver self-scope and return eligible request/detail data |
| Assignment decision API | Validate request ownership/state/time/lock/busy/capacity/concurrency and apply one decision |
| Group/order services | Apply group/member assignment, competing-request cancellation and related order effects |
| ETA follow-on | Update each accepted member independently when configured |
| Socket/push/providers | Transport updates only; never define authorization or durable completion |
| Dispatcher/operator | Reconcile partial or ambiguous assignment/member state |
Inputs and result
List and detail reads
Inputs include authenticated Driver context, pagination/filter state, and current request lifecycle. Results are loading, displayable request cards, grouped cards, empty, expired/removed, detail, or error.
Distance derived from stored location is presentation/eligibility input, not a fresh or trusted live-position guarantee.
Decisions
Accept/reject intent applies to one assignment request and the current Driver. The service must revalidate ownership, pending state, expiry, locks, workload, group capacity, and concurrency at decision time.
Wait for the decision result before treating a request as accepted or rejected. The current detail flow can navigate Back before a rejection request settles, so returning to the list does not confirm the result.
Groups and ETA
A grouped assignment decision can affect the group, member orders, competing requests, Driver state, history, integrations, sockets, notifications, and jobs. Configured default ETA is a separate write per member after acceptance. Those writes are not one transaction and individual failures can be silent.
Security and privacy
- Derive Driver identity from the authenticated session.
- Authorize the assignment request and every affected group/member before mutation.
- Use locks/idempotency to prevent competing Drivers or duplicate decisions.
- Return a purpose-minimal result without private contact/location/message data not needed by the decision UI.
- Never log request IDs, group/member IDs, coordinates, contact values, tokens, rooms, or provider payloads in tickets or shared examples.
Limits and failure states
| State | Required interpretation |
|---|---|
| Visible card/detail | Candidate presentation, not eligibility receipt |
| Locked/expired/busy/capacity error | Decision rejected at one validation stage |
| Back after decision | Navigation only |
| Group moves lists | Local/result presentation, not all-member completion |
| Toast | Client message, not durable assignment receipt |
| Partial ETA | Assignment may have settled while one or more ETA writes failed |
| Socket update | Transport hint, not authorization/ordering guarantee |
| Detail GPS/message/provider activity | Mount effects, not assignment result |
Group assignment and ETA updates are separate operations. Do not assume that a decision is atomic across members, rolls back completely, or can be retried safely without checking the current server result.
Troubleshooting
A request disappears
Treat expiry, lock, ownership, competing decision, socket update, or refresh as possible causes. Re-read the current authorized list; do not replay a decision.
Back occurs immediately after Reject
Do not interpret Back as rejection success. Await a server result receipt or ask the dispatcher to reconcile the request.
A group is partly updated
Reconcile the assignment and every member independently. Do not repair member ETA/status from the client without an accepted recovery contract.
ETA differs across members
ETA writes are independent follow-ons. Record the affected member set privately and use the operator-owned reconciliation path.
The logistics entry appears unexpectedly
Review typed configuration and combined-tab policy. Raw truthiness is not an enablement contract.
Related guides: Logistics assignment requests · Accept a delivery request · Reject a delivery request