542 lines
34 KiB
Markdown
542 lines
34 KiB
Markdown
<div align="center">
|
||
|
||
# 🚀 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 مدرن جایگزین می‌کند. این سیستم با تکیه بر **Laravel 11** به‌عنوان بک‌اند، **WordPress** به‌عنوان فرانت‌اند و **Filament 3.3** به‌عنوان پنل مدیریت، تجربه‌ای یکپارچه برای اپراتورها و مشتریان فراهم می‌آورد.
|
||
|
||
### ✨ امکانات کلیدی
|
||
|
||
- **معماری ارزی IRR-only** — ارز مبنا = ریال ایران؛ تبدیل ارز در زمان ایمپورت، نه محاسبه
|
||
- **موتور قیمت‌گذاری هوشمند** با ۴-رُبعی (Export/Import × Doc/Parcel) و ایمپورت از اکسل
|
||
- **دریافت خودکار نرخ ارز** از Exir.io (USD/AED) + FreeCurrencyAPI (EUR/CNY) با کرون روزانه
|
||
- **فاکتورهای دستی مدیر** — صدور فاکتور برای خدمات خارج از سفارش + پرداخت از کیف پول + اعلان خودکار
|
||
- **ثبت سفارش آنلاین چندمرحله‌ای** با Wizard و محاسبهٔ لحظه‌ای قیمت
|
||
- **پشتیبانی چندبسته‌ای** (Multi-Package) در یک سفارش با محاسبهٔ خودکار وزن حجمی
|
||
- **دفترچه آدرس مشتری** — ذخیره و انتخاب یک‌کلیکی آدرس‌های پرتکرار (فرستنده/گیرنده) با سقف ۵۰ رکورد و رکورد تکراری نداشتن
|
||
- **تولید خودکار اسناد** (AWB، Invoice، Label، فاکتور واردات) با بارکد Code-128 و پشتیبانی کامل از زبان انگلیسی
|
||
- **پورتال مشتری کامل** با کیف پول، پرداخت آنلاین، فاکتورهای دستی، دفترچه آدرس، تراکنش‌ها، اعلان‌ها و رهگیری مرسوله
|
||
- **فلوی تأیید سفارش** با مسیر `pending_approval → approved → paid → processed`
|
||
- **چرخهٔ تعهدنامه** با فلوی کامل End-to-End (دانلود قالب ← آپلود امضاشده ← تأیید یا رد ادمین ← اعلان مشتری)
|
||
- **سیستم اعتبار چندارزی** — بدهی به همان ارز ثبت می‌شود، تسویه با نرخ روز
|
||
- **مانده حساب** با نمایش موجودی کیف پول منهای بدهی‌های تأییدشده (سفارشات + فاکتورهای دستی)
|
||
- **وضعیت مالی مشتری** — صفحهٔ جامع در پنل ادمین (۴ KPI + بدهی‌های ارزی + سفارش‌ها و تراکنش‌ها)
|
||
- **ویجت هشدار بدهی‌های ارزی** روی داشبورد به‌همراه badge روی منو
|
||
- **چک‌لیست خودکار کارمند** — نمونه‌سازی از قالب پس از تأیید سفارش
|
||
- **ایمپورت گروهی وضعیت ترکینگ** با فایل CSV در پنل مدیریت
|
||
- **سیستم Audit Log** برای ثبت لاگ تغییرات مدیر
|
||
- **پنل مدیریت قدرتمند Filament** شامل مدیریت مرسوله‌ها، نرخ‌ها، ارزها، فاکتورهای دستی، کاربران و گزارش‌ها
|
||
- **سیستم ترکینگ** با مهاجرت داده‌های تاریخی و تایم‌لاین کامل
|
||
- **اعلان‌های دیتابیس** برای ادمین و مشتری با badge unread در سایدبار
|
||
- **Rate Limiting** روی همهٔ APIها (۶ لایه: auth / sms / public / customer / wallet / staff)
|
||
- **پشتیبانی از ۱۹۲ کشور** با پیش‌شمارهٔ تلفن استاندارد ISO 3166-1
|
||
- **اعتبارسنجی فرم‌ها** با تشخیص خودکار زبان فارسی/انگلیسی و پیش‌شمارهٔ خودکار
|
||
- **سرویس پیامک Kavenegar** برای تأیید موبایل و ارسال اعلان وضعیت سفارش
|
||
- **دستورات خودکار استقرار** — `ifnex:preflight` (fail-fast)، `ifnex:import-fx-rates` (نرخ ارز)، `ifnex:smoke-test` (E2E post-deploy)
|
||
|
||
---
|
||
|
||
## 🏗️ معماری سیستم
|
||
|
||
این پروژه بر اساس الگوی **Headless** طراحی شده است — فرانت‌اند (WordPress) و بک‌اند (Laravel) کاملاً جدا و فقط از طریق REST API با هم ارتباط دارند. این جداسازی امکان مقیاس‌پذیری مستقل هر لایه، بهبود امنیت و افزودن فرانت‌اندهای آینده (مثل اپلیکیشن موبایل) را می‌دهد.
|
||
|
||
```text
|
||
┌──────────────────────────────────────────────────────┐
|
||
│ CLIENT BROWSER │
|
||
└────────────────────────┬─────────────────────────────┘
|
||
│
|
||
┌────────────────────────▼─────────────────────────────┐
|
||
│ WORDPRESS (Frontend) │
|
||
│ ┌───────────────────┐ ┌──────────────────────────┐ │
|
||
│ │ IFNEX Theme │ │ IFNEX Bridge Plugin │ │
|
||
│ │ (Landing Page) │ │ (REST Client + AJAX) │ │
|
||
│ └───────────────────┘ └────────────┬─────────────┘ │
|
||
└───────────────────────────────────────┼──────────────┘
|
||
│ REST API (Sanctum + Bridge Key)
|
||
┌───────────────────────────────────────▼──────────────┐
|
||
│ LARAVEL 11 (Backend) │
|
||
│ ┌─────────────────┐ ┌──────────────┐ ┌──────────┐ │
|
||
│ │ Filament │ │ API │ │ Services │ │
|
||
│ │ Admin Panel │ │ Controllers │ │ (Pricing,│ │
|
||
│ │ (/panel) │ │ (/api/v1) │ │ PDF, │ │
|
||
│ └─────────────────┘ └──────┬───────┘ │ Payment) │ │
|
||
└──────────────────────────────┼──────────┴──────────┘
|
||
│
|
||
┌────────────▼────────────┐
|
||
│ MySQL 8 Database │
|
||
│ (62 migrations, 31 │
|
||
│ models) │
|
||
└─────────────────────────┘
|
||
```
|
||
|
||
### جریان احراز هویت
|
||
|
||
```text
|
||
┌──────────┐ ┌─────────────────┐ ┌──────────────┐
|
||
│ WordPress│ ──POST /bridge/login──> │ Laravel Bridge │ ──> │ Sanctum Token│
|
||
│ Plugin │ <──token + user info── │ Controller │ <── │ (30 days) │
|
||
└──────────┘ └─────────────────┘ └──────────────┘
|
||
│ │
|
||
│ ──────── All subsequent API calls with Bearer Token ──────────────>│
|
||
└─────────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 📁 ساختار پروژه
|
||
|
||
```text
|
||
IFNEX-Logistics/
|
||
├── 📄 01_Documents/ # مستندات فنی پروژه
|
||
│ ├── IFNEX_File_Map.md # نقشهٔ کامل فایل‌های پروژه
|
||
│ ├── IFNEX_Roadmap.md # نقشهٔ راه فازی (۰ تا ۳.۱۱ + آینده ۴/۵)
|
||
│ ├── IFNEX_ADR.md # تصمیمات معماری (ADR-001 تا 009)
|
||
│ ├── IFNEX_Commercial_Model.md # مدل تجاری (Starter/Business/Enterprise)
|
||
│ ├── IFNEX_Pro_Backlog.md # فیچرهای نگه‌داشته‌شده برای نسخه Pro
|
||
│ ├── IFNEX_I18N_Strategy.md # استراتژی چندزبانه (موکول به زمان دیپلوی)
|
||
│ ├── DESIGN_SYSTEM.md # سیستم طراحی
|
||
│ ├── EXCEL_ANALYSIS.md # تحلیل داده‌های تاریخی
|
||
│ └── archives/ # اسناد منسوخ‌شده (PRD_v2، Project_Roadmap قدیم)
|
||
│
|
||
├── 🌐 03_WordPress/ # فرانت‌اند (WordPress 7.1)
|
||
│ └── wp-content/
|
||
│ ├── themes/ifnex/ # قالب سفارشی IFNEX
|
||
│ └── plugins/ifnex-bridge/ # پلاگین ارتباط با لاراول
|
||
│ ├── includes/
|
||
│ │ ├── api-client.php # ارتباط مستقیم با API
|
||
│ │ ├── user-bridge.php # احراز هویت Bridge + AJAX handlers
|
||
│ │ ├── shortcodes.php # ۱۰+ شورت‌کد
|
||
│ │ └── tracking-form.php # فرم رهگیری
|
||
│ └── assets/
|
||
│ ├── css/ # استایل داشبورد + دفترچه آدرس
|
||
│ └── js/ # فرم چندمرحله‌ای + دفترچه آدرس
|
||
│
|
||
├── ⚙️ 04_Laravel/ # بک‌اند (Laravel 11)
|
||
│ ├── app/
|
||
│ │ ├── Console/Commands/ # ifnex:preflight, import-fx-rates, smoke-test + ۶ دستور قدیمی
|
||
│ │ ├── Enums/ # ShipmentStatus، Direction، Type
|
||
│ │ ├── Filament/
|
||
│ │ │ ├── Resources/ # ۱۹ Resource (Shipment، AddressBookEntry و…)
|
||
│ │ │ ├── Pages/ # Dashboard، IfnexSettings، ImportRates، CustomerFinancialOverview
|
||
│ │ │ └── Widgets/ # داشبورد
|
||
│ │ ├── Http/
|
||
│ │ │ ├── Controllers/Api/ # Track، Pricing، Auth، Bridge، Customer، Wallet، Payment، AddressBook
|
||
│ │ │ └── Middleware/ # ApiKeyMiddleware، StaffApiMiddleware، SetCspHeaders
|
||
│ │ ├── Models/ # ۳۱ مدل Eloquent
|
||
│ │ ├── Notifications/ # اعلان‌های دیتابیسی + SMS
|
||
│ │ ├── Services/ # PriceCalculator، Pdf، Tracking، OrderPayment، DiscountCode، CustomerCredit، AddressBook
|
||
│ │ └── Imports/ # ایمپورت اکسل (OldShipments، ShippingRates)
|
||
│ ├── database/
|
||
│ │ ├── migrations/ # ۶۲ migration
|
||
│ │ └── seeders/ # Countries، SystemSettings، Currency، RoleAndPermission، DatabaseSeeder
|
||
│ ├── scripts/ # deploy.sh + cron-exir-rates.sh + one-off/
|
||
│ ├── resources/views/
|
||
│ │ ├── pdfs/ # awb، invoice، label، import-invoice
|
||
│ │ └── filament/ # Blade views
|
||
│ └── routes/
|
||
│ ├── api.php # ۵۰+ endpoint
|
||
│ └── web.php # روت‌های وب + دانلود Template
|
||
│
|
||
├── 📋 README.md # همین فایل
|
||
├── 📋 AGENT.md # راهنمای ایجنت
|
||
├── 📋 CLIENT_DELIVERY.md # چک‌لیست وضعیت تحویل مشتری (منبع اصلی وضعیت)
|
||
├── 📋 UAT-3.11.md # چک‌لیست ۴۳ موردی UAT نهایی کارفرما (فاز ۳.۱۱)
|
||
├── 📋 RATE_IMPORTER.md # راهنمای ایمپورت نرخ‌ها (سیستم ۴-رُبعی)
|
||
└── 📋 DEPLOYMENT_HANDOFF.md # تحویل استقرار به تیم IT کارفرما
|
||
```
|
||
|
||
---
|
||
|
||
## ✨ ویژگی‌ها بر اساس فازها
|
||
|
||
### فاز ۰ — بنیان سیستم ✅ (۱۰۰٪)
|
||
|
||
- اسکیمای دیتابیس مدرن با ۴ زون مجزا (Export/Import × Parcel/Doc)
|
||
- مهاجرت ۳۹۵۰ رکورد تاریخی از اکسل به دیتابیس
|
||
- پنل مدیریت Filament با UX تخصصی اپراتور
|
||
- API ترکینگ با امنیت کلید API و Rate Limiting
|
||
- پلاگین WordPress Bridge برای ارتباط با فرانت‌اند
|
||
|
||
### فاز ۱ — پورتال مشتری ✅ (۱۰۰٪)
|
||
|
||
- احراز هویت Laravel Sanctum + Bridge Auth (بدون نیاز به رمز عبور)
|
||
- فرم ثبت سفارش چندمرحله‌ای با Wizard (مسیر، اطلاعات تماس، تخفیف، تأیید)
|
||
- داشبورد جامع مشتری: داشبورد، سفارش‌ها، ثبت سفارش، کیف پول، تراکنش‌ها، رهگیری، اعلان‌ها، پروفایل
|
||
- سیستم ترکینگ با تایم‌لاین و تاریخچهٔ کامل
|
||
|
||
### فاز ۲ — مالی و کیف پول ✅ (۱۰۰٪)
|
||
|
||
- سیستم کیف پول کامل با تراکنش‌ها و تاریخچه
|
||
- درگاه پرداخت Zarinpal + Mock Gateway برای تست لوکال
|
||
- مدیریت ارزهای چندگانه (IRR، AED، USD، EUR، CNY)
|
||
- کدهای تخفیف با اعتبارسنجی و محدودیت مصرف
|
||
- تولید PDF حرفه‌ای (AWB، Invoice، Label) با بارکد استاندارد
|
||
- پشتیبانی از چند بسته در یک سفارش (Multi-Package)
|
||
- تاریخچهٔ تغییرات وضعیت (ShipmentStatusHistory)
|
||
|
||
### فاز ۳ — بهبود و یکپارچه‌سازی ✅ (۱۰۰٪)
|
||
|
||
- ایمپورت/اکسپورت نرخ‌ها با دانلود Template اکسل
|
||
- سیستم اعلان‌های دیتابیس (ادمین + مشتری) با badge unread در سایدبار
|
||
- هشدار هوشمند زبان فارسی/انگلیسی در فرم سفارش (نام، شهر، آدرس)
|
||
- پیش‌شمارهٔ تلفن خودکار بر اساس کشور انتخابی (۱۹۲ کشور)
|
||
- اعتبارسنجی تلفن (فقط اعداد، `+` و فاصله)
|
||
- استایل مدرن تراکنش‌ها و داشبورد مشتری
|
||
- صفحهٔ شارژ کیف پول با مبالغ آماده
|
||
- بازطراحی PDFها (AWB، Invoice، Label) با بارکد مطابق نمونهٔ کارفرما
|
||
- اصلاح متدهای Enum (`isPaid`، `canBeCancelledByCustomer`)
|
||
- میدلور API برای بازگرداندن JSON 401 به‌جای redirect
|
||
|
||
### فاز ۳.۵ — اصلاحات اساسی ✅ (۱۰۰٪)
|
||
|
||
- Multi-Package در فرم سفارش مشتری (چند بسته در یک سفارش)
|
||
- فرم Invoice برای محموله‌های PARCEL (اقلام گمرکی با HS Code)
|
||
- بازطراحی PDFها (AWB، Invoice، Label) با بارکد مطابق نمونهٔ کارفرما
|
||
- تست کامل ترکینگ با تایم‌لاین چندمرحله‌ای
|
||
- محاسبهٔ خودکار وزن حجمی از ابعاد (فرمول: `L × W × H / 5000`)
|
||
- ساختار ۵ مرحله‌ای فرم سفارش (مسیر ← تماس ← اقلام ← تخفیف ← تأیید)
|
||
- اصلاحات فنی (Enum casts، migration، model)
|
||
- پشتیبانی چندزبانه (i18n) — موکول به زمان دیپلوی
|
||
|
||
### فاز ۳.۶ — اصلاحات جلسهٔ کارفرما ✅ (۱۰۰٪)
|
||
|
||
- [x] فلوی تأیید سفارش `pending_approval → approved → پرداخت → processed` — تست End-to-End
|
||
- [x] تعهدنامه‌ها با فلوی کامل (دانلود قالب ← آپلود امضاشده ← تأیید/رد ادمین ← اعلان مشتری)
|
||
- [x] دانلود اسناد سفارش (AWB، Invoice، Label، فاکتور واردات) در پورتال مشتری
|
||
- [x] صفحهٔ «وضعیت مالی مشتری» در پنل ادمین (۴ KPI + بدهی ارزی + سفارش‌ها و تراکنش‌ها)
|
||
- [x] سیستم اعتبار چندارزی کامل (درخواست ۹) — `CustomerCreditService` + نمایش در پورتال مشتری
|
||
- [x] ویجت هشدار بدهی‌های ارزی روی داشبورد + badge قرمز روی منو
|
||
- [x] چک‌لیست خودکار پس از تأیید سفارش (درخواست ۵) — `instantiateChecklist()`
|
||
- [x] Rate Limiting روی همهٔ APIها (۶ لایه throttle)
|
||
- [x] ایمپورت گروهی وضعیت ترکینگ با CSV در پنل (`BulkTrackingImport`)
|
||
- [x] Audit Log برای مدل‌های اصلی + `ShipmentStatusHistory` با `from_status` / `to_status`
|
||
- [x] اتصال SMS کاوه‌نگار: تأیید/رد سفارش، پرداخت موفق، به‌روزرسانی ترکینگ + تنظیمات پنل
|
||
- [x] فاکتور واردات (Import Invoice) با فیلدهای جدید shipments + قالب PDF
|
||
- [x] مانده حساب (موجودی منهای بدهی‌های تأییدشده) در پروفایل مشتری
|
||
- [x] بازطراحی داشبورد و Login فیلمنت (هویت بصری navy + amber)
|
||
- [x] بازطراحی AWB، Invoice و Label (dompdf، چیدمان جدولی، سبک DHL)
|
||
- [x] استایل‌دهی صفحهٔ پروفایل مشتری در وردپرس
|
||
- [x] پاک‌سازی کد — حذف فایل‌های تستی، تأیید تمیزی `opcache_reset` / `dd` / `dump`
|
||
|
||
### فاز ۳.۷ — اصلاحات ارزی و فاکتور دستی ✅ (۱۰۰٪)
|
||
|
||
- [x] **سیستم ۴-رُبعی نرخ‌ها** (Export/Import × Doc/Parcel) با ایمپورت از اکسل
|
||
- [x] **معماری IRR-only** — ارز مبنا = ریال ایران، حذف جفت‌ارز و تبدیل در زمان ایمپورت
|
||
- [x] **ایمپورت فایل اصلی مشتری** + قالب جدید `IFNEX_Rate_Template.xlsx`
|
||
- [x] **حذف تمام «تومان» و «درهم» از نمایش قیمت‌های داخلی** در همه UIها
|
||
- [x] **فاکتورهای دستی مدیر** — صدور، پرداخت از کیف پول، اعلان خودکار
|
||
- [x] **تب «فاکتورهای دستی» در پورتال وردپرس** (لیست + جزئیات + پرداخت)
|
||
- [x] **اضافه شدن فاکتورها به وضعیت مالی و داشبورد مشتری**
|
||
- [x] **فرمت هزارگان** در فیلدهای عددی فرم فاکتور ادمین
|
||
|
||
### فاز ۳.۸ — برندینگ و تجربهٔ کاربری ✅ (۱۰۰٪)
|
||
|
||
- [x] **Favicon حرفه‌ای IFNEX** — هواپیمای کاغذی کهربایی روی سرمه‌ای (مولتی‌سایز + SVG + webmanifest)
|
||
- [x] **صفحهٔ `/` برندشده** — جایگزین welcome پیش‌فرض لاراول (RTL، وزیرمتن)
|
||
- [x] **جمع‌شدن کارت لاگین فیلمنت** — عرض ۴۴۰←۳۸۰px، موبایل-فرندلی
|
||
- [x] **SweetAlert2 برای خطاهای فرم سفارش وردپرس** — باندل محلی بدون CDN
|
||
|
||
### فاز ۳.۸.۱ — سخت‌سازی Production ✅ (۱۰۰٪)
|
||
|
||
- [x] **باگ P0 کد تخفیف** — `DiscountCodeService` + جدول `discount_code_usages` (idempotency + قفل رقابتی)
|
||
- [x] **گارد Mock Gateway در Production** — `OrderPaymentService` با `Log::critical`
|
||
- [x] **حذف هک‌های دیباگ** از ۵ فایل پلاگین وردپرس (opcache_reset / header / cache-buster)
|
||
- [x] **نسخه‌بندی سالم assetها** — `filemtime` + ثابت `IFNEX_BRIDGE_VERSION`
|
||
- [x] **سخت‌سازی آپلود** — بررسی mimetype واقعی فایل
|
||
- [x] **خروج `wp-config.php` از گیت** (saltها لو‌رفته فرض می‌شوند)
|
||
- [x] **چک‌لیست امنیتی استقرار** در `DEPLOYMENT_HANDOFF.md` (بخش ۴.۴)
|
||
|
||
### فاز ۳.۹ — دفترچه آدرس ✅ (۱۰۰٪)
|
||
|
||
- [x] **مدل + جدول `address_book_entries`** — نقش sender/receiver، سقف ۵۰ رکورد
|
||
- [x] **CRUD API محافظت‌شده با Sanctum** — `GET/POST/PUT/DELETE /api/v1/addresses` + `POST /{id}/default`
|
||
- [x] **اتصال به ثبت سفارش** — چک‌باکس «ذخیره این آدرس» + dropdown در فرم
|
||
- [x] **تب «دفترچه آدرس» در پنل کاربری وردپرس** — کارت‌های آدرس + فیلتر + فرم
|
||
- [x] **۴ پروکسی AJAX امن** (nonce + sanitize + توکن Sanctum)
|
||
- [x] **۱۸ تست Feature جدید** — مالکیت، سقف، تکراری، پیش‌فرض
|
||
|
||
### فاز ۳.۱۰ — استقرار Production ✅ (۱۰۰٪)
|
||
|
||
- [x] **`ifnex:preflight`** — دستور fail-fast برای ممیزی محیط Production پیش از migrate
|
||
- [x] **`ifnex:import-fx-rates`** — جایگزین `ifnex:update-rates` با پشتیبانی از EUR/CNY + `--auto-approve`
|
||
- [x] **`CurrencySeeder`** — پنج ارز پایه (USD/AED/EUR/CNY/IRR)، idempotent
|
||
- [x] **`scripts/deploy.sh`** — اسکریپت خودکار ۱۳ مرحله‌ای استقرار با fail-fast
|
||
- [x] **`scripts/cron-exir-rates.sh`** — wrapper کرون روزانه
|
||
- [x] **سخت‌سازی `.env.example`** — MySQL پیش‌فرض، EXIR_API_URL، SANCTUM_STATEFUL_DOMAINS
|
||
- [x] **رفع باگ latent در `bootstrap/app.php`** — حذف `use ApiKeyAuth` که کلاس وجود نداشت
|
||
- [x] **بهبود `DatabaseSeeder`** — حساب super_admin با رمز `password` در Production ساخته نمی‌شود
|
||
|
||
### فاز ۳.۱۱ — UAT نهایی ✅ (۱۰۰٪)
|
||
|
||
- [x] **`ifnex:smoke-test`** — دستور E2E خودکار Post-Deploy (۲۵+ بررسی: DB، داده‌ها، API endpoints)
|
||
- [x] **۹ تست Feature جدید** — حالت‌های PASS/FAIL با Http::fake
|
||
- [x] **`UAT-3.11.md`** — چک‌لیست ۴۳ موردی فارسی برای کارفرما + فرم امضای تحویل
|
||
- [x] **به‌روزرسانی `CLIENT_DELIVERY.md`** — ثبت فازهای ۳.۱۰ و ۳.۱۱
|
||
|
||
---
|
||
|
||
> ⚠️ **هشدار دربارهٔ فاز ۴ و ۵:** هیچ‌یک از فیچرهای فاز ۴ (سیستم نمایندگی) و فاز ۵ (تجاری‌سازی) پیاده‌سازی نشده‌اند. این‌ها صرفاً طرح آینده‌اند و در [بخش مراحل بعدی](#-مراحل-بعدی) آمده‌اند. برای ارزیابی آمادگی واقعی پروژه، [UAT-3.11.md](UAT-3.11.md) را ببینید.
|
||
|
||
---
|
||
|
||
## ⚡ شروع سریع
|
||
|
||
### پیش‌نیازها
|
||
|
||
- PHP 8.2+ با اکستنشن‌های `pdo_mysql`، `mbstring`، `xml`، `gd`، `zip`
|
||
- Composer 2.x
|
||
- MySQL 8+
|
||
- WordPress 7.1+
|
||
|
||
### نصب بک‌اند (Laravel)
|
||
|
||
```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=ifnex_db
|
||
# DB_USERNAME=root
|
||
# DB_PASSWORD=your_password
|
||
# IFNEX_BRIDGE_API_KEY=change-this-secret-key # مهم برای وردپرس (پیش از استقرار با
|
||
# # openssl rand -hex 32 جایگزین کن)
|
||
# ZARINPAL_MERCHANT_ID=fake-merchant-id-for-testing # برای Mock Mode
|
||
# ZARINPAL_SANDBOX=true
|
||
# CORS_ALLOWED_ORIGINS=http://localhost,http://127.0.0.1
|
||
|
||
# ۶. اجرای migrations و seeders
|
||
php artisan migrate --force
|
||
php artisan db:seed --class=CountriesTableSeeder --force
|
||
php artisan db:seed --class=SystemSettingSeeder --force
|
||
php artisan db:seed --class=CurrencySeeder --force
|
||
php artisan db:seed --class=RoleAndPermissionSeeder --force
|
||
|
||
# ۷. دریافت نرخ ارز اولیه
|
||
php artisan ifnex:import-fx-rates --source=all --auto-approve
|
||
|
||
# ۸. اجرای سرور
|
||
php artisan serve
|
||
# پنل ادمین: http://127.0.0.1:8000/panel
|
||
```
|
||
|
||
> 💡 **نکته:** برای استقرار Production، به‌جای اجرای دستی همهٔ مراحل بالا، از `bash scripts/deploy.sh` استفاده کنید — خودکار و fail-fast.
|
||
|
||
### نصب فرانت‌اند (WordPress)
|
||
|
||
1. پوشهٔ `03_WordPress` را در `htdocs` (XAMPP) یا `public_html` (سرور) کپی کنید.
|
||
2. دیتابیس وردپرس را بسازید و نصب را اجرا کنید.
|
||
3. قالب IFNEX و پلاگین IFNEX Bridge را فعال کنید.
|
||
4. تنظیمات پلاگین را کامل کنید (پنل وردپرس ← منوی IFNEX):
|
||
|
||
| تنظیم | مقدار |
|
||
|--------|--------|
|
||
| API URL | `http://localhost:8000/api/v1` |
|
||
| API Key (عمومی) | همان مقدار `IFNEX_API_KEY` در `.env` لاراول |
|
||
| Bridge API Key | همان مقدار `IFNEX_BRIDGE_API_KEY` در `.env` لاراول |
|
||
|
||
5. صفحات را با شورت‌کدها بسازید:
|
||
|
||
| صفحه | شورت‌کد |
|
||
|------|---------|
|
||
| `/my-account/` | `[ifnex_customer_dashboard]` |
|
||
| `/my-orders/` | `[ifnex_orders_list]` |
|
||
| `/new-order/` | `[ifnex_order_form]` |
|
||
| `/wallet/` | `[ifnex_wallet_charge]` |
|
||
| `/tracking/` | `[ifnex_tracking_form]` |
|
||
|
||
> 📖 برای راهنمای کامل استقرار روی سرور، [DEPLOYMENT_HANDOFF.md](DEPLOYMENT_HANDOFF.md) را ببینید. برای راهنمای ایمپورت نرخ‌ها، [RATE_IMPORTER.md](RATE_IMPORTER.md) را ببینید.
|
||
|
||
---
|
||
|
||
## 🛠️ استک فنی
|
||
|
||
### بک‌اند (Laravel)
|
||
|
||
| تکنولوژی | نسخه | کاربرد |
|
||
|-----------|-------|--------|
|
||
| Laravel | 11.x | فریمورک اصلی |
|
||
| PHP | 8.2+ | زبان برنامه‌نویسی |
|
||
| Filament | 3.3.x | پنل مدیریت ادمین |
|
||
| MySQL | 8+ | دیتابیس |
|
||
| Dompdf | Latest | تولید PDF |
|
||
| Laravel Excel | Latest | Import / Export |
|
||
| Sanctum | Latest | احراز هویت API |
|
||
| Morilog Jalali | 3.x | تاریخ شمسی |
|
||
| picqer/php-barcode | Latest | تولید بارکد |
|
||
| Spatie Permission | 6.x | مدیریت نقش‌ها |
|
||
|
||
### فرانت‌اند (WordPress)
|
||
|
||
| تکنولوژی | نسخه | کاربرد |
|
||
|-----------|-------|--------|
|
||
| WordPress | 7.1 | CMS |
|
||
| IFNEX Theme | Custom | قالب سفارشی |
|
||
| IFNEX Bridge | 2.1.0 | پلاگین ارتباطی |
|
||
| jQuery | 3.x | AJAX + DOM |
|
||
|
||
### زیرساخت
|
||
|
||
| سرویس | کاربرد |
|
||
|-------|--------|
|
||
| HestiaCP | پنل مدیریت سرور |
|
||
| Nginx | وب‌سرور |
|
||
| PHP-FPM | پردازش PHP |
|
||
| MySQL 8 | دیتابیس |
|
||
| Let's Encrypt | SSL رایگان |
|
||
| Git (Gitea) | مخزن کد |
|
||
|
||
---
|
||
|
||
## 📊 آمار پروژه
|
||
|
||
| معیار | مقدار |
|
||
|-------|-------|
|
||
| تعداد مایگریشن‌ها | ۶۲ |
|
||
| تعداد API endpoints | ۵۰+ |
|
||
| تعداد Filament Resources | ۱۹ |
|
||
| تعداد مدل‌ها | ۳۱ |
|
||
| تعداد شورت‌کدهای وردپرس | ۱۰+ |
|
||
| تعداد کشورها با پیش‌شماره | ۱۹۲ |
|
||
| رکوردهای تاریخی مهاجرت‌شده | ۳۹۵۰ |
|
||
| تعداد تست‌های Feature | ۸۲ |
|
||
| تعداد assertionها | ۲۲۰+ |
|
||
| خطوط کد (تخمینی) | ۲۵۰۰۰+ |
|
||
|
||
---
|
||
|
||
## 🧪 تست
|
||
|
||
### تست‌های خودکار (Feature Tests)
|
||
|
||
```bash
|
||
cd 04_Laravel
|
||
php artisan test
|
||
# انتظار: 82 passed, 220+ assertions
|
||
```
|
||
|
||
### تست E2E Post-Deploy (فاز ۳.۱۱)
|
||
|
||
```bash
|
||
php artisan ifnex:preflight # بررسی سخت‌سازی محیط قبل از migrate
|
||
php artisan ifnex:smoke-test # تست E2E بعد از deploy (DB، داده‌ها، API endpoints)
|
||
```
|
||
|
||
### تست UAT کارفرما
|
||
|
||
برای چک‌لیست ۴۳ موردی تست دستی توسط کارفرما، [UAT-3.11.md](UAT-3.11.md) را ببینید.
|
||
|
||
---
|
||
|
||
## 📚 مستندات
|
||
|
||
| فایل | محتوا | اولویت |
|
||
|------|-------|---------|
|
||
| [CLIENT_DELIVERY.md](CLIENT_DELIVERY.md) | **چک‌لیست وضعیت تحویل مشتری (منبع اصلی وضعیت)** | ⭐⭐⭐ |
|
||
| [UAT-3.11.md](UAT-3.11.md) | چک‌لیست ۴۳ موردی UAT نهایی کارفرما (فاز ۳.۱۱) + فرم امضای تحویل | ⭐⭐⭐ |
|
||
| [DEPLOYMENT_HANDOFF.md](DEPLOYMENT_HANDOFF.md) | راهنمای استقرار برای تیم IT کارفرما | ⭐⭐⭐ |
|
||
| [AGENT.md](AGENT.md) | راهنمای ایجنت، مفاهیم کلیدی و خط قرمزها | ⭐⭐⭐ |
|
||
| [01_Documents/IFNEX_Roadmap.md](01_Documents/IFNEX_Roadmap.md) | نقشهٔ راه فازی (۰ تا ۳.۱۱ + آینده ۴/۵) | ⭐⭐ |
|
||
| [01_Documents/IFNEX_File_Map.md](01_Documents/IFNEX_File_Map.md) | نقشهٔ فایل‌های پروژه | ⭐⭐ |
|
||
| [01_Documents/IFNEX_Pro_Backlog.md](01_Documents/IFNEX_Pro_Backlog.md) | فیچرهای نگه‌داشته‌شده برای نسخه Pro | ⭐⭐ |
|
||
| [RATE_IMPORTER.md](RATE_IMPORTER.md) | راهنمای ایمپورت نرخ‌ها (سیستم ۴-رُبعی) | ⭐⭐ |
|
||
| [04_Laravel/README.md](04_Laravel/README.md) | راهنمای بک‌اند | ⭐⭐ |
|
||
| [01_Documents/IFNEX_Commercial_Model.md](01_Documents/IFNEX_Commercial_Model.md) | مدل تجاری و پلن‌های فروش (آینده) | ⭐ |
|
||
| [01_Documents/IFNEX_I18N_Strategy.md](01_Documents/IFNEX_I18N_Strategy.md) | استراتژی چندزبانه (موکول به زمان دیپلوی) | ⭐ |
|
||
|
||
---
|
||
|
||
## 🚀 مراحل بعدی
|
||
|
||
> 📌 **فهرست دقیق و به‌روزِ وضعیت تحویل در [CLIENT_DELIVERY.md](CLIENT_DELIVERY.md) و چک‌لیست UAT در [UAT-3.11.md](UAT-3.11.md) نگهداری می‌شود** — این بخش فقط نمای کلی است.
|
||
|
||
### باقی‌ماندهٔ واقعی (post-3.11)
|
||
|
||
موارد زیر تنهای چیزی هستند که قبل از انتشار رسمی Productization باقی‌مانده‌اند:
|
||
|
||
- ⏳ **i18n (چندزبانه)** — موکول به زمان دیپلوی (Polylang + ترجمه‌های .po/.mo)
|
||
- ⏳ **پلاگین ماژولار SMS** — منتظر تحویل پنل SMS مشتری
|
||
- ⏳ **سند پیشنهادی سیستم مالی** (درخواست ۱۳ کارفرما) — موکول به آینده
|
||
- ⏳ **تأیید نهایی UAT کارفرما** — چک‌لیست `UAT-3.11.md` آمادهٔ اجرا
|
||
|
||
### فاز ۴ (آینده) — سیستم نمایندگی 📋
|
||
|
||
> ⚠️ هیچ‌کدام از موارد زیر پیاده‌سازی نشده‌اند.
|
||
|
||
- مدل نمایندگی کامل با کمیسیون و پنل جداگانه
|
||
- طرح مطالعاتی آماده — منتظر تأیید کارفرما
|
||
|
||
### فاز ۵ (آینده) — تجاری‌سازی 📋
|
||
|
||
> ⚠️ هیچ‌کدام از موارد زیر پیاده‌سازی نشده‌اند.
|
||
|
||
- مدل پولی چندلایه: Starter ($299/سال) / Business ($899/سال) / Enterprise ($1999/سال)
|
||
- فرم‌ساز Drag & Drop (Enterprise-tier)
|
||
- White-label branding (Enterprise-tier)
|
||
- API Gateway برای توسعه‌دهندگان (Enterprise-tier)
|
||
- سیستم لایسنس با Domain Lock + Feature Flags
|
||
- بروزرسانی خودکار از گیت
|
||
- اتصال به APIهای ترکینگ زنده (TrackingMore / 17track)
|
||
- مستندات API (OpenAPI / Swagger)
|
||
- راهنمای اپراتور (Operator Manual)
|
||
- اپلیکیشن موبایل (احتمالی)
|
||
- سایت فروش + صفحهٔ قیمت‌گذاری + دمو آنلاین
|
||
|
||
---
|
||
|
||
## 📞 تماس
|
||
|
||
| مورد | مقدار |
|
||
|------|------|
|
||
| توسعه‌دهنده | Kazem Alghasi |
|
||
| شرکت | VernaSoft Group |
|
||
| ایمیل | kazem@vernasoft.group |
|
||
| مخزن | [git.vernahost.ir/gitmodir110/ifnex](https://www.git.vernahost.ir/gitmodir110/ifnex) |
|
||
| سرور Laravel | `https://system.ifnex.ir` |
|
||
| سرور WordPress | `https://ifnex.ir` |
|
||
|
||
---
|
||
|
||
<div align="center">
|
||
|
||
📜 لایسنس
|
||
|
||
© 2026 VernaSoft Group. تمام حقوق محفوظ است.
|
||
|
||
این پروژه طبق سفارش IFNEX و مالکیت آن برای گروه ورناسافت است و کپی یا استفادهٔ غیرمجاز ممنوع می‌باشد.
|
||
|
||
</div>
|