Use the reviewed order query contract
Driver order queries produce scoped pages and details, not a complete or atomic operational snapshot. Tab state, filters, pagination, local grouping, summaries, socket events, and logistics assignment reads are separate layers.
A card, count, empty view, group, summary, sort position, or refreshed detail does not prove currentness or completeness.
Availability
Authenticated Driver order list/detail reads are available through Orders and registered detail routes. The service scopes Driver queries to the current Driver and applies requested filters/pagination.
Logistics assignment requests use a separate assignment-query contract. They must not be merged into ordinary order query semantics merely because the App presents them in the Orders area.
Prerequisites
- Derive Driver identity from the authenticated session.
- Use typed, allowlisted filter/sort/page inputs with bounded page size.
- Define requested relations/fields purpose-minimally.
- Distinguish first page, load more, refresh, cross-status search, detail read, socket/event update, and local grouping.
- Preserve one revision/cursor contract if currentness across pages matters.
Responsibility boundaries
| Owner | Responsibility |
|---|---|
| Order API | Driver scope, filters, sort, pagination, relation projection, detail authorization |
| Client list controller | Tab/page/filter/loading/error state and deduplication |
| Client formatter | Plain/grouped transformations and presentation sorting |
| Filter dependencies | Countries/cities/config controls as separate reads |
| Socket/event layer | Incremental hints requiring authorization and revision reconciliation |
| Logistics API | Assignment request list/detail, not ordinary orders |
| Summary UI | Derived display only; not earnings, payout, accounting, or query authority |
Inputs and result
Supported query dimensions can include order status group, order/external identifier search, city/business, delivery type, date range, timing category, page, page size, and sort. Availability varies by UI/configuration.
Results must distinguish loading, populated page, empty page, error, additional page, refreshed page, grouped presentation, detail, and event-updated local state. An empty page is not “no orders,” and concatenated pages/events are not one snapshot without a revision contract.
Cross-status search clears the current tab-status filter and can use separate pagination/summary presentation. Opening its city selector can automatically start a countries/cities dependency read before Search.
Grouping is a local transformation of returned orders/keys. It is not a user- selectable server grouping rule or authorization boundary. Missing/malformed keys and mixed member states require explicit handling.
Security and privacy
- Enforce Driver self-scope for every list/detail/event refresh.
- Allowlist filters/sorts/relations; cap page size and reject malformed values.
- Return purpose-minimal order, business, customer, location, payment, message, and assignment fields.
- Never expose raw IDs, contacts, addresses, coordinates, tokens, query payloads, room names, or private errors in public evidence.
- Reauthorize socket/event-triggered detail reads; never trust event payload as the current order.
Limits and failure states
| State | Required interpretation |
|---|---|
| Loading skeleton | Read unresolved |
| Card/page | Current returned/local page only |
| Empty | No row in this result/page/filter |
| Load more | Another reported page, not complete snapshot |
| Filtered summary | Derived cross-status display |
| Group card | Local transformation, member outcomes separate |
| Socket move/insert/remove | Incremental local update, not durable/current proof |
| Detail | Authorized read plus related mount dependencies |
| Logistics card | Separate assignment query contract |
No complete count, stable ordering across events, snapshot isolation, exactly-once socket update, exhaustive grouping, payout meaning, or deployed currentness is established.
Troubleshooting
Results look stale or incomplete
Separate tab/filter/page/socket state. Refresh once and compare the returned revision; do not loop reads as a currentness test.
An empty page appears
Check filter/page/status context and errors. Do not infer no order exists or broaden scope without authorization.
Duplicate or moved cards appear
Pagination deduplication and socket events can interleave. Reconcile by order revision, not visual position.
A group contains mixed states
Treat each member independently. Local grouping does not guarantee common status, ownership, eligibility, or atomic outcome.
Logistics and ordinary orders differ
Use the logistics request contract for assignment reads/decisions. Do not force ordinary order filters or grouping rules onto assignment requests.
Related guides: Find delivery requests · Filter and prioritize requests · Use the logistic request contract