Kazem Alghasi e032fceb34 docs(docs): update project documentation for phase 3.6 progress

Update all project documentation including README, Roadmap, Status,
and Agent guides to reflect the transition to Phase 3.6 (Client Meeting
Adjustments).

Key documentation updates:
- Documented the new order approval flow (pending_approval -> approved).
- Added details for shipment commitment forms and document download system.
- Included Kavenegar SMS integration and Audit Log implementation.
- Updated API endpoint references for new verification and commitment routes.
- Reflected increased project metrics (migrations, models, and API endpoints).
- Updated deployment notes regarding SMS configuration.

2026-09-11 21:53:05 +03:30

45 KiB

Raw Blame History

🚨 STATUS.md — این فایل را اول بخوانید

⚠️ به‌روزرسانی 2026-09-10: این سند تا 10 آگوست 2026 به‌روزرسانی شده و تاریخچه فازهای ۰ تا ۳ را پوشش می‌دهد. وضعیت جاری پروژه (فاز ۳.۵ ✅ و فاز ۳.۶ — اصلاحات جلسه کارفرما 🟡 ۸۰٪) در AGENT.md و IFNEX_Roadmap.md نگهداری می‌شود — برای وضعیت فعلی و کارهای باقی‌مانده آن دو سند را ببینید. بخش‌های پایین این فایل را به‌عنوان تاریخچه و مرجع خط قرمزها بخوانید.

آخرین به‌روزرسانی محتوا: 2026-08-10 13:08 (Asia/Tehran)
فاز در حال اجرا (فعلی): فاز ۳.۶ — اصلاحات جلسه کارفرما (تاریخچه: این سند تا فاز ۳ را ثبت کرده است)
توسعه‌دهنده: VernaSoft Group — Kazem Alghasi
وضعیت کلی پروژه: فاز ۰ کامل — فاز ۱ کامل — فاز ۲ کامل — فاز ۳ کامل — فاز ۳.۵ کامل — فاز ۳.۶ در حال تکمیل (۸۰٪)

⚠️ هشدار حیاتی — قبل از هر کاری بخوانید

این پروژه دارای سه سند تاریخی است که با هم تناقض دارند. فقط یکی از آن‌ها معتبر است:

فایل	وضعیت	اقدام
`01_Documents/Phase0_Proposal.md`	🗄️ حذف شده از مخزن	محتوای معتبر آن در `AGENT.md` و `IFNEX_Roadmap.md` ادغام شده است
`01_Documents/PRD_v2.md` (در archives)	❌ قدیمی و ناقص	فقط برای مرجع تاریخی — به اسکیمای دیتابیس آن اعتماد نکنید
`01_Documents/Project_Roadmap.md` (در archives)	❌ قدیمی (۳ فازی)	فقط برای مرجع تاریخی — به فازبندی آن اعتماد نکنید
`01_Documents/EXCEL_ANALYSIS.md`	✅ مرجع تحلیل اکسل	حتماً بخوانید قبل از کار با داده‌های تاریخی
`README.md` (ریشه)	✅ به‌روز	برای نمای کلی بخوانید
`AGENT.md` (ریشه)	✅ مرجع اصلی وضعیت و قراردادها	اول این را بخوانید

🔴 قانون طلایی: هرجا بین اسناد تناقض دیدی، به Phase0_Proposal.md اعتماد کن. اسناد قدیمی فقط برای فهم تاریخچه‌ی تصمیمات نگه داشته شده‌اند.

📌 Quick Reference — نسخه‌ها و معماری

تکنولوژی‌ها (قفل‌شده)

