From 024a41f125f1058c5ca49f5b4d985be4655315fe Mon Sep 17 00:00:00 2001
From: moojttaba <mo.heidari@outlook.com>
Date: Mon, 8 Jun 2026 14:01:52 +0330
Subject: [PATCH] docs: add PRD for mini app & marketplace sprint v2.11

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 ...- Mini App & Marketplace Sprint (v2.11).md | 159 ++++++++++++++++++
 1 file changed, 159 insertions(+)
 create mode 100644 PRD - Mini App & Marketplace Sprint (v2.11).md

diff --git a/PRD - Mini App & Marketplace Sprint (v2.11).md b/PRD - Mini App & Marketplace Sprint (v2.11).md
new file mode 100644
index 0000000..c86b4b0
--- /dev/null
+++ b/PRD - Mini App & Marketplace Sprint (v2.11).md	
@@ -0,0 +1,159 @@
+# PRD — Mini App & Marketplace Sprint (v2.11)
+
+**Status:** Shipped  
+**Version:** frontend v2.11.0 → v2.11.2 / backend v2.11.0 → v2.11.1  
+**Date:** 2026-06-08  
+**Scope:** Telegram Mini App UX, purchase-request archive, payment history, seller shop settings, category filters
+
+---
+
+## 1. Summary
+
+This sprint shipped 10 planned tasks plus several hotfixes discovered in production. The main themes were:
+- **Archive system** — buyers can archive completed/cancelled requests to keep the active list clean
+- **Payment history** — web dashboard table + mini-app overlay showing full escrow transaction history
+- **Seller category selection** — sellers pick categories in shop settings; buyers use them to filter the marketplace
+- **Mini App home dashboard** — stats strip, recent requests, archive shortcut, AI assistant overlay
+- **Correctness fixes** — payment token validation, Telegram link env-var, notification deep-link
+
+---
+
+## 2. Features Shipped
+
+### 2.1 Purchase Request Archive
+
+**Problem:** Completed and cancelled requests pile up in the buyer's request list, making it hard to find active ones.
+
+**Solution:** Three-layer archive system:
+- Requests with status `completed` or `cancelled` are **auto-archived** on status transition (backend service layer)
+- Buyer can manually archive any request via a row action in the web dashboard list
+- Bulk-archive available via checkbox selection
+- Archived requests hidden by default; accessible via "Archived" toggle in the web app and the archive overlay in the mini app
+
+**Backend changes:**
+- `purchase_requests` table: added `is_archived`, `archived_at`, `archived_by` columns (migration `0029_purchase_request_archive.sql`)
+- Self-healing boot guard (`ensurePurchaseRequestArchiveColumns`) added to `connectDatabase()` to survive cold deployments where the migration hasn't been applied yet
+- New routes: `GET /marketplace/purchase-requests/archived`, `POST /marketplace/purchase-requests/:id/archive`, `POST /marketplace/purchase-requests/bulk-archive`
+- `getMyPurchaseRequests` filters out archived by default; accepts `?includeArchived=true`
+
+**Frontend changes:**
+- `buyer-request-list-view.tsx`: archive row action, `showArchived` toggle, bulk selection
+- `TelegramArchivedRequestsView`: full-screen overlay in mini app
+- Archive menu row on mini app home screen (home → archived requests)
+
+**Production incident:** Migration `0029` wasn't applied before the first deploy of v2.11.0. All `GET /marketplace/purchase-requests` calls returned HTTP 500 because Drizzle's schema referenced columns that didn't exist in production. Fixed by adding the self-healing boot guard and documenting the manual SQL path.
+
+---
+
+### 2.2 Payment History
+
+**Problem:** No way to see a consolidated list of all escrow payments (as buyer or seller) in either the web app or the mini app.
+
+**Backend:** New endpoint `GET /payment/history?role=buyer|seller|all` — returns payments filtered by the caller's role.
+
+**Web app:** `PaymentHistoryView` — data-grid table with columns: date, request ID, counterparty, amount, status, payment method. Accessible from the "تاریخچه" nav item under Payments in the dashboard sidebar.
+
+**Mini app:** `TelegramPaymentHistoryView` — scrollable list with icon/status/direction/amount per row. Opened via the "پرداخت‌ها و امانت" quick-action row on the home screen (previously this row only navigated to the account tab).
+
+---
+
+### 2.3 Seller Category Selection
+
+**Problem:** Sellers had no way to tag their shop with categories. Buyers filtering the marketplace by category got back all sellers regardless.
+
+**Backend:** Added `category_ids jsonb` column to `shop_settings` (additive migration via `ensurePostgresShopSettingsSchema`). `normalizeSellerListing` now derives `categoryIds` from the seller's active templates if not set manually.
+
+**Web app:**
+- `ShopSettingsGeneral`: Autocomplete multi-select using real `useGetCategories()` data
+- `seller-filters-drawer.tsx` / `seller-filters-result.tsx`: category filter now uses `{value, label}[]` objects; label shown in active-filter chips
+
+---
+
+### 2.4 Mini App Home Dashboard
+
+**Problem:** Home screen was a plain banner with quick-action links — no at-a-glance status.
+
+**Added:**
+- `TelegramHomeStats` — 3-up stat strip: total requests (tappable → requests tab), active escrow payments (tappable → payment history overlay), unread notifications (tappable → notifications overlay)
+- Recent activity section: the 3 most recent requests rendered as tappable rows
+- Archive shortcut row: direct entry to the archived-requests overlay
+- `TelegramWelcomeBanner`: personalized greeting using Telegram display name with fallback to "کاربر" / "User"
+
+---
+
+### 2.5 AI Assistant In-App Overlay
+
+**Problem:** "دستیار هوشمند" CTA previously opened `assist.amn.gg` in a full WebView navigation, which destroyed the mini app session — the back button led nowhere.
+
+**Solution:** Assistant now loads inside an `<iframe>` overlay with a manual back button at the top. The mini app stays mounted underneath. Auth token and user profile JSON passed as URL params so the assistant can authenticate without a cross-origin `fetch`.
+
+---
+
+### 2.6 Notification Deep-Link Fix
+
+**Problem:** Clicking a notification that had an `actionUrl` (e.g. `/dashboard/buyer/marketplace/request/{id}`) called `router.push()` which navigated the Next.js router to a web-app URL. Inside the Telegram WebView this produced a 404.
+
+**Fix:** `TelegramNotificationsView` no longer uses `router.push`. It extracts the request ID from the `actionUrl` via regex (`/marketplace\/requests?\/([a-zA-Z0-9_-]+)/`) and calls `onOpenRequest(id)` — which sets `openRequestId` in the mini-app shell, closing the notifications overlay and opening the request detail overlay in-app.
+
+---
+
+### 2.7 Telegram Mini App Link — Env Variable
+
+**Problem:** `NEXT_PUBLIC_TELEGRAM_MINI_APP_URL` was hardcoded in two places (`telegram-app-button.tsx`, `tonconnect-provider.tsx`), causing the `twaReturnUrl` to point to the wrong environment in staging.
+
+**Fix:** Centralised to `src/utils/telegram-link.ts` → `getTelegramMiniAppUrl()` reading the env var with a safe fallback.
+
+---
+
+### 2.8 Payment Token Validation
+
+**Problem:** `paymentService.ts` had `currency: 'USDT'` hardcoded. If a request was priced in USDC the payment record stored the wrong token, causing downstream balance-check mismatches.
+
+**Fix:** `resolvePaymentCurrency(token)` validates against `DEFAULT_ALLOWED_TOKENS = ['USDC', 'USDT']` and throws if the token is unsupported. AmnScanner webhook handler logs a warning when the scanned token doesn't match the payment record.
+
+---
+
+### 2.9 Mini App Requests Pagination
+
+**Problem:** Buyers with many requests saw an endless scroll — the entire list rendered at once inside the Telegram WebView, which has no native scroll chrome.
+
+**Fix:** `TelegramRequestsView` renders 8 items at a time (`PAGE_SIZE = 8`). A "نمایش بیشتر (N)" button appends the next page. Changing search/filter/sort resets to page 1.
+
+---
+
+## 3. Migration Notes
+
+### `0029_purchase_request_archive.sql`
+
+Idempotent — safe to run multiple times:
+
+```sql
+ALTER TABLE purchase_requests ADD COLUMN IF NOT EXISTS is_archived   BOOLEAN   NOT NULL DEFAULT false;
+ALTER TABLE purchase_requests ADD COLUMN IF NOT EXISTS archived_at   TIMESTAMP;
+ALTER TABLE purchase_requests ADD COLUMN IF NOT EXISTS archived_by   TEXT;
+CREATE INDEX IF NOT EXISTS idx_purchase_requests_is_archived ON purchase_requests (is_archived);
+```
+
+Apply via:
+```bash
+docker exec -i amanat-postgres psql -U amanat -d amanat < src/db/migrations/0029_purchase_request_archive.sql
+```
+
+Or redeploy backend — the boot guard runs `ADD COLUMN IF NOT EXISTS` on startup automatically.
+
+---
+
+## 4. Deployment Checklist
+
+- [x] Backend: redeploy via Arcane (does NOT auto-deploy on push)
+- [x] Frontend: auto-deploys on push to `main`
+- [x] DB migration `0029` applied (or rely on boot guard)
+- [ ] Verify `NEXT_PUBLIC_TELEGRAM_MINI_APP_URL` is set in production env
+
+---
+
+## 5. Known Limitations / Follow-up
+
+- Payment history view shows `direction: 'in'/'out'` from the backend's `IPayment` record; if `direction` is not set, defaults to buyer (outgoing). May need backend to populate `direction` reliably for all historical records.
+- Mini app payment history does not yet support pagination — fetches up to 100 records at once. Sufficient for current user volumes.
+- Task 10 (UI like wallet + tutorial videos) was descoped from this sprint. The wallet-style home stats strip is the v1 of that work.