160 lines
8.4 KiB
Markdown
160 lines
8.4 KiB
Markdown
# 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.
|