boursecu_user/README.md

Khanegi — اپ مشتری (User Panel)

پنل وب/PWA برای مشتریان خانگی پلتفرم معاملات طلا و آبشده. این اپ بخش front-end مشتری در monorepo پروژه Khanegi است.

مورد	مقدار
نام پکیج	customer
نسخه	1.0.8
فریم‌ورک	Vue 3 + TypeScript
بیلد	Vite 4
State	Pinia
UI	Ant Design Vue 3 + Vant 4 (موبایل)
پورت dev	3100

---

نقش در معماری Khanegi

Khanegi/
├── userModular/   ← این پروژه (پنل مشتری)
├── admin/         ← پنل مدیریت
└── server/        ← API اصلی (Laravel)

اتصال	پروتکل	آدرس
API اصلی	HTTPS + JWT	{node_server}/customer/*, /auth/*
قیمت لحظه‌ای	SSE	{node_server}/api/price/stream
تنظیمات tenant	HTTPS	/get_user (قبل از لود اپ)

---

پیش‌نیازها

• Node.js 18+
• npm، yarn یا pnpm

---

نصب و اجرا

cd userModular
npm install
npm run dev        # http://localhost:3100
npm run build      # vite build
npm run preview    # پیش‌نمایش production
npm run type-check # بررسی TypeScript
npm run lint       # ESLint
npm run format     # Prettier

---

ساختار پروژه

userModular/
├── src/
│   ├── views/           # صفحات اصلی
│   │   ├── login/       # ورود / ثبت‌نام
│   │   └── base/        # صفحات اپ (mobile/ + desktop/)
│   ├── api/             # لایه REST (18 ماژول)
│   ├── router/          # مسیرها + guard
│   ├── store/           # Pinia (user, wallet, fund, settings, config)
│   ├── config/          # بارگذاری tenant config
│   ├── app/             # bootstrap.ts, createApp.ts, setupRouter
│   ├── utils/           # priceSocket (SSE), authToken, useAxios
│   ├── modules/         # PWA manifest
│   ├── models/          # TypeScript types
│   ├── layouts/         # Layout موبایل/دسکتاپ
│   └── sw.ts            # Service Worker (PWA)
├── public/
├── index.html
├── vite.config.ts
├── uno.config.ts
├── themeConfig.ts
└── src/mainConfig.ts

---

قابلیت‌های اصلی

احراز هویت

• ورود با رمز عبور یا SMS
• تأیید OTP (POST /auth/verify)
• ثبت‌نام (POST /auth/register) — کد معرف، احراز Jibit (اختیاری)
• Provider: customer

صفحه اصلی و معاملات

• نمودار قیمت و صفحه home
• خرید/فروش طلا (/gold)
• خرید محصول (/buyProduct)
• قیمت لحظه‌ای از SSE با fallback polling

کیف پول و تراکنش‌ها

• مانده ریال و طلا (/wallet)
• تاریخچه تراکنش‌ها (/transactions)
• برداشت نقدی و فیزیکی
• شارژ از درگاه PayPing

صندوق (Fund)

• لیست صندوق‌ها (/fund)
• جزئیات صندوق (/fund/:id)
• واریز/برداشت صندوق

سایر

• پروفایل کاربر (/user)
• آدرس (/address)
• دریافت فیزیکی طلا (/physicalReceive)
• هشدار قیمت (/notifyTrigger)
• کسب درآمد / معرف (/earnMoney)
• کارت هدیه (/giftCard)
• قوانین و مجوزها (/rules, /permissions)
• آموزش (/educate)
• درباره ما (/aboutUs)

حالت فروشگاهی (is_store)

• سبد خرید (/api/cart/*)
• حواله (/customer/havale)
• checkout (/customer/cart/checkout)

---

مسیرها (Routes)

مسیر	نام	توضیح
/login	login	ورود
/home	home	صفحه اصلی / نمودار
/gold	gold	معامله طلا
/buyProduct	buyProduct	خرید محصول
/wallet	wallet	کیف پول
/transactions	transactions	تراکنش‌ها
/user	user	پروفایل
/notifyTrigger	notifyTrigger	هشدار قیمت
/address	address	آدرس
/physicalReceive	physicalReceive	دریافت فیزیکی
/physicalReceive/new	new	درخواست جدید
/earnMoney	earnMoney	کسب درآمد / معرف
/giftCard	giftCard	کارت هدیه
/fund	fund	صندوق‌ها
/fund/:id	fund_info	جزئیات صندوق
/fund/add	fund_add	صندوق جدید
/rules	rules	قوانین
/permissions	permissions	مجوزها
/educate	educate	آموزش
/aboutUs	aboutUs	درباره ما

ساختار UI: هر صفحه معمولاً mobile/ و desktop/ دارد.

Guard: بدون token به /login هدایت می‌شود.

---

اتصال به Backend

Bootstrap

1. index.html — loader
2. bootstrap.ts → loadAppConfig() — fetch config tenant
3. setAppConfig() + applyAppConfig() — نگاشت node_server
4. startPwaManifest() — PWA
5. mount Vue؛ اگر token باشد: getUserInfo() + initPriceRealtimeChannel()

REST API

• Base URL: getConfigApp('node_server') ← فیلد node_server در JSON tenant
• Token: customer_session_token (ثابت) یا {name}_app_token (legacy)
• Header: Authorization: Bearer <token>
• Axios: src/utils/useAxios.ts — 401 → logout؛ verify با /customer/me

پیشوند	کاربرد
/auth/*	login, verify, register
/customer/*	me, order, wallet, fund, address
/api/*	candle, price/last, city, get_settings

قیمت لحظه‌ای (SSE)

• فایل: src/utils/priceSocket.ts
• Endpoint: GET /api/price/stream (EventSource)
• Fallback: polling هر 10 ثانیه اگر SSE قطع شود
• Reconnection: exponential backoff (3s → 30s)
• در حالت non-store نیاز به JWT customer دارد

Multi-tenant Config

URLهای failover برای /get_user:

• https://nerkh.gold/get_user
• https://tablo.talasevin.ir/get_user
• https://abshode-service.montgit.ir/server/get_user
• http://212.23.201.173:8381/get_user
• http://91.212.174.137:4040/server/get_user

فیلد JSON	معادل اپ
node_server	API base
name, name_fa, avatar	برند
color, background_color	تم

Cache: localStorage.CONFIG_Success_URL + cookie APP_CONFIG_CACHE

---

Pinia Stores

Store	نقش
userStore	اطلاعات کاربر، auth
walletStore	مانده کیف پول
fundStore	صندوق‌ها
settingsStore	تنظیمات اپ
configStore	config tenant
useAuthStore	وضعیت احراز هویت

---

API Modules

فایل	Endpoints
login.ts	/auth/login, /auth/verify, /auth/register
me.ts	/customer/me, /customer/me/update
home.ts	نمودار، قیمت
order.ts	/customer/order
wallet.ts	/customer/wallet/*
fund.ts	/customer/fund/*
products.ts	محصولات
address.ts	/customer/address
giftCard.ts	/customer/giftcard/use
earnMoney.ts	معرف
triggerPrice.ts	هشدار قیمت
physicalreceive.ts	دریافت فیزیکی
configuration.ts	/api/get_settings

---

PWA

• vite-plugin-pwa با injectManifest
• Service Worker: src/sw.ts
• Manifest: نام و آیکون از config tenant
• display: standalone, orientation: portrait-primary

---

فایل‌های Config مهم

فایل	نقش
vite.config.ts	Vite، PWA، UnoCSS، port 3100
src/config/load-config.ts	fetch config ریموت
src/config/app-config.ts	نگاشت tenant
src/themeConfig.ts	token keys، رنگ‌ها
src/utils/useAxios.ts	Axios + auth
src/router/index.ts	routes
src/app/bootstrap.ts	راه‌اندازی اپ
src/sw.ts	Service Worker

---

نکات توسعه

1. دو لایه realtime: REST روی Laravel؛ قیمت از SSE با fallback polling.
2. Multi-tenant: یک build برای چند برند؛ رفتار با settings و is_store تغییر می‌کند.
3. Responsive: هر view دو نسخه mobile/ و desktop/ دارد.
4. Token persistence: customer_session_token برای جلوگیری از گم شدن token هنگام به‌روزرسانی config.
5. انیمیشن: Lottie (@lottiefiles/dotlottie-vue)، Odometer برای اعداد.

---

مستندات مرتبط

• README سرور Laravel
• README پنل ادمین
• README نمای کلی