Kazem Alghasi 91ecbc7656 docs(project): update documentation and project status for phase 1

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.

2026-08-04 09:58:33 +03:30

14 KiB

Raw Blame History

🚀 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 آمده است.

✨ ویژگی‌های کلیدی

فاز ۰ (تکمیل شده)

اسکیمای دیتابیس اصلاح‌شده (بر اساس فایل اکسل عملیاتی)
- جدول countries با ۴ زون مجزا (صادرات/واردات × پارسل/داکیومنت)
- پشتیبانی از ۳ نوع سرویس: DOC_NORMAL, DOC_ECONOMY, PARCEL
- جدول shipment_carrier_mappings برای نگاشت چند شرکت حمل به هر بارنامه
- جدول shipment_tracking_events برای ذخیره تایم‌لاین کامل رویدادهای هر مرسوله
پنل مدیریت اختصاصی (Laravel Filament)
- مدیریت ۲۳۳ کشور با زون‌های صادرات و واردات
- فرم تنظیمات سیستم: تغییر سریع ارزها و ضریب سود بدون دستکاری کد
- UX تخصصی اپراتور ترکینگ: افزودن رویداد در چند ثانیه با فیلدهای از پیش پر شده
ارتباطات 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
مهاجرت داده‌های تاریخی
- انتقال ۳۹۵۰ رکورد تاریخی از فایل اکسل به دیتابیس جدید
- اعتبارسنجی و پاکسازی خودکار داده‌ها

فاز ۱ (در حال اجرا)

موتور قیمت‌گذاری کامل (PriceCalculatorService)
- محاسبه خودکار قیمت بر اساس وزن، زون، نوع سرویس و جهت ارسال
- پشتیبانی از ۴ زون مجزا (export/import × doc/parcel)
- اعمال ضریب سود، VAT و هزینه‌های اضافی
فرم ثبت سفارش آنلاین
- فرم عمومی برای مشتریان با ۹ ردیف کالای گمرکی
- اعتبارسنجی خودکار و محاسبه لحظه‌ای قیمت
- تولید AWB number خودکار
تولید PDFهای حرفه‌ای
- AWB: بارنامه هوایی با لوگوی IFNEX
- INVOICE: فاکتور تجاری با جدول ۹ ردیف کالای گمرکی
- LABEL: لیبل چاپی برای بسته‌ها (پرینتر لیزری + کاغذ چسبان A4)
- تطبیق اولیه با قالب‌های اکسل + لوگوی استخراج‌شده
صفحه استعلام قیمت واقعی
- رابط کاربری عمومی برای محاسبه قیمت تقریبی حمل
- نمایش قیمت پایه (درهم) و قیمت نهایی (ریال)
ماژول ایمپورت اکسل تعرفه‌ها
- کامند php artisan ifnex:import:rates با قابلیت‌های --clear و --dry-run
- پشتیبانی از شیت‌های Export Rate، Import Rate و DocEco
- تبدیل خودکار واحد قیمت (ریال → درهم) برای شیت‌های DocNor/DocEco

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

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 است و کپی یا استفاده‌ی غیرمجاز از آن ممنوع است.

14 KiB Raw Blame History Unescape Escape