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.
This commit is contained in:
Kazem Alghasi
parent
a92701af11
commit
e032fceb34
@ -1,250 +1,272 @@
|
||||
# نقشه فایلهای پروژه IFNEX
|
||||
|
||||
> **آخرین بروزرسانی:** 2026-08-29
|
||||
> **وضعیت کلی:** فاز ۰، ۱، ۲، ۳ تکمیل شد ✅ (۱۹۲ کشور با پیششماره)
|
||||
> **آخرین بروزرسانی:** 2026-09-10
|
||||
> **وضعیت کلی:** فاز ۰، ۱، ۲، ۳، ۳.۵ تکمیل ✅ — فاز ۳.۶ در حال تکمیل (۸۰%) 🟡
|
||||
|
||||
---
|
||||
|
||||
## ۱. Migrations (۲۳ migration)
|
||||
## ۱. Migrations (۴۰ فایل)
|
||||
|
||||
| # | فایل | فاز |
|
||||
|---|------|-----|
|
||||
| 1 | `database/migrations/0001_01_01_000000_create_users_table.php` | ۰ |
|
||||
| 2 | `database/migrations/0001_01_01_000001_create_cache_table.php` | ۰ |
|
||||
| 3 | `database/migrations/0001_01_01_000002_create_jobs_table.php` | ۰ |
|
||||
| 4 | `database/migrations/2026_08_02_000001_create_countries_table.php` | ۰ |
|
||||
| 5 | `database/migrations/2026_08_02_000002_create_shipments_table.php` | ۰ |
|
||||
| 6 | `database/migrations/2026_08_02_000003_create_shipping_rates_table.php` | ۰ |
|
||||
| 7 | `database/migrations/2026_08_02_000004_create_shipment_carrier_mappings_table.php` | ۰ |
|
||||
| 8 | `database/migrations/2026_08_02_000005_create_shipment_tracking_events_table.php` | ۰ |
|
||||
| 9 | `database/migrations/2026_08_02_000006_create_system_settings_table.php` | ۰ |
|
||||
| 10 | `database/migrations/2026_08_02_000007_update_users_table.php` | ۰ |
|
||||
| 11 | `database/migrations/2026_08_05_135016_create_wallets_table.php` | ۲ |
|
||||
| 12 | `database/migrations/2026_08_05_135022_create_wallet_transactions_table.php` | ۲ |
|
||||
| 13 | `database/migrations/2026_08_05_135026_create_discount_codes_table.php` | ۲ |
|
||||
| 14 | `database/migrations/2026_08_05_140000_create_payments_table.php` | ۲ |
|
||||
| 15 | `database/migrations/2026_08_07_000001_create_wallet_activity_logs_table.php` | ۲ |
|
||||
| 16 | `database/migrations/2026_08_07_033748_create_personal_access_tokens_table.php` | ۰ |
|
||||
| 17 | `database/migrations/2026_08_08_000001_create_shipment_items_table.php` | ۰ |
|
||||
| 18 | `database/migrations/2026_08_09_012526_create_notifications_table.php` | ۲ |
|
||||
| 19 | `database/migrations/2026_08_09_220409_create_permission_tables.php` | ۰ |
|
||||
| 20 | `database/migrations/2026_08_09_231738_create_exchange_rate_history_table.php` | ۲ |
|
||||
| 21 | `database/migrations/2026_08_10_020410_update_shipments_status_enum.php` | ۰ |
|
||||
| 22 | `database/migrations/2026_08_10_080853_add_wallet_to_payment_gateway_enum.php` | ۲ |
|
||||
| 23 | `database/migrations/2026_08_10_082121_add_system_to_tracking_source_enum.php` | ۲ |
|
||||
| 24 | `database/migrations/2026_08_24_000001_add_missing_fields_to_shipments_table.php` | ۳ |
|
||||
| 25 | `database/migrations/2026_08_24_100001_create_currencies_table.php` | ۲ |
|
||||
| 26 | `database/migrations/2026_08_24_200001_create_shipment_packages_table.php` | ۲ |
|
||||
| 27 | `database/migrations/2026_08_24_300001_create_shipment_status_histories_table.php` | ۲ |
|
||||
| 28 | `database/migrations/2026_08_28_233839_add_calling_code_to_countries_table.php` | ۳ |
|
||||
| 1 | `0001_01_01_000000_create_users_table.php` | ۰ |
|
||||
| 2 | `0001_01_01_000001_create_cache_table.php` | ۰ |
|
||||
| 3 | `0001_01_01_000002_create_jobs_table.php` | ۰ |
|
||||
| 4 | `2026_08_02_000001_create_countries_table.php` | ۰ |
|
||||
| 5 | `2026_08_02_000002_create_shipments_table.php` | ۰ |
|
||||
| 6 | `2026_08_02_000003_create_shipping_rates_table.php` | ۰ |
|
||||
| 7 | `2026_08_02_000004_create_shipment_carrier_mappings_table.php` | ۰ |
|
||||
| 8 | `2026_08_02_000005_create_shipment_tracking_events_table.php` | ۰ |
|
||||
| 9 | `2026_08_02_000006_create_system_settings_table.php` | ۰ |
|
||||
| 10 | `2026_08_02_000007_update_users_table.php` | ۰ |
|
||||
| 11 | `2026_08_05_135016_create_wallets_table.php` | ۲ |
|
||||
| 12 | `2026_08_05_135022_create_wallet_transactions_table.php` | ۲ |
|
||||
| 13 | `2026_08_05_135026_create_discount_codes_table.php` | ۲ |
|
||||
| 14 | `2026_08_05_140000_create_payments_table.php` | ۲ |
|
||||
| 15 | `2026_08_07_000001_create_wallet_activity_logs_table.php` | ۲ |
|
||||
| 16 | `2026_08_07_033748_create_personal_access_tokens_table.php` | ۰ (Sanctum) |
|
||||
| 17 | `2026_08_08_000001_create_shipment_items_table.php` | ۰ |
|
||||
| 18 | `2026_08_08_000001_fix_discount_codes_type_enum.php` | ۲ |
|
||||
| 19 | `2026_08_09_012526_create_notifications_table.php` | ۲ |
|
||||
| 20 | `2026_08_09_220409_create_permission_tables.php` | ۲ (spatie) |
|
||||
| 21 | `2026_08_09_231738_create_exchange_rate_history_table.php` | ۲ |
|
||||
| 22 | `2026_08_10_020410_update_shipments_status_enum.php` | ۰ |
|
||||
| 23 | `2026_08_10_080853_add_wallet_to_payment_gateway_enum.php` | ۲ |
|
||||
| 24 | `2026_08_10_082121_add_system_to_tracking_source_enum.php` | ۲ |
|
||||
| 25 | `2026_08_24_000001_add_missing_fields_to_shipments_table.php` | ۳ |
|
||||
| 26 | `2026_08_24_100001_create_currencies_table.php` | ۲ |
|
||||
| 27 | `2026_08_24_200001_create_shipment_packages_table.php` | ۳.۵ |
|
||||
| 28 | `2026_08_24_300001_create_shipment_status_histories_table.php` | ۲ |
|
||||
| 29 | `2026_08_28_233839_add_calling_code_to_countries_table.php` | ۳ |
|
||||
| 30 | `2026_08_29_021506_fix_shipment_items_table.php` | ۳.۵ |
|
||||
| 31 | `2026_08_29_021631_make_name_nullable_in_shipment_items.php` | ۳.۵ |
|
||||
| 32 | `2026_09_03_000001_add_approval_statuses_to_shipments_table.php` | ۳.۶ (فلوی تأیید) |
|
||||
| 33 | `2026_09_03_000002_create_commitment_forms_table.php` | ۳.۶ (تعهدنامه) |
|
||||
| 34 | `2026_09_03_000003_add_credit_fields_to_users_table.php` | ۳.۶ (اعتبار) |
|
||||
| 35 | `2026_09_03_000004_create_shipment_checklists_table.php` | ۳.۶ (چکلیست) |
|
||||
| 36 | `2026_09_03_000005_create_audit_logs_table.php` | ۳.۶ (Audit Log) |
|
||||
| 37 | `2026_09_03_000006_add_import_invoice_fields_to_shipments_table.php` | ۳.۶ (فاکتور واردات) |
|
||||
| 38 | `2026_09_09_000001_create_shipment_commitment_forms_table.php` | ۳.۶ (تعهدنامه امضاشده) |
|
||||
| 39 | `2026_09_09_000002_create_shipment_status_history_table.php` | ۳.۶ |
|
||||
| 40 | `2026_09_09_000003_add_reason_to_shipment_status_history_table.php` | ۳.۶ |
|
||||
|
||||
---
|
||||
|
||||
## ۲. Models (۱۳ مدل)
|
||||
## ۲. Models (۲۲ مدل)
|
||||
|
||||
| # | فایل | فاز |
|
||||
|---|------|-----|
|
||||
| 1 | `app/Models/Country.php` | ۰+۳ (calling_code) |
|
||||
| 2 | `app/Models/Shipment.php` | ۰+۲+۳ |
|
||||
| 3 | `app/Models/ShipmentCarrierMapping.php` | ۰ |
|
||||
| 4 | `app/Models/ShipmentTrackingEvent.php` | ۰+۲ (source) |
|
||||
| 5 | `app/Models/ShipmentItem.php` | ۰ |
|
||||
| 6 | `app/Models/ShipmentPackage.php` | ۲ |
|
||||
| 7 | `app/Models/ShipmentStatusHistory.php` | ۲ |
|
||||
| 8 | `app/Models/ShippingRate.php` | ۰ |
|
||||
| 9 | `app/Models/SystemSetting.php` | ۰ |
|
||||
| 10 | `app/Models/User.php` | ۰+۲ |
|
||||
| 11 | `app/Models/Currency.php` | ۲ |
|
||||
| 12 | `app/Models/Wallet.php` | ۲ |
|
||||
| 13 | `app/Models/WalletTransaction.php` | ۲ |
|
||||
| 14 | `app/Models/WalletActivityLog.php` | ۲ |
|
||||
| 15 | `app/Models/DiscountCode.php` | ۲ |
|
||||
| 16 | `app/Models/Payment.php` | ۲ |
|
||||
| 17 | `app/Models/ExchangeRateHistory.php` | ۲ |
|
||||
| # | فایل | توضیح |
|
||||
|---|------|-------|
|
||||
| 1 | `Country.php` | ۲۳۳ کشور + ۴ زون + calling_code |
|
||||
| 2 | `Shipment.php` | مدل مرکزی مرسوله (casts enum + روابط کامل) |
|
||||
| 3 | `ShipmentCarrierMapping.php` | نگاشت شرکتهای حمل |
|
||||
| 4 | `ShipmentTrackingEvent.php` | رویدادهای ترکینگ |
|
||||
| 5 | `ShipmentItem.php` | اقلام گمرکی فاکتور |
|
||||
| 6 | `ShipmentPackage.php` | بستههای چندگانه + محاسبه وزن حجمی |
|
||||
| 7 | `ShipmentStatusHistory.php` | تاریخچه تغییر وضعیت (from/to/reason) |
|
||||
| 8 | `ShippingRate.php` | تعرفهها (zone_1..zone_10) |
|
||||
| 9 | `SystemSetting.php` | تنظیمات key-value |
|
||||
| 10 | `User.php` | کاربران + اعتبار (credit_limit/credit_used) |
|
||||
| 11 | `Currency.php` | ارزها |
|
||||
| 12 | `Wallet.php` | کیف پول |
|
||||
| 13 | `WalletTransaction.php` | تراکنشها (polymorphic) |
|
||||
| 14 | `WalletActivityLog.php` | لاگ فعالیت کیف پول |
|
||||
| 15 | `DiscountCode.php` | کدهای تخفیف |
|
||||
| 16 | `Payment.php` | پرداختهای درگاه |
|
||||
| 17 | `ExchangeRateHistory.php` | تاریخچه نرخ ارز |
|
||||
| 18 | `Role.php` | نقشها (spatie) |
|
||||
| 19 | `CommitmentForm.php` | فرمهای تعهدنامه پایه |
|
||||
| 20 | `ShipmentCommitmentForm.php` | تعهدنامه امضاشده هر سفارش |
|
||||
| 21 | `ShipmentChecklist.php` | چکلیست کارمند |
|
||||
| 22 | `AuditLog.php` | لاگ تغییرات (polymorphic) |
|
||||
|
||||
---
|
||||
|
||||
## ۳. Filament Resources
|
||||
## ۳. Enums (۹ فایل)
|
||||
|
||||
| # | فایل | فاز |
|
||||
|---|------|-----|
|
||||
| 1 | `app/Filament/Resources/CountryResource.php` | ۰ |
|
||||
| 2 | `app/Filament/Resources/CountryResource/Pages/ListCountries.php` | ۰ |
|
||||
| 3 | `app/Filament/Resources/CountryResource/Pages/CreateCountry.php` | ۰ |
|
||||
| 4 | `app/Filament/Resources/CountryResource/Pages/EditCountry.php` | ۰ |
|
||||
| 5 | `app/Filament/Resources/ShipmentResource.php` | ۰+۳ |
|
||||
| 6 | `app/Filament/Resources/ShipmentResource/Pages/ListShipments.php` | ۰ |
|
||||
| 7 | `app/Filament/Resources/ShipmentResource/Pages/CreateShipment.php` | ۰ |
|
||||
| 8 | `app/Filament/Resources/ShipmentResource/Pages/ViewShipment.php` | ۰+۳ |
|
||||
| 9 | `app/Filament/Resources/ShipmentResource/Pages/EditShipment.php` | ۰ |
|
||||
| 10 | `app/Filament/Resources/ShipmentResource/RelationManagers/TrackingEventsRelationManager.php` | ۰+۲ |
|
||||
| 11 | `app/Filament/Resources/ShipmentResource/RelationManagers/CarrierMappingsRelationManager.php` | ۰ |
|
||||
| 12 | `app/Filament/Resources/ShipmentResource/RelationManagers/ItemsRelationManager.php` | ۰ |
|
||||
| 13 | `app/Filament/Resources/ShippingRateResource.php` | ۰ |
|
||||
| 14 | `app/Filament/Resources/ShippingRateResource/Pages/ListShippingRates.php` | ۰ |
|
||||
| 15 | `app/Filament/Resources/ShippingRateResource/Pages/CreateShippingRate.php` | ۰ |
|
||||
| 16 | `app/Filament/Resources/ShippingRateResource/Pages/EditShippingRate.php` | ۰ |
|
||||
| 17 | `app/Filament/Resources/CurrencyResource.php` | ۲ |
|
||||
| 18 | `app/Filament/Resources/CurrencyResource/Pages/ListCurrencies.php` | ۲ |
|
||||
| 19 | `app/Filament/Resources/CurrencyResource/Pages/CreateCurrency.php` | ۲ |
|
||||
| 20 | `app/Filament/Resources/CurrencyResource/Pages/EditCurrency.php` | ۲ |
|
||||
| # | فایل | مقادیر |
|
||||
|---|------|--------|
|
||||
| 1 | `ShipmentStatus.php` | pending_approval, approved, pending_payment, cancelled, processed, picked_up, in_transit, out_for_delivery, failed, delivered, returned, archived |
|
||||
| 2 | `ShipmentDirection.php` | import, export |
|
||||
| 3 | `ShipmentType.php` | DOC_NORMAL, DOC_ECONOMY, PARCEL |
|
||||
| 4 | `CarrierCode.php` | DHL, FEDEX, UPS, ARAMEX, NAGHEL, EMX, APSITEX, IMPEX, OTHER |
|
||||
| 5 | `PaymentGateway.php` | zarinpal, wallet, manual, system |
|
||||
| 6 | `TransactionType.php` | deposit, withdrawal, order_payment, refund |
|
||||
| 7 | `TransactionStatus.php` | pending, completed, failed, refunded |
|
||||
| 8 | `TrackingSource.php` | manual, api, import, system, customer |
|
||||
| 9 | `UserRole.php` | super_admin, tracking_operator, data_entry, customer |
|
||||
|
||||
---
|
||||
|
||||
## ۴. Filament Pages
|
||||
## ۴. Controllers
|
||||
|
||||
| # | فایل | فاز |
|
||||
|---|------|-----|
|
||||
| 1 | `app/Filament/Pages/SettingsPage.php` | ۰ |
|
||||
| 2 | `app/Filament/Pages/PriceTestPage.php` | ۰ |
|
||||
| 3 | `app/Filament/Pages/ImportRatesPage.php` | ۲ |
|
||||
| 4 | `resources/views/filament/pages/settings-page.blade.php` | ۰ |
|
||||
| 5 | `resources/views/filament/pages/price-test-page.blade.php` | ۰ |
|
||||
| 6 | `resources/views/filament/pages/import-rates.blade.php` | ۲ |
|
||||
### app/Http/Controllers/Api (۱۲ کنترلر)
|
||||
|
||||
| # | فایل | توضیح |
|
||||
|---|------|-------|
|
||||
| 1 | `TrackController.php` | رهگیری عمومی (API Key) |
|
||||
| 2 | `PricingController.php` | محاسبه قیمت |
|
||||
| 3 | `AuthController.php` | ورود/خروج Sanctum |
|
||||
| 4 | `BridgeAuthController.php` | Bridge Auth وردپرس |
|
||||
| 5 | `Customer/CustomerOrderController.php` | سفارشات مشتری (۶۷۲ خط — بزرگترین فایل اپ) |
|
||||
| 6 | `WalletController.php` | کیف پول + ادمین |
|
||||
| 7 | `PaymentController.php` | درگاه + callback (فلوی تأیید سفارش) |
|
||||
| 8 | `DiscountCodeController.php` | کدهای تخفیف |
|
||||
| 9 | `MockGatewayController.php` | درگاه شبیهسازی |
|
||||
| 10 | `StaffOrderController.php` | تأیید/رد سفارشات کارمند |
|
||||
| 11 | `CustomerFinancialController.php` | وضعیت مالی مشتری (بدهی به تفکیک ارز) |
|
||||
| 12 | `CommitmentFormController.php` | تعهدنامهها + آپلود امضاشده |
|
||||
| 13 | `MobileVerificationController.php` | تأیید موبایل (کد SMS) |
|
||||
|
||||
### app/Http/Controllers (وب)
|
||||
|
||||
| # | فایل | توضیح |
|
||||
|---|------|-------|
|
||||
| 1 | `ShipmentPdfController.php` | AWB / Invoice / Label / Import-Invoice |
|
||||
| 2 | `OrderController.php` | فلوی legacy Blade (deprecated) |
|
||||
| 3 | `PricingPageController.php` | صفحه استعلام قیمت |
|
||||
|
||||
---
|
||||
|
||||
## ۵. Controllers
|
||||
## ۵. Services (۸ سرویس)
|
||||
|
||||
| # | فایل | فاز |
|
||||
|---|------|-----|
|
||||
| 1 | `app/Http/Controllers/Api/TrackController.php` | ۰ |
|
||||
| 2 | `app/Http/Controllers/Api/PricingController.php` | ۰ |
|
||||
| 3 | `app/Http/Controllers/Api/AuthController.php` | ۱ |
|
||||
| 4 | `app/Http/Controllers/Api/BridgeAuthController.php` | ۱ |
|
||||
| 5 | `app/Http/Controllers/Api/Customer/CustomerOrderController.php` | ۱+۲ |
|
||||
| 6 | `app/Http/Controllers/Api/WalletController.php` | ۲ |
|
||||
| 7 | `app/Http/Controllers/Api/PaymentController.php` | ۲ |
|
||||
| 8 | `app/Http/Controllers/Api/DiscountCodeController.php` | ۲ |
|
||||
| 9 | `app/Http/Controllers/Api/MockGatewayController.php` | ۲ |
|
||||
| 10 | `app/Http/Controllers/OrderController.php` | ۱ |
|
||||
| 11 | `app/Http/Controllers/PricingPageController.php` | ۱ |
|
||||
| 12 | `app/Http/Controllers/ShipmentPdfController.php` | ۱ |
|
||||
| # | فایل | توضیح |
|
||||
|---|------|-------|
|
||||
| 1 | `PriceCalculatorService.php` | موتور قیمتگذاری (۴ زون + VAT + تخفیف) |
|
||||
| 2 | `PdfService.php` | تولید PDF با بارکد base64 |
|
||||
| 3 | `TrackingService.php` | تایملاین و رویدادهای رهگیری |
|
||||
| 4 | `OrderPaymentService.php` | پرداخت سفارش (کیف پول + درگاه) |
|
||||
| 5 | `WalletService.php` | شارژ/برداشت/تسویه کیف پول |
|
||||
| 6 | `ZarinpalService.php` | درگاه واقعی زرینپال |
|
||||
| 7 | `MockZarinpalService.php` | درگاه شبیهسازی تست |
|
||||
| 8 | `ExchangeRateService.php` | نرخ ارز + تاریخچه |
|
||||
| 9 | `KavenegarSmsService.php` | سرویس پیامک کاوهنگار |
|
||||
|
||||
---
|
||||
|
||||
## ۶. Services
|
||||
## ۶. Notifications / Observers / Traits
|
||||
|
||||
| # | فایل | فاز |
|
||||
|---|------|-----|
|
||||
| 1 | `app/Services/PriceCalculatorService.php` | ۰ |
|
||||
| 2 | `app/Services/TrackingService.php` | ۰ |
|
||||
| 3 | `app/Services/PdfService.php` | ۱ |
|
||||
| 4 | `app/Services/OrderPaymentService.php` | ۲ |
|
||||
| # | فایل | توضیح |
|
||||
|---|------|-------|
|
||||
| 1 | `Notifications/ShipmentUpdatedNotification.php` | نوتیفیکیشن دیتابیسی تغییر سفارش |
|
||||
| 2 | `Notifications/ShipmentApprovedSms.php` | SMS تأیید سفارش |
|
||||
| 3 | `Notifications/ShipmentRejectedSms.php` | SMS رد سفارش |
|
||||
| 4 | `Notifications/PaymentSuccessSms.php` | SMS پرداخت موفق |
|
||||
| 5 | `Notifications/TrackingUpdatedSms.php` | SMS بروزرسانی ترکینگ |
|
||||
| 6 | `Notifications/Channels/SmsChannel.php` | کانال ارسال SMS |
|
||||
| 7 | `Observers/ShipmentObserver.php` | تریگر خودکار نوتیفیکیشن/SMS روی تغییر وضعیت |
|
||||
| 8 | `Traits/Auditable.php` | لاگ خودکار تغییرات مدلها |
|
||||
|
||||
---
|
||||
|
||||
## ۷. Notifications
|
||||
## ۷. Filament (پنل ادمین `/panel`)
|
||||
|
||||
| # | فایل | فاز |
|
||||
|---|------|-----|
|
||||
| 1 | `app/Notifications/ShipmentUpdatedNotification.php` | ۳ |
|
||||
### Resources (۱۶)
|
||||
|
||||
| # | Resource | توضیح |
|
||||
|---|----------|-------|
|
||||
| 1 | ShipmentResource | مرسولهها + اکشن تأیید/رد + RelationManagers |
|
||||
| 2 | ShipmentItemResource | اقلام گمرکی |
|
||||
| 3 | ShipmentChecklistResource | چکلیست کارمند |
|
||||
| 4 | CommitmentFormResource | تعهدنامهها (آپلود مدیر) |
|
||||
| 5 | CustomerCreditResource | اعتبار مشتریان |
|
||||
| 6 | AuditLogResource | لاگ تغییرات |
|
||||
| 7 | CountryResource | کشورها |
|
||||
| 8 | CurrencyResource | ارزها |
|
||||
| 9 | ShippingRateResource | تعرفهها |
|
||||
| 10 | UserResource | کاربران |
|
||||
| 11 | RoleResource | نقشها |
|
||||
| 12 | WalletResource | کیف پولها |
|
||||
| 13 | WalletTransactionResource | تراکنشها |
|
||||
| 14 | PaymentResource | پرداختها |
|
||||
| 15 | DiscountCodeResource | کدهای تخفیف |
|
||||
| 16 | ExchangeRateHistoryResource | تاریخچه نرخ ارز |
|
||||
|
||||
### Pages
|
||||
|
||||
| # | فایل | توضیح |
|
||||
|---|------|-------|
|
||||
| 1 | `Dashboard.php` | داشبورد |
|
||||
| 2 | `IfnexSettingsPage.php` | تنظیمات سیستم + کلیدهای SMS |
|
||||
| 3 | `ImportRatesPage.php` | آپلود اکسل نرخها |
|
||||
| 4 | `PriceTestPage.php` | تست قیمتگذاری (⚠️ خراب — در لیست رفع) |
|
||||
| 5 | `BulkTrackingImport.php` | ایمپورت گروهی وضعیت ترکینگ (CSV) |
|
||||
| 6 | `Reports/FinancialReport.php` | گزارش مالی |
|
||||
|
||||
### Widgets (۵)
|
||||
|
||||
DashboardInfoWidget، ExchangeRateWidget، FinanceOverviewWidget، WalletStats، RecentTransactionsWidget، TransactionChartWidget
|
||||
|
||||
### RelationManagers (Shipment)
|
||||
|
||||
CarrierMappingsRelationManager، TrackingEventsRelationManager
|
||||
|
||||
---
|
||||
|
||||
## ۸. Imports / Exports
|
||||
## ۸. سایر اجزای لاراول
|
||||
|
||||
| # | فایل | فاز |
|
||||
|---|------|-----|
|
||||
| 1 | `app/Imports/OldShipmentsImport.php` | ۰ |
|
||||
| 2 | `app/Imports/ShippingRatesImport.php` | ۰ |
|
||||
| 3 | `app/Exports/ShippingRatesTemplateExport.php` | ۳ |
|
||||
| # | فایل | توضیح |
|
||||
|---|------|-------|
|
||||
| 1 | `Imports/OldShipmentsImport.php` | ایمپورت مرسولات تاریخی |
|
||||
| 2 | `Imports/ShippingRatesImport.php` | ایمپورت نرخها (۵ شیت) |
|
||||
| 3 | `Exports/ShippingRatesTemplateExport.php` | قالب اکسل نرخها |
|
||||
| 4 | `Http/Middleware/ApiKeyMiddleware.php` | احراز API Key |
|
||||
| 5 | `Console/Commands` | ifnex:import:rates, ifnex:import:shipments, ifnex:import:tracking, ifnex:sync-wp-users, ifnex:update-rates, ifnex:token (+ ifnex:debug:import) |
|
||||
| 6 | `config/ifnex.php` + `config/cors.php` | تنظیمات اختصاصی |
|
||||
| 7 | `views/pdfs/awb.blade.php` | بارنامه با بارکد |
|
||||
| 8 | `views/pdfs/invoice.blade.php` | فاکتور (PARCEL) |
|
||||
| 9 | `views/pdfs/label.blade.php` | لیبل A5 با بارکد |
|
||||
| 10 | `views/pdfs/import_invoice.blade.php` | فاکتور واردات (مطابق شیت ENG) |
|
||||
| 11 | `database/seeders/` | CountriesTableSeeder، SystemSettingSeeder، RoleAndPermissionSeeder، SampleShippingRatesSeeder، SampleDataSeeder، DatabaseSeeder |
|
||||
|
||||
---
|
||||
|
||||
## ۹. Middleware
|
||||
## ۹. وردپرس — پلاگین IFNEX Bridge
|
||||
|
||||
| # | فایل | فاز |
|
||||
|---|------|-----|
|
||||
| 1 | `app/Http/Middleware/ApiKeyMiddleware.php` | ۰ |
|
||||
| # | فایل | توضیح |
|
||||
|---|------|-------|
|
||||
| 1 | `ifnex-bridge.php` | فایل اصلی + صفحه تنظیمات + enqueue ها |
|
||||
| 2 | `includes/api-client.php` | کلاینت API ترکینگ |
|
||||
| 3 | `includes/user-bridge.php` | Bridge Auth + توکن Sanctum + هندلرهای AJAX (کیف پول، سفارش، پرداخت، کشورها) |
|
||||
| 4 | `includes/shortcodes.php` | ۱۰+ شورتکد پورتال مشتری (~۱۴۰۰ خط) |
|
||||
| 5 | `includes/tracking-form.php` | فرم رهگیری + هندلر AJAX |
|
||||
| 6 | `assets/css/ifnex-bridge.css` | استایل رهگیری/کیف پول/تراکنش |
|
||||
| 7 | `assets/css/ifnex-orders.css` | استایل فرم سفارش/داشبورد/پرداخت |
|
||||
| 8 | `assets/js/ifnex-order-form.js` | فرم ۵ مرحلهای (بستهها + اقلام + محاسبه) |
|
||||
|
||||
**شورتکدها:** `[ifnex_tracking_form]`, `[ifnex_tracking_status]`, `[ifnex_customer_dashboard]`, `[ifnex_orders_list]`, `[ifnex_order_form]`, `[ifnex_order_detail]`, `[ifnex_order_payment]`, `[ifnex_user_profile]`, `[ifnex_wallet_balance]`, `[ifnex_transactions]`
|
||||
⚠️ `[ifnex_wallet_charge]` هنوز ثبت نشده (صفحه /wallet/ خراب است).
|
||||
|
||||
---
|
||||
|
||||
## ۱۰. Enums
|
||||
## ۱۰. وردپرس — قالب IFNEX
|
||||
|
||||
| # | فایل | فاز |
|
||||
|---|------|-----|
|
||||
| 1 | `app/Enums/ShipmentStatus.php` | ۰ |
|
||||
| 2 | `app/Enums/ShipmentDirection.php` | ۰ |
|
||||
| 3 | `app/Enums/ShipmentType.php` | ۰ |
|
||||
| # | فایل | توضیح |
|
||||
|---|------|-------|
|
||||
| 1 | `style.css` | دیزاینسیستم کامل (~۵۹KB) |
|
||||
| 2 | `functions.php` | پشتیبانیها، منوها، Polylang، enqueue |
|
||||
| 3 | `header.php` / `footer.php` | سربرگ/پابرگ با سوییچ زبان |
|
||||
| 4 | `front-page.php` | لندینگ اصلی (Hero + خدمات + CTA) |
|
||||
| 5 | `template-login.php` | صفحه ورود سفارشی |
|
||||
| 6 | `inc/customizer.php` | تنظیمات قالب (لوگو، متنها FA/EN) |
|
||||
| 7 | `inc/enqueue.php` | (stub) |
|
||||
| 8 | `assets/js/main.js` | افکتها + ریدایرکت رهگیری Hero |
|
||||
| 9 | `template-parts/` | ۶ پارشل (در حال حاضر استفاده نمیشوند) |
|
||||
| 10 | `404.php`, `index.php`, `page.php`, `single.php`, `archive.php` | قالبهای عمومی |
|
||||
|
||||
---
|
||||
|
||||
## ۱۱. PDF Views
|
||||
## ۱۱. صفحات وردپرس و شورتکدها
|
||||
|
||||
| # | فایل | فاز |
|
||||
|---|------|-----|
|
||||
| 1 | `resources/views/pdfs/awb.blade.php` | ۱ |
|
||||
| 2 | `resources/views/pdfs/label.blade.php` | ۱ |
|
||||
| 3 | `resources/views/pdfs/invoice.blade.php` | ۱ |
|
||||
| آدرس | شورتکد | وضعیت |
|
||||
|------|---------|--------|
|
||||
| `/my-account/` | `[ifnex_customer_dashboard]` | ✅ (تبها: dashboard, orders, new-order, wallet, transactions, tracking, profile) |
|
||||
| `/new-order/` | `[ifnex_order_form]` | ✅ |
|
||||
| `/my-orders/` | `[ifnex_orders_list]` | ✅ |
|
||||
| `/order-detail/` | `[ifnex_order_detail]` | ✅ |
|
||||
| `/order-payment/` | `[ifnex_order_payment]` | ✅ |
|
||||
| `/tracking/` | `[ifnex_tracking_form]` | ✅ |
|
||||
| `/wallet/` | `[ifnex_wallet_charge]` | ❌ شورتکد ثبت نشده |
|
||||
|
||||
---
|
||||
> مجموع: **۴۰ migration، ۲۲ مدل، ۹ Enum، ۱۳ کنترلر API، ۹ سرویس، ۱۶ Resource فیلمنت، ۱۰+ شورتکد وردپرس**
|
||||
|
||||
## ۱۲. Routes
|
||||
|
||||
| # | فایل | فاز |
|
||||
|---|------|-----|
|
||||
| 1 | `routes/api.php` | ۰+۱+۲ |
|
||||
| 2 | `routes/web.php` | ۱ |
|
||||
|
||||
---
|
||||
|
||||
## ۱۳. Config
|
||||
|
||||
| # | فایل | فاز |
|
||||
|---|------|-----|
|
||||
| 1 | `config/ifnex.php` | ۰ |
|
||||
| 2 | `config/cors.php` | ۰ |
|
||||
|
||||
---
|
||||
|
||||
## ۱۴. وردپرس — پلاگین IFNEX Bridge
|
||||
|
||||
| # | فایل | فاز |
|
||||
|---|------|-----|
|
||||
| 1 | `ifnex-bridge/ifnex-bridge.php` | ۱ |
|
||||
| 2 | `ifnex-bridge/includes/api-client.php` | ۰ |
|
||||
| 3 | `ifnex-bridge/includes/user-bridge.php` | ۱+۲+۳ |
|
||||
| 4 | `ifnex-bridge/includes/shortcodes.php` | ۱+۲+۳ |
|
||||
| 5 | `ifnex-bridge/includes/tracking-form.php` | ۰ |
|
||||
| 6 | `ifnex-bridge/assets/css/ifnex-orders.css` | ۱+۲+۳ |
|
||||
| 7 | `ifnex-bridge/assets/css/ifnex-bridge.css` | ۰ |
|
||||
| 8 | `ifnex-bridge/assets/js/ifnex-order-form.js` | ۱+۳ |
|
||||
|
||||
---
|
||||
|
||||
## ۱۵. وردپرس — قالب IFNEX
|
||||
|
||||
| # | فایل | فاز |
|
||||
|---|------|-----|
|
||||
| 1 | `ifnex/style.css` | ۱ |
|
||||
| 2 | `ifnex/functions.php` | ۱ |
|
||||
| 3 | `ifnex/header.php` | ۱ |
|
||||
| 4 | `ifnex/footer.php` | ۱ |
|
||||
| 5 | `ifnex/front-page.php` | ۱ |
|
||||
| 6 | `ifnex/page.php` | ۱ |
|
||||
| 7 | `ifnex/template-login.php` | ۱ |
|
||||
| 8 | `ifnex/template-parts/hero.php` | ۱ |
|
||||
| 9 | `ifnex/template-parts/services.php` | ۱ |
|
||||
| 10 | `ifnex/template-parts/how-it-works.php` | ۱ |
|
||||
| 11 | `ifnex/template-parts/stats.php` | ۱ |
|
||||
| 12 | `ifnex/template-parts/testimonials.php` | ۱ |
|
||||
| 13 | `ifnex/template-parts/cta.php` | ۱ |
|
||||
| 14 | `ifnex/inc/customizer.php` | ۱ |
|
||||
| 15 | `ifnex/inc/enqueue.php` | ۱ |
|
||||
| 16 | `ifnex/assets/css/main.css` | ۱ |
|
||||
| 17 | `ifnex/assets/js/main.js` | ۱ |
|
||||
|
||||
---
|
||||
|
||||
## ۱۶. Seeders
|
||||
|
||||
| # | فایل | فاز |
|
||||
|---|------|-----|
|
||||
| 1 | `database/seeders/DatabaseSeeder.php` | ۰ |
|
||||
| 2 | `database/seeders/CountriesTableSeeder.php` | ۰ |
|
||||
| 3 | `database/seeders/SystemSettingSeeder.php` | ۰ |
|
||||
|
||||
---
|
||||
|
||||
> مجموع تقریبی: **۱۰۰+ فایل** بین لاراول و وردپرس
|
||||
> 2026 VernaSoft Group. Internal use only.
|
||||
|
||||
@ -1,8 +1,8 @@
|
||||
# نقشه راه پروژه IFNEX
|
||||
|
||||
> **آخرین بروزرسانی:** 2026-08-29
|
||||
> **آخرین بروزرسانی:** 2026-09-10
|
||||
> **توسعهدهنده:** VernaSoft Group — Kazem Alghasi
|
||||
> **وضعیت کلی:** فاز ۰، ۱، ۲، ۳ و ۳.۵ تکمیل شد ✅
|
||||
> **وضعیت کلی:** فاز ۰، ۱، ۲، ۳ و ۳.۵ تکمیل شد ✅ — فاز ۳.۶ در حال تکمیل (۸۰٪) 🟡
|
||||
|
||||
---
|
||||
|
||||
@ -15,10 +15,11 @@
|
||||
| فاز ۲ | پرداخت و کیف پول | ✅ تکمیل شده | 100% |
|
||||
| فاز ۳ | یکپارچهسازی و بهبود | ✅ تکمیل شده | 100% |
|
||||
| **فاز ۳.۵** | **اصلاحات اساسی** | ✅ تکمیل شده (۹۰%) | 90% |
|
||||
| **فاز ۳.۶** | **اصلاحات جلسه کارفرما** | 🟡 در حال تکمیل (۸۰%) | 80% |
|
||||
| فاز ۴ | سیستم نمایندگی | 📋 مطالعاتی | 0% |
|
||||
| فاز ۵ | تجاریسازی و Premium | 📋 مطالعاتی | 0% |
|
||||
|
||||
> **نکته:** فاز ۳.۵ شامل Multi-Package، فرم Invoice و تست ترکینگ است. تنها مورد باقیمانده (پشتیبانی چندزبانه i18n) به زمان دیپلوی منتقل شد.
|
||||
> **نکته:** فاز ۳.۵ شامل Multi-Package، فرم Invoice و تست ترکینگ است. تنها مورد باقیمانده (پشتیبانی چندزبانه i18n) به زمان دیپلوی منتقل شد. فاز ۳.۶ شامل تغییرات درخواستی کارفرما پس از جلسه ارائه است (فلوی تأیید سفارش، تعهدنامه، SMS و...).
|
||||
|
||||
---
|
||||
|
||||
@ -204,6 +205,71 @@
|
||||
|
||||
---
|
||||
|
||||
## فاز ۳.۶ — اصلاحات جلسه کارفرما 🟡 (۸۰%)
|
||||
|
||||
**هدف:** پیادهسازی ۱۳ مورد درخواستی کارفرما پس از جلسه ارائه (سپتامبر ۲۰۲۶)
|
||||
|
||||
### ۳.۶.۱ — فلوی تأیید سفارش ✅
|
||||
|
||||
- ✅ ثبت سفارش با وضعیت `pending_approval` — مشتری مستقیم به درگاه نمیرود
|
||||
- ✅ تأیید/رد توسط کارمند از پنل Filament (ShipmentResource) و API (`/staff/orders/{id}/approve|reject`)
|
||||
- ✅ باز شدن گزینههای پرداخت (کیف پول / درگاه) فقط بعد از `approved`
|
||||
- ✅ گذار خودکار به `processed` بعد از پرداخت موفق (callback درگاه با `is_order_payment`)
|
||||
- ✅ هندلر AJAX پرداخت کیف پول در وردپرس (`ifnex_pay_order_wallet`)
|
||||
- ✅ رفع ستونهای تاریخچه وضعیت در StaffOrderController (`from_status/to_status`)
|
||||
|
||||
### ۳.۶.۲ — تعهدنامه و اسناد سفارش ✅
|
||||
|
||||
- ✅ مدل + migration `shipment_commitment_forms` + مدل `CommitmentForm` برای فرمهای پایه
|
||||
- ✅ آپلود تعهدنامه توسط مدیر (CommitmentFormResource در Filament)
|
||||
- ✅ API لیست تعهدنامهها + آپلود فایل امضاشده توسط مشتری
|
||||
- ✅ شبکه دانلود اسناد (AWB / Invoice / Label / فاکتور واردات) در جزئیات سفارش وردپرس
|
||||
- ⏳ چک مالکیت (ownership) روی دانلود PDF/تعهدنامه — باقیمانده
|
||||
|
||||
### ۳.۶.۳ — مالی و اعتبار 🟡
|
||||
|
||||
- ✅ مانده حساب (موجودی منهای بدهیهای تأییدشده) در پروفایل مشتری
|
||||
- ✅ وضعیت مالی مشتری برای کارمند/مدیر: جستجو + بدهی به تفکیک ارز + تراکنشها و سفارشات اخیر (رفع باگ `user_id`)
|
||||
- ✅ فاکتور واردات: فیلدهای جدید shipments + قالب PDF مطابق شیت ENG Invoice
|
||||
- 🟡 سیستم اعتبار: اسکلت ساخته شده (`credit_limit/credit_used` + CustomerCreditResource) ولی اکشنها خراباند و نیاز کارفرما «بدهی به ارز سفارش» است → نیازمند بازطراحی
|
||||
- ⏳ سند پیشنهادی سیستم مالی (درخواست ۱۳)
|
||||
|
||||
### ۳.۶.۴ — عملیاتی و مدیریت ✅
|
||||
|
||||
- ✅ ایمپورت گروهی وضعیت ترکینگ با CSV (صفحه BulkTrackingImport در پنل)
|
||||
- ✅ Audit Log: trait `Auditable` روی مدلهای اصلی + AuditLogResource
|
||||
- ✅ ShipmentStatusHistory با `from_status/to_status/reason`
|
||||
- 🟡 چکلیست کارمند: Resource ساخته شده ولی خودکار بعد از تأیید ساخته نمیشود و به صفحه سفارش وصل نیست
|
||||
|
||||
### ۳.۶.۵ — SMS کاوهنگار ✅
|
||||
|
||||
- ✅ KavenegarSmsService + کانال SMS + ۴ نوتیفیکیشن (تأیید سفارش، رد سفارش، پرداخت موفق، بروزرسانی ترکینگ)
|
||||
- ✅ ShipmentObserver برای تریگر خودکار روی تغییر وضعیت
|
||||
- ✅ تنظیمات پنل: کلید API + سوییچ هر نوع پیام (SystemSetting)
|
||||
- ✅ API تأیید موبایل (`/verify/send-code`, `/verify/check-code`)
|
||||
- ⏳ اتصال تایید موبایل به ثبتنام وردپرس (صفحه ثبتنام وجود ندارد)
|
||||
|
||||
### ۳.۶.۶ — اصلاحات UI فرم سفارش ✅
|
||||
|
||||
- ✅ رفع باگ «مرحله ۲ لود نمیشود» — ریشه: div بستهنشده در shortcodes.php (مراحل داخل هم nest شده بودند)؛ حذف هکهای MutationObserver/setInterval
|
||||
- ✅ رفع محاسبه مجموع USD اقلام گمرکی (فقدان `data-item-id`)
|
||||
- ✅ رفع رفتن به مرحله ۵ بعد از محاسبه قیمت
|
||||
- ✅ ریدایرکت رهگیری Hero از `ifnexConfig.homeUrl` (حذف مسیر هاردکد)
|
||||
- ✅ عمومیسازی endpoint `/countries`
|
||||
- ⏳ نمایش وزن واقعی/حجمی در خلاصه قیمت (API فیلد `weight` را برنمیگرداند)
|
||||
|
||||
### ۳.۶.۷ — باقیمانده فاز ۳.۶ ⏳
|
||||
|
||||
1. تست انتهای فلو: آپلود تعهدنامه → تأیید کارمند → پرداخت کیف پول/درگاه
|
||||
2. امنیت: چک نقش روتهای `/staff/*`، چک مالکیت PDF، ثبت شورتکد `[ifnex_wallet_charge]` (صفحه /wallet/ خراب است)، محدودسازی `GET /discount-codes`، rate limiting
|
||||
3. بازطراحی سیستم اعتبار (بدهی چندارزی)
|
||||
4. چکلیست خودکار کارمند + نمایش در صفحه سفارش
|
||||
5. سند پیشنهادی سیستم مالی
|
||||
6. پاکسازی هکهای موقت (opcache_reset/header، cache-buster `time()`، `!important` ها، صفحات تستی)
|
||||
7. چندزبانه (i18n) — زمان دیپلوی
|
||||
|
||||
---
|
||||
|
||||
## فاز ۴ (آینده) — سیستم نمایندگی 📋
|
||||
|
||||
**وضعیت:** طرح مطالعاتی آماده — منتظر تصمیم کارفرما
|
||||
@ -432,10 +498,14 @@
|
||||
- سیستم نوتیفیکیشن دیتابیس برای ادمین و مشتری
|
||||
- رابط کاربری مدرن و واکنشگرا
|
||||
|
||||
### ⚠️ نواقص باقیمانده (فاز ۳.۵)
|
||||
- Multi-Package در فرم سفارش مشتری
|
||||
- فرم Invoice برای محمولههای PARCEL
|
||||
- پشتیبانی کامل چندزبانه (i18n)
|
||||
### ⚠️ نواقص باقیمانده (فاز ۳.۶)
|
||||
- تست انتهای فلو (تعهدنامه → تأیید → پرداخت)
|
||||
- امنیت روتهای staff و مالکیت PDFها + شورتکد `[ifnex_wallet_charge]`
|
||||
- بازطراحی سیستم اعتبار (بدهی چندارزی مطابق نیاز کارفرما)
|
||||
- چکلیست خودکار کارمند + اتصال به صفحه سفارش
|
||||
- سند پیشنهادی سیستم مالی
|
||||
- پاکسازی هکهای موقت دیباگ
|
||||
- پشتیبانی کامل چندزبانه (i18n) — زمان دیپلوی
|
||||
- تست نهایی روی سرور
|
||||
|
||||
### 📋 برای آینده
|
||||
|
||||
@ -1,9 +1,11 @@
|
||||
# 🚨 STATUS.md — این فایل را اول بخوانید
|
||||
|
||||
> **آخرین بهروزرسانی:** 2026-08-10 13:08 (Asia/Tehran)
|
||||
> **فاز در حال اجرا:** فاز ۴ (VPS پل + API ترکینگ زنده)
|
||||
> ⚠️ **بهروزرسانی 2026-09-10:** این سند تا **10 آگوست 2026** بهروزرسانی شده و تاریخچه فازهای ۰ تا ۳ را پوشش میدهد. **وضعیت جاری پروژه (فاز ۳.۵ ✅ و فاز ۳.۶ — اصلاحات جلسه کارفرما 🟡 ۸۰٪) در [`AGENT.md`](../AGENT.md) و [`IFNEX_Roadmap.md`](IFNEX_Roadmap.md) نگهداری میشود** — برای وضعیت فعلی و کارهای باقیمانده آن دو سند را ببینید. بخشهای پایین این فایل را بهعنوان تاریخچه و مرجع خط قرمزها بخوانید.
|
||||
|
||||
> **آخرین بهروزرسانی محتوا:** 2026-08-10 13:08 (Asia/Tehran)
|
||||
> **فاز در حال اجرا (فعلی):** فاز ۳.۶ — اصلاحات جلسه کارفرما (تاریخچه: این سند تا فاز ۳ را ثبت کرده است)
|
||||
> **توسعهدهنده:** VernaSoft Group — Kazem Alghasi
|
||||
> **وضعیت کلی پروژه:** فاز ۰ کامل — فاز ۱ کامل — فاز ۲ کامل — فاز ۳ کامل
|
||||
> **وضعیت کلی پروژه:** فاز ۰ کامل — فاز ۱ کامل — فاز ۲ کامل — فاز ۳ کامل — فاز ۳.۵ کامل — فاز ۳.۶ در حال تکمیل (۸۰٪)
|
||||
|
||||
---
|
||||
|
||||
@ -13,11 +15,12 @@
|
||||
|
||||
| فایل | وضعیت | اقدام |
|
||||
|------|-------|-------|
|
||||
| `01_Documents/Phase0_Proposal.md` | ✅ **معتبر و مرجع اصلی** | حتماً کامل بخوانید |
|
||||
| `01_Documents/PRD_v2.md` | ❌ قدیمی و ناقص | فقط برای مرجع تاریخی — به اسکیمای دیتابیس آن اعتماد نکنید |
|
||||
| `01_Documents/Project_Roadmap.md` | ❌ قدیمی (۳ فازی) | فقط برای مرجع تاریخی — به فازبندی آن اعتماد نکنید |
|
||||
| `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` (ریشه) | ✅ بهروز (نسخه ۲) | برای نمای کلی بخوانید |
|
||||
| `README.md` (ریشه) | ✅ بهروز | برای نمای کلی بخوانید |
|
||||
| `AGENT.md` (ریشه) | ✅ **مرجع اصلی وضعیت و قراردادها** | اول این را بخوانید |
|
||||
|
||||
> 🔴 **قانون طلایی:** هرجا بین اسناد تناقض دیدی، به `Phase0_Proposal.md` اعتماد کن. اسناد قدیمی فقط برای فهم تاریخچهی تصمیمات نگه داشته شدهاند.
|
||||
|
||||
|
||||
@ -8,7 +8,7 @@
|
||||
[](https://php.net)
|
||||
[](https://filamentphp.com)
|
||||
[](https://mysql.com)
|
||||
[]()
|
||||
[]()
|
||||
|
||||
---
|
||||
|
||||
@ -39,6 +39,9 @@
|
||||
### ۵. Multi-Package و Invoice (فاز ۳.۵)
|
||||
پشتیبانی از چند بسته در یک سفارش، فرم اقلام گمرکی (Invoice) برای محمولههای PARCEL، و محاسبه خودکار وزن حجمی از ابعاد.
|
||||
|
||||
### ۶. فلوی تأیید سفارش و اعلانها (فاز ۳.۶)
|
||||
ثبت سفارش با وضعیت `pending_approval` → تأیید/رد توسط کارمند (پنل یا API) → باز شدن پرداخت → `processed` بعد از پرداخت. بههمراه تعهدنامهها (آپلود مدیر، دانلود/امضا/آپلود مشتری)، دانلود PDFها در پورتال مشتری، وضعیت مالی مشتری برای کارمندان، Audit Log و اعلانهای SMS کاوهنگار.
|
||||
|
||||
---
|
||||
|
||||
## 🚀 نصب و راهاندازی سریع
|
||||
@ -130,33 +133,52 @@ WALLET_ALLOW_WITHDRAWAL=false
|
||||
|
||||
## 📡 API Endpoints
|
||||
|
||||
### 🔓 API عمومی (با API Key)
|
||||
### 🔓 API عمومی (با API Key یا بدون احراز هویت)
|
||||
|
||||
| متد | Endpoint | توضیح |
|
||||
|------|----------|--------|
|
||||
| GET | `/api/v1/track/{awb_no}` | رهگیری مرسوله |
|
||||
| GET | `/api/v1/track/{awb_no}` | رهگیری مرسوله (API Key) |
|
||||
| POST | `/api/v1/calculate` | محاسبه قیمت |
|
||||
| GET | `/api/v1/discount-codes` | لیست کدهای تخفیف |
|
||||
| GET | `/api/v1/countries` | لیست کشورها با پیششماره (عمومی) |
|
||||
| GET | `/api/v1/discount-codes` | لیست کدهای تخفیف ⚠️ باید محدود شود |
|
||||
| POST | `/api/v1/discount-codes/validate` | اعتبارسنجی کد تخفیف |
|
||||
| POST | `/api/v1/bridge/login` | Bridge Auth (وردپرس ← لاراول) |
|
||||
| POST | `/api/v1/auth/login` | ورود مشتری (ایمیل + رمز) |
|
||||
| POST | `/api/v1/auth/logout` | خروج (Sanctum) |
|
||||
| GET | `/api/v1/commitment-forms[/{direction}]` | لیست فرمهای تعهدنامه فعال |
|
||||
| POST | `/api/v1/verify/send-code` | ارسال کد تأیید موبایل (SMS) |
|
||||
| POST | `/api/v1/verify/check-code` | بررسی کد تأیید موبایل |
|
||||
|
||||
### 🔐 API مشتری (Sanctum Token)
|
||||
|
||||
| متد | Endpoint | توضیح |
|
||||
|------|----------|--------|
|
||||
| GET | `/api/v1/customer/profile` | پروفایل + آمار سفارشات |
|
||||
| GET | `/api/v1/customer/countries` | لیست کشورها با پیششماره |
|
||||
| GET | `/api/v1/customer/profile` | پروفایل + آمار + مانده حساب |
|
||||
| GET | `/api/v1/customer/orders` | لیست سفارشات (paginated) |
|
||||
| POST | `/api/v1/customer/orders` | ثبت سفارش جدید |
|
||||
| POST | `/api/v1/customer/orders` | ثبت سفارش جدید (با packages[] و items[]) — وضعیت `pending_approval` |
|
||||
| GET | `/api/v1/customer/orders/{id}` | جزئیات سفارش |
|
||||
| POST | `/api/v1/customer/orders/{id}/cancel` | لغو سفارش |
|
||||
| POST | `/api/v1/customer/orders/{id}/pay-wallet` | پرداخت با کیف پول |
|
||||
| POST | `/api/v1/customer/orders/{id}/pay-gateway` | پرداخت با درگاه |
|
||||
| GET | `/api/v1/customer/orders/{id}/pdf/awb` | دانلود AWB |
|
||||
| GET | `/api/v1/customer/orders/{id}/pdf/invoice` | دانلود فاکتور (فقط PARCEL) |
|
||||
| GET | `/api/v1/customer/orders/{id}/pdf/label` | دانلود لیبل |
|
||||
| GET | `/api/v1/customer/orders/{id}/pdf/import-invoice` | دانلود فاکتور واردات |
|
||||
| GET | `/api/v1/customer/orders/{id}/commitment-forms` | تعهدنامههای سفارش + وضعیت آپلود |
|
||||
| POST | `/api/v1/customer/orders/{id}/commitment-forms/{form}/upload` | آپلود تعهدنامه امضاشده |
|
||||
| POST | `/api/v1/customer/orders/{id}/pay-wallet` | پرداخت با کیف پول (فقط بعد از تأیید) |
|
||||
| POST | `/api/v1/customer/orders/{id}/pay-gateway` | پرداخت با درگاه (فقط بعد از تأیید) |
|
||||
| GET | `/api/v1/customer/notifications` | لیست اعلانها |
|
||||
| POST | `/api/v1/customer/notifications/{id}/read` | علامتگذاری خواندهشده |
|
||||
|
||||
### 👷 API کارمندان (Sanctum Token) ⚠️ چک نقش در حال تکمیل
|
||||
|
||||
| متد | Endpoint | توضیح |
|
||||
|------|----------|--------|
|
||||
| GET | `/api/v1/staff/orders/pending-approval` | سفارشات در انتظار تأیید |
|
||||
| POST | `/api/v1/staff/orders/{id}/approve` | تأیید سفارش |
|
||||
| POST | `/api/v1/staff/orders/{id}/reject` | رد سفارش |
|
||||
| GET | `/api/v1/staff/customers/search` | جستجوی مشتری |
|
||||
| GET | `/api/v1/staff/customers/{id}/financial-status` | وضعیت مالی مشتری (بدهی به تفکیک ارز) |
|
||||
|
||||
### 💰 API کیف پول (Sanctum Token)
|
||||
|
||||
| متد | Endpoint | توضیح |
|
||||
@ -215,10 +237,14 @@ curl -X POST http://localhost:8000/api/v1/customer/orders \
|
||||
```
|
||||
04_Laravel/
|
||||
├── app/
|
||||
│ ├── Enums/ # ShipmentStatus, ShipmentDirection, ShipmentType, PaymentGateway, TransactionStatus
|
||||
│ ├── Enums/ # ShipmentStatus (۱۲ وضعیت), ShipmentDirection, ShipmentType, PaymentGateway, TransactionType, TransactionStatus, CarrierCode, TrackingSource, UserRole
|
||||
│ ├── Filament/
|
||||
│ │ ├── Resources/ # 10+ Resources
|
||||
│ │ │ ├── ShipmentResource/ # مدیریت مرسولهها (با RelationManagers)
|
||||
│ │ ├── Resources/ # ۱۶ Resources
|
||||
│ │ │ ├── ShipmentResource/ # مدیریت مرسولهها + اکشن تأیید/رد + RelationManagers
|
||||
│ │ │ ├── ShipmentChecklistResource/ # چکلیست کارمند
|
||||
│ │ │ ├── CommitmentFormResource/ # فرمهای تعهدنامه (آپلود مدیر)
|
||||
│ │ │ ├── CustomerCreditResource/ # اعتبار مشتریان
|
||||
│ │ │ ├── AuditLogResource/ # لاگ تغییرات
|
||||
│ │ │ ├── CountryResource/ # مدیریت کشورها + calling_code
|
||||
│ │ │ ├── ShippingRateResource/
|
||||
│ │ │ ├── CurrencyResource/ # مدیریت ارزها
|
||||
@ -231,11 +257,12 @@ curl -X POST http://localhost:8000/api/v1/customer/orders \
|
||||
│ │ │ ├── ExchangeRateHistoryResource/
|
||||
│ │ │ └── RoleResource/ # مدیریت نقشها
|
||||
│ │ ├── Pages/
|
||||
│ │ │ ├── IfnexSettingsPage.php # تنظیمات سیستم (key-value)
|
||||
│ │ │ ├── IfnexSettingsPage.php # تنظیمات سیستم + کلیدهای SMS
|
||||
│ │ │ ├── PriceTestPage.php # تست محاسبه قیمت
|
||||
│ │ │ ├── ImportRatesPage.php # آپلود اکسل نرخها
|
||||
│ │ │ ├── BulkTrackingImport.php # ایمپورت گروهی وضعیت ترکینگ (CSV)
|
||||
│ │ │ └── Reports/FinancialReport.php # گزارش مالی
|
||||
│ │ └── Widgets/ # Dashboard Widgets
|
||||
│ │ └── Widgets/ # DashboardInfo, ExchangeRate, FinanceOverview, WalletStats, ...
|
||||
│ ├── Http/
|
||||
│ │ ├── Controllers/
|
||||
│ │ │ ├── Api/
|
||||
@ -244,54 +271,70 @@ curl -X POST http://localhost:8000/api/v1/customer/orders \
|
||||
│ │ │ │ ├── TrackController.php # رهگیری عمومی
|
||||
│ │ │ │ ├── PricingController.php # محاسبه قیمت
|
||||
│ │ │ │ ├── DiscountCodeController.php
|
||||
│ │ │ │ ├── PaymentController.php # درگاه + Callback
|
||||
│ │ │ │ ├── PaymentController.php # درگاه + Callback (با فلوی تأیید سفارش)
|
||||
│ │ │ │ ├── MockGatewayController.php # شبیهسازی درگاه
|
||||
│ │ │ │ ├── WalletController.php
|
||||
│ │ │ │ ├── StaffOrderController.php # تأیید/رد سفارشات
|
||||
│ │ │ │ ├── CustomerFinancialController.php # وضعیت مالی مشتری
|
||||
│ │ │ │ ├── CommitmentFormController.php # تعهدنامهها + آپلود امضاشده
|
||||
│ │ │ │ ├── MobileVerificationController.php # تأیید موبایل (SMS)
|
||||
│ │ │ │ └── Customer/
|
||||
│ │ │ │ └── CustomerOrderController.php # سفارشات + نوتیفیکیشن
|
||||
│ │ │ ├── ShipmentPdfController.php # AWB/Invoice/Label PDFs
|
||||
│ │ │ └── OrderController.php # صفحات public سفارش
|
||||
│ │ │ │ └── CustomerOrderController.php # سفارشات مشتری (packages/items/PDF/تعهدنامه)
|
||||
│ │ │ ├── ShipmentPdfController.php # AWB/Invoice/Label/Import-Invoice PDFs
|
||||
│ │ │ └── OrderController.php # فلوی legacy Blade (deprecated)
|
||||
│ │ └── Middleware/
|
||||
│ │ └── ApiKeyMiddleware.php # برای APIهای عمومی
|
||||
│ ├── Models/ # 13 مدل Eloquent
|
||||
│ ├── Notifications/ # ShipmentUpdatedNotification
|
||||
│ ├── Models/ # ۲۲ مدل Eloquent
|
||||
│ ├── Notifications/ # DB + SMS: ShipmentApprovedSms, ShipmentRejectedSms, PaymentSuccessSms, TrackingUpdatedSms, SmsChannel
|
||||
│ ├── Observers/
|
||||
│ │ └── ShipmentObserver.php # تریگر نوتیفیکیشن/SMS روی تغییر وضعیت
|
||||
│ ├── Traits/
|
||||
│ │ └── Auditable.php # لاگ خودکار تغییرات مدلها
|
||||
│ ├── Services/
|
||||
│ │ ├── PriceCalculatorService.php # موتور قیمتگذاری
|
||||
│ │ ├── WalletService.php # مدیریت کیف پول
|
||||
│ │ ├── OrderPaymentService.php # پرداخت سفارش
|
||||
│ │ ├── OrderPaymentService.php # پرداخت سفارش (کیف پول + درگاه)
|
||||
│ │ ├── ZarinpalService.php # درگاه واقعی
|
||||
│ │ ├── MockZarinpalService.php # درگاه شبیهسازی
|
||||
│ │ ├── KavenegarSmsService.php # سرویس پیامک
|
||||
│ │ ├── ExchangeRateService.php
|
||||
│ │ ├── PdfService.php # تولید PDF با بارکد
|
||||
│ │ └── TrackingService.php
|
||||
│ ├── Imports/ # Excel imports (OldShipments, ShippingRates)
|
||||
│ ├── Exports/ # ShippingRatesTemplateExport
|
||||
│ └── Console/Commands/
|
||||
│ ├── ImportShippingRates.php
|
||||
│ ├── ImportTrackingData.php
|
||||
│ ├── UpdateExchangeRates.php
|
||||
│ ├── GenerateApiToken.php
|
||||
│ └── SyncWordPressUsers.php
|
||||
│ ├── ifnex:import:rates # ایمپورت نرخها از اکسل
|
||||
│ ├── ifnex:import:shipments # ایمپورت مرسولات تاریخی
|
||||
│ ├── ifnex:import:tracking # ایمپورت دادههای ترکینگ
|
||||
│ ├── ifnex:sync-wp-users # همگامسازی کاربران وردپرس
|
||||
│ ├── ifnex:update-rates # بروزرسانی نرخ ارز (--source=ecb|freecurrencyapi)
|
||||
│ └── ifnex:token # تولید API Token برای ادمین
|
||||
│
|
||||
├── database/
|
||||
│ ├── migrations/ # 23 migrations
|
||||
│ ├── migrations/ # ۴۰ migration
|
||||
│ └── seeders/
|
||||
│ ├── CountrySeeder.php # 233 کشور + calling_code
|
||||
│ ├── CountriesTableSeeder.php # ۲۳۳ کشور + calling_code
|
||||
│ ├── SystemSettingSeeder.php
|
||||
│ ├── RoleAndPermissionSeeder.php
|
||||
│ ├── SampleShippingRatesSeeder.php
|
||||
│ ├── SampleDataSeeder.php
|
||||
│ └── DatabaseSeeder.php
|
||||
│
|
||||
├── resources/views/
|
||||
│ ├── pdfs/
|
||||
│ │ ├── awb.blade.php # Air Waybill PDF
|
||||
│ │ ├── invoice.blade.php # فاکتور PDF
|
||||
│ │ └── label.blade.php # لیبل پستی با بارکد
|
||||
│ └── filament/
|
||||
│ └── pages/ # صفحات Filament
|
||||
│ │ ├── awb.blade.php # Air Waybill PDF با بارکد
|
||||
│ │ ├── invoice.blade.php # فاکتور PDF (PARCEL)
|
||||
│ │ ├── label.blade.php # لیبل A5 با بارکد
|
||||
│ │ └── import-invoice.blade.php # فاکتور واردات (مطابق شیت ENG)
|
||||
│ └── filament/pages/ # صفحات Filament
|
||||
│
|
||||
├── routes/
|
||||
│ ├── api.php # 30+ REST API endpoints
|
||||
│ └── web.php # Web + Download Template
|
||||
│ ├── api.php # ۵۰+ REST API endpoint
|
||||
│ └── web.php # Web (PDF قدیمی، payment-result، دانلود template)
|
||||
│
|
||||
└── config/
|
||||
└── ifnex.php # تنظیمات اختصاصی IFNEX
|
||||
├── ifnex.php # تنظیمات اختصاصی IFNEX
|
||||
└── cors.php
|
||||
```
|
||||
|
||||
---
|
||||
@ -317,6 +360,13 @@ curl -X POST http://localhost:8000/api/v1/customer/orders \
|
||||
| WalletActivityLog | wallet_activity_logs | لاگ فعالیتهای کیف پول | ۲ |
|
||||
| DiscountCode | discount_codes | کدهای تخفیف | ۲ |
|
||||
| Payment | payments | پرداختها | ۲ |
|
||||
| CommitmentForm | commitment_forms | فرمهای تعهدنامه (آپلود مدیر) | ۳.۶ |
|
||||
| ShipmentCommitmentForm | shipment_commitment_forms | تعهدنامه امضاشده هر سفارش | ۳.۶ |
|
||||
| ShipmentChecklist | shipment_checklists | چکلیست کارمند برای هر سفارش | ۳.۶ |
|
||||
| AuditLog | audit_logs | لاگ تغییرات مدلها (polymorphic) | ۳.۶ |
|
||||
| Role | roles | نقشها (spatie/laravel-permission) | ۲ |
|
||||
|
||||
**جمع: ۲۲ مدل**
|
||||
|
||||
---
|
||||
|
||||
@ -326,7 +376,11 @@ curl -X POST http://localhost:8000/api/v1/customer/orders \
|
||||
|
||||
| Resource | توضیح | ویژگیها |
|
||||
|----------|--------|---------|
|
||||
| ShipmentResource | مدیریت مرسولهها | جدول + فرم + View + CSV Export + Bulk Actions |
|
||||
| ShipmentResource | مدیریت مرسولهها | جدول + فرم + View + اکشن تأیید/رد + CSV Export + Bulk Actions |
|
||||
| ShipmentChecklistResource | چکلیست کارمند | CRUD — ⚠️ اتصال خودکار به سفارش باقی است |
|
||||
| CommitmentFormResource | تعهدنامهها | آپلود فرم + direction (export/import/both) |
|
||||
| CustomerCreditResource | اعتبار مشتریان | افزایش/کاهش اعتبار — ⚠️ نیازمند رفع و بازطراحی |
|
||||
| AuditLogResource | لاگ تغییرات | مشاهده لاگهای Audit |
|
||||
| CountryResource | مدیریت کشورها | CRUD + calling_code + ۴ زون |
|
||||
| ShippingRateResource | مدیریت تعرفهها | CRUD + فیلتر + Import از اکسل |
|
||||
| CurrencyResource | مدیریت ارزها | CRUD + بروزرسانی خودکار نرخ |
|
||||
@ -336,24 +390,24 @@ curl -X POST http://localhost:8000/api/v1/customer/orders \
|
||||
| PaymentResource | پرداختها | View + بررسی وضعیت |
|
||||
| DiscountCodeResource | کدهای تخفیف | CRUD + اعتبارسنجی |
|
||||
| RoleResource | نقشها | مدیریت Roles + Permissions |
|
||||
| ShipmentItemResource | اقلام گمرکی | CRUD |
|
||||
| ExchangeRateHistoryResource | تاریخچه نرخ ارز | View |
|
||||
|
||||
### RelationManagers
|
||||
### RelationManagers (ثبتشده در ShipmentResource)
|
||||
|
||||
| RelationManager | والد | توضیح |
|
||||
|-----------------|------|--------|
|
||||
| TrackingEventsRelationManager | Shipment | رویدادهای ترکینگ با فیلد source |
|
||||
| CarrierMappingsRelationManager | Shipment | نگاشت شرکتهای حمل |
|
||||
| ItemsRelationManager | Shipment | اقلام گمرکی |
|
||||
| PackagesRelationManager | Shipment | بستههای چندگانه |
|
||||
| StatusHistoriesRelationManager | Shipment | تاریخچه تغییرات وضعیت |
|
||||
| RelationManager | توضیح |
|
||||
|-----------------|-------|
|
||||
| TrackingEventsRelationManager | رویدادهای ترکینگ با فیلد source |
|
||||
| CarrierMappingsRelationManager | نگاشت شرکتهای حمل |
|
||||
|
||||
### صفحات سفارشی
|
||||
|
||||
| صفحه | توضیح |
|
||||
|-------|--------|
|
||||
| IfnexSettingsPage | تنظیمات سیستم (key-value) — نرخ درهم، VAT، حاشیه سود |
|
||||
| PriceTestPage | تست محاسبه قیمت با پارامترهای مختلف |
|
||||
| IfnexSettingsPage | تنظیمات سیستم — نرخ درهم، VAT، حاشیه سود، کلید کاوهنگار و سوییچهای SMS |
|
||||
| PriceTestPage | تست محاسبه قیمت با پارامترهای مختلف — ⚠️ با مقادیر type فعلی خراب است |
|
||||
| ImportRatesPage | آپلود اکسل نرخها + دانلود Template |
|
||||
| BulkTrackingImport | ایمپورت گروهی وضعیت ترکینگ با CSV |
|
||||
| FinancialReport | گزارش مالی (درآمد، تخفیف، کارمزد) |
|
||||
|
||||
---
|
||||
@ -362,15 +416,16 @@ curl -X POST http://localhost:8000/api/v1/customer/orders \
|
||||
|
||||
```bash
|
||||
# Import / Migration
|
||||
php artisan ifnex:import-rates # ایمپورت نرخها از اکسل
|
||||
php artisan ifnex:import-tracking # ایمپورت دادههای ترکینگ تاریخی
|
||||
php artisan ifnex:sync-wp-users # همگامسازی کاربران وردپرس با لاراول
|
||||
php artisan ifnex:import:rates {path} # ایمپورت نرخها از اکسل
|
||||
php artisan ifnex:import:shipments {path} # ایمپورت مرسولات تاریخی از اکسل
|
||||
php artisan ifnex:import:tracking {path} # ایمپورت دادههای ترکینگ
|
||||
php artisan ifnex:sync-wp-users # همگامسازی کاربران وردپرس با لاراول
|
||||
|
||||
# Currency
|
||||
php artisan ifnex:update-exchange-rates # بروزرسانی نرخ ارز از API
|
||||
php artisan ifnex:update-rates # بروزرسانی نرخ ارز (--source=ecb یا freecurrencyapi)
|
||||
|
||||
# Token
|
||||
php artisan ifnex:generate-api-token # تولید API Token برای ادمین
|
||||
php artisan ifnex:token # تولید API Token برای ادمین
|
||||
|
||||
# Standard
|
||||
php artisan migrate # اجرای migrations
|
||||
@ -439,12 +494,16 @@ curl -X POST http://localhost:8000/api/v1/bridge/login \
|
||||
|
||||
## 🚀 مراحل بعدی
|
||||
|
||||
- [ ] تستهای واحد (PHPUnit)
|
||||
- [ ] تستهای Integration (Laravel Dusk)
|
||||
- [ ] تست انتهای فلوی سفارش (تعهدنامه → تأیید → پرداخت)
|
||||
- [ ] امنیت: چک نقش روی `/staff/*`، چک مالکیت PDF/تعهدنامه، rate limiting
|
||||
- [ ] بازطراحی سیستم اعتبار (بدهی چندارزی) + رفع CustomerCreditResource
|
||||
- [ ] چکلیست خودکار کارمند بعد از تأیید سفارش
|
||||
- [ ] رفع PriceTestPage و ثبت شورتکد `[ifnex_wallet_charge]`
|
||||
- [ ] مستندات API (OpenAPI/Swagger)
|
||||
- [ ] اتصال به APIهای ترکینگ زنده
|
||||
- [ ] اتصال به APIهای ترکینگ زنده (فاز ۵)
|
||||
- [ ] سیستم نمایندگی (فاز ۴)
|
||||
- [ ] بهبود گزارشهای مالی
|
||||
|
||||
> وضعیت دقیق و جزئیات فاز ۳.۶: [AGENT.md](../AGENT.md) و [IFNEX_Roadmap.md](../01_Documents/IFNEX_Roadmap.md)
|
||||
|
||||
---
|
||||
|
||||
|
||||
259
AGENT.md
259
AGENT.md
@ -1,18 +1,17 @@
|
||||
# IFNEX Logistics Management System — Agent Guide
|
||||
|
||||
> **هدف:** راهنمای جامع برای دستیار هوش مصنوعی (OpenCode + DeepSeek Flash) جهت درک سریع پروژه، معماری، قراردادها و نکات کلیدی.
|
||||
> **هدف:** راهنمای جامع برای دستیار هوش مصنوعی جهت درک سریع پروژه، معماری، قراردادها و نکات کلیدی.
|
||||
>
|
||||
> **نسخه:** 1.0
|
||||
> **تاریخ:** 2026-09-02
|
||||
> **مدل پیشنهادی:** DeepSeek Flash (تنظیم شده با API)
|
||||
> **نسخه:** 1.1
|
||||
> **تاریخ:** 2026-09-10
|
||||
|
||||
---
|
||||
|
||||
## 🎯 خلاصه پروژه
|
||||
|
||||
سیستم مدیریت لجستیک بینالمللی با معماری Headless (Laravel 11 بهعنوان بکاند، WordPress بهعنوان فرانتاند، Filament 3.3 بهعنوان پنل مدیریت). جایگزین فرآیندهای دستی مبتنی بر اکسل شده و از Multi-Package، فاکتور گمرکی (Invoice)، کیف پول دیجیتال، درگاه پرداخت Zarinpal، تولید PDF با بارکد، و سیستم رهگیری پیشرفته پشتیبانی میکند.
|
||||
سیستم مدیریت لجستیک بینالمللی با معماری Headless (Laravel 11 بهعنوان بکاند، WordPress بهعنوان فرانتاند، Filament 3.3 بهعنوان پنل مدیریت). جایگزین فرآیندهای دستی مبتنی بر اکسل شده و از Multi-Package، فاکتور گمرکی (Invoice)، کیف پول دیجیتال، درگاه پرداخت Zarinpal، تولید PDF با بارکد، فلوی تأیید سفارش، تعهدنامه، SMS کاوهنگار و سیستم رهگیری پیشرفته پشتیبانی میکند.
|
||||
|
||||
**وضعیت فعلی:** فازهای ۰، ۱، ۲، ۳ و ۳.۵ (۹۰٪) تکمیل شدهاند. تنها مورد باقیمانده از فاز ۳.۵، پشتیبانی کامل چندزبانه (i18n) است که به زمان دیپلوی موکول شده است.
|
||||
**وضعیت فعلی:** فازهای ۰، ۱، ۲، ۳ و ۳.۵ تکمیل شدهاند. **فاز ۳.۶ (اصلاحات جلسه کارفرما — فلوی تأیید سفارش، تعهدنامه و دانلود اسناد، SMS کاوهنگار، Audit Log، وضعیت مالی مشتری)** حدود ۸۰٪ انجام شده است؛ فهرست دقیق باقیمانده در بخش «کارهای باقیمانده» همین سند و سکشن فاز ۳.۶ در `01_Documents/IFNEX_Roadmap.md` آمده است. چندزبانه (i18n) همچنان به زمان دیپلوی موکول است.
|
||||
|
||||
---
|
||||
|
||||
@ -23,13 +22,14 @@
|
||||
| **Backend** | Laravel | 11.x |
|
||||
| **PHP** | PHP | ^8.2 (۸.۳ نیز پشتیبانی میشود) |
|
||||
| **Admin Panel** | Filament | 3.3.x |
|
||||
| **Frontend** | WordPress | 7.0.3 + قالب سفارشی IFNEX |
|
||||
| **Frontend** | WordPress | 7.x + قالب سفارشی IFNEX |
|
||||
| **Authentication** | Laravel Sanctum + Bridge Auth | بدون رمز عبور (API Key مشترک) |
|
||||
| **Payment** | Zarinpal + Mock Gateway (تست) | کلید sandbox برای تست لوکال |
|
||||
| **PDF & Barcode** | Dompdf + picqer/php-barcode-generator | تولید AWB، Invoice، Label |
|
||||
| **PDF & Barcode** | Dompdf + picqer/php-barcode-generator | تولید AWB، Invoice، Label، فاکتور واردات |
|
||||
| **SMS** | Kavenegar | تأیید موبایل + اعلان وضعیت سفارش |
|
||||
| **Excel** | maatwebsite/excel | Import/Export نرخها و دادههای تاریخی |
|
||||
| **Date/Time** | morilog/jalali + Carbon | تاریخ شمسی در نمایش، میلادی در DB |
|
||||
| **Database** | MySQL | 8.0+ |
|
||||
| **Database** | MySQL | 8.0+ (تستها با SQLite) |
|
||||
| **Queue** | Redis (ترجیح) / Database | برای پردازشهای سنگین |
|
||||
| **Server** | HestiaCP + Nginx + PHP-FPM | تولید (api.ifnex.vernahost.ir) |
|
||||
|
||||
@ -37,48 +37,32 @@
|
||||
|
||||
## 📂 ساختار دایرکتوری (کلیدی)
|
||||
|
||||
```
|
||||
IFNEX-Logistics/
|
||||
├── 01_Documents/ # مستندات فنی (تحلیل اکسل، نقشه راه، چکلیست، ...)
|
||||
│ ├── EXCEL_ANALYSIS.md # تحلیل کامل فایلهای اکسل (۳۹۵۰ رکورد)
|
||||
│ ├── IFNEX_Phase0_Checklist.md # چکلیست کامل فازها
|
||||
│ ├── IFNEX_Roadmap.md # نقشه راه ۵ فازی
|
||||
│ ├── IFNEX_File_Map.md # نقشه ۱۰۰+ فایل پروژه
|
||||
│ ├── IFNEX_I18N_Strategy.md # استراتژی چندزبانه
|
||||
│ ├── IFNEX_Commercial_Model.md # مدل تجاری و پلنهای فروش
|
||||
│ └── DESIGN_SYSTEM.md # رنگها، تایپوگرافی، فاصلهگذاری
|
||||
│
|
||||
├── 03_WordPress/ # فرانتاند وردپرس
|
||||
│ ├── wp-content/themes/ifnex/ # قالب سفارشی
|
||||
│ └── wp-content/plugins/ifnex-bridge/ # پلاگین ارتباط با لاراول
|
||||
│
|
||||
├── 04_Laravel/ # بکاند لاراول (هسته اصلی)
|
||||
│ ├── app/
|
||||
│ │ ├── Enums/ # ShipmentStatus, ShipmentDirection, ShipmentType, PaymentGateway, TransactionStatus
|
||||
│ │ ├── Filament/
|
||||
│ │ │ ├── Resources/ # ۱۰+ Resource (Shipment, Country, ShippingRate, Currency, ...)
|
||||
│ │ │ ├── Pages/ # Settings, PriceTest, ImportRates, FinancialReport
|
||||
│ │ │ └── Widgets/ # داشبورد
|
||||
│ │ ├── Http/
|
||||
│ │ │ ├── Controllers/Api/ # Track, Pricing, Auth, Bridge, Customer, Wallet, Payment, MockGateway
|
||||
│ │ │ └── Middleware/ # ApiKeyMiddleware
|
||||
│ │ ├── Models/ # ۱۷ مدل (Shipment, Package, Invoice, Wallet, ...)
|
||||
│ │ ├── Notifications/ # ShipmentUpdatedNotification
|
||||
│ │ ├── Services/ # PriceCalculator, Pdf, Tracking, OrderPayment, Zarinpal, MockZarinpal
|
||||
│ │ ├── Imports/ # OldShipmentsImport, ShippingRatesImport
|
||||
│ │ └── Exports/ # ShippingRatesTemplateExport
|
||||
│ ├── database/
|
||||
│ │ ├── migrations/ # ۲۸+ migration
|
||||
│ │ └── seeders/ # Countries, SystemSettings, DatabaseSeeder
|
||||
│ ├── resources/views/
|
||||
│ │ ├── pdfs/ # awb, invoice, label (با بارکد)
|
||||
│ │ └── filament/ # صفحات سفارشی
|
||||
│ └── routes/
|
||||
│ ├── api.php # ۳۰+ endpoint
|
||||
│ └── web.php # روتهای عمومی (دانلود template، Mock Gateway)
|
||||
│
|
||||
├── DEPLOYMENT.md # راهنمای استقرار در سرور
|
||||
└── README.md # معرفی کلی پروژه
|
||||
|
||||
├── 01_Documents/ # مستندات فنی (تحلیل اکسل، نقشه راه، چکلیست، ...)
|
||||
├── 03_WordPress/ # فرانتاند وردپرس
|
||||
│ ├── wp-content/themes/ifnex/ # قالب سفارشی
|
||||
│ └── wp-content/plugins/ifnex-bridge/ # پلاگین ارتباط با لاراول
|
||||
├── 04_Laravel/ # بکاند لاراول (هسته اصلی)
|
||||
│ ├── app/
|
||||
│ │ ├── Enums/ # ShipmentStatus, ShipmentDirection, ShipmentType, PaymentGateway, TransactionStatus
|
||||
│ │ ├── Filament/ # ۱۷ Resource + Pages (Settings, ImportRates, BulkTrackingImport, FinancialReport) + Widgets
|
||||
│ │ ├── Http/Controllers/Api/ # Track, Pricing, Auth, Bridge, Customer, Wallet, Payment, Staff, CommitmentForm, ...
|
||||
│ │ ├── Http/Middleware/ # ApiKeyMiddleware
|
||||
│ │ ├── Models/ # ۲۲ مدل (Shipment, ShipmentPackage, CommitmentForm, Wallet, ...)
|
||||
│ │ ├── Notifications/ # DB notifications + SMS (ShipmentApprovedSms, PaymentSuccessSms, SmsChannel, ...)
|
||||
│ │ ├── Observers/ # ShipmentObserver (تریگر نوتیفیکیشن/SMS روی تغییر وضعیت)
|
||||
│ │ ├── Services/ # PriceCalculator, Pdf, Tracking, OrderPayment, Wallet, Zarinpal, KavenegarSms
|
||||
│ │ ├── Traits/ # Auditable
|
||||
│ │ ├── Imports/ # OldShipmentsImport, ShippingRatesImport
|
||||
│ │ └── Exports/ # ShippingRatesTemplateExport
|
||||
│ ├── database/migrations/ # ۳۸+ migration
|
||||
│ ├── resources/views/pdfs/ # awb, invoice, label, import-invoice (با بارکد)
|
||||
│ └── routes/api.php # ۴۰+ endpoint
|
||||
├── AGENT.md # همین سند
|
||||
├── DEPLOYMENT.md # راهنمای استقرار در سرور
|
||||
└── README.md # معرفی کلی پروژه
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
@ -87,11 +71,11 @@ IFNEX-Logistics/
|
||||
### ۱. مرسوله (Shipment)
|
||||
- **انواع (Type):** `DOC_NORMAL`، `DOC_ECONOMY`، `PARCEL`
|
||||
- **جهت (Direction):** `export` (صادرات) و `import` (واردات)
|
||||
- **وضعیت (Status):** `pending` → `confirmed` → `picked_up` → `in_transit` → `out_for_delivery` → `delivered` / `failed` / `returned` / `cancelled`
|
||||
- **ویژگیها:** دارای چند بسته (`packages`)، اقلام گمرکی (`items` - فقط برای PARCEL)، تاریخچه تغییرات وضعیت (`statusHistories`)، شرکتهای حمل (`carrierMappings`)، رویدادهای رهگیری (`trackingEvents`).
|
||||
- **وضعیت (Status):** `pending_approval` → `approved` → `processed` → `picked_up` → `in_transit` → `out_for_delivery` → `delivered` / `failed` / `returned` / `cancelled` (+ `pending_payment` legacy و `archived`)
|
||||
- **ویژگیها:** دارای چند بسته (`packages`)، اقلام گمرکی (`items` - فقط برای PARCEL)، تاریخچه تغییرات وضعیت (`statusHistories`)، شرکتهای حمل (`carrierMappings`)، رویدادهای رهگیری (`trackingEvents`)، تعهدنامهها (`commitmentForms`).
|
||||
|
||||
### ۲. بسته (Package)
|
||||
- هر مرسوله میتواند چندین بسته داشته باشد.
|
||||
- هر مرسوله میتواند چندین بسته داشته باشد (جدول `shipment_packages`).
|
||||
- وزن حجمی = `(Length × Width × Height) / 5000` (استاندارد IATA).
|
||||
- وزن قابل پرداخت = `max(وزن واقعی, وزن حجمی)`.
|
||||
|
||||
@ -99,27 +83,56 @@ IFNEX-Logistics/
|
||||
- فقط برای مرسولههای نوع `PARCEL` صادر میشود.
|
||||
- حداکثر ۹ قلم کالا (شرح، HS Code، تعداد، قیمت واحد، مجموع به USD).
|
||||
- مجموع کل فاکتور در `shipments.invoice_total_usd` ذخیره میشود.
|
||||
- **فاکتور واردات (Import Invoice):** فیلدهای brand_fee, report_fee, customs_clearance_cost, order_registration_fee و... + قالب PDF مطابق شیت ENG Invoice.
|
||||
|
||||
### ۴. کیف پول (Wallet)
|
||||
- هر کاربر یک کیف پول دارد.
|
||||
- تراکنشها (`WalletTransaction`) با نوع `deposit`، `payment`، `refund`، `adjustment`.
|
||||
- پرداخت از کیف پول یا درگاه Zarinpal (با Mock برای تست).
|
||||
- تراکنشها (`WalletTransaction`) با نوع `deposit`، `order_payment`، `refund`، `withdrawal` — بهصورت polymorphic به Payment/سفارش متصل است.
|
||||
- پرداخت از کیف پول یا درگاه Zarinpal (با Mock برای تست). freeze/unfreeze + activity log کامل.
|
||||
|
||||
### ۵. احراز هویت Bridge
|
||||
- کاربران وردپرس بدون نیاز به رمز عبور، از طریق `POST /api/v1/bridge/login` با ارسال `bridge_api_key` و `wp_user_id` وارد لاراول میشوند.
|
||||
- پاسخ شامل `token` Sanctum (معتبر ۳۰ روز) و اطلاعات کاربر است.
|
||||
- کلید `IFNEX_BRIDGE_API_KEY` باید در هر دو طرف (`.env` لاراول و تنظیمات پلاگین وردپرس) یکسان باشد.
|
||||
- توکن در usermeta کاربر وردپرس (`ifnex_laravel_token`) ذخیره میشود و روی 401 خودکار باطل/تجدید میشود.
|
||||
|
||||
### ۶. رهگیری (Tracking)
|
||||
- کاربر با شماره AWB جستجو میکند.
|
||||
- سیستم رویدادهای رهگیری را از جدول `shipment_tracking_events` با `source` (manual, api, system) نمایش میدهد.
|
||||
- در فاز ۳.۵، صفحه رهگیری با تایملاین زیبا و badge رنگی بازطراحی شده است.
|
||||
- سیستم رویدادهای رهگیری را از جدول `shipment_tracking_events` با `source` (manual, api, import, system, customer) نمایش میدهد.
|
||||
- ایمپورت گروهی وضعیت ترکینگ با CSV از پنل (صفحه BulkTrackingImport).
|
||||
|
||||
### ۷. قیمتگذاری (Pricing)
|
||||
- بر اساس ۴ زون مجزا (Export/Import × Parcel/Doc) و ۳ نوع سرویس.
|
||||
- فرمول: قیمت پایه (AED) × ضریب سود × نرخ تبدیل به ریال + هزینههای جانبی (Packing, Domestic Pickup, ...) + VAT (۹٪).
|
||||
- محمولههای بالای ۳۰ کیلوگرم مشمول نرخ ویژه (Spot Rate) هستند و محاسبه آنلاین ندارند.
|
||||
|
||||
### ۸. فلوی تأیید سفارش (Approval Flow)
|
||||
- مشتری بعد از ثبت سفارش، **مستقیم به درگاه نمیرود**؛ سفارش با وضعیت `pending_approval` ثبت میشود.
|
||||
- کارمند/مدیر از پنل فیلمنت (اکشن تأیید در ShipmentResource) یا API (`/staff/orders/{id}/approve|reject`) تأیید میکند.
|
||||
- فقط بعد از `approved`، گزینههای پرداخت (کیف پول / درگاه) در وردپرس باز میشود؛ پرداخت موفق سفارش را `processed` میکند (PaymentController در callback با `is_order_payment` در metadata).
|
||||
- سفارشهای `approved` (پرداختنشده) روی مانده حساب کاربر (account_balance در profile) اثر میگذارند.
|
||||
|
||||
### ۹. تعهدنامه و اسناد سفارش (Commitment Forms)
|
||||
- مدیر فرمهای تعهدنامه را در فیلمنت (`CommitmentFormResource`) آپلود میکند (با direction: export/import/both).
|
||||
- مشتری در جزئیات سفارش وردپرس، لیست تعهدنامهها را میبیند → دانلود/پرینت/امضا → آپلود فایل امضاشده (`POST /orders/{shipment}/commitment-forms/{form}/upload`)؛ ثبت در جدول `shipment_commitment_forms`.
|
||||
- دانلود AWB / Invoice / Label هم از همین بخش (`/orders/{shipment}/pdf/*`) انجام میشود.
|
||||
- ⚠️ هنوز چک مالکیت (ownership) در کنترلر PDF/تعهدنامه اضافه نشده — کار باقیمانده.
|
||||
|
||||
### ۱۰. اعلانها و SMS کاوهنگار
|
||||
- تنظیمات از `SystemSetting` خوانده میشود (`kavenegar_api_key` + سوییچ هر نوع پیام مثل `kavenegar_send_shipment_approved`).
|
||||
- نوتیفیکیشنها: `ShipmentApprovedSms`، `ShipmentRejectedSms`، `PaymentSuccessSms`، `TrackingUpdatedSms` + کانال `SmsChannel`.
|
||||
- تریگر اصلی: `ShipmentObserver` (روی تغییر وضعیت Shipment) و PaymentController (پرداخت موفق). تأیید موبایل: `MobileVerificationController`.
|
||||
- در `.env` لوکال کلید کاوهنگار خالی است؛ تا وقتی تنظیم نشود SMS ارسال نمیشود (فقط DB notification).
|
||||
|
||||
### ۱۱. اعتبار مشتری (Credit) — نیمهکاره
|
||||
- فعلاً فقط دو ستون `credit_limit/credit_used` روی جدول users + `CustomerCreditResource` در فیلمنت.
|
||||
- ⚠️ اکشنهای افزایش/کاهش اعتبار هنوز روی ستونهای ناموجود `wallet_transactions.user_id` و تایپهای `credit_add/credit_reduce` مینویسند (خراب) و اعتبار در فلوی سفارش/پرداخت هم استفاده نشده.
|
||||
- نیاز کارفرما: بدهی به **ارز سفارش** (مثلاً ۵۰ یورو بدهکار) + تسویه ریالی با نرخ روز → نیاز به بازطراحی دارد.
|
||||
|
||||
### ۱۲. Audit Log
|
||||
- trait `App\Traits\Auditable` روی مدلهای اصلی (User, Shipment, Wallet, ...) اعمال شده و در `AuditLogResource` قابل مشاهده است.
|
||||
- `ShipmentStatusHistory` با ستونهای `from_status/to_status/reason` + ثبت نام کاربر تغییردهنده.
|
||||
|
||||
---
|
||||
|
||||
## ⚙️ دستورات روزمره (برای ایجنت)
|
||||
@ -153,17 +166,20 @@ php artisan view:cache
|
||||
php artisan filament:clear-cached-components
|
||||
|
||||
# ایمپورت/اکسپورت نرخها
|
||||
php artisan ifnex:import-rates
|
||||
php artisan ifnex:export-rates-template
|
||||
php artisan ifnex:import:rates {path}
|
||||
php artisan ifnex:import:shipments {path}
|
||||
php artisan ifnex:import:tracking {path}
|
||||
|
||||
# بروزرسانی نرخ ارز (کرون)
|
||||
php artisan ifnex:update-exchange-rates
|
||||
php artisan ifnex:update-rates --source=ecb
|
||||
|
||||
# تولید API Token برای ادمین
|
||||
php artisan ifnex:generate-api-token
|
||||
php artisan ifnex:token
|
||||
```
|
||||
|
||||
## 🧪 متغیرهای محیطی کلیدی (.env)
|
||||
|
||||
🧪 متغیرهای محیطی کلیدی (.env)
|
||||
```env
|
||||
APP_ENV=local
|
||||
APP_DEBUG=true
|
||||
APP_URL=http://localhost:8000
|
||||
@ -190,70 +206,85 @@ ZARINPAL_CALLBACK_URL=http://localhost:8000/api/v1/payment/callback
|
||||
ZARINPAL_FRONTEND_SUCCESS_URL=http://localhost/IFNEX-Logistics/03_WordPress/wallet
|
||||
ZARINPAL_FRONTEND_FAILURE_URL=http://localhost/IFNEX-Logistics/03_WordPress/wallet
|
||||
|
||||
# Kavenegar SMS (خالی = فقط DB notification)
|
||||
KAVENEGAR_API_KEY=
|
||||
KAVENEGAR_SENDER=10008566
|
||||
|
||||
# Wallet
|
||||
WALLET_MIN_DEPOSIT=10000
|
||||
WALLET_MAX_DEPOSIT=500000000
|
||||
WALLET_AUTO_CREATE=true
|
||||
```
|
||||
|
||||
## ⚠️ خط قرمزها (ممنوعیتهای مطلق)
|
||||
|
||||
⚠️ خط قرمزها (ممنوعیتهای مطلق)
|
||||
| ❌ هرگز | ✅ همیشه |
|
||||
|---------|----------|
|
||||
| برگرداندن کشورها به ۲ زون | ۴ زون مجزا (Export/Import × Parcel/Doc) |
|
||||
| استفاده از ۲ نوع سرویس | ۳ نوع (DOC_NORMAL, DOC_ECONOMY, PARCEL) |
|
||||
| ذخیره تاریخ شمسی در DB | ذخیره timestamp میلادی + تبدیل در نمایش |
|
||||
| CORS * در Production | CORS محدود به دامنه وردپرس |
|
||||
| کامیت .env در Git | در .gitignore باشد |
|
||||
| APP_DEBUG=true در Production | APP_DEBUG=false |
|
||||
| PDF فارسی (AWB/Invoice/Label) | همیشه انگلیسی (برای حمل بینالمللی) |
|
||||
| کپی از DHL | طراحی منحصر به فرد IFNEX |
|
||||
| استفاده از wire:click برای دانلود | استفاده از `<a href>` با روت مستقیم |
|
||||
| getFormActions() در Custom Pages | استفاده از wire:click در Blade |
|
||||
| هدایت AJAX به redirect() | استفاده از payment_url در response JSON |
|
||||
| متدهای نوتیفیکیشن بیرون از کلاس | داخل کلاس IFNEX_User_Bridge |
|
||||
| روت staff/admin بدون چک نقش | چک نقش/مالکیت در middleware یا ابتدای کنترلر |
|
||||
| سفارش مستقیم به درگاه بعد از ثبت | فلوی pending_approval → approved → پرداخت |
|
||||
|
||||
❌ هرگز ✅ همیشه
|
||||
برگرداندن کشورها به ۲ زون ۴ زون مجزا (Export/Import × Parcel/Doc)
|
||||
استفاده از ۲ نوع سرویس ۳ نوع (DOC_NORMAL, DOC_ECONOMY, PARCEL)
|
||||
ذخیره تاریخ شمسی در DB ذخیره timestamp میلادی + تبدیل در نمایش
|
||||
CORS * در Production CORS محدود به دامنه وردپرس
|
||||
کامیت .env در Git در .gitignore باشد
|
||||
APP_DEBUG=true در Production APP_DEBUG=false
|
||||
PDF فارسی (AWB/Invoice/Label) همیشه انگلیسی (برای حمل بینالمللی)
|
||||
کپی از DHL طراحی منحصر به فرد IFNEX
|
||||
استفاده از wire:click برای دانلود استفاده از <a href> با روت مستقیم
|
||||
getFormActions() در Custom Pages استفاده از wire:click در Blade
|
||||
هدایت AJAX به redirect() استفاده از payment_url در response JSON
|
||||
متدهای نوتیفیکیشن بیرون از کلاس داخل کلاس IFNEX_User_Bridge
|
||||
📌 نکات ویژه برای ایجنت (DeepSeek Flash)
|
||||
هنگام تولید کد جدید، حتماً از Enumها به جای رشتههای سختکد شده استفاده کن.
|
||||
## 📌 نکات ویژه برای ایجنت
|
||||
|
||||
برای هر مدل جدید، migration، مدل، و در صورت نیاز کنترلر/ریسورس Filament بساز.
|
||||
- هنگام تولید کد جدید، حتماً از Enumها به جای رشتههای سختکد شده استفاده کن.
|
||||
- برای هر مدل جدید، migration، مدل، و در صورت نیاز کنترلر/ریسورس Filament بساز.
|
||||
- خطاهای رایج:
|
||||
- عدم وجود فیلد deleted_at در کوئریها (از SoftDeletes استفاده کن).
|
||||
- فراموشی fillable یا casts در مدلها.
|
||||
- فراموشی $with برای بارگذاری روابط در Resourceها.
|
||||
- استفاده از redirect() در کنترلرهای API (باید JSON برگردانند).
|
||||
- برای تغییر وضعیت مرسوله، حتماً تاریخچه را بهروز کن (مدل ShipmentStatusHistory با from_status/to_status/reason).
|
||||
- در فرم سفارش مشتری، مرحله Invoice فقط برای نوع PARCEL نمایش داده شود.
|
||||
- تولید PDF با بارکد بهصورت base64 embed انجام شود.
|
||||
- Bridge Auth نیازی به رمز عبور ندارد؛ فقط از IFNEX_BRIDGE_API_KEY استفاده میکند.
|
||||
- تست لوکال پرداخت: از ZARINPAL_MERCHANT_ID=fake-merchant-id-for-testing برای فعالسازی Mock Gateway استفاده کن.
|
||||
- مدیریت تاریخ: همیشه از Carbon استفاده کن و تاریخ را بهصورت Y-m-d H:i:s در DB ذخیره کن.
|
||||
- برای کوئریهای سنگین، از chunk() یا cursor() استفاده کن تا حافظه مصرف نشود.
|
||||
- **هنگام استفاده از هر Model در فایل جدید، حتماً `use App\Models\...` را import کن** — باگ اخیر `SystemSetting` در PaymentController/ShipmentObserver/TrackingService فلوی تأیید/پرداخت را میشکست (در کامیت `2737e26` رفع شد).
|
||||
- **در مارکآپ شورتکدهای وردپرس، باز/بسته بودن div ها را متوازن نگه دار** — باگ «مرحله ۲ فرم سفارش لود نمیشود» ریشهاش یک div بستهنشده در shortcodes.php بود که مراحل را داخل هم nest میکرد؛ هکهای MutationObserver/setInterval هیچکدام مشکل را حل نمیکردند و حذف شدند.
|
||||
- **هکهای موقت دیباگ** (`opcache_reset()` و `header()` بالای فایلهای پلاگین، cache-buster با `time()`) فقط برای کار لوکال هستند و قبل از دیپلوی باید حذف شوند.
|
||||
|
||||
خطاهای رایج:
|
||||
## 🧭 کارهای باقیمانده (فاز ۳.۶ — بهروزرسانی 2026-09-10)
|
||||
|
||||
عدم وجود فیلد deleted_at در کوئریها (از SoftDeletes استفاده کن).
|
||||
| # | کار | وضعیت |
|
||||
|---|-----|-------|
|
||||
| 1 | تست انتهای فلوی سفارش: آپلود تعهدنامه → تأیید کارمند → پرداخت کیف پول/درگاه | ⏳ اولویت اول |
|
||||
| 2 | امنیت: چک نقش روی `/staff/*`، چک مالکیت PDF/تعهدنامه، ثبت شورتکد `[ifnex_wallet_charge]` (صفحه /wallet/ خراب است)، محدودسازی `GET /discount-codes`، rate limiting | ⏳ |
|
||||
| 3 | بازطراحی سیستم اعتبار (بدهی چندارزی مطابق نیاز کارفرما) + رفع اکشنهای `CustomerCreditResource` | ⏳ |
|
||||
| 4 | چکلیست خودکار کارمند بعد از تأیید سفارش + نمایش در صفحه سفارش (فعلاً فقط CRUD دستی) | ⏳ |
|
||||
| 5 | سند پیشنهادی سیستم مالی (درخواست ۱۳ کارفرما) | ⏳ |
|
||||
| 6 | پاکسازی: opcache_reset/header ها، cache-buster `time()`، هکهای `!important` CSS، صفحات تستی منتشرشده، پلاگین ifnex-bridge-test، فایلهای آشغال ریشه | ⏳ |
|
||||
| 7 | نمایش وزن واقعی/حجمی در خلاصه قیمت وردپرس (API فیلد `weight` را برنمیگرداند) | ⏳ |
|
||||
| 8 | چندزبانه (i18n) — به زمان دیپلوی موکول شده | ⏳ |
|
||||
|
||||
فراموشی fillable یا casts در مدلها.
|
||||
---
|
||||
|
||||
فراموشی $with برای بارگذاری روابط در Resourceها.
|
||||
## 📚 مستندات مرجع (برای مطالعه بیشتر)
|
||||
|
||||
استفاده از redirect() در کنترلرهای API (باید JSON برگردانند).
|
||||
| فایل | محتوا |
|
||||
|------|-------|
|
||||
| 01_Documents/EXCEL_ANALYSIS.md | تحلیل کامل فایلهای اکسل (۳۹۵۰ رکورد، فرمولها، زونها) |
|
||||
| 01_Documents/IFNEX_Phase0_Checklist.md | چکلیست کامل فازها (۰ تا ۳.۵) |
|
||||
| 01_Documents/IFNEX_Roadmap.md | نقشه راه فازی (تا فاز ۳.۶) |
|
||||
| 01_Documents/IFNEX_File_Map.md | نقشه ۱۰۰+ فایل پروژه |
|
||||
| 01_Documents/IFNEX_I18N_Strategy.md | استراتژی چندزبانه (برای زمان دیپلوی) |
|
||||
| 01_Documents/IFNEX_Commercial_Model.md | مدل تجاری و پلنهای فروش |
|
||||
| 01_Documents/DESIGN_SYSTEM.md | رنگها، تایپوگرافی، فاصلهگذاری |
|
||||
| DEPLOYMENT.md | راهنمای کامل استقرار روی سرور |
|
||||
| 04_Laravel/README.md | راهنمای بکاند |
|
||||
|
||||
برای تغییر وضعیت مرسوله، حتماً تایملاین را بهروز کن (مدل ShipmentStatusHistory).
|
||||
|
||||
در فرم سفارش مشتری، مرحله Invoice فقط برای نوع PARCEL نمایش داده شود.
|
||||
|
||||
تولید PDF با بارکد بهصورت base64 embed انجام شود.
|
||||
|
||||
Bridge Auth نیازی به رمز عبور ندارد؛ فقط از IFNEX_BRIDGE_API_KEY استفاده میکند.
|
||||
|
||||
تست لوکال پرداخت: از ZARINPAL_MERCHANT_ID=fake-merchant-id-for-testing برای فعالسازی Mock Gateway استفاده کن.
|
||||
|
||||
مدیریت تاریخ: همیشه از Carbon استفاده کن و تاریخ را بهصورت Y-m-d H:i:s در DB ذخیره کن.
|
||||
|
||||
برای کوئریهای سنگین، از chunk() یا cursor() استفاده کن تا حافظه مصرف نشود.
|
||||
|
||||
|
||||
📚 مستندات مرجع (برای مطالعه بیشتر)
|
||||
فایل محتوا
|
||||
01_Documents/EXCEL_ANALYSIS.md تحلیل کامل فایلهای اکسل (۳۹۵۰ رکورد، فرمولها، زونها)
|
||||
01_Documents/IFNEX_Phase0_Checklist.md چکلیست کامل فازها (۰ تا ۳.۵)
|
||||
01_Documents/IFNEX_Roadmap.md نقشه راه ۵ فازی
|
||||
01_Documents/IFNEX_File_Map.md نقشه ۱۰۰+ فایل پروژه
|
||||
01_Documents/IFNEX_I18N_Strategy.md استراتژی چندزبانه (برای زمان دیپلوی)
|
||||
01_Documents/IFNEX_Commercial_Model.md مدل تجاری و پلنهای فروش
|
||||
01_Documents/DESIGN_SYSTEM.md رنگها، تایپوگرافی، فاصلهگذاری
|
||||
DEPLOYMENT.md راهنمای کامل استقرار روی سرور
|
||||
04_Laravel/README.md راهنمای بکاند
|
||||
تاریخ: 2026-09-02
|
||||
نسخه: 1.0
|
||||
---
|
||||
تاریخ: 2026-09-10
|
||||
نسخه: 1.1
|
||||
تهیهکننده: VernaSoft Group — Kazem Alghasi
|
||||
مدل هدف: DeepSeek Flash (API)
|
||||
|
||||
|
||||
@ -85,6 +85,8 @@ KAVENEGAR_API_KEY=YOUR_KAVENEGAR_API_KEY
|
||||
KAVENEGAR_SENDER=10008566
|
||||
```
|
||||
|
||||
> 📱 **نکته SMS:** سرویس پیامک از تنظیمات پنل ادمین (Filament → تنظیمات سیستم → SystemSetting) خوانده میشود: `kavenegar_api_key` و سوییچهای `kavenegar_send_*` برای هر نوع اعلان. بعد از استقرار، کلید کاوهنگار را از پنل تنظیم کنید — در غیر این صورت فقط نوتیفیکیشن دیتابیسی ارسال میشود.
|
||||
|
||||
### ۱.۴ دیتابیس
|
||||
|
||||
```bash
|
||||
@ -208,8 +210,8 @@ crontab -e
|
||||
```
|
||||
|
||||
```cron
|
||||
# بهروزرسانی نرخ ارز (اگر ExchangeRateService فعال شد)
|
||||
0 0 * * * cd /home/USER/web/api.ifnex.vernahost.ir/public_html && php artisan ifnex:update-exchange-rates >> /dev/null 2>&1
|
||||
# بهروزرسانی نرخ ارز
|
||||
0 0 * * * cd /home/USER/web/api.ifnex.vernahost.ir/public_html && php artisan ifnex:update-rates --source=freecurrencyapi >> /dev/null 2>&1
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
37
README.md
37
README.md
@ -9,7 +9,7 @@
|
||||
[](https://filamentphp.com)
|
||||
[](https://wordpress.org)
|
||||
[](https://mysql.com)
|
||||
[]()
|
||||
[]()
|
||||
[]()
|
||||
|
||||
---
|
||||
@ -199,6 +199,23 @@ IFNEX-Logistics/
|
||||
- اصلاحات فنی (Enum casts, migration, model)
|
||||
- پشتیبانی چندزبانه (i18n) — به زمان دیپلوی منتقل شد
|
||||
|
||||
### فاز ۳.۶ — اصلاحات جلسه کارفرما 🟡 (در حال تکمیل - ۸۰٪)
|
||||
|
||||
**هدف:** پیادهسازی تغییرات درخواستی کارفرما پس از جلسه ارائه
|
||||
|
||||
- ✅ فلوی تأیید سفارش: `pending_approval → approved → (پرداخت) → processed` — مشتری بعد از ثبت منتظر تأیید کارمند میماند و سپس پرداخت (کیف پول/درگاه) باز میشود
|
||||
- ✅ تعهدنامهها: آپلود توسط مدیر در Filament → نمایش/دانلود برای مشتری → آپلود فایل امضاشده توسط مشتری (جدول `shipment_commitment_forms`)
|
||||
- ✅ دانلود اسناد سفارش (AWB, Invoice, Label, فاکتور واردات) در پورتال مشتری
|
||||
- ✅ وضعیت مالی مشتری برای کارمند/مدیر: جستجوی مشتری + بدهی به تفکیک ارز + تراکنشها و سفارشات اخیر
|
||||
- ✅ سیستم اعتبار مشتری (اسکلت: `credit_limit/credit_used` + CustomerCreditResource) — نیازمند بازطراحی چندارزی
|
||||
- ✅ ایمپورت گروهی وضعیت ترکینگ با CSV در پنل (BulkTrackingImport)
|
||||
- ✅ Audit Log برای مدلهای اصلی + ShipmentStatusHistory با from/to_status
|
||||
- ✅ اتصال SMS کاوهنگار: تأیید/رد سفارش، پرداخت موفق، بروزرسانی ترکینگ + تنظیمات پنل
|
||||
- ✅ فاکتور واردات (Import Invoice) با فیلدهای جدید shipments + قالب PDF مطابق شیت ENG
|
||||
- ✅ مانده حساب (موجودی منهای بدهیهای تأییدشده) در پروفایل مشتری
|
||||
- ✅ رفع باگ مراحل فرم سفارش (ریشه: div بستهنشده در shortcodes.php) و محاسبه مجموع USD اقلام
|
||||
- ⏳ باقیمانده: تست انتهای فلو، امنیت روتهای staff، بازطراحی اعتبار چندارزی، چکلیست خودکار، سند سیستم مالی (جزئیات در AGENT.md)
|
||||
|
||||
### فاز ۴ (آینده) — سیستم نمایندگی 📋
|
||||
- مدل نمایندگی کامل با کمیسیون و پنل جداگانه
|
||||
- طرح مطالعاتی آماده — منتظر تأیید کارفرما
|
||||
@ -318,14 +335,14 @@ php artisan serve
|
||||
|
||||
| معیار | مقدار |
|
||||
|-------|-------|
|
||||
| تعداد مایگریشنها | ۲۳ |
|
||||
| تعداد API endpoints | ۳۰+ |
|
||||
| تعداد Filament Resources | ۱۰+ |
|
||||
| تعداد مدلها | ۱۳ |
|
||||
| تعداد مایگریشنها | ۳۸ |
|
||||
| تعداد API endpoints | ۴۰+ |
|
||||
| تعداد Filament Resources | ۱۷ |
|
||||
| تعداد مدلها | ۲۲ |
|
||||
| تعداد شورتکدهای وردپرس | ۱۰+ |
|
||||
| تعداد کشورها با پیششماره | ۱۹۲ |
|
||||
| رکوردهای تاریخی مهاجرتشده | ۳۹۵۰ |
|
||||
| خطوط کد (تخمینی) | ۱۵۰۰۰+ |
|
||||
| خطوط کد (تخمینی) | ۲۰۰۰۰+ |
|
||||
|
||||
---
|
||||
|
||||
@ -348,6 +365,14 @@ php artisan serve
|
||||
|
||||
## 🚀 مراحل بعدی
|
||||
|
||||
### فاز ۳.۶ — باقیمانده (تست و تکمیل)
|
||||
- تست انتهای فلو: آپلود تعهدنامه → تأیید کارمند → پرداخت (کیف پول / درگاه)
|
||||
- امنیت: چک نقش روی روتهای `/staff/*`، چک مالکیت PDF/تعهدنامه، ثبت شورتکد `[ifnex_wallet_charge]`، محدودسازی `GET /discount-codes`، rate limiting
|
||||
- بازطراحی سیستم اعتبار مطابق نیاز کارفرما (بدهی به ارز سفارش + تسویه ریالی)
|
||||
- چکلیست خودکار کارمند بعد از تأیید سفارش + نمایش در صفحه سفارش
|
||||
- سند پیشنهادی سیستم مالی
|
||||
- پاکسازی هکهای موقت دیباگ (opcache_reset، cache-buster، صفحات تستی)
|
||||
|
||||
### فاز ۳.۵ — باقیمانده (زمان دیپلوی)
|
||||
- پشتیبانی کامل چندزبانه (i18n) با Polylang
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user