boursecu_admin/README.md

# Khanegi — پنل ادمین (Admin Panel)

داشبورد **مدیریتی فارسی RTL** برای اپراتورهای پلتفرم معاملات طلا و آبشده: مشتریان، محصولات، قیمت‌گذاری، سفارشات، کیف پول، برداشت، حسابداری (ته‌حساب)، SMS و پیکربندی.

| مورد | مقدار |
|------|--------|
| نام پکیج | `admin-vue3` |
| نسخه | `0.0.1` |
| فریم‌ورک | Vue 3 + TypeScript |
| بیلد | Vite 4 |
| UI | Ant Design Vue 3 (RTL) |
| Base path | `/admin` |
| پورت dev | `3600` |

---

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

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

| اتصال | پروتکل | آدرس |
|--------|--------|------|
| API | HTTPS + JWT | `{node_server}/admin/*`, `/auth/*` |
| Tenant config | HTTPS | `/get_user` (قبل از لود اپ) |
| WebSocket (اختیاری) | WS | از تنظیمات `wss_link` |

---

## پیش‌نیازها

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

---

## نصب و اجرا

```bash
cd admin
npm install
npm run dev              # http://localhost:3600/admin/
npm run build            # vite build → dist/
npm run build-type-check # vue-tsc + build
npm run preview
npm run type-check
npm run lint
npm run format
```

**توجه:** در dev، `config-loader.js` به URLهای production `/get_user` متصل می‌شود. بدون دسترسی به آن‌ها، اپ با config خالی لود می‌شود (timeout 12 ثانیه).

### Deploy

خروجی `dist/` زیر مسیر `/admin` سرو می‌شود. `public/.htaccess` درخواست‌های SPA را به `/admin/index.html` هدایت می‌کند.

---

## ساختار پروژه

```
admin/
├── config.ts              # API URLs از window.__APP_CONFIG__
├── index.html             # loads config-loader.js
├── vite.config.ts         # base: '/admin', port: 3600
├── src/
│   ├── main.ts            # bootstrap, auth guard, dynamic routes
│   ├── config-loader.js   # fetch tenant config + version check
│   ├── App.vue            # RTL shell
│   ├── api/               # 23 ماژول REST
│   ├── pages/             # صفحات مدیریتی
│   │   ├── dashboard/     # میز کار
│   │   ├── menuPages/     # ماژول‌های اصلی
│   │   ├── balance/       # تراز (پنجره جدا)
│   │   └── mobileMenu/    # نمای موبایل
│   ├── router/
│   │   ├── index.ts       # setupRoutes(), permission filter
│   │   └── routes/        # ماژول‌های مسیر (18 فایل)
│   ├── store/             # userStore, configStore
│   ├── utils/             # config, deployAdmin
│   └── core/              # فریم‌ورک مشترک (git submodule)
│       ├── layouts/
│       ├── components/
│       ├── router/
│       └── config/vite.ts
└── public/.htaccess
```

### Path Aliases

| Alias | مسیر |
|-------|------|
| `@/` | `src/` |
| `@core/` | `src/core/` |
| `@root/` | ریشه admin |

`src/core` یک submodule قابل به‌روزرسانی است (Admin-Vue3-Core):

```bash
git submodule update --remote --recursive
```

---

## Tech Stack

| لایه | تکنولوژی |
|------|-----------|
| Framework | Vue 3 (Composition API, `<script setup>`) |
| Build | Vite 4 |
| Router | Vue Router 4 |
| State | Pinia |
| UI | Ant Design Vue 3 |
| Styling | Less + UnoCSS |
| HTTP | Axios (`src/core/utils/useAxios.ts`) |
| Charts | ECharts, ApexCharts |
| Dates | moment-jalaali, jalaliday |
| PWA | vite-plugin-pwa |

---

## ماژول‌های مدیریتی

### میز کار (`dashboard`)
- آمار کلی، نمودار مالی
- `GET/POST /admin/dashboard`, `POST /admin/dashboard/finance`

### مشتریان (`customers`)
- لیست مشتریان، بایگانی
- احراز هویت (فقط tenant `garoosi`)
- دارایی مشتری (`/admin/customer/{id}/assets`)

### محصولات (`products`)
- CRUD محصولات، بایگانی، دسته‌بندی
- Quick actions: فعال/غیرفعال، بستن خرید/فروش، sync نمایش
- `resource /admin/product`

### کیف پول (`wallet`)
- شارژ ریال/طلا، لیست کیف پول‌ها
- تراکنش‌ها و به‌روزرسانی

### گزارشات (`transactions`)
- گزارش تراکنش‌ها

### حساب‌ها (`accounts`)
- حساب‌های بانکی مشتریان
- تأیید/رد (`POST /admin/account/sts`)

### سفارشات (`orders`)
- لیست سفارشات عمده و تک
- `POST /admin/order/table`, `POST /admin/order/single/table`

### برداشت و واریز (`withdraw`)
- مدیریت درخواست‌های برداشت
- فاکتور (`/withdraw/factor/:id`)

