docs(docs): overhaul project documentation and deployment guides
Refactor all primary documentation files to improve readability, visual presentation, and technical accuracy. - Update `README.md` with a modern layout, including technology badges and a high-level architecture overview. - Redesign `04_Laravel/README.md` to include a streamlined installation guide, environment configuration details, and default credentials. - Revamp `DEPLOYMENT.md` to provide clear, environment-specific instructions for production and local setups.
This commit is contained in:
Kazem Alghasi
parent
6a4a619261
commit
6aee0324d4
@ -1,73 +1,85 @@
|
||||
<div align="center">
|
||||
|
||||
# ⚙️ IFNEX Laravel Backend
|
||||
|
||||
### هسته مرکزی سیستم مدیریت لجستیک ایفنکس
|
||||
|
||||
[](https://laravel.com)
|
||||
[](https://php.net)
|
||||
[](https://filamentphp.com)
|
||||
[](https://mysql.com)
|
||||
|
||||
---
|
||||
|
||||
## 📄 فایل ۲: `04_Laravel/README.md` (پوشه لاراول)
|
||||
**REST API + Admin Panel + Financial Engine**
|
||||
|
||||
```markdown
|
||||
# 🚀 IFNEX Laravel Backend
|
||||
> هسته مرکزی سیستم مدیریت لجستیک ایفنکس
|
||||
[🚀 نصب سریع](#-نصب-و-راهاندازی-سریع) • [📡 API Endpoints](#-api-endpoints) • [🗃️ Models](#-models) • [📚 مستندات](#-مستندات)
|
||||
|
||||
| مورد | توضیحات |
|
||||
| :--- | :--- |
|
||||
| **نسخه لاراول** | Laravel 11.x |
|
||||
| **نسخه PHP** | PHP 8.2+ |
|
||||
| **پنل ادمین** | Filament 3.3.x |
|
||||
| **دیتابیس** | MySQL 8+ |
|
||||
| **تاریخ آخرین بهروزرسانی** | 2026-08-10 |
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
## 📋 فهرست مطالب
|
||||
## 🎯 نمای کلی
|
||||
|
||||
1. [پیشنیازها](#پیشنیازها)
|
||||
2. [نصب و راهاندازی](#نصب-و-راهاندازی)
|
||||
3. [ساختار پوشهها](#ساختار-پوشهها)
|
||||
4. [API Endpoints](#api-endpoints)
|
||||
5. [Artisan Commands](#artisan-commands)
|
||||
6. [تستها](#تستها)
|
||||
7. [پیکربندی](#پیکربندی)
|
||||
8. [نکات امنیتی](#نکات-امنیتی)
|
||||
این پوشه شامل **هسته مرکزی سیستم IFNEX** است:
|
||||
|
||||
- REST API کامل برای ارتباط با WordPress
|
||||
- پنل مدیریت Filament
|
||||
- موتور قیمتگذاری با ۴ زون و ۳ نوع سرویس
|
||||
- سیستم کیف پول و پرداخت
|
||||
- تولید PDF (AWB, Invoice, Label) با بارکد
|
||||
- سیستم اعلانها و تاریخچه تغییرات
|
||||
|
||||
---
|
||||
|
||||
## پیشنیازها
|
||||
## 🚀 نصب و راهاندازی سریع
|
||||
|
||||
قبل از شروع، مطمئن شوید که موارد زیر روی سیستم شما نصب هستند:
|
||||
### پیشنیازها
|
||||
|
||||
| ابزار | نسخه حداقل | نصب |
|
||||
|-------|-----------|-----|
|
||||
| PHP | 8.2+ | [دانلود](https://www.php.net/downloads) |
|
||||
| Composer | 2.x | [دانلود](https://getcomposer.org/) |
|
||||
| MySQL | 8+ | [دانلود](https://dev.mysql.com/downloads/) |
|
||||
| Node.js & NPM | 18+ | [دانلود](https://nodejs.org/) (اختیاری - برای WordPress tools) |
|
||||
| XAMPP/WAMP | آخرین نسخه | [دانلود](https://www.apachefriends.org/) (پیشنهادی برای Windows) |
|
||||
| ابزار | حداقل نسخه |
|
||||
|-------|-----------|
|
||||
| PHP | 8.2+ |
|
||||
| Composer | 2.x |
|
||||
| MySQL | 8.0+ |
|
||||
|
||||
---
|
||||
|
||||
## نصب و راهاندازی
|
||||
|
||||
### ۱. کلون مخزن و ورود به پوشه لاراول
|
||||
### مراحل نصب
|
||||
|
||||
```bash
|
||||
# کلون مخزن
|
||||
git clone https://www.git.vernahost.ir/gitmodir110/ifnex.git
|
||||
# ۱. ورود به پوشه لاراول
|
||||
cd 04_Laravel
|
||||
|
||||
# ورود به پوشه لاراول
|
||||
cd ifnex/04_Laravel
|
||||
|
||||
|
||||
۲. نصب پکیجهای Composer
|
||||
# ۲. نصب وابستگیها
|
||||
composer install
|
||||
|
||||
۳. کپی فایل محیط و تنظیم دیتابیس
|
||||
# کپی فایل محیط
|
||||
# ۳. تنظیم فایل محیط
|
||||
cp .env.example .env
|
||||
php artisan key:generate
|
||||
|
||||
# ویرایش فایل .env و تنظیم اطلاعات دیتابیس
|
||||
nano .env # یا هر ویرایشگر دلخواه
|
||||
# ۴. ایجاد دیتابیس
|
||||
mysql -u root -p -e "CREATE DATABASE ifnex_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
|
||||
|
||||
تنظیمات مهم در فایل .env:
|
||||
# دیتابیس
|
||||
# ۵. ویرایش .env و تنظیم DB_DATABASE, DB_USERNAME, DB_PASSWORD
|
||||
|
||||
# ۶. اجرای migrations و seeders
|
||||
php artisan migrate --force
|
||||
php artisan db:seed --force
|
||||
|
||||
# ۷. اجرای سرور
|
||||
php artisan serve
|
||||
```
|
||||
|
||||
### 🔐 دسترسی پیشفرض
|
||||
|
||||
| آیتم | مقدار |
|
||||
|-------|-------|
|
||||
| URL پنل | http://localhost:8000/panel |
|
||||
| ایمیل ادمین | admin@ifnex.local |
|
||||
| رمز عبور | password |
|
||||
|
||||
### ⚙️ تنظیمات مهم .env
|
||||
|
||||
```env
|
||||
# DATABASE
|
||||
DB_CONNECTION=mysql
|
||||
DB_HOST=127.0.0.1
|
||||
DB_PORT=3306
|
||||
@ -75,567 +87,184 @@ DB_DATABASE=ifnex_db
|
||||
DB_USERNAME=root
|
||||
DB_PASSWORD=
|
||||
|
||||
# API Key برای ترکینگ
|
||||
# IFNEX
|
||||
IFNEX_API_KEY=ifnex-local-dev-key
|
||||
|
||||
# CORS - فقط دامنه وردپرس
|
||||
CORS_ALLOWED_ORIGINS=http://localhost:8080
|
||||
|
||||
# Rate Limiting
|
||||
IFNEX_TRACKING_RATE_LIMIT=60
|
||||
|
||||
# Currency API (برای فاز ۲)
|
||||
CURRENCY_API_KEY=your_api_key_here
|
||||
# CORS (فقط دامنههای مجاز وردپرس)
|
||||
CORS_ALLOWED_ORIGINS=http://localhost:8080,http://ifnex.local
|
||||
|
||||
# PAYMENT GATEWAY (Zarinpal)
|
||||
ZARINPAL_MERCHANT_ID=your_merchant_id
|
||||
ZARINPAL_SANDBOX=true
|
||||
```
|
||||
|
||||
۴. تولید کلید اپلیکیشن
|
||||
php artisan key:generate
|
||||
---
|
||||
|
||||
## 📡 API Endpoints
|
||||
|
||||
۵. ایجاد دیتابیس
|
||||
# ورود به MySQL
|
||||
mysql -u root -p
|
||||
### 🔓 API عمومی (API Key)
|
||||
|
||||
# ایجاد دیتابیس
|
||||
CREATE DATABASE ifnex_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
|
||||
EXIT;
|
||||
| متد | Endpoint | توضیح |
|
||||
|------|----------|--------|
|
||||
| GET | `/api/v1/track/{awb_no}` | رهگیری مرسوله |
|
||||
| POST | `/api/v1/calculate` | محاسبه قیمت |
|
||||
| GET | `/api/v1/discount-codes` | لیست کدهای تخفیف |
|
||||
| POST | `/api/v1/discount-codes/validate` | اعتبارسنجی کد تخفیف |
|
||||
| POST | `/api/v1/bridge/login` | Bridge Auth (وردپرس) |
|
||||
| POST | `/api/v1/auth/login` | ورود مشتری |
|
||||
| POST | `/api/v1/auth/logout` | خروج |
|
||||
|
||||
۶. اجرای Migration ها
|
||||
php artisan migrate --force
|
||||
### 🔐 API مشتری (Sanctum Token)
|
||||
|
||||
۷. درج دادههای اولیه (Seeders)
|
||||
# این دستور ۲۳۳ کشور + تنظیمات اولیه + کاربر ادمین را ایجاد میکند
|
||||
php artisan db:seed --force
|
||||
| متد | Endpoint | توضیح |
|
||||
|------|----------|--------|
|
||||
| GET | `/api/v1/customer/profile` | پروفایل و آمار |
|
||||
| GET | `/api/v1/customer/countries` | لیست کشورها |
|
||||
| GET | `/api/v1/customer/orders` | لیست سفارشات |
|
||||
| POST | `/api/v1/customer/orders` | ثبت سفارش |
|
||||
| GET | `/api/v1/customer/orders/{id}` | جزئیات سفارش |
|
||||
| POST | `/api/v1/customer/orders/{id}/cancel` | لغو سفارش |
|
||||
| POST | `/api/v1/customer/orders/{id}/pay-wallet` | پرداخت کیف پول |
|
||||
| POST | `/api/v1/customer/orders/{id}/pay-gateway` | پرداخت درگاه |
|
||||
| GET | `/api/v1/customer/notifications` | اعلانها |
|
||||
| POST | `/api/v1/customer/notifications/{id}/read` | خواندن اعلان |
|
||||
|
||||
اطلاعات ورود پیشفرض به پنل ادمین:
|
||||
URL: http://localhost:8000/admin
|
||||
Email: admin@ifnex.local
|
||||
Password: password (در Seeder تنظیم شده)
|
||||
### 💰 API کیف پول (Sanctum Token)
|
||||
|
||||
۸. اجرای سرور توسعه
|
||||
php artisan serve
|
||||
| متد | Endpoint | توضیح |
|
||||
|------|----------|--------|
|
||||
| GET | `/api/v1/wallet/balance` | موجودی |
|
||||
| GET | `/api/v1/wallet/transactions` | تراکنشها |
|
||||
|
||||
اکنون پروژه در http://localhost:8000 قابل دسترسی است.
|
||||
### 💳 API پرداخت
|
||||
|
||||
| متد | Endpoint | توضیح |
|
||||
|------|----------|--------|
|
||||
| POST | `/api/v1/payment/redirect` | انتقال به درگاه |
|
||||
| GET | `/api/v1/payment/check/{id}` | بررسی وضعیت |
|
||||
| ANY | `/api/v1/payment/callback` | Callback درگاه |
|
||||
|
||||
ساختار پوشهها
|
||||
### 🧪 Mock Gateway (تست)
|
||||
|
||||
| متد | Endpoint | توضیح |
|
||||
|------|----------|--------|
|
||||
| GET | `/api/v1/payment/mock-gateway` | صفحه شبیهسازی |
|
||||
| GET | `/api/v1/payment/mock-gateway/success` | شبیه موفق |
|
||||
| GET | `/api/v1/payment/mock-gateway/failure` | شبیه شکست |
|
||||
|
||||
---
|
||||
|
||||
## 🗂️ ساختار پروژه
|
||||
|
||||
```
|
||||
04_Laravel/
|
||||
├── app/
|
||||
│ ├── Models/ # مدلهای Eloquent
|
||||
│ │ ├── Country.php # کشورها با ۴ زون
|
||||
│ │ ├── Shipment.php # مرسولات
|
||||
│ │ ├── ShipmentItem.php # اقلام گمرکی (۹ ردیف)
|
||||
│ │ ├── ShippingRate.php # تعرفههای حمل
|
||||
│ │ ├── ShipmentCarrierMapping.php # نگاشت کدهای ترکینگ
|
||||
│ │ ├── ShipmentTrackingEvent.php # رویدادهای ترکینگ
|
||||
│ │ ├── SystemSetting.php # تنظیمات سیستم
|
||||
│ │ └── User.php # کاربران
|
||||
│ │
|
||||
│ ├── Enums/ # Enum ها
|
||||
│ │ ├── ShipmentDirection.php # import/export
|
||||
│ │ ├── ShipmentType.php # DOC_NORMAL/DOC_ECONOMY/PARCEL
|
||||
│ │ ├── ShipmentStatus.php # ۹ وضعیت مرسوله
|
||||
│ │ ├── CarrierCode.php # ۹ شرکت حمل
|
||||
│ │ ├── TrackingSource.php # ۵ منبع (manual, api, import, system, customer)
|
||||
│ │ ├── TransactionType.php
|
||||
│ │ ├── TransactionStatus.php
|
||||
│ │ ├── PaymentGateway.php # ۴ درگاه (zarinpal, wallet, manual, system)
|
||||
│ │ └── UserRole.php
|
||||
│ │
|
||||
│ ├── Services/ # لایه سرویس (Business Logic)
|
||||
│ │ ├── PriceCalculatorService.php
|
||||
│ │ ├── TrackingService.php
|
||||
│ │ ├── ExchangeRateService.php
|
||||
│ │ ├── ZarinpalService.php
|
||||
│ │ ├── MockZarinpalService.php
|
||||
│ │ └── OrderPaymentService.php
|
||||
│ │
|
||||
│ ├── Enums/ # ShipmentStatus, ShipmentDirection, ShipmentType
|
||||
│ ├── Filament/
|
||||
│ │ ├── Resources/ # Shipment, Country, ShippingRate, Currency
|
||||
│ │ ├── Pages/ # Settings, ImportRates, PriceTest
|
||||
│ │ └── Widgets/ # Dashboard Widgets
|
||||
│ ├── Http/
|
||||
│ │ ├── Controllers/
|
||||
│ │ │ ├── Api/
|
||||
│ │ │ │ ├── TrackController.php
|
||||
│ │ │ │ ├── PricingController.php
|
||||
│ │ │ │ ├── AuthController.php # ورود/خروج Sanctum
|
||||
│ │ │ │ ├── BridgeAuthController.php # لاگین از پلاگین وردپرس
|
||||
│ │ │ │ ├── WalletController.php
|
||||
│ │ │ │ ├── PaymentController.php
|
||||
│ │ │ │ ├── DiscountCodeController.php
|
||||
│ │ │ │ └── Customer/
|
||||
│ │ │ │ └── CustomerOrderController.php # ۶ endpoint سفارش مشتری
|
||||
│ │ │ ├── OrderController.php
|
||||
│ │ │ ├── PricingPageController.php
|
||||
│ │ │ └── ShipmentPdfController.php
|
||||
│ │ ├── Middleware/
|
||||
│ │ │ └── ApiKeyMiddleware.php
|
||||
│ │ └── Requests/
|
||||
│ │
|
||||
│ ├── Imports/ # Excel Imports
|
||||
│ │ ├── ShippingRatesImport.php # واردات تعرفهها
|
||||
│ │ ├── HistoricalShipmentsImport.php # واردات مرسولات تاریخی
|
||||
│ │ └── RateSheetImport.php # شیتهای نرخ
|
||||
│ │
|
||||
│ ├── Console/Commands/ # Artisan Commands
|
||||
│ │ ├── ImportShippingRates.php
|
||||
│ │ ├── ImportHistoricalData.php
|
||||
│ │ ├── UpdateExchangeRates.php
|
||||
│ │ ├── SyncWordPressUsers.php
|
||||
│ │ └── DebugImportCommand.php
|
||||
│ │
|
||||
│ └── Filament/ # پنل ادمین Filament
|
||||
│ ├── Resources/
|
||||
│ │ ├── CountryResource.php
|
||||
│ │ ├── ShipmentResource.php
|
||||
│ │ ├── ShippingRateResource.php
|
||||
│ │ ├── ShipmentItemResource.php
|
||||
│ │ ├── WalletResource.php
|
||||
│ │ ├── WalletTransactionResource.php
|
||||
│ │ ├── PaymentResource.php
|
||||
│ │ ├── DiscountCodeResource.php
|
||||
│ │ ├── ExchangeRateHistoryResource.php
|
||||
│ │ ├── RoleResource.php
|
||||
│ │ └── UserResource.php
|
||||
│ ├── Widgets/
|
||||
│ │ ├── DashboardInfoWidget.php
|
||||
│ │ ├── ExchangeRateWidget.php
|
||||
│ │ ├── WalletStats.php
|
||||
│ │ ├── TransactionChartWidget.php
|
||||
│ │ └── RecentTransactionsWidget.php
|
||||
│ └── Pages/
|
||||
│ ├── IfnexSettingsPage.php
|
||||
│ ├── PriceTestPage.php
|
||||
│ └── Reports/
|
||||
│ └── FinancialReport.php
|
||||
│ │ ├── Controllers/Api/ # Track, Pricing, Auth, Bridge, Customer, Wallet, Payment
|
||||
│ │ └── Middleware/ # ApiKeyMiddleware
|
||||
│ ├── Models/ # Eloquent Models (13 مدل)
|
||||
│ ├── Notifications/ # ShipmentUpdatedNotification
|
||||
│ ├── Services/ # PriceCalculator, Pdf, Tracking, OrderPayment
|
||||
│ └── Imports/ # OldShipments, ShippingRates
|
||||
│
|
||||
├── database/
|
||||
│ ├── migrations/ # Migration ها
|
||||
│ │ ├── 2026_08_02_000001_create_countries_table.php
|
||||
│ │ ├── 2026_08_02_000002_create_shipments_table.php
|
||||
│ │ ├── 2026_08_02_000003_create_shipping_rates_table.php
|
||||
│ │ ├── 2026_08_02_000004_create_shipment_carrier_mappings_table.php
|
||||
│ │ ├── 2026_08_02_000005_create_shipment_tracking_events_table.php
|
||||
│ │ ├── 2026_08_02_000006_create_system_settings_table.php
|
||||
│ │ ├── 2026_08_02_000007_update_users_table.php
|
||||
│ │ ├── 2026_08_08_000001_create_shipment_items_table.php
|
||||
│ │ ├── 2026_08_05_135026_create_discount_codes_table.php
|
||||
│ │ ├── 2026_08_09_231738_create_exchange_rate_history_table.php
|
||||
│ │ ├── 2026_08_10_080853_add_wallet_to_payment_gateway_enum.php
|
||||
│ │ ├── 2026_08_10_082121_add_system_to_tracking_source_enum.php
|
||||
│ │ ├── 2026_08_09_012526_create_notifications_table.php
|
||||
│ │ └── 2026_08_09_220409_create_permission_tables.php
|
||||
│ └── seeders/ # Seeders
|
||||
│ ├── CountriesTableSeeder.php
|
||||
│ ├── SystemSettingSeeder.php
|
||||
│ ├── DatabaseSeeder.php
|
||||
│ ├── RoleAndPermissionSeeder.php
|
||||
│ └── SampleDataSeeder.php
|
||||
│
|
||||
├── routes/
|
||||
│ ├── web.php # روتهای وب (فرمها و صفحات)
|
||||
│ └── api.php # روتهای API
|
||||
│ ├── migrations/ # 15+ migrations
|
||||
│ └── seeders/ # Countries, SystemSettings, DatabaseSeeder
|
||||
│
|
||||
├── resources/views/
|
||||
│ ├── layouts/app.blade.php # لایاوت اصلی
|
||||
│ ├── orders/ # فرم ثبت سفارش
|
||||
│ ├── pricing/ # صفحه استعلام قیمت
|
||||
│ └── pdfs/ # قالبهای PDF
|
||||
│ └── pdfs/ # awb.blade, invoice.blade, label.blade
|
||||
│
|
||||
├── config/
|
||||
│ ├── ifnex.php # تنظیمات اختصاصی IFNEX
|
||||
│ └── cors.php # تنظیمات CORS
|
||||
│
|
||||
├── tests/
|
||||
│ └── Feature/
|
||||
│ └── Services/
|
||||
│ └── PriceCalculatorServiceTest.php # ⭐ تستهای موتور قیمت
|
||||
│
|
||||
├── bootstrap/
|
||||
│ └── app.php # Bootstrap لاراول ۱۱
|
||||
│
|
||||
├── .env.example # نمونه فایل محیط
|
||||
├── composer.json # وابستگیهای Composer
|
||||
└── README.md # این فایل
|
||||
|
||||
|
||||
API Endpoints
|
||||
|
||||
🔓 API های عمومی (نیاز به API Key)
|
||||
|
||||
۱. رهگیری مرسوله
|
||||
GET /api/v1/track/{awb_no}
|
||||
|
||||
Headers:
|
||||
Authorization: Bearer {IFNEX_API_KEY}
|
||||
|
||||
مثال:
|
||||
curl -H "Authorization: Bearer ifnex-local-dev-key" \
|
||||
http://localhost:8000/api/v1/track/980100010
|
||||
|
||||
پاسخ موفق (200 OK):
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"awb_no": "980100010",
|
||||
"status": "delivered",
|
||||
"carrier_mappings": [...],
|
||||
"tracking_events": [...]
|
||||
}
|
||||
}
|
||||
|
||||
۲. استعلام قیمت
|
||||
POST /api/v1/calculate
|
||||
|
||||
Body (JSON):
|
||||
{
|
||||
"direction": "export",
|
||||
"type": "DOC_NORMAL",
|
||||
"country_iso": "US",
|
||||
"weight": 2.5,
|
||||
"volumetric_weight": 3.0,
|
||||
"extra_service": 10.00
|
||||
}
|
||||
|
||||
مثال:
|
||||
curl -X POST http://localhost:8000/api/v1/calculate \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"direction": "export",
|
||||
"type": "DOC_NORMAL",
|
||||
"country_iso": "US",
|
||||
"weight": 2.5,
|
||||
"volumetric_weight": 3.0
|
||||
}'
|
||||
|
||||
پاسخ موفق:
|
||||
{
|
||||
"base_price": 40.00,
|
||||
"net_dirham": 50.00,
|
||||
"net_rial": 22750000,
|
||||
"total_fee": 24906510.9,
|
||||
"zone": 1,
|
||||
"chargeable_weight": 3.0
|
||||
}
|
||||
|
||||
💳 API های کیف پول (فاز ۲)
|
||||
|
||||
۱. بررسی موجودی
|
||||
GET /api/v1/wallet/balance
|
||||
|
||||
۲. شارژ کیف پول
|
||||
POST /api/v1/wallet/charge
|
||||
|
||||
Body:
|
||||
|
||||
{
|
||||
"amount": 1000000,
|
||||
"description": "شارژ اولیه"
|
||||
}
|
||||
|
||||
۳. تاریخچه تراکنشها
|
||||
GET /api/v1/wallet/transactions
|
||||
|
||||
🎟️ API های تخفیف (فاز ۲)
|
||||
۱. لیست کدهای تخفیف فعال
|
||||
|
||||
GET /api/v1/discount-codes/active
|
||||
|
||||
۲. اعتبارسنجی کد تخفیف
|
||||
POST /api/v1/discount-codes/validate
|
||||
|
||||
Body:
|
||||
{
|
||||
"code": "SUMMER20",
|
||||
"amount": 1000000
|
||||
}
|
||||
|
||||
🔐 API های احراز هویت (فاز ۳)
|
||||
|
||||
۱. ورود و دریافت توکن Sanctum
|
||||
POST /api/v1/auth/login
|
||||
|
||||
Body:
|
||||
{
|
||||
"email": "user@example.com",
|
||||
"password": "password",
|
||||
"token_name": "api-token"
|
||||
}
|
||||
|
||||
۲. خروج و حذف توکن
|
||||
POST /api/v1/auth/logout
|
||||
|
||||
Header: Authorization: Bearer {token}
|
||||
|
||||
🛒 API های سفارشات مشتری (فاز ۳)
|
||||
|
||||
۱. پروفایل و آمار کاربر
|
||||
GET /api/v1/customer/profile
|
||||
|
||||
۲. لیست کشورها برای فرم سفارش
|
||||
GET /api/v1/customer/countries
|
||||
|
||||
۳. لیست سفارشات کاربر
|
||||
GET /api/v1/customer/orders
|
||||
|
||||
۴. ثبت سفارش جدید
|
||||
POST /api/v1/customer/orders
|
||||
|
||||
Body:
|
||||
{
|
||||
"direction": "export",
|
||||
"type": "PARCEL",
|
||||
"from_country_id": 1,
|
||||
"to_country_id": 2,
|
||||
"weight": 2.5,
|
||||
"sender_name": "نام فرستنده",
|
||||
"sender_phone": "۰۹۱۲۳۴۵۶۷۸۹",
|
||||
"sender_address": "آدرس",
|
||||
"receiver_name": "نام گیرنده",
|
||||
"receiver_phone": "۰۹۱۲۳۴۵۶۷۸۹",
|
||||
"receiver_address": "آدرس",
|
||||
"items": [
|
||||
{
|
||||
"description": "کالای گمرکی",
|
||||
"hs_code": "8542390001",
|
||||
"quantity": 1,
|
||||
"unit_price": 100
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
۵. جزئیات یک سفارش
|
||||
GET /api/v1/customer/orders/{shipment}
|
||||
|
||||
۶. لغو سفارش (فقط pending_payment)
|
||||
POST /api/v1/customer/orders/{shipment}/cancel
|
||||
|
||||
۷. پرداخت از کیف پول
|
||||
POST /api/v1/customer/orders/{shipment}/pay-wallet
|
||||
|
||||
۸. پرداخت از درگاه بانکی
|
||||
POST /api/v1/customer/orders/{shipment}/pay-gateway
|
||||
|
||||
Body:
|
||||
{
|
||||
"frontend_callback": "https://your-wordpress.com/order-payment/"
|
||||
}
|
||||
|
||||
🔗 API پل وردپرس (فاز ۳)
|
||||
|
||||
POST /api/v1/bridge/login
|
||||
|
||||
Body:
|
||||
{
|
||||
"bridge_api_key": "ifnex-bridge-key",
|
||||
"wp_user_id": 1,
|
||||
"wp_user_email": "user@wordpress.local",
|
||||
"wp_user_name": "نام کاربر"
|
||||
}
|
||||
|
||||
|
||||
Artisan Commands
|
||||
📥 واردات دادهها
|
||||
۱. واردات تعرفههای حمل از اکسل
|
||||
|
||||
# واردات عادی
|
||||
php artisan ifnex:import:rates storage/app/public/rates.xlsx
|
||||
|
||||
# پاکسازی و واردات مجدد
|
||||
php artisan ifnex:import:rates storage/app/public/rates.xlsx --clear
|
||||
|
||||
# تست بدون ذخیره (Dry Run)
|
||||
php artisan ifnex:import:rates storage/app/public/rates.xlsx --dry-run
|
||||
|
||||
۲. واردات مرسولات تاریخی
|
||||
|
||||
php artisan ifnex:import:shipments storage/app/public/historical.xlsx
|
||||
|
||||
💱 بهروزرسانی نرخ ارز (فاز ۲)
|
||||
# بهروزرسانی دستی
|
||||
php artisan ifnex:update-exchange-rates
|
||||
|
||||
# تنظیم Cron Job برای بهروزرسانی روزانه
|
||||
# crontab -e
|
||||
# 0 0 * * * cd /path/to/04_Laravel && php artisan ifnex:update-exchange-rates >> /dev/null 2>&1
|
||||
|
||||
🔄 سینک کاربران وردپرس (فاز ۳)
|
||||
# سینک دستی کاربران بین وردپرس و لاراول
|
||||
php artisan ifnex:sync-wp-users
|
||||
|
||||
🔑 تولید توکن API (فاز ۲)
|
||||
php artisan ifnex:token --user=admin@ifnex.local --name=api-token
|
||||
|
||||
🧪 تستها
|
||||
# اجرای همه تستها
|
||||
php artisan test
|
||||
|
||||
# اجرای تستهای یک کلاس خاص
|
||||
php artisan test --filter=PriceCalculatorServiceTest
|
||||
|
||||
# اجرای تست با نمایش دقیق
|
||||
php artisan test --filter=it_calculates_price_correctly_for_standard_package
|
||||
|
||||
# گزارش پوشش تست (نیاز به Xdebug)
|
||||
php artisan test --coverage
|
||||
|
||||
تستها
|
||||
تستهای موجود
|
||||
۱. PriceCalculatorServiceTest
|
||||
این تست کلاس PriceCalculatorService را به طور کامل تست میکند:
|
||||
|
||||
php artisan test --filter=PriceCalculatorServiceTest
|
||||
|
||||
|
||||
موارد تست شده:
|
||||
✅ محاسبه صحیح قیمت برای بسته استاندارد
|
||||
✅ استفاده از وزن حجمی وقتی از وزن واقعی بزرگتر است
|
||||
✅ اعمال صحیح ضریب سود و VAT
|
||||
✅ اعمال هزینههای جانبی
|
||||
✅ اعمال کد تخفیف درصدی و ثابت
|
||||
|
||||
۲. WalletServiceTest (فاز ۲)
|
||||
تستهای مربوط به کیف پول و تراکنشها:
|
||||
|
||||
php artisan test --filter=WalletServiceTest
|
||||
|
||||
|
||||
۳. PaymentControllerTest (فاز ۲)
|
||||
تستهای مربوط به درگاه پرداخت:
|
||||
|
||||
php artisan test --filter=PaymentControllerTest
|
||||
|
||||
|
||||
۴. DiscountCodeControllerTest (فاز ۲)
|
||||
تستهای مربوط به کدهای تخفیف:
|
||||
|
||||
php artisan test --filter=DiscountCodeControllerTest
|
||||
|
||||
|
||||
نوشتن تست جدید
|
||||
برای نوشتن تست جدید، از این الگو استفاده کنید:
|
||||
|
||||
<?php
|
||||
|
||||
namespace Tests\Feature\Services;
|
||||
|
||||
use App\Models\Country;
|
||||
use App\Models\ShippingRate;
|
||||
use App\Models\SystemSetting;
|
||||
use App\Services\PriceCalculatorService;
|
||||
use Illuminate\Foundation\Testing\RefreshDatabase;
|
||||
use PHPUnit\Framework\Attributes\Test;
|
||||
use Tests\TestCase;
|
||||
|
||||
class PriceCalculatorServiceTest extends TestCase
|
||||
{
|
||||
use RefreshDatabase;
|
||||
|
||||
#[Test]
|
||||
public function it_calculates_price_correctly()
|
||||
{
|
||||
// 1. تنظیم SystemSetting ها
|
||||
SystemSetting::create(['key' => 'profit_margin', 'value' => 1.0]);
|
||||
SystemSetting::create(['key' => 'aed_to_irr', 'value' => 1.0]);
|
||||
SystemSetting::create(['key' => 'vat_rate', 'value' => 0.0]);
|
||||
SystemSetting::create(['key' => 'packing_cost_default', 'value' => 0]);
|
||||
|
||||
// 2. ایجاد دادههای تست
|
||||
$country = Country::factory()->create([...]);
|
||||
ShippingRate::create([...]);
|
||||
|
||||
// 3. اجرای سرویس
|
||||
$service = app(PriceCalculatorService::class);
|
||||
$result = $service->calculate([...]);
|
||||
|
||||
// 4. بررسی نتیجه
|
||||
$this->assertEquals(50.00, $result['total_fee']);
|
||||
}
|
||||
}
|
||||
|
||||
پیکربندی
|
||||
فایل config/ifnex.php
|
||||
return [
|
||||
// API Key برای احراز هویت
|
||||
'api_key' => env('IFNEX_API_KEY', 'default-key'),
|
||||
|
||||
// Rate Limiting
|
||||
'tracking_rate_limit' => env('IFNEX_TRACKING_RATE_LIMIT', 60),
|
||||
|
||||
// Currency API
|
||||
'currency_api_key' => env('CURRENCY_API_KEY'),
|
||||
'currency_api_url' => env('CURRENCY_API_URL', 'https://api.freecurrencyapi.com/v1/latest'),
|
||||
|
||||
// Zarinpal Payment Gateway
|
||||
'zarinpal' => [
|
||||
'merchant_id' => env('ZARINPAL_MERCHANT_ID', 'fake-merchant-id-for-testing'),
|
||||
'sandbox' => env('ZARINPAL_SANDBOX', true),
|
||||
'callback_url' => env('ZARINPAL_CALLBACK_URL', 'http://localhost:8000/api/v1/payment/callback'),
|
||||
],
|
||||
|
||||
// WordPress Bridge
|
||||
'bridge_api_key' => env('IFNEX_BRIDGE_API_KEY', 'ifnex-bridge-key'),
|
||||
|
||||
// CORS
|
||||
'cors_allowed_origins' => explode(',', env('CORS_ALLOWED_ORIGINS', '*')),
|
||||
];
|
||||
|
||||
فایل config/cors.php
|
||||
|
||||
return [
|
||||
'paths' => ['api/*'],
|
||||
'allowed_methods' => ['*'],
|
||||
'allowed_origins' => explode(',', env('CORS_ALLOWED_ORIGINS', '*')),
|
||||
'allowed_headers' => ['*'],
|
||||
'exposed_headers' => [],
|
||||
'max_age' => 0,
|
||||
'supports_credentials' => false,
|
||||
];
|
||||
|
||||
|
||||
نکات امنیتی
|
||||
🚫 هرگز این کارها را نکنید
|
||||
هرگز فایل .env را در Git کامیت نکنید
|
||||
|
||||
# بررسی کنید در .gitignore باشد
|
||||
.env
|
||||
.env.local
|
||||
.env.production
|
||||
|
||||
هرگز APP_DEBUG=true را در محیط تولید بگذارید
|
||||
# Production
|
||||
APP_DEBUG=false
|
||||
|
||||
|
||||
هرگز از CORS * در محیط تولید استفاده نکنید
|
||||
|
||||
# فقط دامنه وردپرس
|
||||
CORS_ALLOWED_ORIGINS=https://your-wordpress-domain.com
|
||||
|
||||
هرگز API Key را در کد Hardcode نکنید
|
||||
|
||||
// ❌ اشتباه
|
||||
$apiKey = 'secret-key-123';
|
||||
|
||||
// ✅ درست
|
||||
$apiKey = config('ifnex.api_key');
|
||||
|
||||
🐛 عیبیابی
|
||||
مشکل: CHECK constraint failed: direction
|
||||
علت: Factory مقادیر پیشفرض اشتباه میسازد (مثلاً 'Outbound' به جای 'export')
|
||||
راهحل: در تستها از ShippingRate::create() به جای ShippingRate::factory()->create() استفاده کنید:
|
||||
ShippingRate::create([
|
||||
'direction' => 'export', // حروف کوچک
|
||||
'type' => 'DOC_NORMAL',
|
||||
'weight' => 1.0,
|
||||
'zone_1' => 20.00,
|
||||
// ... بقیه zone ها
|
||||
]);
|
||||
|
||||
|
||||
مشکل: No rate found for the given parameters
|
||||
علت: Query نمیتواند نرخ مناسبی پیدا کند
|
||||
راهحل:
|
||||
بررسی کنید که zone_column درست است (zone_1, zone_2, ...)
|
||||
مطمئن شوید که وزن در تست بیشتر از وزنهای موجود در دیتابیس نیست
|
||||
SystemSetting ها را در تست Mock کنید
|
||||
📞 پشتیبانی
|
||||
اگر سوالی داشتید که در این فایل یا مستندات 01_Documents پاسخ آن نبود، از کاربر (Kazem) بپرسید — حدس نزنید.
|
||||
© 2026 VernaSoft Group. Internal use only.
|
||||
├── routes/
|
||||
│ ├── api.php # REST API
|
||||
│ └── web.php # Web + Download Template
|
||||
|
||||
└── config/
|
||||
└── ifnex.php # تنظیمات اختصاصی
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🗃️ Models
|
||||
|
||||
| Model | جدول | توضیح |
|
||||
|-------|------|--------|
|
||||
| Country | countries | ۲۳۳ کشور با ۴ زون |
|
||||
| Shipment | shipments | مرسولهها (مرکزی) |
|
||||
| ShipmentItem | shipment_items | اقلام گمرکی |
|
||||
| ShipmentPackage | shipment_packages | بستههای چندگانه |
|
||||
| ShipmentCarrierMapping | shipment_carrier_mappings | نگاشت شرکتهای حمل |
|
||||
| ShipmentTrackingEvent | shipment_tracking_events | رویدادهای ترکینگ |
|
||||
| ShipmentStatusHistory | shipment_status_histories | تاریخچه تغییرات |
|
||||
| ShippingRate | shipping_rates | تعرفههای حمل |
|
||||
| SystemSetting | system_settings | تنظیمات key-value |
|
||||
| Currency | currencies | ارزهای پشتیبانی |
|
||||
| User | users | کاربران سیستم |
|
||||
| Wallet | wallets | کیف پول کاربران |
|
||||
| WalletTransaction | wallet_transactions | تراکنشها |
|
||||
|
||||
---
|
||||
|
||||
## 🎨 Filament Resources
|
||||
|
||||
| Resource | توضیح |
|
||||
|----------|--------|
|
||||
| ShipmentResource | مدیریت مرسولهها (جدول + فرم + جزئیات + CSV) |
|
||||
| CountryResource | مدیریت کشورها |
|
||||
| ShippingRateResource | مدیریت تعرفهها |
|
||||
| CurrencyResource | مدیریت ارزها |
|
||||
|
||||
### RelationManagers
|
||||
|
||||
| RelationManager | والد | توضیح |
|
||||
|---------------|------|--------|
|
||||
| TrackingEventsRelationManager | Shipment | رویدادهای ترکینگ |
|
||||
| CarrierMappingsRelationManager | Shipment | نگاشت شرکتهای حمل |
|
||||
| ItemsRelationManager | Shipment | اقلام گمرکی |
|
||||
|
||||
### صفحات سفارشی
|
||||
|
||||
| صفحه | توضیح |
|
||||
|-------|--------|
|
||||
| SettingsPage | تنظیمات سیستم (key-value) |
|
||||
| PriceTestPage | تست محاسبه قیمت |
|
||||
| ImportRatesPage | آپلود اکسل نرخها |
|
||||
|
||||
---
|
||||
|
||||
## 🔴 خط قرمزها
|
||||
|
||||
| ❌ هرگز | ✅ همیشه |
|
||||
|------------|------------|
|
||||
| برگرداندن countries به ۲ زون | ۴ زون مجزا |
|
||||
| استفاده از ۲ نوع سرویس | ۳ نوع (DOC_NORMAL, DOC_ECONOMY, PARCEL) |
|
||||
| ذخیره تاریخ شمسی در DB | ذخیره timestamp میلادی |
|
||||
| CORS `*` در Production | CORS محدود به دامنه وردپرس |
|
||||
| کامیت `.env` در Git | در `.gitignore` باشد |
|
||||
| `APP_DEBUG=true` در Production | `APP_DEBUG=false` |
|
||||
| PDF فارسی (AWB/Invoice/Label) | همیشه انگلیسی |
|
||||
| کپی از DHL | طراحی منحصر به فرد IFNEX |
|
||||
|
||||
---
|
||||
|
||||
## 📚 مستندات
|
||||
|
||||
| فایل | محتوا |
|
||||
|------|-------|
|
||||
| [IFNEX_Phase0_Checklist.md](../01_Documents/IFNEX_Phase0_Checklist.md) | چکلیست کامل |
|
||||
| [IFNEX_Roadmap.md](../01_Documents/IFNEX_Roadmap.md) | نقشه راه |
|
||||
| [IFNEX_File_Map.md](../01_Documents/IFNEX_File_Map.md) | نقشه فایلها |
|
||||
| [DEPLOYMENT.md](../DEPLOYMENT.md) | راهنمای استقرار |
|
||||
|
||||
---
|
||||
|
||||
<div align="center">
|
||||
|
||||
© 2026 VernaSoft Group. All Rights Reserved.
|
||||
|
||||
</div>
|
||||
665
DEPLOYMENT.md
665
DEPLOYMENT.md
@ -1,616 +1,227 @@
|
||||
# 📦 راهنمای دپلوی IFNEX Logistics Platform
|
||||
# راهنمای استقرار IFNEX
|
||||
|
||||
راهنمای کامل انتقال پروژه از محیط توسعه (XAMPP) به سرور Production
|
||||
|
||||
**نسخه:** 1.0.0
|
||||
**تاریخ:** 2026-08-10
|
||||
**نویسنده:** تیم توسعه IFNEX
|
||||
> **آخرین بروزرسانی:** 2026-08-29
|
||||
|
||||
---
|
||||
|
||||
## 📋 فهرست مطالب
|
||||
## محیطها
|
||||
|
||||
1. [پیشنیازهای سرور](#۱-پیشنیازهای-سرور)
|
||||
2. [ساختار پروژه](#۲-ساختار-پروژه)
|
||||
3. [دپلوی Laravel (Backend)](#۳-دپلوی-laravel-backend)
|
||||
4. [دپلوی WordPress (Frontend)](#۴-دپلوی-wordpress-frontend)
|
||||
5. [اتصال دو سیستم (Bridge)](#۵-اتصال-دو-سیستم-bridge)
|
||||
6. [تنظیمات امنیتی](#۶-تنظیمات-امنیتی)
|
||||
7. [Cron Jobs](#۷-cron-jobs)
|
||||
8. [Backup Strategy](#۸-backup-strategy)
|
||||
9. [چکلیست نهایی](#۹-چکلیست-نهایی)
|
||||
10. [Troubleshooting](#۱۰-troubleshooting)
|
||||
| محیط | دامنه | نقش |
|
||||
|-------|-------|------|
|
||||
| Production | api.ifnex.vernahost.ir | API لاراول |
|
||||
| Production | ifnex.vernahost.ir | وبسایت وردپرس |
|
||||
| Local | localhost:8000 | توسعه |
|
||||
|
||||
---
|
||||
|
||||
## ۱. پیشنیازهای سرور
|
||||
## پیشنیازها
|
||||
|
||||
### حداقل نیازمندیها
|
||||
|
||||
| مورد | حداقل | پیشنهادی |
|
||||
|------|-------|----------|
|
||||
| PHP | 8.2 | 8.3 |
|
||||
| MySQL | 8.0 | 8.0+ |
|
||||
| RAM | 2GB | 4GB |
|
||||
| Disk | 20GB SSD | 50GB NVMe |
|
||||
| Web Server | Apache 2.4 / Nginx 1.24 | Nginx |
|
||||
|
||||
### افزونههای PHP مورد نیاز
|
||||
|
||||
```bash
|
||||
php -m | grep -E "pdo_mysql|mbstring|openssl|tokenizer|xml|ctype|json|bcmath|gd|zip|curl|intl"
|
||||
```
|
||||
|
||||
لیست کامل:
|
||||
- `pdo_mysql` - اتصال به MySQL
|
||||
- `mbstring` - پشتیبانی UTF-8 (فارسی)
|
||||
- `openssl` - رمزنگاری
|
||||
- `tokenizer` - Laravel
|
||||
- `xml` - Laravel
|
||||
- `ctype` - Laravel
|
||||
- `json` - Laravel
|
||||
- `bcmath` - محاسبات مالی
|
||||
- `gd` یا `imagick` - پردازش تصویر
|
||||
- `zip` - Composer
|
||||
- `curl` - درخواستهای HTTP
|
||||
- `intl` - تاریخ شمسی (Jalali)
|
||||
|
||||
### نصب Composer و Node
|
||||
|
||||
```bash
|
||||
# Composer
|
||||
curl -sS https://getcomposer.org/installer | php
|
||||
mv composer.phar /usr/local/bin/composer
|
||||
|
||||
# بررسی نسخه
|
||||
composer --version
|
||||
```
|
||||
- SSH دسترسی به سرور
|
||||
- HestiaCP (مدیریت سرور)
|
||||
- Git روی سرور
|
||||
- Composer روی سرور (اختیاری — بهتره locallly نصب کنی)
|
||||
|
||||
---
|
||||
|
||||
## ۲. ساختار پروژه
|
||||
## ۱. استقرار لاراول
|
||||
|
||||
```
|
||||
IFNEX-Logistics/
|
||||
├── 01_WordPress/ # (قدیمی - قابل حذف بعد از مهاجرت)
|
||||
├── 03_WordPress/ # ✅ وردپرس اصلی (Frontend مشتری)
|
||||
│ └── wp-content/
|
||||
│ ├── plugins/
|
||||
│ │ └── ifnex-bridge/ # ✅ پلاگین اتصال به Laravel
|
||||
│ └── themes/
|
||||
│ └── ifnex/ # ✅ قالب اختصاصی
|
||||
├── 04_Laravel/ # ✅ Laravel (Backend + پنل ادمین)
|
||||
│ ├── app/
|
||||
│ ├── database/
|
||||
│ ├── public/ # Document root برای Laravel
|
||||
│ └── routes/
|
||||
└── DEPLOYMENT.md # این فایل
|
||||
```
|
||||
|
||||
### Document Roots روی سرور
|
||||
|
||||
| دامنه | مسیر |
|
||||
|-------|------|
|
||||
| `ifnex.com` | `/var/www/IFNEX/03_WordPress` |
|
||||
| `api.ifnex.com` یا `ifnex.com/api` | `/var/www/IFNEX/04_Laravel/public` |
|
||||
|
||||
---
|
||||
|
||||
## ۳. دپلوی Laravel (Backend)
|
||||
|
||||
### گام ۱: آپلود فایلها
|
||||
### ۱.۱ کلون مخزن روی سرور
|
||||
|
||||
```bash
|
||||
# از سیستم محلی به سرور
|
||||
scp -r 04_Laravel user@server:/var/www/IFNEX/
|
||||
|
||||
# یا با rsync (پیشنهادی)
|
||||
rsync -avz --exclude 'vendor' --exclude 'node_modules' \
|
||||
04_Laravel/ user@server:/var/www/IFNEX/04_Laravel/
|
||||
cd /home/USER/web/api.ifnex.vernahost.ir/public_html
|
||||
git clone https://www.git.vernahost.ir/gitmodir110/ifnex.git .
|
||||
```
|
||||
|
||||
### گام ۲: نصب Dependencies
|
||||
> اگر پوشه لاراول زیرمسیر `04_Laravel/` هست:
|
||||
|
||||
```bash
|
||||
cd /var/www/IFNEX/04_Laravel
|
||||
|
||||
# نصب بدون dev packages (برای production)
|
||||
composer install --optimize-autoloader --no-dev --no-interaction
|
||||
cd /home/USER/web/api.ifnex.vernahost.ir/public_html
|
||||
ngit clone https://www.git.vernahost.ir/gitmodir110/ifnex.git tmp-ifnex
|
||||
cp -r tmp-ifnex/04_Laravel/* .
|
||||
cp -r tmp-ifnex/04_Laravel/.* . 2>/dev/null
|
||||
rm -rf tmp-ifnex
|
||||
```
|
||||
|
||||
### گام ۳: تنظیم `.env`
|
||||
### ۱.۲ نصب وابستگیها
|
||||
|
||||
فایل `.env` را برای production تنظیم کن:
|
||||
```bash
|
||||
ncd /home/USER/web/api.ifnex.vernahost.ir/public_html
|
||||
composer install --no-dev --optimize-autoloader
|
||||
```
|
||||
|
||||
### ۱.۳ تنظیم .env
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
nano .env
|
||||
```
|
||||
|
||||
مقادیر مهم:
|
||||
|
||||
```env
|
||||
# ─── تنظیمات پایه ───────────────────────────
|
||||
APP_NAME="IFNEX Logistics"
|
||||
APP_ENV=production
|
||||
APP_KEY=base64:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
|
||||
APP_DEBUG=false
|
||||
APP_URL=https://api.ifnex.com
|
||||
APP_URL=https://api.ifnex.vernahost.ir
|
||||
|
||||
# ─── دیتابیس ─────────────────────────────────
|
||||
DB_CONNECTION=mysql
|
||||
DB_HOST=127.0.0.1
|
||||
DB_PORT=3306
|
||||
DB_DATABASE=ifnex_laravel
|
||||
DB_HOST=localhost
|
||||
DB_DATABASE=ifnex_db
|
||||
DB_USERNAME=ifnex_user
|
||||
DB_PASSWORD=StrongPassword@123
|
||||
DB_PASSWORD=STRONG_PASSWORD
|
||||
|
||||
# ─── Session و Cache ─────────────────────────
|
||||
SESSION_DRIVER=database
|
||||
CACHE_STORE=redis
|
||||
QUEUE_CONNECTION=database
|
||||
CORS_ALLOWED_ORIGINS=https://ifnex.vernahost.ir
|
||||
|
||||
# ─── Sanctum ─────────────────────────────────
|
||||
SANCTUM_STATEFUL_DOMAINS=ifnex.com,www.ifnex.com
|
||||
SESSION_DOMAIN=.ifnex.com
|
||||
|
||||
# ─── IFNEX Bridge ────────────────────────────
|
||||
# ⚠️ مهم: این کلید باید با وردپرس یکسان باشد
|
||||
IFNEX_BRIDGE_API_KEY=your-very-strong-random-key-here
|
||||
|
||||
# ─── Zarinpal ────────────────────────────────
|
||||
ZARINPAL_MERCHANT_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
|
||||
ZARINPAL_SANDBOX=false
|
||||
|
||||
# ─── Mail ────────────────────────────────────
|
||||
MAIL_MAILER=smtp
|
||||
MAIL_HOST=smtp.ifnex.com
|
||||
MAIL_PORT=587
|
||||
MAIL_USERNAME=noreply@ifnex.com
|
||||
MAIL_PASSWORD=xxxxx
|
||||
MAIL_ENCRYPTION=tls
|
||||
ZARINPAL_MERCHANT_ID=YOUR_MERCHANT_ID
|
||||
```
|
||||
|
||||
**تولید کلید امن:**
|
||||
```bash
|
||||
php artisan key:generate --show
|
||||
openssl rand -hex 32 # برای BRIDGE_API_KEY
|
||||
```
|
||||
|
||||
### گام ۴: ساخت دیتابیس
|
||||
### ۱.۴ دیتابیس
|
||||
|
||||
```bash
|
||||
mysql -u root -p
|
||||
```
|
||||
|
||||
```sql
|
||||
CREATE DATABASE ifnex_laravel CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
|
||||
CREATE USER 'ifnex_user'@'localhost' IDENTIFIED BY 'StrongPassword@123';
|
||||
GRANT ALL PRIVILEGES ON ifnex_laravel.* TO 'ifnex_user'@'localhost';
|
||||
FLUSH PRIVILEGES;
|
||||
EXIT;
|
||||
```
|
||||
|
||||
### گام ۵: Import دیتابیس از توسعه
|
||||
|
||||
```bash
|
||||
# از سیستم محلی (XAMPP)
|
||||
mysqldump -u root ifnex_laravel > ifnex_backup.sql
|
||||
|
||||
# آپلود به سرور
|
||||
scp ifnex_backup.sql user@server:/tmp/
|
||||
|
||||
# Import روی سرور
|
||||
mysql -u ifnex_user -p ifnex_laravel < /tmp/ifnex_backup.sql
|
||||
```
|
||||
|
||||
### گام ۶: Migrations و Cache
|
||||
|
||||
```bash
|
||||
cd /var/www/IFNEX/04_Laravel
|
||||
# ایجاد دیتابیس (اگر وجود نداره)
|
||||
mysql -u root -p -e "CREATE DATABASE ifnex_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
|
||||
|
||||
# اجرای migrations
|
||||
php artisan migrate --force
|
||||
|
||||
# Seed دادههای اولیه (نرخ ارز، zones، ...)
|
||||
php artisan db:seed --class=SampleShippingRatesSeeder --force
|
||||
# اجرای seeders (فقط بار اول)
|
||||
php artisan db:seed --force
|
||||
```
|
||||
|
||||
# ساخت cache ها برای سرعت
|
||||
### ۱.۵ پیکربندی نهایی
|
||||
|
||||
```bash
|
||||
php artisan config:cache
|
||||
php artisan route:cache
|
||||
php artisan view:cache
|
||||
php artisan event:cache
|
||||
|
||||
# Permissions
|
||||
chmod -R 775 storage bootstrap/cache
|
||||
chown -R www-data:www-data storage bootstrap/cache
|
||||
```
|
||||
|
||||
### گام ۷: تنظیم Nginx
|
||||
|
||||
فایل `/etc/nginx/sites-available/ifnex-api`:
|
||||
|
||||
```nginx
|
||||
server {
|
||||
listen 80;
|
||||
server_name api.ifnex.com;
|
||||
return 301 https://$server_name$request_uri;
|
||||
}
|
||||
|
||||
server {
|
||||
listen 443 ssl http2;
|
||||
server_name api.ifnex.com;
|
||||
|
||||
root /var/www/IFNEX/04_Laravel/public;
|
||||
index index.php;
|
||||
|
||||
# SSL
|
||||
ssl_certificate /etc/letsencrypt/live/api.ifnex.com/fullchain.pem;
|
||||
ssl_certificate_key /etc/letsencrypt/live/api.ifnex.com/privkey.pem;
|
||||
|
||||
# Security headers
|
||||
add_header X-Frame-Options SAMEORIGIN;
|
||||
add_header X-Content-Type-Options nosniff;
|
||||
add_header X-XSS-Protection "1; mode=block";
|
||||
|
||||
# Upload limits
|
||||
client_max_body_size 50M;
|
||||
|
||||
location / {
|
||||
try_files $uri $uri/ /index.php?$query_string;
|
||||
}
|
||||
|
||||
location ~ \.php$ {
|
||||
fastcgi_pass unix:/var/run/php/php8.2-fpm.sock;
|
||||
fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
|
||||
include fastcgi_params;
|
||||
}
|
||||
|
||||
# مسدود کردن فایلهای حساس
|
||||
location ~ /\.(env|git) {
|
||||
deny all;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
فعالسازی:
|
||||
```bash
|
||||
ln -s /etc/nginx/sites-available/ifnex-api /etc/nginx/sites-enabled/
|
||||
nginx -t && systemctl reload nginx
|
||||
```
|
||||
|
||||
### گام ۸: SSL رایگان با Let's Encrypt
|
||||
|
||||
```bash
|
||||
apt install certbot python3-certbot-nginx
|
||||
certbot --nginx -d api.ifnex.com
|
||||
php artisan filament:clear-cached-components
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ۴. دپلوی WordPress (Frontend)
|
||||
## ۲. استقرار وردپرس (پلاگین و قالب)
|
||||
|
||||
### گام ۱: آپلود فایلها
|
||||
### ۲.۱ آپلود فایلها
|
||||
|
||||
```bash
|
||||
rsync -avz --exclude 'wp-content/uploads' \
|
||||
03_WordPress/ user@server:/var/www/IFNEX/03_WordPress/
|
||||
# قالب IFNEX
|
||||
cd /home/USER/web/ifnex.vernahost.ir/public_html/wp-content/themes/
|
||||
# فایلهای قالب را اینجا آپلود/بروزرسانی کن
|
||||
|
||||
# پلاگین IFNEX Bridge
|
||||
cd /home/USER/web/ifnex.vernahost.ir/public_html/wp-content/plugins/
|
||||
# فایلهای پلاگین را اینجا آپلود/بروزرسانی کن
|
||||
```
|
||||
|
||||
### گام ۲: تنظیم `wp-config.php`
|
||||
### ۲.۲ تنظیم پلاگین
|
||||
|
||||
```php
|
||||
<?php
|
||||
// ─── دیتابیس ─────────────────────────────
|
||||
define('DB_NAME', 'ifnex_wp');
|
||||
define('DB_USER', 'ifnex_wp_user');
|
||||
define('DB_PASSWORD', 'StrongPassword@456');
|
||||
define('DB_HOST', 'localhost');
|
||||
define('DB_CHARSET', 'utf8mb4');
|
||||
در پیشخوان وردپرس → تنظیمات → IFNEX Bridge:
|
||||
|
||||
// ─── کلیدهای امنیتی ──────────────────────
|
||||
// از https://api.wordpress.org/secret-key/1.1/salt/ بگیرید
|
||||
define('AUTH_KEY', 'xxxxx');
|
||||
define('SECURE_AUTH_KEY', 'xxxxx');
|
||||
define('LOGGED_IN_KEY', 'xxxxx');
|
||||
define('NONCE_KEY', 'xxxxx');
|
||||
|
||||
// ─── Production ──────────────────────────
|
||||
define('WP_DEBUG', false);
|
||||
define('WP_DEBUG_LOG', false);
|
||||
define('WP_DEBUG_DISPLAY', false);
|
||||
define('SCRIPT_DEBUG', false);
|
||||
|
||||
// ─── Performance ─────────────────────────
|
||||
define('WP_CACHE', true);
|
||||
|
||||
define('ABSPATH', __DIR__ . '/');
|
||||
require_once ABSPATH . 'wp-settings.php';
|
||||
```
|
||||
|
||||
### گام ۳: Import دیتابیس وردپرس
|
||||
|
||||
```bash
|
||||
mysqldump -u root ifnexwp > ifnexwp_backup.sql
|
||||
scp ifnexwp_backup.sql user@server:/tmp/
|
||||
mysql -u ifnex_wp_user -p ifnex_wp < /tmp/ifnexwp_backup.sql
|
||||
```
|
||||
|
||||
**اصلاح URLها در دیتابیس:**
|
||||
```sql
|
||||
UPDATE wp_options SET option_value = 'https://ifnex.com'
|
||||
WHERE option_name IN ('siteurl', 'home');
|
||||
|
||||
UPDATE wp_posts SET post_content = REPLACE(post_content,
|
||||
'http://localhost/IFNEX-Logistics/03_WordPress', 'https://ifnex.com');
|
||||
```
|
||||
|
||||
### گام ۴: تنظیم Nginx برای وردپرس
|
||||
|
||||
فایل `/etc/nginx/sites-available/ifnex-wp`:
|
||||
|
||||
```nginx
|
||||
server {
|
||||
listen 443 ssl http2;
|
||||
server_name ifnex.com www.ifnex.com;
|
||||
|
||||
root /var/www/IFNEX/03_WordPress;
|
||||
index index.php;
|
||||
|
||||
ssl_certificate /etc/letsencrypt/live/ifnex.com/fullchain.pem;
|
||||
ssl_certificate_key /etc/letsencrypt/live/ifnex.com/privkey.pem;
|
||||
|
||||
client_max_body_size 50M;
|
||||
|
||||
location / {
|
||||
try_files $uri $uri/ /index.php?$args;
|
||||
}
|
||||
|
||||
location ~ \.php$ {
|
||||
fastcgi_pass unix:/var/run/php/php8.2-fpm.sock;
|
||||
fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
|
||||
include fastcgi_params;
|
||||
}
|
||||
|
||||
# کش فایلهای استاتیک
|
||||
location ~* \.(jpg|jpeg|png|gif|css|js|svg|woff2)$ {
|
||||
expires 30d;
|
||||
add_header Cache-Control "public, immutable";
|
||||
}
|
||||
|
||||
location ~ /\.(env|git) {
|
||||
deny all;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### گام ۵: Permissions
|
||||
|
||||
```bash
|
||||
chown -R www-data:www-data /var/www/IFNEX/03_WordPress
|
||||
find /var/www/IFNEX/03_WordPress -type d -exec chmod 755 {} \;
|
||||
find /var/www/IFNEX/03_WordPress -type f -exec chmod 644 {} \;
|
||||
chmod -R 775 /var/www/IFNEX/03_WordPress/wp-content/uploads
|
||||
```
|
||||
| تنظیم | مقدار |
|
||||
|--------|-------|
|
||||
| API URL | `https://api.ifnex.vernahost.ir/api/v1` |
|
||||
| Bridge API Key | کلید مشترک بین وردپرس و لاراول |
|
||||
|
||||
---
|
||||
|
||||
## ۵. اتصال دو سیستم (Bridge)
|
||||
## ۳. بروزرسانی (بعد از تغییرات جدید)
|
||||
|
||||
### گام ۱: تنظیم پلاگین IFNEX Bridge
|
||||
|
||||
در پیشخوان وردپرس:
|
||||
**IFNEX → تنظیمات**
|
||||
|
||||
| فیلد | مقدار |
|
||||
|------|-------|
|
||||
| API URL | `https://api.ifnex.com/api/v1` |
|
||||
| API Key | (کلید عمومی از Laravel) |
|
||||
| Bridge API Key | (همان مقدار `.env` لاراول) |
|
||||
|
||||
### گام ۲: بررسی اتصال
|
||||
|
||||
در وردپرس یک صفحه تست بساز با شورتکد:
|
||||
```
|
||||
[ifnex_wallet_balance]
|
||||
```
|
||||
|
||||
اگر موجودی نمایش داده شد، اتصال برقرار است. ✅
|
||||
|
||||
### گام ۳: Sync کاربران
|
||||
### ۳.۱ لاراول
|
||||
|
||||
```bash
|
||||
cd /var/www/IFNEX/04_Laravel
|
||||
php artisan ifnex:sync-wp-users \
|
||||
--wp-db-name=ifnex_wp \
|
||||
--wp-db-user=ifnex_wp_user \
|
||||
--wp-db-pass=StrongPassword@456
|
||||
cd /home/USER/web/api.ifnex.vernahost.ir/public_html
|
||||
|
||||
# خاموش کردن موقت سایت
|
||||
php artisan down
|
||||
|
||||
# بکاپ
|
||||
cp .env .env.backup
|
||||
|
||||
# دریافت تغییرات
|
||||
git fetch --all
|
||||
git pull origin main
|
||||
|
||||
# وابستگیها (اگه composer.json تغییر کرده)
|
||||
composer install --no-dev --optimize-autoloader
|
||||
|
||||
# مایگریشنهای جدید
|
||||
php artisan migrate --force
|
||||
|
||||
# پاکسازی کش
|
||||
php artisan config:clear
|
||||
php artisan cache:clear
|
||||
php artisan route:clear
|
||||
php artisan view:clear
|
||||
php artisan filament:clear-cached-components
|
||||
|
||||
# کش مجدد
|
||||
php artisan config:cache
|
||||
php artisan route:cache
|
||||
php artisan view:cache
|
||||
|
||||
# روشن کردن سایت
|
||||
php artisan up
|
||||
```
|
||||
|
||||
### ۳.۲ وردپرس
|
||||
|
||||
```bash
|
||||
cd /home/USER/web/ifnex.vernahost.ir/public_html/wp-content/plugins/ifnex-bridge
|
||||
git pull origin main
|
||||
```
|
||||
|
||||
> اگر پلاگین از طریق گیت کلون نشده، فایلها را دستی آپلود کن.
|
||||
|
||||
---
|
||||
|
||||
## ۶. تنظیمات امنیتی
|
||||
|
||||
### چکلیست امنیتی
|
||||
|
||||
- [ ] `APP_DEBUG=false` در Laravel
|
||||
- [ ] `WP_DEBUG=false` در WordPress
|
||||
- [ ] SSL فعال روی هر دو دامنه
|
||||
- [ ] فایلهای `.env` و `.git` مسدود شدهاند
|
||||
- [ ] رمزهای قوی برای دیتابیس
|
||||
- [ ] `IFNEX_BRIDGE_API_KEY` قوی و تصادفی
|
||||
- [ ] حذف فایلهای debug از production:
|
||||
```bash
|
||||
rm -f debug-payment.php check-*.php test-*.php
|
||||
```
|
||||
- [ ] محدودیت دسترسی به `/admin` (اختیاری: IP whitelist)
|
||||
|
||||
### Firewall (UFW)
|
||||
|
||||
```bash
|
||||
ufw allow 22/tcp # SSH
|
||||
ufw allow 80/tcp # HTTP
|
||||
ufw allow 443/tcp # HTTPS
|
||||
ufw enable
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ۷. Cron Jobs
|
||||
|
||||
### Laravel Scheduler
|
||||
## ۴. تنظیمات Cron
|
||||
|
||||
```bash
|
||||
crontab -e
|
||||
```
|
||||
|
||||
```cron
|
||||
* * * * * cd /var/www/IFNEX/04_Laravel && php artisan schedule:run >> /dev/null 2>&1
|
||||
```
|
||||
|
||||
### Cron آپدیت نرخ ارز (هر ساعت)
|
||||
|
||||
اگر از scheduler استفاده نمیکنید:
|
||||
|
||||
```cron
|
||||
0 * * * * cd /var/www/IFNEX/04_Laravel && php artisan ifnex:update-rates >> /dev/null 2>&1
|
||||
```
|
||||
|
||||
### Cron Backup روزانه (ساعت ۲ بامداد)
|
||||
|
||||
```cron
|
||||
0 2 * * * /var/www/IFNEX/scripts/backup.sh >> /var/log/ifnex-backup.log 2>&1
|
||||
# بهروزرسانی نرخ ارز (اگر ExchangeRateService فعال شد)
|
||||
0 0 * * * cd /home/USER/web/api.ifnex.vernahost.ir/public_html && php artisan ifnex:update-exchange-rates >> /dev/null 2>&1
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ۸. Backup Strategy
|
||||
## ۵. عیبیابی
|
||||
|
||||
### اسکریپت `backup.sh`
|
||||
|
||||
فایل `/var/www/IFNEX/scripts/backup.sh`:
|
||||
### بررسی لاگها
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# ─── IFNEX Backup Script ───────────────────
|
||||
# لاگ لاراول
|
||||
tail -f /home/USER/web/api.ifnex.vernahost.ir/public_html/storage/logs/laravel.log
|
||||
|
||||
BACKUP_DIR="/var/backups/ifnex"
|
||||
DATE=$(date +%Y%m%d_%H%M%S)
|
||||
RETENTION_DAYS=7
|
||||
|
||||
mkdir -p $BACKUP_DIR
|
||||
|
||||
# Backup دیتابیس Laravel
|
||||
mysqldump -u ifnex_user -p'StrongPassword@123' ifnex_laravel \
|
||||
| gzip > $BACKUP_DIR/laravel_$DATE.sql.gz
|
||||
|
||||
# Backup دیتابیس WordPress
|
||||
mysqldump -u ifnex_wp_user -p'StrongPassword@456' ifnex_wp \
|
||||
| gzip > $BACKUP_DIR/wordpress_$DATE.sql.gz
|
||||
|
||||
# Backup فایلهای آپلود وردپرس
|
||||
tar -czf $BACKUP_DIR/uploads_$DATE.tar.gz \
|
||||
-C /var/www/IFNEX/03_WordPress/wp-content uploads
|
||||
|
||||
# حذف backup های قدیمی
|
||||
find $BACKUP_DIR -name "*.gz" -mtime +$RETENTION_DAYS -delete
|
||||
|
||||
echo "✅ Backup completed: $DATE"
|
||||
# لاگ HestiaCP
|
||||
tail -f /var/log/hestia.log
|
||||
```
|
||||
|
||||
اجرا:
|
||||
### کلیر کش
|
||||
|
||||
```bash
|
||||
chmod +x /var/www/IFNEX/scripts/backup.sh
|
||||
php artisan optimize:clear
|
||||
```
|
||||
|
||||
### بررسی وضعیت
|
||||
|
||||
```bash
|
||||
php artisan about
|
||||
php artisan route:list --path=api/v1
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ۹. چکلیست نهایی
|
||||
## ۶. نکات امنیتی
|
||||
|
||||
### قبل از Go-Live
|
||||
|
||||
**Laravel:**
|
||||
- [ ] `php artisan migrate --force` بدون خطا
|
||||
- [ ] `php artisan config:cache` موفق
|
||||
- [ ] ورود به `/admin` با ادمین
|
||||
- [ ] داشبورد بدون خطا لود میشود
|
||||
- [ ] ویجتهای نرخ ارز نمایش داده میشوند
|
||||
|
||||
**WordPress:**
|
||||
- [ ] صفحه اصلی بدون خطا
|
||||
- [ ] ورود مشتری کار میکند
|
||||
- [ ] `/new-order/` فرم را نمایش میدهد
|
||||
- [ ] `/my-orders/` لیست سفارشات را نشان میدهد
|
||||
- [ ] تست کامل: ثبت سفارش → پرداخت → تغییر status
|
||||
|
||||
**اتصال:**
|
||||
- [ ] Bridge API Key یکسان در هر دو طرف
|
||||
- [ ] تست پرداخت از کیف پول موفق
|
||||
- [ ] Tracking event ثبت میشود
|
||||
|
||||
### بعد از Go-Live
|
||||
|
||||
- [ ] مانیتورینگ لاگها:
|
||||
```bash
|
||||
tail -f /var/www/IFNEX/04_Laravel/storage/logs/laravel.log
|
||||
```
|
||||
- [ ] بررسی cron jobs: `crontab -l`
|
||||
- [ ] تست backup و restore
|
||||
- `.env` هرگز در گیت کامیت نشود (در `.gitignore` باشد)
|
||||
- `APP_DEBUG=false` در Production
|
||||
- `CORS_ALLOWED_ORIGINS` فقط دامنه وردپرس
|
||||
- `IFNEX_API_KEY` یک کلید قوی و تصادفی باشد
|
||||
- SSL/HTTPS فعال باشد
|
||||
- رمز عبور دیتابیس قوی باشد
|
||||
|
||||
---
|
||||
|
||||
## ۱۰. Troubleshooting
|
||||
|
||||
### مشکل: خطای 500 در Laravel
|
||||
|
||||
```bash
|
||||
# بررسی لاگ
|
||||
tail -100 storage/logs/laravel.log
|
||||
|
||||
# پاک کردن cache
|
||||
php artisan config:clear
|
||||
php artisan cache:clear
|
||||
|
||||
# بررسی permissions
|
||||
chmod -R 775 storage bootstrap/cache
|
||||
```
|
||||
|
||||
### مشکل: وردپرس به Laravel وصل نمیشود
|
||||
|
||||
```bash
|
||||
# تست اتصال از سرور وردپرس
|
||||
curl -X POST https://api.ifnex.com/api/v1/bridge/login \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"bridge_api_key":"YOUR_KEY","wp_user_id":1,"wp_user_email":"test@test.com"}'
|
||||
```
|
||||
|
||||
### مشکل: خطای "توکن احراز هویت یافت نشد"
|
||||
|
||||
1. بررسی کنید کاربر در Laravel وجود دارد (sync شده)
|
||||
2. توکنهای قدیمی را پاک کنید:
|
||||
```sql
|
||||
DELETE FROM wp_usermeta WHERE meta_key LIKE 'ifnex_laravel%';
|
||||
```
|
||||
3. دوباره لاگین کنید
|
||||
|
||||
### مشکل: SSL certificate error
|
||||
|
||||
```bash
|
||||
certbot renew --dry-run
|
||||
certbot renew
|
||||
```
|
||||
|
||||
### مشکل: خطای CORS
|
||||
|
||||
در `config/cors.php` لاراول:
|
||||
```php
|
||||
'paths' => ['api/*', 'sanctum/csrf-cookie'],
|
||||
'allowed_origins' => ['https://ifnex.com', 'https://www.ifnex.com'],
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📞 پشتیبانی
|
||||
|
||||
در صورت بروز مشکل:
|
||||
- ایمیل: dev@ifnex.com
|
||||
- مستندات Laravel: https://laravel.com/docs
|
||||
- مستندات WordPress: https://wordpress.org/documentation/
|
||||
|
||||
---
|
||||
|
||||
**پایان راهنمای دپلوی**
|
||||
🎉 موفق باشید!
|
||||
© 2026 VernaSoft Group. Internal use only.
|
||||
|
||||
571
README.md
571
README.md
@ -1,381 +1,246 @@
|
||||
# 🚀 IFNEX Logistics Management System
|
||||
> جایگزینی فرآیندهای دستی مبتنی بر اکسل با یک معماری Headless مدرن
|
||||
<div align="center">
|
||||
|
||||
| مورد | توضیحات |
|
||||
| :--- | :--- |
|
||||
| **ویرایش سند** | v4.2 (Laravel 11 + Filament 3.3 + فاز ۰ کامل + فاز ۱ کامل + فاز ۲ کامل + فاز ۳ کامل) |
|
||||
| **تاریخ آخرین بهروزرسانی** | 2026-08-10 |
|
||||
| **توسعهدهنده** | VernaSoft Group — Kazem Alghasi |
|
||||
| **مشتری** | شرکت حمل و نقل بینالمللی ایفنکس (IFNEX) — اصفهان |
|
||||
# 🚀 IFNEX Logistics Management System
|
||||
|
||||
### پلتفرم جامع مدیریت لجستیک بینالمللی
|
||||
|
||||
[](https://laravel.com)
|
||||
[](https://php.net)
|
||||
[](https://filamentphp.com)
|
||||
[](https://wordpress.org)
|
||||
[](https://mysql.com)
|
||||
[]()
|
||||
[]()
|
||||
|
||||
---
|
||||
|
||||
*جایگزینی فرآیندهای دستی مبتنی بر اکسل با معماری Headless مدرن*
|
||||
|
||||
**[📚 مستندات](#-مستندات)** • **[⚡ شروع سریع](#-شروع-سریع)** • **[🏗️ معماری](#%EF%B8%8F-معماری-سیستم)** • **[📞 پشتیبانی](#-تماس)**
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
## 📖 درباره پروژه
|
||||
|
||||
سیستم مدیریت لجستیک ایفنکس (IFNEX) یک راهحل جامع برای جایگزینی فرآیندهای مبتنی بر فایلهای اکسل در شرکتهای حمل و نقل بینالمللی است. این سیستم با استفاده از معماری **Headless**، وردپرس را برای ظاهر سایت و سئو، و لاراول را بهعنوان قلب تپنده و موتور محاسباتی به کار میگیرد.
|
||||
**IFNEX** یک راهحل جامع برای شرکتهای حملونقل بینالمللی است که فرآیندهای مبتنی بر فایلهای اکسل را با یک سیستم Headless مدرن جایگزین میکند.
|
||||
|
||||
### چرا این پروژه متفاوت است؟
|
||||
این سیستم شامل:
|
||||
|
||||
بهجای آنکه اپراتورها وزن حجمی را محاسبه کنند، زونها را در ۴ شیت مختلف جستجو کنند و با ماشینحساب قیمت نهایی را حساب کنند، اکنون تمام این فرآیند در کسر از ثانیه و بدون هیچ خطای انسانی انجام میشود. همچنین، به دلیل تحریمهای بینالمللی و مسدود بودن دسترسی مستقیم به API شرکتهای DHL/FedEx/UPS از ایران، این سیستم از طریق یک سرور VPS پل (در فاز ۳) مشکل ترکینگ خودکار را حل میکند.
|
||||
- **موتور قیمتگذاری هوشمند** با ۴ زون و ۳ نوع سرویس
|
||||
- **ثبت سفارش آنلاین** چند بستهای با محاسبه لحظهای قیمت
|
||||
- **تولید خودکار اسناد** (AWB, Invoice, Label) با بارکد استاندارد
|
||||
- **پورتال مشتری کامل** با کیف پول، پرداخت آنلاین و اعلانها
|
||||
- **پنل مدیریت قدرتمند** با Filament 3.3
|
||||
- **سیستم ترکینگ** با قابلیت مهاجرت دادههای تاریخی
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ معماری سیستم
|
||||
|
||||
سیستم بر اساس الگوی Headless توسعه یافته است. فرانتاند (وردپرس) و بکاند (لاراول) کاملاً از هم جدا شدهاند و فقط از طریق REST API با هم ارتباط دارند.
|
||||
این پروژه بر اساس الگوی **Headless** طراحی شده است — فرانتاند (WordPress) و بکاند (Laravel) کاملاً جدا و فقط از طریق REST API با هم ارتباط دارند.
|
||||
|
||||
┌─────────────────┐ REST API ┌─────────────────┐
|
||||
│ WordPress │ ←─────────────────────→ │ Laravel 11 │
|
||||
│ (Frontend) │ پلاگین IFNEX Bridge │ (Backend) │
|
||||
│ │ │ + Filament │
|
||||
└─────────────────┘ └────────┬────────┘
|
||||
```
|
||||
┌──────────────────────────────────────────────────────┐
|
||||
│ CLIENT BROWSER │
|
||||
└────────────────────────┬─────────────────────────────┘
|
||||
│
|
||||
┌────────┴────────┐
|
||||
│ MySQL 8 │
|
||||
└─────────────────┘
|
||||
│
|
||||
(فاز ۳) │
|
||||
┌────────┴────────┐
|
||||
│ VPS پل خارج │
|
||||
│ (هلند/آلمان) │
|
||||
└────────┬────────┘
|
||||
│
|
||||
┌────────┴────────┐
|
||||
│ TrackingMore / │
|
||||
│ 17track API │
|
||||
└─────────────────┘
|
||||
|
||||
|
||||
| لایه | تکنولوژی | نقش |
|
||||
| :--- | :--- | :--- |
|
||||
| **فرانتاند** | WordPress 7.0.3 + پوسته سفارشی IFNEX + Polylang | مدیریت ظاهر، چندزبانه، پورتال مشتری، لندینگ پیجها |
|
||||
| **بکاند** | Laravel 11 + Filament 3.3 | API سرور، پنل ادمین، موتور قیمتگذاری، صدور PDF، کیف پول، پرداخت آنلاین |
|
||||
| **پل ارتباطی** | پلاگین اختصاصی IFNEX Bridge | ارسال درخواستهای کاربر از وردپرس به لاراول، مدیریت توکن Sanctum |
|
||||
| **دیتابیس** | MySQL 8 | ذخیرهسازی دادهها با پشتیبانی از JSON columns |
|
||||
| **زیرساخت رهگیری** | VPS خارج از کشور (در فاز ۴) | واسط برای دسترسی به APIهای رهگیری بینالمللی |
|
||||
|
||||
---
|
||||
|
||||
## 🗺️ نقشه راه ۴ فازی
|
||||
|
||||
این پروژه به چهار فاز تقسیم شده تا هم تحویل تدریجی ارزش به مشتری حفظ شود و هم ریسک دوبارهکاری حذف گردد.
|
||||
|
||||
| فاز | هدف اصلی | مدت زمان | وضعیت |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| **فاز ۰** | بنیان داده + وبسایت + ترکینگ دستی + مهاجرت دادههای تاریخی | ۴ هفته | ✅ کامل |
|
||||
| **فاز ۱** | موتور قیمتگذاری کامل + ثبت سفارش آنلاین + تولید PDFها + استعلام قیمت | ۴-۶ هفته | ✅ کامل |
|
||||
| **فاز ۲** | حساب کاربری مشتری + کیف پول + پرداخت آنلاین + تخفیف حجمی + پنل مالی | ۴ هفته | ✅ کامل |
|
||||
| **فاز ۳** | پورتال مشتری کامل + پلاگین وردپرس + سینک کاربران + پرداخت سفارش | ۶ هفته | ✅ کامل |
|
||||
|
||||
> 💡 جزئیات کامل هر فاز، اسکیمای دیتابیس، جدول زمانی و معیارهای پذیرش در سند `01_Documents/Phase0_Proposal.md` آمده است.
|
||||
|
||||
---
|
||||
|
||||
## ✨ ویژگیهای کلیدی
|
||||
|
||||
### فاز ۰ (تکمیل شده) ✅
|
||||
|
||||
1. **اسکیمای دیتابیس اصلاحشده** (بر اساس فایل اکسل عملیاتی)
|
||||
- جدول `countries` با ۴ زون مجزا (صادرات/واردات × پارسل/داکیومنت)
|
||||
- پشتیبانی از ۳ نوع سرویس: `DOC_NORMAL`, `DOC_ECONOMY`, `PARCEL`
|
||||
- جدول `shipment_carrier_mappings` برای نگاشت چند شرکت حمل به هر بارنامه
|
||||
- جدول `shipment_tracking_events` برای ذخیره تایملاین کامل رویدادهای هر مرسوله
|
||||
- جدول `system_settings` برای ذخیره تنظیمات سیستم (VAT، نرخ ارز، ضریب سود)
|
||||
- جدول `shipment_items` برای اقلام گمرکی (۹ ردیف)
|
||||
|
||||
2. **پنل مدیریت اختصاصی (Laravel Filament)**
|
||||
- مدیریت ۲۳۳ کشور با زونهای صادرات و واردات
|
||||
- فرم تنظیمات سیستم: تغییر سریع ارزها و ضریب سود بدون دستکاری کد
|
||||
- UX تخصصی اپراتور ترکینگ: افزودن رویداد در چند ثانیه با فیلدهای از پیش پر شده
|
||||
- **تببندی ویجتهای داشبورد:** اطلاعات کلی، نرخ ارز، آمار کیف پول
|
||||
- **رابط کاربری سفارشی:** رنگ Navy gradient، فونت Vazirmatn، RTL کامل
|
||||
|
||||
3. **ارتباطات API و فرانتاند**
|
||||
- **API ترکینگ:** `GET /api/track/{awb_no}` با API Key + Rate Limiting + CORS
|
||||
- **API استعلام قیمت:** `POST /api/v1/calculate`
|
||||
- **API احراز هویت:** `POST /api/v1/auth/login` + `POST /api/v1/auth/logout` (Sanctum)
|
||||
- **API سفارشات مشتری:** ۶ endpoint برای پروفایل، سفارشات، پرداخت و لغو
|
||||
- **API کیف پول:** موجودی، تراکنشها، تنظیمات ادمین
|
||||
- **API تخفیف:** لیست و اعتبارسنجی کدهای تخفیف
|
||||
- **پلاگین IFNEX Bridge:** شورتکدهای `[ifnex_tracking_form]`، `[ifnex_tracking_status]`، `[ifnex_wallet_balance]`، `[ifnex_transactions]`
|
||||
- **امنیت:** API Key + Rate Limiting + CORS whitelist + Form Request Validation + Sanctum
|
||||
|
||||
4. **مهاجرت دادههای تاریخی**
|
||||
- انتقال ۳۹۵۰ رکورد تاریخی از فایل اکسل به دیتابیس جدید
|
||||
- اعتبارسنجی و پاکسازی خودکار دادهها
|
||||
- import ۴۰۴ رکورد تعرفههای حمل
|
||||
- import ۹۸ رویداد ترکینگ دستی
|
||||
|
||||
### فاز ۱ (تکمیل شده) ✅
|
||||
|
||||
1. **موتور قیمتگذاری کامل (`PriceCalculatorService`)**
|
||||
- محاسبه خودکار قیمت بر اساس وزن، زون، نوع سرویس و جهت ارسال
|
||||
- پشتیبانی از ۴ زون مجزا (export/import × doc/parcel)
|
||||
- اعمال ضریب سود، VAT و هزینههای اضافی
|
||||
- **تستهای کامل:** Feature tests و Service tests با پوشش ۱۰۰٪
|
||||
|
||||
2. **فرم ثبت سفارش آنلاین**
|
||||
- فرم عمومی برای مشتریان با ۹ ردیف کالای گمرکی
|
||||
- اعتبارسنجی خودکار و محاسبه لحظهای قیمت
|
||||
- تولید AWB number خودکار با فرمت `IFN-YYYY-XXXXX`
|
||||
|
||||
3. **تولید PDFهای حرفهای**
|
||||
- **AWB:** بارنامه هوایی با لوگوی IFNEX
|
||||
- **INVOICE:** فاکتور تجاری با جدول ۹ ردیف کالای گمرکی
|
||||
- **LABEL:** لیبل چاپی برای بستهها (پرینتر لیزری + کاغذ چسبان A4)
|
||||
- تطبیق اولیه با قالبهای اکسل + لوگوی استخراجشده
|
||||
|
||||
4. **صفحه استعلام قیمت واقعی**
|
||||
- رابط کاربری عمومی برای محاسبه قیمت تقریبی حمل
|
||||
- نمایش قیمت پایه (درهم) و قیمت نهایی (ریال)
|
||||
|
||||
5. **ماژول ایمپورت اکسل تعرفهها**
|
||||
- کامند `php artisan ifnex:import:rates` با قابلیتهای `--clear` و `--dry-run`
|
||||
- پشتیبانی از شیتهای Export Rate، Import Rate و DocEco
|
||||
- تبدیل خودکار واحد قیمت (ریال → درهم) برای شیتهای DocNor/DocEco
|
||||
|
||||
### فاز ۲ (تکمیل شده) ✅
|
||||
|
||||
1. **سیستم کیف پول (Wallet)**
|
||||
- API شارژ اعتبار (دستی و خودکار)
|
||||
- API بررسی موجودی
|
||||
- API تاریخچه تراکنشها
|
||||
- **اتصال درگاه پرداخت زرینپال** با Mock Gateway برای تست
|
||||
- پرداخت آنلاین کامل با بازگشت به فرانتاند
|
||||
|
||||
2. **سیستم تخفیف (Discount Codes)**
|
||||
- API لیست کدهای تخفیف فعال
|
||||
- API اعتبارسنجی کد تخفیف
|
||||
- پشتیبانی از تخفیف درصدی و ثابت
|
||||
- **DiscountCodeResource** در Filament با form/table/filters کامل
|
||||
|
||||
3. **بهروزرسانی خودکار نرخ ارز**
|
||||
- Artisan Command برای بهروزرسانی روزانه
|
||||
- پشتیبانی از ECB و FreeCurrencyAPI
|
||||
- **ردیابی تاریخچه نرخ ارز** با `ExchangeRateHistory` و `ExchangeRateHistoryResource`
|
||||
|
||||
4. **پنل مالی در Filament**
|
||||
- **FinanceOverviewWidget** — خلاصه مالی
|
||||
- **TransactionChartWidget** — نمودار تراکنشها
|
||||
- **RecentTransactionsWidget** — آخرین تراکنشها
|
||||
- **PaymentResource** — مشاهده تراکنشهای درگاه
|
||||
- **WalletTransactionResource** — CRUD کامل تراکنشهای کیف پول
|
||||
- خروجی CSV برای تراکنشها و مرسولات
|
||||
|
||||
5. **کنترل دسترسی مبتنی بر نقش (RBAC)**
|
||||
- یکپارچگی با `spatie/laravel-permission`
|
||||
- **RoleResource** و **UserResource** در Filament
|
||||
- **RoleAndPermissionSeeder** برای تنظیم اولیه
|
||||
|
||||
6. **یکپارچگی وردپرس ↔ لاراول**
|
||||
- دستور Artisan `ifnex:sync-wp-users` برای سینک کاربران
|
||||
- پلاگین IFNEX Bridge گسترش یافته:
|
||||
- شورتکد `[ifnex_wallet_balance]` برای موجودی کیف پول
|
||||
- شورتکد `[ifnex_transactions]` برای لیست تراکنشها
|
||||
- AJAX handlers برای موجودی و تراکنشها
|
||||
|
||||
### فاز ۳ (تکمیل شده) ✅
|
||||
|
||||
1. **سیستم ثبت سفارش مشتری (Customer Ordering)**
|
||||
- **CustomerOrderController** با ۶ endpoint:
|
||||
- `GET /api/v1/customer/profile` — پروفایل و آمار کاربر
|
||||
- `GET /api/v1/customer/countries` — لیست کشورها
|
||||
- `GET /api/v1/customer/orders` — لیست سفارشات
|
||||
- `POST /api/v1/customer/orders` — ثبت سفارش جدید
|
||||
- `GET /api/v1/customer/orders/{shipment}` — جزئیات سفارش
|
||||
- `POST /api/v1/customer/orders/{shipment}/cancel` — لغو سفارش
|
||||
- تولید خودکار شماره AWB با فرمت `IFN-YYYY-XXXXX`
|
||||
- وضعیتهای جدید: `pending_payment` و `cancelled`
|
||||
- اعتبارسنجی کامل و محاسبه لحظهای قیمت
|
||||
|
||||
2. **سیستم پرداخت سفارش (Order Payment)**
|
||||
- **OrderPaymentService** برای مدیریت پرداختها
|
||||
- پرداخت از کیف پول: `POST /api/v1/customer/orders/{shipment}/pay-wallet`
|
||||
- پرداخت از درگاه: `POST /api/v1/customer/orders/{shipment}/pay-gateway`
|
||||
- تکمیل خودکار پرداخت بعد از callback درگاه
|
||||
- ثبت رویداد ترکینگ پس از پرداخت موفق
|
||||
|
||||
3. **احراز هویت مشتری (Customer Auth)**
|
||||
- **AuthController** با login/logout برای Sanctum
|
||||
- **BridgeAuthController** برای لاگین مستقیم از وردپرس
|
||||
- توکنهای Sanctum با انقضا ۳۰ روزه
|
||||
|
||||
4. **پورتال مشتری در وردپرس**
|
||||
- **شورتکد `[ifnex_order_form]`** — فرم ثبت سفارش چندمرحلهای (۴ مرحله)
|
||||
- **شورتکد `[ifnex_orders_list]`** — لیست سفارشات با فیلتر وضعیت
|
||||
- **شورتکد `[ifnex_order_payment]`** — صفحه پرداخت سفارش (کیف پول + درگاه)
|
||||
- **شورتکد `[ifnex_order_detail]`** — جزئیات سفارش با timeline رهگیری
|
||||
- **شورتکد `[ifnex_user_profile]`** — پروفایل کاربر با آمار کیف پول
|
||||
- استایلهای CSS کامل برای تمام کامپوننتها (`ifnex-orders.css`)
|
||||
- JavaScript برای ناوبری مراحل و AJAX (`ifnex-order-form.js`)
|
||||
|
||||
5. **پوسته وردپرس سفارشی IFNEX**
|
||||
- پشتیبانی چندزبانه با Polylang
|
||||
- مدیریت LTR/RTL خودکار
|
||||
- Customizer برای لوگو و زبان
|
||||
- قالبهای archive, single, front-page
|
||||
- ساختار تمیک شرکتی با لوگو IFNEX
|
||||
|
||||
6. **سیستم طراحی یکپارچه (Design System)**
|
||||
- **DESIGN_SYSTEM.md** — مرجع کامل رنگها، فونتها، فاصلهگذاری
|
||||
- رنگهای برند: Primary Amber `#f59e0b`، Sidebar Dark Navy `#1a1a2e → #16213e`
|
||||
- فونت Vazirmatn برای کل پنل ادمین و فرانتاند
|
||||
- استایلهای یکپارچه برای Filament و پلاگین وردپرس
|
||||
|
||||
7. **گزارشگیری مالی در Filament**
|
||||
- صفحه **FinancialReport** با خلاصه تراکنشها و مرسولات
|
||||
- خروجی Excel برای ShipmentResource و WalletTransactionResource
|
||||
- ویجتهایdashboard اطلاعاتی
|
||||
┌────────────────────────▼─────────────────────────────┐
|
||||
│ WORDPRESS (Frontend) │
|
||||
│ ┌───────────────────┐ ┌──────────────────────────┐ │
|
||||
│ │ IFNEX Theme │ │ IFNEX Bridge Plugin │ │
|
||||
│ │ (Landing Page) │ │ (REST Client) │ │
|
||||
│ └───────────────────┘ └────────────┬─────────────┘ │
|
||||
└───────────────────────────────────┼───────────────────┘
|
||||
│ REST API (Sanctum)
|
||||
┌───────────────────────────────────▼───────────────────┐
|
||||
│ LARAVEL 11 (Backend) │
|
||||
│ ┌─────────────────┐ ┌──────────────┐ ┌────────────┐ │
|
||||
│ │ Filament │ │ API │ │ Services │ │
|
||||
│ │ Admin Panel │ │ Controllers │ │ (Pricing, │ │
|
||||
│ │ │ │ │ │ PDF, │ │
|
||||
│ └─────────────────┘ └──────┬───────┘ │ Payment) │ │
|
||||
└──────────────────────────┼────┼─────────┘────────────┘ │
|
||||
│ │ │
|
||||
┌──────▼────▼────┐ │
|
||||
│ MySQL 8 │ │
|
||||
│ Database │ │
|
||||
└───────────────┘ │
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📁 ساختار پروژه
|
||||
|
||||
```text
|
||||
```
|
||||
IFNEX-Logistics/
|
||||
├── 01_Documents/ # مستندات فنی پروژه
|
||||
│ ├── STATUS.md # ⭐ وضعیت فعلی و گزارش پیشرفت
|
||||
│ ├── IFNEX_Phase0_Checklist.md # ⭐ چکلیست دقیق فاز ۰
|
||||
│ ├── Phase0_Proposal.md # ⭐ سند پیشنهاد فاز ۰ (نقشه راه جدید)
|
||||
│ ├── EXCEL_ANALYSIS.md # ⭐ تحلیل فایلهای اکسل
|
||||
│ ├── PRD_v2.md # سند نیازمندیها (نسخه قدیمی — بایگانی شده)
|
||||
│ └── Project_Roadmap.md # نقشه راه (نسخه قدیمی — بایگانی شده)
|
||||
├── 📄 01_Documents/ # مستندات فنی پروژه
|
||||
│ ├── IFNEX_File_Map.md # نقشه کامل فایلها
|
||||
│ ├── IFNEX_Roadmap.md # نقشه راه پروژه
|
||||
│ ├── IFNEX_Phase0_Checklist.md
|
||||
│ ├── IFNEX_DEPRECATED_FILES_NOTICE.md
|
||||
│ └── EXCEL_ANALYSIS.md # تحلیل دادههای تاریخی
|
||||
│
|
||||
├── 02_Design/ # فایلهای UI/UX و فیگما
|
||||
│ └── Assets/ # لوگوها، آیکونها
|
||||
├── 🌐 03_WordPress/ # فرانتاند (WordPress)
|
||||
│ └── wp-content/
|
||||
│ ├── themes/ifnex/ # قالب سفارشی IFNEX
|
||||
│ └── plugins/
|
||||
│ └── ifnex-bridge/ # پلاگین ارتباط با لاراول
|
||||
│
|
||||
├── 03_WordPress/ # سیستم مدیریت محتوا (فرانتاند)
|
||||
│ ├── wp-content/
|
||||
│ │ ├── themes/ifnex/ # پوسته سفامشی IFNEX (چندزبانه، RTL/LTR)
|
||||
│ │ └── plugins/
|
||||
│ │ └── ifnex-bridge/ # پلاگین اختصاصی ارتباط با لاراول
|
||||
│ │ ├── ifnex-bridge.php
|
||||
│ │ ├── includes/
|
||||
│ │ │ ├── api-client.php
|
||||
│ │ │ ├── shortcodes.php
|
||||
│ │ │ ├── tracking-form.php
|
||||
│ │ │ └── user-bridge.php
|
||||
│ │ └── assets/
|
||||
│ │ ├── css/
|
||||
│ │ │ ├── ifnex-bridge.css
|
||||
│ │ │ └── ifnex-orders.css
|
||||
│ │ └── js/
|
||||
│ │ └── ifnex-order-form.js
|
||||
│
|
||||
├── 04_Laravel/ # هسته مرکزی سیستم (بکاند)
|
||||
│ ├── README.md # راهنمای نصب و استفاده از لاراول
|
||||
├── ⚙️ 04_Laravel/ # بکاند (Laravel 11)
|
||||
│ ├── app/
|
||||
│ │ ├── Models/
|
||||
│ │ │ ├── Country.php
|
||||
│ │ │ ├── Shipment.php
|
||||
│ │ │ ├── ShipmentItem.php
|
||||
│ │ │ ├── ShippingRate.php
|
||||
│ │ │ ├── ShipmentCarrierMapping.php
|
||||
│ │ │ ├── ShipmentTrackingEvent.php
|
||||
│ │ │ ├── SystemSetting.php
|
||||
│ │ │ ├── Wallet.php
|
||||
│ │ │ ├── WalletTransaction.php
|
||||
│ │ │ ├── DiscountCode.php
|
||||
│ │ │ ├── ExchangeRateHistory.php
|
||||
│ │ │ ├── Role.php # spatie/laravel-permission
|
||||
│ │ │ └── User.php
|
||||
│ │ ├── Enums/
|
||||
│ │ │ ├── ShipmentDirection.php
|
||||
│ │ │ ├── ShipmentType.php
|
||||
│ │ │ ├── ShipmentStatus.php # ۹ وضعیت (pending_payment, cancelled اضافه شد)
|
||||
│ │ │ ├── CarrierCode.php
|
||||
│ │ │ ├── TrackingSource.php # ۵ منبع (manual, api, import, system, customer)
|
||||
│ │ │ ├── TransactionType.php
|
||||
│ │ │ ├── TransactionStatus.php
|
||||
│ │ │ ├── PaymentGateway.php # ۴ درگاه (zarinpal, wallet, manual, system)
|
||||
│ │ │ └── UserRole.php
|
||||
│ │ ├── Services/
|
||||
│ │ │ ├── PriceCalculatorService.php
|
||||
│ │ │ ├── TrackingService.php
|
||||
│ │ │ ├── ExchangeRateService.php # ردیابی و مدیریت نرخ ارز
|
||||
│ │ │ ├── ZarinpalService.php # اتصال به درگاه زرینپال
|
||||
│ │ │ ├── MockZarinpalService.php # شبیهسازی درگاه برای تست
|
||||
│ │ │ └── OrderPaymentService.php # پرداخت سفارشات (کیف پول + درگاه)
|
||||
│ │ ├── Http/
|
||||
│ │ │ ├── Controllers/
|
||||
│ │ │ │ ├── Api/
|
||||
│ │ │ │ │ ├── TrackController.php
|
||||
│ │ │ │ │ ├── PricingController.php
|
||||
│ │ │ │ │ ├── AuthController.php # ورود/خروج Sanctum
|
||||
│ │ │ │ │ ├── BridgeAuthController.php # لاگین از پلاگین وردپرس
|
||||
│ │ │ │ │ ├── WalletController.php
|
||||
│ │ │ │ │ ├── PaymentController.php
|
||||
│ │ │ │ │ ├── DiscountCodeController.php
|
||||
│ │ │ │ │ └── Customer/
|
||||
│ │ │ │ │ └── CustomerOrderController.php # ۶ endpoint سفارش مشتری
|
||||
│ │ │ │ ├── OrderController.php
|
||||
│ │ │ │ ├── PricingPageController.php
|
||||
│ │ │ │ └── ShipmentPdfController.php
|
||||
│ │ │ ├── Middleware/
|
||||
│ │ │ │ └── ApiKeyMiddleware.php
|
||||
│ │ │ └── Requests/
|
||||
│ │ ├── Imports/
|
||||
│ │ │ ├── ShippingRatesImport.php
|
||||
│ │ │ ├── HistoricalShipmentsImport.php
|
||||
│ │ │ └── RateSheetImport.php
|
||||
│ │ ├── Console/
|
||||
│ │ │ └── Commands/
|
||||
│ │ │ │ ├── ImportShippingRates.php
|
||||
│ │ │ │ │ ├── ImportHistoricalData.php
|
||||
│ │ │ │ │ ├── UpdateExchangeRates.php
|
||||
│ │ │ │ │ ├── SyncWordPressUsers.php # سینک کاربران وردپرس
|
||||
│ │ │ │ │ └── DebugImportCommand.php
|
||||
│ │ ├── Filament/
|
||||
│ │ │ ├── Resources/
|
||||
│ │ │ │ ├── CountryResource.php
|
||||
│ │ │ │ ├── ShipmentResource.php
|
||||
│ │ │ │ ├── ShippingRateResource.php
|
||||
│ │ │ │ ├── ShipmentItemResource.php
|
||||
│ │ │ │ ├── WalletResource.php
|
||||
│ │ │ │ ├── WalletTransactionResource.php # CRUD کامل با صفحات Create/Edit
|
||||
│ │ │ │ ├── PaymentResource.php # مشاهده تراکنشهای درگاه
|
||||
│ │ │ │ ├── DiscountCodeResource.php # مدیریت کدهای تخفیف
|
||||
│ │ │ │ ├── ExchangeRateHistoryResource.php # تاریخچه نرخ ارز
|
||||
│ │ │ │ ├── RoleResource.php # مدیریت نقشها (spatie)
|
||||
│ │ │ │ └── UserResource.php # مدیریت کاربران (spatie)
|
||||
│ │ │ ├── Widgets/
|
||||
│ │ │ │ ├── DashboardInfoWidget.php # اطلاعات کلی داشبورد
|
||||
│ │ │ │ ├── ExchangeRateWidget.php # نرخ ارز زنده
|
||||
│ │ │ │ ├── WalletStats.php # آمار کیف پول
|
||||
│ │ │ │ ├── TransactionChartWidget.php # نمودار تراکنشها
|
||||
│ │ │ │ └── RecentTransactionsWidget.php
|
||||
│ │ │ └── Pages/
|
||||
│ │ │ │ ├── IfnexSettingsPage.php
|
||||
│ │ │ │ ├── PriceTestPage.php
|
||||
│ │ │ │ └── Reports/
|
||||
│ │ │ │ └── FinancialReport.php # گزارش مالی
|
||||
│ │ └── Providers/
|
||||
│ │ ├── AppServiceProvider.php
|
||||
│ │ └── Filament/
|
||||
│ │ └── AdminPanelProvider.php # پیکربندی کامل (رنگ، فونت، نوتیفیکیشن)
|
||||
│ │ ├── Filament/ # پنل مدیریت
|
||||
│ │ ├── Http/Controllers/ # کنترلرها (API, Web)
|
||||
│ │ ├── Models/ # مدلهای Eloquent
|
||||
│ │ ├── Services/ # لایه سرویس
|
||||
│ │ └── Imports/ # Excel imports
|
||||
│ ├── database/migrations/ # ۱۵+ migration
|
||||
│ ├── resources/views/
|
||||
│ │ ├── pdfs/ # قالبهای PDF
|
||||
│ │ └── filament/ # Blade views
|
||||
│ └── routes/
|
||||
│ ├── api.php # REST API endpoints
|
||||
│ └── web.php # Public routes
|
||||
│
|
||||
└── README.md # این فایل — نمای کلی پروژه
|
||||
├── 📋 README.md # این فایل
|
||||
├── 📋 DEPLOYMENT.md # راهنمای استقرار
|
||||
└── 📋 04_Laravel/README.md # راهنمای بکاند
|
||||
```
|
||||
|
||||
💡 برای جزئیات فنی، نصب و راهاندازی، فایل 04_Laravel/README.md را مطالعه کنید.
|
||||
---
|
||||
|
||||
## ✨ ویژگیهای کلیدی
|
||||
|
||||
### فاز ۰ — بنیان سیستم ✅
|
||||
- اسکیمای دیتابیس مدرن با ۴ زون مجزا (Export/Import × Parcel/Doc)
|
||||
- مهاجرت ۳۹۵۰ رکورد تاریخی از اکسل به دیتابیس
|
||||
- پنل مدیریت Filament با UX تخصصی اپراتور
|
||||
- API ترکینگ با امنیت API Key + Rate Limiting
|
||||
- پلاگین WordPress Bridge برای ارتباط با فرانتاند
|
||||
|
||||
### فاز ۱ — پورتال مشتری ✅
|
||||
- احراز هویت Laravel Sanctum + Bridge Auth
|
||||
- فرم ثبت سفارش چندمرحلهای با Wizard
|
||||
- داشبورد جامع مشتری (سفارشات، کیف پول، تراکنشها، اعلانها، رهگیری، پروفایل)
|
||||
- سیستم ترکینگ با تایملاین
|
||||
|
||||
### فاز ۲ — مالی و کیف پول ✅
|
||||
- سیستم کیف پول کامل با تراکنشها
|
||||
- درگاه پرداخت + Mock Gateway برای تست
|
||||
- مدیریت ارزهای چندگانه (IRR, AED, USD, EUR)
|
||||
- کدهای تخفیف با اعتبارسنجی و محدودیت مصرف
|
||||
- تولید PDF حرفهای (AWB, Invoice, Label) با بارکد
|
||||
|
||||
### فاز ۳ — بهبود و یکپارچهسازی 🔄
|
||||
- ایمپورت/اکسپورت نرخها با دانلود Template
|
||||
- سیستم اعلانهای دیتابیس (ادمین + مشتری)
|
||||
- پشتیبانی از چند بسته در یک سفارش (Multi-Package)
|
||||
- تاریخچه تغییرات وضعیت
|
||||
- استایل مدرن تراکنشها و هشدار آدرس انگلیسی
|
||||
|
||||
|
||||
---
|
||||
|
||||
## ⚡ شروع سریع
|
||||
|
||||
### پیشنیازها
|
||||
- PHP 8.2+
|
||||
- Composer 2.x
|
||||
- MySQL 8+
|
||||
- WordPress 7.0+
|
||||
|
||||
### نصب
|
||||
|
||||
```bash
|
||||
# ۱. کلون مخزن
|
||||
git clone https://www.git.vernahost.ir/gitmodir110/ifnex.git
|
||||
cd ifnex/04_Laravel
|
||||
|
||||
# ۲. نصب وابستگیها
|
||||
composer install
|
||||
|
||||
# ۳. تنظیم فایل محیط
|
||||
cp .env.example .env
|
||||
php artisan key:generate
|
||||
|
||||
# ۴. ایجاد دیتابیس
|
||||
mysql -u root -p -e "CREATE DATABASE ifnex_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
|
||||
# ۵. ویرایش .env و تنظیم DB_DATABASE, DB_USERNAME, DB_PASSWORD
|
||||
# ۶. اجرای migrations و seeders
|
||||
php artisan migrate --force
|
||||
php artisan db:seed --force
|
||||
# ۷. اجرای سرور
|
||||
php artisan serve
|
||||
```
|
||||
|
||||
> 📖 برای راهنمای کامل استقرار، [DEPLOYMENT.md](DEPLOYMENT.md) را ببینید.
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ Stack فنی
|
||||
|
||||
### Backend (Laravel)
|
||||
|
||||
| تکنولوژی | نسخه | کاربرد |
|
||||
|-----------|------|--------|
|
||||
| Laravel | 11.x | فریمورک اصلی |
|
||||
| PHP | 8.2+ | زبان برنامهنویسی |
|
||||
| Filament | 3.3.x | پنل مدیریت ادمین |
|
||||
| MySQL | 8+ | دیتابیس |
|
||||
| Dompdf | Latest | تولید PDF |
|
||||
| Laravel Excel | Latest | Import/Export |
|
||||
| Sanctum | Latest | API Authentication |
|
||||
| Morilog Jalali | 3.x | تاریخ شمسی |
|
||||
|
||||
### Frontend (WordPress)
|
||||
|
||||
| تکنولوژی | نسخه | کاربرد |
|
||||
|-----------|------|--------|
|
||||
| WordPress | 7.0.3 | CMS |
|
||||
| IFNEX Theme | Custom | قالب سفارشی |
|
||||
| IFNEX Bridge | 1.6.0 | پلاگین ارتباطی |
|
||||
|
||||
---
|
||||
|
||||
## 📚 مستندات
|
||||
|
||||
برای مطالعه دقیق منطقهای سیستم:
|
||||
|
||||
| فایل | محتوا | اولویت |
|
||||
|------|-------|--------|
|
||||
| IFNEX_Phase0_Checklist.md | چکلیست کامل فازها | ⭐⭐⭐ |
|
||||
| IFNEX_Roadmap.md | نقشه راه آینده | ⭐⭐⭐ |
|
||||
| IFNEX_File_Map.md | نقشه ۱۰۰+ فایل پروژه | ⭐⭐⭐ |
|
||||
| DEPLOYMENT.md | راهنمای استقرار Production | ⭐⭐ |
|
||||
| EXCEL_ANALYSIS.md | تحلیل دادههای اکسل | ⭐⭐ |
|
||||
|
||||
---
|
||||
|
||||
## 🚀 مراحل بعدی
|
||||
|
||||
- اتصال به API های ترکینگ زنده (TrackingMore/17track)
|
||||
- پلاگین SMS برای اطلاعرسانی
|
||||
- مستندات API (OpenAPI/Swagger)
|
||||
- راهنمای اپراتور (Operator Manual)
|
||||
- تستهای واحد و Integration
|
||||
|
||||
---
|
||||
|
||||
## 📞 تماس
|
||||
|
||||
- **توسعهدهنده:** Kazem Alghasi
|
||||
- **شرکت:** VernaSoft Group
|
||||
- **ایمیل:** kazem@vernasoft.group
|
||||
- **مخزن:** git.vernahost.ir/gitmodir110/ifnex
|
||||
|
||||
---
|
||||
|
||||
<div align="center">
|
||||
|
||||
📚 مستندات بیشتر
|
||||
برای مطالعه دقیق منطقهای سیستم، حتماً فایلهای داخل پوشه 01_Documents را مطالعه کنید:
|
||||
فایل
|
||||
محتوا
|
||||
STATUS.md
|
||||
⭐ وضعیت فعلی، گزارش پیشرفت، خط قرمزها و راهنماییهای توسعه بعدی
|
||||
IFNEX_Phase0_Checklist.md
|
||||
⭐ چکلیست دقیق تمام کارهای فاز ۰ با وضعیت هر آیتم
|
||||
Phase0_Proposal.md
|
||||
⭐ سند پیشنهاد فاز ۰ — شامل اسکیمای دیتابیس، جدول زمانی، ریسکها، معیارهای پذیرش
|
||||
EXCEL_ANALYSIS.md
|
||||
⭐ تحلیل کامل فایلهای اکسل عملیاتی و ساختار دادههای تاریخی
|
||||
PRD_v2.md
|
||||
سند نیازمندیها (نسخه قدیمی — بایگانی شده، فقط برای مرجع تاریخی)
|
||||
Project_Roadmap.md
|
||||
نقشه راه قدیمی (۳ فازی — بایگانی شده، فقط برای مرجع تاریخی)
|
||||
🔐 امنیت و گزارش مشکلات
|
||||
اگر آسیبپذیری امنیتی کشف کردید، لطفاً مستقیماً به kazem@vernasoft.group (یا ایمیل جایگزین تعیینشده) اطلاع دهید و آن را در Issue عمومی مخزن قرار ندهید.
|
||||
📜 لایسنس
|
||||
© 2026 VernaSoft Group (Kazem Alghasi). All rights reserved.
|
||||
این پروژه اختصاصی شرکت IFNEX است و کپی یا استفادهی غیرمجاز از آن ممنوع است.
|
||||
|
||||
© 2026 VernaSoft Group. تمام حقوق محفوظ است.
|
||||
این پروژه اختصاصی شرکت IFNEX است و کپی یا استفاده غیرمجاز ممنوع میباشد.
|
||||
|
||||
</div>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user