6aee0324d4
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.
270 lines
9.0 KiB
Markdown
270 lines
9.0 KiB
Markdown
<div align="center">
|
||
|
||
# ⚙️ IFNEX Laravel Backend
|
||
|
||
### هسته مرکزی سیستم مدیریت لجستیک ایفنکس
|
||
|
||
[](https://laravel.com)
|
||
[](https://php.net)
|
||
[](https://filamentphp.com)
|
||
[](https://mysql.com)
|
||
|
||
---
|
||
|
||
**REST API + Admin Panel + Financial Engine**
|
||
|
||
[🚀 نصب سریع](#-نصب-و-راهاندازی-سریع) • [📡 API Endpoints](#-api-endpoints) • [🗃️ Models](#-models) • [📚 مستندات](#-مستندات)
|
||
|
||
</div>
|
||
|
||
---
|
||
|
||
## 🎯 نمای کلی
|
||
|
||
این پوشه شامل **هسته مرکزی سیستم IFNEX** است:
|
||
|
||
- REST API کامل برای ارتباط با WordPress
|
||
- پنل مدیریت Filament
|
||
- موتور قیمتگذاری با ۴ زون و ۳ نوع سرویس
|
||
- سیستم کیف پول و پرداخت
|
||
- تولید PDF (AWB, Invoice, Label) با بارکد
|
||
- سیستم اعلانها و تاریخچه تغییرات
|
||
|
||
---
|
||
|
||
## 🚀 نصب و راهاندازی سریع
|
||
|
||
### پیشنیازها
|
||
|
||
| ابزار | حداقل نسخه |
|
||
|-------|-----------|
|
||
| PHP | 8.2+ |
|
||
| Composer | 2.x |
|
||
| MySQL | 8.0+ |
|
||
|
||
### مراحل نصب
|
||
|
||
```bash
|
||
# ۱. ورود به پوشه لاراول
|
||
cd 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
|
||
```
|
||
|
||
### 🔐 دسترسی پیشفرض
|
||
|
||
| آیتم | مقدار |
|
||
|-------|-------|
|
||
| URL پنل | http://localhost:8000/panel |
|
||
| ایمیل ادمین | admin@ifnex.local |
|
||
| رمز عبور | password |
|
||
|
||
### ⚙️ تنظیمات مهم .env
|
||
|
||
```env
|
||
# DATABASE
|
||
DB_CONNECTION=mysql
|
||
DB_HOST=127.0.0.1
|
||
DB_PORT=3306
|
||
DB_DATABASE=ifnex_db
|
||
DB_USERNAME=root
|
||
DB_PASSWORD=
|
||
|
||
# IFNEX
|
||
IFNEX_API_KEY=ifnex-local-dev-key
|
||
IFNEX_TRACKING_RATE_LIMIT=60
|
||
|
||
# CORS (فقط دامنههای مجاز وردپرس)
|
||
CORS_ALLOWED_ORIGINS=http://localhost:8080,http://ifnex.local
|
||
|
||
# PAYMENT GATEWAY (Zarinpal)
|
||
ZARINPAL_MERCHANT_ID=your_merchant_id
|
||
ZARINPAL_SANDBOX=true
|
||
```
|
||
|
||
---
|
||
|
||
## 📡 API Endpoints
|
||
|
||
### 🔓 API عمومی (API Key)
|
||
|
||
| متد | 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` | خروج |
|
||
|
||
### 🔐 API مشتری (Sanctum Token)
|
||
|
||
| متد | 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` | خواندن اعلان |
|
||
|
||
### 💰 API کیف پول (Sanctum Token)
|
||
|
||
| متد | Endpoint | توضیح |
|
||
|------|----------|--------|
|
||
| GET | `/api/v1/wallet/balance` | موجودی |
|
||
| GET | `/api/v1/wallet/transactions` | تراکنشها |
|
||
|
||
### 💳 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/
|
||
│ ├── Enums/ # ShipmentStatus, ShipmentDirection, ShipmentType
|
||
│ ├── Filament/
|
||
│ │ ├── Resources/ # Shipment, Country, ShippingRate, Currency
|
||
│ │ ├── Pages/ # Settings, ImportRates, PriceTest
|
||
│ │ └── Widgets/ # Dashboard Widgets
|
||
│ ├── Http/
|
||
│ │ ├── 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/ # 15+ migrations
|
||
│ └── seeders/ # Countries, SystemSettings, DatabaseSeeder
|
||
│
|
||
├── resources/views/
|
||
│ └── pdfs/ # awb.blade, invoice.blade, label.blade
|
||
│
|
||
├── 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> |