233 lines
16 KiB
Markdown
233 lines
16 KiB
Markdown
---
|
||
title: Purchase Request Flow
|
||
tags: [flow, marketplace, buyer, purchase-request]
|
||
related_models: ["[[PurchaseRequest]]", "[[Category]]", "[[Address]]", "[[SellerOffer]]"]
|
||
related_apis: ["POST /api/marketplace/purchase-requests", "GET /api/marketplace/purchase-requests", "PATCH /api/marketplace/purchase-requests/:id"]
|
||
---
|
||
|
||
> **Last updated:** 2026-05-31 — template checkout delivery/payment rail behavior added.
|
||
|
||
> [!warning] Audit — 2026-05-29
|
||
> This document was corrected against the live codebase. Key changes: status enum updated (added `pending_payment`, `active`; removed undocumented `finalized`/`archived`); urgency values expanded to include `urgent`; sellers endpoint corrected; attachment upload endpoint corrected; `request-cancelled` socket event removed (non-existent); `new-purchase-request` fan-out target corrected to shared `sellers` room; socket room join/leave events documented; description minimum corrected to 5 chars; PUT vs PATCH mismatch flagged as known bug; two frontend actions hitting non-existent backend endpoints flagged as not implemented.
|
||
|
||
# Purchase Request Flow
|
||
|
||
A **buyer** drafts and publishes a purchase request describing what they want to source. Once published, the request becomes visible to sellers (either all sellers or a curated subset), kicking off [[Seller Offer Flow]].
|
||
|
||
## Actors
|
||
|
||
- **Buyer** — owner of the request.
|
||
- **Frontend** — multi-step wizard at `/dashboard/request/new` (`frontend/src/app/dashboard/request/new/page.tsx`). The wizard component lives in `frontend/src/sections/request/components/request-form-wizard.tsx` and uses the step files under `frontend/src/sections/request/components/steps/` (basic info, details, budget, review) plus `buyer-steps/` for the post-publish lifecycle.
|
||
- **Backend** — `PurchaseRequestService.createPurchaseRequest` and the marketplace controller (`backend/src/services/marketplace/marketplaceController.ts`).
|
||
- **MongoDB** — `purchaserequests`, with population from `users` and `categories`.
|
||
- **Socket.IO** — emits `purchase-request-update` to the `request-{id}` room and `seller-offer-update` to seller rooms.
|
||
- **Notification service** — pushes in-app notifications to all targeted sellers.
|
||
|
||
## Preconditions
|
||
|
||
- User is authenticated and `req.user.role === 'buyer'`.
|
||
- At least one category exists (seeded via `seedCategories`).
|
||
- Optional: the buyer has saved a delivery address under `/dashboard/account/addresses`.
|
||
|
||
## State machine
|
||
|
||
Status progression is enforced by `STATUS_PROGRESSION_ORDER` in `PurchaseRequestService.ts:12-26`. Moving backward is disallowed except into a terminal status.
|
||
|
||
```mermaid
|
||
stateDiagram-v2
|
||
[*] --> pending: createPurchaseRequest()
|
||
pending --> active: request activated
|
||
pending --> pending_payment: payment initiated
|
||
pending_payment --> active: payment confirmed
|
||
active --> received_offers: first SellerOffer saved\nSellerOfferService.createOffer
|
||
received_offers --> in_negotiation: buyer/seller chat\n(counter-offer, see [[Negotiation Flow]])
|
||
in_negotiation --> received_offers: counter rejected
|
||
received_offers --> payment: Request Network payment confirmed\n(selected offer)
|
||
in_negotiation --> payment: same
|
||
payment --> processing: seller acknowledges
|
||
processing --> delivery: seller marks shipped
|
||
delivery --> delivered: buyer enters delivery code
|
||
delivered --> confirming: optional auto-release timer
|
||
confirming --> completed: escrow released to seller
|
||
pending --> cancelled: buyer cancels (any pre-payment status)
|
||
active --> cancelled
|
||
received_offers --> cancelled
|
||
in_negotiation --> cancelled
|
||
cancelled --> [*]
|
||
completed --> [*]
|
||
```
|
||
|
||
Terminal statuses: `completed`, `cancelled` (`PurchaseRequestService.ts:28`).
|
||
|
||
> [!note] Statuses `finalized` and `archived` do NOT exist in the frontend `IPurchaseRequest` type and are not live statuses. They are not part of the active state machine.
|
||
|
||
## Step-by-step narrative
|
||
|
||
### Multi-step wizard
|
||
|
||
1. Buyer clicks "New request" in the dashboard sidebar and lands at `/dashboard/request/new`.
|
||
2. **Step 1 — Basic info** (`steps/request-basic-info-step.tsx`): title (5–200 chars), description (5–2000 chars, **minimum is 5 characters** per frontend Zod schema — not 20), category selection (dropdown populated from `GET /api/marketplace/categories`).
|
||
3. **Step 2 — Details** (`steps/request-details-step.tsx`): optional product link, size, color, quantity, free-form specifications (key/value pairs), AI-assisted description generation (calls `POST /api/ai/generate-description` if the user clicks the magic-wand button — see `backend/src/services/ai/`).
|
||
4. **Step 3 — Budget** (`steps/request-budget-step.tsx`): min/max in chosen currency (default USDT), urgency (`low | medium | high | urgent`), preferred sellers (typeahead bound to `GET /api/marketplace/sellers`; `"all"` means public).
|
||
5. **Step 4 — Review** (`steps/request-review-step.tsx`): summary; user can attach a saved address (`GET /api/addresses`) or enter a one-off `deliveryInfo.address`. Upload optional attachments via `POST /api/marketplace/purchase-requests/:id/attachments` — returns URLs persisted into `attachments[]`.
|
||
6. **Draft vs. publish** — The wizard always POSTs on submit; drafts are not first-class today (the local wizard state is the "draft"). The persisted record is immediately `status: "pending"` and visible to sellers.
|
||
|
||
### Submission
|
||
|
||
7. Frontend POSTs `POST /api/marketplace/purchase-requests` with the full payload (`PurchaseRequestCreateData` in `PurchaseRequestService.ts:73-106`).
|
||
8. Backend `PurchaseRequestService.createPurchaseRequest` (`:123-188`):
|
||
- **Duplicate-guard** (`:128-143`): rejects a request with identical `buyerId`, `title`, `description` within the last 5 minutes. Returns `Error("درخواست مشابه در ۵ دقیقه گذشته ایجاد شده است")`.
|
||
- **Sanitise `preferredSellerIds`** (`:146-150`): drops literal `"all"` and any invalid ObjectIds.
|
||
- **`isPublic`** is `true` when the cleaned array is empty OR the original payload included `"all"`. Public requests are visible to every active seller; private requests only to listed sellers.
|
||
- Builds and saves the `PurchaseRequest` document with `status: "pending"`.
|
||
9. **Notify the buyer**: `notificationService.notifyPurchaseRequestCreated()` fires asynchronously (no `await`) — an info notification appears in the buyer's bell-icon dropdown.
|
||
10. **Fan-out to sellers** (`notifyAllSellersAboutNewRequest`, `:190-249`):
|
||
- If `isPublic`: emits `new-purchase-request` to the shared **`sellers` room** (all connected sellers receive it in a single emit — no per-seller iteration for the socket event itself).
|
||
- For per-seller in-app notifications (bell icon): `User.find({ role: "seller", status: "active" })` OR only the curated `preferredSellerIds`.
|
||
- Iterates with **50 ms stagger** between notification writes to avoid overwhelming Mongo.
|
||
- For each seller: `notificationService.createNotification(...)` writes a `Notification` doc AND emits via Socket.IO (`actionUrl: /dashboard/seller/marketplace/request/{id}`).
|
||
11. **Real-time fan-out** is also performed when sellers eventually act on the request (offers, payments) via `emitPurchaseRequestUpdate(requestId, eventType, data)` (`PurchaseRequestService.ts:53-71`) and `emitOfferUpdate` in [[Seller Offer Flow]].
|
||
|
||
### Visibility filter
|
||
|
||
When a seller hits `GET /api/marketplace/purchase-requests?sellerId=...`, `PurchaseRequestService.getPurchaseRequests` (`:251-364`) applies a per-status visibility filter:
|
||
|
||
| Request status | Visible to seller if |
|
||
|---|---|
|
||
| `pending` | `isPublic` OR seller ∈ `preferredSellerIds` |
|
||
| `received_offers`, `in_negotiation` | seller has an offer for the request OR no offer is selected yet AND (public/preferred) |
|
||
| `payment`, `processing`, `delivery`, `delivered`, `confirming`, `seller_paid`, `completed` | seller is the **selected** seller (their offer is `selectedOfferId`) |
|
||
|
||
## Sequence diagram
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
autonumber
|
||
actor B as Buyer
|
||
participant FE as Frontend Wizard
|
||
participant BE as Backend
|
||
participant DB as MongoDB
|
||
participant N as NotificationService
|
||
participant IO as Socket.IO
|
||
actor S1 as Seller (n sellers)
|
||
|
||
B->>FE: Open /dashboard/request/new
|
||
loop Steps 1-4
|
||
B->>FE: Fill basic / details / budget / review
|
||
FE-->>FE: Local validation
|
||
end
|
||
opt AI assist
|
||
FE->>BE: POST /api/ai/generate-description
|
||
BE-->>FE: { description }
|
||
end
|
||
opt attachments
|
||
FE->>BE: POST /api/marketplace/purchase-requests/:id/attachments
|
||
BE-->>FE: { url }
|
||
end
|
||
B->>FE: Click "Publish"
|
||
FE->>BE: POST /api/marketplace/purchase-requests
|
||
BE->>DB: Duplicate check (same title+desc in 5m?)
|
||
BE->>BE: clean preferredSellerIds
|
||
BE->>BE: compute isPublic
|
||
BE->>DB: PurchaseRequest.create({status: "pending"})
|
||
DB-->>BE: savedRequest
|
||
BE->>N: notifyPurchaseRequestCreated(buyer, requestId)
|
||
par fan-out to sellers (staggered 50ms for DB writes)
|
||
BE->>IO: emit 'new-purchase-request' to 'sellers' room (public requests)
|
||
BE->>DB: User.find({role:"seller", status:"active"}) (or preferred)
|
||
BE->>N: createNotification(seller_i, ...)
|
||
N->>IO: emit user-{seller_i} 'new-notification'
|
||
N->>DB: Notification.create
|
||
end
|
||
BE-->>FE: 201 { request }
|
||
FE-->>B: Redirect /dashboard/buyer/requests/{id}
|
||
IO-->>S1: 'new-purchase-request' (sellers room) + 'new-notification' (per-user)
|
||
```
|
||
|
||
## API calls
|
||
|
||
| Method | Endpoint | Purpose |
|
||
|---|---|---|
|
||
| `POST` | `/api/marketplace/purchase-requests` | Create the request |
|
||
| `GET` | `/api/marketplace/categories` | Step 1 dropdown |
|
||
| `GET` | `/api/marketplace/sellers` | Step 3 preferred-sellers typeahead |
|
||
| `GET` | `/api/addresses` | Step 4 saved addresses |
|
||
| `POST` | `/api/marketplace/purchase-requests/:id/attachments` | Attachments upload |
|
||
| `POST` | `/api/ai/generate-description` | Optional AI-assisted description |
|
||
| `GET` | `/api/marketplace/purchase-requests` | Listing (buyer's own and seller's filtered view) |
|
||
| `GET` | `/api/marketplace/purchase-requests/:id` | Detail page (joins payment data) |
|
||
| `PATCH` | `/api/marketplace/purchase-requests/:id` | Generic update (status, attachments, etc.) |
|
||
| `DELETE` | `/api/marketplace/purchase-requests/:id` | Cancel (only before payment) |
|
||
|
||
> [!bug] ⚠️ KNOWN BUG — PUT vs PATCH mismatch
|
||
> The frontend `updatePurchaseRequest` action sends `PUT /api/marketplace/purchase-requests/:id`, but the backend only registers a `PATCH` handler for that route. The `PUT` call will receive a `404` or `405` response. The backend handler must be updated to also accept `PUT`, or the frontend action must be changed to use `PATCH`.
|
||
|
||
> [!warning] ⚠️ NOT IMPLEMENTED — Frontend actions with no backend endpoints
|
||
> The following frontend actions target backend routes that do not exist:
|
||
> - `searchPurchaseRequests` → `GET /marketplace/purchase-requests/search` — this endpoint does not exist. Use query parameters on the standard list endpoint (`GET /api/marketplace/purchase-requests?q=...`) instead.
|
||
> - `getMarketplaceStats` → `GET /marketplace/purchase-requests/stats` — this endpoint does not exist. No stats aggregation route is registered.
|
||
|
||
## Database writes
|
||
|
||
- **`purchaserequests` collection**: full insert. Subsequent status transitions and `selectedOfferId` updates happen in [[Seller Offer Flow]], [[PRD - Request Network In-House Checkout]], and [[Delivery Confirmation Flow]].
|
||
- **`notifications` collection**: one per notified seller plus one for the buyer.
|
||
- **`users.referralStats`** is not touched at request creation.
|
||
|
||
## Socket events emitted
|
||
|
||
- **`new-purchase-request`** → `sellers` room for public purchase requests (shared room, single broadcast; emitted by `notifyAllSellersAboutNewRequest`).
|
||
- **`new-notification`** → `user-{sellerId}` for each notified seller (via `NotificationService.emitRealTimeNotification`).
|
||
- **`purchase-request-update`** → `request-{id}` on status changes (`emitPurchaseRequestUpdate`, `PurchaseRequestService.ts:53-71`). Cancellation emits this event with `eventType: 'status-changed'` — there is **no** separate `request-cancelled` event.
|
||
- **`seller-offer-update`** → `seller-{id}` when an offer is created against this request (see [[Seller Offer Flow]]).
|
||
|
||
### Socket room join/leave events
|
||
|
||
| Event | Direction | Emitted by |
|
||
|---|---|---|
|
||
| `join-request-room` | client → server | Buyer detail page on mount (subscribes to `request-{id}`) |
|
||
| `join-seller-room` | client → server | `useSellerMarketplaceSocket` on mount |
|
||
| `leave-seller-room` | client → server | `useSellerMarketplaceSocket` on unmount |
|
||
| `join-buyer-room` | client → server | Buyer socket hook on mount |
|
||
| `leave-buyer-room` | client → server | Buyer socket hook on unmount |
|
||
|
||
## Side effects
|
||
|
||
- One Mongo write per notification (potentially N+1 for a large seller base — mitigated by the 50 ms stagger). For mass markets this should be batched.
|
||
- The buyer is auto-subscribed to the `request-{id}` Socket.IO room on the detail page mount (frontend emits `join-request-room`).
|
||
- If `urgency === "high"` or `urgency === "urgent"`, the notification message uses the high-priority template — visible in [[Notification Flow]].
|
||
|
||
## Error / edge cases
|
||
|
||
- **Duplicate within 5 minutes** → `400` with Persian message. Prevents double-submit on flaky networks.
|
||
- **Invalid category ObjectId** → `400` from Mongoose validation.
|
||
- **`preferredSellerIds` with invalid ObjectIds** → silently dropped, not an error.
|
||
- **Empty cleaned `preferredSellerIds` + no `"all"` in original** → `isPublic` is `true` (open marketplace). This is the intended fallback.
|
||
- **Buyer cancels after payment** → blocked by `STATUS_PROGRESSION_ORDER` (cannot move to `cancelled` from `processing`+ without admin intervention; in practice cancellations after payment must go through [[Dispute Flow]]).
|
||
- **Notification fan-out failure for one seller** → logged and resolved as `false`; the overall request creation still succeeds.
|
||
- **Invalid status progression on PATCH** → `400 Invalid status progression` (`PurchaseRequestService.ts:418-424`).
|
||
- **Seller calls GET listing without `sellerId` query** → logs `"No sellerId provided - returning ALL requests!"` (`:348`) and returns the full set. Frontend always supplies `sellerId` for seller dashboards; missing it is a bug worth catching.
|
||
|
||
> [!tip] Status progression is forward-only
|
||
> Once `status` reaches `payment`, you cannot put it back to `received_offers` even via PATCH. The only escape hatches are the terminal statuses (`cancelled`) and admin tools.
|
||
|
||
## Linked flows
|
||
|
||
- [[RequestTemplate]] checkout — seller chooses physical vs online delivery on the template; buyer checkout collects only the required address/email details and `batch-convert` creates one [[PurchaseRequest]] per seller/template group.
|
||
- [[Seller Offer Flow]] — sellers respond to the published request.
|
||
- [[Negotiation Flow]] — counter-offer mechanics in `in_negotiation`.
|
||
- [[PRD - Request Network In-House Checkout]] — buyer pays for the accepted offer.
|
||
- [[Delivery Confirmation Flow]] — seller ships, buyer confirms.
|
||
- [[Dispute Flow]] — escape hatch for failed deliveries.
|
||
- [[Notification Flow]] — backbone of the seller fan-out.
|
||
|
||
## Source files
|
||
|
||
- Backend: `backend/src/services/marketplace/PurchaseRequestService.ts`
|
||
- Backend: `backend/src/services/marketplace/marketplaceController.ts`
|
||
- Backend: `backend/src/services/marketplace/controllerRoutes.ts`
|
||
- Backend: `backend/src/models/PurchaseRequest.ts`
|
||
- Frontend: `frontend/src/app/dashboard/request/new/page.tsx`
|
||
- Frontend: `frontend/src/sections/request/components/request-form-wizard.tsx`
|
||
- Frontend: `frontend/src/sections/request/components/steps/` (4 step files)
|
||
- Frontend: `frontend/src/sections/request/view/buyer-request-view.tsx`
|