مورد	نسخه/مقدار	دلیل
Laravel	11 (همه‌جا یکسان)	در PRD قدیمی ۱۰+ نوشته، در Roadmap قدیمی ۱۱، در README قدیمی ۱۲ — نسخه نهایی: ۱۱
PHP	8.2+	الزام لاراول ۱۱
MySQL	8+	برای پشتیبانی JSON columns
WordPress	۷.۰.۳	با پوسته سفامشی IFNEX + Polylang برای چندزبانه
پنل ادمین	Laravel Filament 3.3.x	رنگ Navy gradient، فونت Vazirmatn، RTL کامل
Frontend	وردپرس + پوسته IFNEX	کپی نکنید — فقط الهام
Authentication	Laravel Sanctum	توکن‌های Bearer برای API مشتری
Permissions	spatie/laravel-permission	RBAC برای پنل ادمین
Payment Gateway	زرین‌پال (Zarinpal)	با Mock Gateway برای تست
Design System	IFNEX Design System	رنگ‌های برند، فاصله‌گذاری، تایپوگرافی یکپارچه

معماری کلی

┌─────────────────┐         REST API         ┌─────────────────┐
│   WordPress     │  ←─────────────────────→  │   Laravel 11    │
│  (Frontend)     │   پلاگین IFNEX Bridge     │   (Backend)     │
│                 │                           │  + Filament     │
└─────────────────┘                           └────────┬────────┘
                                                        │
                                               ┌────────┴────────┐
                                               │     MySQL 8     │
                                               └─────────────────┘
                                                        │
                                               (فاز ۳)  │
                                               ┌────────┴────────┐
                                               │  VPS پل خارج    │
                                               │  (هلند/آلمان)   │
                                               └────────┬────────┘
                                                        │
                                               ┌────────┴────────┐
                                               │ TrackingMore /  │
                                               │ 17track API     │
                                               └─────────────────┘

✅ وضعیت فعلی کار

کارهای انجام‌شده (تا تاریخ 2026-08-04)

۱. اسکیمای دیتابیس فاز ۰ (کامل)

بازنویسی migration countries با ۴ زون مجزا + iso_code + is_active
بازنویسی migration shipments مطابق Phase 0 (فیلدهای مالی + ۴ زون + nullable حقایل)
بازنویسی migration shipping_rates با enum direction و type (DOC_NORMAL/DOC_ECONOMY/PARCEL)
ایجاد migration shipment_carrier_mappings (جدول جدید — نگاشت چند شرکت حمل)
ایجاد migration shipment_tracking_events (جدول جدید — تایم‌لاین رویدادها)
ایجاد migration system_settings (جدول جدید — key-value برای VAT، نرخ ارز و...)
ایجاد migration update_users (افزودن phone, role, is_active)
ایجاد migration shipment_items (جدول جدید — اقلام گمرکی)
حل مشکل unsignedDecimal در Laravel 11 (استفاده از decimal()->unsigned())
حل مشکل FK constraints در migrations (استفاده از disableForeignKeyConstraints())
اجرای همه migrations در MySQL بدون خطا

۲. مدل‌ها و Enums (کامل)

بازنویسی Country.php + روابط fromShipments() / toShipments()
بازنویسی Shipment.php + روابط fromCountry(), toCountry(), items(), carrierMappings(), trackingEvents()
بازنویسی ShippingRate.php + cast برای enums
بازنویسی User.php + فیلدهای phone, role, is_active + helper methods
ایجاد مدل‌های جدید:
- ShipmentCarrierMapping.php
- ShipmentTrackingEvent.php
- SystemSetting.php
- Wallet.php + WalletTransaction.php
- DiscountCode.php
- ExchangeRateHistory.php
- Role.php (spatie/laravel-permission)
ایجاد ۶ enum:
- ShipmentDirection (import/export)
- ShipmentType (DOC_NORMAL/DOC_ECONOMY/PARCEL)
- ShipmentStatus (۹ وضعیت شامل pending_payment/cancelled)
- CarrierCode (DHL/FEDEX/UPS/ARAMEX/NAGHEL/EMX/APSITEX/IMPEX/OTHER)
- TrackingSource (۵ منبع: manual/api/import/system/customer)
- TransactionType + TransactionStatus
- PaymentGateway (zarinpal/wallet/manual/system)
- UserRole (super_admin/tracking_operator/data_entry/customer)

۳. Seeders (کامل)

