diff --git a/04_Laravel/README.md b/04_Laravel/README.md index da80b65..5eb250e 100644 --- a/04_Laravel/README.md +++ b/04_Laravel/README.md @@ -1,73 +1,85 @@ +
+ +# ⚙️ IFNEX Laravel Backend + +### هسته مرکزی سیستم مدیریت لجستیک ایف‌نکس + +[![Laravel](https://img.shields.io/badge/Laravel-11.x-FF2D20?logo=laravel&logoColor=white)](https://laravel.com) +[![PHP](https://img.shields.io/badge/PHP-8.2+-777BB4?logo=php&logoColor=white)](https://php.net) +[![Filament](https://img.shields.io/badge/Filament-3.3-EDB200?logo=laravel&logoColor=white)](https://filamentphp.com) +[![MySQL](https://img.shields.io/badge/MySQL-8+-4479A1?logo=mysql&logoColor=white)](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 | +
--- -## 📋 فهرست مطالب +## 🎯 نمای کلی -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 - - -نوشتن تست جدید -برای نوشتن تست جدید، از این الگو استفاده کنید: - - '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. \ No newline at end of file +├── 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) | راهنمای استقرار | + +--- + +
+ +© 2026 VernaSoft Group. All Rights Reserved. + +
\ No newline at end of file diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md index cb09778..3ab125a 100644 --- a/DEPLOYMENT.md +++ b/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 - 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/ - ---- - -**پایان راهنمای دپلوی** -🎉 موفق باشید! \ No newline at end of file +© 2026 VernaSoft Group. Internal use only. diff --git a/README.md b/README.md index 8319317..40be5e3 100644 --- a/README.md +++ b/README.md @@ -1,381 +1,246 @@ -# 🚀 IFNEX Logistics Management System -> جایگزینی فرآیندهای دستی مبتنی بر اکسل با یک معماری Headless مدرن +
-| مورد | توضیحات | -| :--- | :--- | -| **ویرایش سند** | v4.2 (Laravel 11 + Filament 3.3 + فاز ۰ کامل + فاز ۱ کامل + فاز ۲ کامل + فاز ۳ کامل) | -| **تاریخ آخرین به‌روزرسانی** | 2026-08-10 | -| **توسعه‌دهنده** | VernaSoft Group — Kazem Alghasi | -| **مشتری** | شرکت حمل و نقل بین‌المللی ایف‌نکس (IFNEX) — اصفهان | +# 🚀 IFNEX Logistics Management System + +### پلتفرم جامع مدیریت لجستیک بین‌المللی + +[![Laravel](https://img.shields.io/badge/Laravel-11.x-FF2D20?logo=laravel&logoColor=white)](https://laravel.com) +[![PHP](https://img.shields.io/badge/PHP-8.2+-777BB4?logo=php&logoColor=white)](https://php.net) +[![Filament](https://img.shields.io/badge/Filament-3.3-EDB200?logo=laravel&logoColor=white)](https://filamentphp.com) +[![WordPress](https://img.shields.io/badge/WordPress-7.0.3-21759B?logo=wordpress&logoColor=white)](https://wordpress.org) +[![MySQL](https://img.shields.io/badge/MySQL-8+-4479A1?logo=mysql&logoColor=white)](https://mysql.com) +[![License](https://img.shields.io/badge/License-Proprietary-blue.svg)]() +[![Status](https://img.shields.io/badge/Status-Phase_3-60%25-yellow.svg)]() + +--- + +*جایگزینی فرآیندهای دستی مبتنی بر اکسل با معماری Headless مدرن* + +**[📚 مستندات](#-مستندات)** • **[⚡ شروع سریع](#-شروع-سریع)** • **[🏗️ معماری](#%EF%B8%8F-معماری-سیستم)** • **[📞 پشتیبانی](#-تماس)** + +
--- ## 📖 درباره پروژه -سیستم مدیریت لجستیک ایف‌نکس (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 │ -└─────────────────┘ └────────┬────────┘ -│ -┌────────┴────────┐ -│ 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 اطلاعاتی +``` +┌──────────────────────────────────────────────────────┐ +│ CLIENT BROWSER │ +└────────────────────────┬─────────────────────────────┘ + │ +┌────────────────────────▼─────────────────────────────┐ +│ 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 + +--- + +
-📚 مستندات بیشتر -برای مطالعه دقیق منطق‌های سیستم، حتماً فایل‌های داخل پوشه 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 است و کپی یا استفاده‌ی غیرمجاز از آن ممنوع است. \ No newline at end of file + +© 2026 VernaSoft Group. تمام حقوق محفوظ است. +این پروژه اختصاصی شرکت IFNEX است و کپی یا استفاده غیرمجاز ممنوع می‌باشد. + +