91ecbc7656
Update project documentation to reflect the completion of Phase 0 and the current progress of Phase 1. This includes: - Updating `STATUS.md` and `README.md` to mark Phase 0 as completed. - Adding details for Phase 1 features: `PriceCalculatorService`, online order forms, and professional PDF generation. - Documenting new API endpoints for price calculation and tracking. - Updating the Laravel technical stack to include `dompdf` and `laravel-dompdf`. - Detailing the new directory structure and public web routes.
215 lines
14 KiB
Markdown
215 lines
14 KiB
Markdown
# 🚀 IFNEX Logistics Management System
|
||
> جایگزینی فرآیندهای دستی مبتنی بر اکسل با یک معماری Headless مدرن
|
||
|
||
| مورد | توضیحات |
|
||
| :--- | :--- |
|
||
| **ویرایش سند** | v4.0 (Laravel 11 + Filament 3.3 + فاز ۰ کامل + فاز ۱ در حال اجرا) |
|
||
| **توسعهدهنده** | VernaSoft Group — Kazem Alghasi |
|
||
| **مشتری** | شرکت حمل و نقل بینالمللی ایفنکس (IFNEX) — اصفهان |
|
||
|
||
---
|
||
|
||
## 📖 درباره پروژه
|
||
سیستم مدیریت لجستیک ایفنکس (IFNEX) یک راهحل جامع برای جایگزینی فرآیندهای مبتنی بر فایلهای اکسل در شرکتهای حمل و نقل بینالمللی است. این سیستم با استفاده از معماری Headless، وردپرس را برای ظاهر سایت و سئو، و لاراول را بهعنوان قلب تپنده و موتور محاسباتی به کار میگیرد.
|
||
|
||
### چرا این پروژه متفاوت است؟
|
||
بهجای آنکه اپراتورها وزن حجمی را محاسبه کنند، زونها را در ۴ شیت مختلف جستجو کنند و با ماشینحساب قیمت نهایی را حساب کنند، اکنون تمام این فرآیند در کسر از ثانیه و بدون هیچ خطای انسانی انجام میشود. همچنین، به دلیل تحریمهای بینالمللی و مسدود بودن دسترسی مستقیم به API شرکتهای DHL/FedEx/UPS از ایران، این سیستم از طریق یک سرور VPS پل (در فاز ۳) مشکل ترکینگ خودکار را حل میکند.
|
||
|
||
---
|
||
|
||
## 🏗️ معماری سیستم
|
||
سیستم بر اساس الگوی Headless توسعه یافته است. فرانتاند (وردپرس) و بکاند (لاراول) کاملاً از هم جدا شدهاند و فقط از طریق REST API با هم ارتباط دارند.
|
||
|
||
| لایه | تکنولوژی | نقش |
|
||
| :--- | :--- | :--- |
|
||
| **فرانتاند** | WordPress | مدیریت ظاهر، منوها، لندینگ پیجها، صفحات ثابت، وبلاگ سئو |
|
||
| **بکاند** | Laravel 11 | API سرور، پنل ادمین (Filament 3.3)، موتور قیمتگذاری، صدور PDF، کیف پول |
|
||
| **پل ارتباطی** | پلاگین اختصاصی IFNEX Bridge | ارسال درخواستهای کاربر از وردپرس به لاراول |
|
||
| **زیرساخت رهگیری** | VPS خارج از کشور (در فاز ۳) | واسط برای دسترسی به APIهای رهگیری بینالمللی |
|
||
|
||
---
|
||
|
||
## 🗺️ نقشه راه ۴ فازی
|
||
این پروژه به چهار فاز تقسیم شده تا هم تحویل تدریجی ارزش به مشتری حفظ شود و هم ریسک دوبارهکاری حذف گردد.
|
||
|
||
| فاز | هدف اصلی | مدت زمان | وضعیت |
|
||
| :--- | :--- | :--- | :--- |
|
||
| **فاز ۰** | بنیان داده + وبسایت + ترکینگ دستی + مهاجرت دادههای تاریخی | ۴ هفته | ✅ کامل |
|
||
| **فاز ۱** | موتور قیمتگذاری کامل + ثبت سفارش آنلاین + تولید PDFها + استعلام قیمت | ۴-۶ هفته | 🚧 در حال اجرا |
|
||
| **فاز ۲** | حساب کاربری مشتری + کیف پول + حسابداری ساده + تخفیف حجمی | ۴ هفته | ⏳ در صف |
|
||
| **فاز ۳** | VPS پل + API ترکینگ زنده + CRM + داشبورد مالی تحلیلی | ۶-۸ هفته | ⏳ در صف |
|
||
|
||
> 💡 جزئیات کامل هر فاز، اسکیمای دیتابیس، جدول زمانی و معیارهای پذیرش در سند `01_Documents/Phase0_Proposal.md` آمده است.
|
||
|
||
---
|
||
|
||
## ✨ ویژگیهای کلیدی
|
||
|
||
### فاز ۰ (تکمیل شده)
|
||
1. اسکیمای دیتابیس اصلاحشده (بر اساس فایل اکسل عملیاتی)
|
||
- جدول `countries` با ۴ زون مجزا (صادرات/واردات × پارسل/داکیومنت)
|
||
- پشتیبانی از ۳ نوع سرویس: `DOC_NORMAL`, `DOC_ECONOMY`, `PARCEL`
|
||
- جدول `shipment_carrier_mappings` برای نگاشت چند شرکت حمل به هر بارنامه
|
||
- جدول `shipment_tracking_events` برای ذخیره تایملاین کامل رویدادهای هر مرسوله
|
||
|
||
2. پنل مدیریت اختصاصی (Laravel Filament)
|
||
- مدیریت ۲۳۳ کشور با زونهای صادرات و واردات
|
||
- فرم تنظیمات سیستم: تغییر سریع ارزها و ضریب سود بدون دستکاری کد
|
||
- UX تخصصی اپراتور ترکینگ: افزودن رویداد در چند ثانیه با فیلدهای از پیش پر شده
|
||
|
||
3. ارتباطات API و فرانتاند
|
||
- **API ترکینگ:** `GET /api/track/{awb_no}` با API Key + Rate Limiting + CORS
|
||
- **پلاگین IFNEX Bridge:** شورتکد `[ifnex_tracking_form]` برای فرم رهگیری در وردپرس
|
||
- **امنیت:** API Key + Rate Limiting + CORS whitelist + Form Request Validation
|
||
|
||
4. مهاجرت دادههای تاریخی
|
||
- انتقال ۳۹۵۰ رکورد تاریخی از فایل اکسل به دیتابیس جدید
|
||
- اعتبارسنجی و پاکسازی خودکار دادهها
|
||
|
||
### فاز ۱ (در حال اجرا)
|
||
1. موتور قیمتگذاری کامل (`PriceCalculatorService`)
|
||
- محاسبه خودکار قیمت بر اساس وزن، زون، نوع سرویس و جهت ارسال
|
||
- پشتیبانی از ۴ زون مجزا (export/import × doc/parcel)
|
||
- اعمال ضریب سود، VAT و هزینههای اضافی
|
||
|
||
2. فرم ثبت سفارش آنلاین
|
||
- فرم عمومی برای مشتریان با ۹ ردیف کالای گمرکی
|
||
- اعتبارسنجی خودکار و محاسبه لحظهای قیمت
|
||
- تولید AWB number خودکار
|
||
|
||
3. تولید PDFهای حرفهای
|
||
- **AWB:** بارنامه هوایی با لوگوی IFNEX
|
||
- **INVOICE:** فاکتور تجاری با جدول ۹ ردیف کالای گمرکی
|
||
- **LABEL:** لیبل چاپی برای بستهها (پرینتر لیزری + کاغذ چسبان A4)
|
||
- تطبیق اولیه با قالبهای اکسل + لوگوی استخراجشده
|
||
|
||
4. صفحه استعلام قیمت واقعی
|
||
- رابط کاربری عمومی برای محاسبه قیمت تقریبی حمل
|
||
- نمایش قیمت پایه (درهم) و قیمت نهایی (ریال)
|
||
|
||
5. ماژول ایمپورت اکسل تعرفهها
|
||
- کامند `php artisan ifnex:import:rates` با قابلیتهای `--clear` و `--dry-run`
|
||
- پشتیبانی از شیتهای Export Rate، Import Rate و DocEco
|
||
- تبدیل خودکار واحد قیمت (ریال → درهم) برای شیتهای DocNor/DocEco
|
||
|
||
---
|
||
|
||
## 📁 ساختار پروژه
|
||
```text
|
||
IFNEX-Logistics/
|
||
├── 01_Documents/ # مستندات فنی پروژه
|
||
│ ├── STATUS.md # ⭐ وضعیت فعلی و گزارش پیشرفت
|
||
│ ├── IFNEX_Phase0_Checklist.md # ⭐ چکلیست دقیق فاز ۰
|
||
│ ├── Phase0_Proposal.md # ⭐ سند پیشنهاد فاز ۰ (نقشه راه جدید)
|
||
│ ├── EXCEL_ANALYSIS.md # ⭐ تحلیل فایلهای اکسل
|
||
│ ├── PRD_v2.md # سند نیازمندیها (نسخه قدیمی — بهزودی بازنویسی)
|
||
│ └── Project_Roadmap.md # نقشه راه و چکلیست (بهزودی بهروزرسانی)
|
||
│
|
||
├── 02_Design/ # فایلهای UI/UX و فیگما
|
||
│ └── Assets/ # لوگوها، آیکونها
|
||
│
|
||
├── 03_WordPress/ # سیستم مدیریت محتوا (فرانتاند)
|
||
│ └── wp-content/plugins/
|
||
│ └── ifnex-bridge/ # پلاگین اختصاصی ارتباط با لاراول
|
||
│
|
||
└── 04_Laravel/ # هسته مرکزی سیستم (بکاند)
|
||
├── app/
|
||
│ ├── Models/ # Country, Shipment, ShipmentItem, ShipmentRate, ...
|
||
│ ├── Enums/ # ShipmentDirection, ShipmentType, ShipmentStatus, ...
|
||
│ ├── Services/ # PriceCalculatorService, PdfService, ...
|
||
│ ├── Http/
|
||
│ │ ├── Controllers/
|
||
│ │ │ ├── Api/ # PricingController, TrackController
|
||
│ │ │ ├── OrderController.php # فرم ثبت سفارش آنلاین
|
||
│ │ │ ├── PricingPageController.php # صفحه استعلام قیمت
|
||
│ │ │ └── ShipmentPdfController.php # تولید PDF
|
||
│ │ ├── Middleware/ # ApiKeyMiddleware
|
||
│ │ └── Requests/ # Form Request Validation classes
|
||
│ ├── Imports/ # ShippingRatesImport
|
||
│ ├── Console/Commands/ # ImportShippingRates
|
||
│ └── Filament/ # پنل مدیریت ادمین
|
||
│ ├── Resources/ # Country, Shipment, ShippingRate, ShipmentItem
|
||
│ └── Pages/ # Settings, Dashboard, Custom pages
|
||
├── database/
|
||
│ ├── migrations/ # ۷ migration فاز ۰
|
||
│ └── seeders/ # CountriesSeeder, SystemSettingSeeder
|
||
├── routes/
|
||
│ ├── web.php # روتهای عمومی: /order, /pricing, PDF download
|
||
│ └── api.php # API: /api/v1/calculate, /api/v1/track/{awb}
|
||
├── resources/views/
|
||
│ ├── layouts/app.blade.php # لایاوت عمومی صفحات
|
||
│ ├── orders/ # فرم ثبت سفارش + صفحه موفقیت
|
||
│ ├── pricing/ # صفحه استعلام قیمت
|
||
│ └── pdfs/ # قالبهای PDF: AWB, INVOICE, LABEL
|
||
├── config/
|
||
│ ├── ifnex.php
|
||
│ └── cors.php
|
||
└── bootstrap/
|
||
└── app.php
|
||
|
||
|
||
🚀 راهاندازی و اجرا (Localhost)
|
||
پیشنیازها
|
||
XAMPP یا مشابه (PHP 8.2+ و MySQL 8+)
|
||
Composer
|
||
Node.js و NPM (برای ابزارهای وردپرس/المنتور)
|
||
مراحل نصب (بخش لاراول)
|
||
|
||
# ۱. کلون مخزن و وارد شدن به پوشه لاراول
|
||
git clone https://www.git.vernahost.ir/gitmodir110/ifnex.git
|
||
cd ifnex/04_Laravel
|
||
|
||
# ۲. نصب پکیجها
|
||
composer install
|
||
|
||
# ۳. کپی فایل محیط و تنظیم دیتابیس
|
||
cp .env.example .env
|
||
# فایل .env را ویرایش کرده و اطلاعات دیتابیس XAMPP را وارد کنید
|
||
|
||
# ۴. تولید کلید اپلیکیشن
|
||
php artisan key:generate
|
||
|
||
# ۵. اجرای Migration ها
|
||
php artisan migrate --force
|
||
|
||
# ۶. درج دادههای اولیه (کشورها و نرخ ارز اولیه)
|
||
php artisan db:seed --force
|
||
|
||
# ۷. اجرای سرور توسعه
|
||
php artisan serve
|
||
|
||
|
||
مراحل نصب (بخش وردپرس)
|
||
۱. پوشهی 03_WordPress را در htdocs یا مسیر هاست وردپرس قرار دهید.
|
||
|
||
۲. وردپرس را بهصورت معمول نصب کنید.
|
||
|
||
۳. پلاگین ifnex-bridge را از مسیر wp-content/plugins/ifnex-bridge فعال کنید.
|
||
|
||
۴. در تنظیمات پلاگین، URL لاراول و API Key را وارد کنید.
|
||
|
||
۵. شورتکد [ifnex_tracking_form] را در صفحهی «رهگیری مرسوله» قرار دهید.
|
||
|
||
⚠️ نکات امنیتی و تولید (Production)
|
||
هرگز فایل .env را در مخزن کد (Git) کامیت نکنید (در .gitignore تأیید شده).
|
||
در محیط تولید، APP_DEBUG=false را در .env تنظیم کنید.
|
||
برای محیط تولید، پیکربندی وبسرور (Nginx/Apache) و تنظیمات CORS برای ارتباط WP و Laravel ضروری است.
|
||
برای API ترکینگ خودکار (فاز ۳)، سرور VPS پل در خارج از کشور راهاندازی شود — راهنمای کامل در سند فاز ۳.
|
||
📚 مستندات بیشتر
|
||
برای مطالعه دقیق منطقهای سیستم، حتماً فایلهای داخل پوشه 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 است و کپی یا استفادهی غیرمجاز از آن ممنوع است.
|