boursecu_server/README.md

# Khanegi — سرور API (Laravel)

**API اصلی** پلتفرم معاملات طلا و آبشده با تمرکز بر مشتریان خانگی. تمام منطق کسب‌وکار، احراز هویت، دیتابیس، کیف پول و یکپارچه‌سازی با سیستم‌های خارجی در این پروژه قرار دارد.

| مورد | مقدار |
|------|--------|
| فریم‌ورک | Laravel 8.75 |
| PHP | ^7.3 \| ^8.0 |
| Auth | JWT (`tymon/jwt-auth`) + Sanctum |
| DB | MySQL 8 |
| پکیج داخلی | `Rooyesh\Wallet` |
| تاریخ شمسی | `morilog/jalali`, `hekmatinasser/verta` |

---

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

```
Khanegi/
├── userModular/   ← پنل مشتری (مصرف‌کننده /customer, /auth)
├── admin/         ← پنل مدیریت (مصرف‌کننده /admin, /auth)
└── server/        ← این پروژه
```

کلاینت‌ها REST + JWT به این سرور متصل می‌شوند. برای رویدادهای لحظه‌ای قیمت، SSE از `/api/price/stream` استفاده می‌شود. broadcast اختیاری WebSocket از طریق `WebsocketBroadcastService` انجام می‌شود.

---

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

- PHP 7.3+ یا 8.x
- Composer
- MySQL 8
- Node.js (فقط برای Laravel Mix، اختیاری)

---

## نصب و اجرا

```bash
cd server
composer install
# ایجاد .env و تنظیم DB_*, JWT_SECRET, APP_KEY
php artisan key:generate
php artisan jwt:secret
php artisan migrate
php artisan serve         # http://localhost:8000
```

### Docker

```bash
docker-compose up
# app: :8000, db: :3306
```

### Deploy DB موجود

```bash
bash database/sql/run_deploy_existing_db.sh
```

جزئیات: [database/sql/DEPLOY_CHECKLIST.md](./database/sql/DEPLOY_CHECKLIST.md)

---

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

```
server/
├── app/
│   ├── Http/Controllers/
│   │   ├── Admin/        # بک‌آفیس
│   │   ├── Customer/     # اپ مشتری
│   │   ├── Auth/         # ورود، ثبت‌نام
│   │   ├── Site/         # قیمت، شهر، گزارش
│   │   ├── pay/          # PayPing
│   │   ├── Finance/      # مالی
│   │   └── Single/       # سفارشات تک
│   ├── Models/           # 30 مدل Eloquent
│   └── Services/         # 22 سرویس
├── packages/rooyesh/wallet/   # کیف پول داخلی
├── routes/
│   ├── api.php
│   ├── auth.php
│   ├── admin.php
│   ├── customer.php
│   └── web.php
├── config/
│   ├── auth.php, jwt.php
│   ├── price_providers.php
│   ├── payment.php, fee.php
│   └── validation.php
├── database/
│   ├── migrations/       # 21 migration (2026_*)
│   ├── schema/mysql-schema.sql.reference
│   └── sql/              # deploy scripts
├── docker-compose.yml
└── Dockerfile
```

---

## گروه‌های Route

بارگذاری در `RouteServiceProvider`:

| Prefix | Middleware | File | مخاطب |
|--------|------------|------|--------|
| `/api` | api | `api.php` | عمومی (قیمت، شهر، تنظیمات) |
| `/auth` | api + validation | `auth.php` | ورود |
| `/admin` | api | `admin.php` | پنل مدیریت |
| `/customer` | api | `customer.php` | اپ مشتری |
| `/` | web | `web.php` | views, cron |

Rate limit: **60 req/min** روی `api`.

---

## API Endpoints (خلاصه)

### `/auth` — احراز هویت

| Method | Path | توضیح |
|--------|------|--------|
| POST | `/auth/login` | ورود (رمز/SMS) |
| POST | `/auth/verify` | تأیید OTP |
| POST | `/auth/register` | ثبت‌نام مشتری |

### `/api` — عمومی

| Endpoint | عملکرد |
|----------|--------|
| GET `/api/candle` | نمودار شمعی |
| GET/POST `/api/price/last` | آخرین قیمت |
| GET `/api/price/stream` | SSE قیمت لحظه‌ای |
| GET `/api/city/*` | استان/شهر |
| GET `/api/get_settings` | تنظیمات عمومی |
| GET `/api/const/key/{key}` | ثابت‌ها |
| POST `/api/price_triggers/table` | جدول هشدار قیمت |
| Store: `/api/cart/*`, `/api/categories` | سبد خرید بدون لاگین |

### `/admin` — مدیریت (JWT: `auth:user`)

| Domain | Endpoints |
|--------|-----------|
| Profile | `GET /admin/me`, `POST /admin/me/update` |
| Users | `resource /admin/user`, `POST /admin/user/table` |
| Customers | `resource /admin/customer`, archive, assets, referrals |
| Products | `resource /admin/product`, quick actions, categories |
| Prices | `POST /admin/price`, `/admin/prices/chart`, sync logs |
| Orders | `POST /admin/order/table`, single orders |
| Wallet | charge, withdraw, transactions |
| Dashboard | `GET/POST /admin/dashboard`, finance |
| Tahesab | sync, register, retry |
| Settings | `GET/POST /admin/get_settings` |
| Messages | `resource /admin/messages` |
| Gift Card | `POST /admin/giftcard/generate` |
| Offer Codes | `resource /admin/offer_code` |

### `/customer` — مشتری (JWT: `auth:customer`)

