123 lines
6.0 KiB
Markdown
123 lines
6.0 KiB
Markdown
---
|
|
title: Task 5.1 Telegram Product Surface and Flow Map
|
|
tags: [taskmaster, telegram, product, flow-map, canonical-state]
|
|
created: 2026-05-24
|
|
status: draft
|
|
---
|
|
|
|
# Task 5.1 Telegram Product Surface and Flow Map
|
|
|
|
Source: `/.taskmaster/docs/prd-telegram-native-app-bot-wallet.md`
|
|
|
|
This map defines the first-release Telegram-native surface for Task 5.1 and keeps the financial core bound to the canonical
|
|
[`Funds Ledger and Escrow State Machine Specification`](Funds%20Ledger%20and%20Escrow%20State%20Machine%20Specification.md) and
|
|
Task 4 authorization/risk controls.
|
|
|
|
## 1) Channel split (first release)
|
|
|
|
| Area | Bot messages | Mini App | Web/Admin-only (first release) |
|
|
|---|---|---|---|
|
|
| Discovery & onboarding | `/start`, `/help`, `/link`, `/settings` | Onboarding cards, link prompts, fallback CTA | Full self-serve onboarding docs |
|
|
| Request browse/create | summary list + quick actions only | Full in-app list, create/edit request form | Full advanced catalog/search UI |
|
|
| Offers | receive offer summary, accept/reject shortcuts | full offer list and detail, offer accept/reject | Seller negotiation detail with admin context |
|
|
| Payment start | payment shortcut button + deep link payload | payment state UI + provider launch from in-app | Payment method setup, advanced failure handling |
|
|
| Delivery evidence | status update nudges + evidence deep link | upload evidence from in-app flow | Full media manager + admin-side attachments |
|
|
| Dispute | dispute open/summary + status check | open/respond/track dispute in app | Admin moderation, manual evidence review |
|
|
| Release/Refund | only status blockers and support handoff | confirmation request + release/refund request | Execute actions through canonical payment API |
|
|
| Notification settings | toggle on/off, blocked-state view | mirror of notification status and quiet mode | Full support/notification audit UI |
|
|
| Support | support contact + report IDs | support request and context handoff | Admin/operator console and action audit |
|
|
|
|
## 2) Canonical state mapping (all actions)
|
|
|
|
All Telegram actions must map to existing canonical states and API-side checks:
|
|
|
|
- `PurchaseRequest.status`: `pending` → `received_offers` → `in_negotiation` → `payment` → `processing` → `delivery` → `delivered` → `confirming` → `completed` / `cancelled`
|
|
- `Payment.escrowState`: `FUNDED` / `PARTIALLY_FUNDED` / `RELEASABLE` / `DISPUTED` / `RELEASING` / `RELEASED` / `REFUNDING` / `REFUNDED` / `FAILED` / `CANCELLED`
|
|
- `Dispute.status`: `OPEN` / `UNDER_REVIEW` / `RESOLVED_*` / `CLOSED` as appropriate
|
|
|
|
The only transitions that may modify funds, release eligibility, or dispute holds are those enforced by the canonical service
|
|
layer from the
|
|
[`Funds Ledger and Escrow State Machine Specification`](Funds%20Ledger%20and%20Escrow%20State%20Machine%20Specification.md).
|
|
|
|
## 3) Journey mapping by persona
|
|
|
|
### 3.1 Unauthenticated user
|
|
|
|
- See bot start/help and public support command.
|
|
- Any authenticated action routes to account-link flow.
|
|
- No request write actions without auth link.
|
|
|
|
### 3.2 Unlinked Telegram user
|
|
|
|
1. Start in bot or Mini App.
|
|
2. Prompt account linking (`/link` equivalent) using signed callback token.
|
|
3. Complete account link or return to web flow.
|
|
4. After link success, deep link returns user to prior action context (request, offer, payment, or dispute).
|
|
|
|
### 3.3 Linked buyer
|
|
|
|
- Browse/create requests, send offer review decision, start payment, upload delivery evidence, open disputes, monitor request state, request release/refund.
|
|
- No direct fund release path: Telegram actions read state and submit intent only.
|
|
|
|
### 3.4 Linked seller
|
|
|
|
- Receive offer and request notifications, update offer availability, review buyer disputes, upload shipping/proof artifacts.
|
|
- No direct payout mutation from Telegram; actions remain canonical requests to existing payment/dispute endpoints.
|
|
|
|
### 3.5 Admin/support
|
|
|
|
- Dedicated support context in admin view only (first release).
|
|
- Telegram-origin IDs and linked wallet/payment provenance shown in existing admin interfaces.
|
|
- Any manual override for Telegram-originated cases follows the same step-up/two-person policy as web flows when configured in
|
|
[`Security Ownership and Launch Decision Criteria`](Security%20Ownership%20and%20Launch%20Decision%20Criteria.md).
|
|
|
|
## 4) Deep-link and context contract
|
|
|
|
Deep-link entry points in order of priority:
|
|
|
|
1. `request` detail
|
|
2. `offer-review` (accept/reject)
|
|
3. `payment-start`
|
|
4. `dispute-open` / `dispute-track`
|
|
5. `delivery-evidence`
|
|
6. `account-link`
|
|
|
|
Rules:
|
|
|
|
- No raw IDs in clear URLs when not needed.
|
|
- Use short opaque or signed context IDs.
|
|
- Expire context tokens and bind to Telegram user + wallet/session.
|
|
- Every context hit verifies canonical ownership/state before rendering any action.
|
|
|
|
### Example startapp routes (illustrative)
|
|
|
|
- `.../startapp=request&rid=<opaque>`
|
|
- `.../startapp=offer&oid=<opaque>`
|
|
- `.../startapp=payment&pid=<opaque>`
|
|
- `.../startapp=dispute&did=<opaque>`
|
|
- `.../startapp=verify`
|
|
|
|
## 5) Release phasing
|
|
|
|
| Phase | Telegram surface | Backend dependency |
|
|
|---|---|---|
|
|
| Phase 0 (MVP) | bot + limited Mini App for state-safe buyer/seller actions; no Telegram-only financial mutations | Payment and ledger gates already enforced |
|
|
| Phase 1 | richer navigation, richer filters, deeper support surfaces | Identity linking + event fanout |
|
|
| Phase 2 | admin operator actions in Telegram | Additional ops hardening and audit scope |
|
|
|
|
## 6) Acceptance traceability
|
|
|
|
Directly mapped to PRD section "Task 1":
|
|
|
|
- Buyer/seller/admin/support journeys and entry contexts documented: **yes**
|
|
- Deep links and entry points defined with phase split: **yes**
|
|
- Canonical API/state mapping in table + journey sections: **yes**
|
|
- Non-native and admin surfaces identified: **yes**
|
|
- Backward compatibility with existing web flows retained: **yes**
|
|
|
|
## 7) Open items for implementation
|
|
|
|
1. Finalize concrete deep-link payload schema (opaque token claim set).
|
|
2. Finalize Mini App navigation IDs and route-to-state matrix in frontend routing.
|
|
3. Confirm unsupported actions for `DISPUTED`/`FAILED` states at Telegram action layer.
|