### پیکربندی (`settings`)
- تنظیمات عمومی (`configuration`)
- تاریخچه قیمت (`pricing`)
- تنظیمات پیشرفته (`advanced-configuration`) — فقط deploy admin
- بنرها (`banners`)
- هشدار قیمت (`priceTriggers`)
- پیامک‌ها (`sms`)
- کارت هدیه (`giftCard`) — tenant `garoosi` یا حالت store
- تخفیفات (`discounts`) — فقط tenant `goldsun`
- مدیران (`admins`)
- حسابداری / ته‌حساب (`accounting`)

### تراز (`balance`)
- صفحه balance در پنجره جدا — hidden از منو

---

## احراز هویت و دسترسی

### Boot Sequence

1. `index.html` → `config-loader.js`
2. Fetch `/get_user` و `/get_version` (failover URLs)
3. `window.__APP_CONFIG__` set
4. `main.ts` → `GET /admin/me`
5. `setupRoutes(permissions)` — فیلتر مسیرها

### Auth

| مورد | مقدار |
|------|--------|
| Login | `POST /auth/login` |
| Payload | `{ mobile, password?, provider: 'user' }` |
| OTP | `POST /auth/verify` |
| Token | `peransa_token` (localStorage) |
| Profile | `GET /admin/me` |

### Authorization

- **Permissions:** `userInfo.role.permissions[]`
- **Admin کامل:** `is_admin` → `permissionsKeys = ['*']`
- **Route meta:** `permissionsKey` — فیلتر recursive در `setupRoutes()`
- **Tenant filter:** منو بر اساس `is_store`, `garoosi`, `goldsun`
- **Deploy admin:** زیرمنوی «تنظیمات پیشرفته» فقط برای شماره‌های deploy admin

---

## مسیرها (Routes)

Base: `/admin`

| Route | Path | عنوان |
|-------|------|--------|
| login | `/login` | ورود |
| dashboard | `/dashboard` | میز کار |
| customers | `/customers/*` | مشتریان |
| products | `/products/*` | محصولات |
| wallet | `/wallet` | کیف پول |
| transactions | `/transactions` | گزارشات |
| accounts | `/accounts` | حساب‌ها |
| orders | `/orders` | سفارشات |
| withdraw | `/withdraw` | برداشت و واریز |
| settings | `/settings/*` | پیکربندی |
| balance | `/balance` | تراز (hidden) |

مسیر فاکتور (hidden): `/withdraw/factor/:id`

---

## API Integration

### HTTP Client

- `httpApi` / `httpProjectApi` — base: `getConfigApp('node_server')`
- Request: `Authorization: Bearer {token}`
- Response: `response.data` مستقیم
- 401: پاک کردن token و redirect به login

### API Modules

| فایل | Endpoints |
|------|-----------|
| `login.ts` | `/auth/login`, `/auth/verify` |
| `user.ts` | `/admin/me`, `/admin/user/*` |
| `customer.ts` | `/admin/customer/*` |
| `product.ts` | `/admin/product/*` |
| `price.ts` | `/admin/price/*`, `/admin/prices/*` |
| `order.ts` | `/admin/order/*` |
| `wallet.ts` | `/admin/wallet/*` |
| `tahesab.ts` | `/admin/tahesab/*` |
| `configuration.ts` | `/admin/get_settings` |
| `giftCard.ts` | `/admin/giftcard/*` |
| `accounting.ts` | `/admin/finance` |
| `sms.ts` | `/admin/messages/*` |
| `dashboard.ts` | `/admin/dashboard/*` |

---

## Runtime Config

`config-loader.js` URLهای failover:

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

فیلدهای مورد استفاده در `config.user`:

- `name`, `avatar`, `node_server`

Cache: `localStorage.CONFIG_Success_URL`

---

## Tenant / White-label

- فیلتر منو per-tenant: `garoosi`, `goldsun`, `is_store`
- `document.title` و favicon از config
- حالت store: کارت هدیه + تخفیف، منوی متفاوت
- `prefixCls`: `hr-tamin`

---

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

| فایل | نقش |
|------|-----|
| `config.ts` | tokenName (`peransa_token`), appName, prefixCls |
| `vite.config.ts` | base `/admin`, port 3600 |
| `src/core/config/vite.ts` | auto-import, Less |
| `src/config-loader.js` | tenant bootstrap |
| `src/router/index.ts` | route registration + permission filter |
| `src/store/userStore.ts` | auth + permissions |
| `src/utils/config.ts` | `getConfigApp`, `isStoreApp` |

---

## نکات توسعه

1. **Core submodule:** تغییرات مشترک در `src/core` — با دقت merge کنید.
2. **Permission-driven UI:** قبل از افزودن route، `permissionsKey` تعریف کنید.
3. **No .env:** مقادیر محیطی از `/get_user` می‌آید.
4. **Store mode:** `isStoreApp()` رفتار منو و API را تغییر می‌دهد.
5. **Mobile view:** `src/pages/mobileMenu/` برای نمای موبایل ادمین.

---

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

- [README اپ مشتری](../userModular/README.md)
- [README سرور Laravel](../server/README.md)
- [README نمای کلی](../README.md)