| Domain | Endpoints |
|--------|-----------|
| Profile | `GET /customer/me`, `POST /customer/me/update` |
| Wallet | `GET /customer/wallet/me`, withdraw, transactions |
| Orders | `POST /customer/order`, `POST /customer/order/table` |
| Fund | `resource /customer/fund`, deposit/withdraw |
| Product | `POST /customer/wallet/product/deposit` |
| Bank Account | `resource /customer/account` |
| Gateway | `POST /customer/charge_account` |
| Referral | `POST /customer/im_from/{code}` |
| Price Trigger | `resource /customer/price_triggers` |
| Address | `resource /customer/address` |
| Gift Card | `POST /customer/giftcard/use` |
| Store | `POST /customer/havale`, `POST /customer/cart/checkout` |

---

## مدل‌ها و دامنه‌های کسب‌وکار

| دامنه | Models |
|--------|--------|
| کاربران | `User` |
| مشتریان | `Customer`, `CustomersSetting` |
| کاتالوگ | `Product`, `Category`, `Price`, `PriceCandle`, `PriceTrigger` |
| معاملات | `Order` |
| مالی | `Fund`, `Withdraw`, `BankAccount` |
| کیف پول | `Wallet`, `Transaction` (Rooyesh) |
| فروشگاه | `Cart`, `CartItem` |
| کارت هدیه | `GiftCard`, `GiftCardCodes`, `OfferCode` |
| حسابداری | `Tahesab`, `TransactionsAdmin` |
| سیستم | `Setting`, `Cnt`, `Message`, `Log`, `File`, `City` |
| Sync | `PriceSyncLog`, `PriceSyncLogItem` |

**تنظیمات runtime** در جدول `settings` ذخیره می‌شود (`ConfigService`).

کلیدهای رایج در `config/price_providers.php`:

- `price_provider` — `montzar` \| `main_product` \| `zaarbox`
- `is_store` — حالت فروشگاهی
- `register_jibit_verify` — احراز هویت Jibit
- `profit_gold_api_enabled` — API سود طلا
- `external_order_api_enabled` — API سفارش خارجی

---

## احراز هویت

### Guards

| Guard | Model | کاربرد |
|-------|-------|--------|
| `user` | `User` | ادمین |
| `customer` | `Customer` | مشتری خانگی |

### Login Flow

- Provider: `user` یا `customer`
- روش‌ها: password، SMS OTP (4 رقمی)، master password
- TTL JWT: **43200 دقیقه** (30 روز)
- بررسی: `active`, `is_archive` (مشتری)

### Middleware

- `auth:user` / `auth:customer` — JWT
- `validation` — rules از `config/validation.php` + تبدیل اعداد فارسی
- `throttle:api` — 60 req/min

---

## سرویس‌های کلیدی

| سرویس | کاربرد |
|--------|--------|
| `ConfigService` | تنظیمات از DB + fallback |
| `ProductPriceService` | قیمت‌گذاری محصولات |
| `PriceStreamService` | SSE قیمت لحظه‌ای |
| `MontzarService` | منبع قیمت Montzar |
| `ZaarboxPriceService` | منبع قیمت Zaarbox |
| `TahesabSyncService` | همگام‌سازی ته‌حساب |
| `WalletBalanceService` | مانده کیف پول |
| `AssetSummaryService` | خلاصه دارایی |
| `WebsocketBroadcastService` | trigger WebSocket اختیاری |
| `NotificationService` | SMS و اعلان |
| `ReferralGiftService` | پاداش معرف |
| `AccountingLedgerService` | دفتر حسابداری |

---

## پکیج کیف پول (Rooyesh)

```
packages/rooyesh/wallet/
├── WalletInterface
├── TransactionInterface
└── Models: Wallet, Transaction, TransactionMeta
```

مدیریت موجودی `cash` (ریال) و `gold` (طلا) per owner.

---

## یکپارچه‌سازی‌های خارجی

| سرویس | کاربرد |
|--------|--------|
| **ته‌حساب** | حسابداری، مانده، اسناد |
| **PayPing** | درگاه پرداخت |
| **Montzar / Zaarbox** | منبع قیمت |
| **Jibit** | احراز هویت ثبت‌نام |
| **WebSocket (اختیاری)** | realtime trigger |

### Trigger WebSocket

```php
// WebsocketBroadcastService
// POST {wss_link}/prc/api/trigger-update
// body: { "trigger": "price_update", ... }
```

تنظیم از `settings`: `wss_link`, `wss_http_port`, `wss_trigger_host`

---

## متغیرهای محیط

### `.env` استاندارد

```env
APP_NAME, APP_ENV, APP_KEY, APP_DEBUG, APP_URL
DB_CONNECTION=mysql
DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, DB_PASSWORD
JWT_SECRET
```

**توجه:** بیشتر credentialهای یکپارچه‌سازی در جدول `settings` است، نه `.env`.

---

## Deploy

| روش | توضیح |
|------|--------|
| PHP-FPM + Nginx | production استاندارد |
| Docker | `docker-compose.yml` — app + MySQL |
| DB موجود | `baseline_migrations.sql` → `migrate` → `deploy_settings_const.sql` |

مستندات:

- [database/sql/DEPLOY_CHECKLIST.md](./database/sql/DEPLOY_CHECKLIST.md)
- [database/schema/README.md](./database/schema/README.md)

---

## نکات امنیتی

1. routeهای debug در `web.php` و `api.php` (`/test`, `/check`) را در production غیرفعال کنید.
2. `JWT_SECRET` را rotate کنید.
3. master password pattern (`monTech@...`) را بررسی کنید.
4. CORS: `allowed_origins: ['*']` — در production محدود کنید.

---

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

- [README اپ مشتری](../userModular/README.md)
- [README پنل ادمین](../admin/README.md)
- [README نمای کلی](../README.md)