Document telegram-native task 5 foundation
This commit is contained in:
Siavash Sameni
122
09 - Audits/Task 5.1 Telegram Product Surface and Flow Map.md
Normal file
122
09 - Audits/Task 5.1 Telegram Product Surface and Flow Map.md
Normal file
@@ -0,0 +1,122 @@
|
||||
---
|
||||
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.
|
||||
Reference in New Issue
Block a user