nick/nick-doc
3
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

Initial commit: nick docs

Browse Source
This commit is contained in:
moojttaba
2026-05-23 20:35:34 +03:30
commit 0da235ae27
90 changed files with 18268 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

435
06 - Usage/Admin Guide.md Normal file
View File

@@ -0,0 +1,435 @@
---
title: Admin Guide
tags: [usage, role/admin]
audience: Admin
created: 2026-05-23
---
# Admin Guide
Operational usage for **Admin** users — moderation, dispute mediation, payment ops, blog management, system oversight.
> [!info]
> Looking for a different role? See [[User Guide]] (Buyer), [[Seller Guide]] (Owner), [[Support Guide]].
---
## 1. Default admin credentials
In a freshly-seeded environment (dev or first prod boot with `AUTO_SEED_ON_START=true`):
| Email | Password | Role |
|---|---|---|
| `admin@marketplace.com` | `Moji6364` | admin |
> [!warning]
> Change this password immediately in production. The default values are committed to the seed scripts.
Sign in at `/auth/jwt/sign-in` like any other user. The dashboard sidebar will surface admin-only sections.
---
## 2. Admin dashboard overview
**Dashboard → Overview** for admin shows aggregated platform KPIs:
| Tile | Metric | Source |
|---|---|---|
| Active users (30d) | Distinct logins | Users collection |
| New registrations (today / 7d / 30d) | Signups | TempVerification + User |
| Open requests | Status = open | PurchaseRequest |
| In-flight payments | Status = pending or processing | Payment |
| Open disputes | Status = open | Dispute |
| Revenue (fees) | Platform commission ledger | Payment + ShopSettings |
| Pending approvals | New seller verifications, blog drafts | various |
> [!tip]
> Click any KPI tile to drill into the filtered list.
---
## 3. User management
### 3.1 List users
**Dashboard → User → List**:
- DataGrid with: email, name, role, status, joined date, last activity, points balance, kyc state.
- Filters: role, status (active/banned/pending verification), country, signup-date range.
- Search: email, name, phone.
- Export to CSV (admin-only action).
### 3.2 Edit a user
Click a user row → **Edit**:
- Change role (e.g., promote to seller, demote to buyer, grant admin).
- Manually verify email.
- Reset password (sends a reset code to their email).
- Adjust points balance (audited).
- Ban / unban.
- View linked addresses, payment methods, devices.
> [!warning]
> Role escalation is logged in the audit trail. Granting admin rights should be limited and reversible — use `support` for less-privileged staff (see [[Support Guide]]).
### 3.3 Create a user (admin-only)
**User → New** lets you provision an account without email verification (useful for migrating staff or VIP onboarding).
### 3.4 Ban a user
1. Open user row → **Ban**.
2. Provide a reason (logged + emailed to user).
3. Optional: auto-resolve all their open requests/offers (recommended for fraud cases).
A banned user:
- Cannot sign in.
- Their open offers are withdrawn.
- Their open requests are cancelled.
- Their funds in escrow are NOT auto-released — handle through disputes.
---
## 4. Listing & content moderation
### 4.1 Purchase Request review
Public requests are typically auto-published, but admin can review:
**Marketplace → Requests → Filter status: Open**. Look for:
- Suspicious wording (drugs, weapons, prohibited items — block list TBD)
- Unrealistic prices (likely scams)
- Foreign language abuse
Action: **Hide** (sets visibility off without deleting), or **Force-cancel** with reason.
### 4.2 Seller Template review
**Marketplace → Templates** — sellers' shareable templates. Same scrutiny as requests. Reject with reason; the seller is notified.
### 4.3 Blog post review
Admin owns blog content:
**Dashboard → Post → List**:
- Drafts, published, archived
- New: `Post → New` → TipTap editor → fill title, slug, category, cover image, body, SEO meta → **Publish**.
- Edit existing: same flow.
- Comments moderation (if comments enabled): approve / reject / spam.
---
## 5. Dispute mediation
The most critical admin function.
### 5.1 Dispute queue
**Dashboard → Disputes** lists every dispute with:
- Reason
- Status (open / awaiting evidence / under review / resolved)
- Buyer & seller links
- Amount in escrow
- Days open
- Last action
Sort by **Days open desc** to handle aging cases first.
### 5.2 Picking up a dispute
Click a dispute → **Assign to me** (or it's auto-assigned on first open).
You'll see:
- Buyer's claim + evidence
- Seller's response + evidence
- Full chat history between buyer/seller
- Order timeline (payment, shipment, confirmation actions)
- Payment & escrow status
### 5.3 Communicating
A 3-way chat exists in the dispute view:
- Send a message visible to both parties ("Please clarify…").
- Send a message visible to one party only (rare).
- Request additional evidence.
### 5.4 Resolving
When you have enough information, click **Resolve**:
| Resolution | What happens |
|---|---|
| **Refund buyer (100%)** | Escrow returned to buyer; seller marked at-fault |
| **Refund buyer (partial)** | Specify split; e.g., 70% buyer, 30% seller |
| **Release to seller** | Buyer's claim denied; full payout to seller |
| **Mutual cancel** | Buyer & seller agreed to refund |
You MUST write a resolution narrative explaining your reasoning. Both parties see this.
> [!warning]
> Resolutions are **irreversible** in the system. Triple-check the split before confirming.
See [[Dispute Flow]] and the [[Dispute]] model.
### 5.5 Pattern detection
If you see repeat disputes against the same seller (or repeat frivolous disputes from the same buyer), check:
- **Dashboard → User → [profile] → History** for past disputes.
- Consider banning persistent bad actors after review.
---
## 6. Payment operations
### 6.1 Payment monitoring
**Dashboard → Payment → List** shows all payments with filters by status, provider, network, time range.
Watch for:
- **Stuck payments** (pending > 1h) — SHKeeper webhook may have failed; check logs.
- **Failed webhooks** — SHKeeper retried but signature didn't verify; see [[Payment API]].
- **Missing tx hashes** on completed payments — run the repair script (see §6.3).
### 6.2 Manual payout
For sellers who can't access self-service or for one-off ops:
1. **Payment → Payout → New**.
2. Fields: recipient address, amount, token (USDT…), network (BSC…), reference, description.
3. Submit → ts-node script also exists at `backend/manual-payout-test.ts` for local testing.
Behind the scenes this calls SHKeeper's payout endpoint. See [[Payout Flow]].
### 6.3 Fix missing transaction hashes
Some completed payments may lack the on-chain tx hash (webhook race, partial confirmation). Run:
```bash
cd /Users/mojtabaheidari/code/backend
node fix-transaction-hashes.js
```
The script polls SHKeeper for each affected invoice and patches `transactionHash` + `blockchain.transactionHash` in MongoDB.
See [[Scripts]] for the full inventory.
### 6.4 Refunds
Issued automatically when a dispute resolves to "refund buyer". For manual refunds (e.g., goodwill):
1. **Payment → [payment] → Refund**.
2. Specify amount (full or partial).
3. Confirm. The refund triggers a payout-style return to the buyer's address.
---
## 7. Loyalty / Points system
### 7.1 Levels
**Dashboard → Points → Levels** (admin view):
- View all `LevelConfig` tiers.
- Edit thresholds (points required).
- Edit benefits (discount %, perks).
- Add / archive levels.
See [[LevelConfig]] model.
### 7.2 Award bonus points
For promotions, contests, makegoods:
1. **Points → Award bonus**.
2. Pick a user (by email).
3. Amount + reason (logged in audit).
4. Submit → user is notified.
Recorded as a `PointTransaction` with `source: 'admin'`.
### 7.3 Audit point transactions
**Points → Transactions** with admin filter shows every earn / spend / expire / admin-adjust event for any user.
---
## 8. Category management
**Marketplace → Categories** (or a dedicated admin area):
- Add new category (Persian name + English name + icon + parent for sub-categories).
- Edit / archive.
- Reorder (drag-drop).
- Seed initial set via `npm run seed:categories`.
See [[Category]] model.
---
## 9. System health & ops
### 9.1 Healthcheck
```bash
curl https://amn.gg/health
# → { "status": "ok", "uptime": 12345, "db": "connected", "redis": "connected" }
```
(Confirm exact shape from `backend/src/app.ts`.)
Healthcheck is also wired into Docker (`HEALTHCHECK` in `backend/Dockerfile.prod`), so a failing healthcheck restarts the container automatically.
### 9.2 Container status
On the host:
```bash
docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Image}}'
# nickapp-backend Up 2h (healthy) git.manko.yoga/manawenuz/escrow-backend:latest
# nickapp-frontend Up 2h (healthy) …/frontend:latest
# nickapp-nginx Up 2h nginx:alpine
# nickapp-mongodb Up 2h (healthy) mongo:8.0
# nickapp-redis Up 2h (healthy) redis:8-alpine
```
### 9.3 Logs
```bash
docker logs -f --tail 200 nickapp-backend
docker logs -f --tail 200 nickapp-frontend
docker logs -f --tail 200 nickapp-nginx
```
Sentry collects unhandled errors with full context. See [[Monitoring]].
### 9.4 Restart
```bash
docker compose -f /path/to/docker-compose.production.yml restart nickapp-backend
```
Or roll a new image: push to registry → Watchtower auto-restarts within 5 min.
### 9.5 Database access
```bash
docker exec -it nickapp-mongodb mongosh \
--username "$MONGO_USERNAME" --password "$MONGO_PASSWORD"
use nickapp
db.users.find({ role: 'admin' })
```
> [!warning]
> Direct DB writes bypass all validation, hooks, and audit logging. Use the admin UI whenever possible.
See [[Database Operations]] for the runbook.
---
## 10. Reports & analytics
### 10.1 Built-in admin reports
(If implemented — verify in `backend/src/services/admin/`.)
- **Revenue by month / category / seller**
- **Top sellers by GMV / completion rate**
- **Top buyers by spend**
- **Dispute rate by category / seller**
- **Funnel: signup → first request → first payment**
Export to CSV for offline analysis.
### 10.2 Ad-hoc queries
For complex investigations, use `mongosh` directly (see §9.5).
---
## 11. Communications
### 11.1 System announcement
(If admin has a broadcast UI — check `Notification` model.)
1. Compose message (title, body, link).
2. Audience: all users / specific role / specific list.
3. Send → appears in users' notification drawer and (optionally) emails.
Backed by `notification:received` socket event broadcast to all relevant rooms. See [[Notification Flow]].
### 11.2 Maintenance window
For planned downtime:
1. Post an in-app announcement 24h ahead.
2. At T-15 min, broadcast `system:maintenance` socket event.
3. UI shows a yellow banner: "Maintenance in 15 min — please save your work."
4. Take the system offline (compose stop, deploy, compose start).
See [[Incident Response]] for unplanned ops.
---
## 12. Support escalations
Support agents (see [[Support Guide]]) handle Tier-1 issues. Items that escalate to admin:
- Refund > $X
- Role changes
- Account un-ban
- Suspected fraud / chargeback dispute
- Manual payout exceptions
- Data correction (anything bypassing the UI)
Admins should reply to escalations within 1 business day SLA.
---
## 13. Common admin tasks (quick reference)
| Task | Where |
|---|---|
| Reset a user's password | User → [profile] → Reset password |
| Manually verify a user | User → [profile] → Verify email |
| Promote user to seller | User → [profile] → Edit → role |
| Award points | Points → Award |
| Approve a refund | Payment → [payment] → Refund |
| Resolve a dispute | Disputes → [case] → Resolve |
| Hide a request | Marketplace → [request] → Hide |
| Publish a blog post | Post → [post] → Publish |
| Add a category | Marketplace → Categories → New |
| Check system health | `curl /health` |
---
## 14. Audit & accountability
Every admin action SHOULD be logged. Today the system logs role changes, refunds, point-adjustments, and dispute resolutions in the `Notification` and `PointTransaction` collections with `metadata.actor`. Stronger audit trail (append-only collection with diffs) is on the roadmap.
> [!warning]
> Do NOT use admin powers to read private chats unless required for dispute investigation. Document the case ID and reason for each access.
---
## 15. Operations runbooks (pointers)
When something breaks, see:
- [[Incident Response]] — what to do when the site is down
- [[Backup & Recovery]] — restore from backup
- [[Monitoring]] — what to watch
- [[Database Operations]] — direct DB ops
---
## 16. Related
- [[User Guide]] · [[Seller Guide]] · [[Support Guide]]
- Flows: [[Dispute Flow]] · [[Payout Flow]] · [[Notification Flow]]
- Models: [[User]] · [[Dispute]] · [[Payment]] · [[LevelConfig]] · [[PointTransaction]] · [[Category]] · [[BlogPost]]
- [[Admin API]] · [[Glossary]]

365
06 - Usage/Seller Guide.md Normal file
View File

@@ -0,0 +1,365 @@
---
title: Seller Guide
tags: [usage, role/seller, role/owner]
audience: Seller (Owner)
created: 2026-05-23
---
# Seller Guide (Owner)
End-to-end usage for a **Seller** (Shop Owner) — the person who responds to buyer purchase requests, fulfils orders, and withdraws escrow funds.
> [!info]
> Looking for a different role? See [[User Guide]] (Buyer), [[Admin Guide]], [[Support Guide]].
---
## 1. Becoming a Seller
You can either:
- **Sign up as Seller** at registration (`/auth/jwt/sign-up` → choose role = Seller).
- **Upgrade from Buyer**: existing buyer → **Dashboard → Account → Become a seller** → submit shop info → admin verification.
Either path requires:
- Verified email
- Phone number on file (some regions require KYC)
- Initial shop info (name, country, payout wallet address)
---
## 2. Configuring your shop
### 2.1 Shop branding
**Dashboard → Shop Settings → Settings**:
| Field | Notes |
|---|---|
| Shop name | Public; shown in shop URL `/shop/{slug}` |
| Tagline | One-line summary on the shop card |
| About | Rich-text editor (use the editor for headings, lists, links) |
| Avatar / logo | 256×256 recommended |
| Cover image | 1600×400 recommended |
| Category specialisations | Tag your shop with categories you cover |
| Country / Region | Used for delivery filters |
| Default response time | "I usually respond within X hours" |
| Default delivery window | "Typical fulfilment 3–5 business days" |
### 2.2 Social links
**Shop Settings → Socials**: Twitter, Instagram, Telegram, website. Shown on your public shop page.
### 2.3 Security
**Shop Settings → Security**:
- Withdraw confirmation requires email code (recommended)
- Two-factor authentication
- Login alerts
### 2.4 Payout wallet
**Account → Wallet** or **Shop Settings → Payout**:
- Add a crypto address you control on the supported networks (BSC, Polygon, …).
- All payouts (escrow releases) go here.
- You can change it, but new payouts go to the new address — past payouts are settled to whichever address was active at the time.
> [!warning]
> Your payout address is the **single source of funds out of escrow**. Triple-check it. If it's wrong, funds can be irretrievably lost.
---
## 3. Request Templates
Templates are pre-defined product/service offerings. Buyers can create a request from your template with one click.
### 3.1 Create a template
**Dashboard → Request Templates → + New**:
1. **Title** — what you sell ("Vintage leather jacket", "Custom logo design").
2. **Category** — primary category.
3. **Description** — rich text, use images.
4. **Pricing** — fixed price or "starts at" range. Specify currency.
5. **Delivery window** — typical days from acceptance.
6. **Customisations** — list of options (size, color, quantity) buyers can choose.
7. **Videos** (optional) — embed up to N video URLs.
8. **Default proposal** — your standard offer text that auto-populates when a buyer creates from this template.
9. **Expiration** — leave blank for evergreen; set a date for limited-time offers.
10. **Visibility** — public (anyone can use) or unlisted (shareable URL only).
Click **Publish**. You'll get a shareable URL: `https://amn.gg/shop/{seller}/{templateId}`.
### 3.2 Manage templates
**Dashboard → Request Templates** shows all templates with:
- Status (active / expired / draft)
- Usage count (how many buyers used it → became a real request)
- Conversion rate (used → accepted)
- Quick edit / clone / disable
See [[RequestTemplate]] and [[Purchase Request Flow]].
---
## 4. Finding open buyer requests
Once your shop is configured, you can browse incoming buyer demand.
### 4.1 Public requests
**Dashboard → Shops → Browse** (or via the marketplace surface):
- Filter by category, budget range, delivery deadline, buyer location.
- Sort by recency, budget, urgency.
- Click a request for details.
### 4.2 Invited requests
If a buyer specifically invites you (often via a template URL), the request appears under **Dashboard → Requests → Invited**.
### 4.3 Notifications
- New public request matching your specialisation → notification + email (if enabled).
- Direct invitation → push notification.
---
## 5. Submitting an offer
On a request detail page → **Submit offer**:
1. **Your price** (in the buyer's requested currency).
2. **Delivery window** (days from acceptance).
3. **Notes** (rich text — explain your approach, materials, brand, etc.).
4. **Attachments** (optional — photos of work samples, references).
5. **Expire offer in** (default 7 days) — after which the offer auto-rejects.
Click **Send offer**. The buyer is notified instantly via socket.
> [!tip]
> Offers with personalised notes convert ~3× better than generic ones. Show the buyer you read their request.
See [[Seller Offer Flow]].
---
## 6. Negotiating
The buyer may message you to discuss:
- Lowering your price
- Faster delivery
- Customisations not in your template
You can:
1. **Reply via chat** to explain or negotiate.
2. **Issue a counter-offer** — opens a new offer slot replacing your previous one.
3. **Accept their counter-proposal** if they sent one.
See [[Negotiation Flow]].
---
## 7. Acceptance — what happens
When the buyer accepts your offer:
1. All other sellers' offers on this request are auto-rejected.
2. Status moves to **Accepted**.
3. The buyer is prompted to pay into escrow.
4. You receive a notification.
5. You can prepare to fulfil — but **DO NOT ship until escrow is funded**.
> [!warning]
> Shipping before funding = you have no recourse if buyer never pays. Always wait for status = **Funded**.
---
## 8. Fulfilment
Once status = **Funded**:
1. Prepare the item / service.
2. On the request page → click **Mark as shipped**.
3. Optionally add:
- Tracking number + carrier
- Photos of packed item
- Notes for buyer
4. The buyer is notified.
For digital goods (designs, files): upload via the request's **Deliverables** section. Buyer is notified to confirm.
See [[Delivery Confirmation Flow]].
---
## 9. Getting paid
When the buyer confirms receipt → status = **Delivered** → escrow released.
> [!important]
> Today, escrow release after confirmation triggers a **payout request** which an admin manually processes. See [[Payout Flow]]. Payouts typically clear within 1–2 business days.
### 9.1 Withdraw
**Dashboard → Payment → Payouts** lists pending and processed payouts.
For self-service withdrawal (if enabled):
1. Click **Request payout**.
2. Confirm your payout wallet address.
3. Enter the amount (≤ available balance).
4. Submit.
5. Status moves through **pending → processing → completed**.
Once **completed**, you'll see the on-chain transaction hash linking to a block explorer.
---
## 10. Disputes
If a buyer opens a dispute:
1. You're notified immediately.
2. **The escrow is paused** — neither party can move funds until the dispute resolves.
3. Open the dispute page → review the buyer's claim and evidence.
4. **Submit your evidence**: photos (e.g., shipped item, packaging proof), chat screenshots, tracking confirmation.
5. Write a clear response narrative.
6. An **admin mediator** reviews both sides and issues a decision.
Possible outcomes:
- **Full refund to buyer** (dispute upheld) — you lose the sale + may lose listing if pattern.
- **Partial refund** — split.
- **Release to you** (dispute denied) — full payout proceeds.
- **Mutual cancellation** — agreed refund.
Tips to win disputes:
- Always include proof of shipping with timestamp.
- Save chat screenshots (the platform retains them, but redundant proof helps).
- Respond to disputes within 24 hours.
- Don't argue with the buyer publicly in chat — let the mediator decide.
See [[Dispute Flow]].
---
## 11. Reviews
After each completed transaction:
- Buyer rates you (1–5 stars + comment).
- You rate the buyer.
Your overall rating is shown on every offer you make. Common rating thresholds:
- **4.8+** — Top-rated badge, priority listing
- **4.0–4.7** — Normal
- **<4.0** — Limited visibility, manual review may follow
Respond to negative reviews professionally — your reply is public.
---
## 12. Analytics
**Dashboard → Overview** shows your seller KPIs:
| Metric | Description |
|---|---|
| Open requests | Active conversations |
| Acceptance rate | Offers accepted / submitted |
| Avg. response time | How fast you reply |
| Avg. delivery time | From accept to ship |
| Revenue (30/90/365 days) | Net of fees |
| Active templates | Live request templates |
| Rating | Current overall stars |
| Dispute rate | % of orders disputed |
Improve weak areas to climb the seller leaderboard.
---
## 13. Earning points (Seller side)
Sellers earn points for:
- Each successful sale
- Maintaining high rating
- Fast response times
- Referring other sellers / buyers
Points unlock benefits — see [[User Guide]] §12 and [[LevelConfig]].
---
## 14. Settings
Same as Buyer (theme, language, notifications, security) plus:
- **Auto-decline** new requests when busy (set a date range).
- **Vacation mode** — pause public visibility without losing offers in flight.
- **Tax info** — if applicable in your jurisdiction.
---
## 15. Common issues
### "My offer isn't getting acceptance"
- Compare your price to similar offers (visible in the request side panel).
- Improve your **default response time** & rating.
- Add personalised notes to each offer.
- Use rich descriptions in templates.
### "Escrow funds not showing up after delivery"
> [!warning]
> Auto-release on delivery confirmation is **not yet automated** — an admin manually triggers payouts on a schedule. Allow 1–2 business days.
If it's been longer, contact support.
### "Wrong payout address"
If you noticed a wrong address BEFORE the payout was sent → update in **Shop Settings → Payout** and contact support.
If the payout was already broadcast → recovery requires on-chain coordination; contact support immediately with the transaction hash.
### "Dispute opened — what to do first"
1. Don't panic.
2. Read the buyer's claim carefully.
3. Gather all proof (shipping receipts, photos, chat history).
4. Submit evidence within 24 hours.
5. Be respectful in your narrative.
### "Need to take time off"
Set **Vacation mode** in Shop Settings. New requests auto-decline with a courteous message; existing orders proceed normally.
---
## 16. Tips & best practices
> [!tip]
> - **Reply fast** — first responder often wins.
> - **Photos sell** — clear, well-lit images convert.
> - **Be specific in delivery dates** — buyers value predictability.
> - **Use templates** for repeat offerings — saves time, increases conversion.
> - **Build a portfolio in your shop About** — recent work, certifications.
> - **Respond to ALL reviews** — even one-line "Thank you" helps.
---
## 17. Related
- [[User Guide]] · [[Admin Guide]] · [[Support Guide]]
- Flows: [[Seller Offer Flow]] · [[Negotiation Flow]] · [[Delivery Confirmation Flow]] · [[Payout Flow]] · [[Dispute Flow]] · [[Rating Flow]]
- Models: [[User]] · [[RequestTemplate]] · [[SellerOffer]] · [[ShopSettings]] · [[Review]]
- [[Glossary]]

331
06 - Usage/Support Guide.md Normal file
View File

@@ -0,0 +1,331 @@
---
title: Support Guide
tags: [usage, role/support]
audience: Support agent
created: 2026-05-23
---
# Support Guide
End-to-end usage for **Support** agents — Tier-1 customer help, account recovery, troubleshooting. Support has elevated read permissions but limited write power; serious actions escalate to admin.
> [!info]
> Looking for a different role? See [[User Guide]] (Buyer), [[Seller Guide]] (Owner), [[Admin Guide]].
---
## 1. Support account
Support agents are provisioned by an admin (see [[Admin Guide]] §3.3). A typical seed:
| Email | Role | Capabilities |
|---|---|---|
| `support@amn.gg` | support | Read users, reset passwords, view chat (case-scoped), escalate |
A support account CANNOT:
- Change roles
- Ban / unban
- Resolve disputes (read-only)
- Issue refunds (escalate to admin)
- Modify points or financial records
- Publish blog posts
---
## 2. Workflow
Support tickets flow through these stages:
```mermaid
flowchart LR
A[New ticket] --> B[Triage]
B --> C{Resolvable?}
C -- yes --> D[Resolve]
C -- no --> E[Escalate to admin]
D --> F[Close]
E --> G[Wait]
G --> H[Admin resolves]
H --> F
```
Ticket sources:
- In-app contact form (writes to a `support` Notification / dedicated collection)
- Email to `support@amn.gg` (forwards to ticketing tool)
- Live chat widget (if enabled)
---
## 3. Common Tier-1 tasks
### 3.1 "I can't sign in"
1. Ask the user for their email.
2. **Dashboard → User → [profile]** to look them up.
3. Check status: `active`, `banned`, `pending email verification`?
4. If pending verification → **Resend verification email** (button in user profile).
5. If account locked → wait out the lockout (default 30 min) OR escalate to admin for immediate unlock.
6. If forgotten password → tell the user to use **Forgot password** on the sign-in page OR you can trigger **Reset password** from their profile (sends a fresh reset code).
> [!warning]
> Never ask a user for their password. Never SET a password for them — the platform sends a reset code so only they can complete the change.
### 3.2 "I didn't receive the email"
Checklist:
1. Confirm the correct email is on file.
2. Ask them to check Spam / Promotions.
3. Check if the user's email domain is on a known block list (yopmail, mailinator, etc.).
4. Resend (max 3 retries / hour).
5. If issue persists → check backend SMTP logs (escalate to admin).
### 3.3 "How do I change my email?"
1. Ask the user to first verify ownership of the new email.
2. Today this is an admin-assisted change — escalate.
(Roadmap: self-service email change with verify-old + verify-new.)
### 3.4 "I lost access to my Passkey device"
1. They can use their password as a fallback.
2. Direct to **Dashboard → Account → Passkey → Remove [device]**.
3. Add a new passkey from the new device.
4. If passkey was their ONLY auth method → escalate to admin who can manually unlock.
### 3.5 "I'm a seller — how do I withdraw?"
1. Verify they completed shop setup (payout wallet on file).
2. Walk them through **Dashboard → Payment → Payouts → Request payout**.
3. Remind them that payouts process within 1–2 business days.
4. If a specific payout is stuck → escalate to admin with the payout ID.
### 3.6 "My payment is stuck"
1. Get the payment ID or invoice URL.
2. Open in Admin user (if you have read access).
3. Check status:
- `pending` for <1h — tell user to wait for blockchain confirmation.
- `pending` for >1h — escalate to admin (webhook may have failed).
- `processing` — usually clears within minutes.
- `failed` — note the error code and escalate.
4. If user sent wrong network/token → **escalate immediately**, recovery may require manual on-chain work.
### 3.7 "I want to delete my account"
1. Confirm via email reply (anti-impersonation).
2. Check for: open orders, in-flight payments, open disputes — none should exist.
3. If any open obligations → ask user to settle first.
4. Escalate to admin for the actual deletion (it's a manual op to ensure data retention compliance).
### 3.8 "How do I become a seller?"
Walk them through:
1. **Dashboard → Account → Become a seller**.
2. Fill in shop info (name, country, payout address, social links).
3. Submit → admin verification within 1 business day.
4. Once approved → can build templates and submit offers.
See [[Seller Guide]].
### 3.9 "I see stale data / the page is broken"
Suggest the **localStorage cleanup** trick:
1. Open browser DevTools (`F12` or `Cmd+Opt+I`).
2. Console tab → paste:
```js
Object.keys(localStorage)
.filter(k => /^(manual-payment|buyer-step|LAST_(PAYMENT|TEMPLATE|SOCKET))-/.test(k))
.forEach(k => localStorage.removeItem(k));
location.reload();
```
3. (This pattern matches the keys cleared by `frontend/cleanup-localstorage.js`.)
If the issue persists → screenshot + browser info + URL → escalate.
### 3.10 "I want a refund"
1. Confirm what they're requesting (full / partial / for which order).
2. Check the order status & history.
3. If order is **Funded** and not yet shipped → they can negotiate cancellation with the seller (no admin needed).
4. If order is shipped/disputed/refund-disputed → direct them to open a **dispute** (or it's already open).
5. Goodwill refund < $10 — admin can issue. Note the case and escalate.
6. Larger refunds — must go through dispute process.
See [[Dispute Flow]].
---
## 4. Triage rubric
Assign priority based on impact:
| Priority | Examples | SLA |
|---|---|---|
| **P0 — Site outage / data loss** | Cannot reach amn.gg, all logins failing, payments silently failing | Immediate page admin |
| **P1 — User cannot transact** | Specific user can't pay, payout failed, dispute stuck > 7 days | 4 hours |
| **P2 — Functional bug, workaround exists** | Notification not arriving, cosmetic issue | 1 business day |
| **P3 — Question / how-to** | "How do I…" inquiries | 2 business days |
---
## 5. Escalation matrix
| Issue | Escalate to |
|---|---|
| Account un-ban request | Admin |
| Role change (buyer→seller, granting support) | Admin |
| Refund > $10 | Admin |
| Dispute resolution | Admin (mediator) |
| Manual payout exception | Admin |
| Database correction | Admin + engineer on-call |
| Site outage | Engineering on-call |
| Security incident (suspected breach / abuse) | Admin + engineering on-call IMMEDIATELY |
| Legal request (law enforcement, GDPR) | Admin + legal/compliance |
---
## 6. Communication templates
### 6.1 Password reset
```
Subject: Reset your Amn password
Hi {name},
You can reset your password at https://amn.gg/auth/jwt/reset-password. You'll receive a 6-digit code by email valid for 1 hour.
If you didn't request this, please ignore this email — your password remains unchanged.
— Amn Support
```
### 6.2 Verification email not received
```
Hi {name},
The verification email was sent. Please:
1. Check your Spam / Promotions folder.
2. Allow up to 5 minutes for delivery.
3. Click "Resend code" if it still hasn't arrived.
If the issue persists, reply with the email address you signed up with so we can investigate.
— Amn Support
```
### 6.3 Payment stuck (>1 hour)
```
Hi {name},
We see your payment {paymentId} is still showing pending. Crypto confirmations usually take a few minutes; an hour is unusual.
We've escalated this to our payments team for investigation. We'll update you within 4 hours.
In the meantime, please do NOT send additional funds — that may complicate recovery.
— Amn Support
```
### 6.4 Refund request → dispute path
```
Hi {name},
I understand you'd like a refund for order {orderId}. The fairest way to resolve this is through our dispute process, which gives both you and the seller a chance to provide evidence before a neutral mediator decides.
To open a dispute:
1. Open the order page (link below).
2. Click "Open dispute".
3. Choose a reason and upload photos / chat screenshots as evidence.
A mediator will pick up your case within 24 hours.
Link: https://amn.gg/dashboard/request/{orderId}
— Amn Support
```
### 6.5 Account un-ban (require admin approval)
```
Hi {name},
I've escalated your account review to our admin team. They'll look at the original reason for the suspension and respond within 1 business day.
In the meantime, you won't be able to sign in. Funds in escrow are unaffected and will be settled once any open orders complete.
— Amn Support
```
---
## 7. Tools & access
| Tool | Purpose | Permission |
|---|---|---|
| Admin dashboard (read mode) | Look up users, orders, payments | Yes (read) |
| User → Reset password | Trigger fresh reset code | Yes |
| User → Resend verification | Resend signup code | Yes |
| Notification system | Send "follow-up" notifications | Yes (scoped) |
| Chat history viewer | Read dispute chats | Yes (case-scoped) |
| MongoDB direct | Ad-hoc queries | No (escalate) |
| Payout trigger | Issue payouts | No (escalate) |
| Refund issuer | Issue refunds | No (escalate) |
| Dispute resolver | Make resolution | No (escalate) |
---
## 8. Privacy & ethics
> [!warning]
> Support has powerful read access. Do not browse user chats, payments, or addresses unless investigating a specific ticket. Each access should be tied to a ticket ID, ideally logged.
- Never disclose one user's data to another user.
- Verify identity before discussing account specifics (signed-in session > email reply > anonymous form).
- For financial / legal inquiries, escalate to admin + legal.
---
## 9. Common knowledge base
Bookmark these for instant reference:
- [[User Guide]] — common Buyer questions
- [[Seller Guide]] — common Seller questions
- [[Glossary]] — terminology reference
- [[Authentication Flow]] · [[Password Reset Flow]] · [[Passkey (WebAuthn) Flow]] — how auth actually works
- [[Payment Flow - SHKeeper]] · [[Payment Flow - DePay & Web3]] — how payments flow
- [[Dispute Flow]] — when refund requests need to go to dispute
- [[Notification Flow]] — why a user might not have received an email
- [[Error Codes]] — interpret HTTP errors / app-specific codes the user reports
---
## 10. Improving the docs
If you answer the same question repeatedly, propose a **knowledge-base article**:
1. Note the recurring question.
2. Write a short answer with screenshots.
3. Submit to admin for inclusion in `frontend/src/sections/blog/` or this vault.
A good support team grows the docs over time.
---
## 11. Related
- [[User Guide]] · [[Seller Guide]] · [[Admin Guide]]
- All flow docs in [[04 - Flows]] folder
- [[Incident Response]] — when support is alerted to outages
- [[Glossary]]

410
06 - Usage/User Guide.md Normal file
View 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]]