بازنویسی CountriesTableSeeder با ۲۳۳ کشور + ۴ زون + iso_code تصحیح‌شده
- تصحیح کدهای ISO نادرست (Bonaire BQ، Curacao CW، حذف Somaliland XS)
- حذف کشورهای تکراری ("United Arab Emirates" و "Rest of Dubai" هر دو با zone 9 و 10)
ایجاد SystemSettingSeeder (VAT 9%، packing 100000 IRR، profit_margin 1.25، نرخ ارزهای اولیه)
بازنویسی DatabaseSeeder (countries + system_settings + super_admin user)
ایجاد RoleAndPermissionSeeder (نقش‌های اولیه + دسترسی‌های پایه)
ایجاد SampleDataSeeder (۵ مرسوله، ۴ تراکنش، ۳ کد تخفیف)
اجرای seeders — ۲۳۲ کشور + ۷ setting + ۱ کاربر ادمین

۴. API ترکینگ (کامل)

ایجاد TrackController با JSON response کامل (shipment + carrier_mappings + timeline)
ایجاد ApiKeyMiddleware (Bearer token validation)
ثبت route GET /api/v1/track/{awb_no} با middleware API Key
تست‌های موفق:
- GET /api/v1/track/TEST123 با API Key صحیح → 200 OK
- بدون API Key → 401 Unauthorized
- با API Key نامعتبر → 403 Forbidden

۵. Filament Resources (کامل)

CountryResource — فرم ۴ زون + iso_code + is_active + فیلترها
ShipmentResource — فرم کامل با ۷ Section + RelationManagers
- Section: Route & Status
- Section: Weight & Dimensions
- Section: Financial Info (۱۱ فیلد مالی)
- Section: Sender Info
- Section: Receiver Info
- Section: Customs Items (Repeater ۹ ردیف)
ShippingRateResource — فرم ۱۰ zone + enum type/direction
ShipmentItemResource — CRUD کامل
WalletResource — مدیریت کیف پول
WalletTransactionResource — CRUD کامل با صفحات Create/Edit
PaymentResource — مشاهده تراکنش‌های درگاه
DiscountCodeResource — مدیریت کدهای تخفیف با form/table/filters
ExchangeRateHistoryResource — مشاهده تاریخچه نرخ ارز
RoleResource — مدیریت نقش‌ها (spatie/laravel-permission)
UserResource — مدیریت کاربران (spatie/laravel-permission)
RelationManagers:
- CarrierMappingsRelationManager (برای Shipment)
- TrackingEventsRelationManager (برای Shipment)
Pages:
- ListShipments, CreateShipment, EditShipment, ViewShipment
- ListCountries, CreateCountry, EditCountry
- ListShippingRates, CreateShippingRate, EditShippingRate
- ListShipmentItems, CreateShipmentItem, EditShipmentItem
- ListWalletTransactions, CreateWalletTransaction, EditWalletTransaction
- ListPayments, ViewPayment
- ListDiscountCodes, CreateDiscountCode, EditDiscountCode
- ListExchangeRateHistories, ViewExchangeRateHistory
- ListRoles, CreateRole, EditRole
- ListUsers, CreateUser, EditUser
SettingsPage (Page سفارشی برای System Settings)
DashboardInfoWidget — اطلاعات کلی داشبورد
ExchangeRateWidget — نرخ ارز زنده
WalletStats — آمار کیف پول
TransactionChartWidget — نمودار تراکنش‌ها
RecentTransactionsWidget — آخرین تراکنش‌ها
FinancialReport — گزارش مالی کامل

۶. Services (کامل)

TrackingService — getTrackingTimeline, addTrackingEvent, getShipmentWithTracking
PriceCalculatorService — محاسبه قیمت کامل مطابق EXCEL_ANALYSIS.md
- مرحله ۱: وزن حجمی
- مرحله ۲: وزن قابل پرداخت
- مرحله ۳: استخراج زون از ۴ زون مجزا
- مرحله ۴: استخراج قیمت پایه از shipping_rates
- مرحله ۵: اعمال ضریب سود
- مرحله ۶: تبدیل درهم به ریال
- مرحله ۷: اضافه هزینه‌های جانبی
- مرحله ۸: اعمال VAT 9%
- مرحله ۹: ذخیره خروجی‌ها
ExchangeRateService — مدیریت و ردیابی نرخ ارز
ZarinpalService — اتصال به درگاه پرداخت زرین‌پال
MockZarinpalService — شبیه‌سازی درگاه برای تست
OrderPaymentService — پرداخت سفارشات (کیف پول + درگاه)

