Initial commit: nick docs
This commit is contained in:
moojttaba
410
06 - Usage/User Guide.md
Normal file
410
06 - Usage/User Guide.md
Normal file
@@ -0,0 +1,410 @@
|
||||
---
|
||||
title: User Guide
|
||||
tags: [usage, role/buyer]
|
||||
audience: Buyer
|
||||
created: 2026-05-23
|
||||
---
|
||||
|
||||
# User Guide (Buyer)
|
||||
|
||||
End-to-end usage of the Amn marketplace for a **Buyer** — the person who creates purchase requests and pays sellers via crypto escrow.
|
||||
|
||||
> [!info]
|
||||
> Looking for a different role? See [[Seller Guide]], [[Admin Guide]], [[Support Guide]].
|
||||
|
||||
---
|
||||
|
||||
## 1. Creating your account
|
||||
|
||||
### 1.1 Sign up
|
||||
|
||||
1. Visit **`/auth/jwt/sign-up`**.
|
||||
2. Enter:
|
||||
- **Email** (will receive a verification code)
|
||||
- **Password** (≥ 8 chars; mix of letters/digits/symbol recommended)
|
||||
- **Role**: choose **Buyer**. (You can later add Seller capabilities — see [[Seller Guide]].)
|
||||
3. Optional: enter a **referral code** if a friend invited you (you'll both earn points — see [[Referral Flow]]).
|
||||
4. Accept Terms of Service.
|
||||
5. Click **Sign up** → you'll receive an email with a 6-digit code.
|
||||
|
||||
> [!warning]
|
||||
> Codes expire in 1 hour. If yours expires, click **Resend code** on the verify page.
|
||||
|
||||
Alternative sign-up methods:
|
||||
|
||||
- **Sign in with Google** — single-click using your Google account ([[Google OAuth Flow]]).
|
||||
- **Passkey / Touch ID / Face ID** — passwordless after first sign-up ([[Passkey (WebAuthn) Flow]]).
|
||||
|
||||
### 1.2 Verify your email
|
||||
|
||||
1. Open the verification email and copy the 6-digit code.
|
||||
2. Paste into the **Verify** page (`/auth/jwt/verify`).
|
||||
3. Click **Verify**.
|
||||
4. You land on the dashboard.
|
||||
|
||||
> [!tip]
|
||||
> Until verified, a yellow banner appears on every page asking you to verify. Some actions (paying, opening disputes) are gated behind email verification.
|
||||
|
||||
### 1.3 Complete your profile
|
||||
|
||||
Go to **Dashboard → Account → Profile** and fill in:
|
||||
|
||||
| Field | Why it matters |
|
||||
|---|---|
|
||||
| Display name | Shown to sellers in chat / on offers |
|
||||
| Avatar | Helps sellers recognize repeat buyers |
|
||||
| Phone number | Used for delivery coordination (optional) |
|
||||
| Country / Language | Sets default currency display & language |
|
||||
|
||||
---
|
||||
|
||||
## 2. Adding addresses
|
||||
|
||||
Delivery addresses are required before some sellers will accept your offer.
|
||||
|
||||
1. **Dashboard → Account → Address**.
|
||||
2. Click **+ Add address**.
|
||||
3. Fill in: label (Home, Office, …), recipient name, country, full address, postal code, phone.
|
||||
4. Set one as **Primary** — it will be auto-filled into new purchase requests.
|
||||
5. You can add up to **N** addresses (depending on tier).
|
||||
|
||||
---
|
||||
|
||||
## 3. Connecting a wallet
|
||||
|
||||
If you want to pay via **Web3** instead of SHKeeper invoice:
|
||||
|
||||
1. **Dashboard → Account → Wallet**.
|
||||
2. Click **Connect Wallet**.
|
||||
3. Choose **MetaMask** (browser) or **WalletConnect** (mobile).
|
||||
4. Approve the connection request in your wallet.
|
||||
5. The connected address appears as a chip. You can disconnect anytime.
|
||||
|
||||
> [!info]
|
||||
> Connecting a wallet is **optional**. SHKeeper QR payments work without one. See [[Payment Flow - DePay & Web3]].
|
||||
|
||||
---
|
||||
|
||||
## 4. Setting up Passkeys (recommended)
|
||||
|
||||
1. **Dashboard → Account → Passkey**.
|
||||
2. Click **Add passkey**.
|
||||
3. Follow your device's prompt (Touch ID, Face ID, Windows Hello, USB key…).
|
||||
4. Name the passkey ("MacBook", "iPhone 15", …) and save.
|
||||
5. Next sign-in, you'll see a **Sign in with passkey** button.
|
||||
|
||||
Multiple passkeys can be added — one per device.
|
||||
|
||||
---
|
||||
|
||||
## 5. Browsing the marketplace
|
||||
|
||||
| Where | What you see |
|
||||
|---|---|
|
||||
| **`/shop`** | Public list of sellers & featured items |
|
||||
| **`/shop/[seller]`** | A specific seller's shop |
|
||||
| **`/shop/[seller]/[id]`** | An item / request template detail |
|
||||
| **`/post`** | Blog posts (announcements, tutorials) |
|
||||
| **Dashboard → Overview** | Your personalised dashboard |
|
||||
|
||||
---
|
||||
|
||||
## 6. Creating a Purchase Request
|
||||
|
||||
A **Purchase Request** is a description of what you want to buy. Sellers see open requests and submit offers.
|
||||
|
||||
### 6.1 From scratch
|
||||
|
||||
1. **Dashboard → Request → + New Request**.
|
||||
2. Fill in the multi-step form:
|
||||
- **Step 1 — Basics**: title, category, sub-category.
|
||||
- **Step 2 — Details**: rich description (use the editor — markdown, images), budget range, currency.
|
||||
- **Step 3 — Delivery**: pick an address, preferred delivery date.
|
||||
- **Step 4 — Attachments**: upload reference photos, spec sheets (max 5 MB each).
|
||||
- **Step 5 — Visibility**: public (any seller can offer) or invite-only (specific sellers).
|
||||
3. Click **Save as draft** to come back later, or **Publish** to make it live.
|
||||
|
||||
> [!tip]
|
||||
> Use the **AI-assist** button next to the description field — it suggests phrasing improvements (uses OpenAI). See [[AI API]].
|
||||
|
||||
### 6.2 From a template
|
||||
|
||||
If a seller shared a request template URL:
|
||||
|
||||
1. Open the link (or **Dashboard → Request → From template**).
|
||||
2. Pre-filled with the seller's defaults.
|
||||
3. Tweak quantity / customisations.
|
||||
4. Publish — the original seller is automatically invited.
|
||||
|
||||
See [[Purchase Request Flow]] for the full state machine.
|
||||
|
||||
### 6.3 Managing your requests
|
||||
|
||||
**Dashboard → Request** shows all your requests with status:
|
||||
|
||||
| Status | Meaning |
|
||||
|---|---|
|
||||
| Draft | Saved, not yet published |
|
||||
| Open | Live; sellers can offer |
|
||||
| In negotiation | At least one offer received, conversation active |
|
||||
| Accepted | You accepted an offer; awaiting payment |
|
||||
| Funded | Payment in escrow; awaiting delivery |
|
||||
| Shipped | Seller marked as shipped |
|
||||
| Delivered | You confirmed receipt; escrow released |
|
||||
| Completed | Closed; can leave a review |
|
||||
| Disputed | A dispute is open |
|
||||
| Cancelled | Cancelled before payment |
|
||||
| Refunded | Money returned (dispute outcome) |
|
||||
| Expired | Open too long with no acceptable offers |
|
||||
|
||||
Click a request to:
|
||||
|
||||
- See offers (compare prices, delivery times, seller ratings).
|
||||
- Chat with a specific seller.
|
||||
- Edit (only while in **Draft** or **Open**).
|
||||
- Cancel (only while no payment is in flight).
|
||||
|
||||
---
|
||||
|
||||
## 7. Receiving and reviewing offers
|
||||
|
||||
When a seller submits an offer:
|
||||
|
||||
1. You get a **notification** (bell badge + email if enabled).
|
||||
2. Click into the request → **Offers** tab.
|
||||
3. Compare offers side-by-side:
|
||||
- Price
|
||||
- Delivery time
|
||||
- Seller rating + completed orders
|
||||
- Optional notes (use of materials, brand, etc.)
|
||||
|
||||
### 7.1 Negotiate
|
||||
|
||||
Each offer has a **Chat** button. Use it to:
|
||||
|
||||
- Ask clarifying questions.
|
||||
- Request a counter-offer (lower price, faster delivery).
|
||||
- Discuss customisations.
|
||||
|
||||
The seller can issue a **counter-offer** which appears as a new offer entry on the same chat. See [[Negotiation Flow]].
|
||||
|
||||
### 7.2 Accept
|
||||
|
||||
Click **Accept this offer** → confirmation modal → **Confirm**.
|
||||
|
||||
Effects:
|
||||
- All other open offers on this request are auto-rejected.
|
||||
- The request status moves to **Accepted**.
|
||||
- The chat continues with this seller only.
|
||||
- You are prompted to pay.
|
||||
|
||||
---
|
||||
|
||||
## 8. Paying for an order
|
||||
|
||||
Two payment paths. Pick at the **Pay** step.
|
||||
|
||||
### 8.1 Path A — SHKeeper invoice (recommended for non-crypto-native users)
|
||||
|
||||
1. Click **Pay with crypto invoice**.
|
||||
2. Choose a token + network (e.g., USDT on BSC).
|
||||
3. A QR code + address appears.
|
||||
4. Open your wallet (any wallet that supports the network).
|
||||
5. Scan the QR, send the exact amount, confirm in your wallet.
|
||||
6. The page updates in real-time as the blockchain confirms (typically 30s–5 min).
|
||||
7. Status moves to **Funded** when fully confirmed.
|
||||
|
||||
> [!warning]
|
||||
> Send the **exact** amount on the **exact** network. Sending USDT on the wrong network (e.g., ERC-20 instead of BSC) WILL lose your funds. The displayed network is binding.
|
||||
|
||||
See [[Payment Flow - SHKeeper]].
|
||||
|
||||
### 8.2 Path B — Direct Web3 wallet
|
||||
|
||||
1. Click **Pay from connected wallet** (requires a connected wallet — see §3).
|
||||
2. Your wallet pops up a transaction approval (token transfer to escrow address).
|
||||
3. Approve & sign.
|
||||
4. Wait for on-chain confirmation.
|
||||
5. Backend verifies the transaction and moves status to **Funded**.
|
||||
|
||||
See [[Payment Flow - DePay & Web3]].
|
||||
|
||||
---
|
||||
|
||||
## 9. Tracking the order
|
||||
|
||||
Once **Funded**, the seller is notified to ship.
|
||||
|
||||
1. Seller marks the order **Shipped** — you receive a notification + optional tracking number.
|
||||
2. When you receive the item, return to the request page → **Confirm receipt**.
|
||||
3. This releases the escrow to the seller and moves status to **Delivered**.
|
||||
|
||||
See [[Delivery Confirmation Flow]].
|
||||
|
||||
> [!warning]
|
||||
> Only confirm after you've received and inspected the item. Confirming is **irreversible** — to reverse, you must open a dispute.
|
||||
|
||||
---
|
||||
|
||||
## 10. Opening a dispute
|
||||
|
||||
If something is wrong (item not as described, never arrived, wrong quantity…):
|
||||
|
||||
1. On the request page → **Open dispute**.
|
||||
2. Choose a reason (Not received / Damaged / Not as described / Other).
|
||||
3. Upload evidence (photos, screenshots — max 5 MB each).
|
||||
4. Write a clear narrative.
|
||||
5. Submit.
|
||||
|
||||
An **admin mediator** is assigned within 24 hours. You and the seller will both be able to chat with the mediator and submit additional evidence.
|
||||
|
||||
Possible outcomes:
|
||||
|
||||
- **Full refund** — escrow returns to you.
|
||||
- **Partial refund** — split between you and seller.
|
||||
- **Release to seller** — your dispute is denied; escrow goes to seller.
|
||||
- **Mutual cancellation** — both parties agree to refund.
|
||||
|
||||
See [[Dispute Flow]].
|
||||
|
||||
---
|
||||
|
||||
## 11. Rating
|
||||
|
||||
After the order is **Completed** (delivered or dispute resolved):
|
||||
|
||||
1. You're prompted to leave a rating + review.
|
||||
2. Stars 1–5, plus a free-text comment (optional but encouraged).
|
||||
3. The seller also rates you.
|
||||
|
||||
Ratings affect seller reputation (visible on their shop page). See [[Rating Flow]].
|
||||
|
||||
---
|
||||
|
||||
## 12. Earning & spending points
|
||||
|
||||
Points are earned via:
|
||||
|
||||
- Sign-up bonus
|
||||
- Each completed purchase (X points per $1 — see [[LevelConfig]] for tiers)
|
||||
- Referrals (you and the referred friend both get points)
|
||||
- Special bonuses (admin-awarded for promotions)
|
||||
|
||||
**Dashboard → Points** shows:
|
||||
|
||||
- **Balance** — current points
|
||||
- **Transactions** — history
|
||||
- **Levels** — current tier + benefits + next-tier threshold
|
||||
- **Referrals** — your unique referral link + invited friends
|
||||
|
||||
Higher levels unlock:
|
||||
|
||||
- Discount % on platform fee
|
||||
- Priority support
|
||||
- Free shipping (on partnered sellers)
|
||||
- Special offers / early access
|
||||
|
||||
Spend points by selecting "Use points" at checkout (subject to seller acceptance).
|
||||
|
||||
See [[Referral Flow]] and the [[PointTransaction]] model.
|
||||
|
||||
---
|
||||
|
||||
## 13. Settings
|
||||
|
||||
### 13.1 Theme & display
|
||||
|
||||
Click the **cog** icon in the topbar to open the **Settings drawer**:
|
||||
|
||||
- Light / Dark / System mode
|
||||
- Color preset
|
||||
- Layout (Vertical / Mini / Horizontal)
|
||||
- Direction (auto from language, override possible)
|
||||
- Font family
|
||||
- Border radius
|
||||
|
||||
See [[Settings & Theming]].
|
||||
|
||||
### 13.2 Language
|
||||
|
||||
Click the **flag chip** in the topbar to switch language. Persian and Arabic automatically flip the UI to RTL. See [[Internationalization & RTL]].
|
||||
|
||||
### 13.3 Notifications
|
||||
|
||||
**Dashboard → Account → Notifications**:
|
||||
|
||||
- Email notifications (on/off per category)
|
||||
- In-app notifications (cannot be fully disabled)
|
||||
- Push notifications (browser permission required)
|
||||
|
||||
### 13.4 Security
|
||||
|
||||
**Dashboard → Account → Security**:
|
||||
|
||||
- Change password
|
||||
- Manage passkeys
|
||||
- View active sessions / sign out elsewhere
|
||||
- Two-factor authentication (if enabled)
|
||||
|
||||
---
|
||||
|
||||
## 14. Common issues
|
||||
|
||||
### "I can't sign in"
|
||||
|
||||
1. Confirm you're using the correct email.
|
||||
2. Click **Forgot password** to reset.
|
||||
3. If multiple failed attempts, the account is **temporarily locked** for cooldown.
|
||||
4. If issue persists, contact support — see [[Support Guide]].
|
||||
|
||||
### "My email verification didn't arrive"
|
||||
|
||||
1. Check spam folder.
|
||||
2. Click **Resend code** on the verify page.
|
||||
3. Try a different email if the issue persists.
|
||||
|
||||
### "I sent USDT on the wrong network"
|
||||
|
||||
> [!warning]
|
||||
> If you sent the wrong token/network combination, funds are likely **unrecoverable**. Contact support immediately with the transaction hash — recovery may be possible if the receive address is shared across networks.
|
||||
|
||||
### "The page froze / I see stale data"
|
||||
|
||||
1. Refresh the page.
|
||||
2. If issue persists, paste the following in browser DevTools console (it clears stuck localStorage state):
|
||||
```js
|
||||
// From frontend/cleanup-localstorage.js
|
||||
Object.keys(localStorage).filter(k => /^(manual-payment|buyer-step|LAST_(PAYMENT|TEMPLATE|SOCKET))-/.test(k)).forEach(k => localStorage.removeItem(k));
|
||||
```
|
||||
3. Refresh.
|
||||
|
||||
### "I can't pay — wallet won't connect"
|
||||
|
||||
1. Make sure your wallet extension is installed and unlocked.
|
||||
2. Confirm you're on a **supported network** (BSC, Polygon, Ethereum, Sepolia).
|
||||
3. Try WalletConnect (QR code) on mobile.
|
||||
|
||||
### "I want to delete my account"
|
||||
|
||||
Contact support — account deletion is a manual operation by admins to ensure all funds and disputes are cleared first.
|
||||
|
||||
---
|
||||
|
||||
## 15. Tips & best practices
|
||||
|
||||
> [!tip]
|
||||
> - Save offers as drafts and revisit before publishing — it's harder to edit live requests.
|
||||
> - Read seller ratings AND read recent reviews (not just the score).
|
||||
> - Use chat early to clarify expectations — fewer disputes later.
|
||||
> - Confirm receipt only after physical inspection.
|
||||
> - Take photos at unboxing for evidence in case of dispute.
|
||||
> - Keep your wallet seed phrase offline.
|
||||
|
||||
---
|
||||
|
||||
## 16. Related
|
||||
|
||||
- [[Seller Guide]] · [[Admin Guide]] · [[Support Guide]]
|
||||
- Flows: [[Authentication Flow]] · [[Registration Flow]] · [[Purchase Request Flow]] · [[Payment Flow - SHKeeper]] · [[Payment Flow - DePay & Web3]] · [[Delivery Confirmation Flow]] · [[Dispute Flow]] · [[Rating Flow]] · [[Referral Flow]]
|
||||
- Models: [[User]] · [[PurchaseRequest]] · [[Payment]] · [[Address]]
|
||||
- [[Glossary]]
|
||||
Reference in New Issue
Block a user