nick-doc/09 - Audits/Task 5.1 Telegram Product Surface and Flow Map.md

title, tags, created, status

title	tags	created	status
Task 5.1 Telegram Product Surface and Flow Map	taskmaster telegram product flow-map canonical-state	2026-05-24	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 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.

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.

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.