۷. Imports (Excel) (کامل)

ShippingRatesImport — import از ۵ شیت (Import Rate, Export Rate, DocNor, DocEco, Parcel)
- ۴۰۴ رکورد import شد: DocNormal: ۷۴، DocEconomy: ۷۰، Parcel: ۲۶۰
HistoricalShipmentsImport — import از شیت List فایل اصلی
- ⚠️ مشکل: فایل اکسل فقط ۲ ردیف داده واقعی دارد و بقیه فرمول‌های Excel هستند
- ۱ رکورد (980100010) موفقیت‌آمیز import شد
Artisan Commands:
- ifnex:import:rates {path}
- ifnex:import:shipments {path}

۸. سوییچ به Laravel 11 (کامل با نقص باقی‌مانده)

تغییر composer.json: laravel/framework از ^12.0 به ^11.0
تغییر morilog/jalali از ^4.3 به ^3.0 (v4 وجود ندارد)
اجرای composer update — Laravel از v12.64.0 به v11.55.0 downgrade شد
رفع خطای PSR-4 در SettingsPage.php
رفع مشکل middleware در bootstrap/app.php برای Laravel 11
رفع خطای MethodNotAllowedHttpException برای POST /admin/login

٩. پیکربندی (کامل)

اضافه کردن IFNEX_API_KEY به .env.example
اضافه کردن CORS_ALLOWED_ORIGINS به .env.example
اضافه کردن IFNEX_TRACKING_RATE_LIMIT به .env.example
ایجاد config/ifnex.php برای تنظیمات اختصاصی
تغییر APP_LOCALE به fa در .env.example
اضافه کردن morilog/jalali به composer.json
ایجاد 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:

->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:

->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 تست شدند
🟢 پایین	تست نهایی فاز ۰ و تحویل به مشتری	✅ انجام شد	همه موارد تست شدند

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

موتور قیمت‌گذاری کامل (PriceCalculatorService) — نوشته شد، تست با داده‌های واقعی انجام شد
جدول shipping_rates — ۱۳۸ رکورد import شد با پشتیبانی از ۵ نوع سرویس/جهت
فرم ثبت سفارش آنلاین با ۹ ردیف کالای گمرکی
تولید PDF: AWB، INVOICE، Label — پیاده شد. قالب‌ها بر اساس ساختار شیت‌های اکسل و لوگوی استخراج‌شده طراحی شدند. استایل نهایی و تطبیق دقیق‌تر با قالب‌های اکسل در فاز بعدی انجام می‌شود.
ماژول ایمپورت اکسل تعرفه‌ها — command با قابلیت‌های --clear و --dry-run پیاده شد
صفحه استعلام قیمت واقعی — رابط کاربری عمومی + API محاسبه قیمت

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

