# 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.