nick/nick-doc

Fork 0

Files

Siavash Sameni ddc0434819 docs: sync from backend 19f7eb9, frontend 60ee6fb — Task #10 AML screening

2026-05-28 20:35:38 +04:00

13 KiB

Raw Blame History

title, tags, audience, created

title

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.

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

Open user row → Ban.
Provide a reason (logged + emailed to user).
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) — Request Network webhook/reconciliation may not have completed; check webhook logs and derived-destination balances.
Failed webhooks — Request Network signature verification or payload validation failed; see Payment API and Request Network Integration Constraints.
Missing tx hashes on completed payments — use the payment console or reconciliation job to fetch and verify the on-chain transaction before any release.

6.2 Manual payout

For sellers who can't access self-service or for one-off ops:

Payment → Payout → New.
Fields: recipient address, amount, token (USDT…), network (BSC…), reference, description.
Submit → ts-node script also exists at backend/manual-payout-test.ts for local testing.

Behind the scenes this should create a release/refund instruction and ledger entry, then route signing through the configured custody signer. See Payout Flow and PRD - Decentralized Custody and Smart-Contract Escrow Roadmap.

6.3 Fix missing transaction hashes

Some completed payments may lack the on-chain tx hash (webhook race, callback delay, or partial reconciliation). Prefer the admin payment console or Request Network reconciliation tooling. For older SHKeeper records only, use the historical repair script:

cd /Users/mojtabaheidari/code/backend
node fix-transaction-hashes.js

The legacy script polls SHKeeper for each affected historical invoice and patches transactionHash + blockchain.transactionHash in MongoDB. Do not use it for new Request Network payments.

See Scripts for the full inventory.

6.4 Refunds

Issued automatically when a dispute resolves to "refund buyer". For manual refunds (e.g., goodwill):

Payment → [payment] → Refund.
Specify amount (full or partial).
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:

Points → Award bonus.
Pick a user (by email).
Amount + reason (logged in audit).
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

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:

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

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

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

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.)

Compose message (title, body, link).
Audience: all users / specific role / specific list.
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:

Post an in-app announcement 24h ahead.
At T-15 min, broadcast system:maintenance socket event.
UI shows a yellow banner: "Maintenance in 15 min — please save your work."
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

User Guide · Seller Guide · Support Guide
Flows: Dispute Flow · Payout Flow · Notification Flow
Models: User · Dispute · Payment · LevelConfig · PointTransaction · Category · BlogPost
Admin API · Glossary

13 KiB Raw Blame History