gitmodir110/ifnex
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
main
ifnex/04_Laravel/README.md
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

515 lines
26 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<div align="center">
# ⚙️ IFNEX Laravel Backend
### هسته مرکزی سیستم مدیریت لجستیک ایف‌نکس
[![Laravel](https://img.shields.io/badge/Laravel-11.x-FF2D20?logo=laravel&logoColor=white)](https://laravel.com)
[![PHP](https://img.shields.io/badge/PHP-8.2+-777BB4?logo=php&logoColor=white)](https://php.net)
[![Filament](https://img.shields.io/badge/Filament-3.3-EDB200?logo=laravel&logoColor=white)](https://filamentphp.com)
[![MySQL](https://img.shields.io/badge/MySQL-8+-4479A1?logo=mysql&logoColor=white)](https://mysql.com)
[![Status](https://img.shields.io/badge/Status-Phase_3.6_In_Progress-yellow.svg)]()
---
**REST API + Admin Panel + Financial Engine + PDF Generator**
[🚀 نصب سریع](#-نصب-و-راهاندازی-سریع) &bull; [📡 API Endpoints](#-api-endpoints) &bull; [🗃️ Models](#-models) &bull; [🎨 Filament Resources](#-filament-resources) &bull; [📚 مستندات](#-مستندات)
</div>
---
## 🎯 نمای کلی
این پوشه شامل **هسته مرکزی سیستم IFNEX** است که شامل پنج بخش اصلی می‌شود:
### ۱. REST API کامل
ارتباط با WordPress از طریق Sanctum Token + Bridge Auth (بدون رمز عبور) — ۳۰+ endpoint برای تمام عملیات مشتری (سفارش، پرداخت، کیف پول، نوتیفیکیشن، رهگیری).
### ۲. پنل مدیریت Filament 3.3
پنل کامل برای اپراتورها و مدیران شامل مدیریت مرسوله‌ها، نرخ‌ها، ارزها، کاربران، گزارش‌های مالی و تنظیمات سیستم.
### ۳. موتور قیمت‌گذاری
محاسبه قیمت بر اساس ۴ زون (Export/Import × Parcel/Doc) و ۳ نوع سرویس با پشتیبانی از تخفیف، VAT، هزینه‌های داخلی و تبدیل ارز (درهم ↔ ریال).
### ۴. سیستم مالی و سندسازی
کیف پول دیجیتال، درگاه پرداخت Zarinpal، تولید خودکار PDF (AWB, Invoice, Label) با بارکد استاندارد و سیستم نوتیفیکیشن دیتابیس.
### ۵. Multi-Package و Invoice (فاز ۳.۵)
پشتیبانی از چند بسته در یک سفارش، فرم اقلام گمرکی (Invoice) برای محموله‌های PARCEL، و محاسبه خودکار وزن حجمی از ابعاد.
### ۶. فلوی تأیید سفارش و اعلان‌ها (فاز ۳.۶)
ثبت سفارش با وضعیت `pending_approval` → تأیید/رد توسط کارمند (پنل یا API) → باز شدن پرداخت → `processed` بعد از پرداخت. به‌همراه تعهدنامه‌ها (آپلود مدیر، دانلود/امضا/آپلود مشتری)، دانلود PDFها در پورتال مشتری، وضعیت مالی مشتری برای کارمندان، Audit Log و اعلان‌های SMS کاوه‌نگار.
---
## 🚀 نصب و راه‌اندازی سریع
### پیش‌نیازها
| ابزار | حداقل نسخه | توضیحات |
|-------|-----------|---------|
| PHP | 8.2+ | با extensions: pdo_mysql, mbstring, xml, gd, zip |
| Composer | 2.x | مدیریت وابستگی‌ها |
| MySQL | 8.0+ | دیتابیس اصلی |
| Node.js | 18+ | برای build assets (اختیاری) |
### مراحل نصب
```bash
# ۱. ورود به پوشه لاراول
cd 04_Laravel
# ۲. نصب وابستگی‌ها
composer install
# ۳. تنظیم فایل محیط
cp .env.example .env
php artisan key:generate
# ۴. ایجاد دیتابیس
mysql -u root -p -e "CREATE DATABASE ifnex_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
# ۵. ویرایش .env — مقادیر کلیدی (مشاهده جدول زیر)
# ۶. اجرای migrations و seeders
php artisan migrate --force
php artisan db:seed --force
# ۷. اجرای سرور
php artisan serve
# پنل ادمین: http://127.0.0.1:8000/panel
```
### 🔐 دسترسی پیش‌فرض
| آیتم | مقدار |
|-------|-------|
| URL پنل ادمین | http://localhost:8000/panel |
| URL API | http://localhost:8000/api/v1 |
| ایمیل ادمین | (از seeder) admin@ifnex.local |
| رمز عبور | password |
### ⚙️ تنظیمات مهم `.env`
```env
# DATABASE
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=ifnex_db
DB_USERNAME=root
DB_PASSWORD=
# IFNEX API
IFNEX_API_KEY=ifnex-local-dev-key
IFNEX_BRIDGE_API_KEY=ifnex-bridge-secret-key-2026-vernasoft # مهم برای وردپرس
IFNEX_TRACKING_RATE_LIMIT=60
# CORS (فقط دامنه‌های مجاز وردپرس)
CORS_ALLOWED_ORIGINS=http://localhost,http://127.0.0.1
# PAYMENT GATEWAY (Zarinpal)
ZARINPAL_MERCHANT_ID=fake-merchant-id-for-testing # برای Mock Mode
ZARINPAL_SANDBOX=true
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
# CURRENCY API (برای بروزرسانی نرخ ارز)
CURRENCY_API_KEY=your_api_key_here
CURRENCY_API_URL=https://api.freecurrencyapi.com/v1/latest
# WALLET
WALLET_MIN_DEPOSIT=10000
WALLET_MAX_DEPOSIT=500000000
WALLET_AUTO_CREATE=true
WALLET_ALLOW_WITHDRAWAL=false
```
> ⚠️ **نکته مهم:** اگر `ZARINPAL_MERCHANT_ID` برابر `fake-merchant-id-for-testing` باشد، سیستم از MockZarinpalService استفاده می‌کند که برای تست لوکال مناسب است.
---
## 📡 API Endpoints
### 🔓 API عمومی (با API Key یا بدون احراز هویت)
| متد | Endpoint | توضیح |
|------|----------|--------|
| GET | `/api/v1/track/{awb_no}` | رهگیری مرسوله (API Key) |
| POST | `/api/v1/calculate` | محاسبه قیمت |
| 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/orders` | لیست سفارشات (paginated) |
| POST | `/api/v1/customer/orders` | ثبت سفارش جدید (با packages[] و items[]) — وضعیت `pending_approval` |
| GET | `/api/v1/customer/orders/{id}` | جزئیات سفارش |
| POST | `/api/v1/customer/orders/{id}/cancel` | لغو سفارش |
| 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 | توضیح |
|------|----------|--------|
| GET | `/api/v1/wallet/balance` | موجودی + آمار |
| GET | `/api/v1/wallet/transactions` | تراکنش‌ها (paginated) |
| GET | `/api/v1/wallet/{wallet}/activity-log` | لاگ فعالیت‌ها |
| POST | `/api/v1/wallet/{wallet}/freeze` | مسدود کردن کیف پول (admin) |
| POST | `/api/v1/wallet/{wallet}/unfreeze` | آزاد کردن کیف پول (admin) |
| POST | `/api/v1/wallet/admin-adjust` | تراکنش دستی (admin) |
### 💳 API پرداخت
| متد | Endpoint | توضیح |
|------|----------|--------|
| POST | `/api/v1/payment/redirect` | انتقال به درگاه (شارژ کیف پول) |
| GET | `/api/v1/payment/check/{transaction}` | بررسی وضعیت تراکنش |
| ANY | `/api/v1/payment/callback` | Callback از درگاه (Zarinpal) |
### 🧪 Mock Gateway (تست لوکال)
| متد | Endpoint | توضیح |
|------|----------|--------|
| GET | `/api/v1/payment/mock-gateway` | صفحه شبیه‌سازی درگاه |
| GET | `/api/v1/payment/mock-gateway/success` | شبیه‌سازی پرداخت موفق |
| GET | `/api/v1/payment/mock-gateway/failure` | شبیه‌سازی پرداخت ناموفق |
### 📥 مثال: ثبت سفارش
```bash
curl -X POST http://localhost:8000/api/v1/customer/orders \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"direction": "export",
"type": "PARCEL",
"from_country_id": 1,
"to_country_id": 2,
"weight": 2.5,
"volumetric_weight": 2.5,
"sender_name": "John Doe",
"sender_phone": "+98 9123456789",
"sender_city": "Tehran",
"sender_address": "No 1, ValiAsr Street",
"receiver_name": "Ahmed Ali",
"receiver_phone": "+971 501234567",
"receiver_city": "Dubai",
"receiver_address": "Sheikh Zayed Road 100"
}'
```
---
## 🗂️ ساختار پروژه
```
04_Laravel/
├── app/
│ ├── Enums/ # ShipmentStatus (۱۲ وضعیت), ShipmentDirection, ShipmentType, PaymentGateway, TransactionType, TransactionStatus, CarrierCode, TrackingSource, UserRole
│ ├── Filament/
│ │ ├── Resources/ # ۱۶ Resources
│ │ │ ├── ShipmentResource/ # مدیریت مرسوله‌ها + اکشن تأیید/رد + RelationManagers
│ │ │ ├── ShipmentChecklistResource/ # چک‌لیست کارمند
│ │ │ ├── CommitmentFormResource/ # فرم‌های تعهدنامه (آپلود مدیر)
│ │ │ ├── CustomerCreditResource/ # اعتبار مشتریان
│ │ │ ├── AuditLogResource/ # لاگ تغییرات
│ │ │ ├── CountryResource/ # مدیریت کشورها + calling_code
│ │ │ ├── ShippingRateResource/
│ │ │ ├── CurrencyResource/ # مدیریت ارزها
│ │ │ ├── UserResource/ # مدیریت کاربران
│ │ │ ├── WalletResource/ # کیف پول‌ها
│ │ │ ├── WalletTransactionResource/
│ │ │ ├── PaymentResource/ # پرداخت‌ها
│ │ │ ├── DiscountCodeResource/
│ │ │ ├── ShipmentItemResource/
│ │ │ ├── ExchangeRateHistoryResource/
│ │ │ └── RoleResource/ # مدیریت نقش‌ها
│ │ ├── Pages/
│ │ │ ├── IfnexSettingsPage.php # تنظیمات سیستم + کلیدهای SMS
│ │ │ ├── PriceTestPage.php # تست محاسبه قیمت
│ │ │ ├── ImportRatesPage.php # آپلود اکسل نرخ‌ها
│ │ │ ├── BulkTrackingImport.php # ایمپورت گروهی وضعیت ترکینگ (CSV)
│ │ │ └── Reports/FinancialReport.php # گزارش مالی
│ │ └── Widgets/ # DashboardInfo, ExchangeRate, FinanceOverview, WalletStats, ...
│ ├── Http/
│ │ ├── Controllers/
│ │ │ ├── Api/
│ │ │ │ ├── AuthController.php # لاگین/لاگاوت مشتری
│ │ │ │ ├── BridgeAuthController.php # Bridge Auth (وردپرس)
│ │ │ │ ├── TrackController.php # رهگیری عمومی
│ │ │ │ ├── PricingController.php # محاسبه قیمت
│ │ │ │ ├── DiscountCodeController.php
│ │ │ │ ├── PaymentController.php # درگاه + Callback (با فلوی تأیید سفارش)
│ │ │ │ ├── MockGatewayController.php # شبیه‌سازی درگاه
│ │ │ │ ├── WalletController.php
│ │ │ │ ├── StaffOrderController.php # تأیید/رد سفارشات
│ │ │ │ ├── CustomerFinancialController.php # وضعیت مالی مشتری
│ │ │ │ ├── CommitmentFormController.php # تعهدنامه‌ها + آپلود امضاشده
│ │ │ │ ├── MobileVerificationController.php # تأیید موبایل (SMS)
│ │ │ │ └── Customer/
│ │ │ │ └── CustomerOrderController.php # سفارشات مشتری (packages/items/PDF/تعهدنامه)
│ │ │ ├── ShipmentPdfController.php # AWB/Invoice/Label/Import-Invoice PDFs
│ │ │ └── OrderController.php # فلوی legacy Blade (deprecated)
│ │ └── Middleware/
│ │ └── ApiKeyMiddleware.php # برای APIهای عمومی
│ ├── Models/ # ۲۲ مدل Eloquent
│ ├── Notifications/ # DB + SMS: ShipmentApprovedSms, ShipmentRejectedSms, PaymentSuccessSms, TrackingUpdatedSms, SmsChannel
│ ├── Observers/
│ │ └── ShipmentObserver.php # تریگر نوتیفیکیشن/SMS روی تغییر وضعیت
│ ├── Traits/
│ │ └── Auditable.php # لاگ خودکار تغییرات مدل‌ها
│ ├── Services/
│ │ ├── PriceCalculatorService.php # موتور قیمت‌گذاری
│ │ ├── WalletService.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/
│ ├── 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/ # ۴۰ migration
│ └── seeders/
│ ├── 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 (PARCEL)
│ │ ├── label.blade.php # لیبل A5 با بارکد
│ │ └── import-invoice.blade.php # فاکتور واردات (مطابق شیت ENG)
│ └── filament/pages/ # صفحات Filament
│
├── routes/
│ ├── api.php # ۵۰+ REST API endpoint
│ └── web.php # Web (PDF قدیمی، payment-result، دانلود template)
│
└── config/
├── ifnex.php # تنظیمات اختصاصی IFNEX
└── cors.php
```
---
## 🗃️ Models
| Model | جدول | توضیح | فاز |
|-------|------|--------|-----|
| Country | countries | ۲۳۳ کشور با ۴ زون + calling_code | ۰ |
| Shipment | shipments | مرسوله‌ها (مدل مرکزی) | ۰+۲+۳.۵ |
| ShipmentItem | shipment_items | اقلام گمرکی (Invoice) | ۰+۳.۵ |
| ShipmentPackage | shipment_packages | بسته‌های چندگانه (Multi-Package) | ۳.۵ |
| ShipmentCarrierMapping | shipment_carrier_mappings | نگاشت شرکت‌های حمل | ۰ |
| ShipmentTrackingEvent | shipment_tracking_events | رویدادهای ترکینگ | ۰+۲ |
| ShipmentStatusHistory | shipment_status_histories | تاریخچه تغییرات وضعیت | ۲ |
| ShippingRate | shipping_rates | تعرفه‌های حمل | ۰ |
| SystemSetting | system_settings | تنظیمات key-value | ۰ |
| Currency | currencies | ارزهای پشتیبانی (IRR, AED, USD, EUR, CNY) | ۲ |
| ExchangeRateHistory | exchange_rate_histories | تاریخچه نرخ ارز | ۲ |
| User | users | کاربران سیستم (admin + customer) | ۰ |
| Wallet | wallets | کیف پول کاربران | ۲ |
| WalletTransaction | wallet_transactions | تراکنش‌های کیف پول | ۲ |
| 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) | ۲ |
**جمع: ۲۲ مدل**
---
## 🎨 Filament Resources
### Resources اصلی
| Resource | توضیح | ویژگی‌ها |
|----------|--------|---------|
| 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 + بروزرسانی خودکار نرخ |
| UserResource | مدیریت کاربران | CRUD + Role + Wallet link |
| WalletResource | مدیریت کیف پول | View + Freeze/Unfreeze + Activity Log |
| WalletTransactionResource | تراکنش‌ها | View + فیلتر + گزارش |
| PaymentResource | پرداخت‌ها | View + بررسی وضعیت |
| DiscountCodeResource | کدهای تخفیف | CRUD + اعتبارسنجی |
| RoleResource | نقش‌ها | مدیریت Roles + Permissions |
| ShipmentItemResource | اقلام گمرکی | CRUD |
| ExchangeRateHistoryResource | تاریخچه نرخ ارز | View |
### RelationManagers (ثبت‌شده در ShipmentResource)
| RelationManager | توضیح |
|-----------------|-------|
| TrackingEventsRelationManager | رویدادهای ترکینگ با فیلد source |
| CarrierMappingsRelationManager | نگاشت شرکت‌های حمل |
### صفحات سفارشی
| صفحه | توضیح |
|-------|--------|
| IfnexSettingsPage | تنظیمات سیستم — نرخ درهم، VAT، حاشیه سود، کلید کاوه‌نگار و سوییچ‌های SMS |
| PriceTestPage | تست محاسبه قیمت با پارامترهای مختلف — ⚠️ با مقادیر type فعلی خراب است |
| ImportRatesPage | آپلود اکسل نرخ‌ها + دانلود Template |
| BulkTrackingImport | ایمپورت گروهی وضعیت ترکینگ با CSV |
| FinancialReport | گزارش مالی (درآمد، تخفیف، کارمزد) |
---
## 🔧 Artisan Commands
```bash
# Import / Migration
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-rates # بروزرسانی نرخ ارز (--source=ecb یا freecurrencyapi)
# Token
php artisan ifnex:token # تولید API Token برای ادمین
# Standard
php artisan migrate # اجرای migrations
php artisan db:seed # اجرای seeders
php artisan serve # اجرای سرور
php artisan tinker # محیط تعاملی
php artisan route:list # لیست روت‌ها
php artisan config:clear # پاک‌سازی کش کانفیگ
```
---
## 🔴 خط قرمزها (ممنوعیت‌ها)
| ❌ هرگز | ✅ همیشه |
|------------|------------|
| برگرداندن countries به ۲ زون | ۴ زون مجزا (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` |
---
## 🧪 تست
### Mock Gateway
برای تست پرداخت بدون اتصال به Zarinpal واقعی، `ZARINPAL_MERCHANT_ID=fake-merchant-id-for-testing` را در `.env` تنظیم کنید. سپس:
- پرداخت‌ها از طریق `MockZarinpalService` پردازش می‌شوند
- URL پرداخت: `/api/v1/payment/mock-gateway`
- شبیه‌سازی موفق: `/api/v1/payment/mock-gateway/success`
- شبیه‌سازی ناموفق: `/api/v1/payment/mock-gateway/failure`
### Bridge Token Test
```bash
curl -X POST http://localhost:8000/api/v1/bridge/login \
-H "Content-Type: application/json" \
-d '{
"bridge_api_key": "YOUR_BRIDGE_KEY",
"wp_user_id": 1,
"wp_user_email": "user@example.com",
"wp_user_name": "Test User",
"token_name": "test"
}'
```
---
## 📚 مستندات
| فایل | محتوا |
|------|-------|
| [IFNEX_Phase0_Checklist.md](../01_Documents/IFNEX_Phase0_Checklist.md) | چک‌لیست کامل فازها |
| [IFNEX_Roadmap.md](../01_Documents/IFNEX_Roadmap.md) | نقشه راه ۴ فازی |
| [IFNEX_File_Map.md](../01_Documents/IFNEX_File_Map.md) | نقشه ۱۰۰+ فایل |
| [DEPLOYMENT.md](../DEPLOYMENT.md) | راهنمای استقرار Production |
---
## 🚀 مراحل بعدی
- [ ] تست انتهای فلوی سفارش (تعهدنامه → تأیید → پرداخت)
- [ ] امنیت: چک نقش روی `/staff/*`، چک مالکیت PDF/تعهدنامه، rate limiting
- [ ] بازطراحی سیستم اعتبار (بدهی چندارزی) + رفع CustomerCreditResource
- [ ] چک‌لیست خودکار کارمند بعد از تأیید سفارش
- [ ] رفع PriceTestPage و ثبت شورت‌کد `[ifnex_wallet_charge]`
- [ ] مستندات API (OpenAPI/Swagger)
- [ ] اتصال به APIهای ترکینگ زنده (فاز ۵)
- [ ] سیستم نمایندگی (فاز ۴)
> وضعیت دقیق و جزئیات فاز ۳.۶: [AGENT.md](../AGENT.md) و [IFNEX_Roadmap.md](../01_Documents/IFNEX_Roadmap.md)
---
<div align="center">
&copy; 2026 VernaSoft Group. All Rights Reserved.
</div>
Reference in New Issue View Git Blame Copy Permalink