Initial commit: nick docs

06 - Usage/Admin Guide.md

@@ -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]]