ساخت WalletController با APIهای شارژ، بررسی موجودی و تاریخچه تراکنش‌ها
ساخت DiscountCodeController با APIهای لیست و اعتبارسنجی کده تخفیف
ساخت UpdateExchangeRates Artisan Command با پشتیبانی از ECB و FreeCurrencyAPI
ثبت routeهای کیف پول و تخفیف در api.php
اضافه کردن CURRENCY_API_KEY به .env.example و config/ifnex.php
پاک‌سازی فایل‌های تست و debug (check_*.php, debug_*.php, test_*.php, inspect_*.php)
رفع CORS — تغییر از * به دامنه مشخص از .env
حذف migration‌های قدیمی تکراری (2023_10_27_*, 2026_07_31_*)
اتصال درگاه پرداخت (زرین‌پال) با Mock Gateway برای تست
ساخت ZarinpalService و MockZarinpalService
ساخت OrderPaymentService برای پرداخت سفارشات
ساخت ExchangeRateService و ExchangeRateHistory برای ردیابی نرخ ارز
پنل مالی در Filament (داشبورد سود/زیان)
تکمیل DiscountCodeResource با form/table/filters
ساخت PaymentResource در Filament
ساخت WalletTransactionResource با صفحات Create/Edit
ساخت ExchangeRateHistoryResource
تست‌های Unit/Feature برای Phase 2 (24 تست، 77 assertion)
رفع باگ WalletController::balance()
حذف PaymentGatewayService قدیمی (استفاده نمی‌شد)
زیباسازی داشبورد و صفحه لاگین Filament (رنگ Navy، Vazirmatn، RTL)
گسترش پلاگین IFNEX Bridge برای وردپرس:
- ساخت IFNEX_User_Bridge برای مدیریت توکن Sanctum کاربران وردپرس
- اضافه کردن شورت‌کد [ifnex_wallet_balance]
- اضافه کردن شورت‌کد [ifnex_transactions]
- اضافه کردن AJAX handlers برای کیف پول و تراکنش‌ها
- ساخت استایل‌های CSS کامل برای تمام کامپوننت‌های پلاگین
- ایجاد صفحه تست در وردپرس: http://localhost/ifnexwp/?page_id=18
یکپارچگی RBAC با spatie/laravel-permission
- نصب پکیج spatie/laravel-permission
- ساخت RoleResource و UserResource در Filament
- ساخت RoleAndPermissionSeeder
سینک کاربران وردپرس ↔ لاراول با دستور ifnex:sync-wp-users
طراحی سیستم یکپارچه IFNEX (DESIGN_SYSTEM.md)
گزارش‌گیری مالی در Filament (FinancialReport)
خروجی Excel برای ShipmentResource و WalletTransactionResource

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

ساخت AuthController برای ورود/خروج Sanctum مشتریان
ساخت BridgeAuthController برای لاگین مستقیم از وردپرس
ساخت CustomerOrderController با ۶ endpoint:
- GET /api/v1/customer/profile — پروفایل و آمار
- GET /api/v1/customer/countries — لیست کشورها
- GET /api/v1/customer/orders — لیست سفارشات
- POST /api/v1/customer/orders — ثبت سفارش جدید
- GET /api/v1/customer/orders/{shipment} — جزئیات سفارش
- POST /api/v1/customer/orders/{shipment}/cancel — لغو سفارش
ساخت OrderPaymentService برای پرداخت سفارشات
- پرداخت از کیف پول: payFromWallet()
- پرداخت از درگاه: initiateGatewayPayment()
- تکمیل پرداخت بعد از callback: completeGatewayPayment()
توسعه پلاگین IFNEX Bridge برای پورتال مشتری:
- شورت‌کد [ifnex_order_form] — فرم ثبت سفارش چندمرحله‌ای
- شورت‌کد [ifnex_orders_list] — لیست سفارشات
- شورت‌کد [ifnex_order_payment] — صفحه پرداخت سفارش
- شورت‌کد [ifnex_order_detail] — جزئیات سفارش
- شورت‌کد [ifnex_user_profile] — پروفایل کاربر
- استایل ifnex-orders.css برای تمام کامپوننت‌ها
- اسکریپت ifnex-order-form.js برای ناوبری مراحل و AJAX
- AJAX handlers: ifnex_pay_order_wallet, ifnex_pay_order_gateway, ifnex_cancel_order
توسعه پوسته سفامشی IFNEX برای وردپرس:
- پشتیبانی چندزبانه با Polylang
- مدیریت LTR/RTL خودکار
- Customizer برای لوگو و زبان
- قالب‌های archive, single, front-page
- ساختار تمیک شرکتی با لوگو IFNEX
به‌روزرسانی وردپرس به نسخه ۷.۰.۳ با بهبودهای امنیتی
یکپارچگی Design System در Filament و وردپرس
خروجی CSV برای ShipmentResource و WalletTransactionResource

