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>
107 lines
4.3 KiB
Markdown
107 lines
4.3 KiB
Markdown
# 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](./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 platform `rider` record 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
|
||
|
||
1. **Telegram confirmed** as the driver channel (default yes). Flag if Ops wants WhatsApp or a native app instead.
|
||
2. This repo owns its **own** backend spec sheet — not folded into Admin’s.
|
||
3. Customer notification bot vs dispatch bot: **separate bots**, shared worker/patterns recommended.
|
||
4. Live location: out of v1 unless Dispatch Board requires continuous map pins from riders.
|
||
5. Platform open items (checkout entitlement-split, Procurement vs Stock transfers, Mini App spec ownership) are **N/A** to this repo.
|