kirukib
b4293887a8
Documents rider Telegram flows and the API/events this client needs so the shared backend can consolidate later. Co-authored-by: Cursor <cursoragent@cursor.com>
4.3 KiB
Gishen Dispatch Bot — Feature Brief
Source: Yaltopia Tech Proposal (Rev. 2.0) + Gishen E-Commerce PRD — platform feature inventory, Admin § Dispatch Bot
Repo: Gishen-Dispatch-Bot
Channel assumption: Telegram (same family as customer notification bots; separate bot instance for drivers)
This document is the build brief for this repo only. Backend contracts live in BACKEND_SPEC.md.
Product role
Replace a dedicated rider / driver mobile app for v1. Drivers receive trip work and report progress entirely inside Telegram. Ops enrolls drivers by linking their Telegram account; there is no separate driver login or app install beyond Telegram.
The Admin Dispatch Board (desk console) remains in the Admin Console repo. This bot is the rider-facing surface only.
Features
1. Trip assignment push
When: Ops assigns (or reassigns) a trip on the Dispatch Board.
Then: The bot delivers a trip/order manifest to the assigned driver’s Telegram chat, including:
- Trip id and branch / zone context
- Ordered stops with addresses
- Line items per stop (customer-safe names/qty; no clinical prescription narrative beyond what Ops already exposes to riders)
- COD amount if applicable
- Special delivery notes if present
Acceptance
- Assigned driver receives the manifest promptly after assign
- Reassign removes or supersedes the previous driver’s active trip message / buttons
- Cancelled trip notifies the driver and disables further status actions
2. Inline status updates
Driver advances the trip with inline action buttons:
picked_up → en_route → arrived → delivered / failed
Acceptance
- Only legal next transitions are shown (no skipping without backend allowance)
- Each successful press updates the shared backend; Dispatch Board and customer tracking reflect the new status in near real time
- Failed path requires or allows an exception reason (unreachable, wrong address, refused, partial delivery, other)
- Stale / already-advanced buttons are rejected safely (idempotent or clear error)
3. Proof of delivery (POD)
On delivered (and optionally on partial success paths if Ops requires):
- Driver sends a photo in the bot conversation
- Driver types recipient name in chat
Acceptance
- POD photo + recipient name are attached to the trip/stop record via the backend
- Delivery cannot be finalized without required POD fields (unless Ops configures an exception path later)
- Driver gets clear confirmation when POD is accepted
4. Driver identity & enrollment
- No separate driver credentials
- Identity = Telegram
user_id(and username if available), linked to a platformriderrecord by an Operations admin - Unlinked Telegram users cannot receive trips or mutate status
Acceptance
- Unenrolled user gets a clear “not enrolled — contact Ops” message
- Enrolled driver can list / see their active trip(s)
- Ops can unlink a driver; subsequent bot actions from that Telegram account are rejected
5. Real-time write-back
Status and POD updates from the bot must flow to:
- Admin Dispatch Board
- Customer order tracking (web / mobile / Mini App)
Transport is the shared backend (webhooks/events/websockets as the API team chooses). This bot does not talk to customer clients directly.
Non-goals (this repo / phase)
| Item | Owner / note |
|---|---|
| Dispatch Board UI, batching, route map, drag-reassign | Admin Console |
| Customer Telegram order alerts / Mini App commerce | Ecom Web |
| Continuous live GPS heartbeat | Deferred for v1 (see backend open items) |
| Health trackers, community, AI Phase 2+ | Platform exclusions |
| Flutter dedicated rider app | Superseded by this bot for v1 |
Open items to flag upward
- Telegram confirmed as the driver channel (default yes). Flag if Ops wants WhatsApp or a native app instead.
- This repo owns its own backend spec sheet — not folded into Admin’s.
- Customer notification bot vs dispatch bot: separate bots, shared worker/patterns recommended.
- Live location: out of v1 unless Dispatch Board requires continuous map pins from riders.
- Platform open items (checkout entitlement-split, Procurement vs Stock transfers, Mini App spec ownership) are N/A to this repo.