🚫 خط قرمزها (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 است.

س: چه کارهایی در این جلسه انجام شد؟

ج:

تکمیل کامل سیستم سفارشات مشتری (CustomerOrderController با ۶ endpoint)
توسعه سرویس پرداخت سفارشات (OrderPaymentService) — کیف پول + درگاه
ساخت AuthController و BridgeAuthController برای احراز هویت
گسترش پلاگین IFNEX Bridge با شورت‌کدهای پرداخت و جزئیات سفارش
افزودن ۲ وضعیت جدید به ShipmentStatus: pending_payment و cancelled
توسعه پورتال مشتری در وردپرس (فرم سفارش، لیست، پرداخت، جزئیات)
یکپارچگی RBAC با spatie/laravel-permission
ردیابی تاریخچه نرخ ارز با ExchangeRateHistory
طراحی سیستم یکپارچه IFNEX (DESIGN_SYSTEM.md)
به‌روزرسانی وردپرس به ۷.۰.۳

س: چه کارهایی باقی مانده؟

ج:

تست کامل APIهای سفارشات مشتری و پرداخت
تست کامل پلاگین وردپرس با داده‌های واقعی مشتری
راه‌اندازی VPS پل خارج برای API ترکینگ زنده (فاز ۴)
اتصال به TrackingMore/17track API
~~فرمول محاسبه قیمت رقبا~~ (آرشیو شد)

🛠️ Quick Commands — دستورات پرکاربرد

نصب و راه‌اندازی لاراول

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 سفارشی

# 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

# Update exchange rates
php artisan ifnex:update-exchange-rates

# Sync WordPress users
php artisan ifnex:sync-wp-users

تست API Track

# با 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

تست API سفارشات مشتری

# ورود و دریافت توکن
curl -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@ifnex.local","password":"password"}'

# لیست سفارشات (با توکن)
curl -H "Authorization: Bearer {token}" \
  http://localhost:8000/api/v1/customer/orders

# ثبت سفارش جدید
curl -X POST http://localhost:8000/api/v1/customer/orders \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"direction":"export","type":"PARCEL","from_country_id":1,"to_country_id":2,"weight":2.5,...}'

پشتیبان‌گیری از دیتابیس

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 را بررسی کن — ببین چه چیزی نوشته شده ۶. اولویت اول: تست کامل APIهای جدید (customer orders, payments, auth) ۷. اولویت دوم: تست کامل پلاگین وردپرس با داده‌های واقعی ۸. با کاربر (Kazem) هماهنگ کن — بپرس کدام کار را باید ادامه دهی

مهم‌ترین کار بعدی: تست کامل APIهای سفارشات مشتری + پرداخت.

📞 تماس

توسعه‌دهنده اصلی: 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ها
تست کامل داشبورد مالی و منوهای مختلف
تکمیل کامل پورتال مشتری وردپرس:
- شورت‌کد [ifnex_order_form] — فرم ثبت سفارش چندمرحله‌ای
- شورت‌کد [ifnex_orders_list] — لیست سفارشات با فیلتر وضعیت
- شورت‌کد [ifnex_order_payment] — صفحه پرداخت سفارش (کیف پول + درگاه)
- شورت‌کد [ifnex_order_detail] — جزئیات سفارش با timeline رهگیری
- شورت‌کد [ifnex_user_profile] — پروفایل کاربر با آمار کیف پول
- استایل ifnex-orders.css و اسکریپت ifnex-order-form.js
- AJAX handlers برای پرداخت از کیف پول و درگاه
تکمیل سیستم پرداخت سفارشات:
- CustomerOrderController با ۶ endpoint
- OrderPaymentService برای پرداخت از کیف پول و درگاه
- BridgeAuthController برای لاگین از وردپرس
- APIهای /customer/orders/* و /customer/orders/{shipment}/pay-*
- وضعیت‌های جدید pending_payment و cancelled در ShipmentStatus
به‌روزرسانی Enums:
- PaymentGateway اضافه شدن case WALLET
- TrackingSource اضافه شدن cases SYSTEM و CUSTOMER

۲۰۲۶-۰۸-۰۸

ساخت 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 - تغییر از * به دامنه مشخص

کارهای بعدی

فاز ۲.۵ — تست و بهینه‌سازی

تست نهایی پلاگین وردپرس با داده‌های واقعی
- تست همه شورت‌کدها با داده‌های واقعی مشتری
- تست CORS و Rate Limiting در محیط تولید
- تست عملکرد offline/timeout
مستندسازی API
- مستند کامل APIهای لاراول برای فرانت‌اند developerها
- مستند نحوه نصب و تنظیم پلاگین وردپرس
- مستند نحوه sync کاربران
بهینه‌سازی عملکرد
- کش‌کردن نرخ ارز و تعرفه‌ها
- بهینه‌سازی queryهای پرتکرار

فاز ۴ — VPS پل و ترکینگ زنده

راه‌اندازی VPS پل خارج (هلند/آلمان)
اتصال به TrackingMore/17track API
- مپ کردن کدهای رهگیری
- وب‌هوک برای به‌روزرسانی خودکار وضعیت
گزارش‌گیری پیشرفته
- خروجی Excel/PDF برای تراکنش‌ها، مرسولات، سود/زیان
- داشبورد مدیریتی برای مدیرعامل
پلاگین SMS
- اطلاع‌رسانی وضعیت مرسوله به مشتری
- اطلاع‌رسانی پرداخت‌های کیف پول
- یادآوری انقضا کدهای تخفیف
ماژول CRM
- مدیریت مشتریان
- تماس‌ها و یادآوری‌ها
- تحلیل رفتار مشتریان
اپلیکیشن موبایل
- نسخه Android/iOS برای مشتریان
- Push notification برای وضعیت مرسوله

45 KiB Raw Blame History Unescape Escape

🚨 STATUS.md — این فایل را اول بخوانید

⚠️ هشدار حیاتی — قبل از هر کاری بخوانید

📌 Quick Reference — نسخه‌ها و معماری

تکنولوژی‌ها (قفل‌شده)

معماری کلی

✅ وضعیت فعلی کار

کارهای انجام‌شده (تا تاریخ 2026-08-04)

۱. اسکیمای دیتابیس فاز ۰ (کامل)

۲. مدل‌ها و Enums (کامل)

۳. Seeders (کامل)

۴. API ترکینگ (کامل)

۵. Filament Resources (کامل)

۶. Services (کامل)

۷. Imports (Excel) (کامل)

۸. سوییچ به Laravel 11 (کامل با نقص باقی‌مانده)

٩. پیکربندی (کامل)

🔴 Code Review Findings — نیاز به رفع

🔴 مشکل — مهاجرت داده‌های تاریخی

کارهای در دست اقدام (فاز ۰)

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

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

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

🚫 خط قرمزها (DO NOT) — هرگز این کارها را نکن

🚫 اسکیمای دیتابیس

🚫 معماری

🚫 طراحی و کپی‌رایت

🚫 فرآیند

❓ سوالات متداول (FAQ)

س: کدام نسخه لاراول استفاده کنم؟

س: مهاجرت داده‌هایHistorical چقدر مهم است؟

س: چه کارهایی در این جلسه انجام شد؟

س: چه کارهایی باقی مانده؟

🛠️ Quick Commands — دستورات پرکاربرد

نصب و راه‌اندازی لاراول

Artisan Commands سفارشی

تست API Track

تست API سفارشات مشتری

پشتیبان‌گیری از دیتابیس

📂 ساختار پوشه‌های پروژه (پس از تکمیل فاز ۰)

🎯 گام بعدی برای ادامه‌ی کار

📞 تماس

کارهای انجام‌شده اخیر (آگوست ۲۰۲۶)

2026-08-10

۲۰۲۶-۰۸-۰۸

۲۰۲۶-۰۸-۰۷

۲۰۲۶-۰۸-۰۵

کارهای بعدی

فاز ۲.۵ — تست و بهینه‌سازی

فاز ۴ — VPS پل و ترکینگ زنده

🚫 خط قرمزها (DO NOT) — هرگز این کارها را نکن

45 KiB

Raw Blame History