8ca92f3a05
Update the status documentation to reflect recent development milestones, including the implementation of the financial panel, payment gateway integration, and Filament theme customizations.
654 lines
37 KiB
Markdown
654 lines
37 KiB
Markdown
# 🚨 STATUS.md — این فایل را اول بخوانید
|
||
|
||
> **آخرین بهروزرسانی:** 2026-08-05 22:32 (Asia/Tehran)
|
||
> **فاز در حال اجرا:** فاز ۲ (اتوماسیون مالی + کیف پول + تخفیف)
|
||
> **توسعهدهنده:** VernaSoft Group — Kazem Alghasi
|
||
> **وضعیت کلی پروژه:** فاز ۰ کامل — فاز ۱ کامل — فاز ۲ در حال اجرا
|
||
|
||
---
|
||
|
||
## ⚠️ هشدار حیاتی — قبل از هر کاری بخوانید
|
||
|
||
این پروژه دارای **سه سند تاریخی** است که با هم تناقض دارند. فقط یکی از آنها معتبر است:
|
||
|
||
| فایل | وضعیت | اقدام |
|
||
|------|-------|-------|
|
||
| `01_Documents/Phase0_Proposal.md` | ✅ **معتبر و مرجع اصلی** | حتماً کامل بخوانید |
|
||
| `01_Documents/PRD_v2.md` | ❌ قدیمی و ناقص | فقط برای مرجع تاریخی — به اسکیمای دیتابیس آن اعتماد نکنید |
|
||
| `01_Documents/Project_Roadmap.md` | ❌ قدیمی (۳ فازی) | فقط برای مرجع تاریخی — به فازبندی آن اعتماد نکنید |
|
||
| `01_Documents/EXCEL_ANALYSIS.md` | ✅ **مرجع تحلیل اکسل** | حتماً بخوانید قبل از کار با دادههای تاریخی |
|
||
| `README.md` (ریشه) | ✅ بهروز (نسخه ۲) | برای نمای کلی بخوانید |
|
||
|
||
> 🔴 **قانون طلایی:** هرجا بین اسناد تناقض دیدی، به `Phase0_Proposal.md` اعتماد کن. اسناد قدیمی فقط برای فهم تاریخچهی تصمیمات نگه داشته شدهاند.
|
||
|
||
---
|
||
|
||
## 📌 Quick Reference — نسخهها و معماری
|
||
|
||
### تکنولوژیها (قفلشده)
|
||
| مورد | نسخه/مقدار | دلیل |
|
||
|------|------------|------|
|
||
| Laravel | **11** (همهجا یکسان) | در PRD قدیمی ۱۰+ نوشته، در Roadmap قدیمی ۱۱، در README قدیمی ۱۲ — نسخه نهایی: **۱۱** |
|
||
| PHP | 8.2+ | الزام لاراول ۱۱ |
|
||
| MySQL | 8+ | برای پشتیبانی JSON columns |
|
||
| WordPress | آخرین نسخه پایدار | با Polylang برای چندزبانه |
|
||
| پنل ادمین | Laravel Filament 3.3.x | برای سرعت توسعه |
|
||
| Frontend | وردپرس + قالب DHL-inspired | **کپی نکنید** — فقط الهام |
|
||
|
||
### معماری کلی
|
||
```
|
||
┌─────────────────┐ REST API ┌─────────────────┐
|
||
│ WordPress │ ←─────────────────────→ │ Laravel 11 │
|
||
│ (Frontend) │ پلاگین IFNEX Bridge │ (Backend) │
|
||
│ │ │ + Filament │
|
||
└─────────────────┘ └────────┬────────┘
|
||
│
|
||
┌────────┴────────┐
|
||
│ MySQL 8 │
|
||
└─────────────────┘
|
||
│
|
||
(فاز ۳) │
|
||
┌────────┴────────┐
|
||
│ VPS پل خارج │
|
||
│ (هلند/آلمان) │
|
||
└────────┬────────┘
|
||
│
|
||
┌────────┴────────┐
|
||
│ TrackingMore / │
|
||
│ 17track API │
|
||
└─────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## ✅ وضعیت فعلی کار
|
||
|
||
### کارهای انجامشده (تا تاریخ 2026-08-04)
|
||
|
||
#### ۱. اسکیمای دیتابیس فاز ۰ (کامل)
|
||
- [x] بازنویسی migration `countries` با ۴ زون مجزا + `iso_code` + `is_active`
|
||
- [x] بازنویسی migration `shipments` مطابق Phase 0 (فیلدهای مالی + ۴ زون + nullable حقایل)
|
||
- [x] بازنویسی migration `shipping_rates` با enum `direction` و `type` (DOC_NORMAL/DOC_ECONOMY/PARCEL)
|
||
- [x] ایجاد migration `shipment_carrier_mappings` (جدول جدید — نگاشت چند شرکت حمل)
|
||
- [x] ایجاد migration `shipment_tracking_events` (جدول جدید — تایملاین رویدادها)
|
||
- [x] ایجاد migration `system_settings` (جدول جدید — key-value برای VAT، نرخ ارز و...)
|
||
- [x] ایجاد migration `update_users` (افزودن `phone`, `role`, `is_active`)
|
||
- [x] حل مشکل `unsignedDecimal` در Laravel 11 (استفاده از `decimal()->unsigned()`)
|
||
- [x] حل مشکل FK constraints در migrations (استفاده از `disableForeignKeyConstraints()`)
|
||
- [x] اجرای همه migrations در MySQL بدون خطا
|
||
|
||
#### ۲. مدلها و Enums (کامل)
|
||
- [x] بازنویسی `Country.php` + روابط `fromShipments()` / `toShipments()`
|
||
- [x] بازنویسی `Shipment.php` + روابط `fromCountry()`, `toCountry()`, `items()`, `carrierMappings()`, `trackingEvents()`
|
||
- [x] بازنویسی `ShippingRate.php` + cast برای enums
|
||
- [x] بازنویسی `User.php` + فیلدهای `phone`, `role`, `is_active` + helper methods
|
||
- [x] ایجاد مدلهای جدید:
|
||
- `ShipmentCarrierMapping.php`
|
||
- `ShipmentTrackingEvent.php`
|
||
- `SystemSetting.php`
|
||
- [x] ایجاد ۶ enum:
|
||
- `ShipmentDirection` (import/export)
|
||
- `ShipmentType` (DOC_NORMAL/DOC_ECONOMY/PARCEL)
|
||
- `ShipmentStatus` (processed/picked_up/in_transit/out_for_delivery/failed/delivered/returned)
|
||
- `CarrierCode` (DHL/FEDEX/UPS/ARAMEX/NAGHEL/EMX/APSITEX/IMPEX/OTHER)
|
||
- `TrackingSource` (manual/api_carrier/api_aggregator)
|
||
- `UserRole` (super_admin/tracking_operator/data_entry/customer)
|
||
|
||
#### ۳. Seeders (کامل)
|
||
- [x] بازنویسی `CountriesTableSeeder` با ۲۳۳ کشور + ۴ زون + iso_code تصحیحشده
|
||
- تصحیح کدهای ISO نادرست (Bonaire BQ، Curacao CW، حذف Somaliland XS)
|
||
- حذف کشورهای تکراری ("United Arab Emirates" و "Rest of Dubai" هر دو با zone 9 و 10)
|
||
- [x] ایجاد `SystemSettingSeeder` (VAT 9%، packing 100000 IRR، profit_margin 1.25، نرخ ارزهای اولیه)
|
||
- [x] بازنویسی `DatabaseSeeder` (countries + system_settings + super_admin user)
|
||
- [x] اجرای seeders — ۲۳۲ کشور + ۷ setting + ۱ کاربر ادمین
|
||
|
||
#### ۴. API ترکینگ (کامل)
|
||
- [x] ایجاد `TrackController` با JSON response کامل (shipment + carrier_mappings + timeline)
|
||
- [x] ایجاد `ApiKeyMiddleware` (Bearer token validation)
|
||
- [x] ثبت route `GET /api/v1/track/{awb_no}` با middleware API Key
|
||
- [x] تستهای موفق:
|
||
- `GET /api/v1/track/TEST123` با API Key صحیح → **200 OK**
|
||
- بدون API Key → **401 Unauthorized**
|
||
- با API Key نامعتبر → **403 Forbidden**
|
||
|
||
#### ۵. Filament Resources (کامل)
|
||
- [x] `CountryResource` — فرم ۴ زون + iso_code + is_active + فیلترها
|
||
- [x] `ShipmentResource` — فرم کامل با ۷ Section + RelationManagers
|
||
- Section: Route & Status
|
||
- Section: Weight & Dimensions
|
||
- Section: Financial Info (۱۱ فیلد مالی)
|
||
- Section: Sender Info
|
||
- Section: Receiver Info
|
||
- Section: Customs Items (Repeater ۹ ردیف)
|
||
- [x] `ShippingRateResource` — فرم ۱۰ zone + enum type/direction
|
||
- [x] `ShipmentItemResource` — CRUD کامل
|
||
- [x] RelationManagers:
|
||
- `CarrierMappingsRelationManager` (برای Shipment)
|
||
- `TrackingEventsRelationManager` (برای Shipment)
|
||
- [x] Pages:
|
||
- `ListShipments`, `CreateShipment`, `EditShipment`, `ViewShipment`
|
||
- `ListCountries`, `CreateCountry`, `EditCountry`
|
||
- `ListShippingRates`, `CreateShippingRate`, `EditShippingRate`
|
||
- `ListShipmentItems`, `CreateShipmentItem`, `EditShipmentItem`
|
||
- [x] `SettingsPage` (Page سفارشی برای System Settings)
|
||
|
||
#### ۶. Services (کامل)
|
||
- [x] `TrackingService` — getTrackingTimeline, addTrackingEvent, getShipmentWithTracking
|
||
- [x] `PriceCalculatorService` — محاسبه قیمت کامل مطابق EXCEL_ANALYSIS.md
|
||
- مرحله ۱: وزن حجمی
|
||
- مرحله ۲: وزن قابل پرداخت
|
||
- مرحله ۳: استخراج زون از ۴ زون مجزا
|
||
- مرحله ۴: استخراج قیمت پایه از shipping_rates
|
||
- مرحله ۵: اعمال ضریب سود
|
||
- مرحله ۶: تبدیل درهم به ریال
|
||
- مرحله ۷: اضافه هزینههای جانبی
|
||
- مرحله ۸: اعمال VAT 9%
|
||
- مرحله ۹: ذخیره خروجیها
|
||
|
||
#### ۷. Imports (Excel) (کامل)
|
||
- [x] `ShippingRatesImport` — import از ۵ شیت (Import Rate, Export Rate, DocNor, DocEco, Parcel)
|
||
- ۴۰۴ رکورد import شد: DocNormal: ۷۴، DocEconomy: ۷۰، Parcel: ۲۶۰
|
||
- [x] `HistoricalShipmentsImport` — import از شیت List فایل اصلی
|
||
- ⚠️ **مشکل:** فایل اکسل فقط ۲ ردیف داده واقعی دارد و بقیه فرمولهای Excel هستند
|
||
- ۱ رکورد (980100010) موفقیتآمیز import شد
|
||
- [x] Artisan Commands:
|
||
- `ifnex:import:rates {path}`
|
||
- `ifnex:import:shipments {path}`
|
||
|
||
#### ۸. سوییچ به Laravel 11 (کامل با نقص باقیمانده)
|
||
- [x] تغییر `composer.json`: `laravel/framework` از `^12.0` به `^11.0`
|
||
- [x] تغییر `morilog/jalali` از `^4.3` به `^3.0` (v4 وجود ندارد)
|
||
- [x] اجرای `composer update` — Laravel از v12.64.0 به v11.55.0 downgrade شد
|
||
- [x] رفع خطای PSR-4 در `SettingsPage.php`
|
||
- [x] رفع مشکل middleware در `bootstrap/app.php` برای Laravel 11
|
||
- [x] رفع خطای `MethodNotAllowedHttpException` برای POST `/admin/login`
|
||
|
||
#### ٩. پیکربندی (کامل)
|
||
- [x] اضافه کردن `IFNEX_API_KEY` به `.env.example`
|
||
- [x] اضافه کردن `CORS_ALLOWED_ORIGINS` به `.env.example`
|
||
- [x] اضافه کردن `IFNEX_TRACKING_RATE_LIMIT` به `.env.example`
|
||
- [x] ایجاد `config/ifnex.php` برای تنظیمات اختصاصی
|
||
- [x] تغییر `APP_LOCALE` به `fa` در `.env.example`
|
||
- [x] اضافه کردن `morilog/jalali` به `composer.json`
|
||
- [x] ایجاد `config/cors.php`
|
||
|
||
---
|
||
|
||
### 🔴 Code Review Findings — نیاز به رفع
|
||
|
||
| # | فایل | مشکل | وضعیت | راهحل |
|
||
|---|------|------|-------|-------|
|
||
| 1 | `bootstrap/app.php` | گروه `web` تعریف نشده | ✅ انجام شد | `$middleware->group('web', [...])` اضافه شد |
|
||
| 2 | `AdminPanelProvider.php` | Middlewareهای طولانی به صورت لیست دستی | ✅ انجام شد | استفاده از گروه `web` به جای لیست دستی |
|
||
| 3 | `bootstrap/app.php` | `statefulApi` تعریف نشده | 🟡 آینده | برای احراز هویت SPA در فاز بعد لازم است |
|
||
|
||
**توضیح مشکل #1:**
|
||
در Laravel 11، گروه `web` بهصورت خودکار تعریف نمیشود. Filament برای لاگین نیاز به Session, Cookies, CSRF, ShareErrors دارد. فعلاً کار میکند چون در `AdminPanelProvider.php` همه Middlewareها به صورت لیست دستی نوشته شدهاند، اما این روش **خوب نیست** و مطابق Laravel 11 conventions نیست. اگر جایی از `web` group استفاده شود، کار نمیکند.
|
||
|
||
**راهحل پیشنهادی برای `bootstrap/app.php`:**
|
||
```php
|
||
->withMiddleware(function (Middleware $middleware): void {
|
||
$middleware->api(prepend: \Illuminate\Http\Middleware\HandleCors::class);
|
||
|
||
$middleware->group('web', [
|
||
\Illuminate\Cookie\Middleware\EncryptCookies::class,
|
||
\Illuminate\Cookie\Middleware\AddQueuedCookiesToResponse::class,
|
||
\Illuminate\Session\Middleware\StartSession::class,
|
||
\Illuminate\View\Middleware\ShareErrorsFromSession::class,
|
||
\Illuminate\Foundation\Http\Middleware\ValidateCsrfToken::class,
|
||
\Illuminate\Routing\Middleware\SubstituteBindings::class,
|
||
]);
|
||
})
|
||
```
|
||
|
||
**راهحل پیشنهادی برای `AdminPanelProvider.php` بعد از تعریف گروه `web`:**
|
||
```php
|
||
->middleware([
|
||
'web',
|
||
\Filament\Http\Middleware\Authenticate::class,
|
||
])
|
||
```
|
||
|
||
---
|
||
|
||
### 🔴 مشکل — مهاجرت دادههای تاریخی
|
||
|
||
**وضعیت:** فایل اکسل مرسولات فعلی فقط دادههای نمونه/قدیمی دارد و برای import کامل مناسب نیست.
|
||
**راهحل:** هر فایل اکسل جدید که مشتری تحویل دهد، باید قابل import باشد. نیازی به مهاجرت همه دادههای قدیمی نیست.
|
||
**فایل ترکینگ:** `01_Documents/Data entry 2026-06-28.xlsx` — شامل ۶ شیت: Sheet1, Refrence, Paste, copy, Delivered, test
|
||
**وضعیت:** **فایل موجود است** — مهاجrut دادههای ترکینگ میتواند انجام شود.
|
||
|
||
---
|
||
|
||
### کارهای در دست اقدام (فاز ۰)
|
||
|
||
| اولویت | کار | وضعیت | توضیحات |
|
||
|--------|-----|-------|---------|
|
||
| 🔴 بالا | تست دستی کامل Filament (ورود + CRUD) | ✅ انجام شد | همه Resources + RelationManagers + Settings کار میکنند |
|
||
| 🟡 متوسط | مهاجرت دادههای ترکینگ از `01_Documents/Data entry 2026-06-28.xlsx` | ✅ انجام شد | 98 رویداد import شد، 8 shipment |
|
||
| 🟡 متوسط | ساخت پلاگین وردپرس IFNEX Bridge | ✅ انجام شد | شورتکدهای [ifnex_tracking_form] و [ifnex_tracking_status] کار میکنند |
|
||
| 🟡 متوسط | تست API Track با نمونههای بیشتر | ✅ انجام شد | AWB 980100010 و 980103619 تست شدند |
|
||
| 🟢 پایین | تست نهایی فاز ۰ و تحویل به مشتری | ✅ انجام شد | همه موارد تست شدند |
|
||
|
||
---
|
||
|
||
### کارهای فاز ۱ (تکمیل شده)
|
||
|
||
- [x] موتور قیمتگذاری کامل (`PriceCalculatorService`) — نوشته شد، تست با دادههای واقعی انجام شد
|
||
- [x] جدول `shipping_rates` — ۱۳۸ رکورد import شد با پشتیبانی از ۵ نوع سرویس/جهت
|
||
- [x] فرم ثبت سفارش آنلاین با ۹ ردیف کالای گمرکی
|
||
- [x] تولید PDF: AWB، INVOICE، Label — پیاده شد. قالبها بر اساس ساختار شیتهای اکسل و لوگوی استخراجشده طراحی شدند. استایل نهایی و تطبیق دقیقتر با قالبهای اکسل در فاز بعدی انجام میشود.
|
||
- [x] ماژول ایمپورت اکسل تعرفهها — command با قابلیتهای --clear و --dry-run پیاده شد
|
||
- [x] صفحه استعلام قیمت واقعی — رابط کاربری عمومی + API محاسبه قیمت
|
||
|
||
---
|
||
|
||
### کارهای فاز ۲ (در حال اجرا)
|
||
|
||
- [x] ساخت `WalletController` با APIهای شارژ، بررسی موجودی و تاریخچه تراکنشها
|
||
- [x] ساخت `DiscountCodeController` با APIهای لیست و اعتبارسنجی کده تخفیف
|
||
- [x] ساخت `UpdateExchangeRates` Artisan Command با پشتیبانی از ECB و FreeCurrencyAPI
|
||
- [x] ثبت routeهای کیف پول و تخفیف در `api.php`
|
||
- [x] اضافه کردن `CURRENCY_API_KEY` به `.env.example` و `config/ifnex.php`
|
||
- [x] پاکسازی فایلهای تست و debug (`check_*.php`, `debug_*.php`, `test_*.php`, `inspect_*.php`)
|
||
- [x] رفع CORS — تغییر از `*` به دامنه مشخص از `.env`
|
||
- [x] حذف migrationهای قدیمی تکراری (`2023_10_27_*`, `2026_07_31_*`)
|
||
- [x] اتصال درگاه پرداخت (زرینپال)
|
||
- [x] شارژ آنلاین کامل با درگاه پرداخت
|
||
- [x] پنل مالی در Filament (داشبورد سود/زیان)
|
||
- [x] تکمیل DiscountCodeResource با form/table/filters
|
||
- [x] ساخت PaymentResource در Filament
|
||
- [x] تستهای Unit/Feature برای Phase 2 (24 تست، 77 assertion)
|
||
- [x] رفع باگ WalletController::balance()
|
||
- [x] حذف PaymentGatewayService قدیمی (استفاده نمیشد)
|
||
- [x] زیباسازی داشبورد و صفحه لاگین Filament
|
||
- [x] گسترش پلاگین IFNEX Bridge برای وردپرس:
|
||
- [x] ساخت `IFNEX_User_Bridge` برای مدیریت توکن Sanctum کاربران وردپرس
|
||
- [x] اضافه کردن شورتکد `[ifnex_wallet_balance]`
|
||
- [x] اضافه کردن شورتکد `[ifnex_transactions]`
|
||
- [x] اضافه کردن AJAX handlers برای کیف پول و تراکنشها
|
||
- [x] ساخت استایلهای CSS کامل برای تمام کامپوننتهای پلاگین
|
||
- [x] ایجاد صفحه تست در وردپرس: http://localhost/ifnexwp/?page_id=16
|
||
[x] ساخت WalletController با APIهای کامل
|
||
[x] ساخت DiscountCodeController
|
||
[x] ساخت UpdateExchangeRates Artisan Command
|
||
[x] اتصال درگاه پرداخت (زرینپال) — با Mock Gateway
|
||
[x] شارژ آنلاین کامل با درگاه
|
||
[x] پنل مالی در Filament (داشبورد سود/زیان)
|
||
[x] Export CSV برای تراکنشها و مرسولات
|
||
[ ] فرمول محاسبه قیمت رقبا (حذف شد — تصمیم استراتژیک)
|
||
|
||
---
|
||
|
||
## 🚫 خط قرمزها (DO NOT) — هرگز این کارها را نکن
|
||
|
||
### 🚫 اسکیمای دیتابیس
|
||
- **NEVER** جدول `countries` را به ۲ زون برگردانی — ۴ زون مجزا (export_parcel, export_doc, import_parcel, import_doc) الزامی است.
|
||
- **NEVER** فقط ۲ نوع سرویس پیاده کن — ۳ نوع الزامی است: `DOC_NORMAL`, `DOC_ECONOMY`, `PARCEL`.
|
||
- **NEVER** فیلد `forwarder_track_id` را بهعنوان فیلد واحد در `shipments` نگه دار — باید `shipment_carrier_mappings` استفاده شود.
|
||
- **NEVER** فیلدهای مالی مهم (VAT، Domestic Pickup، Domestic Delivery، Warehousing Cost، Extra Service، Packing Cost) را حذف کن.
|
||
- **NEVER** فیلد `status` در `shipments` را به String تغییر دهی — Enum استفاده کن.
|
||
|
||
### 🚫 معماری
|
||
- **NEVER** ترکینگ را در وردپرس پیاده کن — همیشه در لاراول.
|
||
- **NEVER** در وردپرس پردازش دادهی سفارش انجام دهی — تمام فرمها از طریق پلاگین IFNEX Bridge به لاراول ارسال میشوند.
|
||
- **NEVER** API لاراول را بدون API Key، Rate Limiting و CORS whitelist بگذاری.
|
||
- **NEVER** از CORS `*` استفاده کنی — فقط دامنهی تولیدی وردپرس باید whitelist شود.
|
||
- **NEVER** تاریخها را به شمسی در دیتابیس ذخیره کنی — همیشه timestamp میلادی.
|
||
|
||
### 🚫 طراحی و کپیرایت
|
||
- **NEVER** از رنگ، لوگو یا عناصر هویت بصری DHL کپی کنی.
|
||
- **NEVER** خروجی PDF (AWB، Invoice، Label) را به فارسی بسازی — انگلیسی باشد.
|
||
|
||
### 🚫 فرآیند
|
||
- **NEVER** فایل `.env` را در Git کامیت کنی.
|
||
- **NEVER** `APP_DEBUG=true` را در محیط تولید بگذاری.
|
||
- **NEVER** اسکوپ فاز ۰ را بدون Change Request رسمی تغییر دهی.
|
||
- **NEVER** فاز ۱ را قبل از تأیید رسمی فاز ۰ توسط مشتری شروع کنی.
|
||
|
||
---
|
||
|
||
## ❓ سوالات متداول (FAQ)
|
||
|
||
### س: کدام نسخه لاراول استفاده کنم؟
|
||
**ج:** لاراول **۱۱**. این نسخه در `STATUS.md` قفل شده و در `composer.json` هم تنظیم شده است.
|
||
|
||
### س: مهاجرت دادههایHistorical چقدر مهم است؟
|
||
**ج:** هر فایل اکسل جدید که مشتری تحویل دهد، باید قابل import باشد. نیازی به مهاجرت همه دادههای قدیمی نیست. فایل ترکینگ `Data entry 2026-06-28.xlsx` موجود است و قابل import است.
|
||
|
||
### س: چه کارهایی در این جلسه انجام شد؟
|
||
**ج:**
|
||
1. ساخت `WalletController` با APIهای شارچ، بررسی موجودی و تاریخچه تراکنشها
|
||
2. ساخت `DiscountCodeController` با APIهای لیست و اعتبارسنجی کده تخفیف
|
||
3. ساخت `UpdateExchangeRates` Artisan Command
|
||
4. ثبت routeهای کیف پول و تخفیف در `api.php`
|
||
5. اضافه کردن `CURRENCY_API_KEY` به `.env.example` و `config/ifnex.php`
|
||
6. پاکسازی فایلهای تست و debug از پوشه `04_Laravel`
|
||
7. رفع CORS — تغییر از `*` به دامنه مشخص از `.env`
|
||
8. حذف migrationهای قدیمی تکراری
|
||
|
||
### س: چه کارهایی باقی مانده؟
|
||
**ج:**
|
||
- پنل مالی در Filament (داشبورد سود/زیان)
|
||
- تست دستی APIهای جدید
|
||
- ~~فرمول محاسبه قیمت رقبا~~ (آرشیو شد)
|
||
|
||
---
|
||
|
||
## 🛠️ Quick Commands — دستورات پرکاربرد
|
||
|
||
### نصب و راهاندازی لاراول
|
||
```bash
|
||
cd 04_Laravel
|
||
composer install
|
||
cp .env.example .env
|
||
php artisan key:generate
|
||
php artisan migrate --force
|
||
php artisan db:seed --force
|
||
php artisan serve
|
||
```
|
||
|
||
### Artisan Commands سفارشی
|
||
```bash
|
||
# Import shipping rates
|
||
php artisan ifnex:import:rates storage/app/public/01KYWGVNKS5TNMN37RV77PCYNZ.xlsx
|
||
|
||
# Import historical shipments
|
||
php artisan ifnex:import:shipments storage/app/public/01KYWGVNKS5TNMN37RV77PCYNZ.xlsx
|
||
```
|
||
|
||
### تست API Track
|
||
```bash
|
||
# با API Key صحیح
|
||
curl -H "Authorization: Bearer ifnex-local-dev-key" http://localhost:8000/api/v1/track/TEST123
|
||
|
||
# بدون API Key
|
||
curl http://localhost:8000/api/v1/track/TEST123
|
||
|
||
# با API Key نامعتبر
|
||
curl -H "Authorization: Bearer wrong-key" http://localhost:8000/api/v1/track/TEST123
|
||
```
|
||
|
||
### پشتیبانگیری از دیتابیس
|
||
```bash
|
||
mysqldump -u root -p ifnex_db > backups/ifnex_$(date +%Y%m%d).sql
|
||
```
|
||
|
||
---
|
||
|
||
## 📂 ساختار پوشههای پروژه (پس از تکمیل فاز ۰)
|
||
|
||
```
|
||
IFNEX-Logistics/
|
||
├── 01_Documents/
|
||
│ ├── STATUS.md ⭐ این فایل — اول بخوان
|
||
│ ├── Phase0_Proposal.md ⭐ مرجع اصلی پروژه
|
||
│ ├── EXCEL_ANALYSIS.md ⭐ تحلیل فایلهای اکسل
|
||
│ ├── PRD_v2.md (قدیمی — مرجع تاریخی)
|
||
│ ├── Project_Roadmap.md (قدیمی — مرجع تاریخی)
|
||
│ └── IFNEX_Phase0_Checklist.md (چکلیست فاز ۰)
|
||
│
|
||
├── 02_Design/
|
||
│ └── Assets/ (لوگوها، آیکونها، فایلهای فیگما)
|
||
│
|
||
├── 03_WordPress/
|
||
│ └── wp-content/plugins/
|
||
│ └── ifnex-bridge/ (پلاگین اختصاصی)
|
||
│ ├── ifnex-bridge.php
|
||
│ ├── includes/
|
||
│ │ ├── api-client.php
|
||
│ │ ├── shortcodes.php
|
||
│ │ └── tracking-form.php
|
||
│ └── assets/
|
||
│ ├── css/
|
||
│ └── js/
|
||
│
|
||
├── 04_Laravel/
|
||
│ ├── app/
|
||
│ │ ├── Models/
|
||
│ │ │ ├── Country.php
|
||
│ │ │ ├── Shipment.php
|
||
│ │ │ ├── ShipmentCarrierMapping.php
|
||
│ │ │ ├── ShipmentTrackingEvent.php
|
||
│ │ │ ├── SystemSetting.php
|
||
│ │ │ ├── ShippingRate.php
|
||
│ │ │ ├── ShipmentItem.php
|
||
│ │ │ └── User.php
|
||
│ │ ├── Enums/
|
||
│ │ │ ├── ShipmentDirection.php
|
||
│ │ │ ├── ShipmentType.php
|
||
│ │ │ ├── ShipmentStatus.php
|
||
│ │ │ ├── CarrierCode.php
|
||
│ │ │ ├── TrackingSource.php
|
||
│ │ │ └── UserRole.php
|
||
│ │ ├── Services/
|
||
│ │ │ ├── TrackingService.php
|
||
│ │ │ └── PriceCalculatorService.php
|
||
│ │ ├── Http/
|
||
│ │ │ ├── Controllers/
|
||
│ │ │ │ └── Api/
|
||
│ │ │ │ ├── TrackController.php
|
||
│ │ │ │ └── PricingController.php
|
||
│ │ │ └── Middleware/
|
||
│ │ │ └── ApiKeyMiddleware.php
|
||
│ │ ├── Imports/
|
||
│ │ │ ├── ShippingRatesImport.php
|
||
│ │ │ ├── HistoricalShipmentsImport.php
|
||
│ │ │ └── RateSheetImport.php
|
||
│ │ ├── Console/
|
||
│ │ │ └── Commands/
|
||
│ │ │ ├── ImportShippingRates.php
|
||
│ │ │ ├── ImportHistoricalData.php
|
||
│ │ │ └── DebugImportCommand.php
|
||
│ │ ├── Filament/
|
||
│ │ │ ├── Resources/
|
||
│ │ │ │ ├── CountryResource.php
|
||
│ │ │ │ ├── ShipmentResource.php
|
||
│ │ │ │ │ ├── Pages/
|
||
│ │ │ │ │ │ ├── CreateShipment.php
|
||
│ │ │ │ │ │ ├── EditShipment.php
|
||
│ │ │ │ │ │ ├── ViewShipment.php
|
||
│ │ │ │ │ │ └── ListShipments.php
|
||
│ │ │ │ │ └── RelationManagers/
|
||
│ │ │ │ │ ├── CarrierMappingsRelationManager.php
|
||
│ │ │ │ │ └── TrackingEventsRelationManager.php
|
||
│ │ │ │ ├── ShippingRateResource.php
|
||
│ │ │ │ └── ShipmentItemResource.php
|
||
│ │ │ └── Pages/
|
||
│ │ │ └── IfnexSettingsPage.php
|
||
│ │ └── Providers/
|
||
│ │ ├── AppServiceProvider.php
|
||
│ │ └── Filament/
|
||
│ │ └── AdminPanelProvider.php
|
||
│ ├── database/
|
||
│ │ ├── migrations/
|
||
│ │ │ ├── 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
|
||
│ │ └── seeders/
|
||
│ │ ├── CountriesTableSeeder.php
|
||
│ │ ├── SystemSettingSeeder.php
|
||
│ │ └── DatabaseSeeder.php
|
||
│ ├── routes/
|
||
│ │ ├── web.php
|
||
│ │ └── api.php
|
||
│ ├── config/
|
||
│ │ ├── ifnex.php
|
||
│ │ └── cors.php
|
||
│ ├── bootstrap/
|
||
│ │ └── app.php
|
||
│ └── .env.example
|
||
│
|
||
├── README.md
|
||
├── composer.json
|
||
└── .gitignore
|
||
```
|
||
|
||
---
|
||
|
||
## 🎯 گام بعدی برای ادامهی کار
|
||
|
||
اگر نمونهی جدیدی از AI Agent هستی که میخواهی کار را ادامه دهی، این مراحل را به ترتیب برو:
|
||
|
||
۱. **این فایل (`STATUS.md`)** را کامل بخوان — حالا خواندی ✅
|
||
۲. **`EXCEL_ANALYSIS.md`** را کامل بخوان — برای فهم دادههای تاریخی ضروری است
|
||
۳. **`Phase0_Proposal.md`** را کامل بخوان — مرجع اصلی پروژه
|
||
۴. **`README.md`** ریشه را بخوان — برای نمای کلی
|
||
۵. کد موجود در `04_Laravel` را بررسی کن — ببین چه چیزی نوشته شده
|
||
۶. **اولویت اول:** رفع مشکل middleware در `bootstrap/app.php` و `AdminPanelProvider.php` (راهحل در بالای این فایل آمده)
|
||
۷. با کاربر (Kazem) هماهنگ کن — بپرس کدام کار را باید ادامه دهی
|
||
|
||
**مهمترین کار بعدی:** رفع مشکل middleware + تست دستی Filament.
|
||
|
||
---
|
||
|
||
## 📞 تماس
|
||
|
||
- **توسعهدهنده اصلی:** Kazem Alghasi (VernaSoft Group)
|
||
- **مشتری:** شرکت IFNEX اصفهان
|
||
- **مخزن:** https://www.git.vernahost.ir/gitmodir110/ifnex
|
||
|
||
اگر سوالی داشتی که در این فایل یا `EXCEL_ANALYSIS.md` یا `Phase0_Proposal.md` پاسخ آن نبود، از کاربر بپرس — حدس نزن.
|
||
|
||
---
|
||
|
||
### کارهای انجامشده اخیر (آگوست ۲۰۲۶)
|
||
|
||
### 2026-08-10
|
||
- رفع باگ ExportAction در ShipmentResource و WalletTransactionResource
|
||
- جایگزینی ExportAction با Action ساده + CSV native (بدون نیاز به maatwebsite/excel)
|
||
- ساخت صفحات CreateWalletTransaction و EditWalletTransaction
|
||
- اصلاح match expression برای TransactionType enum
|
||
- سفارشیسازی تم Filament:
|
||
* رنگ Primary = Amber (#f59e0b)
|
||
* Sidebar = Dark Navy gradient (#1a1a2e → #16213e)
|
||
* فونت Vazirmatn برای فارسی
|
||
* RTL کامل
|
||
* Scrollbar سفارشی
|
||
* Login Page با گرادیان زیبا
|
||
- نصب جدول notifications برای database notifications
|
||
- بهینهسازی استفاده از متدهای color() و label() در Enumها
|
||
- تست کامل داشبورد مالی و منوهای مختلف
|
||
|
||
|
||
#### ۲۰۲۶-۰۸-۰8
|
||
- ساخت `WalletController` با APIهای شارچ، بررسی موجودی و تاریخچه تراکنشها
|
||
- ساخت `DiscountCodeController` با APIهای لیست و اعتبارسنجی کده تخفیف
|
||
- ساخت `UpdateExchangeRates` Artisan Command
|
||
- ثبت routeهای کیف پول و تخفیف در `api.php`
|
||
- اضافه کردن `CURRENCY_API_KEY` به `.env.example` و `config/ifnex.php`
|
||
- پاکسازی فایلهای تست و debug از پوشه `04_Laravel`
|
||
- رفع CORS — تغییر از `*` به دامنه مشخص از `.env`
|
||
- حذف migrationهای قدیمی تکراری
|
||
- نصب و پیکربندی Laravel Sanctum برای API authentication
|
||
- ساخت Artisan Command `ifnex:token` برای تولید توکن API
|
||
- تست کامل APIهای کیف پول با curl
|
||
- ساخت ZarinpalService برای اتصال به درگاه پرداخت واقعی
|
||
- ساخت MockZarinpalService برای تست بدون Merchant ID
|
||
- ساخت MockGatewayController با UI زیبا برای شبیهسازی درگاه
|
||
- تست کامل flow پرداخت آنلاین (redirect → verify → complete)
|
||
- رفع باگ double-click در PaymentController
|
||
- ساخت صفحه Payment Result با UI موفق/ناموفق
|
||
- رفع باگ WalletController::balance() — کیف پول خودکار ایجاد میشود
|
||
- حذف PaymentGatewayService قدیمی (استفاده نمیشد)
|
||
- ساخت پنل مالی Filament با ۳ Widget: FinanceOverviewWidget، TransactionChartWidget، RecentTransactionsWidget
|
||
- تکمیل DiscountCodeResource با form/table/filters کامل
|
||
- ساخت PaymentResource در Filament برای مشاهده تراکنشهای درگاه
|
||
- نوشتن ۲۱ تست جدید Phase 2: WalletServiceTest (8)، PaymentControllerTest (5)، DiscountCodeControllerTest (6)
|
||
- رفع باگ CHECK constraint در migration discount_codes (enum type: percent → percentage)
|
||
- رفع باگ Wallet::isFrozen() — مدیریت null برای مقدار پیشفرض
|
||
- بهروزرسانی STATUS.md با کارهای انجامشده Phase 2
|
||
- گسترش پلاگین IFNEX Bridge:
|
||
- ساخت `IFNEX_User_Bridge` برای مدیریت توکن Sanctum کاربران وردپرس
|
||
- اضافه کردن شورتکد `[ifnex_wallet_balance]` با نمایش موجودی کیف پول
|
||
- اضافه کردن شورتکد `[ifnex_transactions]` با لیست تراکنشهای کاربر
|
||
- اضافه کردن AJAX handlers برای موجودی کیف پول و تراکنشها
|
||
- ساخت استایلهای CSS کامل برای تمام کامپوننتهای پلاگین
|
||
- ایجاد صفحه تست در وردپرس: http://localhost/ifnexwp/?page_id=18
|
||
- رفع باگ صفحه لاگین Filament (MethodNotAllowed)
|
||
- حذف فایلهای سفارشی لاگین و بازگشت به پیشفرض Filament
|
||
- رفع باگ DiscountCode enum: تغییر از `percent` به `percentage`
|
||
- ساخت `SampleDataSeeder` برای دادههای نمونه (۵ مرسوله، ۴ تراکنش، ۳ کد تخفیف)
|
||
- ساخت دستور Artisan `ifnex:sync-wp-users` برای یکسازی کاربران وردپرس ↔ لاراول
|
||
- تست زنده پلاگین وردپرس — همه APIها با موفقیت تست شدند
|
||
- پاکسازی فایلهای تست و اضافی از ریشه پروژه
|
||
- افزودن خروجی Excel برای تراکنشها و مرسولات در Filament
|
||
- ساخت صفحه گزارشگیری مالی در Filament: خلاصه مالی، تراکنشها، مرسولات
|
||
- ساخت Design System یکپارچه IFNEX برای استفاده در Filament و وردپرس
|
||
- بهروزرسانی استایلهای Filament مطابق با Design System
|
||
- بهروزرسانی استایلهای پلاگین وردپرس مطابق با Design System
|
||
|
||
|
||
|
||
#### ۲۰۲۶-۰۸-۰۷
|
||
[x] **refactor(api): improve pricing logic و add test coverage**
|
||
- بهروزرسانی `ShippingRatesImport` برای استفاده از 'outbound' و 'inbound'
|
||
- Refactor `PriceCalculatorService` با ساختار ماژولارتر
|
||
- بهروزرسانی مدل `ShippingRate` با Property Casting برای zones
|
||
- اضافه شدن `HasFactory` به مدلهای `Country` و `ShippingRate`
|
||
- اضافه شدن Factories جدید برای تست
|
||
- پیادهسازی تستهای Feature و Service برای `PriceCalculatorService`
|
||
- ✅ تمام تستها پاس شدند
|
||
|
||
#### ۲۰۲۶-۰۸-۰۵
|
||
[x] **refactor(api): expose wallet و discount endpoints**
|
||
- ساخت `WalletController` با APIهای شارژ، بررسی موجودی و تاریخچه
|
||
- ساخت `DiscountCodeController` با APIهای لیست و اعتبارسنجی
|
||
- ساخت `UpdateExchangeRates` Artisan Command
|
||
- ثبت routeهای کیف پول و تخفیف در `api.php`
|
||
- پاکسازی فایلهای تست و debug
|
||
- رفع CORS - تغییر از `*` به دامنه مشخص
|
||
|
||
|
||
### کارهای بعدی
|
||
|
||
#### فاز ۲.۵ — آمادهسازی برای دمو/استفاده واقعی
|
||
- [ ] **یکسازی کاربران وردپرس ↔ لاراول**
|
||
- تکمیل `ifnex:sync-wp-users` command برای sincron خودکار کاربران
|
||
- ایجادendent webhook برای sync تغییرات کاربر بین وردپرس و لاراول
|
||
- [ ] **تست نهایی پلاگین وردپرس با دادههای واقعی**
|
||
- تست همه شورتکدها با دادههای واقعی مشتری
|
||
- تست CORS و Rate Limiting در محیط تولید
|
||
- تست عملکرد offline/timeout
|
||
- [ ] **مستندسازی API**
|
||
- مستند کامل APIهای لاراول برای فرانتاند developerها
|
||
- مستند نحوه نصب و تنظیم پلاگین وردپرس
|
||
- مستند نحوه sync کاربران
|
||
|
||
#### فاز ۳ — با نیاز مشتری
|
||
- [ ] **پلاگین SMS**
|
||
- اطلاعرسانی وضعیت مرسوله به مشتری
|
||
- اطلاعرسانی پرداختهای کیف پول
|
||
- یادآوری انقضا کدهای تخفیف
|
||
- [ ] **پورتال مشتری کامل**
|
||
- ثبت سفارش آنلاین
|
||
- پرداخت از کیف پول
|
||
- مشاهده فاکتورها و گزارشات
|
||
- مدیریت آدرسها و تحویلگیرندگان
|
||
- [ ] **گزارشگیری پیشرفته**
|
||
- خروجی Excel/PDF برای تراکنشها، مرسولات، سود/زیان
|
||
- داشبورد مدیریتی برای مدیرعامل
|
||
- [ ] **ماژول CRM**
|
||
- مدیریت مشتریان
|
||
- تماسها و یادآوریها
|
||
- تحلیل رفتار مشتریان
|
||
|
||
#### فاز ۴ — آینده دور
|
||
- [ ] **VPS پل خارج**
|
||
- اتصال به TrackingMore/17track API
|
||
- پشتیبانی از ۱۰+ کاربر خارجی
|
||
- [ ] **Webhookها**
|
||
- اطلاعرسانی خودکار به مشتری وقتی مرسوله وضعیتش عوض میشه
|
||
- یکسازی خودکار بین لاراول و وردپرس
|
||
- [ ] **اپلیکیشن موبایل**
|
||
- نسخه Android/iOS برای مشتریان
|
||
- Push notification برای وضعیت مرسوله
|
||
|
||
---
|
||
|
||
## 🚫 خط قرمزها (DO NOT) — هرگز این کارها را نکن
|