e1c4385a9c
Implement a comprehensive financial management suite within the Filament admin panel, including new resources for payments and discount codes, along with a financial dashboard. - feat(ui): add Filament Dashboard with finance overview and transaction widgets - feat(ui): implement PaymentResource for monitoring gateway transactions - feat(ui): complete DiscountCodeResource with full CRUD and filtering - feat(wallet): add automatic wallet creation on balance retrieval - fix(wallet): resolve null handling in isFrozen() and balance viewing - fix(db): correct enum type from 'percent' to 'percentage' in discount_codes migration - fix(api): update pricing calculation endpoint to /api/v1/calculate - test: add 21 new feature and service tests covering wallet, payment, and discount logic - chore: remove obsolete PaymentGatewayService and update project status
558 lines
31 KiB
Markdown
558 lines
31 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 قدیمی (استفاده نمیشد)
|
||
|
||
---
|
||
|
||
## 🚫 خط قرمزها (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` پاسخ آن نبود، از کاربر بپرس — حدس نزن.
|
||
|
||
---
|
||
|
||
### کارهای انجامشده اخیر (آگوست ۲۰۲۶)
|
||
|
||
|
||
#### ۲۰۲۶-۰۸-۰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
|
||
|
||
|
||
|
||
#### ۲۰۲۶-۰۸-۰۷
|
||
[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 - تغییر از `*` به دامنه مشخص
|
||
|
||
|
||
|
||
© 2026 VernaSoft Group. Internal use only.
|